World

const World: object

Defined in: server/api.d.ts:6761

The server’s own clock and weather, which every client follows, and the three questions it can ask a client’s engine about the level itself.

Type Declaration

day

readonly day: number

Whole days the clock has run, from the level’s own midnight. Starts at 0 and only grows.

hour

readonly hour: number

Hour within the current day, from 0 up to but not including 24, with the minutes as the fraction. 13.5 is half past one.

level

readonly level: string

The configured level loaded by every client in this server session.

previousWeather

readonly previousWeather: string

The preset the sky is blending from; the same as weather once it has settled.

puddles

readonly puddles: number

Puddle coverage, from 0 to 1. Derived like wetness, and only starts filling after the rain has run a while.

rainAmount

readonly rainAmount: number

How much of the rain is drawn, from 0 to 1. Thins the downpour without stopping it.

rainIntensity

readonly rainIntensity: number

How hard it is raining, from 0 to 1.

timeScale

readonly timeScale: number

How many game seconds pass per real second. 15 is the game’s own pace, 0 stops the clock, and the server drops it to 0 by itself at the clock’s ceiling.

weather

readonly weather: string

The time-of-day preset the sky is blending towards, which is where it settles. Set it with setWeather.

weatherBlending

readonly weatherBlending: boolean

Whether a blend is still running. setWeather is refused while it is: a half-finished blend has no single preset to leave from.

weatherRemaining

readonly weatherRemaining: number

Game seconds left of the blend, and 0 once the sky has settled. setWeather is refused until then.

wetness

readonly wetness: number

How wet the ground has become, from 0 to 3. Derived from how long it has been raining, so it is read-only, and it dries far slower than it soaks.

wind

readonly wind: Vector3

The wind every client is blowing, in metres per second, world space. It bends the trees, drags the cloth and slants the rain, and it is the one part of the weather the game itself never touches. Set it with setWind.

windSpeed

readonly windSpeed: number

How hard the wind is blowing, whichever way: the length of wind, from 0 to 50.

entitiesInRadius()

entitiesInRadius(player, centre, radius, options?): Promise<WorldRadiusResult>

Every entity that client’s engine has inside a sphere, nearest first.

It reads the engine’s own spatial grid, so it costs what the sphere covers rather than what the level holds. This reports the level’s entities – doors, props, bodies – and not the server’s replicas; correlate them by guid.

The server has no world of its own, so this asks that player’s client and waits for it to answer. Three things follow: the answer is a round trip late; it covers only what that machine has streamed in, so a point far from the player reads as empty world; and it is a client’s word, which is fine for a prompt and is not fine for anything a player gains by lying about. The promise always settles – on the answer, on a five-second timeout, or when the player leaves – and answered says which.

Parameters

player

Player

Whose client is asked. Their machine is the one that answers, so pick a player near the point in question.

centre

Vector3

The centre of the sphere, in world-space metres.

radius

number

Its radius in metres, up to 256.

options?

class reports only entities of that engine class – AnimDoor, NPC_NAI, GeomEntity – and a class the engine does not know matches nothing rather than everything; omitted, every class is reported. max is how many to report, nearest first, up to 64. physicalOnly skips entities the engine has built no physics for, which is the filter the game’s own proximity query applies, and is off by default.

class?

string

max?

number

physicalOnly?

boolean

Returns

Promise<WorldRadiusResult>

The entities, once that client has looked.

pointsOfInterest()

pointsOfInterest(): object[]

Points of interest in the configured level only, from the compiled game catalog. Positions are ground-marker clusters checked against the level navmesh; a teleport still needs the destination to stream on the client.

Returns

object[]

raycast()

raycast(player, from, to, options?): Promise<WorldTraceResult>

Traces a segment through the world and reports the first thing it meets.

The server has no world of its own, so this asks that player’s client and waits for it to answer. Three things follow: the answer is a round trip late; it covers only what that machine has streamed in, so a point far from the player reads as empty world; and it is a client’s word, which is fine for a prompt and is not fine for anything a player gains by lying about. The promise always settles – on the answer, on a five-second timeout, or when the player leaves – and answered says which.

Parameters

player

Player

Whose client is asked. Their machine is the one that answers, so pick a player near the point in question.

from

Vector3

Where the ray starts, in world-space metres.

to

Vector3

Where it ends. Up to 4096 metres away; a ray of no length is refused.

options?

mode picks which of the game’s own three traces to run: cover asks whether the world is in the way – static geometry, props and doors block, and bodies cannot, which is what a line of sight wants; anything asks what is under the ray, bodies included, which is what a pick wants; ground sees only surfaces a player could stand on. It defaults to cover, and a name that is none of the three is rejected rather than guessed at.

mode?

"cover" | "anything" | "ground"

Returns

Promise<WorldTraceResult>

The trace, once that client has run it.

raycastAll()

raycastAll(player, from, to, options?): Promise<WorldTraceResult>

Traces a segment and reports everything solid along it, nearest first.

