Skip to content

Events and listeners

Scope Send Listen
Local, within the server or one client revo.emit(name, ...args) revo.on(name, handler)
Client → server revo.emitServer(name, ...args) revo.onClient(name, handler)
Server → client revo.emitClient(player, name, ...args) revo.onServer(name, handler)

Built-in events such as playerConnected on the server and keyDown on the client also use revo.on().

Local and network listeners have separate registrations. A message sent with emitServer('playerConnected') reaches listeners registered through onClient('playerConnected'). The built-in event uses on('playerConnected').

For client-to-server messages, the first argument is the sending Player, supplied by the connection. Validate the remaining arguments and check that this player is allowed to perform the requested action.

The first-mod example shows a complete exchange in both directions. WebViews use their own event bridge.

The client registers its listener, then signals that it is ready to receive notices. The server responds with a welcome message:

// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
/** @param {string} message */
function logNotice(message) {
revo.log(`[Server] ${message}`);
}
revo.onServer('server:notice', logNotice);
revo.emitServer('notices:ready');

To stop listening, call revo.offServer('server:notice', logNotice) with the same function reference. Use the matching removal method for each API:

Registration Removal
on(name, handler) off(name, handler)
onClient(name, handler) offClient(name, handler)
onServer(name, handler) offServer(name, handler)

An event can have several listeners. Registering the same function twice adds two callbacks. The matching off method removes all registrations of that function for the given name.

Register a feature’s listeners when it starts and remove them when it stops. Keep the original function, including the result of .bind() when using a bound method.

Listener changes made during dispatch affect subsequent dispatches. A callback already selected for the current event can still run after being removed.

A local emit() calls its listeners immediately, in registration order. Arguments are passed directly, so listeners receiving an object share that object with the caller.

Custom event listeners can be async. After a listener reaches await, the remaining listeners and later events can run while its work is pending. Receive order therefore does not determine the order in which asynchronous work finishes. Catch expected failures inside asynchronous handlers.

Custom events discard handler return values. Use requests when the sender needs a result from the other side. The built-in serverStop event has a separate shutdown waiting policy.

Network events use reliable delivery while connected. Register receiving handlers before sending messages to them. During startup, the client can send a readiness event after installing its handlers. See Handler readiness for the connection timing.

Event arguments use the same supported values and payload limits as requests. emitServer() and emitClient() can throw if arguments are invalid, the peer is disconnected or sending fails.

A received event with no listener is discarded. For state that players need after joining or returning to an area, use synced metadata or request a current snapshot from the server.

Client events · Server events