EvilEngine/Events
Introduction
Events are used by assets as the main method of interacting with each other. Most of the asset types have the ability to send events to other assets to tell them to do something. It can be something as simple as checking a condition or starting a timer, *or* it can be an in-game action, such as warping to another level, playing a sound effect, showing a textbox, giving the player shiny objects, etc. This allows for actual level mechanics and complex logic to be created and built right inside a level, instead of having to manually add level-specific code to the game. Perfect for modding!
Structure
Assets can both send and receive events. Most of the time, assets will automatically "receive" an event when certain things happen, such as when the scene is prepared, when the player enters a trigger, or when the game evaluates a boolean condition -- useful for COND assets, which will send a True or False event after receiving an Evaluate event.
When an asset receives an event, it can react to it by sending a new event to either itself or another asset. For example, when the player enters a trigger, an EnterPlayer event is sent by the trigger asset. You can add, what I call, an event handler to the trigger to listen to the EnterPlayer event and react to it when it happens. Once it receives the event, you can make it send any event you want! You could, say, make it give the player 5,000 shiny objects if you want. You would do this by sending a GiveShinyObjects event to the SPONGEBOB PLYR asset.
Example 1: Say you have a Clam you don't feel like grinding for 10 minutes to afford, so every time the player enters its trigger you want to award them 5,000 shiny objects... because you're a cheater :) So you would add a new event handler to the Clam trigger asset. This is basically what your new event handler would say:
When I receive EnterPlayer, send GiveShinyObjects to SPONGEBOB with an argument of 5000.
I'll show you how that looks in hex later on. As you can see, you can include arguments when you send events. Arguments are used by the game when running whatever built-in code is defined for an event.
Events can only be sent to or by Object Assets, which include Placeable Assets. You can add up to 255 event handlers to an asset. You can also define more than one event handler for the same event ID. The game will run your event handlers in the order that you define them. The GRUP asset (which is an asset with the sole purpose of grouping other assets) has the special property of being an event forwarder: once it receives an event, it passes it on to every asset it includes.
Format
Below is what an event handler looks like in an asset.
int16 eventReceiveID // event ID received int16 eventSendID // event ID to send int32 targetAssetID // asset to send event to number32[6] arguments // either int32 or float
Example 1 (cont.): Here's what your event handler would look like in the Clam TRIG:
00 05 00 35 BD 70 97 E3 45 9C 40 00 00 00 00 00 ...
- When the EnterPlayer (0x0005) event is received,
- Send the GiveShinyObjects (0x0035) event...
- ...to whatever the SpongeBob PLYR asset ID is (0xBD7097E3 in this case)...
- with an argument of 5,000 (0x459C4000 as a float).
- Leave the other 5 arguments blank (0x00000000).
You can also use the GiveShinyObjects event to take away shiny objects from the player. That's actually what happens when you finally do pay the Clam! To do that, all you have to do is pass a negative number to the event. It's that simple.
Example 2: Say you want to take away 100 shiny objects when the player leaves the trigger. Here's what your event would look like:
00 06 00 35 BD 70 97 E3 C2 C8 00 00 00 00 00 00 ...
- Replace EnterPlayer with ExitPlayer (0x0006)
- Replace 5,000 with -100 (0xC2C80000)
If the stuff above confuses you, Industrial Park can edit all events for all object assets (even assets which it does not have an editor for yet!) using enumarations for event names.