The server has no world of its own, so this asks that player’s client and waits for it to answer. Three things follow: the answer is a round trip late; it covers only what that machine has streamed in, so a point far from the player reads as empty world; and it is a client’s word, which is fine for a prompt and is not fine for anything a player gains by lying about. The promise always settles – on the answer, on a five-second timeout, or when the player leaves – and answered says which.

Parameters

player

Player

Whose client is asked. Their machine is the one that answers, so pick a player near the point in question.

from

Vector3

Where the ray starts, in world-space metres.

to

Vector3

Where it ends. Up to 4096 metres away; a ray of no length is refused.

options?

mode is as World.raycast documents it. maxHits is how many things along the ray to report, up to 8 and 8 by default; each is a separate solid hit, found by re-tracing past the one before, so a window does not hide the wall it is set in.

maxHits?

number

mode?

"cover" | "anything" | "ground"

Returns

Promise<WorldTraceResult>

The trace, once that client has run it.

replicasInRadius()

replicasInRadius(position, radius, virtualWorld?): Entity[]

The server’s own replicated entities near a point, nearest first – players, horses, dogs, props, dropped items, doors, gates and stashes, each as its own handle.

This needs no client: the server already knows where its replicas are, so unlike entitiesInRadius it is immediate and authoritative. It sees only what the server replicates, which is the other half – the level’s own entities are what entitiesInRadius is for.

Parameters

position

Vector3

World-space point to measure from.

radius

number

How far to look, in metres.

virtualWorld?

number

Optional virtual world to look in; omitted looks in the global one, where every body starts.

Returns

Entity[]

The handles, nearest first.

resolveGround()

resolveGround(player, position, options?): Promise<WorldTraceResult>

What is underfoot at a point: its height in hit.position.z, the slope it landed on, and what the surface is made of.

A trace rather than a terrain height, so it stands on whatever is actually there – a bridge, a floor, a castle roof – and not on the heightmap underneath it. There is no bare-number form here, because a promise has to be able to say that nothing answered.

The server has no world of its own, so this asks that player’s client and waits for it to answer. Three things follow: the answer is a round trip late; it covers only what that machine has streamed in, so a point far from the player reads as empty world; and it is a client’s word, which is fine for a prompt and is not fine for anything a player gains by lying about. The promise always settles – on the answer, on a five-second timeout, or when the player leaves – and answered says which.

Parameters

player

Player

Whose client is asked. Their machine is the one that answers, so pick a player near the point in question.

position

Vector3

The point to look under, in world-space metres. Its own z is where the probe is centred.

options?

How far above the point the probe starts and how far below it reaches, in metres. 5 and 200 by default – the 5 above is what lets a point already slightly underground still resolve – and up to 512 each.

down?

number

up?

number

Returns

Promise<WorldTraceResult>

The probe, once that client has run it.

setHour()

setHour(hour): boolean

Winds the clock forward to the next time it is this hour, rolling into tomorrow when it has passed today. The clock never runs backwards: clients cannot be wound back with it.

Parameters

hour

number

Hour to wind forward to, from 0 up to but not including 24.

Returns

boolean

True when the clock moved; false when the hour is out of range.

setRain()

setRain(intensity, amount?): boolean

Sets the rain, which is separate from the sky preset: a preset can be overcast without a drop falling. Starting or stopping it restarts the phase the ground soaks and dries over.

Parameters

intensity

number

How hard it rains, from 0 to 1. 0 stops it.

amount?

number

How much of the rain is drawn, from 0 to 1; defaults to all of it.

Returns

boolean

True when the rain was taken; false when either value is out of range.

setTime()

setTime(day, hour): boolean

Winds the clock forward to an absolute day and hour, which is how a saved clock is restored.

Parameters

day

number

Absolute day to wind forward to, as the day property counts them. Must be whole.

hour

number

Hour of that day, from 0 up to but not including 24.

Returns

boolean

True when the clock moved; false when that moment is already past, or the day or hour is out of range.

setTimeScale()

setTimeScale(scale): boolean

Sets how fast the day passes for everyone.

Parameters

scale

number

Game seconds per real second, from 0 to 200. 0 freezes the clock where it stands.

Returns

boolean

True when the scale was taken; false when it is out of range.

setWeather()

setWeather(preset, seconds?): boolean

Blends the sky to another of the game’s time-of-day presets, and raises worldWeatherChange. Only a client can tell whether a preset exists, so a name the game does not know leaves every sky where it is.

Parameters

preset

string

Name of one of the game’s own time-of-day presets, such as cloudless_sunny.

seconds?

number

Game seconds to blend over, up to 21600. Omitted, the sky changes at once.

Returns

boolean

True when the blend started; false while an earlier one is still running, or when the name or duration is out of range.

setWind()

setWind(wind): boolean

Sets the wind for everyone. There is nothing to blend against – the engine takes a vector and holds it – so a gust is a script ramping this itself. It also drives a physical wind area, which is why the length is capped.

Parameters

wind

Vector3 | Partial<Vector3>

Wind velocity in metres per second, world space; omitted components are zero. Its length may not exceed 50.

Returns

boolean

True when the wind was taken; false when a component is not finite or it blows harder than 50 m/s.