Unification - Java Plugins

All objects in Unification are controlled by Java plugins stored in the 'plugins' directory.

The interface to the game is built into 'class GameInterface' and all plugins are required to derive from that class. The name of your class must match the name of the file it's stored in - so an object called 'Elephant' must be stored in a file called 'plugins/Elephant.java'. In outline, the file should look like this:

 import java.io.* ;
 import java.lang.* ;
 import java.util.* ;
 import javaUni.* ;
 public class Elephant extends GameInterface
 {
   ...
   public Elephant ()
   {
     ...
   }
 }

The 'javaUni' import contains the definitions of 'GameInterface'.

See also Game Interface.

In the Constructor function:

Plugins are expected to initialise themselves in their constructor function - which then returns.

There are several things that most constructors will need to do:

1. Typically, objects that react directly to user input call a function within the class: 'void help()' that prints out what controls the object reacts to. Eventually, we'll want to collect those outputs into a buffer somewhere and pop them onto the screen when the user asks for help. Typically, only the main character and the camera react to user input - but there are other possibilities.
2. The plugin needs to find the 'handles' of models that it's going to directly control.
3. Any interesting 'events' need to be registered with 'callback' functions.

Object Handles

Objects in the game world are connected to Java plugins via integer "handles". One of those objects is special - it is the object that was invoked with this script. There are two functions that enable you to find the handle of an object:

 int GameInterface::getMyObjectHandle() ;  // Returns the handle of the object the plugin was attached to.
 int GameInterface::getObjectHandle ( String objectName ) ;

Hence, if the character was just a simple object. the initialisation code would probably say:

 import java.io.* ;
 import java.lang.* ;
 import java.util.* ;
 import javaUni.* ;
 public class Elephant extends GameInterface
 {
   int myHandle ;
   public Elephant ()
   {
     myHandle = getMyObjectHandle () ;
     ...
   }
 }

But if the elephant wears a clown hat, then you might say:

 import java.io.* ;
 import java.lang.* ;
 import java.util.* ;
 import javaUni.* ;
 public class Elephant extends GameInterface
 {
   int myHandle ;
   int clownHatHandle
   public Elephant ()
   {
     myHandle = getMyObjectHandle () ;
     clownHatHandle = getObjectHandle ( "clownhat" ) ;
     ...
   }
 }

It's occasionally the case that you want to have a clown hat in some levels and not in others. The script can ask whether an object exists before attempting to get its handle:

     if ( objectExists ( "clownhat" ) )
       clownHatHandle = getObjectHandle ( "clownhat" ) ;
     else
       clownHatHandle = 0 ;   // Clown hat doesn't exist in this level of the game.

(The game engine guarantees that there is never an object with a handle of zero).

For each Java plugin, there is the concept of "the current object". Most of the calls within the GameInterface object work on the current object. Hence:

     makeCurrentObject ( myHandle ) ;
       setMass ( 1234.0f ) ;
       setXYZ ( 0, 100, 0 ) ;
       ...
     makeCurrentObject ( clownHatHandle ) ;
       setMass ( 1.0f ) ;
       setBouyancy ( 0.5f ) ;

...says that the elephant himself (myHandle) has a mass of 1234 kg and is positioned at (0,100,0), while the clown hat has a mass of just 1 kg and is mildly bouyant in water.

Events

See also Unification Event handling

"Registering an event" causes the game engine to call a specified function (a "callback function") within your class whenever the event happens. Events are things like a key or a mouse button or a joystick button being pushed or released. However, objects in the world can cause events to happen that other objects in the world might choose to react to.

To register an event, we find it's handle and call 'wantEvent':

      int  GameInterface::getEventHandle ( String eventName ) ;
      void GameInterface::wantEvent ( int eventHandle, String callbackFunctionName ) ;

In typical use, you use them like this:

      wantEvent ( getEventHandle ( "NextFrame" ), "myUpdate" ) ;

...this causes the 'NextFrame' event to call your function 'myUpdate' every frame from then on.

    public void myUpdate ()
    {
      ...do your stuff!...
    }

For example, if your main character has a 'spin attack' that's started by pressing the 'A' button on the joystick then the plugin for that character will have registered the joystick button event and when that function is called, it'll broadcast a "I am spinning" event to every other object within range of the attack. Those objects that represent enemy characters that are vulnerable to spin attacks will have registered the "I am spinning" event. So when the player pressed the 'A' button, that event tells the main character to spin - and the fact of him spinning causes functions to be called in the plugins of whatever objects are the victims of the spin attack. What they choose to do when that happens is up to them...perhaps they trigger a particle system and then die. Perhaps they just get knocked backwards. Perhaps they simply ignore the event.

Another common event is:

      wantEvent ( getEventHandle ( "Keystroke" ), "keyboardHit" ) ;

...which would call:

    public void keyboardHit ( int keystroke )
    {
      if ( keystroke == 's' )
      {
        ...start a spin attack...
      }
      else
        ...
    }

The keystroke is passed to the event callback function as an integer because the many special keys on a PC keyboard are passed as numbers outside of the 0..255 range of ASCII characters.

Unification Event handling contains a complete list of built-in events.