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

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

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