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, the game will automatically send assets events 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 allow you to decide what to do whether the game sends you a True or False 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, the game sends an EnterPlayer event to 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 only used by the game when running whatever built-in code is defined for an event. For example, if you send GiveShinyObjects with an argument of 5000 to SPONGEBOB, the game will automatically give the player 5,000 shiny objects. You don't need to set up another event handler for SPONGEBOB to do that. (You can't add event handlers to PLYR assets for some reason anyway...)

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.

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 ...


 * 1) When the EnterPlayer (0x0005) event is received,
 * 2) Send the GiveShinyObjects (0x0035) event...
 * 3) ...to whatever the SpongeBob PLYR asset ID is (0xBD7097E3 in this case)...
 * 4) with an argument of 5,000 (0x459C4000 as a float).
 * 5) 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)

TODO: Add a video showing the result

Event Descriptions
See List of Events for a list of descriptions for all of the events in the game.