EvilEngine/Events: Difference between revisions

Content added Content deleted

Inline

Revision as of 19:58, 7 March 2019

An event can be thought of as a signal or message that can be sent to any object. Events are usually used to notify an object of something happening between that object and another object. For example, when the Player walks inside a Trigger, the EnterPlayer event is automatically sent to the trigger. Events are also used to notify objects of something important happening in the scene. For example, all entities receive the Scene Prepare event during xSceneInit(), which some entities use internally to know when to set themselves up. Events can also be sent directly from one object to another, which can be set up in the asset for an object by using links. Links are extremely powerful since they let you design all kinds of custom interactions between objects without having to edit code.

Links

A link is a property of an object that can be used to "link" that object to another object in a scene.

TODO

Format

Links are usually defined to be stored at the end of the main data struct of a base asset (usually a struct inheriting from xBaseAsset or xEntAsset). The format for a link stored in an asset is defined in the xLinkAsset struct, in xBase.h:

Offset	Type	Variable	Description
0x00	short	srcEvent	Source event enum
0x02	short	dstEvent	Destination event enum
0x04	AssetID	dstAssetID	ID of asset who will receive the destination event
0x08	float[4]	param	Parameters for destination event, these are usually all floats but for some events they are ints/Asset IDs.
0x18	AssetID	paramWidgetAssetID	Base asset ID parameter for destination event
0x1C	AssetID	chkAssetID	If this is non-null, the destination event is only sent if the source event was received from the asset with this specific ID.

List of Events

@@ Line 1: / Line 1: @@
+An '''event''' can be thought of as a signal or message that can be sent to any [[Object Asset|object]]. Events are usually used to notify an object of something happening between that object and another object. For example, when the [[PLYR|Player]] walks inside a [[TRIG|Trigger]], the ''EnterPlayer'' event is automatically sent to the trigger. Events are also used to notify objects of something important happening in the scene. For example, all [[Placeable Asset|entities]] receive the ''Scene Prepare'' event during <code>xSceneInit()</code>, which some entities use internally to know when to set themselves up. Events can also be sent directly from one object to another, which can be set up in the asset for an object by using '''links'''. Links are extremely powerful since they let you design all kinds of custom interactions between objects without having to edit code.
-==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==
+==Links==
+A '''link''' is a property of an [[Object Asset|object]] that can be used to "link" that object to another object in a scene.
-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.
+TODO
-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 [[TRIG|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.
+===Format===
-'''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:
+Links are usually defined to be stored at the end of the main data struct of a base asset (usually a struct inheriting from <code>xBaseAsset</code> or <code>xEntAsset</code>). The format for a link stored in an asset is defined in the <code>xLinkAsset</code> struct, in [https://github.com/pslehisl/BFBB-cpp/blob/master/Core/x/xBase.h xBase.h]:
+{| class="wikitable"
-    When I receive '''EnterPlayer''', send '''GiveShinyObjects''' to '''SPONGEBOB''' with an argument of '''5000'''.
+! Offset !! Type !! Variable !! Description
+|-
-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.
+| 0x00 || short || '''srcEvent''' || Source event enum
+|-
-Events can only be sent to or by [[Asset#Object Assets|Object Assets]], which include [[Asset#Placeable Assets|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.
+| 0x02 || short || '''dstEvent''' || Destination event enum
+|-
-==Format==
+| 0x04 || [[AssetID]] || '''dstAssetID''' || ID of asset who will receive the destination event
-Below is what an event handler looks like in an asset.
+|-
+| 0x08 || float[4] || '''param''' || Parameters for destination event, these are usually all floats but for some events they are ints/Asset IDs.
-    int16 eventReceiveID  // event ID received
+|-
-    int16 eventSendID     // event ID to send
+| 0x18 || [[AssetID]] || '''paramWidgetAssetID''' || [[Object Asset|Base asset ID]] parameter for destination event
-    int32 targetAssetID   // asset to send event to
+|-
-    number32[6] arguments // either int32 or float
+| 0x1C || [[AssetID]] || '''chkAssetID''' || If this is non-null, the destination event is only sent if the source event was received from the asset with this specific ID.
+|}
-'''Example 1 (cont.)''': Here's what your event handler would look like in the Clam TRIG:
-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:
-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.
 ==List of Events==