Client Global Functions

Global functions available in every client-side Lua script — sounds, lights, UI, and the local player.

These functions are available as globals in every client-side Lua script (a mob’s scripts.client-update / scripts.client-on-create / scripts.client-on-interact hooks, an interactable’s client hooks, and so on). They affect only the local player’s game — nothing here is sent to the server or seen by other players.

Function Reference

play_sound(sound_name, volume)

Plays a sound loaded from a sound-config.md file and returns a sound object for controlling playback (see lua-client-sounds.md), or nil if the sound could not be started.

  • sound_name must be fully qualified: "ModName:sound_name".
  • volume is a percentage from 0 to 100 — 100 is full volume, 50 is roughly half as loud, 0 is silent. The player’s master and category volume settings are applied on top.
  • Returns nil for unknown names (logged to the client log) and for sounds that come out silent.
return function(static_object)
    static_object.lua_data.creak = play_sound("Creation:chest_creak", 80)
end

create_new_light()

Returns a fresh light table with a unique id, ready to fill in and attach to an entity or static object with add_light. The light does nothing until attached. See lua-client-lights.md for the fields and a full example.

get_main_player_location()

Returns the local player’s current location — a read-only object with .x, .y (block coordinates) and .world (string). It is a snapshot; it does not track the player afterwards.

display_crafting_menu(craft_type, tier)

Opens the crafting menu (opening the inventory with it). craft_type (string) selects which recipe category to show — a case-insensitive tag matched against recipes’ crafting-type (Crafting, Smelting, or any custom category your mod defines). Only a blank string is invalid; it falls back to the default Crafting category with a logged warning. tier (string, optional) is the tier this station provides — one of the names declared for that type in a crafting-types block. Omit it (or pass nil) for the type’s base tier. Recipes needing a higher tier still show in the menu, greyed with the tier they need.

Typically called from an interactable’s client-on-interact hook so that e.g. a workbench opens its own tier. The craft_type and tier you pass should match the interactable’s server-side crafting-station block, since crafting is validated server-side:

return function(static_object)
    display_crafting_menu("Crafting", "bench")
end

open_entity_interacted_inventory(entity_id)

Opens the inventory panel for the entity with the given ID (e.g. a pack animal). Does nothing if the entity isn’t present on this client. Pair with entity:get_id().

open_static_object_interacted_inventory(object_id)

Opens the inventory panel for the static object with the given ID (e.g. a chest). Does nothing if the object isn’t present on this client. Pair with static_object:get_id():

return function(static_object)
    open_static_object_interacted_inventory(static_object:get_id())
end

open_trade_panel(vendor_id)

Opens the vendor trade panel for the interactable with the given ID, and the player inventory alongside it (so the player can sell from their own slots). Returns true if it opened, false if the id isn’t present on this client. The panel reads the vendor’s stock and prices from config; the server validates and executes every buy/sell. Call it from a vendor’s client-on-interact:

return function(entity)
    if open_trade_panel(entity:get_id()) then
        play_sound("Creation:chest_open", 70.0)
    end
end

open_enhancement_panel(station_id)

Opens the gear-enhancement station panel (reforge / socket / salvage) for the interactable with the given ID, along with the station’s own single work slot and the player inventory (so the player can drop gear into the slot). Returns true if it opened, false if the id isn’t present on this client. The panel reads the station’s kind from config; every enhancement is validated and executed server-side. Call it from a station’s client-on-interact:

return function(entity)
    if open_enhancement_panel(entity:get_id()) then
        play_sound("Creation:chest_open", 70.0)
    end
end

Reserved Globals

The engine also installs a global table named app for its own use. Don’t overwrite or modify it — animation playback resolves textures through it.

See Also

Last updated