Unification Event handling
'Events are sent to Java plugins that desire some form of continual or intermittant updates. Events are generated either by the core game code ("built-in events") or by other plugins ("Java triggered events").
Built-in Events
These events are generated by the core game package and any plugin may use 'wantEvent' to cause one of their methods to be called when the event happens.
- FirstFrame
- This event happens once and once only - on the very first frame of the actual game. Prior to that time, some models, and other plugins may not yet be loaded so it is illegal to do things like collision detection before the FirstFrame event has happened. Hence it is common to do at least some model initialisation in the FirstFrame event rather than in the plugins' constructor function.
- NextFrame
- This event happens at the start of every single frame.
- KeyClick
- This event occurs every time a key on the keyboard is pushed down. The event handler (as named in 'wantEvent') must take a single int parameter - which is the ASCII key that was struck.
- KeyRelease
- This event occurs every time a key on the keyboard is released. The event handler (as named in 'wantEvent') must take a single char parameter - which is the ASCII key that was released.
- MouseClick
- This event occurs every time a mouse-button is clicked down. The event handler (as named in 'wantEvent') must take a single char parameter which is either the letter 'L', 'M' or 'R' depending on whether it was the left, middle or right button of the mouse that was clicked.
- MouseRelease
- This event occurs every time a mouse-button is released. The event handler (as named in 'wantEvent') must take a single char parameter which is either the letter 'L', 'M' or 'R' depending on whether it was the left, middle or right button of the mouse that was released.
- JoystickClick0/JoystickRelease0
- JoystickClick1/JoystickRelease1
- These events occur whenever a button is pressed (or released) on the specified joystick. The event handler (as named in 'wantEvent') must take a single char parameter - which is 'A' for the first button, 'B' for the second and so forth. The actual labelling of buttons on the physical joystick does not always match this scheme - so pressing or releasing the button labelled 'A' may or may not send an 'A' to the event handler. There is a wide variety of joystick labelling schemes which makes the selection of which button does which thing a tricky matter. Trial and error is recommended!
The keyboard, the mouse position and buttons and the joystick position and buttons can also be read directly in any event handler.
Java triggered events
These events are created inside one Java plugin and will be recieved by every other Java plugin that corresponds to a model that meets the criteria set in the event call. It is possible to send events to all other plugins, to only those within a certain range, or to those that fall within a certain angle of the front of this model.
As far as recieving those events, there is no difference between a Java event and a built-in event.
