Controls Customization: Default Button Set (Implementation)

## **⚠️ Problem:**
With no `PBTouchScreenControls` component the HUD renders all 8 buttons — JUMP, POINTER, E, F, 1–4 — regardless of what the scene binds. Most scenes bind none of F / 1–4, so first-session players tap dead controls and the arc occludes scene-authored UI; drives Playtime, dead-tap rate not yet instrumented.

## **🏁 Scope:**
Invert the default set: JUMP + POINTER + E on, F + 1–4 off until the scene opts in. Priority stack, slot geometry and "+" overflow from #2518 unchanged.

## **📝 Implementation Specs:**
`godot/src/ui/components/organisms/joypad/joypad.gd`

Default visibility — no `PBTouchScreenControls`, or action absent from `inputs`:

| Action | Button | Default |
|---|---|---|
| `ia_jump` | JUMP | on |
| `ia_pointer` | POINTER | on |
| `ia_primary` | E | on |
| `ia_secondary` | F | off |
| `ia_action_3` | 1 | off |
| `ia_action_4` | 2 | off |
| `ia_action_5` | 3 | off |
| `ia_action_6` | 4 | off |

- `_compute_visible_list()` seeds from the default-on set, not all of `PRIORITY_ORDER`. `PRIORITY_ORDER` still fixes order and cascade.
- Default-off action turns on when the scene lists it in `PBTouchScreenControls.inputs` with `hide=false`, **or** an active `PointerEvents` in the loaded scene declares it.
- `hide=true` wins over everything — default-on and `main_action` included (#2518).
- `main_action` on a default-off action promotes it to the big slot and shows it.
- Bind added/removed mid-session re-runs `_layout()`. No reload, no scene change.
- `_assign_slots` untouched: index 0 → big, next ≤4 → arc, "+" only above 5 visible.
- Steady state at 3 visible: big JUMP + POINTER + E on the arc, no "+", no overflow column.

Design: [proposal comment](https://github.com/decentraland/godot-explorer/issues/2708#issuecomment-5540596417) — "main button + 2 secondary; unused ones hidden by default".

## **📝 Deliverables:**
- [ ] JUMP, POINTER, E visible with no `PBTouchScreenControls` present
- [ ] F, 1–4 hidden until scene opts in via `inputs` or `PointerEvents`
- [ ] Opt-in / opt-out mid-session relayouts without reload
- [ ] `hide=true` still hides any default-on button, JUMP included
- [ ] `main_action` on a default-off action promotes it to big slot
- [ ] Test `_compute_visible_list()` — one case per row above
- [ ] Regression: #2518 cascade, arc placement, "+" above 5 visible
- [ ] Segment event on scene enter carrying visible action set + taps per action
- [x] File creator-docs issue for the default-visibility contract — #2843

## Notes
`TouchScreenControls` SDK helpers expose `hide(actions)` / `hideAll()` / `showAll()`, no `show(actions)`. `showAll()` is documented as "clears the button hide list" — under the inverted default that no longer shows 1–4. Settle with the SDK team: re-spec `showAll()` to show all 8, or add `show(actions)`. Tracked in #2843.

## Metrics
Target: **Playtime**. Fewer dead buttons on first scene → fewer failed taps, less HUD occlusion of scene UI. Baseline dead-tap rate unmeasured; the Segment deliverable establishes it (visible action set on scene enter, taps per action, bound vs unbound). Set direction + size after 1 sprint of data.

## **🔗 References:**
- [decentraland/godot-explorer#2518](https://github.com/decentraland/godot-explorer/issues/2518) — priority stack, cascade, `main_action`, "+" overflow this builds on, unchanged
- [decentraland/godot-explorer#2843](https://github.com/decentraland/godot-explorer/issues/2843) — creator-docs update this blocks; lists every passage in `touch-screen-controls.md` it invalidates
- [decentraland/godot-explorer#2635](https://github.com/decentraland/godot-explorer/issues/2635) — HUD Iteration #2, consumes this default set
- [decentraland/godot-explorer#2265](https://github.com/decentraland/godot-explorer/issues/2265) — adaptive controls design, source of button-swap rules
- [decentraland/godot-explorer#2183](https://github.com/decentraland/godot-explorer/issues/2183) — open design review on Settings > Gameplay > Gamepad, same surface

No prior art in unity-explorer (searched `action buttons`, `gamepad`, 2026-08-14) — mobile-only surface. Creator-facing contract lives in `creator/sdk7/interactivity/touch-screen-controls.md`.

**Supersedes the review scope of this issue.** Audit, per-button call, stack order and #2518 regression check closed 2026-09-04; body replaced with the implementation spec.