World

The world's clock and weather, which all players' games follow, and questions about the world, such as what a ray hits, the ground under a point, and what stands nearby. The server has no world geometry, so it asks one player's game. Its promise settles with the answer, or without one after five seconds or if that player leaves. Client scripts ask their own game and get the answer within the call, in a frame or two, with more detail on the hit, including kind, mesh, class, name and level GUID. That suits archery, fishing, building, and pressing a key while looking at something. A client's answers are not sent to others and prove nothing to the server.

world.addInteraction()

World.addInteraction(options, handler)

Adds the game's "press [key] to ..." hint on a level entity by name, on a player's or NPC's body, which that player does not see, or at a position. A player aiming at it within `radius` metres sees the hint, and using it runs your handler. It returns an object with setEnabled, setText, setPlayers, where null means everyone, and remove. A resource's interactions end when it stops. Several on one target show together, one per key, as the game shows "E talk, R pickpocket" on its people.

world.landmarks()

World.landmarks()

Points of interest in the server's level, from the game's level files: { name, group, level, position }. `group` is the part of the map the files put it under, and `position` is the middle of what the level places there, not a map marker, so it may be in a tree or on a roof. Empty on a level not in the catalogue.

world.replicasAround()

World.replicasAround(position, radius, dimension)

Server entities around a point, closest first: players, horses, NPCs, dogs, props, dropped items, doors and stashes, each as its own object. It needs no client, so it is immediate. Gates are not listed, since their catalogue has no positions. For the level's own entities, use a client's entitiesAround.

world.raycast()

World.raycast(player, from, to, options)

Asks a player's game to trace a ray, resolving to { answered, reason, hit }. `hit` is null or { position, normal, distance, terrain, entity, surface, kind, model, category, material, entityGuid, entityName, entityClass, levelObject }. `entity` is the player, NPC or horse hit, or null. `kind` is 'terrain', 'entity', 'vegetation', 'brush' or 'static'. `model` is a brush or vegetation mesh in lower case. `category` is 'tree', 'bush', 'plant' or 'rock'. `levelObject` is what LevelEdit.apply needs to find the object, where a tree, bush or plant the level paints is a 'brush' object found by mesh and position, and it is null for terrain and anything spawned. `material` is currently always null.

world.traceAll()

World.traceAll(player, from, to, options)

Like raycast, but resolves to { answered, reason, hits } with all hits along the ray, nearest first.

world.snapToGround()

World.snapToGround(player, position, options)

Asks a player's game for the ground's height under a point, resolving to { answered, reason, z, hit }, with z null if there is no ground.

world.entitiesAround()

World.entitiesAround(player, center, radius)

Asks a player's game which replicated bodies it shows around a point, resolving to { answered, reason, entities }, each { entity, position, distance }, nearest first.

world.setLevelItemsEnabled()

World.setLevelItemsEnabled(enabled)

Turns off or on the items the level places to pick up, such as tankards, tools and shop goods, for all players. When off, all games hide them, including later joiners, and no pick-up is granted. To start with them off, put { "enabled": false } in level-items.json. When on, a picked-up item is gone for everyone, the first in reach gets it, and worldItemPickup can refuse.

world.setPlaceName()

World.setPlaceName(place, name)

Renames a town or place for all current and future players, wherever the game uses its own text: its quest location and settlement. Names inside a sentence, such as a dialogue line, stay as they are. The same name shows in all languages. Returns false for a place the game does not have.

world.places()

World.places()

All named places, as { id, gameName, name }, with gameName the game's English name and name the current one. For World.setPlaceName.

world.day

day

The world clock's current day, as whole days since it started.

world.hour

hour

The current hour, from 0 up to 24, with minutes as the fraction.

world.timeScale

timeScale

Game seconds per real second, where 0 freezes the clock. Default 15.

world.weather

weather

The preset the sky shows or is fading to.

world.lastWeather

lastWeather

The preset the sky is fading from.

world.weatherFade

weatherFade

Whether the sky is still fading from lastWeather to weather.

world.weatherLeft

weatherLeft

Game seconds left in the fade, or 0 once settled.

world.rainStrength

rainStrength

How hard it rains, 0 to 1.

world.rainLevel

rainLevel

How much of the sky rains, 0 to 1.

world.wind

wind

The wind in metres per second.

world.windSpeed

windSpeed

The wind's speed in metres per second.

world.wetness

wetness

How wet the ground is from rain over time. It dries much more slowly than it soaks.

world.puddles

puddles

How much water stands in puddles, 0 to 1.

world.levelItemsEnabled

levelItemsEnabled

Whether the level's items are on.

world.level

level

The level this server runs.

world.setTime()

World.setTime(day, hour)

Moves the clock forward to a day and hour. Returns false if either is out of range or that moment has passed.

world.setHour()

World.setHour(hour)

Moves the clock to the next time it is this hour, which may be the next day.

world.setTimeScale()

World.setTimeScale(scale)

Sets the clock's speed, in game seconds per real second, from 0, frozen, to 200.

world.setWeather()

World.setWeather(preset, seconds)

Fades the sky to a weather preset over some game seconds, up to 21600, where 0 changes it at once. worldWeatherChange follows.

world.setRain()

World.setRain(intensity, amount)

Sets the rain. Returns false if a value is out of range.

world.setWind()

World.setWind(wind)

Sets the wind in metres per second, with missing components as 0. Returns false for a non-finite value, or wind over 50 m/s.

world.groundHeight()

World.groundHeight(position, options)

Client only. Finds the surface height below a point with a downward trace, so bridges, floors and roofs count, not just terrain. Returns null if nothing is found.