Skip to content

Client and server requests

Use a request when the caller needs a result, such as a shop catalog or a list of available jobs. Register a handler with onRequest() and return the value that the caller should receive.

Direction Caller Handler
Client → server revo.fetchServer(name, ...args) Server: revo.onRequest(name, (player, ...args) => result)
Server → client revo.fetchClient(player, name, ...args) Client: revo.onRequest(name, (...args) => result)

The server registers a handler for the city’s dealership:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
/**
* @param {revo.Player} player
* @param {string} dealershipId
*/
function getCatalog(player, dealershipId) {
if (dealershipId !== 'city') {
throw new Error('Unknown dealership.');
}
return [
{ model: 'blista', price: 12000 },
{ model: 'sultan', price: 35000 },
];
}
revo.onRequest('dealership:catalog', getCatalog);

The client passes the dealership ID and waits for the returned catalog:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
try {
const catalog = await revo.fetchServer('dealership:catalog', 'city');
revo.log('Dealership catalog:', catalog);
} catch (error) {
revo.log('Could not load the dealership catalog:', error);
}

Arguments after the request name arrive in the same order. Server handlers also receive the sending Player as their first argument, supplied by the connection. Use that player when checking access to account or inventory data.

A handler can be async. Return its result after awaiting a database query or other work. The caller receives a Promise that resolves with that result. Returning undefined is also supported.

Requests are available after the connection handshake, before spawning. Register server handlers before accepting players. For asynchronous server initialization, see Server startup and shutdown.

For server-to-client requests, have the client send a readiness event after registering its handlers. Start requests from the server’s onClient() handler for that event. playerConnected can run while the client’s scripts are still loading.

Keep await fetchServer() or await fetchClient() inside try/catch. A handler that throws or returns a rejected Promise causes the caller’s Promise to reject with an Error containing its message. Use messages suitable for the receiving side.

Failure What to check
Remote request handler is not registered Check the name, target side and handler registration timing.
Remote request timed out The response was not received within 15 seconds. Check the handler’s work and connection delays.
Remote peer is not connected / Remote peer disconnected The target was unavailable when sending or disconnected while the request was pending.
Remote handler returned an unsupported value Return a supported value or convert class instances to plain data.
Too many pending remote requests Limit concurrent requests and wait for existing ones to finish.

Work already started by the handler can finish after the caller times out. For operations such as purchases, track an operation ID on the server while the operation is running and after it completes. A retry can then use the existing operation or its result.

After await, check player.valid or entity.valid before using an object that may have been destroyed while waiting.

Arguments and results support null, booleans, finite numbers, bigint, strings, Uint8Array, arrays and plain objects. For an entity reference, send its server id or client networkId, as covered in Entity identifiers. Send positions as plain { x, y, z } objects.

Each encoded request or response has a 256 KiB payload limit. Request names can use up to 128 UTF-8 bytes, with at most 64 arguments per call. Large collections can be requested in pages.

Keep the original function reference and call revo.offRequest('dealership:catalog', getCatalog) to remove the example’s handler. Only one handler can be registered per name on each side. Remove the existing handler before replacing it.

Removing a handler leaves already running requests to finish. For requests between a WebView and its client script, see WebView events and requests.

fetchServer() · fetchClient()