UI

Creating UI

create_ui_canvas

Create a screen-space UI canvas at runtime.

EntityHandle create_ui_canvas(ScriptContext* ctx, const char* name, int sort_order);

Parameter	Type	Description
`name`	const char*	Canvas entity name
`sort_order`	int	Render order (higher = on top)

Returns the canvas entity handle, or NULL_ENTITY_HANDLE on failure.

create_ui_element

Create a UI element as a child of a canvas or another UI element.

EntityHandle create_ui_element(ScriptContext* ctx, EntityHandle parent,
                               const char* name, const char* element_type);

Parameter	Type	Description
`parent`	EntityHandle	Canvas or UI element handle
`name`	const char*	Element entity name
`element_type`	const char*	Type string (see below)

Element types: "UIText", "UIButton", "UISlider", "UIToggle", "UIProgressBar", "UIPanel", "UIImage"

destroy_ui_element

Remove a UI element from the hierarchy.

bool destroy_ui_element(ScriptContext* ctx, EntityHandle element);

Text

get_ui_text

const char* get_ui_text(ScriptContext* ctx, EntityHandle element);

Returns the text content (thread-local buffer, valid until next call), or nullptr if not found.

set_ui_text

bool set_ui_text(ScriptContext* ctx, EntityHandle element, const char* text);

Buttons

was_ui_button_clicked

Check if a button was clicked this frame. Requires UIInteractionSystem to be running (play mode).

bool was_ui_button_clicked(ScriptContext* ctx, EntityHandle button);

Sliders

get_ui_slider_value

bool get_ui_slider_value(ScriptContext* ctx, EntityHandle slider, float* out_value);

set_ui_slider_value

Value is clamped to the slider's min/max range.

bool set_ui_slider_value(ScriptContext* ctx, EntityHandle slider, float value);

Toggles

get_ui_toggle_state

bool get_ui_toggle_state(ScriptContext* ctx, EntityHandle toggle, bool* out_is_on);

set_ui_toggle_state

bool set_ui_toggle_state(ScriptContext* ctx, EntityHandle toggle, bool is_on);

Progress Bars

get_ui_fill_amount

bool get_ui_fill_amount(ScriptContext* ctx, EntityHandle element, float* out_amount);

set_ui_fill_amount

bool set_ui_fill_amount(ScriptContext* ctx, EntityHandle element, float amount);

Amount is clamped to 0.0 - 1.0.

Visibility

set_ui_visible

Show or hide a UI element. Hidden elements don't render.

bool set_ui_visible(ScriptContext* ctx, EntityHandle element, bool visible);

Example: HUD with Health Bar

static EntityHandle canvas;
static EntityHandle health_bar;
static EntityHandle score_text;
static int score = 0;

void OnStart(ScriptContext* ctx) {
    canvas = ctx->create_ui_canvas(ctx, "HUD", 0);

    health_bar = ctx->create_ui_element(ctx, canvas,
        "HealthBar", "UIProgressBar");
    score_text = ctx->create_ui_element(ctx, canvas,
        "ScoreText", "UIText");

    ctx->set_ui_text(ctx, score_text, "Score: 0");
    ctx->set_ui_fill_amount(ctx, health_bar, 1.0f);
}

void OnUpdate(ScriptContext* ctx) {
    // Update score display
    char buf[64];
    snprintf(buf, sizeof(buf), "Score: %d", score);
    ctx->set_ui_text(ctx, score_text, buf);
}

static EntityHandle pause_menu;
static bool paused = false;

void OnStart(ScriptContext* ctx) {
    EntityHandle canvas = ctx->create_ui_canvas(ctx, "PauseMenu", 10);
    pause_menu = ctx->create_ui_element(ctx, canvas, "Panel", "UIPanel");

    EntityHandle resume_btn = ctx->create_ui_element(ctx, pause_menu,
        "ResumeBtn", "UIButton");
    EntityHandle quit_btn = ctx->create_ui_element(ctx, pause_menu,
        "QuitBtn", "UIButton");

    ctx->set_ui_visible(ctx, pause_menu, false);
}

void OnUpdate(ScriptContext* ctx) {
    if (ctx->is_key_pressed(ctx, 256)) { // Escape
        paused = !paused;
        ctx->set_ui_visible(ctx, pause_menu, paused);
        ctx->set_cursor_captured(ctx, !paused);
    }

    if (paused) {
        EntityHandle resume = ctx->find_entity_by_name(ctx, "ResumeBtn");
        if (ctx->was_ui_button_clicked(ctx, resume)) {
            paused = false;
            ctx->set_ui_visible(ctx, pause_menu, false);
            ctx->set_cursor_captured(ctx, true);
        }
    }
}

UI