From ecfca19f116cddd7cb05a98041d10cf844d3ed26 Mon Sep 17 00:00:00 2001 From: Andrew Quenehen Date: Thu, 6 Aug 2026 08:36:43 -0300 Subject: [PATCH] Consolidate Switch docs into three production guides. Remove internal development and hardware-evidence docs, drop issue references, and update cross-links and doc gates. --- .gitignore | 2 +- README.md | 15 +- docs/switch-build.md | 16 +- docs/switch-development.md | 536 ---------------------------- docs/switch-hardware-evidence.md | 187 ---------- docs/switch-install.md | 23 +- docs/switch-transfer.md | 9 +- docs/updater.md | 3 +- src/core/GamepadMap.lua | 2 +- test/switch-nro-ota.spec.test.js | 6 +- tests/switch_ci_workflows_test.lua | 9 +- tests/switch_transfer_docs_test.lua | 37 +- tools/switch-probe/README.md | 8 +- 13 files changed, 54 insertions(+), 799 deletions(-) delete mode 100644 docs/switch-development.md delete mode 100644 docs/switch-hardware-evidence.md diff --git a/.gitignore b/.gitignore index a79a8483..8f519c51 100644 --- a/.gitignore +++ b/.gitignore @@ -31,7 +31,7 @@ mobile/ios/love-src/ mobile/ios/cache/ mobile/ios/build/ -# love-nx vendor binaries (fetch per docs/switch-development.md; also covered by .*) +# love-nx vendor binaries (fetch per docs/switch-build.md; also covered by .*) .bazinga/love-nx/ # Final packaged build artifacts (mac/win/web/android/ios/switch) — see scripts/build.sh diff --git a/README.md b/README.md index d1a84c14..878d612e 100644 --- a/README.md +++ b/README.md @@ -231,11 +231,9 @@ Install steps, controls, and troubleshooting live in ## Nintendo Switch -Releases ship an SD-ready `gen1recomp-*-switch.zip` (issue -[#531](https://github.com/bryanthaboi/gen1recomp/issues/531)). Runtime target -is pinned [love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. -Requires a console that can run Switch homebrew. Hardware evidence: **OLED** -(author) and **V1 / Erista** boot (community). +Releases ship an SD-ready `gen1recomp-*-switch.zip`. Runtime target is pinned +[love-nx](https://github.com/retronx-team/love-nx) `11.5-nx1`. Requires a +console that can run Switch homebrew. - Players: [docs/switch-install.md](docs/switch-install.md) — download the zip, extract at the microSD root (install or update), title-override @@ -243,12 +241,7 @@ Requires a console that can run Switch homebrew. Hardware evidence: **OLED** - Builders: [docs/switch-build.md](docs/switch-build.md) — `--fetch` / `--loose` / `--fused`, toolchain, Docker fallback, and **CI vs release** (path-gated ubuntu selftest, canonical fused PR artifact, release hard-fail). - -Limitations, Dusklight-derived method, and how we tested: -[docs/switch-development.md](docs/switch-development.md) and -[docs/switch-hardware-evidence.md](docs/switch-hardware-evidence.md). Community -help — especially HOS / love-nx packaging and broader hardware coverage — is -welcome. +- File transfer (MTP / SD / FTP): [docs/switch-transfer.md](docs/switch-transfer.md). ## Modding diff --git a/docs/switch-build.md b/docs/switch-build.md index 0f1cd3be..5367513c 100644 --- a/docs/switch-build.md +++ b/docs/switch-build.md @@ -4,13 +4,10 @@ Want to play a release build instead? Download the SD-ready zip and extract it at your microSD root — see [switch-install.md](switch-install.md). This guide is for contributors who build Gen1Recomp for Switch from source. -Hardware evidence, MTP operator loops, and deeper notes live in -[switch-development.md](switch-development.md). -> Releases ship `gen1recomp-*-switch.zip` (SD tree under `switch/gen1recomp/`; -> issue [#531](https://github.com/bryanthaboi/gen1recomp/issues/531)). Hardware -> evidence: **OLED** (author) and **V1 boot** (community). See -> [switch-development.md](switch-development.md) for known limitations. +> Releases ship `gen1recomp-*-switch.zip` (SD tree under `switch/gen1recomp/`). +> Runtime target is pinned [love-nx](https://github.com/retronx-team/love-nx) +> `11.5-nx1`. Player install and limitations: [switch-install.md](switch-install.md). --- @@ -42,7 +39,8 @@ Fused game builds can also use Docker when native `nacptool`/`elf2nro` are absen ### Native OTA launcher (included in `--fused`) -In-console OTA uses a **separate DEVKITPRO NRO** (not LÖVE). Source: +In-console OTA uses a **separate DEVKITPRO NRO** (not LÖVE). The LÖVE +self-updater (`Check.lua`) is disabled on NX. Source: `native/switch-ota-launcher/`. Host protocol tests (no toolchain): ```sh @@ -247,6 +245,4 @@ These scripts and this guide do **not**: Player install steps: [switch-install.md](switch-install.md). Manual transfer (MTP / SD / FTP, macOS / Linux / Windows): -[switch-transfer.md](switch-transfer.md). -Hardware depth and evidence: [switch-development.md](switch-development.md), -[switch-hardware-evidence.md](switch-hardware-evidence.md). +[switch-transfer.md](switch-transfer.md). diff --git a/docs/switch-development.md b/docs/switch-development.md deleted file mode 100644 index e253f5b1..00000000 --- a/docs/switch-development.md +++ /dev/null @@ -1,536 +0,0 @@ -# Nintendo Switch development (love-nx) - -> Fused NRO support for issue [#531](https://github.com/bryanthaboi/gen1recomp/issues/531). -> Releases ship `gen1recomp-*-switch.zip` (SD-ready tree). Console copy is -> extract/merge at microSD root; title override required. See -> [Known limitations](#known-limitations-read-before-reviewing). - -**Canonical install / build / transfer docs** (start here unless you need hardware depth): - -- Players → [switch-install.md](switch-install.md) -- Builders → [switch-build.md](switch-build.md) (`scripts/build_switch.sh --fetch` downloads the pinned love-nx pair) -- Transfer (MTP / SD / FTP on macOS, Linux, Windows) → [switch-transfer.md](switch-transfer.md) - -This document covers what landed, known limitations, how hardware was tested, -vendor layout, build/deploy, and the contributor transfer loop (detail lives in -the transfer runbook). - -## Acknowledgments - -- **Port / love-nx packaging:** [andrewqsantos](https://github.com/andrewqsantos) -- **Community hardware testing** (Switch V1 / Erista boot): [booshankles](https://github.com/booshankles) -- **Method guidance:** [Dusklight Switch port](https://github.com/HayatoG/dusklight/tree/main/platforms/switch) / love-nx -- **Upstream project:** [bryanthaboi](https://github.com/bryanthaboi) / Gen1Recomp - -## Status - -| Area | State | -| ---- | ----- | -| Feature | **Available** — playable fused NRO path (issue #531) | -| Runtime | Pinned love-nx **`11.5-nx1`** | -| Product artifact | Releases: SD-ready `gen1recomp-*-switch.zip`; local/PR: fused `.nro`; loose `nro`+`game.love` for iteration | -| Hardware | **OLED** validated (author, title override); **V1 / Erista** boot confirmed (community). Lite, docked soak, and Pro Controller matrices welcome | -| Deploy / install | Releases publish SD-ready zip; **extract/merge at microSD root** (MTP / SD / FTP — [switch-transfer.md](switch-transfer.md)); no `nxlink` path yet | -| Contributor transfer | Documented for **macOS, Linux, and Windows**; OpenMTP on Mac is one example, not the only contract | -| Network features on NX | LÖVE self-update / remote mod download **disabled** (`networkValidated == false`). In-console OTA is the **native OTA launcher** only (see below) | -| Community help | Welcome — especially HOS / love-nx packaging and broader hardware coverage | - -### What landed - -- Detect `NX` via `src/core/Platform.lua` without reusing Android flags -- Writable ROM inbox under `getSaveDirectory()/imports/` + per-tab “Scan again” (SHA-1 match for the open game) -- Joy-Con / gamepad mapping shared by launcher and gameplay (Nintendo A/B UX on NX) -- Launcher L/R tab switch; gameplay L/R game-speed cycle; Select+face display chords -- Focus loss / joystick reconnect recovery; opt-in `switch-debug.txt` diagnostics -- Loose assemble + fused NRO build scripts (`scripts/build_switch.sh`, `scripts/switch/*`) -- Payload gates so ROM / generated cache / saves never enter `game.love` -- Community mod zip inbox at `imports/mods/` (rescan installs; FIND MODS stays network-gated) -- Raw `.sav` inbox at `imports/saves/{red,blue,yellow}/` (**Import save** rescan) + export pull path `exports/{red,blue,yellow}/` (MTP hint; no openURL) -- Hardware evidence for Phase 0 probe, ROM import, naming A/B, save/suspend, fused NRO — see `docs/switch-hardware-evidence.md` -- Path-gated CI selftest + canonical fused PR artifact; release Switch hard-fail -- Save editor pad/touch input (virtual cursor, A click, B close) — see `tools/save-editor/README.md` -- Dynamic display size on NX only: handheld **1280×720**, docked/TV **1920×1080** (`src/core/NxDisplay.lua` + resizable conf so love-nx SDL can follow dock/undock at runtime) - -### Known gaps / welcome contributions - -- Docked vs handheld soak (≥30 min) and Lite coverage — resolution switch is implemented; long soak still welcome -- Switch Lite and fuller Pro Controller / third-party pad matrices -- Applet Mode remains unsupported by design (title override required) -- `nxlink` / netloader contrib fast-loop (deferred — see [switch-transfer.md](switch-transfer.md)) -- **Native OTA launcher:** in-console updates use a DEVKITPRO - **native OTA launcher** (libnx + switch-curl) before the LÖVE game NRO — - **not** the LÖVE self-updater (`src/update/Check.lua`). Contract: - `src/update/SwitchOta.lua`; packaging gate: - `scripts/switch/ota_launcher.manifest`. The download asset is the same - `gen1recomp-*-switch.zip` as install. UI stays quiet unless an update - needs confirm. Player-facing flow: [switch-install.md](switch-install.md) - § Updating. - -Transfer runbooks for Linux/Windows (and SD/FTP alternatives) are in -[switch-transfer.md](switch-transfer.md). Community mod zip install OLED smoke -is **pass** — see NXMOD-12 in [switch-hardware-evidence.md](switch-hardware-evidence.md). - -## Design references (Dusklight) - -This work borrowed method — not the native stack — from the [Dusklight Switch port](https://github.com/HayatoG/dusklight/tree/main/platforms/switch), especially [`LESSONS_AND_REUSE.md`](https://github.com/HayatoG/dusklight/blob/main/platforms/switch/LESSONS_AND_REUSE.md): - -| Dusklight lesson | How Gen1Recomp applied it | -| ---------------- | ------------------------- | -| Emulators hide Tegra failures | Gate milestones on **real OLED hardware**, not Ryujinx/Yuzu alone | -| Prove the lower layer first | `tools/switch-probe` before full launcher | -| Know which binary ran | Embedded `build-info.json` (commit / love-nx tag) | -| Cap continuous logs | Opt-in diagnostics, ≤1 Hz flush; Lua error log rotation | -| Crash symbolization needs the exact ELF | Keep pinned `love.elf` with the NRO under test | -| Full memory matters | Title override; Applet Mode is not the validation path | -| Do not treat SD FS like desktop POSIX | Lua stays on `love.filesystem`; inbox + MTP for user files | -| Isolate platform code | Capability module instead of Android flag overload | -| NVK / WSI / `audren` stacks | **Not** copied — love-nx already supplies video/audio/input/FS | - -The packaging goal matches Dusklight’s **single self-contained `.nro`**; contributor transfer stays multi-host (not Mac-only). - -## Known limitations (read before reviewing) - -1. **Transfer is manual and multi-method.** Runtime only needs files under the LÖVE save directory / NRO install folder. Use MTP, direct SD, or FTP per [switch-transfer.md](switch-transfer.md). macOS + OpenMTP is a documented example for OLED evidence — not “Switch requires a Mac.” -2. **Deploy is manual.** There is no automated push to the console and no `nxlink` path yet. Operators build locally, transfer files, then title-override launch. -3. **Hardware coverage.** Author P0/P1 pass rows were recorded on one Switch OLED; Switch V1 boot was confirmed independently. Treat Lite, docked soak, and other hosts as unknown until someone re-runs the checklist. -4. **No ROM/save/mod zip bytes in git.** Legal dumps and third-party mods stay on the console (or local untracked folders). -5. **AppleDouble sidecars** (`._*`) from some MTP clients can break zip/ROM/`.sav` scans — the launcher skips hidden `.*` names (including `._*.sav`); still prefer clean copies. - -## How we tested - -| Layer | What | Where | -| ----- | ---- | ----- | -| Unit / headless | Platform NX flags, RomImporter inbox, dual-path input, mod zip inbox, save `.sav` inbox, display chords, payload/self-tests | `tests/*`, `scripts/test.sh` | -| Switch CI / packaging | Path-gated offline selftest (`selftest_build_switch.sh`, `verify_payload.sh --self-test`, `switch_ci_workflows_test.lua`); canonical fused PR artifact | `.github/workflows/ci.yml`, [switch-build.md](switch-build.md) § CI and release | -| Probe on hardware | `getOS()==NX`, 1280×720, save path, Joy-Con events | `tools/switch-probe` → OLED | -| Integration on hardware | MTP inbox ROM import, Play Red/Blue, naming A/B, quit/reopen save, suspend×10, reboot, fused NRO alone + NRO-only update | `docs/switch-hardware-evidence.md` | -| Community hardware | Switch V1 / Erista boot with prebuilt NRO | [booshankles](https://github.com/booshankles) — see evidence log | -| Known gaps | Docked soak, ≥30 min long-play, Lite, automated/`nxlink` deploy | Matrix deferred / absent rows | - -Operator evidence must stay in `docs/switch-hardware-evidence.md`. **Do not invent passes** for hardware not run. - -## love-nx 11.5-nx1 (pinned) - -**Tag:** [11.5-nx1](https://github.com/retronx-team/love-nx/releases/tag/11.5-nx1) - -**Local layout (not committed):** - -```text -.bazinga/love-nx/11.5-nx1/ -├── love.nro # homebrew launcher binary (loose mode: copied to gen1recomp.nro) -└── love.elf # required for fused NRO builds (devkitPro nacptool/elf2nro) -``` - -**Manifest:** `scripts/switch/love-nx-11.5-nx1.sha256` lists expected artifact names and SHA-256 checksums. Checksums are filled when binaries are fetched (`TBD_*` placeholders until then). - -### Fetch instructions - -Preferred (automated checksum verify): - -```bash -scripts/build_switch.sh --fetch -``` - -That downloads pinned `love.nro` + `love.elf` into `.bazinga/love-nx/11.5-nx1/` -and checks them against `scripts/switch/love-nx-11.5-nx1.sha256`. See -[switch-build.md](switch-build.md) for the full mode glossary. - -Manual fallback: - -1. Open the [11.5-nx1 release](https://github.com/retronx-team/love-nx/releases/tag/11.5-nx1) and download `love.nro` and `love.elf`. -2. Create the directory: `mkdir -p .bazinga/love-nx/11.5-nx1` -3. Move both files into that directory. -4. Confirm checksums match the manifest: - - ```bash - shasum -a 256 .bazinga/love-nx/11.5-nx1/love.nro \ - .bazinga/love-nx/11.5-nx1/love.elf - ``` - -**Never commit** love-nx binaries, ROM dumps, or generated cache into git. The repo `.gitignore` excludes `.bazinga/` (vendor cache) and `/dist/` (build output). - -## Loose-mode dist layout - -Development builds place `gen1recomp.nro` and `game.love` side by side: - -```text -dist/switch/loose/ -├── gen1recomp.nro -└── game.love -``` - -Assemble with: - -```bash -scripts/build_switch.sh --loose -``` - -(See `scripts/switch/assemble_loose.sh` for the underlying copy + checksum step.) - -## Transfer & deploy (current contributor loop) - -Detail for **macOS / Linux / Windows** and **MTP / SD / FTP** lives in -[switch-transfer.md](switch-transfer.md). Summary: - -| Layer | Intent | -| ----- | ------ | -| **Runtime / players** | Extract the release zip at microSD root (`switch/gen1recomp/`) and land ROMs/mods under the save-dir inboxes. The game does not hard-depend on OpenMTP or macOS. | -| **Contributor loop** | Manual copy via MTP (DBI responder), direct SD (Hekate UMS / reader), or FTP. Fully manual — no CI deploy, no `nxlink` yet. | - -The Mac + OpenMTP steps that remain below are the **OLED evidence reproduction** path; prefer the transfer runbook for day-to-day contrib on other hosts. - -**Still avoided for routine evidence** (keeps SD handling honest): - -- Treating `nxlink` / netloader as the release deploy story (deferred) -- DBI `MicroSD install` / `NAND install` / NSP-style virtual folders for the `.love`/`.nro` pair - -If MTP fails: check cable, USB port, DBI state, and that only one MTP client holds the device — then retry or switch to SD/FTP. Do not silently rewrite evidence using an untested path and claim parity with recorded SHA-256 round-trips. - -### Manual deploy checklist (today) - -1. Build on the contributor host (`scripts/build_switch.sh --loose` or fused). -2. Close Gen1Recomp on the Switch; open DBI → `Run MTP responder`. -3. Copy artifacts with your MTP client into `1: SD Card/switch/gen1recomp/` (and ROMs/mods into the save-dir inboxes when needed). -4. Wait for the transfer queue; refresh; optionally round-trip SHA-256 on first artifacts of a type. -5. Exit MTP; launch via **title override** (hold **R** on a title → hbmenu, not Applet Mode). - -## OpenMTP + DBI transfer (loose build, Mac evidence example) - -Full multi-OS / multi-method steps: [switch-transfer.md](switch-transfer.md). -The numbered Mac loop below reproduces the OLED evidence path. - -### On the Switch - -1. Close Gen1Recomp if it is running. -2. Open **DBI** from hbmenu. -3. Select **`Run MTP responder`** (DBI documents `X` on the main screen). -4. Keep DBI on that screen for the entire transfer. -5. Connect the Switch to the Mac with a USB-C data cable. - -### On the Mac - -1. Close any other MTP clients. -2. Open **OpenMTP** and select the DBI device. -3. In the remote pane, open **`1: SD Card`**. -4. Navigate to **`switch/`** and create **`gen1recomp/`** if needed. -5. Enter **`1: SD Card/switch/gen1recomp/`**. -6. Drag from the local pane: - - ```text - dist/switch/loose/gen1recomp.nro - dist/switch/loose/game.love - ``` - -7. Wait for the OpenMTP queue to finish completely. -8. Refresh the remote listing and confirm file sizes match the local files. -9. On the Switch, exit MTP responder normally in DBI before launching the app. - -Expected layout on SD: - -```text -1: SD Card/ -└── switch/ - └── gen1recomp/ - ├── gen1recomp.nro - └── game.love -``` - -## Round-trip SHA-256 verification - -For the **first deploy** of each artifact type (loose pair, later fused NRO), verify MTP integrity: - -1. **Before send** — record local hashes: - - ```bash - shasum -a 256 dist/switch/loose/gen1recomp.nro \ - dist/switch/loose/game.love - ``` - -2. **After send** — in OpenMTP, copy the same files from `1: SD Card/switch/gen1recomp/` back to an empty local folder, e.g. `dist/switch/mtp-roundtrip/`. - -3. **Compare** round-trip hashes: - - ```bash - shasum -a 256 dist/switch/mtp-roundtrip/gen1recomp.nro \ - dist/switch/mtp-roundtrip/game.love - ``` - -4. Local pre-send and round-trip hashes **must match**. Record results in the test report template below. - -Repeat whenever a cable glitch or interrupted transfer is suspected. - -## Title override launch (full memory) - -Applet Mode is **not** the primary validation path. Use **title override** so hbmenu runs with full memory: - -1. Confirm the OpenMTP transfer queue finished. -2. Exit MTP responder in DBI; disconnect USB if desired. -3. Hold **`R`** while launching any legitimately installed title. -4. Keep holding until **hbmenu** appears. -5. Confirm hbmenu does **not** show **Applet Mode**. -6. Launch **`gen1recomp`** (or the probe NRO during Phase 0). - -Album / applet launches are only useful to document applet-specific limitations; P0/P1 gates use title override. - -## Phase 0 hardware checklist - -Complete **in order** on OLED hardware. Operator fills evidence fields — leave blank until tested. - -| Step | Action | Pass | Evidence / notes | -| ---- | ------ | ---- | ---------------- | -| P0-0a | Fetch love-nx 11.5-nx1; record manifest SHA-256 | yes | See `scripts/switch/love-nx-11.5-nx1.sha256` | -| P0-0b | Build `switch-probe.love` per `tools/switch-probe/README.md` | yes | | -| P0-0c | Assemble loose probe (`game.love` = probe) to `dist/switch/loose/` | yes | | -| P0-0d | MTP deploy to `1: SD Card/switch/gen1recomp/`; round-trip SHA-256 | yes | nro `8290ac15…5918f5`; love `9f198637…fa2e34f` | -| P0-0e | Title override → probe boots; `getOS()` shows `NX` | yes | `getOS()`=`NX`, `love._os`=`NX` | -| P0-0f | Probe lists 1280×720 (or documented dims), save path, gamepad/touch log | yes | save `sdmc:/switch/gen1recomp/switch-probe`; Joy-Con Y→#3 X→#4 | -| P0-1a | Replace `game.love` with unpatched Gen1Recomp build | yes | feat/switch-nx inbox build | -| P0-1b | MTP replace `game.love` only; round-trip SHA-256 | yes | | -| P0-1c | Title override → launcher reaches import screen | yes | | -| P0-1d | Joy-Con: can navigate launcher (no touch-only) | yes | Full report: `docs/switch-hardware-evidence.md` | - -**Operator:** Andrew **Date:** 2026-08-01 **Console:** Switch OLED only -**Deploy:** manual Mac + OpenMTP + DBI MTP (not automated) -**love-nx tag:** 11.5-nx1 **gen1recomp commit:** `df7cea4` - -## Phase 0 test report template - -Copy this block into your hardware notes or PR evidence. **Do not commit ROM files or ROM hashes of private dumps.** - -```markdown -## Switch Phase 0 — hardware report - -- Operator: -- Date: -- Console model: -- Atmosphère / HOS version: -- gen1recomp commit: -- love-nx tag: 11.5-nx1 -- love.nro SHA-256 (local): -- game.love SHA-256 (local, pre-send): -- MTP round-trip SHA-256 (gen1recomp.nro): -- MTP round-trip SHA-256 (game.love): -- Title override used: yes / no -- Applet Mode observed: yes / no (should be no for P0) -- Probe getOS(): -- Probe dimensions: -- Probe save directory shown: -- Gamepad events logged: yes / no -- Touch events logged: yes / no -- Unpatched launcher boot: pass / fail -- Joy-Con launcher navigation: pass / fail / not tested -- Notes: -``` - -## Fast dev loop (loose mode) - -While iterating on Lua/assets: - -1. Edit on Mac; run `scripts/test.sh --quick`. -2. Rebuild `.bazinga/work/game.love` (`scripts/build.sh mac --no-notarize` or project pack step). -3. Close Gen1Recomp on Switch. -4. DBI → `Run MTP responder`. -5. OpenMTP → `1: SD Card/switch/gen1recomp/`. -6. Replace **only** `game.love`; wait for queue + refresh listing. -7. Exit MTP responder; launch via title override. -8. Keep `gen1recomp.nro` unchanged until the love-nx pin changes. - -```bash -scripts/test.sh --quick -scripts/build.sh mac --no-notarize -scripts/build_switch.sh --loose -shasum -a 256 .bazinga/work/game.love -``` - -## Controller input mapping (NX) - -Measured on Switch OLED (`feat/switch-nx`, love-nx `11.5-nx1`, 1280×720). Both `joystickpressed` and `gamepadpressed` fire for Joy-Con; prefer the gamepad path when `joystick:isGamepad()` is true. - -| Path | Control | Mapping | -| ---- | ------- | ------- | -| `gamepadpressed` | D-pad / left stick | move | -| `gamepadpressed` | SDL `a` / `b` on **NX** | swapped via `NX_GAMEPAD_BINDINGS`: physical **A** (east) = GB A confirm, physical **B** (south) = GB B cancel | -| `gamepadpressed` | SDL `a` / `b` on desktop | identity (SDL south = GB A) | -| `gamepadpressed` | `start` / `back` | Start / Select (+ / −) | -| `gamepadpressed` | Right / left shoulder (no Select) | Cycle game speed up / down (same as PC hotkey `1` / speed-down path) | -| `joystickpressed` (raw) | only if **not** `isGamepad()` | face/menu fallback | -| `joystickpressed` (raw) | `#1` / `#2` on NX | Nintendo B / A → GB B / A | -| `joystickpressed` (raw) | `#9` / `#10` | Select / Start (− / +) | - -**Nintendo UX on Switch:** physical A confirms, physical B cancels (explicit NX remap of SDL face labels). - -**Launcher extras** (`RomImporter`): physical **A** clicks at the virtual cursor; **L** / **R** switch tabs; **Start** / **Select** start Play when a ROM is ready (else open Choose ROM). D-pad / left stick move the virtual cursor. - -**Dual-path rule:** love-nx emits both `gamepadpressed` and `joystickpressed` for Joy-Con. When `joystick:isGamepad()` is true, Input and RomImporter **ignore raw** face/menu so NamingScreen does not see A+B in one frame. `NamingScreen` also prefers A over B if both edges still fire. - -Implementation: `src/core/GamepadMap.lua` (`NX_RAW_*`, `ignoreRawForJoystick`, `displayChordDigit`), `src/core/Game.lua` (shoulder speed), `src/import/RomImporter.lua` (launcher tabs). Launcher and gameplay share the same converter. - -## ROM inbox (NX) - -Legal dumps land in a shared MTP inbox; **Scan again** is tab-scoped: - -| Item | Value | -| ---- | ----- | -| Save-relative path | `imports/` (also accepts loose `.gb`/`.gbc` at the save-dir root) | -| MTP destination | `1: SD Card//imports/` (see launcher notice for the live `getSaveDirectory()` path) | -| Candidates | `*.gb` / `*.gbc` (hidden `.*` AppleDouble names skipped) | -| Rescan | Game tab → **Scan again** — imports only the dump whose SHA-1 matches that tab (`GameVersion.forSha1`). Other known dumps stay for their own tabs | -| Already ready | Same SHA already imported → “No new ROM found.” | - -Players may drop Red, Blue, and Yellow into the same folder. Opening Yellow and pressing **Scan again** must not start a Red import. - -## Mod zip inbox (NX) - -Community mods install from a **separate** MTP inbox (not mixed into the ROM `imports/` scan): - -| Item | Value | -| ---- | ----- | -| Save-relative path | `imports/mods/` | -| MTP destination | `1: SD Card//imports/mods/` (see launcher notice for the live `getSaveDirectory()` path) | -| Candidates | `*.zip` only | -| Rescan | MODS tab → **Scan again** (installs each zip via `LauncherMods.installZip`; source zips are retained on success and failure) | -| FIND MODS | Remains network-gated / hidden on NX (`networkValidated == false`) | - -Do **not** commit third-party mod zip bytes into git. Drop the zip over MTP, rescan, enable in MODS, then Play. - -**MTP tip (esp. macOS clients):** OpenMTP/Finder often creates AppleDouble sidecars named `._Something.zip` / `._cart.gb` / `._foo.sav`. Those are not real archives, ROMs, or saves — the launcher ignores hidden `.*` names under `imports/`, `imports/mods/`, and `imports/saves//`. If install still fails with “could not be opened” / “not a zip file”, delete any `._*` under the inbox and confirm the real zip starts with the `PK` magic (re-copy the release asset if unsure). This is a host-side annoyance of the current manual MTP loop, not something players should need forever. - -Drop any community release `.zip` into `imports/mods/`, rescan, enable. -Player-facing install steps: [switch-install.md](switch-install.md#community-mods). -Mods own their OPTIONS / rebinds — do not duplicate third-party control tables here. - -## Save `.sav` inbox (NX) - -Raw Gen1 battery images use a **separate** MTP inbox (not mixed into ROM `imports/` or mod `imports/mods/`): - -| Item | Value | -| ---- | ----- | -| Save-relative path | `imports/saves/red/`, `imports/saves/blue/`, `imports/saves/yellow/` | -| MTP destination | `1: SD Card//imports/saves//` (see launcher notice for the live `getSaveDirectory()` path) | -| Candidates | non-hidden `*.sav` only in **that game’s** folder | -| Rescan | SAVE FILES → **Import save** on the matching game tab (scans only that folder) | -| After success | Retire to `*.sav.imported` + append content hash to `imports/saves//.imported-sha1` | -| Exports | **Export save** writes under `exports//gen1recomp--.sav`; NX shows an MTP path notice (no `openURL`) | - -Do **not** commit `.sav` bytes into git. Drop the file into the matching game folder over MTP, press **Import save** on that tab, then play. Pull exports from `exports//`. - -**MTP tip:** the same AppleDouble `._*.sav` rule applies — see the mod inbox tip above. - -## Joy-Con display chords (Select + face) - -PC digit hotkeys for COLORS / TILT / GBC FX / pipelines have Joy-Con equivalents. Hold **Select** (`back` / −) and press a face/shoulder button; the engine runs the same path as `Game:keypressed` for that digit (including `writeOptions` / Pipelines parity). - -| Chord (Nintendo UX) | Engine key | Stock engine effect | -| ------------------- | ---------- | ------------------- | -| Select + **A** | `2` | COLORS cycle | -| Select + **B** | `3` | TILT / perspective | -| Select + **Y** | `5` | GBC FX | -| Select + **X** | `6` | Mod pipeline hotkey (if registered) | -| Select + **L** (left shoulder) | `7` | Mod pipeline hotkey (if registered) | - -Keys `2` / `3` / `4` / `5` are claimed by the engine before mod pipeline hotkeys run, so a community mod cannot rebind those digits through `Pipelines.hotkey`. Mods that need their own controls should use OPTIONS rows or unclaimed hotkeys. - -Without Select held, face buttons keep normal GB A/B gameplay mapping (no accidental color/tilt cycles). The **Options** menu remains available for the same settings — chords are optional shortcuts, not the only path. - -On NX, A/B chords resolve through the Nintendo UX face remap so physical **A** → key `2` and physical **B** → key `3` match this table. - -**OPTIONS → PERFORMANCE** clamps the port’s own extras (TILT / GBC FX / survey ZOOM) and can cap FPS — useful on weaker handheld budgets. Details: [new-features.md — Performance tier](new-features.md#performance-tier-low-end-devices). - -Community mod zip install smoke (MODS inbox + Play): NXMOD-12 in [switch-hardware-evidence.md](switch-hardware-evidence.md). - -**Opt-in diagnostics:** create an empty `switch-debug.txt` in the save directory; events flush to `switch.log` at ≤1 Hz with build identity (no ROM/save bytes). - -**NX asset probe (always on Play):** every Switch Play writes `nx-asset-probe.log` in the save directory (`pokemon-love2d/`). It lists whether `assets/generated/…` vs `yellow|blue/assets/generated/…` exist, what `Assets.resolve` returns, and whether `newImage` / `newImageData` open — for Yellow/Blue blank-sprite triage. No ROM bytes. - -**Blue/Yellow cache overlay (NX):** fused love-nx cannot reliably mount `yellow|blue/assets/generated` onto the un-prefixed path, so `src/core/NxAssetOverlay.lua` wraps EVERY read-side love API that accepts a filesystem path (`filesystem.read/load/lines/newFileData/getInfo`, `graphics.newImage/newFont`, `image.newImageData`, `audio.newSource`, `sound.newSoundData`, `font.newFontData`) once at boot — only when `Platform.isNX()`. Covering the whole read surface (not just the loaders the boot needs today) keeps future states and mods inside the fallback automatically; write-side functions stay stock. Core code must NOT call love loaders on literal `assets/generated` paths (enforced by `tests/engine/nx_generated_guard_test.lua`); the chip-audio worker is a separate Lua state and gets the prefix explicitly via `audio.programPrefix` from `ChipAudio.slimAudio`. - -**Hardware re-test:** T16 **pass** @ `2699c9a` (naming A=confirm / B=cancel). T19 **pass** (quit/reopen, suspend×10, reboot) — operator 2026-08-01. - -**Suspend/resume audio:** after resume, chip music is stopped to avoid duplicate streams; confirm on hardware during P0-09/10 (T19). - -## Lua error log (save directory) - -On any uncaught Lua error, Gen1Recomp appends a redacted trace to `lua-error.log` in the LÖVE save directory (`love.filesystem.getSaveDirectory()`). The on-screen error overlay includes a hint pointing at that file. Logs rotate to `lua-error.log.1` when the active file exceeds 32 KiB. ROM/save bytes and non-printable data are stripped — never commit or share logs that might contain private paths without reviewing them first. - -## Native crash triage (love-nx / Atmosphère) - -love-nx native faults land under the console’s `crash_reports/` folder on SD (reachable via the same manual MTP workflow used for game deploys). - -1. **Collect** — DBI → `Run MTP responder`; copy `sdmc:/crash_reports/*.bin` (or the dated subfolder) to the contributor host. Prefer keeping the microSD in-console for routine pulls. -2. **Redact** — delete any attached screenshots or notes that mention ROM filenames, save paths, or private hashes before sharing logs publicly. -3. **Symbolize** — use the **pinned** `love.elf` from `.bazinga/love-nx/11.5-nx1/` that matches `build-info.json` / `scripts/switch/love-nx-11.5-nx1.sha256`. Never use a “latest” download. - - ```bash - # Example: aarch64-none-elf-addr2line from devkitPro - aarch64-none-elf-addr2line -e .bazinga/love-nx/11.5-nx1/love.elf -f -C 0xADDRESS_FROM_CRASH_REPORT - ``` - -4. **Correlate** — compare `gitCommit` / `loveNxTag` from embedded `build-info.json` with the operator’s hardware notes. - -If `addr2line` cannot resolve an address, archive the crash `.bin` with the exact `love.elf` SHA-256 used for the build — addresses are only meaningful against that ELF. - -## P0 / P1 hardware matrix (ADR §9) - -Operator evidence lives in `docs/switch-hardware-evidence.md`. **Do not invent passes** for rows that require hardware not yet run. - -| ID | Requirement | Status | Evidence | -| -- | ----------- | ------ | -------- | -| P0-0a–f | love-nx pin, probe, MTP, title override | **pass** | Phase 0 checklist above; T4 | -| P0-1a–d | Unpatched launcher boot + Joy-Con nav | **pass** | T4 / `docs/switch-hardware-evidence.md` | -| P0-02 | MTP inbox import path shown | **pass** | T12 | -| P0-03 | Rescan imports ROM | **pass** | T12 | -| P0-04 | Canonical hash routes version | **pass** | T12 | -| P0-05 | Source dump retained in inbox | **pass** | T12 | -| P0-06 | Play reaches game after import | **pass** | T12 | -| P0-07 | Joy-Con launcher navigation | **pass** | T16 @ `2699c9a` | -| P0-08 | Joy-Con gameplay (incl. naming A/B) | **pass** | T16 @ `2699c9a` | -| P0-09 | Save survives quit + reopen | **pass** | T19 | -| P0-10 | ≥10 suspend cycles, no stuck input/dup audio | **pass** | T19 (operator 2026-08-01) | -| P0-12 | Fused NRO boots without adjacent `game.love` | **pass** | T24 — `docs/switch-hardware-evidence.md` | -| P0-14 | Fused NRO MTP round-trip SHA-256 | **pass** | T24 — first artifact `b019e2e8…` @ `6fb5602` (redeploy after Blue fix) | -| P0-15 | Replace NRO only; saves persist | **pass** | T24 — operator NRO-only update keeps saves | -| P1-01 | Docked vs handheld spot-check | **deferred** | Code: `NxDisplay` 720p↔1080p; OLED dock soak not recorded yet | -| P1-02 | Applet Mode documented unsupported | **pass** | Title override required; Album path not validated | -| P1-03 | Long-play soak (≥30 min) | **deferred** | No soak session recorded | -| P1-04 | Reboot persistence | **pass** | T19 | -| P1-05 | Audio resume after suspend | **pass** | T19 (no dup audio reported) | -| — | Switch V1 / Erista boot | **pass** (boot) | Community — [booshankles](https://github.com/booshankles); see evidence log | -| — | Switch Lite / docked soak | **untested** / **deferred** | Welcome contributions | -| — | Automated / `nxlink` deploy | **absent** | Manual MTP / SD / FTP only (AD-009) | -| — | Multi-OS transfer runbooks | **pass** | [switch-transfer.md](switch-transfer.md) | -| — | Community mod zip OLED smoke (NXMOD-12) | **pass** | `docs/switch-hardware-evidence.md` | - -## Review guidance - -Maintainers may review as one PR or split later. Suggested slices (optional): - -Each slice should declare: **no ROM/save bytes committed**, **love-nx pin with manifest checksums**, **hardware-tested rows listed with linked evidence**, **Applet Mode unsupported**, **network/updater disabled on NX**, **deploy still manual** (MTP / SD / FTP; no nxlink yet), **OpenMTP is one example not the sole contract**. - -### Slice 1 — Platform + import (`platform/import`) - -- `src/core/Platform.lua`, `conf.lua` NX branch -- `src/import/RomImporter.lua` (NX flags, inbox, scan, shell/updater gates) -- Tests: `tests/engine/platform_nx_*`, `tests/engine/rom_importer_nx_*` (ROM-free T2) -- Docs: inbox/MTP import sections only - -### Slice 2 — Input + lifecycle (`input/lifecycle`) - -- `src/core/GamepadMap.lua`, `Input.lua`, `main.lua` focus/joystick hooks -- `src/debug/SwitchDiagnostics.lua` (opt-in probe + error log) -- Tests: input/diagnostics suites -- Docs: controller mapping, suspend/audio notes - -### Slice 3 — Build + docs (`build/docs`) - -- `scripts/pack_love.sh`, `scripts/build_switch.sh`, `scripts/switch/*` -- `assets/switch/icon.jpg`, `docs/switch-development.md`, hardware evidence templates -- Gates: `pack_love.sh --dry-run`, `verify_payload.sh --self-test`, fused build script (devkitPro host) - -**Pre-merge checklist:** - -- [ ] Manifest `scripts/switch/love-nx-11.5-nx1.sha256` filled; binaries not in git -- [ ] `verify_payload.sh` rejects generated cache / ROM / `.sav` / `.bak` -- [ ] P0 matrix rows marked pass only with linked hardware evidence -- [x] Fused NRO P0-12/14/15 pass with T24 evidence (`docs/switch-hardware-evidence.md`) -- [ ] Updater / remote mod download hidden on NX (`networkValidated == false`) - diff --git a/docs/switch-hardware-evidence.md b/docs/switch-hardware-evidence.md deleted file mode 100644 index 12e93c04..00000000 --- a/docs/switch-hardware-evidence.md +++ /dev/null @@ -1,187 +0,0 @@ -# Switch hardware evidence (Phase 0 + import + input) - -> **Hardware evidence log.** Author passes below were recorded on **one -> Nintendo Switch OLED** with a **manual** Mac → DBI MTP deploy loop. A -> separate community row records Switch V1 / Erista boot. These rows do -> **not** claim Lite, docked soak, or automated install. See -> `docs/switch-development.md` for status and limitations. - -**love-nx:** `11.5-nx1` -**Author console:** Switch OLED -**Deploy method (author):** manual OpenMTP + DBI `Run MTP responder` (no CI / no nxlink) -**Operator (author rows):** Andrew ([andrewqsantos](https://github.com/andrewqsantos)) -**Date (author rows):** 2026-08-01 - -Do **not** commit ROM dumps or private dump hashes. Do **not** mark a row **pass** without hardware notes for that row. - ---- - -## Community — Switch V1 / Erista boot — pass (boot) - -| Field | Value | -| ----- | ----- | -| Console | Nintendo Switch V1 (Erista) | -| Check | Prebuilt fused NRO boots under title override | -| Tester | [booshankles](https://github.com/booshankles) | -| Notes | Community confirmation only — not a full P0/P1 matrix re-run on V1 | - ---- - -## Phase 0 — probe (T4) — pass - -| Field | Value | -| ----- | ----- | -| Commit (import era) | `df7cea4` | -| `getOS()` / `love._os` | `NX` | -| Dimensions | 1280×720 | -| Save (probe) | `sdmc:/switch/gen1recomp/switch-probe` | -| Joy-Con | `joystickpressed` + `gamepadpressed` (Y→`#3`, X→`#4`) | - -| Artifact | SHA-256 | -| -------- | ------- | -| `gen1recomp.nro` | `8290ac153d4c630e48c9b26ef9123f5204ed8ee0cef3042511707b5b645918f5` | - ---- - -## T12 — Red import + Play — pass - -Inbox MTP → “Scan again” → Play; Joy-Con launcher/gameplay (not touch-only). - ---- - -# T16 — Joy-Con launcher + gameplay — pass (naming re-verify) - -### Round 1 @ `7504753` — partial - -| Check | Result | -| ----- | ------ | -| Launcher / overworld (Joy-Con only) | **pass** | -| Naming player/rival | **fail** (dual-path a+b; see below) | -| Touch required | **no** | -| `game.love` SHA-256 | `bd3a35461bf453c1f0465a5a289421aef3b5c72d3bf1f8d76e86231256829e0e` | - -### Naming failure (root cause) — fixed in `efd81d8` + `2699c9a` - -- love-nx fires **`gamepadpressed` + `joystickpressed` on the same physical press**. -- `NamingScreen` tested `wasPressed("b")` before `"a"` → if both true in one frame, always deletes. -- Dual-path fix: ignore raw when `isGamepad()` (`efd81d8`). -- SDL-only UX then had physical B confirm / A erase; NX face remap (`2699c9a`) restores Nintendo A=confirm / B=cancel. - -### Round 2 @ `2699c9a` — pass (Nintendo UX) - -| Field | Value | -| ----- | ----- | -| Commit tested | `2699c9a` | -| `game.love` SHA-256 | `a208b21e1f30b00e2e8c6fa6efe14f0e06d1db0ae1e50b810b16d9fb852926bc` | -| Touch required | **no** | - -| Check | Result | -| ----- | ------ | -| Naming — player | **pass** — physical **A** confirms letter, **B** cancels/erases | -| Naming — rival | **pass** (same) | -| Launcher / overworld (prior round) | **pass** (unchanged mapping for d-pad/stick) | - -T16 hardware gate: **closed**. - ---- - -## T19 — save / suspend — pass - -| Check | Result | -| ----- | ------ | -| Save in-game → full quit → title-override reopen → load save | **pass** (@ `7504753` / retained) | -| Suspend/resume ×10 (launcher / gameplay / mixed) | **pass** (operator 2026-08-01) | -| Full console reboot persistence | **pass** (operator 2026-08-01) | - -T19 hardware gate: **closed**. No stuck input, duplicate audio, or crash reported. - ---- - -## T24 — fused NRO alone + NRO-only update — **pass** - -| Field | Value | -| ----- | ----- | -| First fused attempt | `6fb5602` (Blue Play failed — mount) | -| Fix commits | `b1ad7c7` (logs/generated overlay), `ac6dfe7` (Blue/Yellow mount) | -| Deploy | isolated folder, no adjacent `game.love` | -| Boot fused | **pass** | -| ROM import | **pass** | -| Play **Red** | **pass** | -| Play **Blue** (after `ac6dfe7`) | **pass** (operator 2026-08-01) | -| NRO-only replace | **pass** — saves retained; app still boots/plays | -| Touch required | no | - -T24 hardware gate: **closed**. - ---- - -## SWBLD — `build_switch.sh --fetch --fused` + install path — **pass** - -Operator smoke for the switch-build-pipeline packaging CLI (closes matrix-deferred happy paths from validation). - -| Field | Value | -| ----- | ----- | -| Command | `scripts/build_switch.sh --fetch --fused --version 0.0.0-test` | -| Host | macOS + native switch-tools (or Docker fallback if used) | -| Commit / build-info | `9147a64` (`gitCommit` in build-info) | -| love-nx | `11.5-nx1` (manifest checksums match) | -| Artifact | `dist/switch/gen1recomp-0.0.0-test-switch.nro` | -| NRO SHA-256 | `210efb884a8d27443dc1c64ed8f071b0f862d8d0c9b140ad8185093c4e4027db` | -| Install doc | `docs/switch-install.md` — at the time of this row: copy NRO under `sdmc:/switch/gen1recomp/` (releases now ship an SD-ready zip; same folder) | -| Console | Switch OLED | -| Operator | Andrew | -| Date | 2026-08-01 | - -| Check | Result | -| ----- | ------ | -| `--fetch` + `--fused` produce NRO + `.sha256` | **pass** | -| Copy NRO to SD folder per install doc | **pass** (operator) | -| Title-override launch / play | treated as prior T24 path; this row records **packaging + deploy to folder** success | - -SWBLD packaging smoke: **closed** for Mac fused build + file-to-SD install step. - ---- - -## NXMOD-12 — Community mod zip OLED smoke — **pass** - -Closed from existing OLED photo evidence on issue -[#531](https://github.com/bryanthaboi/gen1recomp/issues/531) (operator comment -with launcher MODS + overworld shots). Photos live on the orphan branch -[`switch-oled-photos`](https://github.com/andrewqsantos/gen1recomp/tree/switch-oled-photos) -of the operator fork — **not** committed to this repo. Do **not** commit -third-party mod `.zip` bytes. Community mods own their OPTIONS / rebinds; -this entry only proves the MODS inbox + Play path on OLED. - -| Field | Value | -| ----- | ----- | -| Status | **pass** | -| gen1recomp commit | evidence era on `feat/switch-nx` (see #531); packaging pin love-nx `11.5-nx1` | -| love-nx tag | `11.5-nx1` | -| Console | Switch OLED | -| Mod | community release `.zip` (not vendored; not named here) | -| Zip committed to git? | **no** | -| Photo evidence | [#531 comment](https://github.com/bryanthaboi/gen1recomp/issues/531) — MODS tab + overworld | -| MODS tab photo | https://raw.githubusercontent.com/andrewqsantos/gen1recomp/switch-oled-photos/IMG_1766.jpg | -| Overworld photo | https://raw.githubusercontent.com/andrewqsantos/gen1recomp/switch-oled-photos/IMG_1771.jpg | -| Operator | Andrew | -| Date | 2026-08-01 | - -### Checklist - -| Step | Pass / fail / pending | Notes | -| ---- | --------------------- | ----- | -| MTP zip into save `imports/mods/` | **pass** | Photo evidence + prior inbox path | -| MODS → Scan again → mod listed | **pass** | IMG_1766 — community mod installed | -| Enable mod + Play Red boots without crash | **pass** | Overworld / Pallet / Oak lab photos on #531 | -| Overworld Select+A → visible colors change | **pass** | Stock COLORS chord path exercised | -| Overworld Select+B → visible tilt/perspective change | **pass** | Stock TILT chord path exercised (IMG_1771) | - -### Evidence notes - -```text -Operator: Andrew -Date: 2026-08-01 -Commit tested: feat/switch-nx era documented on issue #531 -Pass / fail summary: PASS — MODS zip install + Play on Switch OLED -Photo branch: andrewqsantos/gen1recomp@switch-oled-photos -``` diff --git a/docs/switch-install.md b/docs/switch-install.md index 00b03cae..4f4c69e4 100644 --- a/docs/switch-install.md +++ b/docs/switch-install.md @@ -6,11 +6,7 @@ Every GitHub Release that includes Switch support ships an SD-ready zip: own legal `.gb` ROM. > You need a console that can run Switch homebrew (custom firmware / hbmenu). -> This project does not help you set that up. Tracks issue -> [#531](https://github.com/bryanthaboi/gen1recomp/issues/531). -> Hardware: **OLED** validated by the porter; **V1 / Erista** boot confirmed -> by the community. Lite and other setups welcome more reports. -> See [switch-development.md](switch-development.md) for limitations. +> This project does not help you set that up. Prefer building from source? See [switch-build.md](switch-build.md). @@ -185,12 +181,23 @@ hotkeys (`2`/`3`/`5` are claimed before any mod pipeline hotkey runs). | Select + **L** | `7` | Mod pipeline hotkey (if a mod registers `7`) | If the handheld stutters with extras on, try **OPTIONS → PERFORMANCE** → -`LOW` or `BALANCED`. Full chord notes for contributors: -[switch-development.md](switch-development.md#joy-con-display-chords-select--face). +`LOW` or `BALANCED`. + +## Limitations + +- **Homebrew required** — custom firmware and hbmenu; this project does not help + set that up. +- **Title override required** — hold **R** when launching a title for full + memory. Applet Mode (Album) is not supported. +- **Manual file transfer** — ROMs, mods, and saves are copied via MTP, direct + SD, or FTP; there is no automated deploy. +- **No LÖVE self-updater** — in-console updates use the native OTA launcher + only. Remote **FIND MODS** / GitHub download stays off on Switch. +- **Hardware** — tested on Switch OLED; Switch V1 / Erista boot confirmed by the + community. Other models may work but are less tested. ## Prefer building it yourself? Building the fused NRO (and SD-ready zip) from source is covered in [switch-build.md](switch-build.md). Copying artifacts and inbox files (MTP / SD / FTP on macOS, Linux, Windows): [switch-transfer.md](switch-transfer.md). -Status, limitations, and how we tested: [switch-development.md](switch-development.md). diff --git a/docs/switch-transfer.md b/docs/switch-transfer.md index f7cd153b..3c1477af 100644 --- a/docs/switch-transfer.md +++ b/docs/switch-transfer.md @@ -6,8 +6,7 @@ Switch. **Any method is valid** if the bytes land in the destinations below. This is the home runbook for contributors on **macOS, Linux, and Windows**. Player install (what to download, title override) stays in [switch-install.md](switch-install.md). Packaging stays in -[switch-build.md](switch-build.md). Hardware evidence lives in -[switch-hardware-evidence.md](switch-hardware-evidence.md). +[switch-build.md](switch-build.md). > **Not supported yet:** `nxlink` / hbmenu netloader automation. Useful later > for a fast contrib rebuild loop; deferred on purpose (AD-009). Do not treat @@ -47,8 +46,8 @@ before launching. #### macOS (example: OpenMTP) -[OpenMTP](https://github.com/ganeshrvel/openmtp) is the loop used for OLED -hardware evidence — **one contributor example**, not a Mac-only product rule. +[OpenMTP](https://github.com/ganeshrvel/openmtp) is a documented example for +macOS — **one contributor workflow**, not a Mac-only product rule. 1. Quit other MTP clients. 2. Open OpenMTP → select the DBI device → **`1: SD Card`**. @@ -164,5 +163,3 @@ Copy the file back from the SD and compare hashes. Round-trip must match. - Players: [switch-install.md](switch-install.md) - Builders: [switch-build.md](switch-build.md) -- Status / hardware matrix: [switch-development.md](switch-development.md) -- Evidence log: [switch-hardware-evidence.md](switch-hardware-evidence.md) diff --git a/docs/updater.md b/docs/updater.md index 6a7c6625..047ffbd1 100644 --- a/docs/updater.md +++ b/docs/updater.md @@ -127,6 +127,5 @@ bundled game, in that case. - **Nintendo Switch does not use this LÖVE self-updater.** On NX, `Platform.networkValidated()` is `false`, so `Boot.run` / `Check` never download `.love` payloads. In-console OTA is the **native OTA launcher** - (DEVKITPRO) documented in [switch-install.md](switch-install.md) and - [switch-development.md](switch-development.md); protocol contract + (DEVKITPRO) documented in [switch-install.md](switch-install.md); protocol contract `src/update/SwitchOta.lua`. Manual zip install remains the fallback. diff --git a/src/core/GamepadMap.lua b/src/core/GamepadMap.lua index c76a1504..9d8b921f 100644 --- a/src/core/GamepadMap.lua +++ b/src/core/GamepadMap.lua @@ -1,5 +1,5 @@ -- Shared gamepad + raw joystick button tables for launcher and gameplay. --- Hardware-measured NX overrides live in NX_* tables (see docs/switch-development.md). +-- Hardware-measured NX overrides live in NX_* tables below. local GamepadMap = {} diff --git a/test/switch-nro-ota.spec.test.js b/test/switch-nro-ota.spec.test.js index ff1bd95f..4f216cb2 100644 --- a/test/switch-nro-ota.spec.test.js +++ b/test/switch-nro-ota.spec.test.js @@ -339,12 +339,12 @@ test('AC-004: Offline ou falha de rede não trava o jogo @spec:AC-004', () => { test('AC-005: Documentação Switch descreve o launcher OTA @spec:AC-005', () => { const install = read('docs/switch-install.md'); - const development = read('docs/switch-development.md'); + const build = read('docs/switch-build.md'); const updater = read('docs/updater.md'); for (const [name, text] of [ ['switch-install', install], - ['switch-development', development], + ['switch-build', build], ['updater', updater], ]) { assert.match(text, /native OTA launcher|launcher nativo/i, `${name} mentions native OTA launcher`); @@ -437,7 +437,7 @@ test('AC-008: Gates de regressão anti-“erro invisível” @spec:AC-008', () = const platform = read('src/core/Platform.lua'); assert.match(platform, /networkValidated\s*=\s*not nx\s+and\s+not uwp/); - for (const rel of ['docs/switch-install.md', 'docs/switch-development.md', 'docs/updater.md']) { + for (const rel of ['docs/switch-install.md', 'docs/switch-build.md', 'docs/updater.md']) { const text = read(rel); assert.match(text, /native OTA launcher|launcher nativo/i, rel); assert.match( diff --git a/tests/switch_ci_workflows_test.lua b/tests/switch_ci_workflows_test.lua index 8225cc46..d43e6ccf 100644 --- a/tests/switch_ci_workflows_test.lua +++ b/tests/switch_ci_workflows_test.lua @@ -152,7 +152,6 @@ check(comment_wf:find("comment-tag: switch-build-result", 1, true) -- --- SWCI-08 / SWCI-09: docs CI vs release --- local build_doc = read("docs/switch-build.md") -local development = read("docs/switch-development.md") local readme = read("README.md") mustContain(build_doc, "Path-gated", "switch-build.md") @@ -167,12 +166,14 @@ mustContain(build_doc, "nacptool", "switch-build.md") mustContain(build_doc, "Docker", "switch-build.md") mustContain(build_doc, "Fork → canonical", "switch-build.md") mustContain(build_doc, "skip Switch fused", "switch-build.md") - -mustContain(development, "Switch CI", "switch-development.md") -mustContain(development, "selftest_build_switch.sh", "switch-development.md") +mustContain(build_doc, "CI and release", "switch-build.md") +mustNotContain(build_doc, "switch-development", "switch-build.md") +mustNotContain(build_doc, "switch-hardware-evidence", "switch-build.md") mustContain(readme, "CI vs release", "README.md") mustContain(readme, "switch-build.md", "README.md") +mustNotContain(readme, "switch-development", "README.md") +mustNotContain(readme, "switch-hardware-evidence", "README.md") -- --- SWFIX-03: headless suite also runs the content gates --- local test_sh = read("scripts/test.sh") diff --git a/tests/switch_transfer_docs_test.lua b/tests/switch_transfer_docs_test.lua index ee80d11d..68cd600b 100644 --- a/tests/switch_transfer_docs_test.lua +++ b/tests/switch_transfer_docs_test.lua @@ -32,7 +32,7 @@ mustContain(transfer, "imports/", "transfer") mustContain(transfer, "imports/mods/", "transfer") mustContain(transfer, "1: SD Card", "transfer") mustContain(transfer, "Scan again", "transfer") -mustContain(transfer, "one contributor example", "transfer") +mustContain(transfer, "one contributor workflow", "transfer") mustContain(transfer, "Linux", "transfer") mustContain(transfer, "Windows", "transfer") mustContain(transfer, "macOS", "transfer") @@ -54,46 +54,27 @@ mustContain(transfer, "USB-C", "transfer") mustContain(transfer, "If MTP is unavailable or flaky on Linux", "transfer") mustContain(transfer, "If MTP is unavailable or flaky on Windows", "transfer") mustContain(transfer, "Joy-Con display chords (stock engine)", "transfer") -mustNotContain(transfer, "VoxelMod", "transfer") +mustNotContain(transfer, "switch-development", "transfer") +mustNotContain(transfer, "switch-hardware-evidence", "transfer") local install = read("docs/switch-install.md") local build = read("docs/switch-build.md") mustContain(install, "switch-transfer.md", "install") mustContain(install, "## Community mods", "install") mustContain(install, "Select + **A**", "install") +mustContain(install, "Select + **L**", "install") mustContain(install, "COLORS", "install") mustContain(install, "TILT", "install") mustContain(install, "GBC FX", "install") mustContain(install, "PERFORMANCE", "install") mustContain(install, "Stock engine effect", "install") +mustContain(install, "## Limitations", "install") +mustContain(install, "Title override required", "install") mustNotContain(install, "VoxelMod", "install") +mustNotContain(install, "switch-development", "install") mustContain(build, "switch-transfer.md", "build") mustContain(build, "nxlink", "build") - -local development = read("docs/switch-development.md") -mustContain(development, "switch-transfer.md", "development") -mustContain(development, "## Joy-Con display chords (Select + face)", "development") -mustContain(development, "Stock engine effect", "development") -mustContain(development, "claimed by the engine before mod pipeline", "development") -mustContain(development, "Select + **L**", "development") -mustContain(development, "OPTIONS → PERFORMANCE", "development") -mustNotContain(development, "VoxelMod", "development") -check(development:find("Non-macOS contributor MTP runbooks", 1, true) == nil, - "development must not list Non-macOS runbooks as absent") - -local evidence = read("docs/switch-hardware-evidence.md") -local nxStart = evidence:find("## NXMOD-12", 1, true) -check(nxStart ~= nil, "NXMOD-12 section present") -local nxmod = evidence:sub(nxStart) -mustContain(nxmod, "**pass**", "NXMOD-12") -mustContain(nxmod, "531", "NXMOD-12") -mustContain(nxmod, "switch-oled-photos", "NXMOD-12") -mustContain(nxmod, "IMG_1766.jpg", "NXMOD-12") -mustContain(nxmod, "IMG_1771.jpg", "NXMOD-12") -mustContain(nxmod, "Community mod zip", "NXMOD-12") -mustNotContain(nxmod, "VoxelMod", "NXMOD-12") -check(nxmod:find("Status | **pending**", 1, true) == nil - and nxmod:find("| **pending** |", 1, true) == nil, - "NXMOD-12 must not keep pending status/checklist") +mustNotContain(build, "switch-development", "build") +mustNotContain(build, "switch-hardware-evidence", "build") T.finish("switch_transfer_docs_test") diff --git a/tools/switch-probe/README.md b/tools/switch-probe/README.md index 616c1300..f0940c85 100644 --- a/tools/switch-probe/README.md +++ b/tools/switch-probe/README.md @@ -11,7 +11,9 @@ Validate Phase 0 runtime facts on real Switch hardware before running the full G - Save directory path (`love.filesystem.getSaveDirectory()`) - Gamepad / joystick / touch event logging -To date this probe has only been run on **Switch OLED** (see `docs/switch-hardware-evidence.md`); other models are untested. Deploy beside `gen1recomp.nro` remains **manual** (MTP); see `docs/switch-development.md`. +To date this probe has only been run on **Switch OLED**; other models are +untested. Deploy beside `gen1recomp.nro` remains **manual** (MTP); see +`docs/switch-transfer.md`. ## Fields shown on screen @@ -36,7 +38,9 @@ mkdir -p .bazinga/work zip -9 -j .bazinga/work/switch-probe.love tools/switch-probe/main.lua tools/switch-probe/conf.lua ``` -Deploy beside `gen1recomp.nro` (loose mode) per `docs/switch-development.md`, renaming to `game.love` only for a probe run — use a separate SD folder so probe and game builds do not mix. +Deploy beside `gen1recomp.nro` (loose mode) per `docs/switch-build.md` and +`docs/switch-transfer.md`, renaming to `game.love` only for a probe run — use a +separate SD folder so probe and game builds do not mix. ## Desktop smoke (optional)