Skip to content

Colshapes

A colshape detects entities entering or leaving an area. Colshapes are created by client scripts and have no visible representation. Add a marker separately if players should see the area.

Coordinates and distances use metres. Boundary points count as inside.

Class Geometry and constructor arguments
ColshapeSphere Centre x, y, z, then radius. Checks distance in all three axes.
ColshapeCircle Centre x, y, then radius. Ignores height.
ColshapeCylinder Base centre x, y, z, then radius, height. Extends upwards from z to z + height.
ColshapeCuboid Minimum corner minX, minY, minZ, then maximum corner maxX, maxY, maxZ.
ColshapeRectangle Minimum corner minX, minY, then maximum corner maxX, maxY. Ignores height.
ColshapePolygon minZ, maxZ, then an array of world-space { x, y } vertices.

Radii and heights must be positive, and each maximum bound must exceed its minimum. Invalid geometry throws an error.

A polygon accepts 3 to 1,024 vertices in boundary order. Supply the first vertex once, as the last edge closes automatically. Concave polygons are supported. Self-intersections and zero-area polygons are rejected.

Circles and rectangles include every height at the same XY coordinates. Use a shape with height bounds for an interaction on a particular floor.

This client example creates a sphere near the beach spawn used in the first game mode. It logs when the local player enters or leaves and sends an entry notification to the server.

Client
// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
const checkpoint = new revo.ColshapeSphere(-1220, -1765, 3.9, 3);
checkpoint.playersOnly = true;
revo.on('entityEnterColshape', (shape, entity) => {
if (shape !== checkpoint || entity !== revo.Player.local) return;
revo.log('Entered the checkpoint.');
revo.emitServer('checkpoint:enter');
});
revo.on('entityLeaveColshape', (shape, entity) => {
if (shape !== checkpoint || entity !== revo.Player.local) return;
revo.log('Left the checkpoint.');
});

playersOnly defaults to false. Setting it to true includes both the local player and other streamed-in players. Check entity === Player.local when only the local player’s movement should trigger your interaction.

Colshapes check the entity’s position. A vehicle’s body can overlap an area before its position enters it. Detection runs each frame, so an entity that crosses an entire small area between checks can be missed.

API Behavior
entityEnterColshape(shape, entity) Fires when a streamed-in entity first qualifies as inside. It can also fire when a shape is created around an entity already there.
entityLeaveColshape(shape, entity) Fires when a tracked entity stops qualifying. This includes movement, stream-out, dimension changes and explicit destruction.
shape.isPointIn(position) Tests the geometry, even while the shape is inactive. It does not check dimensions.
shape.isEntityIn(entity) Tests the entity’s current position and the playersOnly filter. Both objects must be streamed in. An invalid object throws.

Enter events are not repeated while an entity stays inside. Registering a handler does not replay earlier events. Use isEntityIn() to check a player already present when adding an interaction to an existing shape.

There is no public member-list property. Keep a Set from enter and leave events if you need a collection of occupants. After an await, check that saved objects are still valid before using them.

A new shape starts in dimension 0. Set its dimension for another room, or use globalDimension to make it available in every dimension. See Dimensions and visibility.

Colshapes are checked throughout the visible dimension without a distance cutoff from their centre. Only entities loaded on that client can participate. streamDistance does not enlarge the set of loaded entities or limit the shape’s detection area.

Changing to an incompatible dimension deactivates the shape and removes its members. It can activate again when the dimension becomes visible. Setting streamingEnabled = false preserves the current active or inactive state, so it does not immediately disable an active shape. Dimension filtering still applies.

Assign shape.pos to move it. For a cuboid or rectangle, this is the minimum corner. For a cylinder, it is the base centre. A polygon starts at (0, 0, minZ), and position changes translate all its vertices and height bounds.

Geometry sizes are read-only and nonzero rotation is rejected. To resize a shape or change its vertices, destroy it and create a replacement.

The colshape API runs on the client. A client event can request a server action, and the server should check the player’s current position, dimension and any permissions needed for that action.

This handler accepts the notification only when the server’s player position is inside the same sphere in dimension 0:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
// Keep these values in a shared module used by both client and server.
const checkpoint = { x: -1220, y: -1765, z: 3.9, radius: 3, dimension: 0 };
revo.onClient('checkpoint:enter', (player) => {
if (player.dimension !== checkpoint.dimension) return;
if (!player.pos.isInRange(checkpoint, checkpoint.radius)) return;
revo.log(`Player ${player.id} reached the checkpoint.`);
});

The server uses its latest received position. Near a boundary, the client and server checks can differ until a movement update arrives. For rewards or purchases, also enforce eligibility and prevent repeated requests from applying the action twice.

Call shape.destroy() when the area is no longer needed. Explicit destruction emits leave events for tracked members before the shape becomes invalid. Repeated calls have no effect.

Shapes created by a resource are removed when it stops. Leave callbacks are skipped during resource shutdown, so required cleanup must also run independently of those callbacks.

Colshape (client).