Using Event Hooks

Preface

The event hook library allows plugins to insert themselves into the games logic so that they may alter the way events in the game act.
Example projects for event hooks can be found Here.

Creating a hook

To create an event hook SiscosHooks.register(this, HOOK_ID, callback);

How it works

When you register for an event you are giving the library a registrar, event id, and callback.
A registrar is an object to tag the event under, each registered event is put into a list of other registered events for a registrar.
This is so later you can call SiscosHooks.unregister_all(my_registrar); and clear up all of the events you registered.
Usually a plugin will want to pass this for the registrar.

Every event fires the same kind of callback

An event callback function is defined as such: private Sisco_Return my_callback(ref object sender, ref object[] args, ref object return_value)
Each argument a callback receives is a reference type, so any changes made to an argument in a callback will also alter the value of the argument for any callbacks that fire after it. Keep this in mind!
Let's go over the different arguments each callback will receive.

Sender
Unless the function firing the event is static it will pass this as the sender. That is, sender is an instance of whatever class or object the function is a part of.

Args
The args array contains a list of all arguments that were passed to the function that is firing the event.

Return_value
The return_value argument is a little complicated.
If the hooked event is a POST event, such as Player_ApplyUpgrade or CellDirector_Post_Update then you can just assign return_value a value return from the callback and the hooked game function will return the value that was set. But keep in mind that other plugins which hooked the same event after yours did could alter your change to the return_value.
To prevent your changes to the return_value from being further altered you can set early_return = true in the Sisco_Return object you return from your callback.
Now if the hooked event is NOT a POST event you MUST set early_return = true for your Sisco_Return or your return_value change will have no effect.
This is because there is no way for the hooked function to look at the return_value and know if it should continue doing its normal game logic or abort and immediately return the value.
Whereas a POST hook is already at the end of the function, after POST hooks are called the next instruction is return return_value;.

Event callbacks receive two arguments

• The first, sender, is a reference to the calling functions class instance. So it could be an instance of PlayerState or any other class within SlimeRancher.
• The second argument is a reference to all of the arguments the calling function received, but in object form.
  Modifying any of the objects in this list will change the event's arguments to match.

Because they are in object form it is important to know what types of arguments the event function received.
You can find a list of events and the arguments they recieve HERE.

Returning values from an event callback

Please note that if you are just wanting to modify an events argument values then you don't need to return anything but null from your callback. The callback return values serve a different purpose.
All of your functions that get fired by events return an instance of Sisco_Return OR Null.
Returning Null lets the system know you want nothing to change.
Here are the values within Sisco_Return.

bool early_return
If TRUE then the calling function, eg: weapon.update(), will return early without performing the rest of it's logic, and in addition no other event handlers registered for said event will be called this time.

bool handled
should we stop calling other event handlers in the list? (Like saying ok my think did a thing and I don't want any other plugin to cancel it out so stop going through the list and firing everyone else's callback for this event now.)