API Containers

Containers

Lua API / Containers

betamoon.containers:add(definition)

Registers the interactive slot layout connecting a tile inventory to a player inventory. Returns a handle with qualified name. Requires the same owner script as the tile definition. Retained across reload; changes require restart.

local container = betamoon.containers:add {
    name = "mymod:block/storage", tileEntity = tile,
    slots = {
        { slot = "input", x = 44, y = 17 },
        { slot = "fuel", x = 44, y = 53, acceptsFuel = betamoon.mc.fuels.furnace },
        { slot = "output", x = 116, y = 35, outputOnly = true }
    },
    playerInventory = { x = 8, y = 84, includeHotbar = true }
}

Field definitions

Field	Type	Requirement / default
name	string	Required; qualified like tile names.
tileEntity	tile handle	Required tile definition.
slots	list of slot tables	Required visible tile slots.
playerInventory	table	Required player inventory placement.
session	named field table	Optional typed values that last until this container closes.
controls	named control table	Optional gameplay behavior for interactive GUI elements.
onClose	function	Optional callback before the session expires.
playerInventory.x, playerInventory.y	integers	Required GUI coordinates.
playerInventory.includeHotbar	boolean	Default true.

slots

Field	Type	Requirement / default
slot	string	Required declared tile slot name.
name	string	Defaults to slot name; player-facing label.
x, y	integers	Required position on the container GUI.
outputOnly	boolean	Default false; disallows player insertion while allowing machine output.
acceptsFuel	fuel-set reference or key	Optional; accepts only stacks in that set for manual and shift-click insertion. Cannot be combined with outputOnly.

A physical tile slot cannot appear twice. Unknown slot names are errors. acceptsFuel assists player interaction, but machine logic must still validate through consumeFuel because scripts, saved inventories and other mods can bypass a GUI slot. The container establishes interaction; a GUI definition establishes presentation. See Fuels.

Session state

Use tile data for saved machine state and session for temporary screen state such as tabs, searches, and drafts. Session fields support integer, number, boolean, and string, with default; strings also accept maxLength from 1 to 1024. Callbacks use ctx.session:get(name) and ctx.session:set(name, value). Stored session handles expire when the screen closes.

session = {
    selectedTab = { type = "integer", default = 1 },
    search = { type = "string", default = "", maxLength = 40 }
}

Controls

A control owns behavior while its matching GUI element owns position and visuals. A value control binds to exactly one tile or session field with bind = { data = "name" } or bind = { session = "name" }.

controls = {
    enabled = { type = "toggle", bind = { data = "enabled" } },
    speed = {
        type = "number", bind = { data = "speed" },
        minimum = 0, maximum = 100, step = 5
    },
    tab = {
        type = "choice", bind = { session = "selectedTab" },
        values = { 1, 2, 3 }
    }
}

Type	Binding and behavior
action	No binding; onActivate(ctx).
toggle	Boolean binding; toggles on activation.
number	Integer/number binding; requires minimum, maximum; optional positive step, pageStep.
text	String binding; optional maxLength; onEdit receives drafts and onCommit accepted values.
choice	Binding plus 2–64 typed values; optional wrap, default true.
custom	No built-in value; onInput(ctx, input) receives bounded pointer, scroll, and keyboard input.

Value controls accept beforeChange(ctx, proposed, current). Return betamoon.callbackResults.deny to keep the current value, betamoon.callbackResults.pass to accept it, or { result = betamoon.callbackResults.handled, value = replacement } to replace it after validation. onChange(ctx, value, previous) runs after an accepted value is applied. enabledWhen uses the same condition format as GUI visibility.

Callbacks receive the following scoped context. The context and its access objects expire after the callback.

Field	Meaning
player	Current player view, including name.
tile	{ x, y, z, data } for the open tile.
data	Direct alias for the tile's declared data access.
inventory	Named tile inventory access.
session	Temporary container-session access.
control	{ key, type, enabled } for the invoked control.
input	Input description below.

ctx.input and the second input argument passed to a custom control's onInput(ctx, input) expose the same detached values:

Field	Present for / meaning
source	"mouse", "keyboard", "focus", or "script".
phase	"press", "drag", "release", "scroll", "focus", or "blur" when applicable.
button	Native mouse button for pointer input.
wheel	Mouse-wheel delta for a scroll phase.
x, y	Element-local pointer coordinates.
deltaX, deltaY	Movement since the previous captured pointer event.
key	Native key code for keyboard input.
character	Typed character when the key event supplies one.
shift, control	Modifier-key state.
conflicted	True when externally synchronized tile text changed while a text editor was focused.

Fields that do not apply to the current source/phase are absent. A callback error cancels that action and disables the failing callback while leaving other controls usable.

Attaching a screen

A block may attach only a tile, or attach the tile together with both container and gui. Supplying just one of container/gui is invalid. The container must reference the attached tile, and the GUI must reference that container. Register all structural handles under the same script owner.

See Container GUIs.

Container lookup

Method	Result
betamoon.containers:get(name)	Container handle, or nil when absent.
betamoon.containers:getRequired(name)	Container handle; raises an error when absent.
betamoon.containers:find(query)	Result list filtered by optional name, owner, and tileEntity.
betamoon.containers:first(query)	First match, or nil.
betamoon.containers:one(query)	Sole match, nil for none, or an error for multiple matches.

Container handle

A live handle exposes name, owner, exists, and tileEntity (the qualified attached tile type name).

container:override(definition)

Overrides onClose and callbacks of already declared controls through changes.controls.<controlName>. Callback layers can call ctx:base() once. Slots, session fields, bindings, and control types remain structural. Removing the returned override handle restores the next lower behavior.