Stream-synced metadata

Stream-synced metadata attaches gamemode-defined values to server entities. A value is sent to players currently streaming the entity and included in future stream-in snapshots.

const vehicle = vimp.vehicles.create(
  vimp.hash('adder'),
  94.5,
  -1940.2,
  20.7,
  307,
  { dimension: 0 },
)

if (vehicle) {
  vehicle.setStreamSyncedMeta('fuel', 65)
  vehicle.setStreamSyncedMeta('owner', null)
}

Clients read replicated values without being able to mutate the authoritative store.

vimp.on('streamSyncedMetaChange', (change) => {
  if (
    change.entityType === vimp.entities.ENTITY_TYPE.Vehicle &&
    change.key === 'fuel'
  ) {
    console.log(`Vehicle #${change.entityId} fuel:`, change.newValue)
  }
})

vimp.on('vehicleStreamIn', (vehicle) => {
  if (!vehicle) return

  if (vehicle.remoteId === null) return

  const fuel = vimp.entities.getStreamSyncedMeta<number>(
    vimp.entities.ENTITY_TYPE.Vehicle,
    vehicle.remoteId,
    'fuel',
  )
  console.log(`Vehicle #${vehicle.remoteId} streamed in with fuel ${fuel}`)
})

Values must survive JSON serialization. Prefer explicit records, strings, numbers, booleans, arrays, and null. Do not pass functions, class instances, cyclic structures, or undefined. Use deleteStreamSyncedMeta(key) to remove a key.

The client streamSyncedMetaChange event also fires for keys in the initial stream-in snapshot. Its oldValue is undefined for the first observed value; newValue is undefined for a deletion. Leaving streaming range clears the local store without emitting deletion events.

Metadata is ideal for compact presentation state such as ownership labels, fuel, faction, or interaction flags. Large or private application data belongs in explicit events or server-side storage.

Stream-synced metadata ​

Stream-synced metadata