# Subway Surfers — Dance Pad Companion

Play **HTML5 Subway Surfers** (or similar endless runners) with the family USB dance pad. This folder is **not** a clone of the game — it is setup tooling plus documentation.

**Live page:** `subway/index.html` (linked from [Dance Pad Home](../index.php))

---

## How it works (Option 1 — recommended)

```text
USB dance pad
  → Windows / AntiMicroX maps each button → Arrow keys
  → Browser game (Poki, CrazyGames, etc.) reads keyboard only
```

Your custom games (DDR, Dash) read the **Gamepad API** directly. Third-party Subway ports almost always expect **keyboard arrows**, so the companion page helps you:

1. **Verify** the pad (same mapping as [Pad Tester](../tester.html)).
2. **Look up** which physical panel maps to Left / Right / Up / Down.
3. **Configure AntiMicroX** once per PC.
4. **Open** a listed HTML5 game in a new tab.

The companion page **cannot** send keys into Poki or other cross-origin iframes — browser security blocks that.

---

## Default control map

| Pad arrow | Subway-style action | AntiMicroX → key |
|-----------|---------------------|------------------|
| Left | Lane left | `ArrowLeft` |
| Right | Lane right | `ArrowRight` |
| Up | Jump | `ArrowUp` |
| Down | Roll / slide | `ArrowDown` |

Edit `config/controls.json` to change labels, keys, or game URLs.

**0b43:0001 profile (typical):**

| Panel | Button # |
|-------|----------|
| Left (red) | 15 |
| Down (yellow) | 14 |
| Up (yellow) | 12 |
| Right (red) | 13 |

Saved overrides from the tester (`localStorage` `dancepad-button-mapping-v1`) apply here too.

---

## Quick start

1. Open [subway/index.html](index.html).
2. Click **Enable dance pad** and step on all four arrows — cards should highlight.
3. Install [AntiMicroX](https://github.com/AntiMicroX/antimicrox/releases) (`Windows-AMD64.exe` on Windows 11).
4. **Load the ready-made profile:** [profiles/dancepad-subway-surfers.gamecontroller.amgp](profiles/dancepad-subway-surfers.gamecontroller.amgp) — in AntiMicroX use **File → Open**, then **File → Save profile** so it sticks. See [profiles/README.md](profiles/README.md).
5. Test in **Notepad** (left arrow on pad moves cursor left).
6. **Open game** (Poki or CrazyGames link on the companion page).
7. Click **inside** the game once, focus that tab, play.

**Optional:** Map manually instead of using the profile file (same bindings as the cheat sheet). Try keyboard-only in the game first; some ports accept gamepads without AntiMicroX (uncommon).

---

## Files in this folder

| File | Purpose |
|------|---------|
| `index.html` | Companion UI |
| `boot.js` | Cache-bust CSS + load `app.js` |
| `app.js` | Pad poll, live lane display, game links |
| `style.css` | Layout |
| `config/controls.json` | Lane labels, key codes, external game URLs |
| `profiles/*.gamecontroller.amgp` | AntiMicroX profile (import, don’t edit unless button #s differ) |
| `profiles/README.md` | Profile install steps |
| `SUBWAY.md` | This document |

### Shared code used

| Module | Role |
|--------|------|
| `../shared/gamepad.js` | Poll loop, pick dance pad |
| `../shared/pad-session.js` | User-gesture activation |
| `../shared/mapping-store.js` | Saved / profile button indices |
| `../shared/pad-controls.js` | `getHeldLanes()` |
| `../shared/pad-to-key.js` | Synthesize `KeyboardEvent` (bridge test only) |
| `../shared/config.js` | Load `controls.json` |

---

## Keyboard bridge test (same-origin only)

On the companion page, **Keyboard bridge test** emits `ArrowLeft` / etc. into a focusable box when:

- Bridge mode is checked, and  
- The test box is focused, and  
- You press pad arrows.

Use this to validate `shared/pad-to-key.js` before embedding a **self-hosted** runner under `dancepad/`. It does **not** affect external game tabs.

---

## Future: self-hosted clone (Option 2)

If you host an open-licensed HTML5 runner on the **same origin** (e.g. `subway/game/`):

- Import `pad-to-key.js` in the game page or parent frame (same origin).
- Poll pad with `gamepad.js` + `mapping-store.js`.
- Call `syncHeldLaneKeys(window, held, prevHeld, laneKeys)` — no AntiMicroX required on that machine.

Do not bundle Kiloo / Subway Surfers trademark art in this repo without a license. Prefer a generic endless runner or a properly licensed port.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| Pad dead until click | Click **Enable dance pad** or any key on the page first |
| Wrong lane in game | Re-check AntiMicroX bindings vs cheat sheet button # |
| Game ignores pad | Game may be keyboard-only — use AntiMicroX |
| Bridge test does nothing | Focus the test box; enable checkbox; external games still need AntiMicroX |
| AntiMicroX does not list pad | Try JoyToKey; confirm pad works in [tester](../tester.html) |
| Game lags / blocks embed | Open listed URL in new tab (default), not iframe |

---

## Cache busting

Bump `CACHE_BUST` in `../shared/version.js` and `?v=` in `subway/boot.js`, `subway/index.html`, and dynamic imports in `subway/app.js`.

---

## Legal / branding

- **Subway Surfers** is a trademark of Kiloo / SYBO. This project links to third-party hosts; it does not redistribute game assets.
- List only URLs you are comfortable maintaining; update `config/controls.json` if a host moves.