Events

Quick Reference

Name	Type	Description
Subscribe	Shared	Subscribe to an event with a callback function.
Call	Shared	Calls an event which will trigger all local subscribers.
CallRemote	Shared	Calls an event which will trigger all subscribers on remote side.
Cancel	Shared	Cancel the current executed event.
WasLastCanceled	Shared	Checks if last completed event was canceled.
BroadcastRemote	Server	Calls an event which will trigger all subscribers on client side for all players.
GetSource	Server	Gets the server ID of the player from which the last event was triggered.

---

Event Arguments

Event arguments are copied, not shared. Values are converted on the way out and rebuilt on the other side, and only these types survive:

nil, bool, int, float, string, table, and array (Squirrel only).

warning

Anything else (a function, a class instance, a userdata) is silently replaced with nil and only logged as a warning. You cannot pass a callback through an event; pass an identifier and look the callback up on the other side.

caution

Numbers are narrowed. A Lua integer becomes a 32-bit int, anything fractional becomes a single-precision float. Large IDs and values that need full precision should be sent as strings.

info

Nesting is limited to 32 levels. A value nested deeper arrives as nil.

---

Shared Functions

Subscribe

Subscribe to an event with a callback function.

Events.Subscribe(string name, function callbackFunc, [optional] bool isRemoteAllowed)

warning

isRemoteAllowed defaults to false. A handler that was not opted in is skipped when the event arrives from the other side. CallRemote and BroadcastRemote then appear to do nothing, and the only trace is a warning in the log. Set it to true for every handler that is meant to be reachable remotely, and only for those: a client can call any remote-enabled server event with any arguments it likes.

info

Subscribing the same event name more than once is allowed. All handlers run, in the order they were subscribed.

Example:

Lua

Events.Subscribe("testEvent", function(testint, teststr)
    Console.Log("testEvent triggered: " .. testint .. ", " .. teststr)
end, false)

Squirrel

Events.Subscribe("testEvent", function(testint, teststr) {
    Console.Log("testEvent triggered: " + testint + ", " + teststr);
}, false);

---

Call

Calls an event which will immediately trigger all local subscribers.

bool success = Events.Call(string name, [optional] list arguments)

warning

With this function, you can only call events on the same side. Client -> Client or Server -> Server

info

The return value will be false if the event was canceled.

Example:

Lua

Events.Call("testEvent", { 2, "meow" })

Squirrel

Events.Call("testEvent", [ 2, "meow" ]);

---

CallRemote

Calls an event which will trigger all subscribers on remote side.

Events.CallRemote(string name, [server only] int serverID, [optional] list arguments)

warning

With this function, you can only call events on the remote side. Client -> Server or Server -> Client

Example:

Lua

-- in client script:
Events.CallRemote("serverEvent", { 1, true })

-- in server script:
Events.CallRemote("clientEvent", playerid, { 1, true })

Squirrel

// in client script:
Events.CallRemote("serverEvent", [ 1, true ]);

// in server script:
Events.CallRemote("clientEvent", playerid, [ 1, true ]);

---

Cancel

Cancel the current executed event.

Events.Cancel()

warning

This function does not stop further event handlers from being called.

note

The use of this function outside of an event callback has no effect.

info

Only a few built-in events actually act on a cancel, because only they wait for their handlers to finish before continuing: chatSubmit, sessionFail and resourceStop. Every other built-in event is queued and already done deciding by the time your handler runs, so cancelling it changes nothing.

For your own events, Call returns false when a handler cancelled, which is how you act on it.

---

WasLastCanceled

Checks if last completed event was canceled.

bool canceled = Events.WasLastCanceled()

---

Server Functions

BroadcastRemote

Calls an event which will trigger all subscribers on client side for all players.

Events.BroadcastRemote(string name, [optional] list arguments)

Example:

Lua

Events.BroadcastRemote("clientEvent", { 1, "meow" })

Squirrel

Events.BroadcastRemote("clientEvent", [ 1, "meow" ]);

---

GetSource

Gets the server ID of the player from which the last event was triggered.

int serverID = Events.GetSource()

warning

The function may only be used in server events called from the client side.

Example:

Lua

Events.Subscribe("testEvent", function()
    local source = Events.GetSource()

    Console.Log("testEvent was called from " .. Player.GetName(source))
end, true)

Squirrel

Events.Subscribe("testEvent", function() {
    local source = Events.GetSource();

    Console.Log("testEvent was called from " + Player.GetName(source));
}, true);