Added setup guide and launch tools

docs/SETUP-GUIDE.md

@@ -0,0 +1,122 @@
+# Start the Arcade stack
+
+One launcher starts the needed processes, waits for services to respond, saves logs, and stops its children when you press Ctrl+C. It runs on Windows and Linux/Pi (and supports controller-only use on macOS).
+
+| Mode | Starts |
+| --- | --- |
+| `controller` | Room controller; optionally opens the browser operator |
+| `cabinet` | Managed game and, when enabled, its local Pi GPIO bridge |
+| `all` | Controller plus cabinet; useful for Windows simulation or a Pi hosting everything |
+
+For the usual installation, run **controller on the PC/Mac** and **cabinet on each Pi**. Keep the launcher terminal open. These scripts do not install boot services or software packages.
+
+## Files to deploy
+
+Keep the following directory structure, either by copying the repository or creating this deployment folder:
+
+```text
+ArcadeEscape/
+  Start-Arcade.ps1
+  start-arcade.sh
+  ArcadeEscape.exe                 # Windows, with any accompanying export files
+  ArcadeEscape.arm64               # Pi, with any accompanying export files
+  tools/
+    launch/                       # launch.py, examples, your launcher.ini
+    room_controller/              # server.py, operator.html, catalog.json
+    pi_gpio/                      # pi_gpio_bridge.py
+```
+
+Use the executable appropriate to that machine. You can instead point the INI at an executable elsewhere. **All relative INI paths resolve from the INI's folder**, regardless of where you launch the script. Review your existing export location: the project's presets may place builds one directory above the repository.
+
+## Windows controller
+
+Install Python 3 first. From the project/deployment root:
+
+```powershell
+Copy-Item tools/launch/controller.example.ini tools/launch/launcher.ini
+notepad tools/launch/launcher.ini
+```
+
+Fill in `operator_token` and `cabinet_tokens` with the same credentials already used by your cabinets. INI values here are **not surrounded by quotes**, except the JSON strings inside `cabinet_tokens`:
+
+```ini
+operator_token = YOUR_EXISTING_OPERATOR_TOKEN
+cabinet_tokens = {"cabinet_01":"YOUR_EXISTING_CABINET_TOKEN"}
+```
+
+Each token must be distinct and at least 16 characters. Existing `ARCADE_OPERATOR_TOKEN`, `ARCADE_CABINET_TOKENS`, and legacy `ARCADE_CABINET_TOKEN` environment variables take precedence. Reuse credentials; the launcher does not generate or rotate them.
+
+**Set `database` to your existing controller database** when upgrading. The example defaults to a new `tools/launch/state/arcade_room.sqlite3`; that would start a fresh controller history instead of using a database at the project root. To use a root-level database from the default INI location, set `database = ../../arcade_room.sqlite3`.
+
+Then validate and start:
+
+```powershell
+.\Start-Arcade.ps1 -Mode controller -Check
+.\Start-Arcade.ps1 -Mode controller -Browser
+```
+
+If PowerShell blocks script execution, the same launcher can be run directly without changing execution policy:
+
+```powershell
+py -3 tools/launch/launch.py controller --check
+py -3 tools/launch/launch.py controller --browser
+```
+
+## Pi cabinet
+
+Install the GPIO dependencies once, following the [GPIO guide](../pi_gpio/README.md). Configure the game's physical controls using the normal launcher before starting managed mode.
+
+```sh
+sudo apt update
+sudo apt install python3-gpiozero python3-lgpio
+cp tools/launch/pi.example.ini tools/launch/launcher.ini
+nano tools/launch/launcher.ini
+chmod +x ArcadeEscape.arm64
+```
+
+Set the game executable path, cabinet ID, bridge controller ID, and BCM pin allowlist. GPIO is enabled in this Pi example. Leave `url` and `token` blank to reuse the game's existing `user://arcade_network.cfg`, or supply them here:
+
+```ini
+[cabinet]
+executable = ../../ArcadeEscape.arm64
+id = cabinet_01
+url = http://CONTROLLER_IP:8766
+token = YOUR_EXISTING_CABINET_TOKEN
+gpio = true
+```
+
+Do not copy operator credentials to a cabinet-only Pi. URL/token environment variables still override these INI values. Unlike the launcher INI, Godot's own CFG file requires double quotes around string values.
+
+```sh
+bash start-arcade.sh cabinet --check
+bash start-arcade.sh cabinet
+```
+
+This starts the GPIO bridge first, waits for its local heartbeat endpoint, then launches the managed game with real GPIO enabled. The bridge uses **8765 locally**; the room URL uses **8766 on the controller**. `--check` validates files, settings, dependencies, and service port availability; it does not drive GPIO or prove wiring/permissions/network credentials work.
+
+For Pi gameplay/network testing without physical outputs, set `gpio = false`. For a Pi that also hosts the controller, add the `[controller]` settings from the controller example and use `all` mode; blank cabinet URL/token then use that local controller's values.
+
+## Windows all-in-one test
+
+Copy `windows-all.example.ini` to `launcher.ini`, fill in the controller tokens, and set the Windows executable path. Keep `gpio = false`:
+
+```powershell
+.\Start-Arcade.ps1 -Mode all -Check
+.\Start-Arcade.ps1 -Mode all -Browser
+```
+
+The game connects to the local controller using its cabinet ID's token. GPIO runs in simulation; Windows does not start the physical Pi bridge. To connect a Windows game to a remote controller instead, configure the cabinet section and use `-Mode cabinet`.
+
+## Stopping, logs, and configuration
+
+- **Ctrl+C** stops the stack started by this invocation. On the Pi, the bridge receives SIGTERM so its normal output cleanup runs.
+- **Escape/game exit** also stops services started by that same invocation. A controller launched separately on another machine stays running.
+- An unexpected child exit stops the other owned processes and returns an error; the launcher does not automatically restart a game or repeat hardware actions.
+- An occupied service port causes startup to stop. Existing processes are never killed or silently adopted.
+- Logs append to `tools/launch/logs/controller.log`, `gpio.log`, and `cabinet.log` by default. Check them for application errors after startup.
+- Keep the database and GPIO request ledger across restarts. Do not delete them to replay a reward.
+- Use `-Config C:\path\launcher.ini` on Windows or `--config /path/launcher.ini` on the Pi for another configuration file.
+- `launcher.ini`, `*.local.ini`, the default logs, and the default state folder are Git-ignored within `tools/launch/`. Keep other private configuration paths out of Git yourself.
+- Controller firewall rules, Godot exports, catalog generation, and GPIO wiring are still one-time deployment tasks; see the [room controller guide](../room_controller/README.md).
+
+For macOS controller use: `bash start-arcade.sh controller --browser`, with Python 3 and a configured controller INI.