Skip to main content

Events

Quick Reference​

NameTypeDescription
SubscribeSharedSubscribe to an event with a callback function.
CallSharedCalls an event which will trigger all local subscribers.
CallRemoteSharedCalls an event which will trigger all subscribers on remote side.
CancelSharedCancel the current executed event.
WasLastCanceledSharedChecks if last completed event was canceled.
BroadcastRemoteServerCalls an event which will trigger all subscribers on client side for all players.
GetSourceServerGets 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 (object), and array.

The languages do not have the same containers, so a value may change shape when it crosses between resources written in different languages:

  • A Lua table whose keys are exactly 1..n arrives in JavaScript and Squirrel as an array; any other table arrives as an object with string keys.
  • A JavaScript or Squirrel array arrives in Lua as a table keyed 1..n; an object arrives as a table with string keys.
warning

Anything else (a function, a class instance, a userdata) is silently replaced with nil/null 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 whole number 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.

JavaScript

A handler may be an async function, but the game does not wait for it. Its return value and any Cancel only count if they happen before the first await.

Example:

Events.Subscribe("testEvent", function(testint, teststr)
    Console.Log("testEvent triggered: " .. testint .. ", " .. teststr)
end, 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:

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:

-- 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, playerDamage 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:

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:

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

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