Area
Defined in: server/api.d.ts:6321
Handle for one area: one of the level’s own gameplay areas, or one a script or the World Builder drew. The server tests who is inside itself, by the game’s own rule for that kind of area.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new Area(
handle):Area
Defined in: server/api.d.ts:6326
Wraps an area handle the server already holds; use Area.create, Area.getById or the lookups to get one.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Internal area handle.
Returns
Section titled “Returns”Area
Methods
Section titled “Methods”contains()
Section titled “contains()”contains(
position):boolean
Defined in: server/api.d.ts:6434
Tests a position the way the game tests its own areas, whether or not the area is enabled and in whatever world.
Parameters
Section titled “Parameters”position
Section titled “position”The world position to test.
Returns
Section titled “Returns”boolean
True when the position is inside.
containsPlayer()
Section titled “containsPlayer()”containsPlayer(
player):boolean
Defined in: server/api.d.ts:6441
Tests where a body stands right now, and in which world: an area bound to another virtual world does not contain it. This is containment only – whether the game considers the player to be trespassing is decided by its own crime system on the player’s client.
Parameters
Section titled “Parameters”player
Section titled “player”The body to test; a player who has not reported a pose yet is never inside.
Returns
Section titled “Returns”boolean
True when the body is inside.
destroy()
Section titled “destroy()”destroy():
boolean
Defined in: server/api.d.ts:6454
Removes a script area. Every body still inside gets its areaExit first, while the handle still resolves.
Returns
Section titled “Returns”boolean
False for a level area or one already gone.
setShape()
Section titled “setShape()”setShape(
definition):boolean
Defined in: server/api.d.ts:6448
Moves, turns or reshapes a script area. Bodies standing where it now is, or was, get their areaEnter and areaExit on the next tick. A level area cannot be reshaped.
Parameters
Section titled “Parameters”definition
Section titled “definition”Partial<AreaDefinition>
The shape fields to change; any left out keep their value. id, labels, metadata and the rest are ignored here.
Returns
Section titled “Returns”boolean
False for a level area, a gone one, or a shape the engine could not build.
toJSON()
Section titled “toJSON()”toJSON():
AreaDefinition|null
Defined in: server/api.d.ts:6460
The definition Area.create takes to build this area again, which is what a script saves: the server keeps nothing past a restart. It is the format the World Builder exports too.
Returns
Section titled “Returns”AreaDefinition | null
Null for a level area, which the level always builds.
toString()
Section titled “toString()”toString():
string
Defined in: server/api.d.ts:6427
Formats this area for logging and debugging.
Returns
Section titled “Returns”string
Its id, kind, type and name.
staticall(kind?):Area[]
Defined in: server/api.d.ts:6512
Every area the server knows.
Parameters
Section titled “Parameters”"script" | "level"
Optional: only the level’s areas, or only script ones.
Returns
Section titled “Returns”Area[]
The areas, level ones first.
create()
Section titled “create()”
staticcreate(definition):Area
Defined in: server/api.d.ts:6467
Builds a script area. Bodies already standing in it get areaEnter on the next tick. Kept in memory only: save area.toJSON() wherever the resource keeps its data, and create it again on boot.
Parameters
Section titled “Parameters”definition
Section titled “definition”The area to build, in the format area.toJSON() and the World Builder export write.
Returns
Section titled “Returns”Area
The new area. Throws for an id already taken or a shape the engine could not build.
getAt()
Section titled “getAt()”
staticgetAt(position,virtualWorld?):Area[]
Defined in: server/api.d.ts:6482
Every enabled area containing a position, level and script alike.
Parameters
Section titled “Parameters”position
Section titled “position”The world position to test.
virtualWorld?
Section titled “virtualWorld?”number
Optional world; when given, a script area bound to another world is left out.
Returns
Section titled “Returns”Area[]
The areas, in no particular order.
getAtPlayer()
Section titled “getAtPlayer()”
staticgetAtPlayer(player):Area[]
Defined in: server/api.d.ts:6489
Every enabled area the body stands in right now, in its own world.
Parameters
Section titled “Parameters”player
Section titled “player”The body whose position and world to test.
Returns
Section titled “Returns”Area[]
The areas; empty for a player who has not reported a pose yet.
getById()
Section titled “getById()”
staticgetById(id):Area|null
Defined in: server/api.d.ts:6474
Looks an area up by its stable identity.
Parameters
Section titled “Parameters”string
A script area’s id, or a level area’s GUID in hex as area.definition.id prints it.
Returns
Section titled “Returns”Area | null
The area, or null when there is none.
nearby()
Section titled “nearby()”
staticnearby(position,radius,virtualWorld?):Area[]
Defined in: server/api.d.ts:6498
Every area whose bounds come within a radius of a position, enabled or not.
Parameters
Section titled “Parameters”position
Section titled “position”Where to look from.
radius
Section titled “radius”number
How far, in metres, from the area’s bounds.
virtualWorld?
Section titled “virtualWorld?”number
Optional world; when given, a script area bound to another world is left out.
Returns
Section titled “Returns”Area[]
The areas, nearest first.
withLabel()
Section titled “withLabel()”
staticwithLabel(label):Area[]
Defined in: server/api.d.ts:6505
Every area carrying a label, such as private or castle.
Parameters
Section titled “Parameters”string
The label, compared without regard to case.
Returns
Section titled “Returns”Area[]
The areas, level ones first.
Properties
Section titled “Properties”bounds
Section titled “bounds”
readonlybounds:object
Defined in: server/api.d.ts:6401
The world box around the area. An area with no ceiling reaches far above and below.
max:
Vector3
min:
Vector3
collision
Section titled “collision”collision:
boolean
Defined in: server/api.d.ts:6366
Invisible boundary walls block both directions while enabled, leaving the interior empty. Authored areas only; invalid collision shapes throw.
readonlydoors:AreaDoor[]
Defined in: server/api.d.ts:6411
The doors the level itself links to this area as its crime_doors, which is how the game knows a house’s doors. Only native links: nothing is inferred from where a door stands.
enabled
Section titled “enabled”enabled:
boolean
Defined in: server/api.d.ts:6371
Whether crossings are raised and the lookups find it. Switching it off raises areaExit for everyone inside on the next tick; switching it on, areaEnter. Works on level areas too.
exists
Section titled “exists”
readonlyexists:boolean
Defined in: server/api.d.ts:6331
False once a script area has been destroyed; every other read then returns its empty value.
height
Section titled “height”
readonlyheight:number
Defined in: server/api.d.ts:6391
How far above its lowest point a prism reaches, in metres; 0 for a shape with no ceiling. A TriggerArea’s comes from the level’s baked prism.
readonlyid:string
Defined in: server/api.d.ts:6336
The stable identity to store an area under. A level area’s is its EntityGuid as sixteen lowercase hex digits, the same on every machine and every boot, as door.guid prints a door’s; a script area’s is the id it was created with.
readonlykind:"script"|"level"
Defined in: server/api.d.ts:6341
Whether the level placed it or a script built it.
labels
Section titled “labels”labels:
string[]
Defined in: server/api.d.ts:6356
The level’s own Label values – private, personal, interior, prohibited, castle and the rest the game’s AI reads – or a script area’s labels. Only a script area’s can be changed.
location
Section titled “location”
readonlylocation:string
Defined in: server/api.d.ts:6396
For a SmartAreaShape bound to one of the game’s map locations, that location’s English name, e.g. a settlement. Empty otherwise.
members
Section titled “members”
readonlymembers:Area[]
Defined in: server/api.d.ts:6406
For an AreaUnion, the TriggerAreas it joins; it contains whatever one of them does. Empty otherwise.
metadata
Section titled “metadata”metadata:
Record<string,unknown>
Defined in: server/api.d.ts:6361
Whatever a script keeps on a script area: ownership, a type, rules. Stored as JSON, so read it, change it and assign it back. Always empty on a level area.
name:
string
Defined in: server/api.d.ts:6351
The level’s entity name, or the script area’s name. Only a script area’s can be changed.
occupants
Section titled “occupants”Defined in: server/api.d.ts:6421
Every body inside as of the last tick: players, horses, carts and server NPCs.
players
Section titled “players”
readonlyplayers:Player[]
Defined in: server/api.d.ts:6416
Every player inside as of the last tick, in any world.
position
Section titled “position”position:
Vector3
Defined in: server/api.d.ts:6381
A script area’s origin, which its shape is placed from; assignment moves it. A level area’s is the centre of its bounds.
rotation
Section titled “rotation”rotation:
Quaternion
Defined in: server/api.d.ts:6386
A script area’s orientation; assignment turns it. A level area’s shape is already in world space, so its rotation is the identity.
readonlytype:"sphere"|"box"|"shape"|"TriggerArea"|"AreaUnion"|"SmartAreaShape"
Defined in: server/api.d.ts:6346
A level area’s entity class – a TriggerArea prism, an AreaUnion of them, or a SmartAreaShape – or a script area’s shape.
virtualWorld
Section titled “virtualWorld”virtualWorld:
number|null
Defined in: server/api.d.ts:6376
The one virtual world a script area belongs to, or null for all of them. A body in another world still crosses it, with matchingVirtualWorld false. A level area is in every world.