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(power, craft_type)

Opens the crafting menu (opening the inventory with it). power (number) sets the available crafting power tier — recipes requiring more power than this are unavailable. 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.

Typically called from an interactable’s client-on-interact hook so that e.g. a workbench opens its own crafting tier. The power and craft_type 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(2, "Crafting")
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

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