Responding to events

Events allow for scripts to react to things happening in the game. For example, there are events for when character logs in, when it casts a spell, or when you receive a chat message. Scripts are generally event driven, which means that they are generally sitting idle until responding to an event.

Listening to events

By default your script will execute the code in its file, and then be done. If you want to continue to do things, you'll need to register for events. To register to an event, you'll need to define an event handler function, and register it to an exposed event. Lets subscribe to the Character.OnVitalChanged event as an example, and print out the vital information that changed. Viewing the API docs for Character.OnVitalChanged, you can see that the event arguments for that event are of type VitalChangedEventArgs. It exposes the vital type that changed, the oldValue, and the current value. When an event handler is called, it will usually be passed information specific to that event occurrence.

Open the HelloWorld script from Creating your first script and change the contents to the following:

-- define a handler function that we want called when our character vitals change
function handleVitalChanged(event_data)
    print("My", event_data.Type, "changed from", event_data.OldValue, "to", event_data.Value)
end

-- register our handler function to the character.onVitalChanged event
game.Character.OnVitalChanged.Add(handleVitalChanged)

The add method of an event allows us to subscribe our event handler to the event. After calling add, our handler will called every time that event is triggered.

[!TIP] If you only want to listen to an event once, and then immediately stop listening, you can use the once(myHandler) method on and event instead of add(myHandler).

Load the script and try jumping so that your character loses some stamina, and you should see something similar to the following:

[Script:HelloWorld] My Stamina changed from 493 to 496
[Script:HelloWorld] My Stamina changed from 496 to 499

Cleaning up registered event handlers

When your script stops, it will automatically clean up all subscribed events so that they are no longer called. It's always a good idea to clean up manually when you are done listening to an event though. Sometimes to achieve the desired functionality, you may also only want to only be conditionally listening to an event. Lets update the HelloWorld script to clean up after itself by unsubscribing to the Character.OnVitalChanged event when the script is unloaded. Update the contents of the HelloWorld script to the following:

-- define a handler function that we want called when our character vitals change
function handleVitalChanged(event_data)
    print("My", event_data.Type, "changed from", event_data.OldValue, "to", event_data.Value)
end

-- register our handler function to the character.onVitalChanged event
game.Character.OnVitalChanged.Add(handleVitalChanged)

-- register an inline handler to the onScriptEnd event. We use the .once() registration
-- method, which calls our handler once and then removes it from the event.
game.OnScriptEnd.Once(function()
  game.Character.OnVitalChanged.Remove(handleVitalChanged)
end)

This time we subscribed to a new event (Game.OnScriptEnd), and in it we called remove(handleVitalChanged) on the Character.OnVitalChanged event. This unsubscribes our handler from being called when the event is fired in the future.

[!TIP] The Game.OnScriptEnd is an event that gets fired just before your script shuts down. This allows you to unsubscribe from events, save an changes you need, etc.

Running this script again should yield no changes, although now it follows best practices for unsubscribing from events when the script shuts down.