Practical guide

Extend the player toolbar

Add deterministic logical actions to the standard toolbar without replacing its provider.

Procedure

1. Declare an extend contribution targeting ui.surface.player-hud/toolbar.
2. Register every logical action ID in the runtime catalog before a widget references it.
3. Compose buttons with visible labels, semantic labels, and unique focus order values.
4. Handle each action in the manifest-declared lifecycle action callback.
5. Reload and verify keyboard traversal and action diagnostics.

Example

function compose_toolbar()
    ui.begin_panel({
        id = "addon.toolbar", title = "Tools",
        anchor = "top-left", x = 350, y = 24,
        width = 260, height = 115, movable = true,
        semantic_label = "Addon tools", semantic_role = "toolbar"
    })
    ui.button("Restore Standard", "ui.action.composition-proof.use-standard",
              "Restore the standard player interface", 1)
    ui.end_panel()
end

Constraints and recovery

• An action is presentation intent until its handler submits a registered command or selects a provider.
• Duplicate action IDs or focus orders are rejected instead of being resolved by load order.
• Toolbar extensions cannot replace or hide the compiled recovery surface.

Related symbols

• ui.button
• ui.action
• lifecycle.handle-action
• ui.slot.player-hud.toolbar

Project references

• Game Development Phase 14
• Engine extension contract