Practical guide

Replace the standard player interface

Provide an alternate player HUD while retaining the compiled recovery shell and explicit restoration path.

Procedure

Declare a provider for ui.surface.player-hud and a replace contribution that names the same provider.
Compose the complete alternate surface through its callback using registered widgets and queries.
Select the provider through ui.select-provider from a registered logical action.
Provide a visible action that selects worldforge.standard.player-hud again.
Test Safe Mode and standard restoration before treating the replacement as usable.

Example

function handle_action(action_id)
    if action_id == "ui.action.composition-proof.use-alternate" then
        ui.select_provider(
            "ui.surface.player-hud",
            "worldforge.composition-proof.player-hud"
        )
    elseif action_id == "ui.action.composition-proof.use-standard" then
        ui.select_provider(
            "ui.surface.player-hud",
            "worldforge.standard.player-hud"
        )
    end
end

Constraints and recovery

Provider selection changes presentation composition only.
The recovery shell remains compiled, non-replaceable, and available when all packages are disabled.
If replacement validation fails, the host retains the prior valid provider graph.

Replace the standard player interface

Procedure

Example

Constraints and recovery

Related symbols

Project references