Events and listeners
Choose the event API
Section titled “Choose the event API”| 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.
Register and remove listeners
Section titled “Register and remove listeners”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');// @ts-check/// <reference types="@revomp/types-server" />import * as revo from 'revo-server';
revo.onClient('notices:ready', (player) => { revo.emitClient(player, 'server:notice', 'Welcome to the server.');});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.
Local dispatch and asynchronous handlers
Section titled “Local dispatch and asynchronous handlers”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 delivery
Section titled “Network delivery”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.