addSphere or an (optionally rotated) box with addBox - everything else works exactly like a point: the same reveal stages, the same options and condition gates, the same automatic cleanup when your resource stops.
Zones live in the same spatial grid as points, and the frame loop only ever looks at the player’s neighborhood - so thousands of registered zones cost nothing at idle. Register your whole map up front; there’s no need to create and destroy zones as players move around.
Quick Start
2.0m the stack is live. The name and grain stages derive from the radius automatically - see Stage Derivation.
Functions
addSphere
addSphere
Register a sphere zone: a point whose reach is the sphere itself.Parameters:
data(table) - Zone configuration (see Sphere Options)
id(number) - The zone’s anchor id, forremove- ornilif the data was invalid (the reason is printed to the client console)
addBox
addBox
Register a box zone: reach is being inside the (optionally rotated) box.Parameters:
data(table) - Zone configuration (see Box Options)
id(number) - The zone’s anchor id, forremove- ornilif the data was invalid (the reason is printed to the client console)
remove
remove
Remove an anchor by id - the same Parameters:
remove shared by every add* export.id(number) - The id returned at registration
Manual removal is only needed for zones that stop making sense mid-session. Everything your resource registered is removed automatically when it stops or restarts.
Configuration
Sphere Options
vector3
required
Center of the sphere. A
vector4 or a plain { x, y, z } table (JSON, database rows) is accepted toonumber
required
Radius of the sphere in meters (must be greater than
0) - this is the reach: the stack is live while the player is inside itnumber
default:"0.0"
Extend the reach this far outside the radius. Useful for a small sphere on a prop or the floor, which the player’s origin - about a meter up - can never enter. The compatibility layers use it for bridged zones
Box Options
vector3
required
Center of the box - the volume extends
size / 2 in every direction from here, including vertically, so place coords.z at the vertical center of the volume, not the floor. A vector4 or a plain { x, y, z } table is accepted toovector3
required
Full dimensions of the box in meters:
x width, y depth, z height (a plain { x, y, z } table is accepted too)number
default:"0.0"
Rotation of the box in degrees around the vertical axis (a heading). A
vector3 euler or a vector4 quaternion is accepted too - its yaw is usednumber
default:"0.0"
Extend the reach this far outside the box in every direction. The compatibility layers use it for bridged zones
Shared Fields
Both exports accept the same anchor-level fields as every otheradd* export: label, icon, options (required), stages, expand, reveal, passive, and inVehicle, plus debug (see Debugging). They are documented in full on Options. Two zone-specific notes:
- Zones default to
reveal = 'ambient', like points. stagesoverrides the derived stages below; any key you omit keeps its derived value.
Stage Derivation
Zones derive their reveal stages from the volume instead of using theConfig.Stages defaults:
boundingRadius is the box’s horizontal bounding radius: sqrt((size.x / 2)² + (size.y / 2)²). A small zone gets comfortable absolute padding around it; a large one scales proportionally instead, so its grain and name stages always sit outside the volume.
For a box, the name and grain stages are radial distances from the center, but reach truth is the inside test: the stack goes live the moment the player steps into the rotated volume, whatever their distance from the center.
Stage boundaries are hysteretic everywhere: entering a stage is instant, but leaving requires backing out
Config.Stages.exitMargin (0.4m) past its threshold. For a box this applies to the inside test itself - while the stack is live, the volume is treated as 0.4m larger in every direction - so standing exactly on the edge never flickers the stack on and off.
Occlusion
Zones are never hidden by occlusion testing. A zone’s center usually sits inside the prop it wraps - a counter, an ATM, a vending machine - so a blocked test would hide it incorrectly.Debugging
Setdebug = true on any zone to draw its physical volume in-world: boxes as translucent faces plus edges, spheres as a sphere of their radius. Shapes are tinted with the theme accent and drawn at any distance while the flag is set - remove it for production.
coords, size, and rotation, then drop the debug flag.