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.
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.
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
xEntAsset). The format for a link stored in an asset is defined in the
xLinkAsset struct, in xBase.h:
|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||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.|