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.
Choose a shape
Section titled “Choose a shape”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.
Create a checkpoint
Section titled “Create a checkpoint”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.
// @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.
Entry, exit and direct checks
Section titled “Entry, exit and direct checks”| 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.
Dimensions, activation and movement
Section titled “Dimensions, activation and movement”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.
Validate server interactions
Section titled “Validate server interactions”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:
// @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.
Remove a shape
Section titled “Remove a shape”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.