Events

From Battlepedia
Jump to navigationJump to search

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