docs(switch): document VoxelMod chords and Switch performance tips

Co-authored-by: Cursor <cursoragent@cursor.com>

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.

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

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
 

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,