Skip to content

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.

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.

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.

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.

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.

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.

Extend ICustomBaseSyncedMeta in revo-shared to give known keys their value types. Include this declaration file in both the server and client projects:

shared/metadata.d.ts
/// <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.