Skip to content

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.

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.

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.

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 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.

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.