lifecycle · lifecycle

handle_action

Receives one activated logical action and an optional selected list row ID.

handle_action(action_id, row_id?)

Stable ID: lifecycle.handle-action
Owner: app.ScriptPackageHost
Authority: host_lifecycle
Timing: immediate
Availability: Phase 14H standard interface
Side effects: May submit documented commands through the existing command API.
Determinism: Delivered in host activation order with a fresh callback budget.
Introduced: 1.0.0

Usage

Declare and implement lifecycle.handle-action through the package manifest lifecycle table. List activations provide the selected stable row ID as the optional second argument; button handlers remain compatible with a single action argument.

Parameters

action_id: stable ID emitted by a composed UI control.
row_id: optional stable row identity emitted by ui.list.

Returns

No engine-owned gameplay value. Success or a Lua error determines whether the lifecycle transition commits.

Cost

Constant-size contract lookup or bounded retained-record access.

Fields

This symbol has no fields.

Errors

error.invalid-action

Examples

function handle_action(action_id, row_id)
    if action_id == "ui.action.work.select" then
        selected_work_row_id = row_id
    end
end

API history

1.0.0: Runtime contract published from the complete Phase 14 registry.
1.19.0: Added the optional stable list row identity.