Metadata
Metadata attaches custom values to Revo objects, such as a player’s job or a vehicle’s fuel level.
| Store | Written by | Available to |
|---|---|---|
| Local metadata | Server or client scripts | The same side that stored it. Each client has its own local data. |
| Synced metadata | Server scripts | The server and clients receiving the object. |
Local metadata
Section titled “Local metadata”Use setMeta(key, value) to store a value, or setMeta(values) to set several
keys. Read them with getMeta(key), check for a key with hasMeta(key), and list
the keys with getMetaKeys(). Remove a value with deleteMeta(key).
A server write stays on the server. A client write stays on that client. For example, a client can keep UI state associated with a vehicle, while the server keeps its own data for that vehicle. Local and synced metadata are separate stores, even when they use the same key.
Write synced metadata
Section titled “Write synced metadata”The synced methods are available on Base, including players, vehicles, peds,
objects and audio. Clients can read synced metadata. The server sets and deletes it.
| Method | Behavior |
|---|---|
setSyncedMeta(key, value) |
Sets or replaces one value. |
setSyncedMeta(values) |
Merges the supplied keys in one atomic update. Other keys remain unchanged. |
getSyncedMeta(key) |
Returns a copy of the value, or undefined for a missing key. |
hasSyncedMeta(key) |
Checks whether the key exists. |
getSyncedMetaKeys() |
Returns the current keys. |
deleteSyncedMeta(key) |
Removes a key. Deleting a missing key has no effect. |
This server example assigns a taxi job, changes duty status and removes the job:
// @ts-check/// <reference types="@revomp/types-server" />/// <reference path="../shared/metadata.d.ts" />
/** @param {import('revo-server').Player} player */export function assignTaxiJob(player) { player.setSyncedMeta({ 'job:name': 'taxi', 'job:onDuty': false, });}
/** * @param {import('revo-server').Player} player * @param {boolean} onDuty */export function setDuty(player, onDuty) { player.setSyncedMeta('job:onDuty', onDuty);}
/** @param {import('revo-server').Player} player */export function removeJob(player) { player.deleteSyncedMeta('job:name'); player.deleteSyncedMeta('job:onDuty');}Values are copied when written and read. Editing the original object or a value
returned by getSyncedMeta() does not update the stored data. Call
setSyncedMeta() again to apply the edited value.
null is a stored value. undefined is rejected as input, so use
deleteSyncedMeta() to remove a key. An invalid value or exceeded limit rejects
the entire batch without changing any keys.
Who receives synced metadata
Section titled “Who receives synced metadata”For entities, metadata follows streaming and dimension visibility. Player metadata also goes to that player’s own client. Audio metadata follows the audio’s recipients.
Keep private account data and credentials in server-only storage. Synced metadata is available to the object’s observers and has no per-key recipient filter.
When a client first receives an object, it receives the current metadata. If the server removes the object from that client’s stream, updates stop. Returning observers receive the latest values. Destroying the object removes its metadata.
Read values and handle changes
Section titled “Read values and handle changes”Both sides expose syncedMetaChange(object, key, newValue, oldValue). On the client,
it fires for initial values as well as later updates. A missing previous value is
undefined, and deletion supplies undefined as the new value.
Registering a handler does not replay past notifications. Read values from objects already available when your script starts, then handle changes:
// @ts-check/// <reference types="@revomp/types-client" />/// <reference path="../shared/metadata.d.ts" />import * as revo from 'revo-client';
/** @param {revo.Player} player */function logJob(player) { const job = player.getSyncedMeta('job:name') ?? 'none'; const onDuty = player.getSyncedMeta('job:onDuty') ?? false; revo.log(`Player ${player.networkId}: ${job}, on duty: ${onDuty}`);}
revo.on('syncedMetaChange', (object, key) => { if (object instanceof revo.Player && (key === 'job:name' || key === 'job:onDuty')) { logJob(object); }});
for (const player of revo.Player.all) { logJob(player);}A batch updates the metadata store before notifications are delivered, with a notification for each changed key. Writing an unchanged value does not produce a change event. Several writes to one key can be combined before sending, so clients may only see the final value. Use remote events when every individual action must be delivered. Server change notifications retain each actual change.
Metadata can be available before the entity’s GTA instance is ready. Reading it
does not require a game handle. For behavior that uses natives, initialize it in
entityStreamIn and apply later metadata changes while the entity is ready.
See Streaming and readiness.
Values and limits for synced metadata
Section titled “Values and limits for synced metadata”Supported values are null, booleans, finite numbers, strings, bigint,
Uint8Array, arrays and plain objects containing those values. Functions, entity
objects, class instances, cyclic data, accessors and proxies are rejected.
| Limit | Maximum |
|---|---|
| Key length | 128 UTF-8 bytes, with at least one byte and no null characters or unpaired surrogates. |
| Value size | 16 KiB after encoding. |
| Keys per object | 128. |
| Total metadata per object | 64 KiB of keys and encoded values. |
Encoding adds type and length information, so a raw 16 KiB byte array already exceeds the value limit. Keep synced values small and update them when their meaningful state changes.
Type known synced keys
Section titled “Type known synced keys”Extend ICustomBaseSyncedMeta in revo-shared to give known keys their value types.
Include this declaration file in both the server and client projects:
/// <reference types="@revomp/types-shared" />import 'revo-shared';
declare module 'revo-shared' { interface ICustomBaseSyncedMeta { 'job:name': string; 'job:onDuty': boolean; }}The examples reference this shared file for type checking. It gives editor hints
and checks values in JavaScript with @ts-check as well as in TypeScript. It does
not add runtime validation. The interface applies to all Base objects, and a
declared key can still be absent, so reads also allow undefined.