CJN EventProcessor Guide

Carl Nagle: Feb 09, 2010

This guide is intended to be an introduction for Java developers wishing to take advantage of the EventProcessor mod for the DimensioneX game engine.  This mod allows DimensioneX game developers familiar with Java to express their game command and event processing in Java code in addition to--or instead of--the SmallBasic code normally processed by the standard DimensioneX game engine.

The EventProcessor mod is a significant modification or "fork" of the standard DimX game engine.  However, the mod is intended to be fully compatible with games developed for the standard game engine.  At some point in the future, this modification may be merged into the standard DimX game engine.  At this time, every effort is being made to keep this mod in-sync with any changes made to the standard DimX engine.

Java developers wishing to take advantage of this mod must setup their Java development environment per the DimensioneX documentation for Editing Sources with NetBeans.  Primarily, this is so that you can develop and test your custom processors.  Once the developer overwrites the standard DimX game engine with the EventProcessor "forked" engine there are no additional game engine edits necessary to accomodate your game.  The game engine is NOT modified or customized to work with any one specific game.  The savvy Java developer more familiar with Eclipse may also choose to develop in that environment, instead.

The Java developer overwrites the standard DimX classes and\or source with the modified engine downloadable below.  These downloads include the source and compiled classes for the CSI Demo--which should be used for compiling and reference purposes:

Engine + CSI Compiled Classes
Engine + CSI Java Sourcecode

It is also highly recommended to review the CSI Demo dimx_system files to see how the sample game is put together in DXW\DXL and largely comprised of Java classes implementing CSI-specific event processing instead of SmallBasic scripting.  You can download this dimx_system content from:

CSI Sample System files

Settings for the WORLD DXW

The Java developer should constantly refer to the Available JavaDoc.

Note the information on the IEventProcessor Interface provided by the game engine.

In our game's DXW "WORLD" definition section we specify an optional CUSTEVENTPROC classname.  This Java class MUST implement the IEventProcessor Interface and have a default constructor in order to be used successfully.  In the CSI.DXW you will see the one shown below:

CSI.dxw contains:

Notice our custom DefautlCSIEventProcessor ultimately subclasses the game engine convenience class of CustEventProcessor.

Processing Events

The custom event processors are required to only deal with 3 event method hooks:

You can review a game's console log to see how and when the different events might be fired and what the parameter values will be when called.  You can also review the CSIEventProcessor sourcecode to see that methods "execute" and "fireEvent_t" are not typically used for very much. It is the method "fireEvent" that ends up being the most commonly useful.

You can use multiple IEventProcessors

In addition to the DefaultCSIEventProcessor specified in the CSI.dxw, you should note via the JavaDoc for the CSI classes there are additional CSIEventProcessor subclasses present for the CSI demo:

While the IEventProcessor hook provided by the engine only allows one EventProcessor to be assigned for the World, that does not prevent our one EventProcessor from using any number of custom processors.  In the custom CSI EventProcessor we actually interrogate action OWNER variables checking for one that specifies a custom EventProcessor for that object.  If the variable exists, we instantiate and use the classname it holds. Othewise, we use the DefaultCSIEventProcessor for those characters, players, rooms, or items that don't have a custom processor.  This allows us to put event-handling code for a single item or object in one easy to manage class.

I strongly recommend Java developers wishing to see how this works review the custom processor sourcecode for the CSI demo.  Still, the CSI sample is just one example of how the IEventProcessor hook into the game engine might be used.