LoL Java plugin API

All player interaction, camera motion, AI and in-level animation is handled by Java scripts.

Scripts are stored in the 'plugins' directory as '.java' files. You don't need to compile them - that is handled automatically by the game as it loads them.

Each plugin controls one basic object in the game and is derived from a base class called GameInterface which is declared in the 'javaLoL' directory as a set of external links to C++ code in the game kernel.

Each Java plugin needs to be named after the object it'll be connected to.

Hence, the model jeep has it's top level object named Jeep - which is automatically hooked up to the plugins/Jeep.java script. The Java code might look something like this:

 import java.io.* ;
 import java.lang.* ;
 import java.util.* ;
 import javaLoL.* ;
 ...
 public class Jeep extends GameInterface
 {
   ...
   public Jeep ()
   {
     ...
     wantEvent ( ... ) ;
     wantEvent ( ... ) ;
   }
   ...
 }

The base GameInterface class contains all the functions you'll need for moving and animating the object the script is attached to, sending and reacting to events, playing sound effects and so on. A complete (autogenerated) list of GameInterface API , Alphabetical Index .

A detailed worked example

Here is some sample code that allows you to drive the Jeep around using the 'W', 'A', 'S' and 'Z' keys. I'll include commentary as we work through the code:

Firstly, we need to include some standard Java libraries - and (most important) all of the 'javaLoL' code:

 import java.io.*   ;
 import java.lang.* ;
 import java.util.* ;
 import javaLoL.*   ;

Next we declare a class named 'Jeep' that's derived from the basic 'GameInterface' code with some handy variables:

 public class Jeep extends GameInterface
 {
   float speed ;
   float steer ;
   float h ;
   float p ;
   float r ;
   float x ;
   float y ;
   float z ;
   float z_velocity ;

The base class constructor is called when the model loads. You can't do much work here because not all models are loaded yet. However, we can set up the initial variables, position the Jeep model and (most importantly) set up some event handlers:

   public Jeep ()
   {
     speed = 0.0f ;
     steer = 0.0f ;
     h = 0.0f ;
     p = 0.0f ;
     r = 0.0f ;
     x = 0.0f ;
     y = -10.0f ;
     z = 0.0f ;
     z_velocity = 0.0f ;

     setXYZHPR ( x, y, z, h, p, r ) ;
     wantEvent ( getEventHandle ( "NextFrame" ), "my_update" ) ;
   }

That call to 'wantEvent' causes a function called 'my_update' to be called whenever the "NextFrame" event happens. Most real scripts will be interested in other events - and in general, one does not need to recieve events every single frame. From an efficiency perspective, keeping the number of "NextFrame" events to a minimum is a good idea.

Anyway - each frame the 'my_update' function is going to be called - so we'd better declare that function:

   public void my_update ()
   {

The duration of a single frame can vary throughout the game - and also from one computer to another. It's essential that these kinds of update event handlers pay careful attention to the amound of elapsed time.

     float t = getFrameTime () ;

So - are any keyboard keys being held down? If so, we need to increase or decrease the speed or steering angle in proportion to the amount of time that's just elapsed - clamping them to a reasonable range:

     if ( keyIsDown ( 'w' ) && speed <  26.0f ) speed += 26.0f * t ;
     if ( keyIsDown ( 'z' ) && speed >  -5.0f ) speed -= 26.0f * t ;
     if ( keyIsDown ( 'a' ) && steer <  30.0f ) steer += 60.0f * t ;
     if ( keyIsDown ( 's' ) && steer > -30.0f ) steer -= 60.0f * t ;

Update heading according to the rate of steering:

     h += steer * t ;

Multiplying speed and steering rates by 0.99 gradually slows everything down when you let go of the controls:

     steer *= 0.99f ;
     speed *= 0.99f ;

Add gravity into velocity in the Z direction:

     z_velocity += -9.8f * t ;

Update the position of everything:

     x += speed * t * Math.sin ( -h * 3.14159 / 180.0 ) ;
     y += speed * t * Math.cos ( -h * 3.14159 / 180.0 ) ;
     z += z_velocity * t ;

Find out how high the ground is under the Jeep:

     float newz = getGroundHeight () ;

If the Jeep is below ground level then kill it's downward velocity, prevent it from sinking underground and gradually match the pitch and roll to the slope of the terrain.

     if ( z <= newz )
     {
       z_velocity = 0.0f ;
       z = newz ;
       p += ( getGroundPitch  () - p ) * 0.1f ;
       r += ( getGroundRoll   () - r ) * 0.1f ;
     }

Now just position the Jeep where we decided it should be.

     setXYZHPR ( x, y, z, h, p, r ) ;
   }
 }

Wikiid Pages relating to gameTools ()

gameTools - Main page

gameTools - Support Tools : plb_to_ac3d, mklevel, mktile, mktree, tiled, autogen_java, mk3dgallery

gameTools - File Formats : title_screen.rgb, ultimate.xml, material.xml, decoration.xml, physics.xml tiled.xml, tiled_autotiles.xml, Level files, Tile naming scheme, PLB files

gameTools - Source Code : Game functions: gameCamera, gameClock, gameChecksum/gameHashTable, gameHTTP, gameIsect, gameJoystick, gameParticleManager, gameScreen/gameMouse, gameSky, gameStarter, gameStrokeFont, gameUtils Material database: MatList/MatEntry Tile map handling: TileObject/MapFlag/MapEntry/Map Java Interfacing: JavaLink Image file loading: liImage/liImageFactory 3D Model file loading: loadPLB, PLB exporter Physics: Sabot, Bullet, gameTools - Use with Blender, PLB exporter Object management: Object