HUD and Configuration Contract
Configuration and HUD are declarative. Lua defines schema and presentation models; Java owns validation, persistence, generated controls, rendering, layout, lifecycle, and performance.
Configuration declaration
hexis.config({
arrive_within = {
type = "number",
label = "Arrival distance",
default = 2,
min = 0.5,
max = 8,
step = 0.5,
},
stop_when_full = {
type = "boolean",
label = "Stop when inventory is full",
default = true,
},
})
Configuration is declared during discovery, before hexis.main. Supported types
are boolean, bounded number, string, enum, color, keybind, and validated
pack-provided selector. Unknown types or invalid defaults prevent registration.
At runtime hexis.config.values() returns an immutable snapshot. Changes arrive
as serialized events and are applied at a safe script boundary. Scripts cannot
mutate persistence directly.
Persistence
Stored values are keyed by script identity, schema version, and profile. Migrations are explicit pure-data transforms with input/output schemas and budgets. Invalid or removed fields fall back visibly; they do not silently retain incompatible values.
Secrets, session tokens, and unrestricted files are not configuration types.
HUD model
local hud = hexis.hud.create({
id = "collector-status",
title = "Collector",
fields = {
{id = "phase", label = "Phase", value = "Starting"},
{id = "count", label = "Collected", value = 0},
},
})
hud:update({phase = "Harvesting", count = 12})
HUD updates are immutable data patches. Java renders the latest model; it never calls Lua per frame. Updates are rate-limited and coalesced.
HUD handles belong to a scope and disappear on close, stop, reload, or world policy transition. IDs are unique within a script, not globally.
Validation and results
Configuration diagnostics identify the field path, expected schema, and
offending value. HUD operations add HUD_ID_CONFLICT, HUD_CLOSED,
UPDATE_RATE_LIMIT, and MODEL_INVALID.
Presentation failures never retain gameplay resources or crash the script. Scripts may choose whether a missing HUD is fatal to their own policy.
GUI generation boundary
The generated module UI reads only the validated schema and values. Lua does not construct native widgets, hold screen references, or run rendering callbacks. Pack-provided labels and presets are data and cannot inject executable code.
Acceptance tasks
- Generate controls for every supported type and reject invalid schemas.
- Persist, reload, and explicitly migrate values.
- Handle a corrupt profile with visible defaults and diagnostics.
- Deliver changes on the script’s Lua lane.
- Coalesce rapid HUD updates without frame-driven Lua calls.
- Remove all HUD state when its scope closes.
- Isolate two scripts using the same local HUD ID.
- Prove screen changes and world unload do not leak handles.
- Fuzz labels, strings, colors, and pack data across the renderer boundary.
- Measure render and update cost under multiple passive scripts.