Modding:Events

Events are the basic building block that most of 's mechanics are built upon. When any object spawns, attacks, moves, dies and etcetera: an event is fired. This gives any number of registered listeners to that event a chance to react and execute their own code. You can read more about traditional application events in Microsoft's C# Programming Guide, the implementation is different but they fulfill the same function.

=Standard Events= Events are typically listened for in generic Parts or Effects, which is what implements more advanced functionality of an object. Mutations (Creation) and Skills are both Parts. Effects such as sleep, prone or poison are handled separately from Parts as they are usually temporary.

Listening
To listen for an event you typically override the Register method of the base IPart or Effect class. This is executed once when the IPart/Effect is added to the object and subsequently serialized. Overriding the AllowStaticRegistration method to return true alters this behaviour: registrations are no longer serialized and Register is re-executed every save load. It is however possible to register for an event anywhere as long as you have an instance of both an IPart/Effect and a GameObject.

Firing
To fire an event you call the FireEvent method on the relevant GameObject and pass it an Event with optional parameters. You can later extract these parameters when handling the event.

Handling
Once the event has been fired it will call the FireEvent method on all registered Parts and Effects, where you can handle it and execute your own code.

=Minimal Events= Minimal events are a new event system introduced with the update (V200). While the underlying implementation has changed drastically, the usage is familiar in that you still listen, fire and handle events.

Listening
To listen for a min event you override the WantEvent method of the base IPart or Effect class. This will be executed every time an event is fired so keep it lean. Unlike regular events, WantEvent is the only way to report you'd like to handle a min event. If you need to dynamically listen for another event it's recommended to do your dynamic logic elsewhere and flip a boolean variable for the WantEvent.

Firing
To fire a min event you call the HandleEvent method on the relevant GameObject and pass it a specific MinEvent. Setting parameters on a MinEvent is a lot more intuitive compared to the old system as they are now properties of their own type.

Handling
The handling of min events is the most drastic change from the old system, as you can now override one separate method for each type of MinEvent which is much simpler to organize.

Custom
Prior to patch 200.43 it was possible to simply overload the handling methods, where it was then retrieved & invoked through reflection based on the parameter type and cached in a dictionary. If you are creating your own custom MinEvent, there's nothing for you to override so you will still have to do this. To mark your custom MinEvent for invocation, override the WantInvokeDispatch method to return true.

Cascading
In some cases events should be handled by objects contained within your Part, such as items in the Inventory or equipped on your Body. This is what the CascadeLevel of the event dictates. The cascade level is a bit field which determines when and where the event should cascade depending on which bits are flipped.