EvilEngine/Events: Difference between revisions

Content added Content deleted

Inline

Latest revision as of 10:54, 2 November 2022

An event is a signal, message, or instruction 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 in the game without having to edit code.

Links

A link is an extra bit of metadata that can be added to any object. Up to 255 links can defined on an object.

Links are mainly used to connect the functionality of one object in a scene to another. A link acts as a "receiver" for a specific type of event that can be sent to the object, and in response to receiving the event, it "sends" a new event to another object in the scene or the object that it belongs to, along with up to 5 parameters. For example, you can define a link on a Trigger object that receives the EnterPlayer event, and sends the GiveShinyObjects event to the Player object in response, with the 1st parameter set to 100 (the amount of shiny objects). That object will also activate any links that receive the event you sent, so to continue the example, if you want to you can also define a link on the Player which receives GiveShinyObjects and sends Increment to a Counter. When you play the scene, every time you walk into the Trigger, EnterPlayer will be sent to it, which causes GiveShinyObjects to be sent to the Player, which causes Increment to be sent to the Counter.

Links can also send events to the same object it belongs to, so you can, for example, define a link on a Trigger that sends Disable to itself when it receives ExitPlayer. Some types of objects do this automatically, such as Counters. When a Counter receives Increment or Decrement and its new value is 0, it automatically sends Expired to itself.

Format

Links are stored in a contiguous array, usually at the end of the main data struct of an object 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 (receive) event ID (see the list of events for your game to find the correct event ID)
0x02	short	dstEvent	Destination (send) event ID (see the list of events for your game to find the correct event ID)
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	Object 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''' is a signal, message, or instruction 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.
-==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!
+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 in the game without having to edit code.
-==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.
+==Links==
-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.
+A '''link''' is an extra bit of metadata that can be added to any [[Object Asset|object]]. Up to 255 links can defined on an object.
+Links are mainly used to connect the functionality of one object in a scene to another. A link acts as a "receiver" for a specific type of event that can be sent to the object, and in response to receiving the event, it "sends" a new event to another object in the scene or the object that it belongs to, along with up to 5 parameters. For example, you can define a link on a [[TRIG|Trigger]] object that receives the ''EnterPlayer'' event, and sends the ''GiveShinyObjects'' event to the [[PLYR|Player]] object in response, with the 1st parameter set to 100 (the amount of shiny objects). That object will also activate any links that receive the event you sent, so to continue the example, if you want to you can also define a link on the Player which receives ''GiveShinyObjects'' and sends ''Increment'' to a [[CNTR|Counter]]. When you play the scene, every time you walk into the Trigger, ''EnterPlayer'' will be sent to it, which causes ''GiveShinyObjects'' to be sent to the Player, which causes ''Increment'' to be sent to the Counter.
-'''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 can also send events to the same object it belongs to, so you can, for example, define a link on a Trigger that sends ''Disable'' to itself when it receives ''ExitPlayer''. Some types of objects do this automatically, such as Counters. When a Counter receives ''Increment'' or ''Decrement'' and its new value is 0, it automatically sends ''Expired'' to itself.
-    When I receive '''EnterPlayer''', send '''GiveShinyObjects''' to '''SPONGEBOB''' with an argument of '''5000'''.
+===Format===
-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.
+Links are stored in a contiguous array, usually at the end of the main data struct of an [[Object Asset|object 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/bfbbdecomp/bfbb/blob/master/src/Core/x/xBase.h xBase.h]:
+{| class="wikitable"
-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.
+! Offset !! Type !! Variable !! Description
+|-
-==Format==
+| 0x00 || short || '''srcEvent''' || Source (receive) event ID (see the [[#List of Events|list of events]] for your game to find the correct event ID)
-Below is what an event handler looks like in an asset.
+|-
+| 0x02 || short || '''dstEvent''' || Destination (send) event ID (see the [[#List of Events|list of events]] for your game to find the correct event ID)
-    int16 eventReceiveID  // event ID received
+|-
-    int16 eventSendID     // event ID to send
+| 0x04 || [[AssetID]] || '''dstAssetID''' || ID of asset who will receive the destination event
-    int32 targetAssetID   // asset to send event to
+|-
-    number32[6] arguments // either int32 or float
+| 0x08 || float[4] || '''param''' || Parameters for destination event, these are usually all floats but for some events they are ints/Asset IDs.
+|-
-'''Example 1 (cont.)''': Here's what your event handler would look like in the Clam TRIG:
+| 0x18 || [[AssetID]] || '''paramWidgetAssetID''' || [[Object Asset|Object asset ID]] parameter for destination event
+|-
-05 00 35 BD 70 97 E3 45 9C 40 00 00 00 00 00 ...
+| 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.
+|}
-# 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==
-* [[List of Events|Battle for Bikini Bottom]]
+* [[List of Events/Scooby|Scooby-Doo: Night Of 100 Frights]]
+* [[List of Events/BFBB|Battle for Bikini Bottom]]
 * [[List of Events/TSSM|The SpongeBob SquarePants Movie]]
+* [[List of Events/Incredibles|The Incredibles]]
+* [[List of Events/ROTU|The Incredibles: Rise of the Underminer]]
+* [[List of Events/RatProto|Ratatouille Prototype]]
-[[Category:Modding]]
+[[Category:EvilEngine]] [[Category:EvilEngine Events]]