diff --git a/docs/switch-development.md b/docs/switch-development.md index a08e309f..5b3ca7e0 100644 --- a/docs/switch-development.md +++ b/docs/switch-development.md @@ -34,6 +34,7 @@ This document covers what landed so far, known limitations, how hardware was tes - 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) - Select+face display chords (COLORS / TILT / pipelines) on Joy-Con +- 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` ### What is still unfinished / out of this draft @@ -353,24 +354,67 @@ 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`. Those are not real archives or ROMs — the launcher ignores hidden `.*` names under both `imports/` and `imports/mods/`. 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. +**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). ## 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). -| Chord (Nintendo UX) | Engine key | Typical effect | -| ------------------- | ---------- | -------------- | -| Select + **A** | `2` | COLORS cycle | -| Select + **B** | `3` | TILT / perspective cycle | -| Select + **Y** | `5` | GBC FX / V-GRID (mod pipeline) | -| Select + **X** | `6` | T-SHIFT / mod pipeline | -| Select + **L** (left shoulder) | `7` | V-CURVE / mod pipeline | +| 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) | + +There is **no** Joy-Con chord for VoxelMod **`8` (3D-BTL)** or **`9` (WATER)** — change those in **OPTIONS** (see below). 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) + +[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. + **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). **Hardware re-test:** T16 **pass** @ `2699c9a` (naming A=confirm / B=cancel). T19 **pass** (quit/reopen, suspend×10, reboot) — operator 2026-08-01. diff --git a/docs/switch-install.md b/docs/switch-install.md index cbde1a00..38fec531 100644 --- a/docs/switch-install.md +++ b/docs/switch-install.md @@ -60,6 +60,51 @@ This project ships **no** game data. On first launch: Saves live in the LÖVE save directory and **persist across NRO updates** — you can replace only the `.nro` and keep your progress. +## Community mods (VoxelMod) + +Mods install from a zip inbox (same transfer methods as ROMs): + +1. Copy a release `.zip` into the save-dir **`imports/mods/`** path the + launcher shows (MTP / SD / FTP — [switch-transfer.md](switch-transfer.md)). +2. In the launcher, open **MODS** → **Procurar novamente** → enable the mod → + **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). + +### Joy-Con shortcuts (Select + face) + +Hold **Select** (−) and press a face/shoulder button. Without Select, A/B stay +normal gameplay confirm/cancel. + +| Chord | Same as PC key | Typical effect (stock / VoxelMod) | +| ----- | -------------- | --------------------------------- | +| 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** | + +**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). + ## Prefer building it yourself? Building the fused (or loose) NRO from source is covered in diff --git a/docs/switch-transfer.md b/docs/switch-transfer.md index d01eed90..43d01e60 100644 --- a/docs/switch-transfer.md +++ b/docs/switch-transfer.md @@ -123,6 +123,8 @@ a single vendor tutorial. Mode is not supported** (not enough memory). 3. For ROMs: launcher → **Procurar novamente** if the file was added after boot. For mods: MODS → **Procurar novamente** → enable → Play. + VoxelMod Joy-Con chords and Switch performance tips: + [switch-install.md](switch-install.md#community-mods-voxelmod). ### Optional NRO integrity check diff --git a/tests/switch_transfer_docs_test.lua b/tests/switch_transfer_docs_test.lua index 8110e1d0..65794769 100644 --- a/tests/switch_transfer_docs_test.lua +++ b/tests/switch_transfer_docs_test.lua @@ -52,11 +52,21 @@ mustContain(transfer, "If MTP is unavailable or flaky on Windows", "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, "Select + **A**", "install") +mustContain(install, "WATER", "install") +mustContain(install, "3D-BTL", "install") +mustContain(install, "PERFORMANCE", "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, "Select + **L**", "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,