diff --git a/docs/switch-development.md b/docs/switch-development.md index 7bada5df..a2887fb1 100644 --- a/docs/switch-development.md +++ b/docs/switch-development.md @@ -46,7 +46,6 @@ the transfer runbook). - 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) -- VoxelMod OPTIONS + Switch performance tips documented (WATER / 3D-BTL / extras) - 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` @@ -59,8 +58,8 @@ the transfer runbook). - `nxlink` / netloader contrib fast-loop (deferred — see [switch-transfer.md](switch-transfer.md)) Transfer runbooks for Linux/Windows (and SD/FTP alternatives) are in -[switch-transfer.md](switch-transfer.md). VoxelMod OLED smoke is **pass** — -see NXMOD-12 in [switch-hardware-evidence.md](switch-hardware-evidence.md). +[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) @@ -373,7 +372,9 @@ Do **not** commit third-party mod zip bytes into git. Drop the zip over MTP, res **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. -**Example zip source:** [DramaticShape VoxelMod releases](https://github.com/DramaticShape/DramaticShapeVoxelMod/releases) — download a release `.zip`, copy into `imports/mods/`, rescan, enable. Player-facing install + performance tips: [switch-install.md](switch-install.md#community-mods-voxelmod). +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) @@ -394,62 +395,25 @@ Do **not** commit `.sav` bytes into git. Drop the file into the matching game fo ## Joy-Con display chords (Select + face) -PC digit hotkeys for COLORS / TILT / 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). +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 | With DramaticShape VoxelMod | -| ------------------- | ---------- | ------------ | --------------------------- | -| Select + **A** | `2` | COLORS cycle | COLORS cycle (unchanged) | -| Select + **B** | `3` | TILT / perspective | **VOXEL** pitch (OFF → 15 → 35 → 50 → 75 → OFF); mod hides stock TILT | -| Select + **Y** | `5` | GBC FX | **V-GRID** ON/OFF (mod hides stock GBC FX) | -| Select + **X** | `6` | (pipeline) | **T-SHIFT** OFF → 1 → 2 → 3 → OFF (tilt-shift blur) | -| Select + **L** (left shoulder) | `7` | (pipeline) | **V-CURVE** OFF → 1 → 2 → 3 (horizon bend) | +| 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) | -There is **no** Joy-Con chord for VoxelMod **`8` (3D-BTL)** or **`9` (WATER)** — change those in **OPTIONS** (see below). +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. -## VoxelMod on Switch (options + performance) +**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). -[DramaticShape VoxelMod](https://github.com/DramaticShape/DramaticShapeVoxelMod) is a heavy presentational mod (3D overworld, optional water shader, 3D battles). It runs on Switch OLED smoke (NXMOD-12), but weaker handheld budgets benefit from dialing options down. Everything below is **purely visual** — no gameplay rules change. - -### VoxelMod OPTIONS rows - -| OPTIONS row | PC key | Values | Notes | -| ----------- | ------ | ------ | ----- | -| **VOXEL** | `3` / Select+B | OFF → 15 → 35 → 50 → 75 → OFF | Camera pitch over the diorama | -| **V-GRID** | `5` / Select+Y | OFF / ON | One-pixel wireframe on every voxel | -| **T-SHIFT** | `6` / Select+X | OFF → 1 → 2 → 3 → OFF | Miniature tilt-shift blur | -| **V-CURVE** | `7` / Select+L | OFF → 1 → 2 → 3 | Bend the world over the horizon | -| **3D-BTL** | `8` (Options only) | ON / OFF | Fight on the map instead of a white field; **ON by default**, independent of VOXEL pitch | -| **WATER** | `9` (Options only) | FULL / SKY / OFF | Waves + reflections. **FULL** = screen-space ray march (heaviest); **SKY** = sky/sun/moon/cast only; **OFF** = disable water shader | -| **BACK SPRITES** | Options only | OFF / ON | Own Pokémon as classic back sprite on the battle menu; only shown while **3D-BTL** is on | -| **DAYTIME** | Options only | SYNC / DAY / NIGHT / DUSK / DAWN / CYCLE | Outdoor lighting; held at SYNC (and off the menu) while VOXEL is FULL | - -While VoxelMod is installed it **hides and forces off** the engine’s **TILT** and **GBC FX** rows (those conflict with the diorama). Uninstall restores them to their last saved values. - -Upstream control table: [DramaticShape README](https://github.com/DramaticShape/DramaticShapeVoxelMod/blob/master/README.md). - -### Suggested Switch profile (smoother handheld) - -Priority order if the game feels heavy with VoxelMod enabled: - -1. **WATER** → **`OFF`** (or at most **`SKY`**; avoid **`FULL`** on Switch) -2. **3D-BTL** → **`OFF`** (biggest win after water; battles go back to the stock field) -3. **T-SHIFT** → **`OFF`** -4. **V-CURVE** → **`OFF`** -5. **V-GRID** → **`OFF`** -6. **BACK SPRITES** → **`OFF`** if 3D-BTL is still on -7. **DAYTIME** → prefer **`SYNC`** (or a fixed time); avoid **`CYCLE`** - -Keep **VOXEL** at a modest pitch (e.g. **35** or **50**) if you want the 3D look without stacking every extra pass. - -### Engine PERFORMANCE tier - -Separately from the mod, **OPTIONS → PERFORMANCE** clamps the port’s own extras (TILT / GBC FX / survey ZOOM) and can cap FPS. On Switch with VoxelMod, set **PERFORMANCE → LOW** (or **BALANCED**) if the handheld still stutters after the VoxelMod rows above are dialed down. Details: [new-features.md — Performance tier](new-features.md#performance-tier-low-end-devices). - -VoxelMod smoke evidence (install + overworld chords): NXMOD-12 in [switch-hardware-evidence.md](switch-hardware-evidence.md). Full soak of every VoxelMod option on OLED is still deferred. +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). @@ -507,7 +471,7 @@ Operator evidence lives in `docs/switch-hardware-evidence.md`. **Do not invent p | — | 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) | -| — | VoxelMod OLED smoke (NXMOD-12) | **pass** | `docs/switch-hardware-evidence.md` | +| — | Community mod zip OLED smoke (NXMOD-12) | **pass** | `docs/switch-hardware-evidence.md` | ## Review guidance diff --git a/docs/switch-hardware-evidence.md b/docs/switch-hardware-evidence.md index ad0a6ba7..12e93c04 100644 --- a/docs/switch-hardware-evidence.md +++ b/docs/switch-hardware-evidence.md @@ -142,15 +142,15 @@ SWBLD packaging smoke: **closed** for Mac fused build + file-to-SD install step. --- -## NXMOD-12 — VoxelMod OLED smoke — **pass** +## 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 + VoxelMod overworld shots). Photos live on the orphan -branch +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 -DramaticShape (or any) mod `.zip` bytes. +third-party mod `.zip` bytes. Community mods own their OPTIONS / rebinds; +this entry only proves the MODS inbox + Play path on OLED. | Field | Value | | ----- | ----- | @@ -158,13 +158,11 @@ DramaticShape (or any) mod `.zip` bytes. | 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 id | DramaticShape VoxelMod (community) | -| Mod version | release zip from upstream (not vendored) | -| Zip source URL | https://github.com/DramaticShape/DramaticShapeVoxelMod/releases | +| 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 + Voxel overworld | +| 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 | -| Voxel overworld photo | https://raw.githubusercontent.com/andrewqsantos/gen1recomp/switch-oled-photos/IMG_1771.jpg | +| Overworld photo | https://raw.githubusercontent.com/andrewqsantos/gen1recomp/switch-oled-photos/IMG_1771.jpg | | Operator | Andrew | | Date | 2026-08-01 | @@ -173,10 +171,10 @@ DramaticShape (or any) mod `.zip` bytes. | 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 — Dramatic Shape Voxel Mod installed | +| 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/settings change | **pass** | Chords shipped; OLED session used display paths with VoxelMod | -| Overworld Select+B → visible tilt/perspective change | **pass** | Same; VoxelMod 3D overworld visible (IMG_1771) | +| 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 @@ -184,6 +182,6 @@ DramaticShape (or any) mod `.zip` bytes. Operator: Andrew Date: 2026-08-01 Commit tested: feat/switch-nx era documented on issue #531 -Pass / fail summary: PASS — MODS install + VoxelMod overworld on Switch OLED +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 d9b32f35..6584f2f0 100644 --- a/docs/switch-install.md +++ b/docs/switch-install.md @@ -123,7 +123,7 @@ create `._*.sav` AppleDouble sidecars that are not real saves. | ------- | ------ | | Hold **R** on HOME, then open from hbmenu | Title override (full memory) | -## Community mods (VoxelMod) +## Community mods Mods install from a zip inbox (same transfer methods as ROMs): @@ -133,40 +133,26 @@ Mods install from a zip inbox (same transfer methods as ROMs): **Play**. Remote **FIND MODS** / GitHub download stays **off** on Switch. Do not put -mod zips into git. - -Example: [DramaticShape VoxelMod](https://github.com/DramaticShape/DramaticShapeVoxelMod/releases). +mod zips into git. Community mods ship their own OPTIONS / rebinds — this port +does not document third-party control tables. ### Joy-Con shortcuts (Select + face) Hold **Select** (−) and press a face/shoulder button. Without Select, A/B stay -normal gameplay confirm/cancel. +normal gameplay confirm/cancel. These chords are the stock engine display +hotkeys (`2`/`3`/`5` are claimed before any mod pipeline hotkey runs). -| Chord | Same as PC key | Typical effect (stock / VoxelMod) | -| ----- | -------------- | --------------------------------- | +| Chord | Same as PC key | Stock engine effect | +| ----- | -------------- | ------------------- | | Select + **A** | `2` | COLORS | -| Select + **B** | `3` | TILT, or VoxelMod **VOXEL** pitch | -| Select + **Y** | `5` | GBC FX, or VoxelMod **V-GRID** | -| Select + **X** | `6` | VoxelMod **T-SHIFT** | -| Select + **L** | `7` | VoxelMod **V-CURVE** | +| Select + **B** | `3` | TILT | +| Select + **Y** | `5` | GBC FX | +| Select + **X** | `6` | Mod pipeline hotkey (if a mod registers `6`) | +| Select + **L** | `7` | Mod pipeline hotkey (if a mod registers `7`) | -**3D-BTL** (`8`) and **WATER** (`9`) have no Joy-Con chord — use **OPTIONS**. - -### VoxelMod: lighter settings on Switch - -VoxelMod is visual-only but expensive. If the Switch stutters, open **OPTIONS** -and prefer: - -1. **WATER** → `OFF` (or `SKY`; avoid `FULL`) -2. **3D-BTL** → `OFF` -3. **T-SHIFT** / **V-CURVE** / **V-GRID** → `OFF` -4. **DAYTIME** → `SYNC` (avoid `CYCLE`) -5. Engine **PERFORMANCE** → `LOW` or `BALANCED` - -Full tables, chords vs Options rows, and contributor notes: -[switch-development.md](switch-development.md#joy-con-display-chords-select--face) -and -[switch-development.md](switch-development.md#voxelmod-on-switch-options--performance). +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). ## Prefer building it yourself? diff --git a/docs/switch-transfer.md b/docs/switch-transfer.md index f42ad4c6..932d8621 100644 --- a/docs/switch-transfer.md +++ b/docs/switch-transfer.md @@ -132,9 +132,8 @@ a single vendor tutorial. 3. For ROMs: launcher → **Scan again** if the file was added after boot. For mods: MODS → **Scan again** → enable → Play. For saves: SAVE FILES → **Import save** (rescans `imports/saves//`). Pull exported - `.sav` files from `exports//`. - VoxelMod Joy-Con chords and Switch performance tips: - [switch-install.md](switch-install.md#community-mods-voxelmod). + `.sav` files from `exports//`. Joy-Con display chords (stock engine): + [switch-install.md](switch-install.md#joy-con-shortcuts-select--face). ### Optional NRO integrity check diff --git a/src/core/Game.lua b/src/core/Game.lua index 7782cd57..bbc70506 100644 --- a/src/core/Game.lua +++ b/src/core/Game.lua @@ -651,7 +651,7 @@ function Game:gamepadpressed(joystick, button) -- next screen touch (mobile only; a no-op elsewhere) TouchControls:noteGamepad() -- Select held? Needed both to suppress shoulder speed hotkeys (Select+L - -- is a display chord on NX / VoxelMod) and for the chord path below. + -- is a display chord on NX) and for the chord path below. local selectHeld = Input:isDown("select") if not selectHeld and joystick and joystick.isGamepadDown then local ok, down = pcall(function() diff --git a/tests/switch_transfer_docs_test.lua b/tests/switch_transfer_docs_test.lua index 13977178..ee80d11d 100644 --- a/tests/switch_transfer_docs_test.lua +++ b/tests/switch_transfer_docs_test.lua @@ -17,6 +17,11 @@ local function mustContain(body, needle, label) label .. " must contain " .. string.format("%q", needle)) end +local function mustNotContain(body, needle, label) + check(body:find(needle, 1, true) == nil, + label .. " must not contain " .. string.format("%q", needle)) +end + local transfer = read("docs/switch-transfer.md") mustContain(transfer, "MTP", "transfer") @@ -48,29 +53,33 @@ mustContain(transfer, "USB-C", "transfer") -- Per-OS SD/FTP fallback when MTP is flaky (XFER-05 AC) 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") local install = read("docs/switch-install.md") local build = read("docs/switch-build.md") mustContain(install, "switch-transfer.md", "install") -mustContain(install, "Community mods (VoxelMod)", "install") +mustContain(install, "## Community mods", "install") mustContain(install, "Select + **A**", "install") -mustContain(install, "WATER", "install") -mustContain(install, "3D-BTL", "install") +mustContain(install, "COLORS", "install") +mustContain(install, "TILT", "install") +mustContain(install, "GBC FX", "install") mustContain(install, "PERFORMANCE", "install") +mustContain(install, "Stock engine effect", "install") +mustNotContain(install, "VoxelMod", "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, "VoxelMod on Switch", "development") -mustContain(development, "Suggested Switch profile", "development") -mustContain(development, "WATER", "development") -mustContain(development, "3D-BTL", "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") -check(development:find("VoxelMod (and other community mods) OLED smoke still **pending**", 1, true) == nil, - "development must not list VoxelMod smoke as pending") local evidence = read("docs/switch-hardware-evidence.md") local nxStart = evidence:find("## NXMOD-12", 1, true) @@ -81,6 +90,8 @@ 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")