room_glitch/games/launcher/README.md

# Arcade launcher and cabinet controls

For central staff operation, see the separate [Arcade room controller guide](../../tools/room_controller/README.md). Open the controller URL in a browser for the multi-cabinet operator on Mac/iPad, or use `-- --operator` for Cabinet 01 quick controls. Run `-- --managed-cabinet --cabinet=cabinet_01 --gpio=real` on the appropriate Pi. These modes bypass the standalone launcher; managed mode uses central scenario mappings instead of local rewards.

For physical Raspberry Pi outputs, follow [the GPIO setup and LED test guide](../../tools/pi_gpio/README.md). The launcher forwards matching Hardware Scenario events; its default scenario connects Pac-Man's win to cabinet 01's GPIO17 coin-release pulse. Start the local helper and use `--gpio=real` to enable electrical outputs.

Open `res://games/launcher/ArcadeLauncher.tscn` and press F6. It lists all seven games with their icons. Move the joystick up/down and press Start to open a game's attract screen; press Start again to begin. Select returns to the list and unloads the game, including its sound players. Mouse selection and double-click also work.

This is a standalone arcade frontend, separate from the room/scenario runtime. To boot directly into it in an export, use this scene as **Project Settings > Application > Run > Main Scene**.

## Map your cabinet

The exported game opens **Control Setup** automatically until a local profile is saved. You can reopen it from the last entry in the game list, or press **F1** on a keyboard as a recovery shortcut. No Godot editor is needed on the Pi.

1. Connect both controllers before beginning. Press any controller button / Enter, or click **Begin Setup**.
2. Follow the prompts for player-one Start, Select, joystick directions and the three game buttons. Release each button or center the joystick before the next prompt. Small axis drift is ignored.
3. For Robotron firing, use four face buttons or move the second joystick in each requested direction. Player-one movement is automatically reused for Robotron movement.
4. Review the list and test inputs: the monitor shows which controller/input was detected and the actions assigned to it. An unassigned player-two button should show no actions. Move the trackball to confirm mouse motion is arriving.
5. Press the learned **Start** button or click **Save Controls**. Learned Select cancels from review. The Cancel button cancels at any point without altering the previous profile. **Escape quits the entire application**, including from setup; unfinished changes are not saved.

Saving replaces the default bindings for the configured actions instead of adding more overlapping bindings. The saved controls load for standalone game scenes and the room runtime as well as the launcher. Project Settings Input Map remains the fallback until a local profile exists; afterwards, the local profile takes precedence.

Profiles are saved outside the exported game as `user://arcade_controls.cfg`, usually `~/.local/share/godot/app_userdata/ArcadeEscape/arcade_controls.cfg` on Linux and `%APPDATA%/Godot/app_userdata/ArcadeEscape/arcade_controls.cfg` on Windows. They survive replacing the game export. Configure each machine independently; do not copy Windows bindings onto the Pi. If saving fails, the screen reports it and keeps the previous profile.

## Two controllers

The shipped default bindings use All Devices, which lets either gamepad activate the same action. Setup records each joypad's identity and specific input, then binds only that device. Different encoders are resolved by name/GUID when device numbers change. A disconnected controller's inputs are disabled rather than assigned to another controller.

Identical encoders can have the same name/GUID and no distinguishable serial identity through Godot. These are separated by their instance order, with a visible warning to check player one after reconnecting. Keep them in consistent USB ports and rerun setup if the players swap. If the count of identical encoders changes, affected bindings are disabled until all are connected again or setup is repeated. Changing connections during setup restarts the wizard.

Keyboard-mode encoders are supported, but two encoders emitting the same keyboard key cannot be distinguished by this setup. Give their players different key codes in the encoder configuration, or use gamepad mode. F1 and Escape are reserved for setup and quitting and cannot be learned as gameplay buttons.

## Action reference (project defaults)

| Action | Cabinet use | Keyboard default |
| --- | --- | --- |
| `arcade_up/down/left/right` | Joystick, menu and most games | Arrow keys |
| `arcade_start` | Start | Enter |
| `arcade_menu` | Select: leave game | Use your learned Select button; Escape quits the application |
| `arcade_action_1` | Fire; Missile Command left battery | Space / left mouse |
| `arcade_action_2` | Tempest Superzapper; Missile Command center battery | Z / middle mouse |
| `arcade_action_3` | Missile Command right battery | X / right mouse |
| `robotron_move_left/right/up/down` | Bind the same movement joystick | A / D / W / S |
| `robotron_fire_left/right/up/down` | Four face buttons arranged directionally | Arrow keys |
| `arcade_rotate_left/right` | Optional Tempest spinner pulses | Mouse wheel down/up |

The default gamepad bindings remain in Project Settings. Use Control Setup to learn the actual cabinet buttons rather than assuming printed button numbers match the operating system. Four face buttons cover Robotron, including diagonal shots by holding two buttons; the second joystick can also handle firing. The remaining games need at most three face buttons.

The trackball must report as a mouse. The launcher enables Missile Command's **Relative Mouse Aim** and captures the pointer for Missile Command and Tempest, so trackball travel continues beyond desktop edges. Select releases the pointer when returning to the menu. Tempest accepts horizontal mouse motion with **Trackball Pixels Per Lane** sensitivity. Continuous mouse motion is handled as motion, not a button action.

## Raspberry Pi 4/5

Input Map settings ship with the project/export. Use Linux ARM64 for a 64-bit Raspberry Pi OS installation and retain the Compatibility renderer. There are no Windows-only input APIs in these controls. Keyboard/mouse USB encoders and recognized gamepads use the same actions, but a generic encoder may report different button/axis mappings on Linux: test the actual hardware on the Pi before final deployment. This change does not add a GPIO input driver.

Godot references: [Linux export](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_linux.html), [controller mappings](https://docs.godotengine.org/en/stable/tutorials/inputs/controllers_gamepads_joysticks.html).

## Quick check

1. Navigate all seven entries with the joystick, open each with Start, begin play, and return with Select.
2. Test Missile Command's three batteries independently with the trackball; test Tempest fire and Superzapper separately.
3. Test Robotron movement independently of all four fire buttons and their diagonals.
4. Save setup, restart the game, and verify the learned bindings persist and unassigned player-two buttons have no effect.
5. Repeat on the Pi after export and reconnecting the USB encoders. Check player-one identity if the encoders are identical.

Automated checks: run `tests/launcher/check_launcher.gd` and `tests/launcher/check_controls.gd` using Godot's headless script runner. The latter uses a temporary profile in `.godot`, not your real saved controls.