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) |
Request a catalog
Section titled “Request a catalog”The server registers a handler for the city’s dealership:
// @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:
// @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.
Register handlers before requesting
Section titled “Register handlers before requesting”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.
Errors and timeouts
Section titled “Errors and timeouts”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.
Values and limits
Section titled “Values and limits”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.
Remove a handler
Section titled “Remove a handler”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.