Dimensions and visibility
Dimensions separate groups of players and entities at the same coordinates. They can be used for private interiors, character selection or separate game sessions. The GTA map stays the same.
Dimension values
Section titled “Dimension values”| Value | Behavior |
|---|---|
0 |
The default dimension for players and world objects. |
1 through 4294967294 |
Additional dimensions assigned by your scripts. |
globalDimension (4294967295) |
Makes an entity visible from every numbered dimension. Players cannot use this value. |
An entity is eligible for streaming when its dimension matches the player’s, or when the entity is global. Distance and the other streaming rules still apply to global entities.
Dimensions do not need to be created or registered. Assign the same number to
players and entities that belong together. Changing dimension leaves their
coordinates unchanged.
Move players and entities
Section titled “Move players and entities”Set dimension through the server API for players and networked entities. The
client receives the change and updates streaming. Loading entities in the new
dimension can take time, so use the usual readiness events before accessing
their GTA handles.
This server example creates a car in dimension 42. Call enterRoom(player)
for an already spawned player on foot to move them beside it. Players who remain
in dimension 0 cannot see the car or the player in the room.
// @ts-check/// <reference types="@revomp/types-server" />import * as revo from 'revo-server';
const roomDimension = 42;const car = new revo.Vehicle('sultan', { x: -1220, y: -1765, z: 3.9 }, 0);car.dimension = roomDimension;
/** @param {revo.Player} player */export function enterRoom(player) { player.dimension = roomDimension; player.pos = { x: -1225.6, y: -1768.9, z: 3.9 };}Set the player’s dimension to 0 to return to the default dimension. Assign a position
separately if the player should also return to a different location.
Vehicles and occupants
Section titled “Vehicles and occupants”Moving a vehicle to another numbered dimension also moves its occupants and its attached trailer. Changing the trailer’s dimension moves the towing vehicle too. For an occupied vehicle, change the vehicle’s dimension to move everyone together.
Changing only a player’s dimension releases their seat if the vehicle is no longer visible in the new dimension. A seat in a global vehicle can remain occupied. Making a vehicle global leaves its occupants in their current dimensions.
Client objects, audio and voice
Section titled “Client objects, audio and voice”Client scripts can set dimension on local objects they create, including local
entities, markers, blips and colshapes. These default to 0, so assign the intended
dimension when creating them. Use globalDimension for objects that should be
available in every dimension. A point blip attached to an entity follows that
entity’s dimension.
The client event playerDimensionChanged(oldDimension, newDimension) reports
changes to the local player’s dimension. It can be used to update local objects
that should follow the player.
Spatial audio respects dimension and distance. Attached audio follows its entity’s dimension. Detach it before assigning a different dimension. Frontend audio plays across dimensions for its selected listeners.
Spatial voice channels require speakers and listeners to be in the same dimension and within range. Non-spatial channels can connect players across dimensions, subject to channel membership and permissions.
Queries and script messages
Section titled “Queries and script messages”Server lookups and collections can include entities from other dimensions. For a
nearby-entity query, pass the player’s dimension to
Entity.getInRadius(position, radius, dimension) or the corresponding entity class.
The results include global entities. Omitting the dimension searches all
dimensions, while passing globalDimension selects only global entities.
Remote script messages are delivered to their chosen recipients regardless of dimension. Validate the sender’s dimension and distance when handling an interaction request on the server.