Server Global Functions

Global functions available in every server-side Lua script, and how locations are passed between Lua and the engine.

These functions are available as globals in every server-side Lua script — mob hooks, item hooks, interactable hooks, weather hooks, block hooks, chat commands, and NPC dialogue.

Function Reference

log_info(message)

Writes message (string) to the server log at INFO level. The standard way to debug server-side scripts.

log_info("boss fight started")

broadcast_server_message(message)

Sends a chat message to every connected player. For a private message to one player, use entity:send_message(text) instead (see lua-server-entity.md).

broadcast_server_message("A meteor is falling!")

get_player_location_from_name(player_name)

Returns the named player’s current location (see below), or nil if no player with that exact name is online. The match is case-sensitive and uses the player’s login name, not their display name.

local loc = get_player_location_from_name("Alice")
if loc ~= nil then
    log_info("Alice is at " .. loc.x .. ", " .. loc.y .. " in " .. loc.world)
end

spawn_mob_at(mob_name, location)

Spawns a mob at the given location and announces it to all clients. Returns the spawned entity object (see lua-server-entity.md) on success, or nil on failure (unknown mob name, or no loaded world matches location.world). Failures are logged to the server log.

  • mob_name must be the fully qualified name, "ModName:mob_name" — e.g. "Creation:glorbo". There is no automatic mod-name prefixing.
  • location is a table with x, y (block coordinates) and world (world name string). All three are required.
  • The mob’s scripts.server-on-create hook runs as part of the spawn.
  • No overlap check is performed — the mob spawns even inside other entities.

The returned object lets you keep scripting against the spawned mob — set its display name, path it, damage/heal it, store an id, etc. This is the standard way to spawn boss adds or segments and then drive them.

local mob = spawn_mob_at("Creation:glorbo", { x = 120.0, y = 46.0, world = "world" })
if mob == nil then
    log_info("spawn failed")
else
    mob:set_display_name("Summoned Glorbo")
end

spawn_mount(mount_name, location)

Spawns a mount at the given location and announces it to all clients. Returns the spawned entity object (see lua-server-entity.md) on success, or nil on failure (unknown mount name, or no world matches location.world). Failures are logged to the server log.

mount_name is fully qualified ("ModName:mount_name"); location is the same {x, y, world} table as spawn_mob_at.

local boat = spawn_mount("Creation:rowboat", { x = 80.0, y = 30.0, world = "world" })
if boat ~= nil then
    boat:set_display_name("S.S. Scripted")
end

spawn_static_object_at(object_name, location)

Spawns a tree or plant (Decoration) static object into the live world at the given location and announces it to all clients. Returns the spawned static object (see lua-server-static-object.md) on success, or nil on failure (unknown object name, an interactable — which needs per-instance setup and is not supported — or no world matches location.world). Failures are logged to the server log.

object_name is fully qualified ("ModName:object_name", e.g. "Creation:tall_grass"); location is the same {x, y, world} table as spawn_mob_at. The first variation is used. Trees and plants normally place at world generation; this hook is for scripting and testing (e.g. dropping a patch of flora on demand).

local loc = player:get_location()
for dx = -3, 3 do
    spawn_static_object_at("Creation:tall_grass", { x = loc.x + dx, y = loc.y, world = loc.world })
end

set_weather_at(weather_name, duration_seconds, location)

Forces the weather in the region containing location to the named weather, overriding the biome’s normal selection (so you can set snow in a desert), and broadcasts the change to all clients. Returns true on success, or false (logged) if the world or weather name is unknown, or no weather region is loaded there yet.

  • weather_name is fully qualified ("ModName:weather", e.g. "Creation:snowy").
  • duration_seconds — a positive value reverts to the normal biome weather cycle after it elapses; 0 (or negative) holds the weather until it is set again.
  • location is the same {x, y, world} table as spawn_mob_at, and comes last in the argument list.
local loc = player:get_location()
set_weather_at("Creation:snowy", 60.0, { x = loc.x, y = loc.y, world = loc.world })  -- snow here for 60s

set_block_in_world(block_name, location)

Places a block by name at a {x, y, world} location — the block-placement counterpart to spawn_mob_at, for contexts that have no world object in scope (chat commands, NPC dialogue). Returns true on success, or false (logged) if the world or block name is unknown, or the target cell is in an unloaded chunk.

  • block_name is fully qualified ("ModName:block_name", e.g. "Creation:stone").
  • location is the same {x, y, world} table as spawn_mob_at; coordinates are world coordinates (1.0 = one block). The block is placed on its own configured layer.
  • Placing a falling block (falls-when-unsupported) unsupported starts it falling, exactly as an in-world placement does. (In a block hook you already have world — use world:set_block_at_from_name there; see lua-server-world.md.)
local loc = executor:get_location()
set_block_in_world("Creation:stone", { x = loc.x, y = loc.y - 1, world = loc.world })

get_block_variation(base_block_id, variation_name)

Returns the block ID (number) of the named variation of a base block, or nil if that variation does not exist. Takes the base block’s numeric ID — get one from a block table’s id field (see lua-server-world.md).

get_difficulty()

Returns the save’s difficulty as a lowercase string: "dormant", "awakened", "forsaken", or "condemned". The value is fixed for the whole session.

if get_difficulty() == "condemned" then
    spawn_mob_at("MyMod:elite_glorbo", { x = loc.x, y = loc.y, world = loc.world })
end

world_set_flag(key)

Sets a persistent, world-scoped story flag and returns true if it was newly set (false if it was already set). Flags are the shared, save-level record of one-time world events — a boss’s first defeat, an unlocked gate, a story beat. They persist across sessions and, in co-op, are shared by the whole world (unlike per-player capabilities). A key is any string you choose; namespace it to avoid clashes with other mods (e.g. "MyMod:boss.genesis.defeated").

The return value lets you detect a first occurrence atomically — the idiomatic way to run first-kill logic exactly once:

-- in a boss's server-side on_death script
if world_set_flag("Creation:boss.genesis.defeated") then
    -- first defeat only: advance the world, open the route onward
    broadcast_server_message("The Genesis warden falls. A path opens.")
end
-- re-fighting the boss later sets nothing new (returns false) and pays loot only

world_has_flag(key)

Returns true if the given world flag is currently set. Use it to gate spawns, structures, or routes on prior progress:

if world_has_flag("Creation:boss.genesis.defeated") then
    spawn_mob_at("Creation:harder_add", { x = loc.x, y = loc.y, world = loc.world })
end

Locations

Several APIs pass positions around as a location — a position plus a world name. Coordinates are in block units.

Receiving a location (from get_location(), get_player_location_from_name, weather region sampling): you get a read-only object with three fields:

local loc = entity:get_location()
loc.x      -- number
loc.y      -- number
loc.world  -- string (world name)

Passing a location (to spawn_mob_at, spawn_mount): build a plain table with the same three keys — all required:

{ x = 100.0, y = 42.0, world = "world" }

A received location object can be passed straight back into these functions, but you cannot modify it — to move a position, build a new table:

local loc = player:get_location()
spawn_mob_at("Creation:glorbo", { x = loc.x + 10, y = loc.y, world = loc.world })

See Also

Last updated