maps

#maps.current(): string?

The id of the map being played ("Earth", or "author.mod:map" for a mod map), or nil in the menus.

#maps.list(): any

Every map that can be played, as { id, name, subtitle, mod }.

#maps.load(mapId: string)

Chooses the map the host's next session starts on; the game does not change map in the middle of a session. Takes a map id from maps.list, such as "Earth" or "author.mod:map". Client scripts cannot change map: send a message to your server script instead.

maps.load("theonaris.examples.crater-canyon:crater-canyon")

#maps.onEnter(mapId: string, handler: function): Subscription

Calls handler({ id }) every time the players arrive on a map — and at once if they are already on it, because a mod can start after its map loaded (after /mods.reload, or on a client joining late). The map id may be a full id ("author.mod:map", "Earth") or the id of one of this mod's own maps ("crater-canyon"). Pair it with maps.onLeave to clean up.

maps.onEnter("crater-canyon", function() music = audio.music("music/theme.wav") end)
maps.onLeave("crater-canyon", function() music:fadeOut(2) end)

#maps.onLeave(mapId: string, handler: function): Subscription

Calls handler() when the players leave a map they were on (back to the menu, or to another map). Same map ids as maps.onEnter.

#maps.resetWater()

Undoes maps.setWater: the current map gets back the water its file declares.

#maps.setWater(settings: boolean|table)

Adds or removes the sea on the current map for every player, until the map changes. Pass true or false, or { enabled, level } to also move the sea to a height (world Y, metres). Ships float, sails stop and splashes happen on the new water at once.

• settings: true, false, or { enabled = boolean?, level = number? }

maps.setWater(false)                        -- drain the map
maps.setWater{ enabled = true, level = 4 }  -- flood it to Y 4

#maps.spawnPoints(): vec3[]

Where players start on the current mod map, or an empty list on one of the game's own maps.

#maps.tryLoad(mapId: string): boolean, string?

Like maps.load, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.

Returns true and the result on success; false and the reason on a refusal.

maps.load("theonaris.examples.crater-canyon:crater-canyon")

#maps.tryResetWater(): boolean, string?

Like maps.resetWater, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.

Returns true and the result on success; false and the reason on a refusal.

#maps.trySetWater(settings: boolean|table): boolean, string?

Like maps.setWater, but a refusal returns false and the reason instead of raising an error. Wrong arguments, side and permission errors still raise.

• settings: true, false, or { enabled = boolean?, level = number? }

Returns true and the result on success; false and the reason on a refusal.

maps.setWater(false)                        -- drain the map
maps.setWater{ enabled = true, level = 4 }  -- flood it to Y 4

#maps.water(): any

The sea on the current map, as { enabled, level, script }: whether there is water, its height (world Y, metres), and whether a server script set it rather than the map. Maps choose their water in their file ("water").

local w = maps.water()
if w.enabled then log.info("sea level " .. w.level) end