Modding:Events

Before reading this article, make sure you read through the guidelines for modding.

Events are Lua signals for when something occurs in the game.

## Example

**When a building is sold, the "BuildingSellEvent" is *fired*, and any code registered to the "BuildingSellEvent" executes.**

Since we are considering all buildings, we will observe `lua/buildings/building_base.lua`. Note that event registration occurs in the `building_base:init()` function, which calls `self:OnInit()`. The `OnInit()` function is called after the basic instance is set up and is a proper place to register event handlers, the `__init()` function will not work.

```
--Step 1: Registration
self:RegisterHandler( self.entity, "BuildingSellEvent", "\_OnSell" )

--Step 2: Wait for BuildingSellEvent to be fired by Riftbreaker engine

--Step 3: Process Signal
function building\_base:\_OnSell( evt )
    --This function executes! You could add extra code here if you wish.
end

```

## Implementation Descriptions

```
void LuaEntityObject:RegisterHandler( object, event_name, callback )

```

> `object  : [definition needed] (self.entity and event_sink are common)`
>
>

> `event_name  : the event to wait for`
>
>

> `callback  : a method belonging to self that we want to call when the event is fired`
>
>

```
void LuaEntityObject:UnregisterHandler( object, event_name, callback )

```

> `object  : [definition needed]`
>
>

> `event_name  : the event to unregister from`
>
>

> `callback  : a method belonging to self that we want to unregister`
>
>

## Limitations and Custom Events

The Riftbreaker back-end fires most of the events. If you registered a Harvester Drone with "BuildingSellEvent", your method would never be executed because the backend has no sell interaction with drones, and thus the "BuildingSellEvent" event would not be fired for the drone.

There may be a way to create custom events. Figuring that out.. is underway. Here's what some process of understanding so far. Perhaps you can finish it if you're willing:

1. Create the Event name in a .Logic file (search "CultivationEnded" in logic/objectives/harvest\_plant.logic)
	1. No idea how they link harvest\_plant.logic to the cultivated\_plant.lua
2. Register the event for detection using Registerhandler (search "CultivationEnded" in lua/props/special/cultivated\_plant.lua)
3. Fire the event using QueueEvent (search "CultivationEnded" in lua/units/air/planter\_drone)

## Usage Search (Windows)

You can find the occurrences of any keywords, including these events:

1. Unzip an original XX\_win\_data.zip file
2. Open PowerShell in the unzipped folder (Hold shift + Right click -> Windows PowerShell)
3. Search for the event's name in all .lua files (`findstr /S /C:"ActivateBuildingEvent" *.lua`)

## Events

The events are sorted by broad category, though there may be overlap.

Buildings
 SpecialBuildingActionRequest

Combat
 TurretEvent

Drones
 EnableDroneRequest

Effects/Animations
 AttachEffectGroupRequest

Entity
 ShieldEntityCreatedEvent

Mission
 PortalOpeningFinishedEvent

Misc
 ComponentRemovedEvent

Mob-Specific
 StartLeechEvent

Resource
 ResourceMissingEvent

Streaming
 GameStreamingCreateVoteRequest

Weather/Time
 SunsetStartedEvent

## evt methodes in callback function

Not every methode may be available in every callback!