In-depth Events guide
As explained in the Introduction to VeniceEXT concepts guide, Events are a way for the engine to provide information to VeniceEXT scripts and for different scripts and mods to talk with each other. In this guide we'll go in a bit more detail on how events work and how to use them.
Every event is identified by a unique string name and can have some data associated with it. Event names are case sensitive. For example, the Player:Joining event carries with it the name of the player who's joining and other information like their account identifier and IP address. Events that the VeniceEXT engine sends are split into client, server, and shared categories meaning that some are only received by
client scripts, some only by
server scripts and others by both (
Subscribing to events
By subscribing to an event you state to the engine that you want to receive that event. That works by using the Events library, stating which event we're interested in, and giving it a handler function to call when said event gets sent.
Let's look at an example of the event we mentioned above:
Events:Subscribe('Player:Joining', function(name, playerGuid, ipAddress, accountGuid) print('Player "' .. name .. '" is joining!') end)
The code above is the functional equivalent of the code below, but using an inline function definition instead of a named function. Both are perfectly valid:
local function OnPlayerJoining(name, playerGuid, ipAddress, accountGuid) print('Player "' .. name .. '" is joining!') end Events:Subscribe('Player:Joining', OnPlayerJoining)
In these examples we use the Subscribe method of the Events library to say we want to receive the Player:Joining event (we should note that this event will only get sent to server-side scripts). When a player joins, the function we provided will get called and
Player "PlayerName" is joining! will be printed (but instead of
PlayerName it will be the real name of the player who is joining). This event also provides us with
accountGuid which we could also use.
Event user data
There is a version of the Subscribe method that allows us to pass some custom user data that will be provided to our event handler function alongside all of the event data as seen in the example below:
local x = 123 Events:Subscribe('Player:Joining', x, function(userData, name, playerGuid, ipAddress, accountGuid) print(userData) end)
What we're doing here is that we're passing the
x variable into the Subscribe method right before our handler function. The
x variable represents our user data in this case. When a player is joining and the handler function gets called,
x will be passed in as the first argument in the function (in this case
123 will get printed. You can pass in anything you want as user data making this especially useful for cases where you need to maintain some context relevant to the event you are receiving.
Stop receiving events
You may want to stop receiving specific events at some point. There are a few different ways to do that:
Using the Event object
local event = Events:Subscribe(...) -- Some time later. event:Unsubscribe()
After you call that method you will no longer receive that event and the handler function will never get called again until you subscribe to it again.
Unsubscribing by name
This will make it so no [Player:Joining] events are received by your mod until you explicitly subscribe to them again.
You can use the same Unsubscribe method without passing an event name in to stop receiving all subscribed to events:
Other than the events that are sent to our scripts by the engine, we can also send and receive our own custom events. Custom events can be sent between your own scripts but also between different mods. To send a custom event you just need to use the Dispatch method of the Events library as seen below:
Events:Dispatch('MyCustomEvent', 1, 2, 3)
And then receive that event like you would any other:
Events:Subscribe('MyCustomEvent', function(a, b, c) print(a) print(b) print(c) end)
In this example we're sending a custom event with the name
MyCustomEvent and the values
3 as its data. When that event gets received, the handler function will print
You can pass any amount of data you want, however there are some restrictions to the type of data you can use. More specifically, only the following types are allowed:
- Lua numbers
- Lua strings
- Lua booleans
- Vec2 objects
- Vec3 objects
- Vec4 objects
- LinearTransform objects
- Guid objects
- AxisAlignedBox objects
- QuatTransform objects
- Quat objects
- Lua tables with keys and values of any of the above types (or other tables)
When you use the Dispatch method you send an event to all of the currently loaded mods. This is useful for communicating information to them in response to functionality specific to your mod. However, this may not always be necessary. In those cases, you can use the DispatchLocal method which will send the event only to your own mod:
Events:DispatchLocal('MyCustomEvent', 1, 2, 3)
Even if other mods subscribe to the
MyCustomEvent event, they will not receive it when you send it.
Next, you can read a more in-depth guide on NetEvents and how to use them.