Area

A volume in the world that the server watches. An area is either the level's own, kind 'level', meaning each TriggerArea and SmartAreaShape on the server's map, such as houses, interiors, private grounds, stealth areas and settlements, with labels the game's AI reads. Or it is built by a resource with Area.create, kind 'script', as a box, sphere or polygon with a height. areaEnter and areaExit fire when a player, horse or NPC goes in or out. The server checks only bodies that moved, against nearby areas, so a body standing still costs nothing. Z is up. Changes from create, setShape and enabled are checked once your code returns, so their events come after the call, while destroy fires exits at once.

area.create()

Area.create(definition)

Creates an area from a definition.

area.getById()

Area.getById(id)

The area with this id, or null. A script area's id is the one it was created with. A level area's is its EntityGuid as sixteen hex digits, in any case, which is the same on all computers and after restarts.

area.getAt()

Area.getAt(position, dimension)

All enabled level and script areas containing a position, in no defined order.

area.aroundEntity()

Area.aroundEntity(body)

All enabled areas now containing a player, horse or NPC, in its dimension.

area.nearby()

Area.nearby(position, radius, dimension)

Areas within a radius of a position, closest first, including disabled ones. Distance is measured to their bounds.

area.taggedWith()

Area.taggedWith(label)

All areas with a label, ignoring case, with level areas first.

area.all()

Area.all(kind)

All areas the server knows, level areas first, about 3,300 on trosecko and 6,900 on kutnohorsko, then your resources'.

area.exists

exists

False once a script area is destroyed, and all reads then give empty values. A level area exists while the server runs its map.

area.id

id

A stable key for saving an area: a script area's id, or a level area's EntityGuid as sixteen lower-case hex digits.

area.kind

kind

'level' for the level's own, 'script' for those from Area.create.

area.type

type

A level area's entity class, 'TriggerArea', a prism baked into the level, 'SmartAreaShape', the outline of a settlement or location, or 'AreaUnion', a house of several rooms. Or a script area's shape, 'box', 'sphere' or 'shape'.

area.name

name

The level's entity name, such as 'pracharna_areaMarker_inn', or the script area's name. Only a script area's can be assigned, and a level area's throws.

area.labels

labels

The area's labels. A level area has the game's own, 'private', 'personal', 'semipersonal', 'semipublic', 'interior', 'prohibited', 'stealthArea_crouch', 'dogForbidden', 'suppressHorseCall' and others its AI reads, and they cannot change. Assign a new array to change a script area's.

area.metadata

metadata

Your JSON data on a script area. To change it, read, edit and assign it. Level areas always have {}, and assigning throws.

area.collision

collision

Script areas only. Invisible walls on the outline that all games collide with, from both sides, while enabled: a box's four sides, a shape's edges, or a sphere's closed shell. A shape needs a height above the thickness and edges that do not cross. Walls follow setShape, enabled and dimension, and go with destroy. False by default. You can assign to it. It throws a TypeError for a non-boolean or on a level area, and a RangeError if the shape cannot take walls that thick.

area.wallBottom

wallBottom

For box and shape areas with collision, adds a plate across the whole interior at the bottom, as strips one metre wide for a shape. False by default, and a sphere is always closed. You can assign to it. It throws a TypeError for a non-boolean or on a level area.

area.wallTop

wallTop

For box and shape areas with collision, adds a plate across the whole interior at the top. False by default. You can assign to it. It throws a TypeError for a non-boolean or on a level area.

area.wallThickness

wallThickness

Wall thickness in metres, across the outline: 0.05 to 2, default 0.2. You can assign it on script areas. A value out of range, or too large for the shape with collision on, throws a RangeError. Level areas throw a TypeError.

area.enabled

enabled

Whether the area fires events and getAt finds it. You can assign to it, on level areas too. Once your code returns, turning it off fires areaExit for everyone inside, and turning it on fires areaEnter.

area.dimension

dimension

A script area's dimension, or null if not tied to one. A level area is in all (null) and cannot be assigned one.

area.position

position

A script area's centre, from which its shape is placed, and assigning moves it. A level area's is the centre of its bounds and cannot be assigned.

area.rotation

rotation

A script area's rotation, and assigning turns it. Level areas use world coordinates directly, so theirs is always the identity and read-only.

area.height

height

How far a shape reaches above its lowest corner, in metres, where 0 means no floor or ceiling. A TriggerArea's comes from the level's prism. For a box, it is the height of its bounds, and for a sphere, 0.

area.location

location

Reserved, always ''. The server does not yet know which map location a SmartAreaShape represents.

area.bounds

bounds

The bounding box in world coordinates, { min, max }. With no ceiling, it extends a long way vertically.

area.members

members

An AreaUnion's member areas. A level's house of several rooms is one area, with type 'AreaUnion' and the house's labels, that a body is inside while in any room. Empty for other areas.

area.lockKey

lockKey

The key for this area's doors and chests. It reads as an item class id, or '' for none, and you assign an item class by name or GUID, or null to remove it. Whoever carries it gets the game's Unlock prompt on each locked door and chest in the area, and a Lock hint on the U key on an unlocked one. A door's key from door.setKey, or a chest's from stash.keyClass, comes first, so a supervisor's key can open what others' cannot. The area's level chests become the server's through Stash.adopt. Throws a TypeError for an item class that does not exist.

area.setLocked()

setLocked(locked)

Locks or unlocks all doors and chests in the area, and a door that locks also closes. Returns how many it reached, with a door counting once a player's game has shown it. Throws a TypeError for anything except true or false.

area.doors

doors

Doors the level links to this area, each { guid, name, position, link }, where `link` is 'entrance', 'basic' or 'storage'. Door.find takes the guid. Empty for a script area or one with no links. No player needs to be near.

area.players

players

Players now inside, in any dimension.

area.occupants

occupants

All bodies now inside, in any dimension: players, horses and NPCs.

area.contains()

contains(position)

Whether a position is inside by geometry alone, whether enabled or not, in any dimension.

area.holdsEntity()

holdsEntity(body)

Whether a player, horse or NPC is inside now, in the area's dimension. A level area is in all.

area.herbsWithin()

herbsWithin(dimension)

The level's herbs available to pick inside the area's current shape in a dimension, with no player needed nearby. It ignores `enabled` and leaves out picked, removed and turned-off plants. Empty for a destroyed area or a dimension the area is not in.

area.clearHerbs()

clearHerbs(dimension)

Removes the level's herbs inside the area in a dimension, including picked ones, until a respawn or server restart, with no items, XP or harvest events. They stay away whatever later happens to the area's shape or state. Returns how many were not already removed, or 0 for a destroyed area or a dimension it is not in.

area.regrowHerbs()

regrowHerbs(dimension)

Brings back picked and removed plants inside the area in a dimension at once, including those with regrowth off. Returns how many picks and removals ended, or 0 for a destroyed area or a dimension it is not in.

area.setShape()

setShape(definition)

Moves, turns or reshapes a script area, leaving omitted fields unchanged. After your code returns, areaEnter and areaExit fire for anything affected.

area.destroy()

destroy()

Removes a script area. Everyone inside gets areaExit first, while the object still works. Returns false if it is already gone or is a level area, which cannot be removed, though you can turn it off with enabled.