Merge pull request #705 from bryanthaboi/dev

Maintainer review on #699 asked to document the hotkeys. Added key 1
(cycle speed up) and controller R2/L2 to the README Hotkeys table, and
GAME SPEED to the Options-menu note.

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -10,8 +10,6 @@ name: ci
 # The T3 content tier asserts Pokemon Red facts; scripts/test.sh detects
 # data/generated/ is absent and skips it rather than failing.
 #
-# Runs alongside release.yml, which is untouched by this file.
-
 on:
   push:
     # Integration branch + release branch. PRs already run via pull_request
@@ -24,12 +22,91 @@ concurrency:
   group: ci-${{ github.ref }}
   cancel-in-progress: true
 
+permissions:
+  contents: read
+
 jobs:
+  ios-changes:
+    name: detect iOS changes
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.paths.outputs.changed }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - id: paths
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
+          HEAD_SHA: ${{ github.sha }}
+        run: |
+          if [ -z "$BASE_SHA" ] || [ "$BASE_SHA" = "0000000000000000000000000000000000000000" ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(mobile/ios/|scripts/build_ios\.sh$|\.github/workflows/(ci|release)\.yml$)'; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  ios-build:
+    name: iOS build
+    needs: ios-changes
+    if: needs.ios-changes.outputs.changed == 'true'
+    runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
+    outputs:
+      ipa_url: ${{ steps.upload-ipa.outputs.artifact-url }}
+    steps:
+      - uses: actions/checkout@v7
+      - name: import signing certificate
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        run: |
+          keychain_path="$RUNNER_TEMP/gen1recomp-ci-signing.keychain-db"
+          ci_dir="${POKEMON_CI_DIR:-$HOME/.config/pokemon-ci}"
+          p12="$ci_dir/signing.p12"
+          passfile="$ci_dir/signing.pass"
+          [ -f "$p12" ] && [ -f "$passfile" ] || exit 1
+          p12pw="$(cat "$passfile")"
+          kcpw="$(openssl rand -base64 24)"
+          echo "::add-mask::$kcpw"
+          security delete-keychain "$keychain_path" 2>/dev/null || true
+          security create-keychain -p "$kcpw" "$keychain_path"
+          security set-keychain-settings "$keychain_path"
+          security unlock-keychain -p "$kcpw" "$keychain_path"
+          security import "$p12" -P "$p12pw" -k "$keychain_path" -T /usr/bin/codesign -T /usr/bin/security
+          security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$kcpw" "$keychain_path" >/dev/null
+          existing="$(security list-keychains -d user | sed -e 's/^[[:space:]]*//' -e 's/"//g')"
+          security list-keychains -d user -s "$keychain_path" $existing
+      - name: install xcbeautify
+        run: brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
+      - name: build iOS release
+        env:
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          if [ "$CANONICAL_REPOSITORY" = true ]; then
+            scripts/build_ios.sh --fetch --device --release
+          else
+            scripts/build_ios.sh --fetch --release
+          fi
+      - name: upload iOS release artifact
+        id: upload-ipa
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        uses: actions/upload-artifact@v7
+        with:
+          name: gen1recomp-ios-ipa
+          path: dist/ios/gen1recomp.ipa
+          if-no-files-found: error
+          retention-days: 7
+      - name: clean up signing keychain
+        if: ${{ always() && github.repository == 'bryanthaboi/gen1recomp' }}
+        run: security delete-keychain "$RUNNER_TEMP/gen1recomp-ci-signing.keychain-db" 2>/dev/null || true
+
   headless:
     name: headless suites (no ROM)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # LuaJIT, not lua5.4: LOVE 11.x embeds LuaJIT 2.1 and the engine is
       # written to Lua 5.1 semantics, so CI must run the interpreter the
@@ -47,7 +124,7 @@ jobs:
     name: fixture dataset integrity
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: sudo apt-get update && sudo apt-get install -y luajit
       - run: python3 -m pip install --upgrade pillow
 
@@ -89,7 +166,7 @@ jobs:
     name: screenshot differ (capture not yet wired)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
       - run: python3 -m pip install --upgrade pillow
 
       # 21-testing-and-ci §"Testing & acceptance criteria": compare_shots
@@ -137,7 +214,7 @@ jobs:
     name: mod lint (no ROM-derived content)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       # the MK305 dump check key-diffs shipped tables through luajit, and
       # modkit treats a missing interpreter as a fatal MK100 -- without

.github/workflows/ios-artifact-comment.yml

@@ -0,0 +1,61 @@
+name: iOS artifact comment
+
+on:
+  workflow_run:
+    workflows: [ci]
+    types: [completed]
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+
+jobs:
+  comment:
+    if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - id: artifact
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RUN_ID: ${{ github.event.workflow_run.id }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          HEAD_REPOSITORY: ${{ github.event.workflow_run.head_repository.full_name }}
+        run: |
+          artifact_id="$(gh api "repos/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts" --jq '.artifacts[] | select(.name == "gen1recomp-ios-ipa") | .id')"
+          [ -n "$artifact_id" ] || exit 0
+          head_owner="${HEAD_REPOSITORY%%/*}"
+          pr_number="$(gh api "repos/$GITHUB_REPOSITORY/pulls?state=open&head=$head_owner:$HEAD_BRANCH" --jq '.[0].number // empty')"
+          [ -n "$pr_number" ] || exit 0
+          echo "artifact_url=https://github.com/$GITHUB_REPOSITORY/actions/runs/$RUN_ID/artifacts/$artifact_id" >> "$GITHUB_OUTPUT"
+          echo "pr_number=$pr_number" >> "$GITHUB_OUTPUT"
+      - name: Delete existing comment
+        if: steps.artifact.outputs.pr_number != ''
+        uses: izhangzhihao/delete-comment@master
+        with:
+          github_token: ${{ github.token }}
+          delete_user_name: github-actions[bot]
+          issue_number: ${{ steps.artifact.outputs.pr_number }}
+      - name: Get build info
+        id: build-info
+        env:
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          commit_hash="$(printf '%s' "$HEAD_SHA" | cut -c1-7)"
+          build_time="$(date "+%Y-%m-%d %H:%M:%S")"
+          echo "hash=$commit_hash" >> "$GITHUB_OUTPUT"
+          echo "time=$build_time" >> "$GITHUB_OUTPUT"
+      - name: comment iOS artifact
+        if: steps.artifact.outputs.pr_number != ''
+        uses: thollander/actions-comment-pull-request@v3
+        with:
+          message: |
+            [gen1recomp.ipa](${{ steps.artifact.outputs.artifact_url }})
+
+            **Commit**: [#${{ steps.build-info.outputs.hash }}](https://github.com/${{ github.event.workflow_run.head_repository.full_name }}/commit/${{ github.event.workflow_run.head_sha }})
+            **Build Time**: `${{ steps.build-info.outputs.time }}`
+
+            <sub>This comment was automatically generated. [View workflow run](https://github.com/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }})</sub>
+          pr-number: ${{ steps.artifact.outputs.pr_number }}
+          comment-tag: ios-build-result
+          github-token: ${{ github.token }}

.github/workflows/release.yml

@@ -24,6 +24,7 @@ on:
     paths-ignore:
       - '.github/**'
       - '**.md'
+      - 'mobile/ios/app-repo.json'
   workflow_dispatch:
     inputs:
       version:
@@ -42,11 +43,17 @@ concurrency:
 
 jobs:
   release:
-    runs-on: [self-hosted, macOS]
+    runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
 
     steps:
+      # The self-hosted runner lives under the machine owner's home
+      # directory; mask it first so absolute paths in every later step's
+      # output show up as *** in the public workflow logs.
+      - name: Mask runner paths
+        run: echo "::add-mask::$HOME"
+
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
           fetch-tags: true
@@ -121,6 +128,7 @@ jobs:
           echo "tag=$tag" >> "$GITHUB_OUTPUT"
 
       - name: Import signing certificate into a temporary keychain
+        if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
           set -euo pipefail
           KEYCHAIN_PATH="$RUNNER_TEMP/pokemon-signing.keychain-db"
@@ -170,14 +178,23 @@ jobs:
           set -euo pipefail
           scripts/build_android.sh --version "${{ steps.ver.outputs.version }}"
 
-      - name: Build iOS
+      - name: Install xcbeautify
         run: |
           set -euo pipefail
-          # Device Release IPA; signs with the Apple Development identity on
-          # the runner (auto team detection). Users on other Apple IDs still
-          # re-sign or build via docs/ios-install.md.
-          scripts/build_ios.sh --fetch --device --release \
-            --version "${{ steps.ver.outputs.version }}"
+          brew list xcbeautify >/dev/null 2>&1 || brew install xcbeautify
+
+      - name: Build iOS
+        env:
+          CANONICAL_REPOSITORY: ${{ github.repository == 'bryanthaboi/gen1recomp' }}
+        run: |
+          set -euo pipefail
+          if [ "$CANONICAL_REPOSITORY" = true ]; then
+            scripts/build_ios.sh --fetch --device --release \
+              --version "${{ steps.ver.outputs.version }}"
+          else
+            scripts/build_ios.sh --fetch --release \
+              --version "${{ steps.ver.outputs.version }}"
+          fi
 
       - name: Build Anbernic RG34XXSP port
         run: |
@@ -187,6 +204,7 @@ jobs:
           ./build-rg34xxsp.sh --version "${{ steps.ver.outputs.version }}"
 
       - name: Notarize & staple macOS app
+        if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
           set -euo pipefail
           ci_dir="${POKEMON_CI_DIR:-$HOME/.config/pokemon-ci}"
@@ -221,6 +239,7 @@ jobs:
           echo "Notarized + stapled ✓"
 
       - name: Stage release assets
+        if: github.repository == 'bryanthaboi/gen1recomp'
         id: assets
         run: |
           set -euo pipefail
@@ -260,6 +279,7 @@ jobs:
           cat "$outdir/sha256sums.txt"
 
       - name: Publish GitHub Release
+        if: github.repository == 'bryanthaboi/gen1recomp'
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
@@ -364,7 +384,72 @@ jobs:
 
           echo "Published release $tag"
 
+      - name: Update iOS app repository
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        run: |
+          set -euo pipefail
+          v="${{ steps.ver.outputs.version }}"
+          ipa="dist/release/gen1recomp-${v}-ios.ipa"
+          app_repo="mobile/ios/app-repo.json"
+          [ -f "$ipa" ] || { echo "::error::$ipa not found"; exit 1; }
+          [ -f "$app_repo" ] || { echo "::error::$app_repo not found"; exit 1; }
+
+          date="$(date -u +"%Y-%m-%d")"
+          size="$(wc -c < "$ipa" | tr -d '[:space:]')"
+          download_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/v${v}/gen1recomp-${v}-ios.ipa"
+          localized_description="Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
+          release_notes="$(GH_TOKEN="${{ github.token }}" gh release view "v${v}" --json body --jq '.body // ""' 2>/dev/null || true)"
+          if [ -n "$release_notes" ]; then
+            localized_description="$release_notes"
+          fi
+          entry="$(jq -n \
+            --arg version "$v" \
+            --arg date "$date" \
+            --arg download_url "$download_url" \
+            --arg localized_description "$localized_description" \
+            --argjson size "$size" \
+            '{version: $version, date: $date, size: $size, downloadURL: $download_url, localizedDescription: $localized_description}')"
+
+          if jq -e --arg version "$v" \
+            'any(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions[]?; .version == $version)' \
+            "$app_repo" >/dev/null; then
+            jq --arg version "$v" --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= map(if .version == $version then $entry else . end)' \
+              "$app_repo" > "$app_repo.tmp"
+          else
+            jq --argjson entry "$entry" \
+              '(.apps[] | select(.bundleIdentifier == "com.theboisclub.gen1recomp").versions) |= [$entry] + .' \
+              "$app_repo" > "$app_repo.tmp"
+          fi
+          mv "$app_repo.tmp" "$app_repo"
+
+      # main is PR-only for everyone except deploy keys (the "main protection"
+      # ruleset's bypass actor), so this push must authenticate with the
+      # RELEASE_DEPLOY_KEY deploy key over SSH; the workflow's GITHUB_TOKEN
+      # would be rejected by the branch protection.
+      - name: Commit iOS app repository
+        if: github.repository == 'bryanthaboi/gen1recomp'
+        env:
+          DEPLOY_KEY: ${{ secrets.RELEASE_DEPLOY_KEY }}
+        run: |
+          set -euo pipefail
+          git add mobile/ios/app-repo.json
+          if git diff --cached --quiet; then
+            echo "app-repo.json unchanged; nothing to push"
+            exit 0
+          fi
+          key="$RUNNER_TEMP/release-deploy-key"
+          printf '%s\n' "$DEPLOY_KEY" > "$key"
+          chmod 600 "$key"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -m "chore(ios): update app-repo.json [skip ci]"
+          git -c core.sshCommand="ssh -i $key -o IdentitiesOnly=yes -o StrictHostKeyChecking=accept-new" \
+            push "git@github.com:${GITHUB_REPOSITORY}.git" "HEAD:${GITHUB_REF_NAME}"
+          rm -f "$key"
+
       - name: Clean up signing keychain
-        if: always()
+        if: ${{ always() && github.repository == 'bryanthaboi/gen1recomp' }}
         run: |
           security delete-keychain "$RUNNER_TEMP/pokemon-signing.keychain-db" 2>/dev/null || true
+          rm -f "$RUNNER_TEMP/release-deploy-key"

.gitignore

@@ -16,6 +16,7 @@ __pycache__/
 .*
 !.github/
 !.gitignore
+!.luacheckrc
 
 # Android build outputs / local SDK path / packaged payload (keep love-android sources)
 mobile/android/app/build/

.luacheckrc

@@ -0,0 +1,43 @@
+-- Static-analysis config for `luacheck` (https://luacheck.readthedocs.io).
+--
+-- Run it over the engine with:  luacheck src   (or scripts/lint.sh)
+--
+-- The point is a high-signal baseline: the categories left on are the ones
+-- that catch real defects -- undefined globals/locals (the class that hid a
+-- `music.volume` crash: applyVolume read a `state` that was still the nil
+-- global), unused values, unreachable code, redefinitions. The cosmetic
+-- categories the codebase deliberately lives with (a `self`/`dt` an
+-- interface requires but a given method ignores, documented empty
+-- fall-through branches, the odd long line) are muted so they don't drown
+-- the signal.
+
+std = "luajit"
+
+-- LÖVE exposes `love` as a mutable table: games assign their callbacks onto
+-- it (love.wheelmoved, love.run, ...), so it is a regular global, not
+-- read-only -- otherwise every callback registration reads as a violation.
+globals = { "love" }
+
+read_globals = {
+  "jit",
+  -- LuaJIT 2.1 ships table.unpack even though the bare 5.1 `table` std lacks
+  -- it; without this, every `table.unpack` reads as an undefined field.
+  table = { fields = { "unpack" } },
+}
+
+-- Vendored/native trees and the test suites have their own conventions.
+exclude_files = {
+  "mobile/",
+  "tests/",
+  "tools/save-editor/",
+}
+
+ignore = {
+  "212",  -- unused argument -- self/dt kept for a shared method signature
+  "213",  -- unused loop variable -- `for _, v in` where only v is wanted
+  "421",  -- shadowing a local -- deliberate re-use in a few tight scopes
+  "431",  -- shadowing an upvalue
+  "432",  -- shadowing an argument
+  "542",  -- empty if branch -- documented fall-throughs, not gaps
+  "631",  -- line is too long
+}

CONTRIBUTING-mods.md

@@ -118,6 +118,7 @@ not a hard error, so the list can grow without breaking old mods.
 | `QUEST` | New story, NPCs, dialogue, cutscenes | content |
 | `MECHANIC` | New or changed battle/field mechanics via hooks/effects | overhaul |
 | `GRAPHICS` | Sprite / tileset / palette / font changes | content |
+| `LANGUAGE` | A translation: `text`, `strings` and the glyphs it needs | content |
 | `AUDIO` | Music, sfx, cries | content |
 | `UI` | New or modified screens, menus, overlays | content / overhaul |
 | `TOOL` | Dev/QoL utilities, overlays, inter-mod libraries | content |
@@ -128,6 +129,15 @@ not a hard error, so the list can grow without breaking old mods.
 keeps validating with the value it has shipped since before the taxonomy
 existed.
 
+A translation may also set `"language": true` in the manifest. That is the
+one claim online play acts on: an install running nothing but verified
+translations may take an ONLINE MATCH or a TOURNAMENT instead of being
+asked to restart vanilla. The claim is checked, not taken -- the mod
+qualifies only if every record it writes lands in `text`, `strings` or
+`font`, it wraps no hook, subscribes to no event and requests no
+permission. Anything else and it is an ordinary content mod that happens to
+ship text.
+
 ### 4. `mod.card`
 
 The manifest is the *engine's* contract: identity, load order, dependencies,

README.md

@@ -4,6 +4,9 @@ A native LÖVE2D recreation of Poke Red, Blue and Yellow. The engine and map
 behavior are hand-written Lua; game data and graphics are decoded from a ROM
 supplied by the player.
 
+> [!CAUTION]
+> **We are NOT affiliated with the website `gen1recomp[.]com`** That website is not run by this project, was not authorized by us, and we have no idea who operates it. It is impersonating this project; do not download anything from it, and treat anything it hosts or claims as untrustworthy. Even if the site currently links back to this repository, the people behind it can change its content at any time, so nothing on it should ever be trusted. This GitHub repository and the Discord linked below are the only official sources for this project.
+
 <p align="center"><img src="https://raw.githubusercontent.com/bryanthaboi/gen1recomp/refs/heads/dev/assets/logo/logo.png"></p>
 
 **SUPPORT / ANNOUNCEMENTS / MODS:** [Discord](https://bois.icu)
@@ -75,6 +78,19 @@ The packaged app contains neither a ROM nor pre-extracted game data. Music,
 sound effects, and cries are synthesized while the game runs from compact
 audio channel programs copied out of the verified ROM.
 
+### A note on Windows Defender warnings
+
+Windows Defender sometimes flags the Windows build with a generic
+machine-learning detection such as `Trojan:Win32/Wacatac!ml` (#621). This is
+a known false positive: the exe is the official LÖVE runtime with the game
+archive appended (the standard way LÖVE games ship), and Defender's
+heuristics distrust unsigned executables with appended data. Every release
+publishes SHA-256 checksums (`sha256sums.txt`) so you can verify your
+download, and you can confirm a flagged file yourself on
+[VirusTotal](https://www.virustotal.com), where these builds come back clean
+on every engine except Defender's heuristic. False positives are reported to
+Microsoft as they come up.
+
 ## Controls
 
 
@@ -96,6 +112,7 @@ supported out of the box.
 | Key       | What it does                                         |
 | --------- | ---------------------------------------------------- |
 | `-` / `=` | Zoom out / in (overworld; also mouse wheel)          |
+| `1`       | Cycle GAME SPEED up (controller: R2 faster, L2 slower) |
 | `2`       | Cycle COLORS                                         |
 | `3`       | Cycle TILT (free-roam overworld)                     |
 | `4`       | Cycle ZOOM through every level (free-roam overworld) |
@@ -105,8 +122,19 @@ supported out of the box.
 | `F10`     | Open / close the mod manager                         |
 
 
-COLORS, TILT, ZOOM, GBC FX, and VOID FILL are also in the Options menu
-and persist in `options.lua`.
+COLORS, TILT, ZOOM, GBC FX, GAME SPEED, and VOID FILL are also in the
+Options menu and persist in `options.lua`.
+
+### Low-end devices
+
+**OPTIONS → PERFORMANCE** scales the port's optional extras for weaker
+hardware: **HIGH** (everything on), **BALANCED** (no 3D tilt or GBC FX),
+**LOW** (also no survey zoom, FPS capped), or **AUTO** — the default, which
+picks a tier from your device (ARM handhelds → LOW, phones → BALANCED,
+normal desktops → HIGH, unchanged). It only scales presentation; the
+fixed-step game logic is identical on every tier, and a lower tier hides
+your tilt/zoom/GBC-FX preferences without forgetting them. Details in
+[docs/new-features.md](docs/new-features.md#performance-tier-low-end-devices).
 
 ### Rulesets
 
@@ -184,6 +212,16 @@ Every release ships `gen1recomp-*-ios.ipa`. Sideload it with AltStore
 build and install from source on a Mac instead, see
 [docs/ios-install.md](docs/ios-install.md).
 
+<div>
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=sidestore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/sidestore-badge.png" alt="Add to SideStore" height="60"></a>
+    &nbsp;
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=feather://source/https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/feather-badge.png" alt="Add to Feather" height="60"></a>
+    &nbsp;
+    <a href="https://intradeus.github.io/http-protocol-redirector?r=altstore://source?url=https://github.com/bryanthaboi/gen1recomp/raw/refs/heads/main/mobile/ios/app-repo.json"><img src="./.github/resources/altstore-badge.png" alt="Add to AltStore" height="60"></a>
+    &nbsp;
+    <a href="https://github.com/bryanthaboi/gen1recomp/releases/latest"><img src="./.github/resources/github-badge.png" alt="Download from GitHub" height="60"></a>
+</div>
+
 ## Handhelds
 
 A PortMaster-style port for the **Anbernic RG34XXSP** on Stock OS 64-bit MOD

conf.lua

@@ -1,4 +1,9 @@
 function love.conf(t)
+  -- PhysFS ignores symlinks unless told otherwise, so a mod dev-linked into
+  -- mods/ (ln -s, matching the mklink /J workflow on Windows) is invisible
+  -- to love.filesystem.getDirectoryItems without this.
+  love.filesystem.setSymlinksEnabled(true)
+
   local editor = os.getenv("POKEPORT_EDITOR") == "1"
   local developer = os.getenv("POKEPORT_DEV") == "1"
   if arg then
@@ -44,7 +49,7 @@ function love.conf(t)
     t.window.minwidth = 480
     t.window.minheight = 360
   end
-  t.version = "11.5"
+  t.version = love._os == "iOS" and "12.0" or "11.5"
   t.window.vsync = 1
   t.modules.joystick = true
   t.modules.physics = false
@@ -62,7 +67,10 @@ function love.conf(t)
     -- the game follow the device.  The renderer letterboxes the 160x144
     -- viewport into whatever size results, and the on-screen touch controls
     -- re-lay themselves out from the new window size, so both orientations
-    -- just work.  iOS follows the Info.plist orientations
+    -- just work.  FULL_SENSOR ignores the device's rotation lock, so
+    -- GameActivity.setOrientationBis remaps it to FULL_USER after SDL has
+    -- run: same orientations allowed, but auto-rotate being off now wins.
+    -- iOS follows the Info.plist orientations
     -- (see mobile/ios/overlays/love-ios.plist, now portrait + landscape).
     t.window.resizable = true
     -- Starting size is a tall portrait hint; the OS resizes to the real

data/palettes_gbc.lua

@@ -1683,158 +1683,172 @@ return {
       { 0, 0, 0 },
     },
   },
+  -- Species -> palette NAME, taken from pokered-gbc data/pokemon/palettes.asm
+  -- ELSE branch -- the one that is NOT gated on GEN_2_GRAPHICS.
+  --
+  -- That file has two tables.  The IF GEN_2_GRAPHICS branch assigns a
+  -- PER-SPECIES palette (PAL_BULBASAUR, PAL_SQUIRTLE, ...) authored for Gen 2
+  -- sprite art; the ELSE branch keeps Gen 1's own assignments (GREENMON,
+  -- CYANMON, ...).  This port extracts Gen 1 pics from the ROM, so the Gen 1
+  -- branch is the matching one.  The per-species table was imported here by
+  -- mistake, which pointed every mon at colours shaded for different art:
+  -- Bulbasaur wore PAL_BULBASAUR's red-orange over a sprite that has no red
+  -- on it, and Squirtle wore PAL_SQUIRTLE's shell brown on his head.
+  --
+  -- The palette VALUES below are still pokered-gbc's, so ADVANCED keeps its
+  -- richer colours -- only which palette each species points at changed.
   pokemon = {
-    ABRA = "ABRA",
-    AERODACTYL = "AERODACTYL",
-    ALAKAZAM = "ALAKAZAM",
-    ARBOK = "ARBOK",
-    ARCANINE = "ARCANINE",
-    ARTICUNO = "ARTICUNO",
-    BEEDRILL = "BEEDRILL",
-    BELLSPROUT = "BELLSPROUT",
-    BLASTOISE = "BLASTOISE",
-    BULBASAUR = "BULBASAUR",
-    BUTTERFREE = "BUTTERFREE",
-    CATERPIE = "CATERPIE",
-    CHANSEY = "CHANSEY",
-    CHARIZARD = "CHARIZARD",
-    CHARMANDER = "CHARMANDER",
-    CHARMELEON = "CHARMELEON",
-    CLEFABLE = "CLEFABLE",
-    CLEFAIRY = "CLEFAIRY",
-    CLOYSTER = "CLOYSTER",
-    CUBONE = "CUBONE",
-    DEWGONG = "DEWGONG",
-    DIGLETT = "DIGLETT",
-    DITTO = "DITTO",
-    DODRIO = "DODRIO",
-    DODUO = "DODUO",
-    DRAGONAIR = "DRAGONAIR",
-    DRAGONITE = "DRAGONITE",
-    DRATINI = "DRATINI",
-    DROWZEE = "DROWZEE",
-    DUGTRIO = "DUGTRIO",
-    EEVEE = "EEVEE",
-    EKANS = "EKANS",
-    ELECTABUZZ = "ELECTABUZZ",
-    ELECTRODE = "ELECTRODE",
-    EXEGGCUTE = "EXEGGCUTE",
-    EXEGGUTOR = "EXEGGUTOR",
-    FARFETCHD = "FARFETCH_D",
-    FEAROW = "FEAROW",
-    FLAREON = "FLAREON",
-    GASTLY = "GASTLY",
-    GENGAR = "GENGAR",
-    GEODUDE = "GEODUDE",
-    GLOOM = "GLOOM",
-    GOLBAT = "GOLBAT",
-    GOLDEEN = "GOLDEEN",
-    GOLDUCK = "GOLDUCK",
-    GOLEM = "GOLEM",
-    GRAVELER = "GRAVELER",
-    GRIMER = "GRIMER",
-    GROWLITHE = "GROWLITHE",
-    GYARADOS = "GYARADOS",
-    HAUNTER = "HAUNTER",
-    HITMONCHAN = "HITMONCHAN",
-    HITMONLEE = "HITMONLEE",
-    HORSEA = "HORSEA",
-    HYPNO = "HYPNO",
-    IVYSAUR = "IVYSAUR",
-    JIGGLYPUFF = "JIGGLYPUFF",
-    JOLTEON = "JOLTEON",
-    JYNX = "JYNX",
-    KABUTO = "KABUTO",
-    KABUTOPS = "KABUTOPS",
-    KADABRA = "KADABRA",
-    KAKUNA = "KAKUNA",
-    KANGASKHAN = "KANGASKHAN",
-    KINGLER = "KINGLER",
-    KOFFING = "KOFFING",
-    KRABBY = "KRABBY",
-    LAPRAS = "LAPRAS",
-    LICKITUNG = "LICKITUNG",
-    MACHAMP = "MACHAMP",
-    MACHOKE = "MACHOKE",
-    MACHOP = "MACHOP",
-    MAGIKARP = "MAGIKARP",
-    MAGMAR = "MAGMAR",
-    MAGNEMITE = "MAGNEMITE",
-    MAGNETON = "MAGNETON",
-    MANKEY = "MANKEY",
-    MAROWAK = "MAROWAK",
-    MEOWTH = "MEOWTH",
-    METAPOD = "METAPOD",
-    MEW = "MEW",
-    MEWTWO = "MEWTWO",
-    MOLTRES = "MOLTRES",
-    MR_MIME = "MR_MIME",
-    MUK = "MUK",
-    NIDOKING = "NIDOKING",
-    NIDOQUEEN = "NIDOQUEEN",
-    NIDORAN_F = "NIDORAN_F",
-    NIDORAN_M = "NIDORAN_M",
-    NIDORINA = "NIDORINA",
-    NIDORINO = "NIDORINO",
-    NINETALES = "NINETALES",
-    ODDISH = "ODDISH",
-    OMANYTE = "OMANYTE",
-    OMASTAR = "OMASTAR",
-    ONIX = "ONIX",
-    PARAS = "PARAS",
-    PARASECT = "PARASECT",
-    PERSIAN = "PERSIAN",
-    PIDGEOT = "PIDGEOT",
-    PIDGEOTTO = "PIDGEOTTO",
-    PIDGEY = "PIDGEY",
-    PIKACHU = "PIKACHU",
-    PINSIR = "PINSIR",
-    POLIWAG = "POLIWAG",
-    POLIWHIRL = "POLIWHIRL",
-    POLIWRATH = "POLIWRATH",
-    PONYTA = "PONYTA",
-    PORYGON = "PORYGON",
-    PRIMEAPE = "PRIMEAPE",
-    PSYDUCK = "PSYDUCK",
-    RAICHU = "RAICHU",
-    RAPIDASH = "RAPIDASH",
-    RATICATE = "RATICATE",
-    RATTATA = "RATTATA",
-    RHYDON = "RHYDON",
-    RHYHORN = "RHYHORN",
-    SANDSHREW = "SANDSHREW",
-    SANDSLASH = "SANDSLASH",
-    SCYTHER = "SCYTHER",
-    SEADRA = "SEADRA",
-    SEAKING = "SEAKING",
-    SEEL = "SEEL",
-    SHELLDER = "SHELLDER",
-    SLOWBRO = "SLOWBRO",
-    SLOWPOKE = "SLOWPOKE",
-    SNORLAX = "SNORLAX",
-    SPEAROW = "SPEAROW",
-    SQUIRTLE = "SQUIRTLE",
-    STARMIE = "STARMIE",
-    STARYU = "STARYU",
-    TANGELA = "TANGELA",
-    TAUROS = "TAUROS",
-    TENTACOOL = "TENTACOOL",
-    TENTACRUEL = "TENTACRUEL",
-    VAPOREON = "VAPOREON",
-    VENOMOTH = "VENOMOTH",
-    VENONAT = "VENONAT",
-    VENUSAUR = "VENUSAUR",
-    VICTREEBEL = "VICTREEBEL",
-    VILEPLUME = "VILEPLUME",
-    VOLTORB = "VOLTORB",
-    VULPIX = "VULPIX",
-    WARTORTLE = "WARTORTLE",
-    WEEDLE = "WEEDLE",
-    WEEPINBELL = "WEEPINBELL",
-    WEEZING = "WEEZING",
-    WIGGLYTUFF = "WIGGLYTUFF",
-    ZAPDOS = "ZAPDOS",
-    ZUBAT = "ZUBAT",
+    ABRA = "YELLOWMON",
+    AERODACTYL = "GRAYMON",
+    ALAKAZAM = "YELLOWMON",
+    ARBOK = "PURPLEMON",
+    ARCANINE = "REDMON",
+    ARTICUNO = "BLUEMON",
+    BEEDRILL = "YELLOWMON",
+    BELLSPROUT = "GREENMON",
+    BLASTOISE = "CYANMON",
+    BULBASAUR = "GREENMON",
+    BUTTERFREE = "CYANMON",
+    CATERPIE = "GREENMON",
+    CHANSEY = "PINKMON",
+    CHARIZARD = "REDMON",
+    CHARMANDER = "REDMON",
+    CHARMELEON = "REDMON",
+    CLEFABLE = "PINKMON",
+    CLEFAIRY = "PINKMON",
+    CLOYSTER = "GRAYMON",
+    CUBONE = "GRAYMON",
+    DEWGONG = "BLUEMON",
+    DIGLETT = "BROWNMON",
+    DITTO = "GRAYMON",
+    DODRIO = "BROWNMON",
+    DODUO = "BROWNMON",
+    DRAGONAIR = "BLUEMON",
+    DRAGONITE = "BROWNMON",
+    DRATINI = "GRAYMON",
+    DROWZEE = "YELLOWMON",
+    DUGTRIO = "BROWNMON",
+    EEVEE = "GRAYMON",
+    EKANS = "PURPLEMON",
+    ELECTABUZZ = "YELLOWMON",
+    ELECTRODE = "YELLOWMON",
+    EXEGGCUTE = "PINKMON",
+    EXEGGUTOR = "GREENMON",
+    FARFETCHD = "BROWNMON",
+    FEAROW = "BROWNMON",
+    FLAREON = "REDMON",
+    GASTLY = "PURPLEMON",
+    GENGAR = "PURPLEMON",
+    GEODUDE = "GRAYMON",
+    GLOOM = "REDMON",
+    GOLBAT = "BLUEMON",
+    GOLDEEN = "REDMON",
+    GOLDUCK = "CYANMON",
+    GOLEM = "GRAYMON",
+    GRAVELER = "GRAYMON",
+    GRIMER = "PURPLEMON",
+    GROWLITHE = "BROWNMON",
+    GYARADOS = "BLUEMON",
+    HAUNTER = "PURPLEMON",
+    HITMONCHAN = "BROWNMON",
+    HITMONLEE = "BROWNMON",
+    HORSEA = "CYANMON",
+    HYPNO = "YELLOWMON",
+    IVYSAUR = "GREENMON",
+    JIGGLYPUFF = "PINKMON",
+    JOLTEON = "YELLOWMON",
+    JYNX = "MEWMON",
+    KABUTO = "BROWNMON",
+    KABUTOPS = "BROWNMON",
+    KADABRA = "YELLOWMON",
+    KAKUNA = "YELLOWMON",
+    KANGASKHAN = "BROWNMON",
+    KINGLER = "REDMON",
+    KOFFING = "PURPLEMON",
+    KRABBY = "REDMON",
+    LAPRAS = "CYANMON",
+    LICKITUNG = "PINKMON",
+    MACHAMP = "GRAYMON",
+    MACHOKE = "GRAYMON",
+    MACHOP = "GRAYMON",
+    MAGIKARP = "REDMON",
+    MAGMAR = "REDMON",
+    MAGNEMITE = "GRAYMON",
+    MAGNETON = "GRAYMON",
+    MANKEY = "BROWNMON",
+    MAROWAK = "GRAYMON",
+    MEOWTH = "YELLOWMON",
+    METAPOD = "GREENMON",
+    MEW = "MEWMON",
+    MEWTWO = "MEWMON",
+    MOLTRES = "REDMON",
+    MR_MIME = "PINKMON",
+    MUK = "PURPLEMON",
+    NIDOKING = "PURPLEMON",
+    NIDOQUEEN = "BLUEMON",
+    NIDORAN_F = "BLUEMON",
+    NIDORAN_M = "PURPLEMON",
+    NIDORINA = "BLUEMON",
+    NIDORINO = "PURPLEMON",
+    NINETALES = "YELLOWMON",
+    ODDISH = "GREENMON",
+    OMANYTE = "BLUEMON",
+    OMASTAR = "BLUEMON",
+    ONIX = "GRAYMON",
+    PARAS = "REDMON",
+    PARASECT = "REDMON",
+    PERSIAN = "YELLOWMON",
+    PIDGEOT = "BROWNMON",
+    PIDGEOTTO = "BROWNMON",
+    PIDGEY = "BROWNMON",
+    PIKACHU = "YELLOWMON",
+    PINSIR = "BROWNMON",
+    POLIWAG = "BLUEMON",
+    POLIWHIRL = "BLUEMON",
+    POLIWRATH = "BLUEMON",
+    PONYTA = "REDMON",
+    PORYGON = "GRAYMON",
+    PRIMEAPE = "BROWNMON",
+    PSYDUCK = "YELLOWMON",
+    RAICHU = "YELLOWMON",
+    RAPIDASH = "REDMON",
+    RATICATE = "GRAYMON",
+    RATTATA = "GRAYMON",
+    RHYDON = "GRAYMON",
+    RHYHORN = "GRAYMON",
+    SANDSHREW = "BROWNMON",
+    SANDSLASH = "BROWNMON",
+    SCYTHER = "GREENMON",
+    SEADRA = "CYANMON",
+    SEAKING = "REDMON",
+    SEEL = "BLUEMON",
+    SHELLDER = "GRAYMON",
+    SLOWBRO = "PINKMON",
+    SLOWPOKE = "PINKMON",
+    SNORLAX = "PINKMON",
+    SPEAROW = "BROWNMON",
+    SQUIRTLE = "CYANMON",
+    STARMIE = "GRAYMON",
+    STARYU = "REDMON",
+    TANGELA = "BLUEMON",
+    TAUROS = "GRAYMON",
+    TENTACOOL = "CYANMON",
+    TENTACRUEL = "CYANMON",
+    VAPOREON = "CYANMON",
+    VENOMOTH = "PURPLEMON",
+    VENONAT = "PURPLEMON",
+    VENUSAUR = "GREENMON",
+    VICTREEBEL = "GREENMON",
+    VILEPLUME = "REDMON",
+    VOLTORB = "YELLOWMON",
+    VULPIX = "REDMON",
+    WARTORTLE = "CYANMON",
+    WEEDLE = "YELLOWMON",
+    WEEPINBELL = "GREENMON",
+    WEEZING = "PURPLEMON",
+    WIGGLYTUFF = "PINKMON",
+    ZAPDOS = "YELLOWMON",
+    ZUBAT = "BLUEMON",
   },
   source = "pokered-gbc data/super_palettes.asm + data/mon_palettes.asm + color/**",
   world = {

data/palettes_yellow.lua

@@ -0,0 +1,686 @@
+-- Generated by tools/build_data.py. DO NOT EDIT.
+-- Pokemon Yellow palettes (COLORS=OG YELLOW): SuperPalettes +
+-- CGBBasePalettes (authentic GBC look) as 4 8-bit RGB colors
+-- per palette (color 0 first), plus MonsterPalettes.
+return {
+  cgbBase = {
+    ["0F"] = {
+      { 255, 255, 255 },
+      { 107, 8, 255 },
+      { 0, 74, 255 },
+      { 8, 8, 8 },
+    },
+    BADGE = {
+      { 255, 255, 255 },
+      { 189, 66, 0 },
+      { 140, 115, 90 },
+      { 25, 25, 25 },
+    },
+    BLACK = {
+      { 255, 255, 255 },
+      { 25, 25, 25 },
+      { 25, 25, 25 },
+      { 25, 25, 25 },
+    },
+    BLUEMON = {
+      { 255, 255, 255 },
+      { 132, 148, 255 },
+      { 0, 8, 206 },
+      { 25, 25, 25 },
+    },
+    BROWNMON = {
+      { 255, 255, 255 },
+      { 239, 148, 82 },
+      { 140, 74, 41 },
+      { 25, 25, 25 },
+    },
+    CAVE = {
+      { 255, 255, 255 },
+      { 189, 66, 0 },
+      { 140, 115, 90 },
+      { 25, 25, 25 },
+    },
+    CELADON = {
+      { 255, 255, 255 },
+      { 41, 255, 41 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CERULEAN = {
+      { 255, 255, 255 },
+      { 41, 66, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CINNABAR = {
+      { 255, 255, 255 },
+      { 255, 66, 66 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    CYANMON = {
+      { 255, 255, 255 },
+      { 132, 214, 255 },
+      { 0, 140, 255 },
+      { 25, 25, 25 },
+    },
+    FUCHSIA = {
+      { 255, 255, 255 },
+      { 255, 123, 123 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    GAMEFREAK = {
+      { 255, 255, 255 },
+      { 255, 156, 0 },
+      { 156, 156, 0 },
+      { 25, 25, 25 },
+    },
+    GRAYMON = {
+      { 255, 255, 255 },
+      { 165, 189, 82 },
+      { 90, 90, 41 },
+      { 25, 25, 25 },
+    },
+    GREENBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 0, 255, 0 },
+      { 25, 25, 25 },
+    },
+    GREENMON = {
+      { 255, 255, 255 },
+      { 140, 255, 90 },
+      { 8, 181, 49 },
+      { 25, 25, 25 },
+    },
+    INDIGO = {
+      { 255, 255, 255 },
+      { 90, 66, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    LAVENDER = {
+      { 255, 255, 255 },
+      { 206, 33, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    LOGO1 = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 0, 0 },
+      { 255, 0, 0 },
+    },
+    LOGO2 = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 58, 58, 206 },
+      { 0, 0, 140 },
+    },
+    MEWMON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 8, 8 },
+      { 25, 25, 25 },
+    },
+    PALLET = {
+      { 255, 255, 255 },
+      { 189, 140, 255 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PEWTER = {
+      { 255, 255, 255 },
+      { 148, 148, 123 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PIKACHUS_BEACH = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    PIKACHUS_BEACH_TITLE = {
+      { 255, 255, 255 },
+      { 74, 74, 74 },
+      { 255, 173, 0 },
+      { 25, 25, 25 },
+    },
+    PIKACHU_PORTRAIT = {
+      { 255, 255, 255 },
+      { 255, 148, 0 },
+      { 156, 58, 8 },
+      { 25, 25, 25 },
+    },
+    PINKMON = {
+      { 255, 255, 255 },
+      { 255, 123, 148 },
+      { 255, 0, 49 },
+      { 25, 25, 25 },
+    },
+    PURPLEMON = {
+      { 255, 255, 255 },
+      { 206, 123, 255 },
+      { 156, 0, 181 },
+      { 25, 25, 25 },
+    },
+    REDBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    REDMON = {
+      { 255, 255, 255 },
+      { 255, 140, 0 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    ROUTE = {
+      { 255, 255, 255 },
+      { 132, 255, 33 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    SAFFRON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    SLOTS1 = {
+      { 255, 255, 255 },
+      { 206, 8, 255 },
+      { 255, 0, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS2 = {
+      { 255, 255, 255 },
+      { 255, 33, 156 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS3 = {
+      { 255, 255, 255 },
+      { 66, 255, 0 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    SLOTS4 = {
+      { 255, 255, 255 },
+      { 0, 255, 255 },
+      { 255, 255, 0 },
+      { 25, 25, 25 },
+    },
+    TOWNMAP = {
+      { 255, 255, 255 },
+      { 0, 173, 255 },
+      { 82, 230, 0 },
+      { 8, 8, 8 },
+    },
+    VERMILION = {
+      { 255, 255, 255 },
+      { 255, 156, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    VIRIDIAN = {
+      { 255, 255, 255 },
+      { 156, 255, 0 },
+      { 90, 189, 255 },
+      { 25, 25, 25 },
+    },
+    YELLOWBAR = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 255, 148, 0 },
+      { 25, 25, 25 },
+    },
+    YELLOWMON = {
+      { 255, 255, 255 },
+      { 255, 255, 0 },
+      { 230, 115, 0 },
+      { 25, 25, 25 },
+    },
+  },
+  order = {
+    "ROUTE",
+    "PALLET",
+    "VIRIDIAN",
+    "PEWTER",
+    "CERULEAN",
+    "LAVENDER",
+    "VERMILION",
+    "CELADON",
+    "FUCHSIA",
+    "CINNABAR",
+    "INDIGO",
+    "SAFFRON",
+    "TOWNMAP",
+    "LOGO1",
+    "LOGO2",
+    "0F",
+    "MEWMON",
+    "BLUEMON",
+    "REDMON",
+    "CYANMON",
+    "PURPLEMON",
+    "BROWNMON",
+    "GREENMON",
+    "PINKMON",
+    "YELLOWMON",
+    "GRAYMON",
+    "SLOTS1",
+    "SLOTS2",
+    "SLOTS3",
+    "SLOTS4",
+    "BLACK",
+    "GREENBAR",
+    "YELLOWBAR",
+    "REDBAR",
+    "BADGE",
+    "CAVE",
+    "GAMEFREAK",
+    "PIKACHUS_BEACH",
+    "PIKACHU_PORTRAIT",
+    "PIKACHUS_BEACH_TITLE",
+  },
+  palettes = {
+    ["0F"] = {
+      { 255, 255, 247 },
+      { 197, 165, 247 },
+      { 90, 165, 247 },
+      { 25, 16, 16 },
+    },
+    BADGE = {
+      { 255, 255, 247 },
+      { 165, 123, 90 },
+      { 181, 173, 165 },
+      { 49, 49, 49 },
+    },
+    BLACK = {
+      { 255, 255, 247 },
+      { 49, 49, 49 },
+      { 49, 49, 49 },
+      { 49, 49, 49 },
+    },
+    BLUEMON = {
+      { 255, 255, 247 },
+      { 173, 181, 255 },
+      { 74, 82, 165 },
+      { 49, 49, 49 },
+    },
+    BROWNMON = {
+      { 255, 255, 247 },
+      { 214, 189, 148 },
+      { 148, 115, 82 },
+      { 49, 49, 49 },
+    },
+    CAVE = {
+      { 255, 255, 247 },
+      { 165, 123, 90 },
+      { 181, 173, 165 },
+      { 49, 49, 49 },
+    },
+    CELADON = {
+      { 255, 255, 247 },
+      { 181, 255, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CERULEAN = {
+      { 255, 255, 247 },
+      { 181, 189, 255 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CINNABAR = {
+      { 255, 255, 247 },
+      { 255, 123, 115 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    CYANMON = {
+      { 255, 255, 247 },
+      { 214, 230, 255 },
+      { 58, 197, 230 },
+      { 49, 49, 49 },
+    },
+    FUCHSIA = {
+      { 255, 255, 247 },
+      { 255, 214, 214 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    GAMEFREAK = {
+      { 255, 255, 247 },
+      { 230, 197, 115 },
+      { 165, 165, 90 },
+      { 49, 49, 49 },
+    },
+    GRAYMON = {
+      { 255, 255, 247 },
+      { 206, 206, 148 },
+      { 132, 132, 115 },
+      { 49, 49, 49 },
+    },
+    GREENBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 0, 173, 0 },
+      { 49, 49, 49 },
+    },
+    GREENMON = {
+      { 255, 255, 247 },
+      { 197, 230, 148 },
+      { 107, 173, 123 },
+      { 49, 49, 49 },
+    },
+    INDIGO = {
+      { 255, 255, 247 },
+      { 140, 140, 206 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    LAVENDER = {
+      { 255, 255, 247 },
+      { 222, 189, 239 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    LOGO1 = {
+      { 255, 255, 247 },
+      { 247, 247, 140 },
+      { 173, 0, 33 },
+      { 173, 0, 33 },
+    },
+    LOGO2 = {
+      { 255, 255, 247 },
+      { 247, 247, 140 },
+      { 148, 148, 197 },
+      { 58, 58, 132 },
+    },
+    MEWMON = {
+      { 255, 255, 247 },
+      { 255, 247, 181 },
+      { 222, 132, 132 },
+      { 49, 49, 49 },
+    },
+    PALLET = {
+      { 255, 255, 247 },
+      { 230, 222, 255 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PEWTER = {
+      { 255, 255, 247 },
+      { 189, 189, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PIKACHUS_BEACH = {
+      { 255, 255, 247 },
+      { 255, 247, 181 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    PIKACHUS_BEACH_TITLE = {
+      { 255, 255, 247 },
+      { 132, 132, 132 },
+      { 255, 206, 74 },
+      { 49, 49, 49 },
+    },
+    PIKACHU_PORTRAIT = {
+      { 255, 255, 247 },
+      { 230, 189, 74 },
+      { 148, 115, 82 },
+      { 49, 49, 49 },
+    },
+    PINKMON = {
+      { 255, 255, 247 },
+      { 255, 197, 214 },
+      { 255, 148, 173 },
+      { 49, 49, 49 },
+    },
+    PURPLEMON = {
+      { 255, 255, 247 },
+      { 222, 181, 247 },
+      { 181, 123, 189 },
+      { 49, 49, 49 },
+    },
+    REDBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    REDMON = {
+      { 255, 255, 247 },
+      { 255, 197, 90 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    ROUTE = {
+      { 255, 255, 247 },
+      { 189, 214, 156 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    SAFFRON = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    SLOTS1 = {
+      { 255, 255, 247 },
+      { 222, 181, 247 },
+      { 214, 74, 49 },
+      { 49, 49, 49 },
+    },
+    SLOTS2 = {
+      { 255, 255, 247 },
+      { 255, 189, 214 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    SLOTS3 = {
+      { 255, 255, 247 },
+      { 189, 255, 165 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    SLOTS4 = {
+      { 255, 255, 247 },
+      { 189, 239, 255 },
+      { 239, 239, 66 },
+      { 49, 49, 49 },
+    },
+    TOWNMAP = {
+      { 255, 255, 247 },
+      { 165, 214, 255 },
+      { 140, 189, 82 },
+      { 25, 16, 16 },
+    },
+    VERMILION = {
+      { 255, 255, 247 },
+      { 255, 206, 132 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    VIRIDIAN = {
+      { 255, 255, 247 },
+      { 214, 255, 173 },
+      { 189, 222, 255 },
+      { 49, 49, 49 },
+    },
+    YELLOWBAR = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 230, 189, 74 },
+      { 49, 49, 49 },
+    },
+    YELLOWMON = {
+      { 255, 255, 247 },
+      { 255, 255, 156 },
+      { 230, 189, 74 },
+      { 49, 49, 49 },
+    },
+  },
+  pokemon = {
+    ABRA = "YELLOWMON",
+    AERODACTYL = "GRAYMON",
+    ALAKAZAM = "YELLOWMON",
+    ARBOK = "PURPLEMON",
+    ARCANINE = "REDMON",
+    ARTICUNO = "BLUEMON",
+    BEEDRILL = "YELLOWMON",
+    BELLSPROUT = "GREENMON",
+    BLASTOISE = "CYANMON",
+    BULBASAUR = "GREENMON",
+    BUTTERFREE = "CYANMON",
+    CATERPIE = "GREENMON",
+    CHANSEY = "PINKMON",
+    CHARIZARD = "REDMON",
+    CHARMANDER = "REDMON",
+    CHARMELEON = "REDMON",
+    CLEFABLE = "PINKMON",
+    CLEFAIRY = "PINKMON",
+    CLOYSTER = "GRAYMON",
+    CUBONE = "GRAYMON",
+    DEWGONG = "BLUEMON",
+    DIGLETT = "BROWNMON",
+    DITTO = "GRAYMON",
+    DODRIO = "BROWNMON",
+    DODUO = "BROWNMON",
+    DRAGONAIR = "BLUEMON",
+    DRAGONITE = "BROWNMON",
+    DRATINI = "GRAYMON",
+    DROWZEE = "YELLOWMON",
+    DUGTRIO = "BROWNMON",
+    EEVEE = "GRAYMON",
+    EKANS = "PURPLEMON",
+    ELECTABUZZ = "YELLOWMON",
+    ELECTRODE = "YELLOWMON",
+    EXEGGCUTE = "PINKMON",
+    EXEGGUTOR = "GREENMON",
+    FARFETCHD = "BROWNMON",
+    FEAROW = "BROWNMON",
+    FLAREON = "REDMON",
+    GASTLY = "PURPLEMON",
+    GENGAR = "PURPLEMON",
+    GEODUDE = "GRAYMON",
+    GLOOM = "REDMON",
+    GOLBAT = "BLUEMON",
+    GOLDEEN = "REDMON",
+    GOLDUCK = "CYANMON",
+    GOLEM = "GRAYMON",
+    GRAVELER = "GRAYMON",
+    GRIMER = "PURPLEMON",
+    GROWLITHE = "BROWNMON",
+    GYARADOS = "BLUEMON",
+    HAUNTER = "PURPLEMON",
+    HITMONCHAN = "BROWNMON",
+    HITMONLEE = "BROWNMON",
+    HORSEA = "CYANMON",
+    HYPNO = "YELLOWMON",
+    IVYSAUR = "GREENMON",
+    JIGGLYPUFF = "PINKMON",
+    JOLTEON = "YELLOWMON",
+    JYNX = "MEWMON",
+    KABUTO = "BROWNMON",
+    KABUTOPS = "BROWNMON",
+    KADABRA = "YELLOWMON",
+    KAKUNA = "YELLOWMON",
+    KANGASKHAN = "BROWNMON",
+    KINGLER = "REDMON",
+    KOFFING = "PURPLEMON",
+    KRABBY = "REDMON",
+    LAPRAS = "CYANMON",
+    LICKITUNG = "PINKMON",
+    MACHAMP = "GRAYMON",
+    MACHOKE = "GRAYMON",
+    MACHOP = "GRAYMON",
+    MAGIKARP = "REDMON",
+    MAGMAR = "REDMON",
+    MAGNEMITE = "GRAYMON",
+    MAGNETON = "GRAYMON",
+    MANKEY = "BROWNMON",
+    MAROWAK = "GRAYMON",
+    MEOWTH = "YELLOWMON",
+    METAPOD = "GREENMON",
+    MEW = "MEWMON",
+    MEWTWO = "MEWMON",
+    MOLTRES = "REDMON",
+    MR_MIME = "PINKMON",
+    MUK = "PURPLEMON",
+    NIDOKING = "PURPLEMON",
+    NIDOQUEEN = "BLUEMON",
+    NIDORAN_F = "BLUEMON",
+    NIDORAN_M = "PURPLEMON",
+    NIDORINA = "BLUEMON",
+    NIDORINO = "PURPLEMON",
+    NINETALES = "YELLOWMON",
+    ODDISH = "GREENMON",
+    OMANYTE = "BLUEMON",
+    OMASTAR = "BLUEMON",
+    ONIX = "GRAYMON",
+    PARAS = "REDMON",
+    PARASECT = "REDMON",
+    PERSIAN = "YELLOWMON",
+    PIDGEOT = "BROWNMON",
+    PIDGEOTTO = "BROWNMON",
+    PIDGEY = "BROWNMON",
+    PIKACHU = "YELLOWMON",
+    PINSIR = "BROWNMON",
+    POLIWAG = "BLUEMON",
+    POLIWHIRL = "BLUEMON",
+    POLIWRATH = "BLUEMON",
+    PONYTA = "REDMON",
+    PORYGON = "GRAYMON",
+    PRIMEAPE = "BROWNMON",
+    PSYDUCK = "YELLOWMON",
+    RAICHU = "YELLOWMON",
+    RAPIDASH = "REDMON",
+    RATICATE = "GRAYMON",
+    RATTATA = "GRAYMON",
+    RHYDON = "GRAYMON",
+    RHYHORN = "GRAYMON",
+    SANDSHREW = "BROWNMON",
+    SANDSLASH = "BROWNMON",
+    SCYTHER = "GREENMON",
+    SEADRA = "CYANMON",
+    SEAKING = "REDMON",
+    SEEL = "BLUEMON",
+    SHELLDER = "GRAYMON",
+    SLOWBRO = "PINKMON",
+    SLOWPOKE = "PINKMON",
+    SNORLAX = "PINKMON",
+    SPEAROW = "BROWNMON",
+    SQUIRTLE = "CYANMON",
+    STARMIE = "GRAYMON",
+    STARYU = "REDMON",
+    TANGELA = "BLUEMON",
+    TAUROS = "GRAYMON",
+    TENTACOOL = "CYANMON",
+    TENTACRUEL = "CYANMON",
+    VAPOREON = "CYANMON",
+    VENOMOTH = "PURPLEMON",
+    VENONAT = "PURPLEMON",
+    VENUSAUR = "GREENMON",
+    VICTREEBEL = "GREENMON",
+    VILEPLUME = "REDMON",
+    VOLTORB = "YELLOWMON",
+    VULPIX = "REDMON",
+    WARTORTLE = "CYANMON",
+    WEEDLE = "YELLOWMON",
+    WEEPINBELL = "GREENMON",
+    WEEZING = "PURPLEMON",
+    WIGGLYTUFF = "PINKMON",
+    ZAPDOS = "YELLOWMON",
+    ZUBAT = "BLUEMON",
+  },
+  source = "pokeyellow data/sgb/sgb_palettes.asm + data/pokemon/palettes.asm",
+}

data/scripts/flavor/bike_shop.lua

@@ -1,10 +1,9 @@
 -- BikeShop (BIKE_SHOP) flavor dialogue
 -- Source: pokered/scripts/BikeShop.asm, pokered/text/BikeShop.asm
 --
--- TEXT_BIKESHOP_CLERK is skipped: it drives the actual voucher-for-bicycle
--- exchange (YesNoChoice purchase menu, GiveItem, RemoveItemByID, SetEvent
--- EVENT_GOT_BICYCLE). That is a significant standalone feature outside the
--- scope of these two flavor NPCs and is left unported here.
+-- TEXT_BIKESHOP_CLERK lives in data/scripts/story2.lua (M.BIKE_SHOP): the
+-- voucher exchange and the BICYCLE/CANCEL price window need more than
+-- command rows (#568).
 
 return {
   BIKE_SHOP = {
@@ -20,12 +19,15 @@ return {
       -- CheckEvent EVENT_GOT_BICYCLE ; jr nz, .gotBike
       -- before the player owns a bike -> TheseBikesAreExpensiveText
       -- after the player owns a bike  -> CoolBikeText
+      -- The check reads the bag, not the event: the port hands out the
+      -- BICYCLE itself (a key item, so it cannot be tossed), and that also
+      -- reads right on saves written before the clerk set the event (#567).
       TEXT_BIKESHOP_YOUNGSTER = {
         { "face_player" },                                            -- 1
-        { "check_flag", "EVENT_GOT_BICYCLE" },                        -- 2
-        { "jump_if_true", 5 },                                        -- 3
+        { "check_item", "BICYCLE" },                                  -- 2
+        { "jump_if_true", 6 },                                        -- 3
         { "show_text", "_BikeShopYoungsterTheseBikesAreExpensiveText" }, -- 4
-        { "jump", 6 },                                                -- 5
+        { "jump", "end" },                                            -- 5
         { "show_text", "_BikeShopYoungsterCoolBikeText" },            -- 6
       },
     },

data/scripts/flavor/cerulean_badge_house.lua

@@ -35,13 +35,25 @@ local function middleAgedMan(game, ow, npc, done)
     -- .loop: print WhichBadgeText, then show the badge list menu again
     push(game, t._CeruleanBadgeHouseMiddleAgedManWhichBadgeText, function()
       local ListMenu = require("src.ui.ListMenu")
+      local Strings = require("src.core.Strings")
       local items = {}
       for _, id in ipairs(BADGE_ORDER) do
         local idef = game.data.items[id]
         items[#items + 1] = { label = idef and idef.name or id, value = id }
       end
+      -- PrintListMenuEntries prints ListMenuCancelText once it hits the
+      -- list's $FF terminator (home/list_menu.asm), so every
+      -- DisplayListMenuID list ends in an on-screen CANCEL row; picking it
+      -- takes DisplayListMenuIDLoop's ExitListMenu path, the same .done
+      -- exit as B (#569)
+      items[#items + 1] = { label = Strings("CANCEL") }
       local menu = ListMenu.new(game, "", items, {
         onChoose = function(item)
+          game.stack:pop()
+          if not item.value then
+            push(game, t._CeruleanBadgeHouseMiddleAgedManVisitAnyTimeText, done)
+            return
+          end
           push(game, t[BADGE_TEXT[item.value]], loop)
         end,
         onCancel = function()

data/scripts/flavor/cerulean_city.lua

@@ -3,6 +3,10 @@
 -- Both NPCs use text_asm with an hRandomAdd roll to pick one of several
 -- flavor lines (no flags, no branching outcome) -- ported as a weighted
 -- math.random pick each time the NPC is talked to.
+--
+-- Yellow renames Slowbro -> Electrode in the text labels (see
+-- tools/yellow_symbol_aliases.py); look up both so Red/Blue and Yellow
+-- share this script.
 
 local M = {}
 
@@ -12,6 +16,29 @@ local function push(game, ow, npc, done, text)
   game.stack:push(TextBox.new(game, text, done))
 end
 
+-- CeruleanCitySlowbroText / CeruleanCityElectrodeText
+-- cp 180 -> 76/256 chance of 1st; cp 120 -> 60/256 chance of 2nd;
+-- cp 60 -> 60/256 chance of 3rd; else 60/256 chance of 4th.
+local function talkMon(game, ow, npc, done)
+  local t = game.data.text
+  local roll = math.random(0, 255)
+  local text
+  if roll >= 180 then
+    text = t._CeruleanCitySlowbroTookASnoozeText
+        or t._CeruleanCityElectrodeTookASnoozeText
+  elseif roll >= 120 then
+    text = t._CeruleanCitySlowbroIsLoafingAroundText
+        or t._CeruleanCityElectrodeIsLoafingAroundText
+  elseif roll >= 60 then
+    text = t._CeruleanCitySlowbroTurnedAwayText
+        or t._CeruleanCityElectrodeTurnedAwayText
+  else
+    text = t._CeruleanCitySlowbroIgnoredOrdersText
+        or t._CeruleanCityElectrodeIgnoredOrdersText
+  end
+  push(game, ow, npc, done, text)
+end
+
 M.CERULEAN_CITY = {
   talk = {
     -- CeruleanCityCooltrainerF1Text (scripts/CeruleanCity.asm:362-393)
@@ -23,32 +50,20 @@ M.CERULEAN_CITY = {
       local text
       if roll >= 180 then
         text = t._CeruleanCityCooltrainerF1SlowbroUseSonicboomText
+            or t._CeruleanCityCooltrainerF1ElectrodeUseSonicboomText
       elseif roll >= 100 then
         text = t._CeruleanCityCooltrainerF1SlowbroPunchText
+            or t._CeruleanCityCooltrainerF1ElectrodePunchText
       else
         text = t._CeruleanCityCooltrainerF1SlowbroWithdrawText
+            or t._CeruleanCityCooltrainerF1ElectrodeWithdrawText
       end
       push(game, ow, npc, done, text)
     end,
 
-    -- CeruleanCitySlowbroText (scripts/CeruleanCity.asm:395-436)
-    -- cp 180 -> 76/256 chance of 1st; cp 120 -> 60/256 chance of 2nd;
-    -- cp 60 -> 60/256 chance of 3rd; else 60/256 chance of 4th.
-    TEXT_CERULEANCITY_SLOWBRO = function(game, ow, npc, done)
-      local t = game.data.text
-      local roll = math.random(0, 255)
-      local text
-      if roll >= 180 then
-        text = t._CeruleanCitySlowbroTookASnoozeText
-      elseif roll >= 120 then
-        text = t._CeruleanCitySlowbroIsLoafingAroundText
-      elseif roll >= 60 then
-        text = t._CeruleanCitySlowbroTurnedAwayText
-      else
-        text = t._CeruleanCitySlowbroIgnoredOrdersText
-      end
-      push(game, ow, npc, done, text)
-    end,
+    TEXT_CERULEANCITY_SLOWBRO = talkMon,
+    -- Yellow map object uses TEXT_CERULEANCITY_ELECTRODE
+    TEXT_CERULEANCITY_ELECTRODE = talkMon,
   },
 }
 

data/scripts/flavor/game_corner.lua

@@ -85,6 +85,47 @@ return {
         alreadyGotLabel = "_GameCornerGentlemanCloselyWatchTheReelsText",
         alreadyGotFallback = "The trick is to\nwatch the reels\vclosely!",
       }),
+
+      -- Yellow keeps all three giveaways with the same events and amounts
+      -- but renames the objects and their text labels: FISHING_GURU ->
+      -- FISHING_GURU1, CLERK2 -> MIDDLE_AGED_MAN2, GENTLEMAN ->
+      -- FISHING_GURU2 (pokeyellow/scripts/GameCorner.asm).  The Red/Blue
+      -- keys above never match there, so Yellow needs its own three (#552).
+      TEXT_GAMECORNER_FISHING_GURU1 = coinGiver({
+        event = "EVENT_GOT_10_COINS",
+        amount = 10,
+        askLabel = "_GameCornerFishingGuru1WantToPlayText",
+        askFallback = "Kid, do you want\nto play?",
+        receivedLabel = "_GameCornerFishingGuru1Received10CoinsText",
+        coinCaseFullLabel = "_GameCornerFishingGuru1DontNeedMyCoinsText",
+        coinCaseFullFallback = "You don't need my\ncoins!",
+        alreadyGotLabel = "_GameCornerFishingGuru1WinsComeAndGoText",
+        alreadyGotFallback = "Wins seem to come\nand go.",
+      }),
+
+      TEXT_GAMECORNER_MIDDLE_AGED_MAN2 = coinGiver({
+        event = "EVENT_GOT_20_COINS_2",
+        amount = 20,
+        askLabel = "_GameCornerMiddleAgedMan2WantSomeCoinsText",
+        askFallback = "What's up? Want\nsome coins?",
+        receivedLabel = "_GameCornerMiddleAgedMan2Received20CoinsText",
+        coinCaseFullLabel = "_GameCornerMiddleAgedMan2YouHaveLotsOfCoinsText",
+        coinCaseFullFallback = "You have lots of\ncoins!",
+        alreadyGotLabel = "_GameCornerMiddleAgedMan2INeedMoreCoinsText",
+        alreadyGotFallback = "Darn! I need more\ncoins for the\vPOKéMON I want!",
+      }),
+
+      TEXT_GAMECORNER_FISHING_GURU2 = coinGiver({
+        event = "EVENT_GOT_20_COINS",
+        amount = 20,
+        askLabel = "_GameCornerFishingGuru2ThrowingMeOffText",
+        askFallback = "Hey, what? You're\nthrowing me off!\vHere are some\vcoins, shoo!",
+        receivedLabel = "_GameCornerFishingGuru2Received20CoinsText",
+        coinCaseFullLabel = "_GameCornerFishingGuru2YouGotYourOwnCoinsText",
+        coinCaseFullFallback = "You've got your\nown coins!",
+        alreadyGotLabel = "_GameCornerFishingGuru2CloselyWatchTheReelsText",
+        alreadyGotFallback = "The trick is to\nwatch the reels\vclosely!",
+      }),
     },
   },
 }

data/scripts/flavor/viridian_school_house.lua

@@ -0,0 +1,175 @@
+-- Viridian School House's two readables (data/events/hidden_events.asm,
+-- hidden_events_for VIRIDIAN_SCHOOL_HOUSE):
+--   hidden_text_predef 3, 0  PrintBlackboardLinkCableText, ViridianSchoolBlackboard
+--   hidden_text_predef 3, 4  PrintNotebookText, ViridianSchoolNotebook
+-- tools/extract/field.py only parses `hidden_event` rows, so neither
+-- hidden_text_predef row reaches data/generated/field.lua and both tiles
+-- were dead A presses (#503).  Same hook shape, and the same sibling asm
+-- file, as the Celadon roof house in data/scripts/celadon_eevee.lua (#391);
+-- hidden_text_predef spends the facing byte on the tx_pre id, so neither
+-- tile gates on facing.
+
+local Font = require("src.render.Font")
+local Theme = require("src.ui.Theme")
+local TextBox = require("src.render.TextBox")
+
+-- ViridianSchoolBlackboard (engine/events/hidden_events/school_blackboard.asm):
+-- StatusAilmentText1/2 are the two columns of the 12x8 box at the top left
+-- (hlcoord 0, 0 + `lb bc, 6, 10`); picking a status prints its
+-- ViridianBlackboardStatusPointers entry and jumps back to .blackboardLoop,
+-- QUIT or B falls through to .exitBlackboard.
+local STATUS_LABELS = {
+  { " SLP", "_ViridianBlackboardSleepText" },
+  { " PSN", "_ViridianBlackboardPoisonText" },
+  { " PAR", "_ViridianBlackboardPrlzText" },
+  { " BRN", "_ViridianBlackboardBurnText" },
+  { " FRZ", "_ViridianBlackboardFrozenText" },
+}
+
+-- The headings list is a two-column menu, which src/ui/Menu.lua does not do
+-- (it stacks one column), so the layout lives here (#591).  .blackboardLoop:
+-- TextBoxBorder at hlcoord 0, 0 with `lb bc, 6, 10` is the 12x8 box,
+-- StatusAilmentText1 (" SLP"/" PSN"/" PAR") is placed at hlcoord 1, 2 and
+-- StatusAilmentText2 (" BRN"/" FRZ"/" QUIT") at hlcoord 6, 2.  LEFT/RIGHT
+-- move wTopMenuItemX between those two columns and swap wMenuItemOffset
+-- between 0 and 3 while leaving wCurrentMenuItem (the row) alone; UP/DOWN
+-- are not in wMenuWatchedKeys, so they only slide the cursor and loop.
+local BOARD_LABELS = {}
+for i, row in ipairs(STATUS_LABELS) do BOARD_LABELS[i] = row[1] end
+BOARD_LABELS[#BOARD_LABELS + 1] = " QUIT"
+local BOARD_COL_X = { 1, 6 }
+local BOARD_ROW_Y = 2
+local BOARD_ROWS = 3
+
+local StatusBoard = {}
+StatusBoard.__index = StatusBoard
+
+function StatusBoard.new(game, onPick, onQuit)
+  return setmetatable({ game = game, col = 1, row = 1, labels = BOARD_LABELS,
+                        onPick = onPick, onQuit = onQuit }, StatusBoard)
+end
+
+-- flat index = pokered's wMenuItemOffset (0 or 3) + wCurrentMenuItem (0..2),
+-- so 1..5 are the statuses in ViridianBlackboardStatusPointers order and 6
+-- is QUIT
+function StatusBoard:selection()
+  return (self.col - 1) * BOARD_ROWS + self.row
+end
+
+function StatusBoard:update()
+  local input = self.game.input
+  if input:wasPressed("up") then
+    -- wMenuWrappingEnabled is never set here, so both ends are hard stops
+    if self.row > 1 then self.row = self.row - 1 end
+  elseif input:wasPressed("down") then
+    if self.row < BOARD_ROWS then self.row = self.row + 1 end
+  elseif input:wasPressed("left") then
+    self.col = 1
+  elseif input:wasPressed("right") then
+    self.col = 2
+  elseif input:wasPressed("a") or input:wasPressed("b") then
+    -- HandleMenuInput_ (home/window.asm) beeps for the PAD_A | PAD_B branch,
+    -- and B and QUIT share .exitBlackboard
+    require("src.core.Sound").play(self.game.data, "Press_AB")
+    local sel = self:selection()
+    if input:wasPressed("b") or sel > #STATUS_LABELS then
+      self.onQuit()
+    else
+      self.onPick(sel)
+    end
+  end
+end
+
+function StatusBoard:draw()
+  Font.drawBox(0, 0, 12, 8)
+  love.graphics.setColor(0, 0, 0, 1)
+  for i, label in ipairs(BOARD_LABELS) do
+    local col = i <= BOARD_ROWS and 1 or 2
+    local row = i - (col - 1) * BOARD_ROWS
+    Font.draw(label, BOARD_COL_X[col] * 8, (BOARD_ROW_Y + row - 1) * 8)
+  end
+  -- wTopMenuItemX equals the column PlaceString started at, so the cursor
+  -- covers the blank each label leads with
+  Font.drawCode(Theme.cursor, BOARD_COL_X[self.col] * 8,
+                (BOARD_ROW_Y + self.row - 1) * 8)
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
+local function blackboard(game)
+  local text = game.data.text or {}
+  local openBoard
+  -- wCurrentMenuItem / wMenuItemOffset are zeroed once, above .blackboardLoop,
+  -- and nothing inside the loop clears them again: after a status blurb
+  -- `jp .blackboardLoop` comes back with the cursor still on the row and
+  -- column the player just picked.  One StatusBoard lives for the whole
+  -- reading and is re-pushed each pass, so only entering the blackboard
+  -- resets to the left column / top row (#591).
+  local board
+  -- .blackboardLoop reprints ViridianSchoolBlackboardText2 and only then
+  -- calls HandleMenuInput, so the prompt is on screen for exactly as long as
+  -- the headings list is.  That text ends in `done`, not `prompt`
+  -- (data/text/text_2.asm:646), so PrintText returns with the box still up
+  -- and never waits for a button: TextBox opts.stay holds it open under the
+  -- list and these callbacks pop the pair together (#591).
+  local function closeBoard()
+    game.stack:pop() -- the headings list
+    game.stack:pop() -- the held "Which heading" box under it
+  end
+  local function pick(i)
+    closeBoard()
+    game.stack:push(TextBox.new(game,
+      text[STATUS_LABELS[i][2]] or STATUS_LABELS[i][1], openBoard))
+  end
+  function openBoard()
+    game.stack:push(TextBox.new(game,
+      text._ViridianSchoolBlackboardText2 or "Which heading do\nyou want to read?",
+      nil, { stay = { onShown = function()
+        board = board or StatusBoard.new(game, pick, closeBoard)
+        game.stack:push(board)
+      end } }))
+  end
+  game.stack:push(TextBox.new(game,
+    text._ViridianSchoolBlackboardText1
+      or "The blackboard\ndescribes POKéMON\vSTATUS changes\vduring battles.",
+    openBoard))
+end
+
+-- ViridianSchoolNotebook (engine/events/hidden_events/school_notebooks.asm):
+-- pages 1-3 each end in TurnPageSchoolNotebook (TurnPageText + YesNoChoice)
+-- and NO stops the read; page 4 turns without asking and runs straight into
+-- page 5, the girl catching you at it.
+local function notebook(game)
+  local text = game.data.text or {}
+  local function page(n, after)
+    return TextBox.new(game, text["_ViridianSchoolNotebookText" .. n] or "", after)
+  end
+  local function turnPage(nextPage)
+    return function()
+      game.stack:push(TextBox.new(game, text._TurnPageText or "Turn the page?",
+        nil, { choice = function(yes)
+          if yes then game.stack:push(nextPage()) end
+        end }))
+    end
+  end
+  local function page5() return page(5) end
+  local function page4() return page(4, function() game.stack:push(page5()) end) end
+  local function page3() return page(3, turnPage(page4)) end
+  local function page2() return page(2, turnPage(page3)) end
+  game.stack:push(page(1, turnPage(page2)))
+end
+
+return {
+  VIRIDIAN_SCHOOL_HOUSE = {
+    onInteract = function(game, ow, fx, fy)
+      if fx == 3 and fy == 0 then
+        blackboard(game)
+        return true
+      end
+      if fx == 3 and fy == 4 then
+        notebook(game)
+        return true
+      end
+      return false
+    end,
+  },
+}

data/scripts/flavor_all.lua

@@ -60,6 +60,7 @@ local files = {
   "data.scripts.flavor.victory_road_2f",
   "data.scripts.flavor.viridian_city",
   "data.scripts.flavor.viridian_nickname_house",
+  "data.scripts.flavor.viridian_school_house", -- #503
   "data.scripts.flavor.wardens_house",
 }
 

data/scripts/init.lua

@@ -48,7 +48,8 @@ end
 if GameVersion.isYellow() then
   for _, file in ipairs({ "data.scripts.yellow_gifts",
                           "data.scripts.yellow_jessie_james",
-                          "data.scripts.yellow_beach_house" }) do
+                          "data.scripts.yellow_beach_house",
+                          "data.scripts.yellow_viridian_old_man" }) do
     for mapId, mod in pairs(require(file)) do
       MapScripts.attachBase(mapId, mod)
     end

data/scripts/oaks_lab.lua

@@ -6,6 +6,8 @@
 --   takes it ("I'll take this one, then!") and both balls disappear.
 --   Source: scripts/OaksLab.asm OaksLabCharmanderPokeBallText /
 --   OaksLabRivalTakePokeBallScript.
+-- * Leftover ball (after the pick): Oak turns and reads the last-mon
+--   line instead of re-offering the starter (OaksLabLastMonScript, #601).
 -- * Rival (object 1): before starter -> "go ahead and choose" once Oak
 --   has walked you in, else "gramps isn't around" (#218); with
 --   starter -> taunt + battle OPP_RIVAL1 with the counter-pick party
@@ -20,10 +22,10 @@ local function starterBall(askText, species, choseFlag, ownBall,
                            rivalBallX, rivalBall)
   return {
     { "check_flag", "EVENT_GOT_STARTER" },        -- 1
-    { "jump_if_true", 20 },                       -- 2
+    { "jump_if_true", 22 },                       -- 2
     -- no picking until Oak has walked you in (OaksLabScript gating)
     { "check_flag", "EVENT_FOLLOWED_OAK_INTO_LAB" }, -- 3
-    { "jump_if_false", 20 },                      -- 4
+    { "jump_if_false", 25 },                      -- 4
     -- the Pokédex "new species" entry shows before the ask (predef
     -- StarterDex ahead of OaksLabYouWant...Text).  StarterDex temporarily
     -- sets the owned bits so ShowPokedexData prints height/weight/text;
@@ -31,30 +33,45 @@ local function starterBall(askText, species, choseFlag, ownBall,
     { "push_screen", "DexEntryMenu",
       { species = species, forceOwned = true } }, -- 5
     { "ask", askText },                           -- 6
-    { "jump_if_false", 21 },                      -- 7
+    { "jump_if_false", "end" },                   -- 7
     -- OaksLab.asm prints ReceivedMon then AddPartyMon (AskName lives
     -- inside give_pokemon).  Show the received text first so the
     -- nickname prompt follows "you got X", matching Gen1.
-    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 8
-    { "give_pokemon", species, 5 },               -- 9
-    { "set_flag", "EVENT_GOT_STARTER" },          -- 10
-    { "set_flag", choseFlag },                    -- 11
+    -- The received text carries sound_get_key_item (OaksLab.asm
+    -- OaksLabReceivedMonText); the jingle plays as the box opens
+    -- (same beat as the Yellow port's starter, #668).
+    { "play_sound", "Get_Key_Item" },                              -- 8
+    { "show_text", "_OaksLabReceivedMonText", { RAM = species } }, -- 9
+    { "give_pokemon", species, 5 },               -- 10
+    { "set_flag", "EVENT_GOT_STARTER" },          -- 11
+    { "set_flag", choseFlag },                    -- 12
     -- POKé BALLs are not handed out here in the original -- Oak gives
     -- them later, at OaksLabOak1Text's .give_poke_balls beat once the
     -- player has beaten the Route 22 rival (see TEXT_OAKSLAB_OAK1 below)
-    { "hide_object", "OAKS_LAB", ownBall },       -- 12
+    { "hide_object", "OAKS_LAB", ownBall },       -- 13
     -- the rival walks to the countering ball (around the furniture)
-    { "move_npc_to", 1, rivalBallX, 4 },          -- 13
-    { "face_object", 1, "up" },                   -- 14
-    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 15
-    { "hide_object", "OAKS_LAB", rivalBall },     -- 16
+    { "move_npc_to", 1, rivalBallX, 4 },          -- 14
+    { "face_object", 1, "up" },                   -- 15
+    { "show_text", "_OaksLabRivalIllTakeThisOneText" },            -- 16
+    { "hide_object", "OAKS_LAB", rivalBall },     -- 17
+    { "play_sound", "Get_Key_Item" },             -- 18 (sound_get_key_item)
     { "show_text", "_OaksLabRivalReceivedMonText",
       { RAM = rivalBall == "OAKSLAB_CHARMANDER_POKE_BALL" and "CHARMANDER"
               or rivalBall == "OAKSLAB_SQUIRTLE_POKE_BALL" and "SQUIRTLE"
-              or "BULBASAUR" } },                 -- 17
-    { "jump", 21 },                               -- 18
-    { "jump", 21 },                               -- 19 (spacer)
-    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 20
+              or "BULBASAUR" } },                 -- 19
+    { "jump", "end" },                            -- 20
+    { "jump", "end" },                            -- 21 (spacer)
+    -- a leftover ball after the player's pick: Oak turns to face the
+    -- player and reads the last-mon line instead of re-offering the
+    -- starter (scripts/OaksLab.asm OaksLabSelectedPokeBallScript ->
+    -- OaksLabLastMonScript; #601).  The ROM's "#MON" ligature is spelled
+    -- out as Pokémon here.
+    { "face_object", 5, "down" },                 -- 22
+    { "show_text", "That's PROF.OAK's\nlast Pokémon!" }, -- 23
+    -- OaksLabLastMonScript ends at TextScriptEnd; the port used to fall
+    -- through into the pre-pick line below (#601 remnant, reported on #600)
+    { "jump", "end" },                            -- 24
+    { "show_text", "_OaksLabThoseArePokeBallsText" }, -- 25
   }
 end
 
@@ -62,10 +79,22 @@ return {
   talk = {
     -- Oak: OaksLabOak1Text.  Parcel delivery kicks SCRIPT_OAKSLAB_RIVAL_
     -- ARRIVES_AT_OAKS_REQUEST + OaksLabOakGivesPokedexScript (rival walk-
-    -- in, full Pokédex speech, rival exit, Route 22 arm).  Dex-rating
-    -- (DisplayDexRating) is still skipped.
+    -- in, full Pokédex speech, rival exit, Route 22 arm).
     TEXT_OAKSLAB_OAK1 = {
       { "face_player" },
+      -- OaksLabOak1Text leads with the dex-rating branch (#600): with
+      -- EVENT_PALLET_AFTER_GETTING_POKEBALLS set (converted saves), or
+      -- 2+ species owned once the Pokédex is in hand, Oak asks how it is
+      -- coming and rates it (predef DisplayDexRating).  Red keeps the
+      -- GOT_POKEDEX gate that Yellow's copy of this text drops
+      -- (data/scripts/oaks_lab_yellow.lua).
+      { "check_flag", "EVENT_PALLET_AFTER_GETTING_POKEBALLS" },
+      { "jump_if_true", "dex_rating" },
+      { "check_dex_owned", 2 },
+      { "jump_if_false", "no_rating" },
+      { "check_flag", "EVENT_GOT_POKEDEX" },
+      { "jump_if_true", "dex_rating" },
+      { "label", "no_rating" },
       { "check_item", "POKE_BALL" },
       { "jump_if_true", "come_see" },
       { "check_flag", "EVENT_BEAT_ROUTE22_RIVAL_1ST_BATTLE" },
@@ -151,6 +180,14 @@ return {
 
       { "label", "come_see" },
       { "show_text", "_OaksLabOak1ComeSeeMeSometimesText" },
+      { "jump", "end" },
+
+      -- .HowIsYourPokedexComingText ends on `prompt` and OaksLabOak1Text
+      -- sets wDoNotWaitForButtonPressAfterDisplayingText, so the seen/owned
+      -- tally follows with no button wait (engine/events/pokedex_rating.asm)
+      { "label", "dex_rating" },
+      { "show_text", "_OaksLabOak1HowIsYourPokedexComingText" },
+      { "dex_rating" },
     },
 
     TEXT_OAKSLAB_CHARMANDER_POKE_BALL =
@@ -245,7 +282,12 @@ return {
        and y >= 6 then
       local rival = ow:npcByIndex(1)
       if not rival then return false end
+      -- OaksLabRivalChallengesPlayerScript swaps in the rival encounter
+      -- fanfare for the taunt/challenge exchange, same as the Yellow port
+      -- (oaks_lab_yellow.lua); it was silently dropped here (#596).
       local rows = {
+        { "stop_music" },
+        { "play_music", "Music_MeetRival" },
         { "show_text", "_OaksLabRivalIllTakeYouOnText" },         -- 1
       }
       -- the rival routes to a free cell beside the player
@@ -283,8 +325,15 @@ return {
       table.insert(rows, { "jump_if_false", base + 6 })
       table.insert(rows, { "show_text", "_OaksLabRivalIPickedTheWrongPokemonText" })
       table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
+      -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
+      -- walk out past the player.  The fanfare was dropped here (#683) -- the
+      -- parcel scene above already plays Music_MeetRival on both arrival and
+      -- departure (lines 144-146), and this exit should match (#596).
+      table.insert(rows, { "stop_music" })
+      table.insert(rows, { "play_music", "Music_MeetRival" })
       table.insert(rows, { "move_npc_to", 1, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
+      table.insert(rows, { "play_music", "Music_OaksLab" })
       ow.runner:run(rows, { npc = rival })
       return true
     end

data/scripts/oaks_lab_yellow.lua

@@ -71,8 +71,12 @@ return {
       { "show_text", "_OaksLabRivalLeaveItAllToMeText" },
       { "set_flag", "EVENT_GOT_POKEDEX" },
       { "set_flag", "EVENT_OAK_GOT_PARCEL" },
+      -- OaksLabOakGivesPokedexScript: HideObject TOGGLE_LYING_OLD_MAN /
+      -- ShowObject TOGGLE_OLD_MAN_2 -- Yellow's tutorial old man stands
+      -- on the sleeper's cell (18,9); the Red/Blue walker OLD_MAN at
+      -- (17,5) never appears in Yellow (#617)
       { "hide_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY" },
-      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN" },
+      { "show_object", "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN2" },
       { "stop_music" },
       { "play_music", "Music_MeetRival" },
       { "move_npc_to", RIVAL, 4, 7 },
@@ -143,17 +147,25 @@ return {
         -- OaksLabRivalExclamationScript: "!" over the rival
         { "emote", RIVAL, "shock" },
       }
-      -- .RivalPushesPlayerAwayFromEeveeBall + the PAD_RIGHT x2 shove:
-      -- the rival cuts across to the ball WHILE the player standing
-      -- below it is bumped two tiles right (both movements run in the
-      -- same beat, so the walk overlaps the shove like the original)
+      -- .RivalPushesPlayerAwayFromEeveeBall is DOWN then RIGHT x3 (the $07
+      -- bytes are Yellow's own step-right encoding, decoded by
+      -- engine/overworld/movement.asm Func_5288 -> Func_532b), and the
+      -- PAD_RIGHT x2 shove is NOT queued alongside it:
+      -- OaksLabRivalTakesPokeballScript .asm_1c564 polls every frame and
+      -- only simulates the pair once wNPCNumScriptedSteps reads 1 -- i.e.
+      -- as the rival begins the LAST byte, the step onto the tile the
+      -- player is standing on.  Starting both on one row had Red stroll
+      -- off the Eevee while the rival was still at the top of the table
+      -- (#559).
       if py == 4 then
-        rows[#rows + 1] = { "walk_npc", RIVAL,
-          { "down", "right", "right", "right" }, { wait = false } }
+        rows[#rows + 1] = { "walk_npc", RIVAL, { "down", "right", "right" } }
+        -- this one runs concurrently with the shove below
+        rows[#rows + 1] = { "walk_npc", RIVAL, { "right" }, { wait = false } }
         rows[#rows + 1] = { "face_player_dir", "left" }
         rows[#rows + 1] = { "move_player", "right", 2 }
-        -- let the rival finish the last stretch to (7,4)
-        rows[#rows + 1] = { "wait", 40 }
+        -- move_player blocks for both tiles, so the rival has already
+        -- landed on (7,4); this is just the beat before he turns up
+        rows[#rows + 1] = { "wait", 20 }
       else
         rows[#rows + 1] = { "move_npc_to", RIVAL, 7, 4 }
       end
@@ -275,10 +287,12 @@ return {
       table.insert(rows, { "label", "lost_lab" })
       table.insert(rows, { "set_field", "rivalStarter", 3 })
       table.insert(rows, { "label", "exit" })
-      -- OaksLabRivalStartsExitScript: parting shot, walk out past the
-      -- player, restore the lab theme
+      -- OaksLabRivalStartsExitScript: parting shot, rival exit fanfare, then
+      -- walk out past the player (#683).
       table.insert(rows, { "wait", 20 })
       table.insert(rows, { "show_text", "_OaksLabRivalSmellYouLaterText" })
+      table.insert(rows, { "stop_music" })
+      table.insert(rows, { "play_music", "Music_MeetRival" })
       table.insert(rows, { "move_npc_to", RIVAL, 4, 11 })
       table.insert(rows, { "hide_object", "OAKS_LAB", "OAKSLAB_RIVAL" })
       table.insert(rows, { "play_music", "Music_OaksLab" })

data/scripts/safari.lua

@@ -4,9 +4,11 @@
 -- (.PlayerNextToSafariZoneWorker1CoordsArray).  Paying ¥500 hands over
 -- 30 SAFARI BALLs and starts the 502-step game
 -- (SafariZoneGateWouldYouLikeToJoinScript: wSafariSteps = 502,
--- wNumSafariBalls = SAFARI_BALLS_RECEIVED).  Declining walks you back
--- so you can't slip past.  Returning to the gate ends the game and the
--- worker takes the leftover balls back.
+-- wNumSafariBalls = SAFARI_BALLS_RECEIVED), then auto-walks the player
+-- up through the north warp into the zone.  Declining walks you back
+-- so you can't slip past.  Returning to the gate ends the game, the
+-- worker takes the leftover balls back and the auto-walk drops you 3
+-- cells below the warp you came in by (#540).
 --
 -- Step/ball bookkeeping lives in src/world/OverworldController.lua
 -- (safariStep/safariGameOver, from
@@ -19,7 +21,33 @@ local FEE = 500
 local BALLS = 30
 local STEPS = 502
 
-local function startGame(game, t, done, balls, introText)
+-- SafariZoneGateSafariZoneWorker1WouldYouLikeToJoinText .success closes with
+-- `ld a, PAD_UP / ld c, 3 / SafariZoneEntranceAutoWalk`: paying walks the
+-- player up out of the gate and through the north warp, it is never left to
+-- the player.  EVENT_IN_SAFARI_ZONE is already set when that walk runs, so
+-- the two gate steps taken before the warp fires are charged against
+-- wSafariSteps (home/overworld.asm:307-310) -- which is why the counter
+-- reads 500/500 on arrival even though the script wrote 502 (#540).  The
+-- port's counter only runs on the nine interior maps (FieldDefaults
+-- safari.stepMaps, OverworldState:inSafariStepZone), so charge those two
+-- steps here instead.
+local function walkIntoZone(game, ow)
+  local p = ow.player
+  -- only from the two trigger cells in front of the worker, which are the
+  -- columns the north warps sit on; a player who paid after TALKING to him
+  -- from somewhere else walks in on their own, as they do today
+  local w = p.cellY == 2 and ow.map:warpAtCell(p.cellX, 0) or nil
+  if not w then return end
+  ow:scriptMove(p, "up", 2, function()
+    local st = game.save.safari
+    if st then st.steps = st.steps - 2 end
+    -- scripted steps skip onStepComplete (and with it CheckWarpsNoCollision),
+    -- so take that warp explicitly once the walk lands on it
+    ow:takeWarp(w.def)
+  end)
+end
+
+local function startGame(game, ow, t, done, balls, introText)
   game.save.safari = { balls = balls or BALLS, steps = STEPS }
   game.save.safariNags = nil
   local TextBox = require("src.render.TextBox")
@@ -31,7 +59,10 @@ local function startGame(game, t, done, balls, introText)
   local pa = t._SafariZoneGateSafariZoneWorker1CallYouOnThePAText
              or "\fWe'll call you on\nthe PA when you\nrun out of time\nor SAFARI BALLs!"
   local luck = t._SafariZoneGateSafariZoneWorker1GoodLuckText or "Good Luck!"
-  game.stack:push(TextBox.new(game, paid .. pa .. "\f" .. luck, done))
+  game.stack:push(TextBox.new(game, paid .. pa .. "\f" .. luck, function()
+    if done then done() end
+    walkIntoZone(game, ow)
+  end))
 end
 
 -- Yellow's soft-lock fix (scripts/SafariZoneGate_2.asm): a player short of
@@ -52,7 +83,7 @@ local function yellowLowCost(game, ow, t, done, back)
           or "\fOh, all right, pay\nme what you have.")
       .. "\f" .. (t._SafariZoneLowCostText2
                   or "But, I can't give\nyou all 30 BALLs.")
-    startGame(game, t, done, balls, intro)
+    startGame(game, ow, t, done, balls, intro)
     return
   end
   local nag = game.save.safariNags or 0
@@ -62,7 +93,7 @@ local function yellowLowCost(game, ow, t, done, back)
       (t._SafariZoneLowCostText8 or "Read my lips, NO!\nGet it?")
       .. (t._SafariZoneLowCostText3
           or "\fYou're persistent,\naren't you?\fOK, you can go in\nfor free, but\njust this once!")
-    startGame(game, t, done, 1, intro)
+    startGame(game, ow, t, done, 1, intro)
     return
   end
   local nags = {
@@ -100,7 +131,7 @@ local function joinPrompt(game, ow, done)
           end
         else
           game.save.money = game.save.money - FEE
-          startGame(game, t, done)
+          startGame(game, ow, t, done)
         end
       end))
     end))
@@ -135,27 +166,38 @@ M.SAFARI_ZONE_GATE = {
   -- no walks you back into the zone
   onEnter = function(game, ow)
     if not game.save.safari or ow.player.cellY > 1 then return end
-    local TextBox = require("src.render.TextBox")
-    local ChoiceBox = require("src.ui.ChoiceBox")
-    local t = game.data.text
-    game.stack:push(TextBox.new(game,
-      t._SafariZoneGateSafariZoneWorker1LeavingEarlyText or "Leaving early?",
-      function()
-        game.stack:push(ChoiceBox.new(game, function(yes)
-          if not yes then
-            -- back into the zone through the entrance warp
-            local w = game.data.maps.SAFARI_ZONE_CENTER.warps[1]
-            ow:startWarpTo("SAFARI_ZONE_CENTER", w.x, w.y, "up")
-            return
-          end
-          game.save.safari = nil
-          game.stack:push(TextBox.new(game,
-            (t._SafariZoneGateSafariZoneWorker1ReturnSafariBallsText
-             or "Please return any\nSAFARI BALLs you\nhave left.")
-            .. "\f" .. (t._SafariZoneGateSafariZoneWorker1GoodHaulComeAgainText
-                        or "Did you get a\ngood haul?\fCome again!")))
-        end))
-      end))
+    -- QUEUED, never pushed: onEnter runs inside the arriving warp's
+    -- Transition midpoint, and Transition:finish pops whatever is on top
+    -- the same frame (Timing.WARP_FADE_IN is 0) -- so a box pushed here is
+    -- swallowed, and on a build where it survived it drew over a screen
+    -- still faded to black (#540).  Same contract as M.HALL_OF_FAME in
+    -- data/scripts/story.lua.
+    --
+    -- SafariZoneGateLeavingSafariScript .leaving_early: YES prints the
+    -- return-balls text, faces the player down and runs
+    -- SafariZoneEntranceAutoWalk with `PAD_DOWN, c = 3`, landing on the
+    -- counter row 3 cells below the warp you came in by; NO prints
+    -- "Good Luck!" and walks one step back up through that same warp.
+    local rightSide = ow.player.cellX ~= 3
+    local dest = game.data.maps.SAFARI_ZONE_CENTER.warps[rightSide and 2 or 1]
+    ow:queueScript({
+      { "ask", "_SafariZoneGateSafariZoneWorker1LeavingEarlyText" },
+      { "jump_if_false", "stay" },
+      -- the port never reaches SafariZoneGateLeavingSafariScript's own
+      -- GOOD_HAUL_COME_AGAIN branch (safariGameOver warps straight to the
+      -- counter), so the sign-off rides on this path
+      { "show_text", "_SafariZoneGateSafariZoneWorker1ReturnSafariBallsText" },
+      { "show_text", "_SafariZoneGateSafariZoneWorker1GoodHaulComeAgainText" },
+      -- no value: set_field assigns nil, which is how save.safari is cleared
+      { "set_field", "safari" },
+      -- move_player runs through scriptMove, which skips onStepComplete, so
+      -- walking back down past (x,2) cannot re-fire the join trigger
+      { "move_player", "down", 3 },
+      { "jump", "end" },
+      { "label", "stay" },
+      { "show_text", "_SafariZoneGateSafariZoneWorker1GoodLuckText" },
+      { "warp", "SAFARI_ZONE_CENTER", dest.x, dest.y, "up" },
+    })
   end,
 }
 

data/scripts/seafoam.lua

@@ -11,7 +11,7 @@
 -- field.seafoam (SEAFOAM_ISLANDS_1F/B1F/B3F holes+holeDestination and
 -- B3F's pluggedByHolesOn) plus the generic
 -- OverworldState:boulderIntoHole in src/world/OverworldController.lua;
--- no per-map onEnter hook is needed here.
+-- no per-map onEnter hook is needed for the boulders.
 
 local M = {}
 
@@ -23,4 +23,46 @@ M.VERMILION_GYM = {
   end,
 }
 
+-- The PLAYER falling down those same holes (#599).  field.seafoam's holes
+-- carry only the BOULDER's object cell on the floor below (landsAt), not
+-- the player's landing, so the player's landing is spelled out here: it
+-- comes from data/maps/special_warps.asm DungeonWarpList/DungeonWarpData,
+-- which the importer does not extract.  Same shape as MANSION_HOLES in
+-- data/scripts/story6.lua and VICTORY_ROAD_3F.onStep in
+-- data/scripts/story.lua; CAVERN $22 is a walkable tile, so the fall has
+-- to be an onStep, not a collision block.
+--
+-- Sources: scripts/SeafoamIslands1F.asm Seafoam1HolesCoords (17,6)/(24,6),
+-- B1F.asm Seafoam2HolesCoords (18,6)/(23,6), B2F.asm Seafoam3HolesCoords
+-- (19,6)/(22,6), B3F.asm Seafoam4HolesCoords (3,16)/(6,16).  Each floor
+-- sets wDungeonWarpDestinationMap and calls IsPlayerOnDungeonWarp, and
+-- wCoordIndex picks that floor's DungeonWarpData row.  Unconditional in
+-- the original: a plugged hole still drops the player.  The B3F and B4F
+-- landings are water; setMap's CheckForceBikeOrSurf pass
+-- (OverworldState:checkForcedMovement) mounts SURF on arrival.
+local HOLE_FALLS = {
+  SEAFOAM_ISLANDS_1F  = { { 17, 6, "SEAFOAM_ISLANDS_B1F", 18, 7 },
+                          { 24, 6, "SEAFOAM_ISLANDS_B1F", 23, 7 } },
+  SEAFOAM_ISLANDS_B1F = { { 18, 6, "SEAFOAM_ISLANDS_B2F", 19, 7 },
+                          { 23, 6, "SEAFOAM_ISLANDS_B2F", 22, 7 } },
+  SEAFOAM_ISLANDS_B2F = { { 19, 6, "SEAFOAM_ISLANDS_B3F", 18, 7 },
+                          { 22, 6, "SEAFOAM_ISLANDS_B3F", 19, 7 } },
+  SEAFOAM_ISLANDS_B3F = { {  3, 16, "SEAFOAM_ISLANDS_B4F", 4, 14 },
+                          {  6, 16, "SEAFOAM_ISLANDS_B4F", 5, 14 } },
+}
+
+for mapId, holes in pairs(HOLE_FALLS) do
+  M[mapId] = M[mapId] or {}
+  M[mapId].onStep = function(game, ow, x, y)
+    for _, h in ipairs(holes) do
+      if x == h[1] and y == h[2] then
+        require("src.core.Sound").play(game.data, "Faint_Fall")
+        ow:startWarpTo(h[3], h[4], h[5], ow.player.facing)
+        return true
+      end
+    end
+    return false
+  end
+end
+
 return M

data/scripts/story.lua

@@ -188,7 +188,12 @@ M.BILLS_HOUSE = {
           end
           if ow.player.facing == "down" then
             -- the player is standing on his straight path: walk around
-            -- (.PokemonWalkAroundPlayerMovement)
+            -- (.PokemonWalkAroundPlayerMovement).  BillsHouseScript2 runs
+            -- BillsHousePikachuWatchPlayer first on this branch, so a
+            -- Pikachu that is still following steps clear of Bill's detour
+            -- and turns to watch the player (#455).
+            require("src.world.PikachuFollower")
+              .onBillWalksAroundPlayer(game, ow)
             ow:scriptMove(npc, "right", 1, function()
               ow:scriptMove(npc, "up", 2, function()
                 ow:scriptMove(npc, "left", 1, function()
@@ -600,12 +605,34 @@ local function snorlaxWake(mapId, objName, beatFlag, wokeUpText, calmedText)
   }
 end
 
+-- A beaten Snorlax is gone for good: Route12/Route16DefaultScript run
+-- HideObject in the same breath as the battle that sets
+-- EVENT_BEAT_ROUTEnn_SNORLAX, so "event set, object still on the map" is a
+-- state the asm cannot produce.  Here it can (a mod's world:toggleObject, a
+-- save edited or migrated from a build older than the flag), and it is a
+-- dead end: ItemEffects' adjacentSleepingSnorlax refuses to wake a Snorlax
+-- whose beat flag is set (ItemUsePokeFlute's CheckEvent, engine/items/
+-- item_effects.asm), so the sleeper sits in the road forever and Cycling
+-- Road is unreachable (#585).  Reconcile the toggle from the flag on every
+-- entry -- the mirror of SaveData.lua's toggle -> flag backfill, and the
+-- same repair shape the Silph Co. floors use below.
+local function hideBeatenSnorlax(mapId, objName, beatFlag)
+  return function(game, ow)
+    if not game.save.flags[beatFlag] then return end
+    local Commands = require("src.script.Commands")
+    Commands.hide_object({ game = game, save = game.save, overworld = ow },
+                         mapId, objName)
+  end
+end
+
 -- snorlaxWake is looked up by ItemEffects.lua/BagMenu.lua (via
 -- data/scripts/init.lua's M.get) and run when the flute wakes Snorlax;
 -- objName/beatFlag let ItemEffects find the NPC and check whether it's
 -- already been beaten before allowing the wake.
 M.ROUTE_12 = {
   talk = { TEXT_ROUTE12_SNORLAX = { { "show_text", "_Route12SnorlaxText" } } },
+  onEnter = hideBeatenSnorlax("ROUTE_12", "ROUTE12_SNORLAX",
+                              "EVENT_BEAT_ROUTE12_SNORLAX"),
   snorlaxWake = {
     objName = "ROUTE12_SNORLAX", beatFlag = "EVENT_BEAT_ROUTE12_SNORLAX",
     script = snorlaxWake("ROUTE_12", "ROUTE12_SNORLAX", "EVENT_BEAT_ROUTE12_SNORLAX",
@@ -614,6 +641,8 @@ M.ROUTE_12 = {
 }
 M.ROUTE_16 = {
   talk = { TEXT_ROUTE16_SNORLAX = { { "show_text", "_Route16Text7" } } },
+  onEnter = hideBeatenSnorlax("ROUTE_16", "ROUTE16_SNORLAX",
+                              "EVENT_BEAT_ROUTE16_SNORLAX"),
   snorlaxWake = {
     objName = "ROUTE16_SNORLAX", beatFlag = "EVENT_BEAT_ROUTE16_SNORLAX",
     script = snorlaxWake("ROUTE_16", "ROUTE16_SNORLAX", "EVENT_BEAT_ROUTE16_SNORLAX",
@@ -645,11 +674,18 @@ M.SAFARI_ZONE_SECRET_HOUSE = {
 M.WARDENS_HOUSE = {
   talk = {
     TEXT_WARDENSHOUSE_WARDEN = {
+      -- Labelled rather than hand-numbered: the branches here have been
+      -- re-pointed twice now (#535, #645), and every insert used to mean
+      -- renumbering three jumps that had no way of announcing they were stale.
       { "face_player" },                                             -- 1
       { "check_flag", "EVENT_GOT_HM04" },                            -- 2
-      { "jump_if_true", 13 },                                        -- 3
+      -- #535: previously jumped to the same silent-end target as the
+      -- give-then-thank fallthrough, so the warden said nothing on every
+      -- visit after the trade. pokered's .got_item branch
+      -- (scripts/WardensHouse.asm) instead prints HM04ExplanationText.
+      { "jump_if_true", "got_hm04" },                                -- 3
       { "check_item", "GOLD_TEETH" },                                -- 4
-      { "jump_if_false", 15 },                                       -- 5
+      { "jump_if_false", "no_teeth" },                               -- 5
       { "show_text", "_WardensHouseWardenGaveTheGoldTeethText" },    -- 6
       { "take_item", "GOLD_TEETH", 1 },                              -- 7
       { "set_flag", "EVENT_GAVE_GOLD_TEETH" },                       -- 8
@@ -658,9 +694,27 @@ M.WARDENS_HOUSE = {
       { "give_item", "HM_STRENGTH", 1, false },                      -- 10
       { "show_text", "_WardensHouseWardenReceivedHM04Text" },        -- 11
       { "set_flag", "EVENT_GOT_HM04" },                              -- 12
-      { "jump", 16 },                                                -- 13 (already got it)
-      { "jump", 16 },                                                -- 14 (unused)
-      { "show_text", "_WardensHouseWardenGibberish1Text" },          -- 15
+      { "jump", "end" },                                             -- 13 (jp .done)
+
+      -- #645: WardensHouseWardenText prints Gibberish1, then YesNoChoice,
+      -- and the warden answers the same gibberish either way -- Gibberish2
+      -- on yes, Gibberish3 on no (scripts/WardensHouse.asm).  The port
+      -- printed the question and walked off before the answer.
+      { "label", "no_teeth" },                                       -- 14
+      { "ask", "_WardensHouseWardenGibberish1Text" },                -- 15
+      { "jump_if_true", "gibberish_yes" },                           -- 16
+      { "show_text", "_WardensHouseWardenGibberish3Text" },          -- 17
+      { "jump", "end" },                                             -- 18
+      { "label", "gibberish_yes" },                                  -- 19
+      { "show_text", "_WardensHouseWardenGibberish2Text" },          -- 20
+      { "jump", "end" },                                             -- 21
+
+      -- #535: pokered .got_item branch (scripts/WardensHouse.asm) --
+      -- printed on every subsequent talk once EVENT_GOT_HM04 is set.
+      -- Text is _WardensHouseWardenHM04ExplanationText (text/WardensHouse.asm):
+      -- HM04 teaches Strength, and hints at the Safari Zone secret house.
+      { "label", "got_hm04" },                                       -- 22
+      { "show_text", "_WardensHouseWardenHM04ExplanationText" },     -- 23
     },
   },
 }
@@ -888,6 +942,7 @@ M.VICTORY_ROAD_3F = {
   -- fall is onStep, not a collision block.
   onStep = function(game, ow, x, y)
     if x == 23 and y == 15 then
+      require("src.core.Sound").play(game.data, "Faint_Fall")
       ow:startWarpTo("VICTORY_ROAD_2F", 22, 16, ow.player.facing)
       return true
     end

data/scripts/story2.lua

@@ -413,22 +413,141 @@ M.POKEMON_FAN_CLUB = {
   },
 }
 
+-- BikeShopClerkText (scripts/BikeShop.asm) runs three ways: the BICYCLE is
+-- already yours, you are carrying the BIKE VOUCHER, or you get the sales
+-- pitch.  The pitch draws its own window (TextBoxBorder hlcoord 0,0, b=4
+-- c=15) holding BikeShopMenuText and BikeShopMenuPrice, and leaves it up
+-- while the clerk keeps talking in the bottom box: the original never
+-- erases it before TextScriptEnd (#568).
+local BikeShopWindow = {}
+BikeShopWindow.__index = BikeShopWindow
+
+function BikeShopWindow.new(game, footer, onChoose)
+  local self = setmetatable({}, BikeShopWindow)
+  self.game = game
+  self.onChoose = onChoose
+  self.index = 1
+  self.active = true
+  -- BikeShopClerkDoYouLikeItText stays on screen under the window for as
+  -- long as the menu is up.  The text box pushed on top types it out and
+  -- pops itself; this copy of its last page takes over from there, so the
+  -- bottom box never blanks between the pitch and the answer.  Paginated
+  -- with the themed column budget so the copy breaks where the box did.
+  local TextBox = require("src.render.TextBox")
+  local box = require("src.ui.Theme").textBox or {}
+  local pages = TextBox.paginate(TextBox.substitute(game, footer), box.maxCols)
+  self.footer = pages[#pages]
+  return self
+end
+
+function BikeShopWindow:update()
+  -- one answer only: the boxes pushed by onChoose sit on top of this
+  -- state, but a second A on the same frame must not fire it twice
+  if not self.active then return end
+  local input = self.game.input
+  -- HandleMenuInput with wMenuWrappingEnabled clear: the two rows clamp
+  if input:wasPressed("up") then
+    self.index = 1
+  elseif input:wasPressed("down") then
+    self.index = 2
+  elseif input:wasPressed("a") or input:wasPressed("b") then
+    local cancelled = input:wasPressed("b") -- bit B_PAD_B -> .cancel
+    require("src.core.Sound").play(self.game.data, "Press_AB")
+    self.active = false
+    self.onChoose(not cancelled and self.index == 1)
+  end
+end
+
+function BikeShopWindow:draw()
+  local Font = require("src.render.Font")
+  local Strings = require("src.core.Strings")
+  local Theme = require("src.ui.Theme")
+  Font.drawBox(0, 0, 17, 6)
+  love.graphics.setColor(0, 0, 0, 1)
+  local bike = self.game.data.items.BICYCLE
+  Font.draw(bike and bike.name or "BICYCLE", 16, 16)  -- hlcoord 2, 2
+  Font.draw("¥1000000", 64, 24)                       -- hlcoord 8, 3
+  Font.draw(Strings("CANCEL"), 16, 32)                -- `next` skips a row
+  -- wTopMenuItemX 1, wTopMenuItemY 2, rows two apart
+  Font.drawCode(Theme.cursor, 8, self.index == 1 and 16 or 32)
+  if self.footer then
+    -- same geometry TextBox resolves against, so a themed box matches
+    local box = Theme.textBox or {}
+    local tx, ty = box.tx or 0, box.ty or 12
+    love.graphics.setColor(1, 1, 1, 1)
+    Font.drawBox(tx, ty, box.tw or 20, box.th or 6)
+    love.graphics.setColor(0, 0, 0, 1)
+    for i, line in ipairs(self.footer) do
+      Font.draw(line, (tx + 1) * 8, (ty + 2 * i) * 8)
+    end
+  end
+  love.graphics.setColor(1, 1, 1, 1)
+end
+
 M.BIKE_SHOP = {
   talk = {
     TEXT_BIKESHOP_CLERK = function(game, ow, npc, done)
+      local Bag = require("src.inventory.Bag")
+      local Flags = require("src.script.Flags")
       local TextBox = require("src.render.TextBox")
-      if (game.save.inventory.BICYCLE or 0) > 0 then
-        game.stack:push(TextBox.new(game, "How's the\nBICYCLE treating\nyou?", done))
-      elseif (game.save.inventory.BIKE_VOUCHER or 0) > 0 then
-        game.save.inventory.BIKE_VOUCHER = nil
-        game.save.inventory.BICYCLE = 1
-        game.stack:push(TextBox.new(game,
-          ("Oh, that's a\nBIKE VOUCHER!\f%s exchanged\nit for a BICYCLE!")
-          :format(game.save.player.name), done))
-      else
-        game.stack:push(TextBox.new(game,
-          "A BICYCLE costs\n¥1000000. Sorry,\nno instalments!", done))
+      local t = game.data.text
+      local function say(text, after, opts)
+        game.stack:push(TextBox.new(game, text, after, opts))
       end
+
+      -- CheckEvent EVENT_GOT_BICYCLE.  Saves made before the clerk started
+      -- setting the event still have the bike in the bag, so either counts.
+      if (game.save.inventory.BICYCLE or 0) > 0
+          or Flags.get(game.save, "EVENT_GOT_BICYCLE") then
+        say(t._BikeShopClerkHowDoYouLikeYourBicycleText, done)
+        return
+      end
+
+      -- .dontHaveBike: IsItemInBag BIKE_VOUCHER
+      if (game.save.inventory.BIKE_VOUCHER or 0) > 0 then
+        say(t._BikeShopClerkOhThatsAVoucherText, function()
+          -- GiveItem's `jr nc, .BagFull`: the voucher is only spent once
+          -- the BICYCLE is actually in the bag
+          if not Bag.add(game.save, "BICYCLE", 1) then
+            say(t._BikeShopBagFullText, done)
+            return
+          end
+          Bag.remove(game.save, "BIKE_VOUCHER", 1)
+          Flags.set(game.save, "EVENT_GOT_BICYCLE")
+          -- BikeShopExchangedVoucherText carries sound_get_key_item; the
+          -- map runs EnableAutoTextBoxDrawing, so the box still waits for
+          -- a button once the jingle has played (auto.wait, #247)
+          say(t._BikeShopExchangedVoucherText, done, {
+            auto = { wait = true, sound = function()
+              return require("src.core.Sound").play(game.data, "Get_Key_Item")
+            end },
+          })
+        end)
+        return
+      end
+
+      -- .dontHaveVoucher: welcome, then the BICYCLE/CANCEL window
+      say(t._BikeShopClerkWelcomeText, function()
+        local pitch = t._BikeShopClerkDoYouLikeItText
+        game.stack:push(BikeShopWindow.new(game, pitch, function(bought)
+          local function comeAgain()
+            say(t._BikeShopComeAgainText, function()
+              game.stack:pop() -- the window, still up under the text
+              done()
+            end)
+          end
+          if bought then
+            -- a million is out of anyone's reach: BikeShopCantAffordText
+            say(t._BikeShopCantAffordText, comeAgain)
+          else
+            comeAgain()
+          end
+        end))
+        -- PrintText BikeShopClerkDoYouLikeItText, then straight into
+        -- HandleMenuInput: the box types out and hands over without
+        -- waiting, leaving the window's copy of the line on screen
+        say(pitch, nil, { auto = { delay = 0 } })
+      end)
     end,
   },
 }

data/scripts/story3.lua

@@ -111,8 +111,9 @@ M.POKEMON_TOWER_5F = {
 --
 -- PokemonTower6FDefaultScript starts the RESTLESS SOUL battle with NO
 -- Silph Scope check at the trigger -- the scope only decides whether the
--- battle is disguised (IsGhostBattle -> makeGhost: "too scared to move",
--- balls dodged). An earlier version of this port turned the player back
+-- disguise sticks (IsGhostBattle -> makeGhost: "too scared to move", balls
+-- dodged) or comes off in the unveil (makeUnveiledGhost, #492). An earlier
+-- version of this port turned the player back
 -- without the scope and never opened the battle, which made 6F
 -- impassable on any route that skips Rocket Hideout; vanilla lets the
 -- battle open and a POKE_DOLL end it (see wBattleResult below).
@@ -133,7 +134,13 @@ M.POKEMON_TOWER_6F = {
       -- or not the scope revealed it, so the "can't be caught" state rides
       -- the battle instead of IsGhostBattle alone (#444)
       battle.noCatch = true
-      if not game.save.inventory.SILPH_SCOPE then
+      -- InitWildBattle enters disguised for the RESTLESS SOUL either way
+      -- (core.asm:6698-6700).  The scope does not skip the disguise, it
+      -- buys the unveil PrintBeginningBattleText .isMarowak plays over it
+      -- before the battle proceeds as an ordinary wild one (#492).
+      if game.save.inventory.SILPH_SCOPE then
+        battle:makeUnveiledGhost()
+      else
         battle:makeGhost()
       end
       battle.onFinish = function(result)
@@ -353,6 +360,38 @@ M.ROCKET_HIDEOUT_B4F = {
         end))
     end,
 
+    -- Yellow swaps Rocket1/Rocket2 for Jessie & James and keeps a single
+    -- grunt, spelled ROCKETHIDEOUTB4F_ROCKET / TEXT_ROCKETHIDEOUTB4F_ROCKET
+    -- (pokeyellow/scripts/RocketHideoutB4F.asm), so the Red/Blue key above
+    -- never matched there and the LIFT KEY never dropped (#552, a
+    -- regression of #105).  Yellow also moves the drop off the second
+    -- talk: RocketHideoutB4FRocketEndBattleText is text_promptbutton +
+    -- text_asm, so its SetEvent EVENT_ROCKET_DROPPED_LIFT_KEY / ShowObject
+    -- TOGGLE_ROCKET_HIDEOUT_B4F_ITEM_5 run the instant the battle ends.
+    TEXT_ROCKETHIDEOUTB4F_ROCKET = function(game, ow, npc, done)
+      if not ow:trainerDefeated(npc) then
+        ow:engageTrainer(npc, function()
+          -- engageTrainer records the win before it calls back, so this
+          -- is the end-battle text's SetEvent + ShowObject
+          if ow:trainerDefeated(npc)
+             and not game.save.flags.EVENT_ROCKET_DROPPED_LIFT_KEY then
+            game.save.flags.EVENT_ROCKET_DROPPED_LIFT_KEY = true
+            local Commands = require("src.script.Commands")
+            Commands.show_object(
+              { game = game, save = game.save, overworld = ow },
+              "ROCKET_HIDEOUT_B4F", "ROCKETHIDEOUTB4F_LIFT_KEY")
+          end
+          done()
+        end)
+        return
+      end
+      -- RocketHideoutB4FRocketAfterBattleText: later talks only reprint
+      local TextBox = require("src.render.TextBox")
+      game.stack:push(TextBox.new(game,
+        game.data.text._RocketHideoutB4FRocketAfterBattleText
+        or "Oh no! I dropped\nthe LIFT KEY!", done))
+    end,
+
     TEXT_ROCKETHIDEOUTB4F_GIOVANNI = function(game, ow, npc, done)
       -- Giovanni has no trainer-header row (def_trainers 2); his text_asm
       -- owns both the engage and the BeatGiovanniScript aftermath.
@@ -502,45 +541,56 @@ M.GAME_CORNER = {
           end))
       end)
     end,
+    -- GameCornerClerk1Text (scripts/GameCorner.asm): the offer, a
+    -- YesNoChoice, then ¥1000 for 50 coins.  Yellow drops the "1" from the
+    -- object const and from every one of his text labels
+    -- (GameCornerClerkText, pokeyellow/scripts/GameCorner.asm) with an
+    -- identical body, so each line resolves under both spellings and the
+    -- handler is bound to both text ids just below (#552).
     TEXT_GAMECORNER_CLERK1 = function(game, ow, npc, done)
       local TextBox = require("src.render.TextBox")
       local ChoiceBox = require("src.ui.ChoiceBox")
       local t = game.data.text
+      local function line(suffix, fallback)
+        return t["_GameCornerClerk1" .. suffix]
+               or t["_GameCornerClerk" .. suffix]
+               or fallback
+      end
       game.stack:push(TextBox.new(game,
-        (t._GameCornerClerk1DoYouNeedSomeGameCoinsText
-         or "Do you need some\ngame coins?\f¥1000 for 50."), function()
+        line("DoYouNeedSomeGameCoinsText",
+             "Do you need some\ngame coins?\f¥1000 for 50."), function()
         game.stack:push(ChoiceBox.new(game, function(yes)
           if not yes then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1PleaseComePlaySometimeText
-              or "No? Please come\nplay sometime!", done))
+              line("PleaseComePlaySometimeText",
+                   "No? Please come\nplay sometime!"), done))
             return
           end
           -- scripts/GameCorner.asm GameCornerClerk1Text: coins need
           -- the COIN CASE and room for at least 9 coins (Has9990Coins)
           if not game.save.inventory.COIN_CASE then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1DontHaveCoinCaseText
-              or "You don't have a\nCOIN CASE!", done))
+              line("DontHaveCoinCaseText",
+                   "You don't have a\nCOIN CASE!"), done))
             return
           end
           if (game.save.coins or 0) >= 9990 then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1CoinCaseIsFullText
-              or "Oops! Your COIN\nCASE is full.", done))
+              line("CoinCaseIsFullText",
+                   "Oops! Your COIN\nCASE is full."), done))
             return
           end
           if game.save.money < 1000 then
             game.stack:push(TextBox.new(game,
-              t._GameCornerClerk1CantAffordTheCoinsText
-              or "You can't afford\nthe coins!", done))
+              line("CantAffordTheCoinsText",
+                   "You can't afford\nthe coins!"), done))
             return
           end
           game.save.money = game.save.money - 1000
           game.save.coins = math.min(9999, (game.save.coins or 0) + 50)
           game.stack:push(TextBox.new(game,
-            (t._GameCornerClerk1ThanksHereAre50CoinsText
-             or "Thanks! Here are\nyour 50 coins!")
+            line("ThanksHereAre50CoinsText",
+                 "Thanks! Here are\nyour 50 coins!")
             .. ("\fCOINS: %d"):format(game.save.coins), done))
         end))
       end))
@@ -548,6 +598,13 @@ M.GAME_CORNER = {
   },
 }
 
+-- Yellow's coin clerk is GAMECORNER_CLERK / TEXT_GAMECORNER_CLERK where Red
+-- and Blue spell him CLERK1, and the two text_asm bodies are identical, so
+-- one handler answers both ids.  Without the alias the Yellow clerk fell
+-- through to his extracted offer line with no yes/no box behind it (#552).
+M.GAME_CORNER.talk.TEXT_GAMECORNER_CLERK =
+  M.GAME_CORNER.talk.TEXT_GAMECORNER_CLERK1
+
 -- Game Corner prize lists (data/events/prizes.asm, prize_mon_levels.asm).
 -- The six mon prizes differ between Red and Blue; the three TM prizes are
 -- identical, so they are shared and appended to each version's mon list.

data/scripts/story4.lua

@@ -171,6 +171,28 @@ local function dojoBall(species, ownBall, otherBall, askKey)
   end
 end
 
+-- FightingDojoDefaultScript does not use the Master's facing direction for
+-- this battle.  It checks exactly the cell left of him, turns both sprites
+-- toward one another, and then displays his trainer text.  Keeping this out
+-- of trainer sight also lets him keep his original downward-facing pose.
+local function dojoMasterGate(game, ow, x, y)
+  if x ~= 4 or y ~= 3 or game.save.flags.EVENT_BEAT_KARATE_MASTER then
+    return false
+  end
+  local master
+  for _, npc in ipairs(ow.npcs) do
+    if npc.def and npc.def.name == "FIGHTINGDOJO_KARATE_MASTER" then
+      master = npc
+      break
+    end
+  end
+  if not master or ow:trainerDefeated(master) then return false end
+  ow.player.facing = "right"
+  master:facePlayer(ow.player)
+  ow:engageTrainer(master)
+  return true
+end
+
 M.FIGHTING_DOJO = {
   talk = {
     TEXT_FIGHTINGDOJO_HITMONLEE_POKE_BALL =
@@ -197,6 +219,7 @@ M.FIGHTING_DOJO = {
     end
     return false
   end,
+  onStep = dojoMasterGate,
 }
 
 -- -------------------------------------------------------------------

data/scripts/story5.lua

@@ -790,8 +790,19 @@ local function bikeGateGuard(coords, stopText, explainText)
     local t = text(game)
     push(game, t[stopText] or "Hey! Wait up!", function()
       push(game, t[explainText] or "You need a\nBICYCLE for\nCYCLING ROAD!", function()
+        -- pokered's Route16Gate1FGuardScript / Route18Gate1FGuardScript
+        -- (scripts/Route16Gate1F.asm, Route18Gate1F.asm) simulate one
+        -- PAD_RIGHT step after the refusal text, and only clear
+        -- wJoyIgnore / hand control back once that step finishes
+        -- (PlayerMovingRightScript). Without it the player was left
+        -- parked beside the guard's counter with no way past. #518
+        local function shoveRight()
+          ow:scriptMove(ow.player, "right", 1)
+        end
         if dist > 0 then
-          ow:scriptMove(ow.player, "up", dist)
+          ow:scriptMove(ow.player, "up", dist, shoveRight)
+        else
+          shoveRight()
         end
       end)
     end)

data/scripts/story6.lua

@@ -118,6 +118,7 @@ local MANSION_HOLES = {
 M.POKEMON_MANSION_3F.onStep = function(game, ow, x, y)
   for _, h in ipairs(MANSION_HOLES) do
     if x == h[1] and y == h[2] then
+      require("src.core.Sound").play(game.data, "Faint_Fall")
       ow:startWarpTo(h[3], h[4], h[5], ow.player.facing)
       return true
     end

data/scripts/yellow_viridian_old_man.lua

@@ -0,0 +1,145 @@
+-- The Viridian City old-man catch tutorial, Yellow's way
+-- (pokeyellow scripts/ViridianCity.asm, scripts/ViridianCity_2.asm,
+--  scripts/OaksLab.asm).  Registered on top of the shared tables by
+-- data/scripts/init.lua on a Yellow boot.
+--
+-- Yellow has TWO gambler objects where Red/Blue have one:
+--   * VIRIDIANCITY_OLD_MAN    at (17,5) -- a Red/Blue leftover; its
+--     toggle stays OFF forever in Yellow, no script ever shows it.
+--   * VIRIDIANCITY_OLD_MAN2   at (18,9) -- replaces the sleeper the
+--     moment the Pokédex is given (OaksLabOakGivesPokedexScript:
+--     HideObject TOGGLE_LYING_OLD_MAN / ShowObject TOGGLE_OLD_MAN_2).
+--
+-- This is the tutorial old man.  The Red/Blue "Are you in a hurry?"
+-- yes/no script must NOT run against him: Yellow's
+-- _ViridianCityOldManHadMyCoffeeNowText is the apology speech ("I've had
+-- my coffee now ... I'll show you how to catch POKéMON as my apology"),
+-- and the shared story.lua TEXT_VIRIDIANCITY_OLD_MAN rows hang an
+-- invented yes/no over it -- YES printed the TimeIsMoney alias
+-- (_ViridianCityOldManLosingMyTouchText) and NO ran the demo, every
+-- talk, forever (#617).
+--
+-- The real flow (ViridianCityCheckWaitingOldMan + ViridianCityOldMan2Text
+-- + ViridianCityOldManInitialCatchTrainingScript + ...EndInitial... +
+-- ViridianCityPostInitialCatchTraining): stepping into (19,9) -- the gap
+-- east of the sleeper's cell -- faces the old man right and the player
+-- left, prints the apology, and without any choice runs the demo battle
+-- (BATTLE_TYPE_OLD_MAN, RATTATA lvl 5).  After it, the same text pointer
+-- now prints _ViridianCityOldManLosingMyTouchText ("That didn't work!
+-- I must be losing my touch."), the old man walks off (down 6 with the
+-- player on (19,9), right 1 otherwise, Pikachu nudged out of the way
+-- first) and TOGGLE_OLD_MAN_2 hides.  A direct talk does the same.
+
+local M = {}
+
+local OLD_MAN2 = "VIRIDIANCITY_OLD_MAN2"
+
+-- Capture the FUNCTION, not the table: attachBase stores the module
+-- table itself, so once this file's onStep is attached the table's slot
+-- points back here -- delegating through the table would self-recurse.
+-- story5's VIRIDIAN_CITY.onStep chains story.lua's sleeping-old-man
+-- gate and its own gym-lock step (same pattern as yellow_jessie_james).
+local baseViridianStep = require("data.scripts.story5").VIRIDIAN_CITY.onStep
+
+-- pokeyellow text/ViridianCity.asm, _ViridianCityOldManHadMyCoffeeNowText
+-- and _ViridianCityOldManLosingMyTouchText, spelled with the extractor's
+-- markers (line -> \n, cont -> \v, para -> \f)
+local function text(game)
+  return {
+    apology = game.data.text._ViridianCityOldManHadMyCoffeeNowText
+      or "Ahh, I've had my\ncoffee now and I\vfeel great!\fSure, you can go\n"
+      .. "through!\fI'm sorry I was\nso rude to you!\fI see you're using\n"
+      .. "a POKéDEX.\fI'll show you how\nto catch POKéMON\vas my apology.",
+    losingMyTouch = game.data.text._ViridianCityOldManLosingMyTouchText
+      or "That didn't work!\nI must be losing\vmy touch.\fI've run out of\n"
+      .. "POKé BALLs too.\fI have to get some\nat POKéMON MART.",
+  }
+end
+
+-- The row list for the initial-tutorial branch, keyed by where the
+-- player stands when the battle ends (ViridianCityPostInitialCatchTraining
+-- reads wXCoord: (19,9) walks the old man down the corridor, anywhere
+-- else walks him right 1 after moving the follower Pikachu aside).
+local function oldMan2Rows(game, ow, npc)
+  local rows = {
+    { "show_text", "_ViridianCityOldManHadMyCoffeeNowText" },
+    { "old_man_demo" },
+    { "set_flag", "EVENT_COMPLETED_CATCH_TRAINING" },
+    { "show_text", "_ViridianCityOldManLosingMyTouchText" },
+  }
+  if ow.player and ow.player.cellX == 19 then
+    rows[#rows + 1] =
+      { "walk_npc", npc.def.index,
+        { "down", "down", "down", "down", "down", "down" } }
+  else
+    -- ViridianCityMovePikachu (scripts/ViridianCity_2.asm): Pikachu
+    -- steps out of the old man's way before he turns right
+    local PikachuFollower = require("src.world.PikachuFollower")
+    local pika = ow and PikachuFollower.current(ow)
+    if pika then
+      rows[#rows + 1] = { "walk_npc", pika.def.index, { "right" } }
+    end
+    rows[#rows + 1] = { "walk_npc", npc.def.index, { "right" } }
+  end
+  rows[#rows + 1] =
+    { "hide_object", "VIRIDIAN_CITY", OLD_MAN2 }
+  return rows
+end
+
+-- The shared talk handler: TEXT_VIRIDIANCITY_OLD_MAN2's text_asm branch
+-- (ViridianCityOldMan2Text) on EVENT_COMPLETED_CATCH_TRAINING.
+local function oldMan2Talk(game, ow, npc, done)
+  if game.save.flags and game.save.flags.EVENT_COMPLETED_CATCH_TRAINING then
+    local TextBox = require("src.render.TextBox")
+    game.stack:push(TextBox.new(game, text(game).losingMyTouch, done))
+    return
+  end
+  ow.runner:run(oldMan2Rows(game, ow, npc), { npc = npc, onDone = done })
+end
+
+M.VIRIDIAN_CITY = {
+  talk = {
+    TEXT_VIRIDIANCITY_OLD_MAN2 = oldMan2Talk,
+  },
+
+  -- Re-apply the Pokédex swap for a save that already holds the flag but
+  -- was never standing here when it fired (converted .sav imports, same
+  -- shape as story.lua's VIRIDIAN_CITY.onEnter).  Yellow shows OLD_MAN2,
+  -- not the Red/Blue OLD_MAN at (17,5), and also puts away a stray
+  -- OLD_MAN a save made by the pre-#617 build left standing.
+  onEnter = function(game, ow)
+    if not (game.save.flags and game.save.flags.EVENT_GOT_POKEDEX) then
+      return
+    end
+    local Commands = require("src.script.Commands")
+    local ctx = { save = game.save, game = game, overworld = ow }
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN_SLEEPY")
+    Commands.hide_object(ctx, "VIRIDIAN_CITY", "VIRIDIANCITY_OLD_MAN")
+    Commands.show_object(ctx, "VIRIDIAN_CITY", OLD_MAN2)
+  end,
+
+  -- ViridianCityCheckWaitingOldMan: with the Pokédex held and the
+  -- tutorial undone, (19,9) -- the gap east of the old man, the same
+  -- cell the sleeper used to gate -- faces him right, turns the player
+  -- left and starts the OLD_MAN2 flow with no choice.
+  onStep = function(game, ow, x, y)
+    if baseViridianStep and baseViridianStep(game, ow, x, y) then
+      return true
+    end
+    local flags = game.save.flags
+    if not flags.EVENT_GOT_POKEDEX then return false end
+    if flags.EVENT_COMPLETED_CATCH_TRAINING then return false end
+    if x ~= 19 or y ~= 9 then return false end
+    local man
+    for _, npc in ipairs(ow.npcs) do
+      if npc.def and npc.def.name == OLD_MAN2 then man = npc break end
+    end
+    if not man then return false end
+    man.facing = "right"
+    ow.player.facing = "left"
+    oldMan2Talk(game, ow, man, nil)
+    return true
+  end,
+}
+
+return M

docs/anbernic-rg34xxsp.md

@@ -65,6 +65,13 @@ display option — COLORS, TILT, ZOOM, VOID FILL, MAX FPS — works normally. If
 your device turns out to handle the pass, launch with `POKEPORT_GBCFX=1` to
 put the row back.
 
+**PERFORMANCE defaults to LOW here.** The OPTIONS → PERFORMANCE tier defaults
+to AUTO, which reads this device as an ARM Linux handheld and resolves to
+**LOW**: the 3D tilt and survey zoom stay off and the frame rate is capped,
+so the overworld runs smoothly on the H700 out of the box. Bump it to
+BALANCED or HIGH from OPTIONS if you want the extras and your device keeps
+up; see [Performance tier](new-features.md#performance-tier-low-end-devices).
+
 The pack bundles the LÖVE 11.5 aarch64 runtime from
 [PortMaster](https://portmaster.games/), so the device does not need a
 separate `love_11.5` runtime download on first launch. The launcher resolves

docs/gameboy-hardware-limitations.md

@@ -12,7 +12,7 @@ this port.
 
 | # | Mechanic | Value | Why the Game Boy had this limit | Where it lives here |
 |---|---|---|---|---|
-| 1 | Bag capacity | 20 item slots | `wNumBagItems` save block was a fixed 20-entry id/quantity array in SRAM | `src/inventory/Bag.lua:8` (`Bag.CAPACITY = 20`) |
+| 1 | Bag capacity | 20 item slots by default | `wNumBagItems` save block was a fixed 20-entry id/quantity array in SRAM | `Data.constants.bagSize`, read by `src/inventory/Bag.lua` (`Bag.capacity`) |
 | 2 | Party size | 6 Pokémon | `wPartyMon1..6` were 6 fixed save-RAM slots | `src/pokemon/Party.lua:5` (`Party.MAX = 6`) |
 | 3 | PC storage | 12 boxes × 20 Pokémon | `wBoxDataStart` / Bill's PC allocated a fixed 12×20 SRAM block | `src/pokemon/Boxes.lua:7-8` |
 | 4 | Moves per Pokémon | 4 | Fixed 4-move-slot field in the party/box Pokémon struct | `src/pokemon/Pokemon.lua:20`, enforced again in `src/battle/BattleState.lua:1941` |
@@ -38,6 +38,10 @@ this port.
 
 ## Notes
 
+- Mods may patch `constants.bagSize` through the public content registry. The
+  native `save.lua` format keeps every existing item when the configured
+  limit changes; exporting to a cartridge `.sav` still writes only the first
+  20 bag slots because the original SRAM layout has no room for more.
 - PC Box **overflow handling** was deliberately changed even though the
   20×12 box *shape* was kept faithful: instead of Gen 1's "full box discards
   or blocks the deposit," this port spills into the next box with room.

docs/modding.md

@@ -167,5 +167,38 @@ The console understands these verbs (anything else is evaluated as Lua):
 - `trace PAT | trace off` — trace events/hooks matching a glob pattern.
 - `help` — list the verbs.
 
+## Tool input and title-menu hooks
+
+Tool mods that need to act once per game logic tick can wrap `input.step`.
+It runs immediately before queued button edges are promoted, so input added by
+the wrapper is visible during that same fixed step. The callback receives
+`(next, game, dt)` and must call `next(game, dt)`.
+
+`ui.title_menu.items` receives `(next, game, items)` and follows the same
+decorate-after-`next` convention as `ui.start_menu.items`. It is the safe place
+for a tool to offer a fresh-session action before gameplay begins.
+
+Ephemeral tools can wrap `save.write(next, game)` and return `false` to veto a
+progress write before world state is captured or any bytes reach disk.
+
+`render.hud` receives `(next, game, viewport)` after the finished game frame is
+composited and before touch controls draw. The window-space viewport contains
+`width`, `height`, `gameX`, `gameY`, `gameWidth`, `gameHeight`, `scale`, `dpiX`,
+and `dpiY`, so a tool can use the letterbox margins without drawing over the
+playfield or pushing an updating game state.
+
+`render.compose` wraps the whole-window composite in `Renderer:endFrame`. It
+receives `(next, renderer, ctx)`; returning `true` without calling `next` hands
+the mod full control of the window, while calling `next` runs the engine's
+normal single-window composite so the mod can decorate around it. `ctx` carries
+the finished `worldCanvas` and `uiCanvas` with their SGB `zones` / `worldZones`,
+`worldActive`, the frame metrics (`ww`, `wh`, `pw`, `ph`, `ox`, `oy`, `vpw`,
+`vph`, `scale`, `Sx`, `Sy`, `dpiX`, `dpiY`), `renderer:blitCanvas(...)` for a
+palette-correct blit of either canvas into an arbitrary screen rect, and the
+`secondScreen` bridge (`available()` / `push(imageData, w, h)` / `setEnabled`)
+for driving a second physical display. This is what lets a mod lay the two
+passes out as two stacked Game Boy screens, or push one onto a second screen,
+without the engine knowing the layout.
+
 Developer mode also arms the mod loader's dev tripwire, which flags mods
 that reach outside their permission set.

docs/new-features.md

@@ -86,14 +86,20 @@ Game Boy equivalent:
 ## Colors mode
 
 The `2` key (and the Options menu COLORS row) cycles the display mode
-through **OG RED → SGB → ADVANCED → OG → OG INV → SGB INV → CLASSIC → OG RED**.
+through **OG RED → SGB → ADVANCED → OG → OG INV → SGB INV → CLASSIC → OG RED**
+(on Blue the first slot labels **OG BLUE**; on Yellow, **OG YELLOW**).
 The first three are the real colorizations; the rest are DMG-shade novelties:
 
-- **OG RED**: the Game Boy Color boot-ROM look for Pokemon Red -- one global
-  red BG palette + one green OBJ palette, every map, no per-map variation
-  (Pokemon Red has no CGB code, so on a GBC the boot ROM colors it globally).
-  The player/NPCs stay green over the red terrain via the OBP bake +
-  post-zone redraw (`PaletteFX.GBC_BG` / `GBC_OBJ`).
+- **OG RED** / **OG BLUE**: the Game Boy Color boot-ROM look for that cart --
+  one global BG palette + one OBJ palette, every map, no per-map variation
+  (Red/Blue ship no CGB code, so on a GBC the boot ROM colors them globally).
+  The player/NPCs keep the boot-ROM OBJ color over the terrain via the OBP
+  bake + post-zone redraw (`PaletteFX.GBC_BG` / `GBC_OBJ`, or Blue's blue/pink
+  pair).
+- **OG YELLOW** (Yellow playthrough, same `ogred` save id): Pokemon Yellow's
+  authentic GBC look from `CGBBasePalettes` (`data/palettes_yellow.lua`,
+  sourced from pret/pokeyellow). Per-map / per-species colors, not a single
+  boot-ROM ramp -- Yellow was CGB-enhanced.
 - **SGB** (default): the per-map Super Game Boy region palettes
   (`data/sgb/sgb_palettes.asm`). Sprites tint with the region palette, as on
   real SGB. (This is the mode formerly mislabeled "GBC".)
@@ -137,6 +143,41 @@ effect, `=1` forces it available. The Anbernic handheld pack exports `0` from
 its launcher because the device reports `"Linux"` while its GPU is in the
 phone class (see [Anbernic RG34XXSP](anbernic-rg34xxsp.md)).
 
+## Performance tier (low-end devices)
+
+The Options **PERFORMANCE** row scales the port's optional presentation
+extras down for weaker hardware. The extras it governs are the three
+heaviest things the port adds on top of the original -- the whole-screen 3D
+**TILT** (transforms the entire map as a ground plane), the **GBC FX**
+post-process shader (a fullscreen pass), and survey **ZOOM** (zooming out
+renders the connected neighbor maps, a lot of extra overdraw) -- plus a hard
+FPS ceiling. None of this touches game logic, which is fixed-step off `dt`
+(`src/core/FixedStep.lua`), so every tier plays identically; they differ
+only in how much eye-candy the renderer is allowed to do.
+
+| Tier         | TILT | GBC FX | Survey ZOOM | Extra FPS ceiling |
+| ------------ | ---- | ------ | ----------- | ----------------- |
+| **HIGH**     | on   | on     | on          | none              |
+| **BALANCED** | off  | off    | on          | none              |
+| **LOW**      | off  | off    | off         | 60                |
+| **AUTO**     | picks a default from the device (below) |||
+
+- **AUTO** (the default) reads the device once at boot: ARM Linux handhelds
+  (e.g. the RG34XXSP) resolve to **LOW**, phones/tablets and very-low-core
+  desktops to **BALANCED**, and everything else -- a normal desktop, and
+  every existing `options.lua` that predates this option -- to **HIGH**,
+  so the common case is unchanged. See `src/core/Performance.detect`.
+- AUTO only chooses the *default*; all four tiers are selectable, so a
+  wrong guess is one row away from being overridden.
+- The clamps are applied **live** against your stored options and never
+  rewrite them (`Game:applyOptions`), so a lower tier hides your TILT / GBC
+  FX / ZOOM without forgetting them -- raising the tier restores exactly
+  what you had. (This is why the TILT / GBC FX / ZOOM rows still show your
+  saved choice on a clamped tier: it's your preference, waiting for a tier
+  that can afford it.)
+- Persisted as `save.options.performance` (`auto` | `high` | `balanced` |
+  `low`); unit-tested in `tests/engine/performance_tiers.lua`.
+
 ## Peer-to-peer link play (lua-enet)
 
 Trades and link battles connect two copies of the game directly over
@@ -151,6 +192,13 @@ tradeoff vs. the relay). Headless tests drive the protocol over an
 in-memory loopback (`Net.loopbackPair`); under LÖVE the same test file
 also exercises real UDP pairing.
 
+Red, Blue, and Yellow copies link with each other, as the real cable
+does. The compatibility fingerprint hashes only data a link mode can
+actually read, so Yellow's Dragonair/Dragonite catch-rate retunes (the
+only R/B/Y link-surface difference) no longer read as different games
+(issue #511). Moving the fingerprint is a link parity change: builds
+from before this fix will refuse to pair with builds after it.
+
 ## Fair play in link and online matches
 
 A link session is decided by the battle and nothing else, so for its
@@ -161,10 +209,15 @@ duration:
   closes, and apply again after. Fast-forward otherwise runs one peer's
   queue faster than the peer it is locked to and drains a tournament shot
   clock faster than the opponent racing it.
-- **Online play runs vanilla.** Picking ONLINE MATCH or TOURNAMENT with
-  mods enabled offers to switch them all off and relaunch (mods merge at
-  boot, so a restart is the only way). The restart is confirmed, not
-  silent. They stay listed as disabled, ready to switch back on.
+- **Online play runs vanilla, except for your language.** Picking ONLINE
+  MATCH or TOURNAMENT with mods enabled offers to switch the gameplay ones
+  off and relaunch (mods merge at boot, so a restart is the only way). The
+  restart is confirmed, not silent. They stay listed as disabled, ready to
+  switch back on. A mod that declares itself a translation and provably
+  writes nothing but text stays on: the two games hash the same link
+  surface, so a Spanish install and an English one can battle and trade,
+  each reading the game in its own language and naming the other player's
+  party out of its own text.
 - **Only a meaningful split ends a match.** The per-turn state signature
   both peers exchange is split three ways: `actives` and `bench` carry
   species, HP, status, stat stages, PP and the rest of the party, and a
@@ -265,6 +318,20 @@ the last controller restores it immediately. Layout re-derives from the
 window size on rotation. Desktop testing: `POKEPORT_TOUCH=1 love .` forces
 the overlay on and lets the mouse act as a finger (`=0` forces it off).
 
+The launcher's **Touch Controls** button opens a drag editor: move each
+button freely, resize the whole pad with **-/+** (60% to 160%), **Disable**
+to hide the overlay permanently (for controllers / emulation handhelds --
+distinct from the temporary gamepad auto-hide), **Reset** for defaults,
+**Done** to save into `options.lua` as normalized window fractions so a
+different screen keeps the relative placement.
+
+Portrait and landscape are edited and saved separately (#633): the editor
+follows whichever orientation is on screen, and **Reset** only clears that
+one, so a layout that works held upright does not have to double as the
+one used sideways. An `options.lua` from before this split keeps its single
+layout in both orientations until one of them is edited. In-game, Options →
+**TOUCH PAD** toggles the same on/off flag without leaving a play session.
+
 ## Translation support
 
 Every string the player can read is now reachable from a mod, so a
@@ -324,8 +391,11 @@ semantics - so the two windows read as one app. Six tabs:
   party dock, so deposit and withdraw live in one place. Empty slots are
   clickable and create a mon there.
 - **Items**: money, a searchable item picker (replacing the arrows that
-  cycled one id at a time through ~250 items), the 20-slot bag, PC storage
-  with no slot cap, and the eight badges as toggle chips.
+  cycled one id at a time through ~250 items), the configurable bag (20 slots
+  by default), PC storage
+  with no slot cap, and the eight badges as toggle chips. The picker, the bag
+  and PC storage all scroll under the mouse wheel, so the whole catalog is
+  reachable one-handed without typing a query.
 - **Events**: flags, defeated trainers, taken items and per-map object
   toggles, with a real filter field and a two-column paged grid.
 - **Map**: any map rendered with the game's own renderer, warps followable,
@@ -367,3 +437,74 @@ kind, number, height/weight, dex text) to a PNG at 4x scale under
 `prints/` in the save directory, then reports the filename in a dialog.
 No printer hardware or link cable emulation involved; the file is the
 printout.
+
+## Find Mods (community mod indexes)
+
+A FIND MODS tab sits beside MODS in the launcher and browses a published
+mod index: a metadata-only feed listing mods that live in their authors'
+own repositories. No index ships with the launcher and none is ever added
+automatically, so the tab opens on an "Add an index" prompt until you name
+one; paste an index URL or its `owner/repo` and it is remembered in
+`options.lua`. More than one index can be added, and the listings merge.
+
+## Soft reset (all versions)
+
+Holding A, B, START and SELECT together restarts the game the way flicking
+a Game Boy's power switch did, dropping straight back to the title screen.
+It works from anywhere, including mid-battle, which the QUIT entry on the
+start menu cannot do: the original combo is how stationary and gift
+Pokemon get their stats rerolled without sitting through a full relaunch.
+Unsaved progress is discarded, exactly as on hardware.
+
+As on the original, the four buttons have to stay held for 16 straight
+polls (better than a quarter of a second) and any direction in the mix
+cancels it, so it is hard to hit by accident -- including on the on-screen
+touch controls, where it would take four fingers held on four separate
+controls.
+
+## Controls rebinding (CONTROLS screen)
+
+OPTIONS -> CONTROLS lists every Game Boy button with its current keyboard
+key and controller button side by side (Z/A). Press A on a row, then press
+and release the key or pad button you want; the rebind commits on the
+release. If that input already belongs to another row, the two rows swap,
+so no button is ever stranded without an input and no input ever serves
+two buttons. Holding a second key or pad button while the first is still
+down backs out of the capture without touching a keyboard; Escape still
+cancels too. SELECT clears one row back to its default, and START resets
+every binding after a confirmation.
+
+Controllers a system has no mapping for (common on Linux handhelds and
+off-brand pads) report bare button numbers rather than names. Those are
+rebindable on the same screen and show up as JOY1, JOY2 and so on in the
+controller column. Recognized controllers are read only through their
+named buttons, so a rebind on those is never shadowed by the factory
+layout underneath it.
+
+## Mod profiles (#593)
+
+The mod manager's PROFILES tab holds named setups. A profile remembers which
+mods are on, every mod's own options, and which save slot each game version
+plays, so swapping profiles swaps the whole playthrough and not just the mod
+list. The setup that existed before profiles shipped becomes PROFILE 1 the
+first time the manager opens.
+
+EXPORT.. writes the selected profile to `profiles/<NAME>.g1rmodlist` in the
+save directory; drop a `.g1rmodlist` someone shared into that folder and
+IMPORT.. adds it. Imported profiles never overwrite an existing one (a name
+clash gets a number). Mods the shared profile names but that are not installed
+are reported when the profile is applied; installing them is still a manual
+trip through the mods list or Find Mods.
+
+## Windows: no console windows on launcher actions
+
+Checking for updates, browsing a mod index, adding a mod repo, installing a
+mod and picking a ROM all run a host tool (curl, PowerShell) in a child
+process. On Windows those children used to each open their own console
+window, so a session could end up buried under half a dozen of them. The
+game now claims one console for itself at boot and hides it; the children
+inherit that invisible console and nothing pops up. Nothing else changes:
+file pickers are ordinary desktop dialogs and still appear normally, and a
+run started from a terminal (`lovec.exe`, what `scripts\run.ps1` prefers)
+keeps its terminal and its printed output. Set `POKEPORT_CONSOLE=1` to opt
+out.

docs/rfcs/0001-surfing-pikachu-sprite.md

@@ -0,0 +1,96 @@
+# RFC 0001 — Port Yellow's `IsSurfingPikachuInParty` surf sprite
+
+## Status
+
+Proposed. Engine: `Player.lua`, `FieldDefaults.lua`,
+`OverworldController.lua`, `RomExtractor.lua`, `PaletteFX.lua`. Tools:
+`build_rom_data.py`, `extract/sprites.py`, `make_rom_manifest.py`,
+`make_yellow_manifest.py`. Tests: `parity_surfing_pikachu_sprite.lua`,
+`mod_world_tests.lua`.
+
+**Regeneration required.** The manifest and sprite sheet update by
+re-running `make_yellow_manifest.py` against a `pret/pokeyellow`
+checkout, then re-importing the Yellow ROM.
+
+## Motivation
+
+Yellow's `IsSurfingPikachuInParty` + `LoadSurfingPlayerSpriteGraphics2`
+(`home/map_objects.asm`, `home/overworld.asm`) swap the player's
+overworld sheet to `SurfingPikachuSprite` (`gfx/sprites/
+surfing_pikachu.2bpp`, a 16×96 walk sheet — not the minigame sheets)
+when the party mon that knows SURF is a Pikachu. The recomp misses this
+in two places:
+
+1. **Extraction.** `SurfingPikachuSprite` is not in
+   `SpriteSheetPointerTable` — loaded by its own `ld de,` like
+   `RedBikeSprite`. The extractor never sees it, and the symbol is not
+   in the Yellow manifest.
+2. **Engine rule.** `field.playerSprites.surf` is one static
+   (`SPRITE_SEEL`), cached at boot. No seam for "swap when the SURF-mon
+   is a Pikachu."
+
+## The decision it extends
+
+No prior D-number. Extends the surf-field-move port in
+`docs/behavior-porting-notes.md` (the `IsSurfingAllowed` exact port)
+with the player-sprite swap vanilla runs alongside it.
+
+## The exact API delta
+
+Backward-compatible, additive-only.
+
+### `field.playerSprites.surfPikachu`
+
+New optional key alongside `walk`/`surf`/`bike`/`fly`, defaults to
+`SPRITE_SURFING_PIKACHU`. Guarded in `Player.new` so before extraction
+lands the ride keeps the Seel — no plain on-water Pikachu.
+
+### `Player.surfPikachuSprite`
+
+`Player.new` builds a second `SpriteRenderer` when the field resolves.
+`pose()` picks it when `surfing and surfingPikachu`.
+
+### `Player.surfingPikachu` (runtime)
+
+Runtime-only boolean (not persisted); re-derived so a party change
+between save and load is honored.
+
+### `OverworldState:syncSurfingPikachu()`
+
+Sets `player.surfingPikachu` from `partyKnows("SURF")`. Called at every
+surf-state toggle: trySurf, dismount, flyTo, beginTeleportOut,
+warpToHealPoint, forced-surf tile, setMap boot-restore.
+
+### Importer — `SPRITE_SURFING_PIKACHU`
+
+`make_yellow_manifest.py` adds `SurfingPikachuSprite` to
+`YELLOW_EXTRA_SYMBOLS`. `make_rom_manifest.py`'s `sprite_metadata()`
+gains a `surfPikachu` entry (guarded, so Red/Blue unchanged).
+`RomExtractor.extractSprites` + `build_rom_data.py` + `extract/sprites.py`
+each gain a parallel extract mirroring `RedBikeSprite`.
+
+### `PaletteFX.spriteObp`
+
+`SurfingPikachuSprite` joins `RedBikeSprite` in the no-bracket-index
+special case, wearing the player's OBP palette so it colors in GBC mode.
+
+## Migration note for existing mods
+
+**Nothing.** `surf` still defaults to `SPRITE_SEEL`; `surfPikachu`
+only resolves on a Yellow import after regeneration. No manifest or
+`mod.save` shape changes. An eligibility hook that swaps a rental
+SURF-mon still drives the sprite pick via `partyKnows`.
+
+## Parity tests
+
+- **No-mod** (`mod_world_tests.lua`): `surf == "SPRITE_SEEL"`,
+  `surfPikachu == "SPRITE_SURFING_PIKACHU"` seeded at boot. The 19229-check
+  `world & maps v2` suite stays green.
+- **Mod-API** (`parity_surfing_pikachu_sprite.lua`): `syncSurfingPikachu`
+  + `Player:pose` across four party shapes (12/12). The existing
+  `parity_cinnabar_east_surf.lua` (24/24) stays green.
+
+## Deprecation etiquette
+
+Nothing deprecated. Additive: a new `field.playerSprites` key, a new
+runtime flag, a new engine method, a new sprite id.

docs/timing-parity.md

@@ -0,0 +1,382 @@
+# Timing parity with the Game Boy
+
+The port's clock is faithful: `src/core/FixedStep.lua` advances game logic in
+whole 1/60 s steps off wall-clock `dt`, the default speed multiplier is 1x
+(`src/core/GameSpeed.lua:22`), and audio runs on its own real-time accumulator
+so fast-forward cannot pitch it. Almost nothing in `src/` is seconds-based.
+
+What diverges is the **frame budget of composed sequences**. The original
+spends a large fraction of its running time inside `DelayFrames` calls that
+produce no visible change - the pause after a page break, the beat before a
+status move resolves, the drain of an HP bar one point at a time. Those are
+invisible in a screenshot and easy to drop when porting behavior rather than
+timing. Dropping them is why the port reads as faster and snappier than
+hardware even though every individual animation is correct.
+
+This document is the specification: what each sequence costs on hardware, and
+where that number comes from.
+
+## Method
+
+`tools/scan_pokered_delays.ps1` walks the disassembly and reports every
+frame-consuming wait with its enclosing routine label:
+
+| Kind | Meaning | Frames |
+| --- | --- | --- |
+| `DelayFrames` | `ld c, N` + `call DelayFrames` (`home/delay.asm:1`) | N |
+| `DelayFrame` | one vblank wait (`home/vblank.asm:92`) | 1 |
+| `Delay3` | `home/palettes.asm:14`, three frames for a full bg-map update | 3 |
+| `Fade` | the `GBFade*` helpers, expanded to their totals below | 24 or 32 |
+
+Current inventory against `pokered-master`: **450 sites** - 181 `DelayFrames`,
+164 `Delay3`, 65 `DelayFrame`, 31 `GBFade*`, and 9 `DelayFrames` calls whose
+count is computed at runtime.
+
+The four fades all live in `home/fade.asm` and are loops of
+`ld c, 8 / call DelayFrames`:
+
+| Routine | Iterations | Frames | Source |
+| --- | --- | --- | --- |
+| `GBFadeInFromBlack` | 4 | **32** | `home/fade.asm:21` |
+| `GBFadeOutToBlack` | 4 | **32** | `home/fade.asm:43` |
+| `GBFadeOutToWhite` | 3 | **24** | `home/fade.asm:26` |
+| `GBFadeInFromWhite` | 3 | **24** | `home/fade.asm:48` |
+
+## The metric
+
+For each catalog entry, `delta = |port - truth| / truth`; the entry passes at
+`delta <= 0.05`. The headline number is the **exposure-weighted** pass rate,
+weighting each sequence by how often it occurs in ordinary play - a 30-frame
+error on every page of dialogue matters more than a 30-frame error in the Hall
+of Fame. Weights are in the tier column: T1 sequences recur constantly, T2 are
+frequent, T3 are set pieces seen once or twice per playthrough.
+
+## Tier 1 - constant exposure
+
+These recur every few seconds of play and dominate perceived pacing. Both
+sides are verified.
+
+### Overworld and transitions
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| Overworld loop iteration | 2 frames (two `DelayFrame`) | `home/overworld.asm:41-44` | 1 step | `src/core/Game.lua:174` | see note |
+| Warp / door: fade out | **32** | `home/overworld.asm:703` -> `GBFadeOutToBlack` | 32 | `src/render/Transition.lua` | **fixed** |
+| Warp / door: fade in | **0** (map is drawn under blacked palettes, no fade) | `home/overworld.asm:690-703` | 0 | `src/render/Transition.lua` | **fixed** |
+| Return to overworld after a battle | **10** hold, then `GBFadeInFromWhite` **24** | `home/overworld.asm:351-352`, `:22`, `:749-753` | 10 + 24 | `Transition.battleReturn` | **fixed** |
+| Special warp entry (fly / teleport / dungeon) | `Delay3` + `GBFadeInFromWhite` = **27** | `engine/overworld/player_animations.asm:5-7` | - | - | unmeasured |
+| Dungeon-warp arrival hold | **50** | `engine/overworld/player_animations.asm:43` | - | - | unmeasured |
+| Player step (walk) | 16 | 8 loop iterations x 2 frames | 16 | `src/world/Player.lua:14` | **ok** |
+| Turn in place | 2 | one extra loop pass | 2 | `src/world/Player.lua:18` | **ok** |
+
+Note on the overworld loop: `OverworldLoop` calls `DelayFrame` and then falls
+through to `OverworldLoopLessDelay`, which calls it again - so a full pass
+costs 2 frames, and input is sampled every other frame. The port steps logic
+and samples input every frame. This does not change walking speed (the 2-frame
+loop moves 2 px, giving the same 16 frames per tile) but it does halve input
+latency versus hardware. Flagged rather than "wrong": matching it exactly would
+make the port feel less responsive than the original does on a modern display,
+and it is the one place where a deliberate divergence is defensible.
+
+### Text
+
+The typewriter cadence itself is already correct - 1/3/5 frames per character
+from `TextSpeedOptionData`, implemented at `src/render/TextBox.lua:267`. The
+gaps around it are missing.
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| `<CONT>` line scroll (after the A press) | `ProtectedDelay3` 3 + 2x `ScrollTextUpOneLine` 5 = **13** | `home/text.asm:262-277`, `:283-307` | 13 | `src/render/TextBox.lua` | **fixed** |
+| `<PARA>` paragraph break | `ProtectedDelay3` 3 + clear + **20** = **23** | `home/text.asm:230-243` | 23 | `src/render/TextBox.lua` | **fixed** |
+| Page break (`PageChar`) | 3 + **20** = **23** | `home/text.asm:245-260` | 23 | `src/render/TextBox.lua` | **fixed** |
+| `TextCommand_PAUSE` | **30** | `home/text.asm:500` | - | - | unmeasured |
+| `TextCommand_DOTS` | **10** per dot | `home/text.asm:576` | - | - | unmeasured |
+
+The three ProtectedDelay3 frames are a *pre*-input hold: the arrow is already
+up and the button is ignored, because `ManualTextScroll` only starts watching
+the joypad after the delay returns. Mashing A through a long conversation
+therefore cannot go faster than 3 frames per line on hardware, and now cannot
+here either. `PromptText` (`home/text.asm:209-217`) has the same shape, so a
+finished page holds three frames before it can be dismissed too.
+
+**Battle text is a second, separate engine.** `BattleState` types its own
+messages rather than going through `src/render/TextBox.lua`, so none of the
+fixes above reached it and it had drifted further than the overworld box:
+
+| Sequence | Hardware | Source | Was | Now |
+| --- | --- | --- | --- | --- |
+| Per character | 1 glyph per `wOptions & $f` frames (1/3/5, default **3**) | `home/print_text.asm:4-45` | 2 glyphs **per frame**, option ignored | 3 |
+| Per character, A or B held | **1** frame | `print_text.asm:27-36` | 2 glyphs per frame | 1 |
+| `<CONT>` pre-input hold | **3** | `home/text.asm:263-267` | 0 | 3 |
+| `<CONT>` scroll after the press | **10** | `home/text.asm:280-305` | 0 | 10 |
+| Finished page, pre-input hold | **3** | `home/text.asm:213-217` | 0 | 3 |
+
+At the default text speed the battle typewriter was running **six times**
+hardware speed, which is most of why battle text read as a blur, and it
+ignored the OPTION text-speed setting entirely.
+
+`ScrollTextUpOneLine` is `ld b, 5` of `DelayFrame` (`home/text.asm:301-305`)
+and its own comment notes it is "always called twice in a row", so a CONT
+scroll blocks for 10 frames. The port's `scrollPx` slide at
+`src/render/TextBox.lua:305-307` is a cosmetic 8 px at 2 px/frame running in
+`draw()`, not on the logic step, and it does not gate the typewriter.
+
+### Menus
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| Yes/no answer (either option) | **15** | `engine/menus/text_box.asm:322-323`, `:333-334` | 15 | `src/ui/ChoiceBox.lua` | **fixed** |
+| List menu open (bag, PC, party-as-list) | **10** | `home/list_menu.asm:55-56` | 0 | `src/ui/ListMenu.lua` | **-100%, open** |
+| List menu redraw per input | `Delay3` = **3** | `home/list_menu.asm:64` | 0 | - | **-100%, open** |
+| Field move from the party menu | `Delay3` = **3** | `engine/menus/start_sub_menus.asm:4,27,175-203` | 7 (white flash) | `src/render/Transition.lua:8` | see note |
+| Teleport from the party menu | **60** + `Delay3` | `engine/menus/start_sub_menus.asm:224-225` | - | - | unmeasured |
+
+The port's 7-frame `white_flash` models `GBPalWhiteOutWithDelay3` plus the
+screen-tile restore, which is a defensible reading of the same sequence; it is
+listed here to be reconciled against the exact path rather than treated as a
+bug.
+
+### Battle entry
+
+The wipe into a battle and the silhouette slide behind it. Numbers here come
+from **pokered-c** (`C:\Users\Anthony\pokered`), whose `battle_transition.c`
+derives each wipe from `battle_transitions.asm` and then corrects it against a
+live side-by-side with the ROM. Where that project's measured value and a
+naive reading of the asm disagree, the measured value wins - see the inward
+spiral below.
+
+| Sequence | Hardware | Was | Now |
+| --- | --- | --- | --- |
+| DoubleCircle wipe (wild, weak) | 10 x 3 = **30** | 40 | 30 |
+| Circle wipe (wild, strong) | 20 x 3 = **60** | 40 | 60 |
+| Spiral outward (trainer, strong) | 360 fills / 3 per frame = **120** | 40 | 120 |
+| Spiral inward (trainer, weak) | 7 tiles per `Delay3` = **~150** | 40 | 156 |
+| HStripes (dungeon wild, weak) | 20 x 3 = **60** | 24 | 60 |
+| VStripes (dungeon wild, strong) | 18 x 3 = **54** | 24 | 54 |
+| Shrink (dungeon trainer, weak) | 9 x 6 = **54** | 24 | 54 |
+| Split (dungeon trainer, strong) | 9 x 6 = **54** | 24 | 54 |
+| Flash before the circle wipes | 12 x 2 x 3 = **72** | 72 | 72 |
+| Black hold before the battle draws | not stated by pokered; ~30 floor, calibrated **60** | 30 | 60 |
+| Silhouette slide in | 144 px at 2 px/frame = **72** | 40 (160 px at 4 px/frame) | 72 |
+| Trainer intro, before balls + text | `WaitForSoundToFinish` + `DelayFrames 20` | 0 | sfx wait + 20 |
+
+The trainer intro's sound is `SFX_Silph_Scope`, extracted here as
+`Trainer_Appeared` (`tools/rom_manifest.json` `audio.sfxHeaders`, bank 8 /
+`$42bb`). It was being extracted and never played by anything. It now plays
+into a clear window: `PrintBeginningBattleText .trainerBattle` does
+`PlaySound` then `WaitForSoundToFinish`, which **blocks**, and only then
+`DelayFrames 20` before `DrawAllPokeballs` and the text. `BattleState`'s
+message queue grew a `waitSound` row for that, since `WaitForSoundToFinish`
+waits on the sound actually stopping rather than on a fixed frame count.
+
+**Scripted battles were skipping the transition entirely.** `BattleTransition`
+runs from `DoBattleTransitionAndInitBattleVariables`, which both
+`InitBattleCommon` (`core.asm:6680`, trainers) and `InitWildBattle` (`:6699`)
+call unconditionally - every battle on hardware enters through a wipe. In the
+port only `OverworldState:pushBattle` built one, and `Commands.start_battle`
+pushed the `BattleState` straight onto the stack. The trainer-*sight* path
+went through `pushBattle`, but every **script-driven** battle did not: gym
+leaders, the rival, Giovanni, and every scripted wild encounter cut straight
+to the battle screen with no transition at all. The catch tutorial
+(`old_man_demo`) had the same gap; `InitWildBattle` has no
+`BATTLE_TYPE_OLD_MAN` special case, so it gets a wipe too.
+
+**Beyond 160x144.** Both halves of the transition used to stop at the classic
+letterbox. The flash filled the 160x144 UI canvas, and the wipe handed the
+surrounding window a generic centre-out square cascade
+(`Renderer:drawBattleCascade`) regardless of which of the eight styles was
+running - so at any zoom a spiral read as "a spiral in a box, with something
+else happening around it".
+
+- The flash is a palette write (`rBGP`), and a palette register tints every
+  pixel the LCD shows; there is no "outside the screen" for it to miss. It is
+  now published to the renderer as a screen-space veil and painted over the
+  finished composite, so it covers the whole surface at any zoom.
+- The spiral and circle walks are now generated for whatever grid the window
+  works out to (`BattleTransition.gridOrder`), and the area outside the
+  letterbox is filled in that order instead of the square cascade. The
+  authentic 20x18 builders still own the letterbox itself, overrun and all,
+  so nothing changes at 1x. The generic builders are deliberately *not* the
+  ROM's walk - out there the hardware has no behaviour to be faithful to,
+  only a shape to continue.
+- `shrink`, `split` and the two stripe styles are plain geometry rather than
+  a tile order, so they keep the cascade for now. Extending them is
+  rectangles, not a walk, and has not been done.
+
+Note that the **flash is wild-only**: `BattleTransition_FlashScreen` is called
+from `BattleTransition_Circle` (`:585`) and `BattleTransition_DoubleCircle`
+(`:628`) and nowhere else. A trainer battle's transition is the spiral -
+inward against a weaker foe, outward against a stronger one
+(`wBattleTransitionSpiralDirection`, `:119-126`) - with no flash in front of
+it. The port's `flash` mapping was already correct; the transition simply
+never ran for those battles.
+
+Two of these deserve their reasoning recorded:
+
+**The inward spiral** writes one tile per iteration and calls
+`BattleTransition_TransferDelay3` every seventh tile. That helper is not a
+one-frame transfer - it is `ld a,1 / ldh [hAutoBGTransferEnabled] / call
+Delay3 / xor a / ldh [...]` (`battle_transitions.asm:619`), so the cadence is
+7 tiles per **three** frames. Reading it as one frame runs the whole wipe 3x
+too fast, ~46 frames against the ROM's ~150. pokered-c hit that exact bug and
+caught it on a live comparison.
+
+**The black hold** is not a number pokered states anywhere; it is incidental
+load cost that a modern port does not pay. The derivable floor is ~13 frames
+(`LoadHpBarAndStatusTilePatterns` 4, `LoadHudTilePatterns` 2, `ClearScreen`'s
+`Delay3` 3, the `DisableLCD` LY wait 1, `Delay3` after `EnableLCD` 3), but the
+two sprite decompressors (`UncompressSpriteFromDE` for the 7x7 front pic and
+`LoadPlayerBackPic`'s uncompress + `ScaleSpriteByTwo`) are bit-level RLE/delta
+decoders that cannot be cycle-counted from the asm at all. So the derivation
+bottoms out around 25-30 with an unbounded remainder. pokered-c set 60 by ear
+against the real ROM and marked it ~95% right rather than frame-matched. The
+credible range is 30-60; it should not be "corrected" down toward the floor on
+the strength of the derivation, because the omitted decompressors are exactly
+the unbounded part. Pinning it exactly wants a frame-by-frame capture.
+
+### Battle turns
+
+| Sequence | Hardware | Source | Port | Port source | Delta |
+| --- | --- | --- | --- | --- | --- |
+| Player HP bar drain of D HP over P pixels | **D + 2P + 6** | `engine/gfx/hp_bar.asm:81-135`, `:140-159`, `:234` | D + 2P + 6 | `src/battle/BattleState.lua` `stepHPDrain` | **fixed** |
+| Enemy HP bar drain over P pixels | **2P + 5** (no per-HP frame) | same, gated at `:207-209` | 2P + 5 | same | **fixed** |
+| Status move / missed move beat | **30** | `engine/battle/core.asm:3145,3158,3185-3186`; enemy `:5588` | 30 | `EffectRegistry` `missBeat`, `BattleState:performMove` | **fixed** |
+| Applying anim type 1, vertical shake b=8 | **48** | `animations.asm:500-503` | 48 | `BattleState:applyHitFx` | ok |
+| Applying anim type 2, fast horizontal b=8 | **72** | `animations.asm:505-508` | 72 | same | ok |
+| Applying anim type 3, slow horizontal 6,2 | **48** | `animations.asm:510-512,526-549` | 48 | same | ok |
+| Applying anim type 4, `AnimationBlinkMon` | **60** | `animations.asm:514-516`, `:1360-1376` | 60 | same | **fixed** |
+| Applying anim type 5, fast horizontal b=2 | **18** | `animations.asm:518-521` | 18 | same | ok |
+| Applying anim type 6, slow horizontal 3,2 | **24** | `animations.asm:523-525` | 24 | same | ok |
+| Faint slide-down | **14** (`PIC_HEIGHT` x `DelayFrames 2`) | `engine/battle/core.asm:1186-1222` | 14 | `BattleState:onFaint` | **fixed** |
+| Before every move animation | `Delay3` = **3** | `engine/battle/core.asm:6635-6640` | 3 | `BattleState:updateQueue` | **fixed** |
+| Battle start, after enemy send-out | **40** | `engine/battle/core.asm:152-156` | 40 | `BattleState:enter` | **fixed** |
+| Poison / burn / leech-seed tick | **20** | `engine/battle/core.asm:529-530` | 20 | `src/battle/BattleState.lua:1817` | **ok** |
+| Switch player mon | **50** | `engine/battle/core.asm:2421-2422` | 50 | `src/battle/BattleState.lua:1666-1668` | **ok** |
+| Post-hit hold (crit text or not) | **20** | `engine/battle/core.asm:3798-3814` | 20 | `EffectRegistry.runDamaging` | **fixed** |
+| Fainted mon slide-down | **2** per row | `engine/battle/core.asm:1216-1217` | - | - | unmeasured |
+| Trainer pic slide off | **2** per column | `engine/battle/core.asm:1267-1268` | - | - | unmeasured |
+| Trainer battle victory | **40** | `engine/battle/core.asm:940-941` | - | - | unmeasured |
+| Player blackout | **40** | `engine/battle/core.asm:1143-1144` | - | - | unmeasured |
+| No moves left (Struggle) | **60** | `engine/battle/core.asm:2753-2754` | - | - | unmeasured |
+| Send-out animation | `Delay3` + **4** + **5** | `engine/battle/core.asm:6814-6830` | - | - | unmeasured |
+
+The HP bar was the single largest battle divergence. `UpdateHPBar` steps **one
+HP point per loop iteration**; each iteration pays 1 frame in
+`UpdateHPBar_PrintHPNumber` whenever `wHPBarType != 0` - the player's own HUD
+and the party menu, but not the enemy HUD - plus 2 frames for each pixel the
+bar actually moves. The tail (`.animateHPBarDone`, `:132-135`) prints the
+number once more, animates one last pixel and falls into `Delay3`, so it costs
+6 frames player-side and 5 enemy-side.
+
+A 150 HP mon losing everything therefore costs 150 + 96 + 6 = **252 frames
+(4.2 s)** on the player's HUD, against 96 + 5 = 101 on the enemy's. The port
+used a flat `maxHP/96` - the enemy-side rate applied to both sides - and ran
+that same drain in 96 frames (1.6 s).
+
+## Tier 2 - frequent
+
+Status-effect failures (`engine/battle/effects.asm:161,1162,1205`) hold **50**
+frames each. `SwitchAndTeleportEffect` uses 50 and 20
+(`:834-901`). Evolution holds **50** then **40**
+(`engine/pokemon/evos_moves.asm:123,155`). The healing machine
+(`engine/overworld/healing_machine.asm`), item effects
+(`engine/items/item_effects.asm`, 259 frames across 8 sites), and the fishing
+animation (**10** then **100**, `engine/overworld/player_animations.asm:380,399`)
+are all in this tier.
+
+## Tier 3 - set pieces
+
+Highest total budgets in the scan, all seen rarely:
+`engine/movie/hall_of_fame.asm` (529 frames / 7 sites),
+`engine/link/cable_club.asm` (507 / 12), `engine/movie/credits.asm` (502 / 7),
+`engine/movie/trade.asm` (494 / 19), `engine/movie/intro.asm` (317 / 7),
+`engine/menus/main_menu.asm` (271 / 15), `engine/menus/save.asm` (250 / 3),
+`engine/battle/end_of_battle.asm` (200 / 1, the link-battle win/lose string).
+Several of these already have faithful implementations - see
+`src/ui/IntroMovie.lua`, `src/ui/Credits.lua`, `src/ui/HallOfFame.lua`, whose
+constants cite their asm sources directly.
+
+## Status
+
+Closed, and locked by `tests/engine/timing_parity.lua`:
+
+1. **Text page and CONT breaks** - were 0 frames where hardware spends 13-23,
+   on every page of every dialogue in the game. Now exact, including the
+   three-frame pre-input hold that swallows a mashed A.
+2. **Player HP bar drain** - was ~2.5x too fast on a typical mon. Now steps
+   one HP point at a time at the hardware rate, with the enemy HUD correctly
+   cheaper than the player's.
+3. **Warp fade** - was a symmetric 12/12; now 32 out and no fade in, which is
+   both the right duration and the right shape.
+4. **Yes/no answer** - was 0 frames where hardware spends 15, with the cursor
+   snapping to NO on B for the duration as `.choseSecondMenuItem` does.
+
+5. **Battle entry** - every wipe ran at a flat 40/24 against budgets of 30-156,
+   the silhouette slide was 40 frames against 72, the black hold was half
+   what pokered-c calibrated, and the trainer intro's 20-frame gap before the
+   balls and text was missing entirely. This was the single most compressed
+   stretch in the game.
+
+6. **Battle turns** - the type-4 blink ran at 20 frames against 60. That is
+   the applying animation for every plain damaging move the player uses, so
+   it was the single most-repeated timing error in the game. The 30-frame
+   beat that hardware spends on every status move and every miss was missing
+   entirely. The faint slide, unusually, ran *slower* than hardware (30
+   against 14).
+
+Two things worth recording about that last batch, because both contradict a
+plausible reading:
+
+- **`PrintCriticalOHKOText`'s 20-frame hold is not conditional.** The
+  "no critical hit" early-out at `core.asm:3799` jumps to `.done`, and
+  `.done` *is* the `ld c, 20 / jp DelayFrames`. Every landed hit pays it,
+  which is where the beat before "It's super effective!" comes from.
+- **`StartBattle`'s 40-frame hold is not conditional either.** The `call nz`
+  at `core.asm:154` gates only `EnemySendOutFirstMon`; the `DelayFrames 40`
+  under it runs for wild battles too, and it lands *between* the enemy's
+  send-out and `.playerSendOutFirstMon` (`:166`) rather than at the end of
+  the intro.
+
+Trainer victory (24-frame scroll-in + 40-frame hold) and the ball shake
+(`SFX_TINK` + `DelayFrames 40` per rock) were already correct -
+`BattleState.lua`'s `wait = 64` and `AnimPlayer.lua`'s `emit(40)`. Note that
+pokered-c's `BUI_TRAINER_VICTORY_SLIDE` comment calls the scroll-in 14
+frames; `_ScrollTrainerPicAfterBattle` is 6 loop passes of `DelayFrames 4`,
+so 24 is right and this port already had it.
+
+**Leaving a battle was a cut, not a fade.** `EnterMap` checks
+`BIT_BATTLE_OVER_OR_BLACKOUT` and calls `MapEntryAfterBattle`
+(`home/overworld.asm:22`), which is `GBFadeInFromWhite` - so the map fades up
+from white over 24 frames, behind the 10-frame hold at `:351-352`. The port
+popped the battle and the overworld was simply there. `Transition.battleReturn`
+supplies both halves, and steps the veil in three palette stages of 8 frames
+rather than tweening it, because `GBFadeIncCommon` writes a palette and holds
+it with `ld c, 8 / call DelayFrames` (`home/fade.asm:30-41`) three times over.
+
+It is wrapped around `battle.onFinish` in `OverworldState:pushBattle` - the
+one funnel every battle goes through - rather than living in `afterBattle`.
+That placement matters: a script-driven **win** defers `afterBattle` into
+`ctx.afterScript` so an evolution screen cannot be buried under the trainer's
+follow-up text (`Commands.start_battle`), and a fade inside `afterBattle`
+inherited that deferral. On a rival battle it fired after the post-battle
+dialogue *and* the rival's walk-off, rather than when the battle ended.
+
+The rest of `onFinish` runs as the fade's `onDone`, which is also the hardware
+order: `MapEntryAfterBattle` fades the map back in and only then does the map
+script run. The overworld is frozen meanwhile - `StateStack` updates the top
+state only - so nothing moves under the white.
+
+Hardware skips the fade on a dark map (`wMapPalOffset` nonzero takes the
+`LoadGBPal` branch at `:754`). This port has no `wMapPalOffset` equivalent -
+no map needs FLASH to be lit - so that branch is unreachable here;
+`battleReturn` accepts `opts.instant` for it if that ever changes.
+
+Still open, hardware number confirmed but not yet wired:
+
+- List menu open (10) and per-input redraw (`Delay3`).
+- Every battle-table row marked "unmeasured" above - the status/miss beat (30)
+  is the highest-exposure of them, since it is paid on every status move and
+  every miss.
+
+Entries marked "unmeasured" have confirmed hardware numbers but the port side
+has not been traced; they are remaining work, not known-good.

main.lua

@@ -10,7 +10,7 @@
 
 local editorMode = os.getenv("POKEPORT_EDITOR") == "1" or POKEPORT_EDITOR_MODE == true
 
-local Game, EditorApp, Importer
+local Game, EditorApp, Importer, TouchEditor
 
 local autopilot -- optional scripted-input dev tool (tests/autopilot.lua)
 local driverCo  -- optional frame-driver (POKEPORT_DRIVER=file.lua): a
@@ -134,6 +134,26 @@ function closeEditor()
   end
 end
 
+-- ------------------------------------------------------------ touch controls editor
+-- Suspends the launcher while the player drags on-screen buttons / toggles
+-- the overlay off (#327).  No ROM cache needed -- options.lua only.
+local touchEditorHost
+local closeTouchControlsEditor  -- forward declaration
+
+local function openTouchControlsEditor()
+  touchEditorHost = Importer
+  Importer = nil
+  TouchEditor = require("src.ui.TouchControlsEditor")
+  TouchEditor.load({ onClose = function() closeTouchControlsEditor() end })
+end
+
+function closeTouchControlsEditor()
+  if TouchEditor and TouchEditor.unload then TouchEditor.unload() end
+  TouchEditor = nil
+  Importer = touchEditorHost
+  touchEditorHost = nil
+end
+
 local function bootGame(version)
   -- The launcher hands us the chosen game (Red / Blue / Yellow); scripted and
   -- headless runs fall back to POKEPORT_VERSION, then Red.  Set the active
@@ -164,6 +184,11 @@ local function bootGame(version)
 end
 
 function love.load(args)
+  -- Before anything can shell out (update check, mod index, ROM picker),
+  -- claim one hidden console on Windows so those children inherit it instead
+  -- of each flashing their own cmd.exe window (#606).  No-op elsewhere.
+  require("src.core.HostShell").hideHostConsole()
+
   -- Self-updater boot shell: a fused build may mount and chainload a newer
   -- downloaded payload here.  True means it took over, so we must stop.  A
   -- dev / source checkout no-ops (see src/update/Boot.lua).
@@ -239,11 +264,17 @@ function love.load(args)
   Importer = RomImporter.new(function(version)
     Importer = nil
     bootGame(version)
-  end, { launcher = true, forceImport = forceImport, onEditSave = openEditor })
+  end, {
+    launcher = true,
+    forceImport = forceImport,
+    onEditSave = openEditor,
+    onEditTouchControls = openTouchControlsEditor,
+  })
 end
 
 function love.update(dt)
   if editorMode then return EditorApp.update(dt) end
+  if TouchEditor then return TouchEditor.update(dt) end
   if Importer then return Importer:update(dt) end
 
   -- Scripted runs (autopilot / POKEPORT_DRIVER) observe and act exactly
@@ -283,6 +314,7 @@ end
 
 function love.draw()
   if editorMode then return EditorApp.draw() end
+  if TouchEditor then return TouchEditor.draw() end
   if Importer then return Importer:draw() end
 
   Game:draw()
@@ -303,60 +335,61 @@ end
 
 function love.keypressed(key, scancode, isrepeat)
   if editorMode then return EditorApp.keypressed(key) end
+  if TouchEditor then return TouchEditor.keypressed(key) end
   if Importer then return Importer:keypressed(key) end
   Game:keypressed(key)
 end
 
 function love.keyreleased(key)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return end
   Game:keyreleased(key)
 end
 
 function love.gamepadpressed(joystick, button)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:gamepadpressed(joystick, button) end
   Game:gamepadpressed(joystick, button)
 end
 
 function love.gamepadreleased(joystick, button)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:gamepadreleased(joystick, button) end
   Game:gamepadreleased(joystick, button)
 end
 
 function love.gamepadaxis(joystick, axis, value)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:gamepadaxis(joystick, axis, value) end
   Game:gamepadaxis(joystick, axis, value)
 end
 
 function love.joystickpressed(joystick, button)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:joystickpressed(joystick, button) end
   Game:joystickpressed(joystick, button)
 end
 
 function love.joystickreleased(joystick, button)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:joystickreleased(joystick, button) end
   Game:joystickreleased(joystick, button)
 end
 
 function love.joystickaxis(joystick, axis, value)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:joystickaxis(joystick, axis, value) end
   Game:joystickaxis(joystick, axis, value)
 end
 
 function love.joystickhat(joystick, hat, direction)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return Importer:joystickhat(joystick, hat, direction) end
   Game:joystickhat(joystick, hat, direction)
 end
 
 function love.joystickremoved(joystick)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return end
   Game:joystickremoved(joystick)
 end
@@ -365,7 +398,7 @@ end
 -- direction's key-up can be delivered to the OS instead of the game while
 -- unfocused, so reset input on either transition rather than trust it.
 function love.focus(f)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then
     if Importer.focus then Importer:focus(f) end
     return
@@ -375,13 +408,19 @@ end
 
 -- v is true when the window becomes visible again, false on minimize.
 function love.visible(v)
-  if editorMode then return end
+  if editorMode or TouchEditor then return end
   if Importer then return end
   Game:visible(v)
 end
 
 function love.touchpressed(id, x, y, dx, dy, pressure)
   if editorMode then return end
+  if TouchEditor then
+    -- iOS synthesizes mousepressed for the primary touch (same as the
+    -- launcher); Android drives the editor through love.touch directly.
+    if love.system.getOS() == "iOS" then return end
+    return TouchEditor.touchpressed(id, x, y)
+  end
   if Importer then
     -- iOS: LÖVE already synthesizes a mousepressed for the primary touch,
     -- and love.mousepressed below forwards that to the Importer, so
@@ -399,12 +438,20 @@ end
 
 function love.touchmoved(id, x, y, dx, dy, pressure)
   if editorMode then return end
+  if TouchEditor then
+    if love.system.getOS() == "iOS" then return end
+    return TouchEditor.touchmoved(id, x, y)
+  end
   if Importer then return end
   Game:touchmoved(id, x, y)
 end
 
 function love.touchreleased(id, x, y, dx, dy, pressure)
   if editorMode then return end
+  if TouchEditor then
+    if love.system.getOS() == "iOS" then return end
+    return TouchEditor.touchreleased(id, x, y)
+  end
   if Importer then return end
   Game:touchreleased(id, x, y)
 end
@@ -414,12 +461,36 @@ function love.wheelmoved(x, y)
     if EditorApp.wheelmoved then return EditorApp.wheelmoved(x, y) end
     return
   end
+  if TouchEditor then return end
   if Importer then return end
   Game:wheelmoved(x, y)
 end
 
-function love.mousepressed(x, y, button)
-  if Importer then return Importer:mousepressed(x, y, button) end
+function love.mousepressed(x, y, button, istouch)
+  if TouchEditor then
+    -- Android primary touch already arrived via love.touchpressed; a second
+    -- mouse path would double-fire Done / begin a second drag.
+    if love.system.getOS() == "Android" then return end
+    return TouchEditor.mousepressed(x, y, button)
+  end
+  if Importer then
+    -- The same double-fire TouchEditor guards against, which the launcher was
+    -- missing: love.touchpressed above forwards the primary touch to the
+    -- Importer on Android, and LÖVE ALSO synthesizes a mouse press for that
+    -- same touch, so one tap ran every launcher button twice.  On Import that
+    -- meant two choose() calls and two stacked SAF picker activities: the
+    -- player picked their ROM, the top picker closed, and the second was still
+    -- underneath asking for it again, which is the "import the file twice"
+    -- in #553.  Filtering on istouch keeps a real mouse (DeX, a Chromebook, a
+    -- USB mouse) working, which an Android-wide return would have broken.
+    --
+    -- ANDROID ONLY, and the OS test is load bearing: love.touchpressed above
+    -- returns early on iOS and never forwards, so there the synthesized mouse
+    -- press is the ONLY event the launcher gets.  Filtering istouch on both
+    -- killed every tap on iOS outright.
+    if istouch and love.system.getOS() == "Android" then return end
+    return Importer:mousepressed(x, y, button)
+  end
   if editorMode and EditorApp.mousepressed then
     return EditorApp.mousepressed(x, y, button)
   end
@@ -429,6 +500,10 @@ function love.mousepressed(x, y, button)
 end
 
 function love.mousereleased(x, y, button)
+  if TouchEditor then
+    if love.system.getOS() == "Android" then return end
+    return TouchEditor.mousereleased(x, y, button)
+  end
   if Importer then return end
   if editorMode and EditorApp.mousereleased then
     return EditorApp.mousereleased(x, y, button)
@@ -439,6 +514,10 @@ function love.mousereleased(x, y, button)
 end
 
 function love.mousemoved(x, y)
+  if TouchEditor then
+    if love.system.getOS() == "Android" then return end
+    return TouchEditor.mousemoved(x, y)
+  end
   if editorMode or Importer then return end
   if mouseTouch and Game and love.mouse.isDown(1) then
     Game:touchmoved("mouse", x, y)
@@ -446,6 +525,7 @@ function love.mousemoved(x, y)
 end
 
 function love.textinput(text)
+  if TouchEditor then return end
   if Importer then return Importer:textinput(text) end
   if editorMode and EditorApp.textinput then
     return EditorApp.textinput(text)

mobile/ANDROID.md

@@ -50,6 +50,44 @@ chosen file under the app save directory as `picked_rom.gb`,
 from that folder on Choose / refocus; see `docs/launcher.md`. The APK payload
 itself remains data-free (no embedded ROM or generated cache).
 
+### Step bridge (Pokéwalker mod)
+
+`love.system.syncHealthSteps()` → `GameActivity.syncHealthSteps` (same
+JNI route as the picker: `common/android.cpp` →
+`modules/system/System.cpp` → `wrap_System.cpp`). The Java side does a
+one-shot read of the hardware `TYPE_STEP_COUNTER` sensor (cumulative
+since boot, counted by the OS whether or not any app runs), anchors the
+reading in `SharedPreferences` so a walk is never credited twice
+(a reading below the anchor means the phone rebooted → re-anchor without
+crediting), and stages the delta as `steps_pending.json` in the save
+identity dir — the same contract as the iOS `GRHealthBridge`. Nothing in
+the base game calls it; the consumer is the
+[Pokéwalker mod](https://github.com/mresnick67/Gen1ReComp-Pokewalker),
+installed as a mod `.zip` at runtime (its SYNC STEPS option defaults
+off).
+
+Android 10+ gates the sensor behind the `ACTIVITY_RECOGNITION` runtime
+permission (declared in `app/src/main/AndroidManifest.xml`; keep it out
+of the build script's permission trim). The first
+`syncHealthSteps()` call shows the system prompt; on grant the sensor
+read runs immediately (`onRequestPermissionsResult`,
+`STEP_PERMISSION_REQUEST_CODE`).
+
+### Network transport (mod index / mod updates)
+
+`love.system.httpDownload(url, absPath [, userAgent [, accept]])` ->
+`GameActivity.httpDownload` (same JNI route as the picker and the step
+bridge: `common/android.cpp` -> `modules/system/System.cpp` ->
+`wrap_System.cpp`). Android ships no `curl`, which is what the desktop
+builds fetch the mod index, mod release lists and mod zips with, so the
+"Find mods" tab used to fail with "curl is not available on this
+platform" (#597). The Java side is a blocking `HttpsURLConnection` GET
+(https only, redirects followed by hand, body renamed into place only
+once complete) and runs on LOVE's Lua thread, never the UI thread.
+`src/core/HostShell.lua` picks the transport: curl when present,
+otherwise this bridge; an APK older than the bridge simply reports no
+transport, exactly as a missing curl does.
+
 ### SDK / NDK
 
 love-android 11.5a expects:
@@ -82,9 +120,9 @@ scripts, tests, and mobile build sources are excluded.
 | --- | --- |
 | `app.application_id` | `com.theboisclub.pokemonred` |
 | `app.name` | Pokemon Red |
-| `app.orientation` | `portrait` |
+| `app.orientation` | `fullUser`. This is only the manifest default: SDL requests FULL_SENSOR at window creation (resizable window, no `SDL_HINT_ORIENTATIONS`), and `GameActivity.setOrientationBis` remaps that to FULL_USER so the device's rotation lock is honoured. |
 | `app.version_name` / `app.version_code` | set from `--version X.Y.Z` (code = major*10000 + minor*100 + patch); left as-is if `--version` is omitted |
-| Permissions | INTERNET / RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH kept |
+| Permissions | RECORD_AUDIO / WRITE_EXTERNAL_STORAGE stripped; VIBRATE + BLUETOOTH + INTERNET (link play, mod index) + ACTIVITY_RECOGNITION (step bridge) kept |
 
 ## Releases
 

mobile/android/app/src/main/AndroidManifest.xml

@@ -8,6 +8,11 @@
        the link screen shows as "(Operation not permitted)" (issue #287).
        scripts/build_android.sh must not strip this again. -->
   <uses-permission android:name="android.permission.INTERNET" />
+  <!-- Step bridge: love.system.syncHealthSteps reads the hardware step
+       counter, which Android 10+ gates behind this runtime permission.
+       Requested only on the first sync call (the Pokéwalker mod's SYNC
+       STEPS option); scripts/build_android.sh must not strip it. -->
+  <uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
 <!-- OpenGL ES 2.0 -->
   <uses-feature android:glEsVersion="0x00020000" />
   <!-- Touchscreen support -->

mobile/android/love/src/jni/love/src/common/android.cpp

@@ -219,6 +219,75 @@ bool showCreateDocument(const char *suggestedName)
 	return result;
 }
 
+bool syncHealthSteps()
+{
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+
+	jmethodID method = env->GetStaticMethodID(activity, "syncHealthSteps", "()Z");
+	jboolean result = env->CallStaticBooleanMethod(activity, method);
+
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
+bool restartApp()
+{
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+
+	// Old APK / new liblove skew: fail soft so HostShell.restart can fall
+	// back to a clean quit instead of aborting on a missing method (#575).
+	jmethodID method = env->GetStaticMethodID(activity, "restartApp", "()Z");
+	if (method == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return false;
+	}
+
+	// Does not return on success: the Java side exits the process.
+	jboolean result = env->CallStaticBooleanMethod(activity, method);
+
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
+bool httpDownload(const char *url, const char *destPath, const char *userAgent, const char *accept)
+{
+	if (url == nullptr || destPath == nullptr)
+		return false;
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+
+	// Old APK / new liblove skew: report "no transport" the same way a
+	// missing curl does, instead of aborting on a missing method (#597).
+	jmethodID method = env->GetStaticMethodID(activity, "httpDownload",
+		"(Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;Ljava/lang/String;)Z");
+	if (method == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return false;
+	}
+
+	jstring jurl = env->NewStringUTF(url);
+	jstring jdest = env->NewStringUTF(destPath);
+	jstring jua = env->NewStringUTF(userAgent != nullptr ? userAgent : "gen1recomp");
+	jstring jaccept = accept != nullptr ? env->NewStringUTF(accept) : nullptr;
+
+	jboolean result = env->CallStaticBooleanMethod(activity, method, jurl, jdest, jua, jaccept);
+
+	env->DeleteLocalRef(jurl);
+	env->DeleteLocalRef(jdest);
+	env->DeleteLocalRef(jua);
+	if (jaccept != nullptr)
+		env->DeleteLocalRef(jaccept);
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
 /*
  * Helper functions for the filesystem module
  */
@@ -851,4 +920,51 @@ const char *getArg0()
 } // android
 } // love
 
+extern "C" __attribute__((visibility("default")))
+int love_android_secondary_ready()
+{
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+	jmethodID m = env->GetStaticMethodID(activity, "hasSecondaryDisplay", "()Z");
+	jboolean ready = JNI_FALSE;
+	if (m)
+		ready = env->CallStaticBooleanMethod(activity, m);
+	else
+		env->ExceptionClear();
+	env->DeleteLocalRef(activity);
+	return ready ? 1 : 0;
+}
+
+extern "C" __attribute__((visibility("default")))
+void love_android_push_secondary(const void *rgba, int w, int h)
+{
+	if (!rgba || w <= 0 || h <= 0)
+		return;
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+	jmethodID m = env->GetStaticMethodID(activity, "updateSecondaryFrame", "(Ljava/nio/ByteBuffer;II)V");
+	if (m)
+	{
+		jobject buf = env->NewDirectByteBuffer((void*) rgba, (jlong) w * (jlong) h * 4);
+		env->CallStaticVoidMethod(activity, m, buf, w, h);
+		env->DeleteLocalRef(buf);
+	}
+	else
+		env->ExceptionClear();
+	env->DeleteLocalRef(activity);
+}
+
+extern "C" __attribute__((visibility("default")))
+void love_android_secondary_enable(int on)
+{
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+	jmethodID m = env->GetStaticMethodID(activity, "setSecondaryEnabled", "(Z)V");
+	if (m)
+		env->CallStaticVoidMethod(activity, m, on ? JNI_TRUE : JNI_FALSE);
+	else
+		env->ExceptionClear();
+	env->DeleteLocalRef(activity);
+}
+
 #endif // LOVE_ANDROID

mobile/android/love/src/jni/love/src/common/android.h

@@ -74,6 +74,30 @@ bool showFilePicker(const char *destFilename = nullptr);
  **/
 bool showCreateDocument(const char *suggestedName = nullptr);
 
+/**
+ * Pokéwalker step bridge: asks GameActivity to read the hardware step
+ * counter and stage steps_pending.json in the save identity dir (see
+ * GameActivity.syncHealthSteps). Returns whether a sync could start.
+ */
+bool syncHealthSteps();
+
+/**
+ * Full process relaunch (GameActivity.restartApp): schedules the app's
+ * launch intent and kills the process, because the in-process
+ * quit("restart") loop double-inits physfs and crashes (#575). On success
+ * the process dies inside the Java call and this never returns; false
+ * means the relaunch could not be scheduled.
+ **/
+bool restartApp();
+
+/**
+ * Blocking HTTPS GET into destPath (GameActivity.httpDownload). Android has
+ * no curl binary, so this is the transport src/core/HostShell.lua uses there
+ * for the mod index and mod updates (#597). userAgent / accept may be null.
+ * Returns whether a complete file was written.
+ **/
+bool httpDownload(const char *url, const char *destPath, const char *userAgent, const char *accept);
+
 /*
  * Helper functions for the filesystem module
  */

mobile/android/love/src/jni/love/src/modules/system/System.cpp

@@ -212,6 +212,38 @@ bool System::createFile(const char *suggestedName) const
 #endif
 }
 
+bool System::syncHealthSteps() const
+{
+#ifdef LOVE_ANDROID
+	return love::android::syncHealthSteps();
+#else
+	return false;
+#endif
+}
+
+bool System::restartApp() const
+{
+#ifdef LOVE_ANDROID
+	return love::android::restartApp();
+#else
+	return false;
+#endif
+}
+
+bool System::httpDownload(const char *url, const char *destPath,
+	const char *userAgent, const char *accept) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::httpDownload(url, destPath, userAgent, accept);
+#else
+	LOVE_UNUSED(url);
+	LOVE_UNUSED(destPath);
+	LOVE_UNUSED(userAgent);
+	LOVE_UNUSED(accept);
+	return false;
+#endif
+}
+
 bool System::hasBackgroundMusic() const
 {
 #if defined(LOVE_ANDROID)

mobile/android/love/src/jni/love/src/modules/system/System.h

@@ -127,6 +127,28 @@ public:
 	 **/
 	virtual bool createFile(const char *suggestedName = nullptr) const;
 
+	/**
+	 * Pokéwalker: stage pending real-world steps (steps_pending.json in the
+	 * save dir) from the platform step source. Android-only; false elsewhere.
+	 */
+	virtual bool syncHealthSteps() const;
+
+	/**
+	 * Relaunches the whole app with a fresh process (Android only; false
+	 * elsewhere). The in-process love.event.quit("restart") double-inits
+	 * physfs on Android and crashes, so src/core/HostShell.lua calls this
+	 * instead (#575). Does not return on success -- the process exits.
+	 **/
+	virtual bool restartApp() const;
+
+	/**
+	 * Blocking HTTPS GET into an absolute host path (Android only; false
+	 * elsewhere). Android has no curl, which is what every other platform
+	 * fetches the mod index with (#597).
+	 **/
+	virtual bool httpDownload(const char *url, const char *destPath,
+		const char *userAgent = nullptr, const char *accept = nullptr) const;
+
 	/**
 	 * Gets if the user is playing music on background.
 	 * Throws an exception on unsupported platforms.

mobile/android/love/src/jni/love/src/modules/system/wrap_System.cpp

@@ -109,6 +109,30 @@ int w_createFile(lua_State *L)
 	return 1;
 }
 
+int w_syncHealthSteps(lua_State *L)
+{
+	luax_pushboolean(L, instance()->syncHealthSteps());
+	return 1;
+}
+
+int w_restartApp(lua_State *L)
+{
+	// Does not return on success: GameActivity.restartApp exits the process
+	// after scheduling the relaunch (#575).
+	luax_pushboolean(L, instance()->restartApp());
+	return 1;
+}
+
+int w_httpDownload(lua_State *L)
+{
+	const char *url = luaL_checkstring(L, 1);
+	const char *dest = luaL_checkstring(L, 2);
+	const char *ua = luaL_optstring(L, 3, nullptr);
+	const char *accept = luaL_optstring(L, 4, nullptr);
+	luax_pushboolean(L, instance()->httpDownload(url, dest, ua, accept));
+	return 1;
+}
+
 int w_hasBackgroundMusic(lua_State *L)
 {
 	lua_pushboolean(L, instance()->hasBackgroundMusic());
@@ -126,6 +150,9 @@ static const luaL_Reg functions[] =
 	{ "vibrate", w_vibrate },
 	{ "pickFile", w_pickFile },
 	{ "createFile", w_createFile },
+	{ "syncHealthSteps", w_syncHealthSteps },
+	{ "restartApp", w_restartApp },
+	{ "httpDownload", w_httpDownload },
 	{ "hasBackgroundMusic", w_hasBackgroundMusic },
 	{ 0, 0 }
 };

mobile/android/love/src/main/java/org/love2d/android/GameActivity.java

@@ -31,22 +31,34 @@ import java.io.FileOutputStream;
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.net.HttpURLConnection;
+import java.net.URL;
 import java.util.ArrayList;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
 import android.Manifest;
+import android.app.AlarmManager;
 import android.app.AlertDialog;
+import android.app.PendingIntent;
 import android.content.Context;
 import android.content.DialogInterface;
 import android.content.Intent;
+import android.content.SharedPreferences;
+import android.content.pm.ActivityInfo;
 import android.content.pm.ApplicationInfo;
 import android.content.res.AssetManager;
+import android.hardware.Sensor;
+import android.hardware.SensorEvent;
+import android.hardware.SensorEventListener;
+import android.hardware.SensorManager;
 import android.media.AudioManager;
 import android.net.Uri;
 import android.os.Bundle;
 import android.os.Environment;
+import android.os.Handler;
+import android.os.Looper;
 import android.os.Vibrator;
 import android.util.Log;
 import android.util.DisplayMetrics;
@@ -66,6 +78,8 @@ public class GameActivity extends SDLActivity {
     public static final int RECORD_AUDIO_REQUEST_CODE = 3;
     public static final int FILE_PICKER_REQUEST_CODE = 4;
     public static final int FILE_CREATE_REQUEST_CODE = 5;
+    public static final int STEP_PERMISSION_REQUEST_CODE = 6;
+    public static final int RESTART_REQUEST_CODE = 7;
     /** @deprecated Prefer FILE_PICKER_REQUEST_CODE; kept for older call sites. */
     public static final int ROM_PICKER_REQUEST_CODE = FILE_PICKER_REQUEST_CODE;
     // Mirrors conf.lua's t.identity ("pokemon-love2d"): where the picked file
@@ -82,8 +96,27 @@ public class GameActivity extends SDLActivity {
     // basename as its body, so RomImporter:focus can say so in the launcher
     // instead of leaving the player on "No ROM imported" (issue #442).
     private static final String PICK_ERROR_FILENAME = "pick_error.flag";
+    // Step bridge (love.system.syncHealthSteps): pending-steps delivery
+    // consumed by the Pokéwalker mod, same contract as the iOS
+    // GRHealthBridge. Steps come from the hardware TYPE_STEP_COUNTER
+    // (cumulative since boot, counted by the OS whether or not any app is
+    // running), anchored in SharedPreferences so a walk is never credited
+    // twice.
+    private static final String PENDING_STEPS_FILENAME = "steps_pending.json";
+    private static final String STEP_PREFS = "pokewalker_steps";
+    private static final String STEP_PREF_ANCHOR = "anchor";
+    private static final String STEP_PREF_ANCHOR_WALLTIME = "anchor_walltime";
+    private static final long STEP_MAX_PER_SYNC = 50000;
     // Destination basename for the in-flight SAF pick (set by showFilePicker).
+    // Saved/restored across instance state: the picker is a separate activity
+    // and Android may destroy this one while it is up (memory pressure, or
+    // "Don't keep activities"). A recreated instance still receives
+    // onActivityResult, so without this a mod or save pick came back with the
+    // field reset and was filed as picked_rom.gb, which Lua then rejected as a
+    // bad ROM instead of installing it (#553).
     private String pendingPickFilename = PICKED_ROM_FILENAME;
+    private static final String STATE_PENDING_PICK = "pendingPickFilename";
+    private static final String STATE_PENDING_CREATE = "pendingCreateSuggestedName";
     // Suggested download name for the in-flight SAF create (set by showCreateDocument).
     private String pendingCreateSuggestedName = "export.sav";
     private static boolean immersiveActive = false;
@@ -148,6 +181,14 @@ public class GameActivity extends SDLActivity {
         }
 
         super.onCreate(savedInstanceState);
+        if (savedInstanceState != null) {
+            // Restore the in-flight SAF destinations, so a pick that returns to
+            // a recreated activity still lands under the basename it asked for.
+            String pick = savedInstanceState.getString(STATE_PENDING_PICK);
+            if (pick != null) pendingPickFilename = pick;
+            String create = savedInstanceState.getString(STATE_PENDING_CREATE);
+            if (create != null) pendingCreateSuggestedName = create;
+        }
         metrics = getResources().getDisplayMetrics();
 
         // Set low-latency audio values
@@ -295,12 +336,62 @@ public class GameActivity extends SDLActivity {
             Log.d("GameActivity", "Cancelling vibration");
             vibrator.cancel();
         }
+        teardownSecondaryDisplay();
         super.onPause();
     }
 
     @Override
     public void onResume() {
         super.onResume();
+        setupSecondaryDisplay();
+    }
+
+    /**
+     * SDL decides the activity's requested orientation at window creation
+     * (SDLActivity.setOrientationBis). With a resizable window and no
+     * SDL_HINT_ORIENTATIONS -- exactly what conf.lua produces on Android --
+     * it asks for SCREEN_ORIENTATION_FULL_SENSOR, and that request overrides
+     * the android:screenOrientation="fullUser" set in the manifest. The
+     * *_SENSOR constants follow the accelerometer even when the player has
+     * turned auto-rotate off, so the game kept rotating on a device whose
+     * rotation was locked.
+     *
+     * Remap SDL's choice onto the matching *_USER constant, which allows the
+     * same orientations but defers to the system rotation setting. Applied
+     * after super so SDL keeps deciding *which* orientations the window may
+     * take; this only changes who breaks the tie, the sensor or the player.
+     */
+    @Override
+    public void setOrientationBis(int w, int h, boolean resizable, String hint) {
+        super.setOrientationBis(w, h, resizable, hint);
+
+        // The *_USER constants only exist from API 18; below that the sensor
+        // ones are all there is, so leave SDL's request alone.
+        if (android.os.Build.VERSION.SDK_INT < 18) {
+            return;
+        }
+
+        int requested = getRequestedOrientation();
+        int userRequested;
+        switch (requested) {
+            case ActivityInfo.SCREEN_ORIENTATION_FULL_SENSOR:
+                userRequested = ActivityInfo.SCREEN_ORIENTATION_FULL_USER;
+                break;
+            case ActivityInfo.SCREEN_ORIENTATION_SENSOR_LANDSCAPE:
+                userRequested = ActivityInfo.SCREEN_ORIENTATION_USER_LANDSCAPE;
+                break;
+            case ActivityInfo.SCREEN_ORIENTATION_SENSOR_PORTRAIT:
+                userRequested = ActivityInfo.SCREEN_ORIENTATION_USER_PORTRAIT;
+                break;
+            default:
+                // SENSOR / plain LANDSCAPE / PORTRAIT etc: either already
+                // explicit or never produced by setOrientationBis.
+                return;
+        }
+
+        Log.d("GameActivity", "requestedOrientation " + requested + " -> " + userRequested
+            + " (honour the device rotation lock)");
+        setRequestedOrientation(userRequested);
     }
 
     @Keep
@@ -361,15 +452,23 @@ public class GameActivity extends SDLActivity {
      * Shows the system document picker (Storage Access Framework) so the
      * player can pick a ROM / mod / save from anywhere (Downloads, Drive,
      * etc.) without needing to know where the app's external files folder
-     * is. Requires API 19+ (ACTION_OPEN_DOCUMENT); the picked file (if any)
-     * arrives later in onActivityResult, not synchronously here.
+     * is. The picked file (if any) arrives later in onActivityResult, not
+     * synchronously here.
+     *
+     * API 21+ uses ACTION_OPEN_DOCUMENT; API 16-20 uses an ACTION_GET_CONTENT
+     * chooser instead. Below 19 OPEN_DOCUMENT does not exist, and on 19/20
+     * the stock DocumentsUI is unreliable -- it launches and then hands back
+     * RESULT_CANCELED with no data, which onActivityResult cannot tell apart
+     * from the player cancelling (#584). GET_CONTENT lets any installed file
+     * manager serve the pick, and both intents return the same content:// or
+     * file:// URI shapes, so the result path in onActivityResult stays
+     * picker-agnostic and unchanged.
      *
      * @param destFilename basename under the app save identity (e.g.
      *                     picked_rom.gb, picked_mod.zip, picked_save.sav)
      */
     @Keep
     public static boolean showFilePicker(String destFilename) {
-        if (android.os.Build.VERSION.SDK_INT < 19) return false;
         GameActivity self = (GameActivity) mSingleton;
         if (self == null) return false;
         if (destFilename == null || destFilename.length() == 0) {
@@ -383,11 +482,26 @@ public class GameActivity extends SDLActivity {
         }
 
         self.pendingPickFilename = destFilename;
-        Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
+        if (android.os.Build.VERSION.SDK_INT >= 21) {
+            Intent intent = new Intent(Intent.ACTION_OPEN_DOCUMENT);
+            intent.addCategory(Intent.CATEGORY_OPENABLE);
+            intent.setType("*/*");
+            try {
+                self.startActivityForResult(intent, FILE_PICKER_REQUEST_CODE);
+                return true;
+            } catch (Exception e) {
+                // Some OEM / TV builds ship without DocumentsUI; fall through
+                // to the GET_CONTENT chooser below instead of giving up (#584).
+                Log.d("GameActivity", "could not open document picker: " + e.getMessage());
+            }
+        }
+        Intent intent = new Intent(Intent.ACTION_GET_CONTENT);
         intent.addCategory(Intent.CATEGORY_OPENABLE);
         intent.setType("*/*");
         try {
-            self.startActivityForResult(intent, FILE_PICKER_REQUEST_CODE);
+            self.startActivityForResult(
+                Intent.createChooser(intent, "Choose a file"),
+                FILE_PICKER_REQUEST_CODE);
             return true;
         } catch (Exception e) {
             Log.d("GameActivity", "could not open file picker: " + e.getMessage());
@@ -413,14 +527,127 @@ public class GameActivity extends SDLActivity {
         return showFilePicker(PICKED_SAVE_FILENAME);
     }
 
+    /**
+     * Relaunches the whole app for love.system.restartApp, used by
+     * src/core/HostShell.lua when a mod toggle needs a cold boot (#575).
+     * love.event.quit("restart") re-runs LOVE's boot inside the same
+     * process, and the second love.filesystem.init throws once physfs
+     * failed to deinit ("already initialized"), killing the app. Instead
+     * we hand our launch intent to AlarmManager and then exit the process:
+     * the alarm lives in system_server, so it survives our death and
+     * cannot race the exit the way a plain startActivity right before
+     * Runtime.exit can on some OEMs, and the dead process guarantees no
+     * native (physfs / SDL / JNI) state leaks into the fresh run.
+     */
+    @Keep
+    public static boolean restartApp() {
+        GameActivity self = (GameActivity) mSingleton;
+        if (self == null) return false;
+        try {
+            Context context = self.getApplicationContext();
+            Intent intent = context.getPackageManager()
+                .getLaunchIntentForPackage(context.getPackageName());
+            if (intent == null) return false;
+            intent.addFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_NEW_TASK);
+            int pendingFlags = PendingIntent.FLAG_CANCEL_CURRENT;
+            if (android.os.Build.VERSION.SDK_INT >= 23) {
+                // Mandatory mutability flag on API 31+; harmless from 23 up.
+                pendingFlags |= PendingIntent.FLAG_IMMUTABLE;
+            }
+            PendingIntent pending = PendingIntent.getActivity(
+                context, RESTART_REQUEST_CODE, intent, pendingFlags);
+            AlarmManager alarm = (AlarmManager) context.getSystemService(Context.ALARM_SERVICE);
+            if (alarm == null) return false;
+            alarm.set(AlarmManager.RTC, System.currentTimeMillis() + 250, pending);
+        } catch (Exception e) {
+            Log.d("GameActivity", "could not schedule restart: " + e.getMessage());
+            return false;
+        }
+        Runtime.getRuntime().exit(0);
+        return true; // unreachable, but keeps the JNI signature honest
+    }
+
+    /**
+     * Blocking HTTPS GET into destPath, exposed as love.system.httpDownload
+     * and used by src/core/HostShell.lua. Android ships no curl binary, so
+     * every remote fetch the desktop builds do with curl (mod index feeds,
+     * mod release lists, mod zips, thumbnails) comes through here (#597).
+     * Runs on LOVE's Lua thread, never the UI thread, so the platform's
+     * network-on-main-thread rule is not in play and a blocking call matches
+     * the curl semantics the Lua callers already expect.
+     *
+     * Redirects are followed by hand because HttpURLConnection silently drops
+     * a redirect that changes protocol, and only https is accepted: the feeds
+     * live on GitHub Pages / raw and a downgrade to http must fail, not fetch.
+     * The body lands in a .part file and is renamed only once complete, so a
+     * dropped connection can never leave a half file the caller trusts.
+     */
+    @Keep
+    public static boolean httpDownload(String url, String destPath, String userAgent, String accept) {
+        if (url == null || destPath == null) return false;
+        HttpURLConnection conn = null;
+        File tmp = new File(destPath + ".part");
+        try {
+            String current = url;
+            for (int hop = 0; hop < 5; hop++) {
+                URL parsed = new URL(current);
+                if (!"https".equalsIgnoreCase(parsed.getProtocol())) return false;
+                conn = (HttpURLConnection) parsed.openConnection();
+                conn.setInstanceFollowRedirects(false);
+                conn.setConnectTimeout(15000);
+                conn.setReadTimeout(60000);
+                conn.setRequestProperty("User-Agent",
+                    userAgent == null ? "gen1recomp" : userAgent);
+                if (accept != null) conn.setRequestProperty("Accept", accept);
+                int code = conn.getResponseCode();
+                if (code == 301 || code == 302 || code == 303 || code == 307 || code == 308) {
+                    String next = conn.getHeaderField("Location");
+                    conn.disconnect();
+                    conn = null;
+                    if (next == null) return false;
+                    current = new URL(parsed, next).toString();
+                    continue;
+                }
+                if (code < 200 || code > 299) return false;
+                InputStream in = new BufferedInputStream(conn.getInputStream());
+                OutputStream out = new BufferedOutputStream(new FileOutputStream(tmp));
+                try {
+                    byte[] buf = new byte[16384];
+                    int n;
+                    while ((n = in.read(buf)) > 0) out.write(buf, 0, n);
+                } finally {
+                    try { out.close(); } catch (IOException ignored) {}
+                    try { in.close(); } catch (IOException ignored) {}
+                }
+                File dest = new File(destPath);
+                dest.delete();
+                if (!tmp.renameTo(dest)) return false;
+                return dest.length() > 0;
+            }
+            return false;
+        } catch (Exception e) {
+            Log.d("GameActivity", "httpDownload failed: " + e.getMessage());
+            return false;
+        } finally {
+            if (conn != null) conn.disconnect();
+            if (tmp.exists()) tmp.delete();
+        }
+    }
+
     /**
      * Shows ACTION_CREATE_DOCUMENT so the player can save a staged export
      * (pending_export.sav in the app save identity) to Downloads / Drive /
      * etc. Suggested name is the dialog's default filename.
+     *
+     * CREATE_DOCUMENT does not exist below API 19 and has no pre-SAF
+     * equivalent, so unlike showFilePicker this stays 19+ (#584); the false
+     * return degrades on the Lua side (RomImporter export) to "Exported
+     * inside the app folder", which is the correct pre-KitKat behavior.
      */
     @Keep
     public static boolean showCreateDocument(String suggestedName) {
         if (android.os.Build.VERSION.SDK_INT < 19) return false;
+        // (see showFilePicker for why the import side got a pre-19 path)
         GameActivity self = (GameActivity) mSingleton;
         if (self == null) return false;
         if (suggestedName == null || suggestedName.length() == 0) {
@@ -467,6 +694,160 @@ public class GameActivity extends SDLActivity {
         }
     }
 
+    /**
+     * Step sync, called from Lua as love.system.syncHealthSteps()
+     * (see modules/system/wrap_System.cpp). Asynchronous like the picker:
+     * returns whether a sync could be started; the result lands later as
+     * steps_pending.json in the save identity dir, where the Pokéwalker
+     * mod's poll consumes it.
+     *
+     * Android 10+ gates the step counter behind the ACTIVITY_RECOGNITION
+     * runtime permission; the first call shows the system prompt and a later
+     * sync (the mod retries on save load / option change) delivers.
+     */
+    @Keep
+    public static boolean syncHealthSteps() {
+        final GameActivity self = (GameActivity) mSingleton;
+        if (self == null) return false;
+        if (android.os.Build.VERSION.SDK_INT >= 29
+                && ActivityCompat.checkSelfPermission(self,
+                    Manifest.permission.ACTIVITY_RECOGNITION)
+                    != PackageManager.PERMISSION_GRANTED) {
+            self.runOnUiThread(new Runnable() {
+                @Override
+                public void run() {
+                    ActivityCompat.requestPermissions(self,
+                        new String[]{Manifest.permission.ACTIVITY_RECOGNITION},
+                        STEP_PERMISSION_REQUEST_CODE);
+                }
+            });
+            return true;
+        }
+        self.startStepSensorRead();
+        return true;
+    }
+
+    /**
+     * One-shot read of the cumulative hardware step counter. The sensor
+     * usually reports its cached value moments after registration; some
+     * devices hold the event until the next physical step, so the listener
+     * is given 20 seconds before being torn down (the next sync retries).
+     */
+    private void startStepSensorRead() {
+        final SensorManager manager =
+            (SensorManager) getSystemService(Context.SENSOR_SERVICE);
+        if (manager == null) return;
+        Sensor counter = manager.getDefaultSensor(Sensor.TYPE_STEP_COUNTER);
+        if (counter == null) {
+            Log.d("GameActivity", "no step counter sensor on this device");
+            return;
+        }
+        final SensorEventListener listener = new SensorEventListener() {
+            private boolean delivered = false;
+
+            @Override
+            public void onSensorChanged(SensorEvent event) {
+                if (delivered || event.values.length == 0) return;
+                delivered = true;
+                manager.unregisterListener(this);
+                deliverSteps((long) event.values[0]);
+            }
+
+            @Override
+            public void onAccuracyChanged(Sensor sensor, int accuracy) {
+            }
+        };
+        if (!manager.registerListener(listener, counter,
+                SensorManager.SENSOR_DELAY_NORMAL)) {
+            Log.d("GameActivity", "step counter listener registration failed");
+            return;
+        }
+        new Handler(Looper.getMainLooper()).postDelayed(new Runnable() {
+            @Override
+            public void run() {
+                // No-op if the listener already delivered and unregistered.
+                manager.unregisterListener(listener);
+            }
+        }, 20000);
+    }
+
+    /**
+     * Convert a cumulative counter reading into pending steps. The counter
+     * resets to zero on reboot: a reading below the stored anchor re-anchors
+     * without crediting (steps walked between the reboot and this sync are
+     * lost, which errs on the honest side).
+     */
+    private void deliverSteps(long counterNow) {
+        SharedPreferences prefs = getSharedPreferences(STEP_PREFS, MODE_PRIVATE);
+        long anchor = prefs.getLong(STEP_PREF_ANCHOR, -1);
+        long now = System.currentTimeMillis();
+        if (anchor < 0 || counterNow < anchor) {
+            prefs.edit()
+                .putLong(STEP_PREF_ANCHOR, counterNow)
+                .putLong(STEP_PREF_ANCHOR_WALLTIME, now)
+                .apply();
+            Log.d("GameActivity", "step anchor set at " + counterNow);
+            return;
+        }
+        long steps = Math.min(counterNow - anchor, STEP_MAX_PER_SYNC);
+        long fromWalltime = prefs.getLong(STEP_PREF_ANCHOR_WALLTIME, now);
+        if (steps <= 0) return;
+        prefs.edit()
+            .putLong(STEP_PREF_ANCHOR, counterNow)
+            .putLong(STEP_PREF_ANCHOR_WALLTIME, now)
+            .apply();
+
+        File dir = saveIdentityDir();
+        if (!dir.isDirectory() && !dir.mkdirs()) {
+            Log.d("GameActivity", "cannot create save dir for steps: " + dir);
+            return;
+        }
+        File pending = new File(dir, PENDING_STEPS_FILENAME);
+        long total = steps;
+        // Merge with an unconsumed earlier delivery so steps are never lost
+        // (same contract as the iOS bridge).
+        if (pending.isFile()) {
+            try {
+                byte[] raw = new byte[(int) Math.min(pending.length(), 4096)];
+                FileInputStream in = new FileInputStream(pending);
+                int read = in.read(raw);
+                in.close();
+                if (read > 0) {
+                    org.json.JSONObject old =
+                        new org.json.JSONObject(new String(raw, 0, read, "UTF-8"));
+                    total += Math.max(0, old.optLong("steps", 0));
+                }
+            } catch (Exception e) {
+                Log.d("GameActivity", "ignoring unreadable pending steps: " + e);
+            }
+        }
+        try {
+            org.json.JSONObject payload = new org.json.JSONObject();
+            payload.put("steps", total);
+            payload.put("from", isoTime(fromWalltime));
+            payload.put("to", isoTime(now));
+            File tmp = new File(dir, PENDING_STEPS_FILENAME + ".tmp");
+            FileOutputStream out = new FileOutputStream(tmp);
+            out.write(payload.toString().getBytes("UTF-8"));
+            out.close();
+            if (!tmp.renameTo(pending)) {
+                tmp.delete();
+                Log.d("GameActivity", "could not publish pending steps");
+                return;
+            }
+            Log.d("GameActivity", total + " steps pending for the Pokewalker mod");
+        } catch (Exception e) {
+            Log.d("GameActivity", "could not write pending steps: " + e);
+        }
+    }
+
+    private static String isoTime(long millis) {
+        java.text.SimpleDateFormat format =
+            new java.text.SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss'Z'", java.util.Locale.US);
+        format.setTimeZone(java.util.TimeZone.getTimeZone("UTC"));
+        return format.format(new java.util.Date(millis));
+    }
+
     private boolean copyFileToUri(File source, Uri destUri) {
         InputStream in = null;
         OutputStream out = null;
@@ -490,6 +871,13 @@ public class GameActivity extends SDLActivity {
         }
     }
 
+    @Override
+    protected void onSaveInstanceState(Bundle outState) {
+        super.onSaveInstanceState(outState);
+        outState.putString(STATE_PENDING_PICK, pendingPickFilename);
+        outState.putString(STATE_PENDING_CREATE, pendingCreateSuggestedName);
+    }
+
     @Override
     protected void onActivityResult(int requestCode, int resultCode, Intent data) {
         super.onActivityResult(requestCode, resultCode, data);
@@ -690,6 +1078,17 @@ public class GameActivity extends SDLActivity {
                     }
                     break;
                 }
+                case STEP_PERMISSION_REQUEST_CODE: {
+                    if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {
+                        Log.d("GameActivity", "Step permission granted");
+                        // Deliver right away so the sync the player just
+                        // opted into doesn't wait for the next launch.
+                        startStepSensorRead();
+                    } else {
+                        Log.d("GameActivity", "Did not get step permission.");
+                    }
+                    break;
+                }
                 default:
                     super.onRequestPermissionsResult(requestCode, permissions, grantResults);
             }
@@ -872,4 +1271,182 @@ public class GameActivity extends SDLActivity {
             return applicationInfo.sourceDir + "!/lib/" + abi + "/?.so";
         }
     }
+
+    // Dual-screen: mirror the engine's bottom-screen canvas onto a secondary
+    // physical display. Driven from the engine through love_android_secondary_*
+    // in src/jni/love/src/common/android.cpp.
+    private static volatile SecondaryPresentation secondaryPresentation;
+    private static volatile boolean secondaryEnabled = false;
+
+    @Keep
+    public static void setSecondaryEnabled(final boolean on) {
+        secondaryEnabled = on;
+        final GameActivity self = (GameActivity) mSingleton;
+        if (self == null) return;
+        self.runOnUiThread(new Runnable() {
+            @Override public void run() {
+                if (on) setupSecondaryDisplay(); else teardownSecondaryDisplay();
+            }
+        });
+    }
+
+    private static void setupSecondaryDisplay() {
+        GameActivity self = (GameActivity) mSingleton;
+        if (self == null || !secondaryEnabled || secondaryPresentation != null) return;
+        try {
+            android.hardware.display.DisplayManager dm =
+                (android.hardware.display.DisplayManager) self.getSystemService(Context.DISPLAY_SERVICE);
+            if (dm == null) return;
+            Display chosen = null;
+            for (Display d : dm.getDisplays()) {
+                android.graphics.Point size = new android.graphics.Point();
+                d.getRealSize(size);
+                Log.d("GameActivity", "display id=" + d.getDisplayId() + " name=" + d.getName()
+                    + " size=" + size.x + "x" + size.y);
+                if (chosen == null && d.getDisplayId() != Display.DEFAULT_DISPLAY) {
+                    chosen = d;
+                }
+            }
+            if (chosen == null) {
+                Display[] pres =
+                    dm.getDisplays(android.hardware.display.DisplayManager.DISPLAY_CATEGORY_PRESENTATION);
+                if (pres != null && pres.length > 0) chosen = pres[0];
+            }
+            if (chosen == null) {
+                Log.d("GameActivity", "no secondary display found");
+                return;
+            }
+            SecondaryPresentation p = new SecondaryPresentation(self, chosen);
+            p.show();
+            secondaryPresentation = p;
+            Log.d("GameActivity", "secondary display presentation started on id=" + chosen.getDisplayId());
+        } catch (Throwable t) {
+            Log.d("GameActivity", "secondary display setup failed: " + t);
+            secondaryPresentation = null;
+        }
+    }
+
+    private static void teardownSecondaryDisplay() {
+        SecondaryPresentation p = secondaryPresentation;
+        secondaryPresentation = null;
+        if (p != null) {
+            try { p.dismiss(); } catch (Throwable t) {}
+        }
+    }
+
+    @Keep
+    public static boolean hasSecondaryDisplay() {
+        return secondaryPresentation != null;
+    }
+
+    @Keep
+    public static void updateSecondaryFrame(java.nio.ByteBuffer buf, int w, int h) {
+        SecondaryPresentation p = secondaryPresentation;
+        if (p != null && buf != null && w > 0 && h > 0) {
+            p.updateFrame(buf, w, h);
+        }
+    }
+
+    private static class SecondaryPresentation extends android.app.Presentation {
+        private final FrameView frameView;
+
+        SecondaryPresentation(Context context, Display display) {
+            super(context, display);
+            frameView = new FrameView(context);
+        }
+
+        @Override
+        protected void onCreate(Bundle savedInstanceState) {
+            super.onCreate(savedInstanceState);
+            android.view.Window w = getWindow();
+            if (w != null) {
+                w.setFlags(WindowManager.LayoutParams.FLAG_FULLSCREEN
+                    | WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS,
+                    WindowManager.LayoutParams.FLAG_FULLSCREEN
+                    | WindowManager.LayoutParams.FLAG_LAYOUT_NO_LIMITS);
+                w.setLayout(WindowManager.LayoutParams.MATCH_PARENT,
+                    WindowManager.LayoutParams.MATCH_PARENT);
+            }
+            setContentView(frameView);
+            applyImmersive();
+            frameView.post(new Runnable() {
+                @Override public void run() { applyImmersive(); }
+            });
+        }
+
+        @Override
+        public void onWindowFocusChanged(boolean hasFocus) {
+            super.onWindowFocusChanged(hasFocus);
+            if (hasFocus) applyImmersive();
+        }
+
+        private void applyImmersive() {
+            android.view.Window w = getWindow();
+            if (w == null) return;
+            if (android.os.Build.VERSION.SDK_INT >= 30) {
+                w.setDecorFitsSystemWindows(false);
+                android.view.WindowInsetsController c = w.getInsetsController();
+                if (c != null) {
+                    c.hide(android.view.WindowInsets.Type.systemBars());
+                    c.setSystemBarsBehavior(
+                        android.view.WindowInsetsController.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE);
+                }
+            } else {
+                w.getDecorView().setSystemUiVisibility(
+                    android.view.View.SYSTEM_UI_FLAG_LAYOUT_STABLE
+                    | android.view.View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
+                    | android.view.View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
+                    | android.view.View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
+                    | android.view.View.SYSTEM_UI_FLAG_FULLSCREEN
+                    | android.view.View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY);
+            }
+        }
+
+        void updateFrame(java.nio.ByteBuffer buf, int w, int h) {
+            frameView.updateFrame(buf, w, h);
+        }
+    }
+
+    private static class FrameView extends View {
+        private android.graphics.Bitmap bitmap;
+        private final android.graphics.Rect dst = new android.graphics.Rect();
+        private final android.graphics.Paint paint = new android.graphics.Paint();
+        private final Object lock = new Object();
+        private int fw, fh;
+
+        FrameView(Context context) {
+            super(context);
+            paint.setFilterBitmap(false);
+            paint.setAntiAlias(false);
+            setBackgroundColor(0xFF000000);
+        }
+
+        void updateFrame(java.nio.ByteBuffer buf, int w, int h) {
+            synchronized (lock) {
+                if (bitmap == null || fw != w || fh != h) {
+                    if (bitmap != null) bitmap.recycle();
+                    bitmap = android.graphics.Bitmap.createBitmap(w, h, android.graphics.Bitmap.Config.ARGB_8888);
+                    fw = w; fh = h;
+                }
+                buf.rewind();
+                bitmap.copyPixelsFromBuffer(buf);
+            }
+            postInvalidate();
+        }
+
+        @Override
+        protected void onDraw(android.graphics.Canvas canvas) {
+            synchronized (lock) {
+                if (bitmap == null || fw == 0 || fh == 0) return;
+                int vw = getWidth(), vh = getHeight();
+                int s = Math.min(vw / fw, vh / fh);
+                if (s < 1) s = 1;
+                int dw = fw * s, dh = fh * s;
+                int dx = (vw - dw) / 2, dy = (vh - dh) / 2;
+                dst.set(dx, dy, dx + dw, dy + dh);
+                canvas.drawColor(0xFF000000);
+                canvas.drawBitmap(bitmap, null, dst, paint);
+            }
+        }
+    }
 }

mobile/ios/LOVE_VERSION

@@ -1 +1 @@
-11.5
+12.0

mobile/ios/README.md

@@ -1,4 +1,4 @@
-# iOS build (LÖVE 11.5)
+# iOS build (LÖVE 12.0)
 
 > **Native ROM/mod/save import.** The iOS build ships a Swift
 > document-picker bridge (`native/GRPickerBridge.swift` + `GRBootstrap.m`)
@@ -20,20 +20,17 @@
 > The note below about a missing "UIDocumentPicker handoff" is
 > resolved by this bridge.
 
-macOS + Xcode only. Pins the official **LÖVE 11.5** iOS Xcode tree
-(`love-11.5-ios-source.zip` from [love2d/love releases](https://github.com/love2d/love/releases/tag/11.5)),
-matching `conf.lua`'s `t.version = "11.5"`.
+macOS + Xcode only. Fetches the **LÖVE 12.0** source tree and matching Apple
+dependencies from the official [LÖVE source](https://github.com/love2d/love)
+and [Apple dependencies](https://github.com/love2d/love-apple-dependencies)
+repositories. `conf.lua` declares LÖVE 12.0 on iOS and 11.5 elsewhere.
 
-There is no separate `love2d/love-ios` GitHub repo for 11.5; the release zip
-**is** the vendored iOS project (Xcode project under
-`love-src/platform/xcode/love.xcodeproj`, target `love-ios`).
-
-Pin file: [`LOVE_VERSION`](./LOVE_VERSION) → `11.5`.
+Pin file: [`LOVE_VERSION`](./LOVE_VERSION) → `12.0`.
 
 ## Quick start (simulator)
 
 ```bash
-# Fetch LÖVE 11.5 iOS sources (once) + build for Simulator
+# Fetch LÖVE 12.0 iOS sources and dependencies (once) + build for Simulator
 scripts/build_ios.sh --fetch
 ```
 
@@ -80,10 +77,10 @@ Manual out-of-band steps:
 
 | Path | Role |
 |------|------|
-| `LOVE_VERSION` | Engine pin (`11.5`) |
+| `LOVE_VERSION` | Engine pin (`12.0`) |
 | `overlays/love-ios.plist` | Portrait-only Info.plist + display name **Pokemon Red** (copied over the upstream plist every build) |
-| `love-src/` | Downloaded `love-11.5-ios-source` tree (**gitignored**,  do not commit) |
-| `cache/` | Downloaded zips (**gitignored**) |
+| `love-src/` | Downloaded LÖVE 12.0 source tree (**gitignored**, do not commit) |
+| `cache/` | Temporary source and dependency checkout data (**gitignored**) |
 | `build/` | `xcodebuild` derived data (**gitignored**) |
 
 Game payload lands at:
@@ -94,28 +91,10 @@ and is fused into the built `.app` (LÖVE auto-runs any bundled `*.love`).
 
 ## Apple libraries dependency
 
-The official `love-11.5-ios-source.zip` already ships prebuilt iOS
-xcframeworks under `platform/xcode/ios/libraries/` (SDL2, LuaJIT, freetype,
-ogg, vorbis, theora, modplug).
-
-If that folder is missing or incomplete (e.g. you cloned sources without
-libs), download the matching prebuilts and install them:
-
-```bash
-curl -fL -o mobile/ios/cache/love-11.5-apple-libraries.zip \
-  https://github.com/love2d/love/releases/download/11.5/love-11.5-apple-libraries.zip
-unzip -q mobile/ios/cache/love-11.5-apple-libraries.zip -d mobile/ios/cache
-rm -rf mobile/ios/love-src/platform/xcode/ios/libraries
-cp -R mobile/ios/cache/love-apple-dependencies/iOS/libraries \
-  mobile/ios/love-src/platform/xcode/ios/libraries
-```
-
-`scripts/build_ios.sh` checks for `libraries/SDL2.xcframework` and fails with
-these instructions if it is absent.
-
-Upstream also documents
-[love-apple-dependencies](https://github.com/love2d/love-apple-dependencies)
-as an alternate source of the same libraries.
+`scripts/build_ios.sh --fetch` retrieves the matching iOS libraries and the
+SDL3 framework from
+[love-apple-dependencies](https://github.com/love2d/love-apple-dependencies).
+Re-run it if either dependency directory is absent.
 
 ## App identity
 
@@ -134,7 +113,7 @@ so refreshing `love-src/` does not lose branding.
 | Flag | Meaning |
 |------|---------|
 | *(default)* | Simulator, Debug, no signing |
-| `--fetch` | Download/extract `love-11.5-ios-source.zip` if `love-src/` is missing |
+| `--fetch` | Fetch the LÖVE 12.0 source tree and Apple dependencies if `love-src/` is missing |
 | `--device` | Build against `iphoneos` instead of `iphonesimulator` |
 | `--release` | `Release` configuration instead of `Debug` |
 | `--package-only` | Zip `game.love` + apply plist overlay; skip `xcodebuild` |
@@ -147,5 +126,5 @@ Also: `scripts/build.sh ios` delegates here (`--release` is forwarded).
 - iOS platform installed in Xcode (Settings → Platforms). `xcodebuild -showsdks`
   should list `iphonesimulator` / `iphoneos`. A partial install can fail IB/xib
   compiles with `iOS … Platform Not Installed` even when the SDK name appears.
-- `love-src/` present (`--fetch` or manual unzip of `love-11.5-ios-source.zip`)
-- iOS libraries under `love-src/platform/xcode/ios/libraries/` (see above)
+- `love-src/` present (`--fetch`)
+- iOS libraries under `love-src/platform/xcode/ios/libraries/` and SDL3 under `love-src/platform/xcode/shared/Frameworks/`

mobile/ios/app-repo.json

@@ -0,0 +1,32 @@
+{
+  "name": "gen1recomp App Repo",
+  "identifier": "com.theboisclub.gen1recomp.repo",
+  "iconURL": "https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/assets/logo/gen1recomp_cover.png",
+  "apps": [
+    {
+      "name": "gen1recomp",
+      "bundleIdentifier": "com.theboisclub.gen1recomp",
+      "developerName": "bryanthaboi",
+      "iconURL": "https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main/assets/logo/gen1recomp_cover.png",
+      "localizedDescription": "Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke",
+      "tintColor": "3b5ca8",
+      "category": "games",
+      "versions": [
+        {
+          "version": "0.1.59",
+          "date": "2026-08-02",
+          "size": 8334731,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.59/gen1recomp-0.1.59-ios.ipa",
+          "localizedDescription": "Download the correct version for your computer below.\n\n## Issues closed\n\n- #668 No Jingle playing when receiving first Pokemon from Oak\n- #671 faint animation error\n\n## Contributors\n\n- @bryanthaboi\n- @castdrian\n- @jherediagu\n- @spiritsnails\n- Shane McGovern"
+        },
+        {
+          "version": "0.1.58",
+          "date": "2026-08-02",
+          "size": 8331163,
+          "downloadURL": "https://github.com/bryanthaboi/gen1recomp/releases/download/v0.1.58/gen1recomp-0.1.58-ios.ipa",
+          "localizedDescription": "Gen1Recomp - A native Lua / LÖVE2D recreation of Gen 1 Poke"
+        }
+      ]
+    }
+  ]
+}

mobile/ios/overlays/love-ios.plist

@@ -5,7 +5,7 @@
 	<key>CFBundleDevelopmentRegion</key>
 	<string>en</string>
 	<key>CFBundleDisplayName</key>
-	<string>Pokemon Red</string>
+	<string>gen1recomp</string>
 	<key>CFBundleDocumentTypes</key>
 	<array>
 		<dict>
@@ -49,10 +49,6 @@
 	<false/>
 	<key>UILaunchStoryboardName</key>
 	<string>Launch Screen</string>
-	<key>UIRequiredDeviceCapabilities</key>
-	<array>
-		<string>opengles-2</string>
-	</array>
 	<key>UIStatusBarHidden</key>
 	<true/>
 	<key>UIViewControllerBasedStatusBarAppearance</key>

mobile/ios/patch_love_src.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Applies gen1recomp's iOS native-bridge patches to the fetched LÖVE 11.5
+"""Applies gen1recomp's iOS native-bridge patches to the fetched LÖVE 12.0
 source tree (mobile/ios/love-src/). Idempotent AND re-appliable: the first
 run stashes a pristine `.orig` copy of every file it rewrites, and later
 runs always start over from that copy — so editing the patch content here
@@ -39,6 +39,7 @@ WRAP_INCLUDES = """
 #ifdef LOVE_IOS
 #include <objc/runtime.h>
 #include <objc/message.h>
+#include <string>
 #include "filesystem/Filesystem.h"
 #endif
 """ % MARKER
@@ -53,8 +54,12 @@ WRAP_FUNCS = """
 #ifdef LOVE_IOS
 static const char *gr_saveDirectory()
 {
+	static std::string saveDirectory;
 	auto fs = Module::getInstance<love::filesystem::Filesystem>(Module::M_FILESYSTEM);
-	return fs != nullptr ? fs->getSaveDirectory() : "";
+	if (fs == nullptr)
+		return "";
+	saveDirectory = fs->getSaveDirectory();
+	return saveDirectory.c_str();
 }
 
 static int gr_callBridge(lua_State *L, const char *className,

mods/nuzlocke/README.md

@@ -0,0 +1,13 @@
+# Nuzlocke
+
+An enforced Gen 1 Nuzlocke.
+
+Oak configures Slow Start, whether duplicate evolutionary families are skipped
+or consume an area's encounter, and whether Safari maps are separate areas.
+
+After Slow Start, the mod enforces mandatory nicknames for starters, gifts,
+and catches; one capture per area; no duplicate evolutionary families; and
+permanent death. A party Pokémon says that it died and is removed immediately.
+If the final party member dies, the game runs the credits to THE END and then
+deletes the active save.
+

mods/nuzlocke/main.lua

@@ -0,0 +1,224 @@
+-- Nuzlocke rules. Uses the current engine's internal seams while the
+-- equivalent public API hooks are being added.
+return function(mod)
+  mod.hooks:wrap("intro.oak_speech.build", function(next, steps, speech)
+    steps = next(steps, speech)
+    mod.ui.insertStepAfter(steps, "oak_welcome", {
+      id = "nuzlocke_intro", kind = "say", pic = "oak",
+      text = "A Nuzlocke is a\npromise.\fEvery loss is\npermanent.",
+    })
+    mod.ui.insertStepAfter(steps, "nuzlocke_intro", {
+      id = "nuzlocke_slow_start", kind = "yesno", pic = "oak",
+      saveKey = "slow_start", defaultNo = true,
+      text = "Use SLOW START?\nRules start with\nPOKé BALLS.",
+    })
+    mod.ui.insertStepAfter(steps, "nuzlocke_slow_start", {
+      id = "nuzlocke_dupes", kind = "choice", pic = "oak",
+      saveKey = "dupes_mode", text = "When you meet a\nknown family?",
+      choices = { "SKIP", "LOSE" }, values = { "skip", "strict" },
+    })
+    mod.ui.insertStepAfter(steps, "nuzlocke_dupes", {
+      id = "nuzlocke_safari", kind = "yesno", pic = "oak",
+      saveKey = "safari_sectors", text = "Separate SAFARI\nsectors?",
+    })
+    mod.ui.insertStepAfter(steps, "nuzlocke_safari", {
+      id = "nuzlocke_close", kind = "say", pic = "oak",
+      text = "Give every friend\na name. Keep them\nsafe. Good luck!",
+    })
+    return steps
+  end)
+
+  mod.events:on("intro.oak_speech.answered", function(ev)
+    if ev.saveKey then mod.save:set(ev.saveKey, ev.value) end
+  end)
+
+  local function active(game, battle)
+    if not (game and game.save) or (battle and (battle.demo or battle.ghost)) then return false end
+    if not mod.save:get("slow_start", false) then return true end
+    if mod.save:get("balls_unlocked", false) then return true end
+    for id, count in pairs(game.save.inventory or {}) do
+      if count > 0 and game.data.items[id] and game.data.items[id].ball then
+        mod.save:set("balls_unlocked", true)
+        return true
+      end
+    end
+    return false
+  end
+
+  local function areaKey(game, battle)
+    if battle and battle.safari and not mod.save:get("safari_sectors", false) then
+      return "SAFARI_ZONE"
+    end
+    return (game.overworld and game.overworld.map and game.overworld.map.id)
+      or (game.save.player and game.save.player.map) or "UNKNOWN"
+  end
+
+  local function family(data, species)
+    local found, pending = {}, { species }
+    while #pending > 0 do
+      local id = table.remove(pending)
+      if not found[id] then
+        found[id] = true
+        for _, evo in ipairs((data.pokemon[id] or {}).evolutions or {}) do pending[#pending + 1] = evo.species end
+        for parent, def in pairs(data.pokemon or {}) do
+          for _, evo in ipairs(def.evolutions or {}) do
+            if evo.species == id then pending[#pending + 1] = parent end
+          end
+        end
+      end
+    end
+    return found
+  end
+
+  local function ownsFamily(game, species)
+    local members = family(game.data, species)
+    local function owns(mon) return mon and members[mon.species] end
+    for _, mon in ipairs(game.save.party or {}) do if owns(mon) then return true end end
+    for _, box in ipairs(game.save.boxes or {}) do
+      for _, mon in ipairs(box) do if owns(mon) then return true end end
+    end
+    return false
+  end
+
+  local function caughtAreas()
+    local areas = mod.save:get("caught_areas")
+    if type(areas) ~= "table" then areas = {}; mod.save:set("caught_areas", areas) end
+    return areas
+  end
+
+  local function denied(game, battle, species)
+    if not active(game, battle) then return nil end
+    if caughtAreas()[areaKey(game, battle)] then return "area" end
+    if ownsFamily(game, species) then return "dupes" end
+  end
+
+  mod.events:on("pokemon.caught", function(ev)
+    -- A successful capture proves that Slow Start has ended even when it was
+    -- the last ball in the bag.
+    if mod.save:get("slow_start", false) then mod.save:set("balls_unlocked", true) end
+    if active(ev.game, ev.battle) then
+      caughtAreas()[areaKey(ev.game, ev.battle)] = ev.species
+      mod.save:set("caught_areas", caughtAreas())
+    end
+  end)
+
+  mod.events:on("game.ready", function()
+    local BattleState = require("src.battle.BattleState")
+    local Commands = require("src.script.Commands")
+    local Party = require("src.pokemon.Party")
+    local Boxes = require("src.pokemon.Boxes")
+    local Pokemon = require("src.pokemon.Pokemon")
+    local Runtime = require("src.mods.Runtime")
+    local Screens = require("src.ui.Screens")
+    local Strings = require("src.core.Strings")
+    local SaveData = require("src.core.SaveData")
+    local GameVersion = require("src.core.GameVersion")
+    local Bag = require("src.inventory.Bag")
+
+    BattleState.askNicknameUI = function(self, mon)
+      self.lockedBall, self.blankForAskName = nil, false
+      return self:buildScreen("NamingScreen", {
+        title = Strings("NICKNAME?"), maxLen = 10,
+        onDone = function(name) mon.nickname = name or "A" end,
+      })
+    end
+
+    -- Gifts and starters use the same mandatory naming screen.
+    Commands.give_pokemon = function(ctx, species, level)
+      local gift = { ctx = ctx, species = species, level = level }
+      if ctx.game.mods then ctx.game.mods.events:emit("pokemon.before_give", gift) end
+      local mon = Pokemon.new(ctx.game.data, gift.species, gift.level)
+      ctx.game.stringBuffer, ctx.pendingPokemonName = ctx.game.data.pokemon[gift.species].name or gift.species, gift.species
+      BattleState.stampOT(ctx.save, mon)
+      local inParty = Party.add(ctx.save.party, mon)
+      local boxNum = inParty and nil or Boxes.deposit(ctx.save, mon)
+      if not inParty and not boxNum then ctx.lastCheck = false; return end
+      if ctx.save.pokedex then ctx.save.pokedex.seen[gift.species], ctx.save.pokedex.owned[gift.species] = true, true end
+      ctx.lastCheck, ctx.addedToParty, ctx.boxNum = true, inParty, boxNum
+      if ctx.runner then
+        Screens.push(ctx.game, "NamingScreen", {
+          title = Strings("NICKNAME?"), maxLen = 10,
+          onDone = function(name) mon.nickname = name or "A"; ctx.runner:resume() end,
+        })
+        ctx.runner:yield()
+      else mon.nickname = "A" end
+      if boxNum then
+        ctx.game.boxMonNicks, ctx.game.stringBuffer = mon.nickname, tostring(boxNum)
+        if ctx.runner then Commands.show_text(ctx, "_SentToBoxText") end
+      end
+    end
+
+    local vanillaThrowBall = BattleState.throwBall
+    BattleState.throwBall = function(self, ball)
+      local reason = denied(self.game, self, self.enemy and self.enemy.mon.species)
+      if reason then
+        if reason == "dupes" and mod.save:get("dupes_mode", "skip") == "strict" then
+          caughtAreas()[areaKey(self.game, self)] = "DUPES_LOST"
+          mod.save:set("caught_areas", caughtAreas())
+        end
+        Bag.add(self.game.save, ball, 1, self.game.data)
+        self:say(reason == "area" and "This area already\nhas a captured POKéMON!"
+          or "You already have\nthis POKéMON family!")
+        return
+      end
+      return vanillaThrowBall(self, ball)
+    end
+
+    local vanillaOnFaint = BattleState.onFaint
+    BattleState.onFaint = function(self, battler)
+      if not (battler.isPlayer and active(self.game, self)) then return vanillaOnFaint(self, battler) end
+      if battler.faintQueued then return end
+      battler.faintQueued = true
+      if self.participants then self.participants[battler.mon] = nil end
+      Runtime.emit("battle.fainted", { battle = self, battler = battler })
+      for i, mon in ipairs(self.game.save.party) do
+        if mon == battler.mon then table.remove(self.game.save.party, i); break end
+      end
+      self:actNext(function()
+        battler.fainted = true
+        require("src.core.Sound").playCry(self.data, battler.mon.species)
+        require("src.core.Sound").play(self.data, "Faint_Fall")
+        self.fx = self.fx or {}; self.fx.faint = { battler = battler, frames = 30 }
+      end)
+      self.nextInsert = (self.nextInsert or 0) + 1
+      table.insert(self.queue, self.nextInsert, { wait = 30 })
+      self:sayNext(Strings("%s\ndied!", battler.name))
+      self:act(function() self:playerMonFainted() end)
+    end
+
+    local vanillaPlayerFainted = BattleState.playerMonFainted
+    BattleState.playerMonFainted = function(self)
+      if active(self.game, self) and not Party.firstHealthy(self.game.save.party) then
+        self.nuzlockeGameOver, self.result, self.afterQueue = true, "nuzlocke_game_over", "finish"
+        self:sayNext(Strings("All of your\nPOKéMON are dead..."))
+        return
+      end
+      return vanillaPlayerFainted(self)
+    end
+
+    local vanillaFinish = BattleState.finish
+    BattleState.finish = function(self)
+      if not self.nuzlockeGameOver then return vanillaFinish(self) end
+      self.nuzlockeGameOver = nil
+      self.game.stack:pop()
+      Runtime.emit("battle.ended", { battle = self, result = "nuzlocke_game_over" })
+      -- Game over has no victory lap: delete the slot, then use Credits only
+      -- as its existing THE END renderer / A-or-B wait screen.
+      local version = GameVersion.get()
+      local slot = SaveData.activeSlot(version)
+      if slot then SaveData.deleteSlot(version, slot)
+      elseif love and love.filesystem then
+        local main = SaveData.saveFilename(version)
+        love.filesystem.remove(main); love.filesystem.remove(main .. ".bak"); love.filesystem.remove(main .. ".tmp")
+      end
+      local ending = Screens.push(self.game, "Credits", function()
+        require("src.core.Music").stop()
+        while self.game.stack:top() do self.game.stack:pop() end
+        Screens.push(self.game, "IntroMovie", function()
+          if self.game.makeTitleState then self.game.stack:push(self.game:makeTitleState()) end
+        end)
+      end)
+      ending.phase, ending.timer = "end_wait", 0
+    end
+  end)
+end

mods/nuzlocke/manifest.json

@@ -0,0 +1,19 @@
+{
+  "id": "nuzlocke",
+  "name": "Nuzlocke",
+  "version": "1.0.0",
+  "api": 2,
+  "entry": "main.lua",
+  "profile": "content",
+  "category": "GAMEPLAY",
+  "game_version": ">=0.0.0-dev <1.0.0",
+  "priority": 100,
+  "permissions": [
+    "engine_internals"
+  ],
+  "dependencies": [],
+  "optional_dependencies": [],
+  "conflicts": [],
+  "description": "A configurable Gen 1 Nuzlocke with permanent death and area catches.",
+  "github": "bryanthaboi/nuzlocke"
+}

scripts/build.sh

@@ -35,6 +35,7 @@ TARGET="all"
 NOTARY_PROFILE="notary-profile"
 NOTARIZE=true
 IOS_RELEASE=false
+IOS_IPA=false
 
 say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
 warn() { printf '\033[1;33mwarn:\033[0m %s\n' "$*" >&2; }
@@ -48,6 +49,7 @@ while [ $# -gt 0 ]; do
     --notary-profile) NOTARY_PROFILE="$2"; shift ;;
     --no-notarize) NOTARIZE=false ;;
     --release) IOS_RELEASE=true ;;
+    --ipa) IOS_IPA=true ;;
     *) fail "unknown argument: $1" ;;
   esac
   shift
@@ -298,6 +300,9 @@ build_android() {
   if [ "$VERSION_EXPLICIT" = true ]; then
     args+=(--version "$VERSION")
   fi
+  if [ "$IOS_IPA" = true ]; then
+    args+=(--ipa)
+  fi
   "$ROOT/scripts/build_android.sh" ${args[@]+"${args[@]}"}
 }
 

scripts/build_android.sh

@@ -198,6 +198,10 @@ pack_game_love() {
   rm -f "$LOVE_FILE"
   # tools/save-editor ships with the app: the launcher's Edit button on a save
   # row opens it in-process, so it must be inside the archive (see build.sh).
+  # Deliberately NO fused mods: a mod inside game.love sits in the read-only
+  # APK, so the mod manager's Delete can't remove it and it reappears every
+  # launch.  Pokewalker ships as an importable .zip instead, which gives it
+  # a real install/upgrade/delete lifecycle.
   (cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
     main.lua conf.lua src data assets tools/save-editor \
     tools/rom_manifest.json tools/rom_manifest_blue.json \
@@ -290,10 +294,32 @@ require_android_sdk() {
 # --------------------------------------------------------------- gradle
 run_gradle() {
   local task="assembleEmbedNoRecordDebug"
-  say "building APK ($task)"
+  local build_dir="$ANDROID_DIR"
 
+  # ndk-build is GNU make underneath and cannot cope with spaces anywhere in
+  # the project path ("Your APP_BUILD_SCRIPT points to an unknown file").
+  # When this checkout lives at a spaced path (e.g. "~/xCode Projects/..."),
+  # shadow the android tree to a space-free location and build there; the
+  # shadow persists across runs so gradle/ndk builds stay incremental.
+  case "$ANDROID_DIR" in
+    *" "*)
+      build_dir="${TMPDIR:-/tmp}/gen1recomp-android-shadow"
+      say "path contains spaces (ndk-build cannot handle them);"
+      say "shadow-building in: $build_dir"
+      mkdir -p "$build_dir"
+      rsync -a --delete \
+        --exclude=".gradle" --exclude="app/build" --exclude="love/build" \
+        --exclude="local.properties" \
+        "$ANDROID_DIR/" "$build_dir/"
+      if [ -f "$ANDROID_DIR/local.properties" ]; then
+        cp "$ANDROID_DIR/local.properties" "$build_dir/local.properties"
+      fi
+      ;;
+  esac
+
+  say "building APK ($task)"
   if ! (
-    cd "$ANDROID_DIR"
+    cd "$build_dir"
     ./gradlew --no-daemon "$task"
   ); then
     fail "gradle $task failed.
@@ -302,7 +328,7 @@ run_gradle() {
   You can still iterate on the .love payload with: scripts/build_android.sh --package-only"
   fi
 
-  local out_dir="$ANDROID_DIR/app/build/outputs/apk/embedNoRecord/debug"
+  local out_dir="$build_dir/app/build/outputs/apk/embedNoRecord/debug"
   if [ -d "$out_dir" ]; then
     say "APK output:"
     find "$out_dir" -name '*.apk' -exec ls -lh {} \;

scripts/build_ios.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
-# Packages the LÖVE2D Pokémon Red port into an iOS app via LÖVE 11.5's
-# official iOS Xcode project (love-11.5-ios-source.zip).
+# Packages the LÖVE2D Pokémon Red port into an iOS app via LÖVE 12.0's
+# iOS Xcode project.
 #
 # Usage: scripts/build_ios.sh [--fetch] [--device] [--release] [--install]
 #                             [--version X.Y.Z] [--package-only]
@@ -11,14 +11,14 @@
 #   --install         after a --device build, install the app onto the
 #                     first connected iPhone/iPad (unlock it first)
 #   --release         Release configuration
-#   --version X.Y.Z   stamp MARKETING_VERSION / CURRENT_PROJECT_VERSION
-#   --fetch           Download love-11.5-ios-source.zip into mobile/ios/love-src/
+#   --version X.Y.Z   stamp the engine version into game.love plus
+#                     MARKETING_VERSION / CURRENT_PROJECT_VERSION
+#   --fetch           Fetch LÖVE 12.0 sources and Apple dependencies into mobile/ios/love-src/
 #   --package-only    Zip game.love + apply plist overlay; skip xcodebuild
 #
 # Prerequisites:
 #   - macOS + Xcode (xcodebuild)
 #   - mobile/ios/love-src/ (see --fetch / mobile/ios/README.md)
-#   - prebuilt iOS libraries under love-src/platform/xcode/ios/libraries/
 #
 # Output: dist/ios/<Config>-<sdk>/gen1recomp.app (convenience copy)
 #         dist/ios/gen1recomp.ipa                 (device builds only)
@@ -50,21 +50,26 @@ DISPLAY_NAME="gen1recomp"
 #      capabilities like HealthKit are involved), so a per-team default
 #      lets anyone build without colliding with someone else's app
 #   4. simulator: the project default (no App ID registration involved)
-BUNDLE_ID="${GEN1_BUNDLE_ID:-}"
+BUNDLE_ID="${GEN1_BUNDLE_ID:-com.theboisclub.gen1recomp}"
 if [ -z "$BUNDLE_ID" ] && [ -f "$IOS_DIR/bundle_id.local" ]; then
   BUNDLE_ID="$(tr -d '[:space:]' < "$IOS_DIR/bundle_id.local")"
 fi
-LOVE_VERSION="$(tr -d '[:space:]' < "$IOS_DIR/LOVE_VERSION" 2>/dev/null || echo 11.5)"
-IOS_SOURCE_ZIP="love-${LOVE_VERSION}-ios-source.zip"
-APPLE_LIBS_ZIP="love-${LOVE_VERSION}-apple-libraries.zip"
-IOS_SOURCE_URL="https://github.com/love2d/love/releases/download/${LOVE_VERSION}/${IOS_SOURCE_ZIP}"
-APPLE_LIBS_URL="https://github.com/love2d/love/releases/download/${LOVE_VERSION}/${APPLE_LIBS_ZIP}"
+LOVE_VERSION="$(tr -d '[:space:]' < "$IOS_DIR/LOVE_VERSION" 2>/dev/null || echo 12.0)"
+LOVE_SOURCE_REF="${LOVE_SOURCE_REF:-main}"
+APPLE_DEPENDENCIES_REF="${APPLE_DEPENDENCIES_REF:-main}"
+LOVE_SOURCE_REPO="https://github.com/love2d/love.git"
+APPLE_DEPENDENCIES_REPO="https://github.com/love2d/love-apple-dependencies.git"
 
 FETCH=false
 DEVICE=false
 RELEASE=false
 PACKAGE_ONLY=false
 INSTALL=false
+CREATE_IPA=false
+# Last resort for an incomplete source export, mirroring build_android.sh.
+MANIFEST_BASE_URL="${MANIFEST_BASE_URL:-https://raw.githubusercontent.com/bryanthaboi/gen1recomp/main}"
+MANIFESTS=""
+
 VERSION=""
 
 say()  { printf '\033[1;32m==>\033[0m %s\n' "$*"; }
@@ -78,6 +83,7 @@ while [ $# -gt 0 ]; do
     --release) RELEASE=true ;;
     --package-only) PACKAGE_ONLY=true ;;
     --install) INSTALL=true ;;
+    --ipa) CREATE_IPA=true ;;
     --version) VERSION="$2"; shift ;;
     -h|--help)
       sed -n '2,24p' "$0"
@@ -88,6 +94,10 @@ while [ $# -gt 0 ]; do
   shift
 done
 
+if $CREATE_IPA; then
+  DEVICE=true
+fi
+
 VERSION_CODE=""
 if [ -n "$VERSION" ]; then
   if ! printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
@@ -150,25 +160,19 @@ fi
 # --------------------------------------------------------------- fetch love-src
 fetch_love_ios() {
   mkdir -p "$CACHE"
-  local zip_path="$CACHE/$IOS_SOURCE_ZIP"
-  if [ ! -f "$zip_path" ]; then
-    say "downloading $IOS_SOURCE_ZIP (LÖVE $LOVE_VERSION iOS sources)"
-    curl -fL --progress-bar "$IOS_SOURCE_URL" -o "$zip_path" \
-      || fail "download failed: $IOS_SOURCE_URL"
-  else
-    say "using cached $zip_path"
-  fi
-
-  say "extracting into $LOVE_SRC"
-  rm -rf "$LOVE_SRC"
   local tmp
   tmp="$(mktemp -d "$CACHE/extract.XXXXXX")"
-  unzip -q "$zip_path" -d "$tmp"
-  # Zip root is love-<version>-ios-source/
-  local extracted
-  extracted="$(find "$tmp" -maxdepth 1 -mindepth 1 -type d ! -name '__MACOSX' | head -1)"
-  [ -n "$extracted" ] || fail "unexpected layout inside $IOS_SOURCE_ZIP"
-  mv "$extracted" "$LOVE_SRC"
+  say "fetching LÖVE $LOVE_VERSION sources ($LOVE_SOURCE_REF)"
+  git clone --depth 1 --branch "$LOVE_SOURCE_REF" "$LOVE_SOURCE_REPO" "$tmp/love" \
+    || fail "failed to fetch LÖVE sources from $LOVE_SOURCE_REPO"
+  say "fetching Apple dependencies ($APPLE_DEPENDENCIES_REF)"
+  git clone --depth 1 --branch "$APPLE_DEPENDENCIES_REF" "$APPLE_DEPENDENCIES_REPO" "$tmp/dependencies" \
+    || fail "failed to fetch Apple dependencies from $APPLE_DEPENDENCIES_REPO"
+  rm -rf "$LOVE_SRC"
+  mv "$tmp/love" "$LOVE_SRC"
+  mkdir -p "$LIBS_DIR" "$XCODE_DIR/shared"
+  cp -R "$tmp/dependencies/iOS/libraries/." "$LIBS_DIR"
+  cp -R "$tmp/dependencies/shared/." "$XCODE_DIR/shared"
   rm -rf "$tmp"
   say "love-src ready (LÖVE $LOVE_VERSION)"
 }
@@ -178,18 +182,12 @@ if [ ! -d "$XCODE_DIR/love.xcodeproj" ]; then
     fetch_love_ios
   else
     fail "LÖVE $LOVE_VERSION iOS sources not found at mobile/ios/love-src/.
-  Fetch them (documented download of love-${LOVE_VERSION}-ios-source.zip):
+  Fetch them:
     scripts/build_ios.sh --fetch
-  Or manually:
-    mkdir -p mobile/ios/cache
-    curl -fL -o mobile/ios/cache/$IOS_SOURCE_ZIP \\
-      $IOS_SOURCE_URL
-    unzip -q mobile/ios/cache/$IOS_SOURCE_ZIP -d mobile/ios/cache
-    mv mobile/ios/cache/love-${LOVE_VERSION}-ios-source mobile/ios/love-src
   See mobile/ios/README.md."
   fi
 elif $FETCH; then
-  say "love-src already present; skipping download (delete mobile/ios/love-src to refresh)"
+  say "love-src already present; skipping fetch (delete mobile/ios/love-src to refresh)"
 fi
 
 [ -d "$XCODE_DIR/love.xcodeproj" ] \
@@ -197,25 +195,16 @@ fi
 
 # --------------------------------------------------------------- apple libraries
 require_ios_libraries() {
-  if [ -d "$LIBS_DIR/SDL2.xcframework" ]; then
+  if [ -d "$LIBS_DIR/SDL2.xcframework" ] && [ -d "$XCODE_DIR/shared/Frameworks/SDL3.xcframework" ]; then
     return 0
   fi
   fail "prebuilt iOS libraries missing at:
   $LIBS_DIR
-  love-ios expects SDL2.xcframework (and friends) there.
+  and shared/Frameworks.
 
-  The official love-${LOVE_VERSION}-ios-source.zip normally includes them.
-  If they are absent, install love-${LOVE_VERSION}-apple-libraries.zip:
+  Re-fetch the LÖVE $LOVE_VERSION source tree and its Apple dependencies:
 
-    mkdir -p mobile/ios/cache
-    curl -fL -o mobile/ios/cache/$APPLE_LIBS_ZIP \\
-      $APPLE_LIBS_URL
-    unzip -q mobile/ios/cache/$APPLE_LIBS_ZIP -d mobile/ios/cache
-    rm -rf mobile/ios/love-src/platform/xcode/ios/libraries
-    cp -R mobile/ios/cache/love-apple-dependencies/iOS/libraries \\
-      mobile/ios/love-src/platform/xcode/ios/libraries
-
-  See mobile/ios/README.md (Apple libraries dependency)."
+    scripts/build_ios.sh --fetch"
 }
 
 require_ios_libraries
@@ -228,7 +217,93 @@ apply_ios_branding() {
   cp "$OVERLAY_PLIST" "$dest"
 }
 
+apply_ios_icon() {
+  local source="$ROOT/assets/logo/logo.png"
+  local target="$XCODE_DIR/Images.xcassets/iOS AppIcon.appiconset"
+  [ -f "$source" ] || fail "missing iOS icon source: $source"
+  [ -d "$target" ] || fail "missing iOS app icon set: $target"
+  local entry name size
+  while IFS=: read -r name size; do
+    sips -z "$size" "$size" "$source" --out "$target/$name" >/dev/null
+  done <<'EOF'
+icon-1024pt@1x.png:1024
+icon-29pt@1x.png:29
+icon-29pt@2x.png:58
+icon-29pt@3x.png:87
+icon-40pt@1x.png:40
+icon-40pt@2x.png:80
+icon-40pt@3x.png:120
+icon-60pt@2x.png:120
+icon-60pt@3x.png:180
+icon-76pt@1x.png:76
+icon-76pt@2x.png:152
+icon-83.5pt@2x.png:167
+EOF
+}
+
 # --------------------------------------------------------------- game.love
+# Every version's import manifest has to ship or that game's ROM import fails in
+# the built app: decodeManifest (src/import/RomImporter.lua) errors outright when
+# one is absent, and dev reads them off the source tree, so the miss only ever
+# shows up in a build.  iOS shipped without the Yellow one in 0.1.45 to 0.1.47
+# for exactly that reason.
+#
+# The list is READ OUT OF src/core/GameVersion.lua rather than hand-kept here, so
+# a fourth version cannot silently ship without its manifest, and a missing file
+# is recovered from Git or the project repo the same way build_android.sh already
+# recovers Yellow's.  Recovery is a last resort for an incomplete source export:
+# a manifest carries extraction metadata only, never a ROM or game data.
+manifest_paths() {
+  python3 - "$ROOT/src/core/GameVersion.lua" <<'PY'
+import re, sys
+src = open(sys.argv[1]).read()
+print(" ".join(dict.fromkeys(re.findall(r'manifest\s*=\s*"([^"]+)"', src))))
+PY
+}
+
+manifest_is_valid() {
+  python3 - "$1" <<'PY'
+import json, pathlib, sys
+try:
+    m = json.loads(pathlib.Path(sys.argv[1]).read_text())
+except (OSError, ValueError):
+    raise SystemExit(1)
+sha = m.get("romSha1")
+raise SystemExit(0 if isinstance(sha, str) and len(sha) == 40 else 1)
+PY
+}
+
+ensure_manifests() {
+  MANIFESTS="$(manifest_paths)"
+  [ -n "$MANIFESTS" ] \
+    || fail "could not read any manifest path out of src/core/GameVersion.lua"
+  local rel staged
+  for rel in $MANIFESTS; do
+    if manifest_is_valid "$ROOT/$rel"; then continue; fi
+    warn "$rel is missing or invalid; recovering it before packaging"
+    staged="$(mktemp)"
+    if git -C "$ROOT" show "HEAD:$rel" > "$staged" 2>/dev/null \
+        && manifest_is_valid "$staged"; then
+      mkdir -p "$ROOT/$(dirname "$rel")"
+      mv "$staged" "$ROOT/$rel"
+      say "restored $rel from this checkout's Git data"
+      continue
+    fi
+    if command -v curl >/dev/null 2>&1 \
+        && curl --fail --location --retry 2 --connect-timeout 15 \
+            --output "$staged" "$MANIFEST_BASE_URL/$rel" \
+        && manifest_is_valid "$staged"; then
+      mkdir -p "$ROOT/$(dirname "$rel")"
+      mv "$staged" "$ROOT/$rel"
+      say "downloaded $rel from the project repository"
+      continue
+    fi
+    rm -f "$staged"
+    fail "$rel is unavailable: Git recovery failed and $MANIFEST_BASE_URL/$rel could not be downloaded"
+  done
+  say "import manifests: $MANIFESTS"
+}
+
 pack_game_love() {
   say "packing game.love for love-ios resources"
   mkdir -p "$RESOURCES_DIR"
@@ -240,9 +315,10 @@ pack_game_love() {
   # it reappears every launch.  Mods install as .zips at runtime instead
   # (launcher -> MODS -> Import mod .zip), the same lifecycle as every
   # other platform.
+  # shellcheck disable=SC2086  # MANIFESTS is a deliberate word list
   (cd "$ROOT" && zip -q -9 -r "$LOVE_FILE" \
     main.lua conf.lua src data assets tools/save-editor \
-    tools/rom_manifest.json tools/rom_manifest_blue.json \
+    $MANIFESTS \
     -x '*.DS_Store' -x '*/.git/*' -x '*/.DS_Store' \
     -x 'data/generated/*' -x 'assets/generated/*')
   # NOTE: grep -q here would race pipefail — it exits on first match, unzip
@@ -252,9 +328,39 @@ pack_game_love() {
       | grep -E '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/' >/dev/null; then
     fail "game.love unexpectedly contains generated ROM data"
   fi
-  unzip -Z1 "$LOVE_FILE" | grep -x 'tools/save-editor/App.lua' >/dev/null \
-    || fail "game.love is missing the save editor (Edit on a save row would crash)"
+  # Same required-file gate as scripts/build.sh and scripts/build_android.sh.
+  # iOS only checked App.lua, which is why the Yellow manifest shipped missing
+  # in 0.1.45 through 0.1.47: decodeManifest (src/import/RomImporter.lua) errors
+  # outright when a version's manifest is absent, so Import ROM on Yellow died
+  # in the built app while dev, which reads the source tree, stayed green.
+  archive_entries="$(unzip -Z1 "$LOVE_FILE")"
+  # shellcheck disable=SC2086  # MANIFESTS is a deliberate word list
+  for required in src/update/Boot.lua tools/save-editor/App.lua \
+                  tools/save-editor/Kit.lua tools/save-editor/panels/Party.lua \
+                  $MANIFESTS; do
+    printf '%s\n' "$archive_entries" | grep -qx "$required" \
+      || fail "game.love is missing $required"
+  done
   say "game.love: $(du -h "$LOVE_FILE" | cut -f1) -> $LOVE_FILE"
+
+  if printf '%s' "$VERSION" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$'; then
+    say "stamping engine version $VERSION into game.love"
+    local stamp_dir
+    stamp_dir="$(mktemp -d)"
+    mkdir -p "$stamp_dir/src/core"
+    sed -E "s/(engine[[:space:]]*=[[:space:]]*\")([^\"]*)(\")/\1$VERSION\3/" \
+      "$ROOT/src/core/Version.lua" > "$stamp_dir/src/core/Version.lua"
+    (cd "$stamp_dir" && zip -q "$LOVE_FILE" src/core/Version.lua)
+    local version_re
+    version_re="$(printf '%s' "$VERSION" | sed 's/\./\\./g')"
+    unzip -p "$LOVE_FILE" src/core/Version.lua \
+      | grep -Eq "engine[[:space:]]*=[[:space:]]*\"$version_re\"" \
+      || fail "version stamp failed: game.love does not report engine $VERSION"
+    rm -rf "$stamp_dir"
+    say "stamped engine version: $VERSION"
+  else
+    say "no X.Y.Z --version,  shipping default engine (no stamp)"
+  fi
 }
 
 # Ensure game.love is in the love-ios Copy Bundle Resources phase (idempotent).
@@ -347,7 +453,124 @@ print("patched project.pbxproj")
 PY
 }
 
+suppress_love_dependency_warnings() {
+  local liblove_pbx="$XCODE_DIR/liblove.xcodeproj/project.pbxproj"
+  local love_pbx="$XCODE_DIR/love.xcodeproj/project.pbxproj"
+  [ -f "$liblove_pbx" ] || fail "missing $liblove_pbx"
+  [ -f "$love_pbx" ] || fail "missing $love_pbx"
+
+  python3 - "$liblove_pbx" "$love_pbx" <<'PY'
+import pathlib
+import sys
+
+def patch_configs(path, config_ids, settings):
+    text = path.read_text()
+    for config_id in config_ids:
+        marker = f"\t\t{config_id}"
+        start = text.find(marker)
+        if start < 0:
+            raise SystemExit(f"missing configuration {config_id}")
+        settings_start = text.find("\t\t\tbuildSettings = {\n", start)
+        block_end = text.find("\n\t\t};", settings_start)
+        if settings_start < 0 or block_end < 0:
+            raise SystemExit(f"invalid configuration {config_id}")
+        block = text[settings_start:block_end]
+        lines = block.splitlines(keepends=True)
+        for setting in settings:
+            key = setting.split(" = ", 1)[0].strip()
+            prefix = f"{key} ="
+            replaced = False
+            normalized = []
+            for line in lines:
+                if line.startswith(f"\t\t\t\t{prefix}"):
+                    if not replaced:
+                        normalized.append(setting)
+                        replaced = True
+                else:
+                    normalized.append(line)
+            if not replaced:
+                normalized.insert(1, setting)
+            lines = normalized
+        normalized_block = "".join(lines)
+        if normalized_block != block:
+            text = text[:settings_start] + normalized_block + text[block_end:]
+    path.write_text(text)
+
+patch_configs(
+    pathlib.Path(sys.argv[1]),
+    (
+        "FA0B78EF1A958B90000E1D17",
+        "FA0B78F01A958B90000E1D17",
+        "FA0B78F11A958B90000E1D17",
+    ),
+    (
+        "\t\t\t\tCLANG_WARN_UNINITIALIZED_AUTOS = NO;\n",
+        "\t\t\t\tCLANG_WARN_UNREACHABLE_CODE = NO;\n",
+        "\t\t\t\tCLANG_WARN_UNUSED_PARAMETER = NO;\n",
+        "\t\t\t\tGCC_WARN_CHECK_SWITCH_STATEMENTS = NO;\n",
+        "\t\t\t\tGCC_WARN_SIGN_COMPARE = NO;\n",
+        "\t\t\t\tGCC_WARN_UNINITIALIZED_AUTOS = NO;\n",
+        "\t\t\t\tGCC_WARN_UNUSED_FUNCTION = NO;\n",
+        "\t\t\t\tGCC_WARN_UNUSED_PARAMETER = NO;\n",
+        "\t\t\t\tGCC_WARN_UNUSED_VARIABLE = NO;\n",
+        "\t\t\t\tOTHER_CFLAGS = \"$(inherited) -Wno-sign-compare -Wno-strict-prototypes -Wno-unused-but-set-variable -Wno-unused-function -Wno-unused-parameter -Wno-unused-variable\";\n",
+        "\t\t\t\tOTHER_CPLUSPLUSFLAGS = \"$(inherited) -Wno-deprecated-declarations -Wno-non-c-typedef-for-linkage -Wno-sign-compare -Wno-switch -Wno-unguarded-availability-new -Wno-unused-but-set-variable -Wno-unused-function -Wno-unused-parameter -Wno-unused-private-field -Wno-unused-variable\";\n",
+    ),
+)
+patch_configs(
+    pathlib.Path(sys.argv[2]),
+    (
+        "FA0B7F261A95AAF4000E1D17",
+        "FA0B7F271A95AAF4000E1D17",
+        "FA0B7F281A95AAF4000E1D17",
+    ),
+    (
+        "\t\t\t\tCLANG_WARN_UNDECLARED_SELECTOR = NO;\n",
+        "\t\t\t\tCLANG_WARN_UNUSED_PARAMETER = NO;\n",
+        "\t\t\t\tOTHER_CFLAGS = \"$(inherited) -Wno-undeclared-selector -Wno-unused-parameter\";\n",
+    ),
+)
+PY
+}
+
 # --------------------------------------------------------------- xcodebuild
+# love.system.pickFile and createFile are a native bridge compiled in by
+# mobile/ios/patch_love_src.py, not part of LÖVE.  A build that skipped the
+# patch still links and still runs, then finds the field nil the moment anyone
+# taps Import ROM (#482).  #539 made that degrade to the copy-into-Files flow
+# rather than crash, which is the right floor, but a build with no picker at all
+# is a silent downgrade, so fail here instead of shipping one.
+#
+# Checked against the built binary rather than the source, because patching
+# love-src proves nothing about what Xcode actually compiled: the shipped
+# 0.1.45/0.1.46/0.1.47 IPAs all DO carry the bridge, so the reports that blamed
+# a missing patch step were self-built IPAs, exactly the case this catches.
+verify_native_bridge() {
+  local app="$1"
+  local exe bin missing=""
+  exe="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleExecutable' \
+         "$app/Info.plist" 2>/dev/null || true)"
+  bin="$app/${exe:-love}"
+  [ -f "$bin" ] || bin="$app/love"
+  if [ ! -f "$bin" ]; then
+    warn "no executable inside $(basename "$app"); skipping native bridge check"
+    return 0
+  fi
+  # grep -q here would race pipefail the same way pack_game_love documents:
+  # it exits on first match, strings dies of SIGPIPE, the pipeline "fails"
+  # nondeterministically.  >/dev/null keeps grep reading the whole stream.
+  for sym in pickFile createFile; do
+    strings -a "$bin" | grep -x "$sym" >/dev/null || missing="$missing $sym"
+  done
+  if [ -n "$missing" ]; then
+    fail "built app has no native bridge (missing:$missing).
+  Import ROM would fall back to copy-into-Files instead of opening the picker.
+  mobile/ios/patch_love_src.py did not take. Re-run:
+    scripts/build_ios.sh --fetch && scripts/build_ios.sh"
+  fi
+  say "native bridge present (pickFile, createFile)"
+}
+
 run_xcodebuild() {
   local config sdk destination
   if $RELEASE; then
@@ -389,6 +612,7 @@ run_xcodebuild() {
     MARKETING_VERSION="$marketing_version"
     CURRENT_PROJECT_VERSION="$project_version"
     ONLY_ACTIVE_ARCH=NO
+    DISABLE_MANUAL_TARGET_ORDER_BUILD_WARNING=YES
   )
 
   if ! $DEVICE; then
@@ -420,11 +644,27 @@ run_xcodebuild() {
 
   say "xcodebuild love-ios ($config / $sdk)"
   set +e
-  (
-    cd "$XCODE_DIR"
-    xcodebuild "${args[@]}"
-  )
-  local xc_status=$?
+  local xc_status
+  if command -v xcbeautify >/dev/null 2>&1; then
+    (
+      cd "$XCODE_DIR"
+      xcodebuild "${args[@]}"
+    ) 2>&1 | xcbeautify
+    local pipeline_status=("${PIPESTATUS[@]}")
+    local xcode_status=${pipeline_status[0]}
+    local beautify_status=${pipeline_status[1]}
+    if [ "$xcode_status" -ne 0 ]; then
+      xc_status=$xcode_status
+    else
+      xc_status=$beautify_status
+    fi
+  else
+    (
+      cd "$XCODE_DIR"
+      xcodebuild "${args[@]}"
+    )
+    xc_status=$?
+  fi
   set -e
   if [ "$xc_status" -ne 0 ]; then
     fail "xcodebuild failed (exit $xc_status).
@@ -455,6 +695,8 @@ run_xcodebuild() {
     cp "$LOVE_FILE" "$app/game.love"
   fi
 
+  verify_native_bridge "$app"
+
   local dist_dir="$DIST/${config}-${sdk}"
   rm -rf "$dist_dir"
   mkdir -p "$dist_dir"
@@ -524,10 +766,13 @@ install_to_device() {
 
 # --------------------------------------------------------------- main
 apply_ios_branding
+apply_ios_icon
 say "applying iOS native bridge patches (picker/Files support)"
 python3 "$IOS_DIR/patch_love_src.py" || fail "patch_love_src.py failed"
+ensure_manifests
 pack_game_love
 ensure_game_love_in_xcode
+suppress_love_dependency_warnings
 
 if $PACKAGE_ONLY; then
   say "package-only: skipping xcodebuild (game.love + plist ready under mobile/ios/love-src/)"

scripts/lint.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Static analysis for the engine Lua (config: .luacheckrc).
+#
+# Complements scripts/test.sh: the tests prove behavior, luacheck catches the
+# defects that never run in a green test -- undefined globals/locals (the
+# class that hid a music.volume crash: a hook read a `state` that was still
+# the nil global), unused values, unreachable code. The .luacheckrc mutes the
+# cosmetic categories the codebase lives with, so what prints is worth a look.
+#
+#   scripts/lint.sh            lint src/
+#   scripts/lint.sh src tools  lint specific paths
+#
+# Install once with:  luarocks install luacheck
+
+set -uo pipefail
+cd "$(dirname "$0")/.."
+
+if ! command -v luacheck >/dev/null 2>&1; then
+  echo "luacheck not found on PATH (install: luarocks install luacheck)" >&2
+  exit 2
+fi
+
+luacheck "${@:-src}"

scripts/test.sh

@@ -123,6 +123,7 @@ if [ -f data/generated/maps.lua ]; then
     run_tier "T3 save editor: events + dex" "$LUA" tests/save_editor_task7_tests.lua
     run_tier "T3 save editor: map browser" "$LUA" tests/save_editor_task8_tests.lua
     run_tier "T3 save editor: mod awareness" "$LUA" tests/save_editor_mod_tests.lua
+    run_tier "T3 save editor: wheel scrolling" "$LUA" tests/save_editor_wheel_bug595_test.lua
     run_tier "T5 link (loopback lockstep)" "$LUA" tests/run_link_tests.lua
   fi
 else

src/battle/EffectRegistry.lua

@@ -9,9 +9,22 @@ local MoveEffects = require("src.battle.MoveEffects")
 local Runtime = require("src.mods.Runtime")
 local StatusRegistry = require("src.battle.StatusRegistry")
 local Strings = require("src.core.Strings")
+local Timing = require("src.core.Timing")
 
 local EffectRegistry = {}
 
+-- A move that misses -- or that registers as missed, which in Gen 1 includes
+-- a type immunity and damage floored to zero -- skips its animation and
+-- falls into PlayerCheckIfFlyOrChargeEffect's `ld c, 30 / call DelayFrames`
+-- (engine/battle/core.asm:3155-3158 and :3185; enemy twin at :5588) before
+-- anything is printed.  EXPLODE_EFFECT is the exception: core.asm:3157
+-- branches it to PlayPlayerMoveAnimation instead, so it pays the animation
+-- rather than the hold -- the same condition that gates cancelMoveAnim.
+local function missBeat(battle, record)
+  if record and record.explode then return end
+  battle:waitNext(Timing.MOVE_STATUS_OR_MISS)
+end
+
 -- pokered's <USER>/<TARGET> text macros print "Enemy " before the enemy
 -- mon's nickname (home/text.asm PlaceMoveUsersName)
 local function displayName(b)
@@ -92,7 +105,14 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if target.invulnerable and not neverMiss then
     -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
     if not (record and record.explode) then battle:cancelMoveAnim() end
+    missBeat(battle, record)
     battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
+    -- MoveHitTest's INVULNERABLE branch sets the same wMoveMissed as a
+    -- failed accuracy roll (core.asm:5260), and the miss handler still
+    -- runs the explode effect ("even if Explosion or Selfdestruct
+    -- missed, its effect still needs to be activated", core.asm:3223),
+    -- so the user faints against a mid-Fly/Dig target too (#528)
+    if record and record.onMiss then record.onMiss(ctx, "invulnerable") end
     return
   end
 
@@ -114,6 +134,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     if not battle:accuracyRoll(move, user, target) then
       -- Explosion/Selfdestruct still animate on a miss (HandleIfPlayerMoveMissed)
       if not (record and record.explode) then battle:cancelMoveAnim() end
+      missBeat(battle, record)
       battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
       -- Jump Kick crash, Explode self-destruct
       if record and record.onMiss then record.onMiss(ctx, "accuracy") end
@@ -141,6 +162,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     end
     if not counterable or (battle.lastDamage or 0) == 0 then
       battle:cancelMoveAnim()
+      missBeat(battle, record)
       battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
       return
     end
@@ -164,6 +186,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if info.typeMult == 0 then
     -- type immunity zeros damage and sets wMoveMissed in Gen 1, so no anim
     if not (record and record.explode) then battle:cancelMoveAnim() end
+    missBeat(battle, record)
     battle:sayNext(Strings("It doesn't affect\n%s!", displayName(target)))
     if record and record.onMiss then record.onMiss(ctx, "immune") end
     return
@@ -171,6 +194,7 @@ function EffectRegistry.runDamaging(battle, ctx, record)
   if info.missed then
     -- 0.25x floored the damage to zero: the original registers a miss
     if not (record and record.explode) then battle:cancelMoveAnim() end
+    missBeat(battle, record)
     battle:sayNext(Strings("%s's\nattack missed!", displayName(user)))
     if record and record.onMiss then record.onMiss(ctx, "floored") end
     return
@@ -225,6 +249,13 @@ function EffectRegistry.runDamaging(battle, ctx, record)
     -- every strike -- damage was only rolled once
     if info.crit then battle:sayNext(Strings("Critical hit!")) end
     if info.ohko then battle:sayNext(Strings("One-hit KO!")) end
+    -- PrintCriticalOHKOText closes with `ld c, 20 / jp DelayFrames` at its
+    -- .done label (core.asm:3812-3814) -- and the no-crit path jumps to that
+    -- same label (:3799), so this hold is paid on EVERY landed hit, not just
+    -- critical ones.  It sits between the crit text and DisplayEffectiveness
+    -- (:3228-3229), which is where the beat before "It's super effective!"
+    -- comes from.
+    battle:waitNext(Timing.CRIT_OHKO_TEXT)
     if info.typeMult > 10 then
       battle:sayNext(Strings("It's super\neffective!"))
     elseif info.typeMult < 10 then

src/battle/MoveEffects.lua

@@ -435,8 +435,18 @@ local function drainHalf(text)
   end
 end
 
--- fixed damage still respects type immunity (AdjustDamageForMoveType
--- flags the miss before the special-damage override)
+-- OHKO is the only "damage but not through normal calculations" family
+-- that still runs the type chart.  CalculateDamage hands OHKO_EFFECT to
+-- JumpToOHKOMoveEffect (engine/battle/core.asm:4329) and, when the effect
+-- did not set wMoveMissed, execution falls through to
+-- AdjustDamageForMoveType (core.asm:3147), which multiplies the 65535 by
+-- the 0 matchup and flags the miss.  Fixed damage and Super Fang do not:
+-- they are the SetDamageEffects table (data/battle/set_damage_effects.asm)
+-- and core.asm:3139 jumps straight to MoveHitTest, skipping
+-- CalculateDamage, AdjustDamageForMoveType and RandomizeDamage, while
+-- ApplyAttackToEnemyPokemon (core.asm:4612) writes wDamage with no
+-- effectiveness step.  So in Gen 1 NIGHT_SHADE hits Normal-types and
+-- SUPER_FANG hits Ghosts, and only OHKO_EFFECT calls this (#616).
 local function immuneMsg(ctx)
   if TypeChart.effectiveness(ctx.move.type, ctx.target.curTypes) == 0 then
     return Strings("It doesn't affect\n%s!", displayName(ctx.target))
@@ -466,8 +476,7 @@ MoveEffects.full = {
 
   SPECIAL_DAMAGE_EFFECT = {
     chooseDamage = function(ctx)
-      local blocked = immuneMsg(ctx)
-      if blocked then return nil, blocked end
+      -- no immunity check: SetDamageEffects skips AdjustDamageForMoveType (#616)
       local dmg = fixedDamageFor(ctx)
       if not dmg then return nil, "But, it failed!" end
       return dmg, plainInfo()
@@ -475,8 +484,7 @@ MoveEffects.full = {
   },
   SUPER_FANG_EFFECT = {
     chooseDamage = function(ctx)
-      local blocked = immuneMsg(ctx)
-      if blocked then return nil, blocked end
+      -- also SetDamageEffects: halves a Ghost's HP in Gen 1 (#616)
       return math.max(1, math.floor(ctx.target.mon.hp / 2)), plainInfo()
     end,
   },

src/battle/WideBattle.lua

@@ -134,12 +134,13 @@ local function drawHUDs(battle, slide)
     drawStatusPanel(battle, battle.enemy, 0, 0, false)
   end
 
-  if battle.safari then
-    Font.drawBox(23, 7, 15, 4)
-    love.graphics.setColor(0, 0, 0, 1)
-    Font.draw(("BALLx%2d"):format(battle.safari.balls), 200, 72)
-  elseif battle.player and not battle.demo and not battle.showPlayerBack
-      and slide == 0 then
+  -- No player status panel in a safari / old-man battle: no mon of the
+  -- player's is out.  Nothing replaces it either -- the ball count is a menu
+  -- item, not a HUD element (DisplayBattleMenu prints wNumSafariBalls inside
+  -- the battle menu box, engine/battle/core.asm:2074-2079), so it rides in
+  -- drawCommandMenu below like the classic layout's (#540).
+  if not battle.safari and battle.player and not battle.demo
+      and not battle.showPlayerBack and slide == 0 then
     drawStatusPanel(battle, battle.player, 184, 56, true)
   end
   drawIntroBalls(battle)
@@ -172,6 +173,9 @@ local function drawCommandMenu(battle)
     Font.drawBox(0, 13, 38, 5)
     love.graphics.setColor(0, 0, 0, 1)
     Font.draw(Strings("BALLx"), 16, 112)
+    -- wNumSafariBalls immediately after the label, as at hlcoord 7,14
+    -- (engine/battle/core.asm:2074-2079) (#540)
+    Font.draw(("%2d"):format(battle.safari.balls), 56, 112)
     Font.draw(Strings("BAIT"), 168, 112)
     Font.draw(Strings("THROW ROCK"), 16, 128)
     Font.draw(Strings("RUN"), 168, 128)
@@ -183,6 +187,21 @@ local function drawCommandMenu(battle)
   Font.drawBox(0, 13, 20, 5)
   Font.drawBox(20, 13, 18, 5)
   love.graphics.setColor(0, 0, 0, 1)
+  -- The old-man / PROF.OAK catch demo has no party, so makeOldManDemo parks
+  -- the WILD mon in battle.player as a placeholder (BattleState:1209).  The
+  -- classic layout's demo branch never names anyone (DisplayBattleMenu,
+  -- core.asm:2038-2049, just draws the menu), so naming it here printed
+  -- "What will PIKACHU do?" over Oak's scripted throw (#557).  Leave the
+  -- prompt side blank and run the same scripted hand the classic does.
+  if battle.demo then
+    Font.draw(Strings("FIGHT"), 176, 112)
+    Font.drawCode(0xE1, 240, 112); Font.drawCode(0xE2, 248, 112)
+    Font.draw(Strings("ITEM"), 176, 128)
+    Font.draw(Strings("RUN"), 240, 128)
+    -- next to FIGHT for the first 80 frames, then ITEM
+    Font.drawCode(0xED, 168, (battle.demoTimer or 0) <= 80 and 112 or 128)
+    return
+  end
   Font.draw(Strings("What will"), 8, 112)
   local who = battle.player and battle.player.name or ""
   Font.draw(fitName(who, 112) .. Strings(" do?"), 8, 128)
@@ -305,22 +324,42 @@ function WideBattle.draw(battle)
   if sx == 0 and sy == 0 and fx and fx.shake and fx.shake > 0 then
     sx = battle.frame % 4 < 2 and 2 or -2
   end
-  local slide = (battle.introSlide or 0) * 4
+  -- same 2 px/frame silhouette slide the 160px layout uses
+  local slide = (battle.introSlide or 0)
+                * require("src.core.Timing").BATTLE_SLIDE_PX_PER_FRAME
 
   -- Each side keeps its original sprite pixels and placement math: the two
   -- 160x144 OAM regions are translated apart and clipped into the wider
   -- battlefield rather than either monster being scaled.  wideRegion tells
-  -- drawBattlerPic its own side window is already the clip.
+  -- drawBattlerPic its own side window is already the clip.  A shake moves
+  -- each region's clip with its contents, so a pic pushed toward a region
+  -- edge is not sheared off it (a vertical shake used to clip the player's
+  -- feet at FIELD_BOTTOM).
   battle.wideRegion = true
-  inRegion(0, 32, 160, WideBattle.FIELD_BOTTOM - 32, 20 + sx, 8 + sy,
+  inRegion(sx, 32 + sy, 160, WideBattle.FIELD_BOTTOM - 32, 20 + sx, 8 + sy,
     function() battle:drawPicsLayer(slide, 0, 0, "player", true) end)
-  inRegion(160, 0, 144, WideBattle.FIELD_BOTTOM, 136 + sx, sy,
+  inRegion(160 + sx, sy, 144, WideBattle.FIELD_BOTTOM, 136 + sx, sy,
     function() battle:drawPicsLayer(slide, 0, 0, "enemy", true) end)
   battle.wideRegion = nil
 
-  drawHUDs(battle, slide)
+  -- A battle sets rWY to 0 (engine/battle/core.asm), so the window the
+  -- shakes move IS the whole screen: PredefShakeScreenHorizontally,
+  -- PredefShakeScreenVertically and AnimationShakeScreenHorizontallySlow
+  -- displace the HUDs and the message window along with the pics, exactly as
+  -- drawClassic offsets its whole BG canvas.  Shaking only the two pic
+  -- regions left the foe gliding sideways across a nailed-down screen on
+  -- every applying-attack shake -- TAIL WHIP and every other status move
+  -- (#562).  The OAM anim layer stays put, as it does in drawClassic.
+  local function shaken(fn)
+    if sx == 0 and sy == 0 then return fn() end
+    g.push()
+    g.translate(sx, sy)
+    fn()
+    g.pop()
+  end
+  shaken(function() drawHUDs(battle, slide) end)
   drawAnimationLayer(battle)
-  drawTextArea(battle)
+  shaken(function() drawTextArea(battle) end)
 
   if fx and fx.flash and fx.flash > 0 and battle.frame % 4 < 2 then
     g.setColor(1, 1, 1, 0.85)

src/core/ChipAudio.lua

@@ -418,16 +418,22 @@ function ChipAudio.newCry(data, species, resolved)
   })
 end
 
+-- Two channels for the same reason ChipSynth.renderEffectData renders stereo:
+-- a mono Source is spatialized by OpenAL at the listener position and spreads
+-- over every output an interface has (#626).  The siren itself is unchanged,
+-- both channels carry the same sample.
 function ChipAudio.newLowHealthAlarm()
   local samples = math.floor(SAMPLE_RATE * 62 / 60)
-  local data = love.sound.newSoundData(samples, SAMPLE_RATE, 16, 1)
+  local data = love.sound.newSoundData(samples, SAMPLE_RATE, 16, 2)
   local phase = 0
   for index = 0, samples - 1 do
     local frame = math.floor(index * 60 / SAMPLE_RATE) % 31
     local register = frame < 11 and 0x750 or 0x6EE
     local frequency = 131072 / (2048 - register)
     phase = (phase + frequency / SAMPLE_RATE) % 1
-    data:setSample(index, (phase < 0.5 and 1 or -1) * 0.25)
+    local value = (phase < 0.5 and 1 or -1) * 0.25
+    data:setSample(index, 1, value)
+    data:setSample(index, 2, value)
   end
   return love.audio.newSource(data, "static")
 end

src/core/ChipSynth.lua

@@ -808,9 +808,22 @@ local function soundData(engine, samples, channels)
   return result
 end
 
--- Render a one-shot effect (SFX/cry) to a mono SoundData, or nil when it is
--- too short to be audible.  The caller wraps it in a static love.audio.Source
--- (a playback concern, hence not done here).
+-- Render a one-shot effect (SFX/cry) to a two-channel SoundData, or nil when
+-- it is too short to be audible.  The caller wraps it in a static
+-- love.audio.Source (a playback concern, hence not done here).
+--
+-- The synthesis is mono (one summed value per frame, unlike the music path's
+-- sampleStereo), but the buffer is written stereo on purpose: OpenAL only
+-- spatializes 1-channel Sources, and a Source left at the default (0,0,0)
+-- position, exactly where the listener sits, is rendered as an ambient sound
+-- spread over EVERY output channel the device exposes at gains that differ
+-- from the front pair.  On an interface with more than two outputs that put
+-- the SFX on outputs 5+6 as well, while the 2-channel music source
+-- (ChipAudio.playMusic) stayed on 1+2 (#626).  Multi-channel buffers skip
+-- spatialization entirely and map onto the front pair, so duplicating the
+-- sample costs one buffer's memory and makes effects route exactly like
+-- music.  Deliberately not sampleStereo: that honors the NR51 panning byte
+-- and would newly hard-pan any effect whose header issues command 0xEE.
 local function renderEffectData(data, header, options)
   if not header then return nil end
   options = options or {}
@@ -825,8 +838,12 @@ local function renderEffectData(data, header, options)
     values[count] = engine:sample()
   end
   if count < math.floor(SAMPLE_RATE / 100) then return nil end
-  local result = love.sound.newSoundData(count, SAMPLE_RATE, 16, 1)
-  for index = 1, count do result:setSample(index - 1, values[index]) end
+  local result = love.sound.newSoundData(count, SAMPLE_RATE, 16, 2)
+  for index = 1, count do
+    local value = values[index]
+    result:setSample(index - 1, 1, value)
+    result:setSample(index - 1, 2, value)
+  end
   return result
 end
 

src/core/Data.lua

@@ -14,12 +14,12 @@ local MODULES = {
 -- Optional for compatibility with developer and stale caches.
 local OPTIONAL = { "audio", "palettes", "icons" }
 
--- The rules the engine still carries as literals.  The constants registry
--- deep-merges over these, so a value has to exist before a mod can patch
--- it; each one is the number the engine hard-codes today, so seeding them
--- changes nothing on a mod-free boot.
+-- Vanilla defaults for rules exposed through the constants registry.  A
+-- value has to exist before a mod can patch it; each one matches the
+-- engine's no-mod behavior, so seeding them changes nothing on a vanilla
+-- boot.
 local CONSTANT_DEFAULTS = {
-  bagSize = 20,                 -- BAG_ITEM_CAPACITY (src/inventory/Bag.lua)
+  bagSize = 20,                 -- BAG_ITEM_CAPACITY (Bag.capacity fallback)
   partyMax = 6,                 -- PARTY_LENGTH (src/pokemon/Party.lua)
   boxCount = 12, boxSize = 20,  -- Bill's PC (src/pokemon/Boxes.lua)
   moveMax = 4,
@@ -77,6 +77,13 @@ end
 function Data:applyVersionedFieldData()
   if require("src.core.GameVersion").isYellow() then
     self.field.trades = copy(YELLOW_TRADES)
+    -- The old man's catch demo is a RATTATA in Yellow
+    -- (scripts/ViridianCity.asm ViridianCityOldManStartCatchTrainingScript
+    -- .SetupBattle: ld a, RATTATA / ld [wCurOpponent], a) but the Yellow
+    -- manifest inherited Red's WEEDLE field.oldManBattle (#617), so old
+    -- Yellow caches carry the wrong demo species too.  The fixed import
+    -- manifest below stamps RATTATA for fresh imports.
+    self.field.oldManBattle = { species = "RATTATA", level = 5 }
   end
 end
 
@@ -144,8 +151,8 @@ end
 -- no def_trainers row (DisplayTextID routes to his ASM script), so the
 -- extractor emits headers only for the four blackbelts ([2]..[5]).  Seed
 -- object index [1] so he behaves like the real leader:
---   * range 4 (matches the strongest blackbelt) -> CheckFightingMapTrainers
---     spots the player in his DOWN line and he challenges on sight (#197),
+--   * range 0: FightingDojoDefaultScript, not trainer sight, starts his
+--     battle from the single tile to his left (#495),
 --   * battle = his pre-battle challenge, won = "Hwa! Arrgh! Beaten!",
 --   * after = the "Stay and train at Karate with us!" re-talk line.
 -- Deliberately NO `event`: EVENT_BEAT_KARATE_MASTER is owned by
@@ -160,7 +167,7 @@ function Data:seedFightingDojoKarateMaster()
   headers.FightingDojo = headers.FightingDojo or {}
   if headers.FightingDojo[1] then return end
   headers.FightingDojo[1] = {
-    range = 4,
+    range = 0,
     battle = "_FightingDojoKarateMasterText",
     won = "_FightingDojoKarateMasterDefeatedText",
     after = "_FightingDojoKarateMasterStayAndTrainWithUsText",

src/core/FaithfulRes.lua

@@ -0,0 +1,220 @@
+-- Faithful resolution: lock the window to an exact integer multiple of the
+-- Game Boy's 160x144 screen, 1X through 4X.
+--
+-- At any other window size the renderer picks the largest integer scale that
+-- fits and letterboxes the remainder (Renderer:fitScale), so the game is
+-- already crisp -- what it is not is *exact*: there are bars, and at a wide
+-- window a lot of them.  Locking the window to 160*N x 144*N removes the
+-- letterbox entirely, so the surface is the Game Boy screen and nothing else.
+--
+-- Persisted as save.options.faithfulRes (0 = OFF).  Applied from OptionsMenu
+-- and on boot via Game:applyOptions.  No-ops in headless stubs that lack
+-- love.window.
+--
+-- MOBILE takes the other route to the same place.  There is no window to
+-- resize -- the window IS the screen, and it rotates -- so the lock caps the
+-- RENDER scale instead: the renderer draws the Game Boy screen at exactly N
+-- physical pixels per GB pixel and centres it, and the rest of the display
+-- stays black.  Same promise as the desktop lock (a GB pixel is exactly N
+-- screen pixels, no more) reached by moving the picture rather than the
+-- window.  This used to return false on the first line, so the row sat in
+-- OPTIONS on Android and iOS doing nothing at all.
+--
+-- Scale, not size, is also what makes rotation free: Renderer:fitScale runs
+-- every frame off the live drawable size, so portrait and landscape both get
+-- the same locked scale with the bars falling wherever the screen is longer.
+
+local FaithfulRes = {}
+
+FaithfulRes.WIDTH, FaithfulRes.HEIGHT = 160, 144
+FaithfulRes.LEVELS = { 0, 1, 2, 3, 4 }
+FaithfulRes.DEFAULT = 0
+
+-- mobile only: the locked scale in physical pixels per GB pixel, 0 for OFF.
+-- Renderer:fitScale reads it through FaithfulRes.scaleCap.
+FaithfulRes.mobileScale = 0
+
+-- conf.lua's floor for the resizable desktop window, restored when the lock
+-- is released.  1X and 2X are BELOW it, so the lock has to lower the minimum
+-- as well as set the size or LOVE clamps the window back up.
+FaithfulRes.MIN_W, FaithfulRes.MIN_H = 480, 360
+
+-- whether this module currently owns the window size
+FaithfulRes.locked = false
+
+-- The highest level this display can actually show.
+--
+-- On desktop it is 4: the levels are window sizes, and 4X is the ceiling the
+-- feature shipped with.  On mobile there is no window to size, so a fixed
+-- 1..4 ladder is meaningless -- 4X is a quarter of a 1080p phone, and the
+-- levels the panel could really use are not on the list at all.  Derive it
+-- from the screen instead, so a 1080x2400 phone offers up to 6X and the top
+-- of the ladder is the biggest exact-pixel picture it can draw.
+--
+-- OFF (0) is untouched by any of this and keeps doing exactly what it always
+-- did: the renderer fits and letterboxes as usual.
+function FaithfulRes.maxLevel()
+  -- Mobile is ON or OFF.  A ladder of absolute multiples is a desktop idea --
+  -- there it names a window size you can see.  On a phone the same number
+  -- means a different fraction of every device, and every level below the top
+  -- is just a smaller picture for no reason.  ON means one thing instead:
+  -- lock the viewport to the Game Boy's 10:9 and size it to this screen.
+  if FaithfulRes.isMobile() then return 1 end
+  return 4
+end
+
+-- the selectable ladder for this display: OFF, then 1X..maxLevel
+function FaithfulRes.levels()
+  local out = { 0 }
+  for i = 1, FaithfulRes.maxLevel() do out[#out + 1] = i end
+  return out
+end
+
+function FaithfulRes.normalize(v)
+  v = math.floor(tonumber(v) or FaithfulRes.DEFAULT)
+  if v < 0 then return 0 end
+  local max = FaithfulRes.maxLevel()
+  if v > max then return max end
+  return v
+end
+
+function FaithfulRes.label(v)
+  v = FaithfulRes.normalize(v)
+  if v == 0 then return "OFF" end
+  -- mobile has one ON: the level is chosen from the display, not the player
+  if FaithfulRes.isMobile() then return "ON" end
+  return tostring(v) .. "X"
+end
+
+function FaithfulRes.cycle(v, dir)
+  local levels = FaithfulRes.levels()
+  local cur = 1
+  for i, level in ipairs(levels) do
+    if level == FaithfulRes.normalize(v) then cur = i break end
+  end
+  return levels[(cur - 1 + (dir or 1)) % #levels + 1]
+end
+
+function FaithfulRes.isMobile()
+  -- POKEPORT_FORCE_MOBILE=1: take the mobile branch on a desktop build, so the
+  -- scale lock can be seen and driven without a device.  The window is still
+  -- resizable, which is the point -- drag it to a phone aspect, rotate it by
+  -- dragging the other way, and the lock has to hold through both.  Only this
+  -- module reads isMobile, so the override cannot leak into anything else.
+  if os.getenv("POKEPORT_FORCE_MOBILE") == "1" then return true end
+  if not love or not love.system or not love.system.getOS then return false end
+  local osName = love.system.getOS()
+  return osName == "Android" or osName == "iOS"
+end
+
+-- Physical pixels per LOVE unit for the CURRENT window.
+--
+-- Deliberately NOT love.window.getDPIScale: that reports the display's
+-- scaling factor even when the window is not high-DPI aware, and conf.lua
+-- only sets t.window.highdpi on mobile.  On a plain desktop window a unit IS
+-- a pixel, so dividing by the display scale just shrinks the window -- at
+-- 125% scaling a 2X request became 256x230 pixels, which Renderer:fitScale
+-- floors to 1, and 4X became 512x461, which floors to 3.  That is exactly
+-- the "2X renders at 1X, 4X renders at 3X" this shipped with.
+--
+-- Measuring the ratio the window actually reports is correct in both worlds:
+-- 1 on a plain desktop window, the real scale on a high-DPI one.
+local function pixelsPerUnit()
+  local g = love and love.graphics
+  if not (g and g.getDimensions and g.getPixelDimensions) then return 1 end
+  local uw = tonumber((g.getDimensions()))
+  local pw = tonumber((g.getPixelDimensions()))
+  if not uw or not pw or uw <= 0 or pw <= 0 then return 1 end
+  return pw / uw
+end
+
+-- The window size in LOVE UNITS that puts 160*v x 144*v PHYSICAL pixels on
+-- screen.
+function FaithfulRes.size(v)
+  v = FaithfulRes.normalize(v)
+  if v == 0 then return nil end
+  local ratio = pixelsPerUnit()
+  return math.floor(FaithfulRes.WIDTH * v / ratio + 0.5),
+         math.floor(FaithfulRes.HEIGHT * v / ratio + 0.5)
+end
+
+-- Push the lock into the live window.  Returns true when the window is
+-- locked afterwards.
+-- The largest WHOLE multiple of the Game Boy screen this display can hold.
+-- Integer, never fractional: a GB pixel has to be the same number of screen
+-- pixels in both axes or it is not pixel perfect, it is resampled.
+--
+-- The leftover is black bars, and on a tall phone there is a lot of it
+-- vertically -- that is simply what a 10:9 screen looks like on a 9:20
+-- display, and it is what an emulator shows too.
+function FaithfulRes.deviceScale()
+  local g = love and love.graphics
+  if not (g and g.getPixelDimensions) then return 1 end
+  local pw, ph = g.getPixelDimensions()
+  if not pw or not ph or pw <= 0 or ph <= 0 then return 1 end
+  return math.max(1, math.floor(math.min(pw / FaithfulRes.WIDTH,
+                                         ph / FaithfulRes.HEIGHT)))
+end
+
+-- The scale the renderer must lock to, or nil for "fit the window as usual".
+-- Only ever set on mobile: on desktop the window itself is the lock, so
+-- fitScale already lands on N and this would be a second, redundant one.
+--
+-- Always the device maximum.  Anything less is a smaller picture for no gain,
+-- which is how the first cut ended up showing a postage stamp on a 1080p
+-- phone.
+function FaithfulRes.scaleCap()
+  if not FaithfulRes.locked then return nil end
+  if not FaithfulRes.isMobile() then return nil end
+  return FaithfulRes.deviceScale()
+end
+
+function FaithfulRes.apply(v)
+  v = FaithfulRes.normalize(v)
+  -- Mobile: lock the render scale instead of the window.  The scale itself
+  -- comes from the display (deviceScale), not from v -- v only says whether
+  -- the lock is on.  Nothing to restore on release: the renderer simply goes
+  -- back to filling the display.
+  if FaithfulRes.isMobile() then
+    FaithfulRes.locked = v > 0
+    FaithfulRes.mobileScale = FaithfulRes.locked and FaithfulRes.deviceScale() or 0
+    return FaithfulRes.locked
+  end
+  if not love or not love.window or not love.window.setMode
+     or not love.window.getMode then
+    return false
+  end
+  local curW, curH, flags = love.window.getMode()
+  flags = flags or {}
+
+  if v == 0 then
+    -- only touch the window if we were the one holding it: an OFF setting on
+    -- boot must not resize a window the player sized themselves
+    if not FaithfulRes.locked then return false end
+    flags.resizable = true
+    flags.minwidth, flags.minheight = FaithfulRes.MIN_W, FaithfulRes.MIN_H
+    love.window.setMode(curW, curH, flags)
+    FaithfulRes.locked = false
+    return false
+  end
+
+  local w, h = FaithfulRes.size(v)
+  -- An exact size and a desktop-fullscreen mode cannot both hold.  The lock
+  -- is the more specific request, so it wins and drops fullscreen; VIDEO MODE
+  -- reads BORDERLESS until the player changes it, which then releases this.
+  flags.fullscreen = false
+  -- resizing by hand would silently break the lock, and nothing re-applies it
+  -- (there is no love.resize handler -- the renderer re-reads the size every
+  -- frame), so the window is fixed while locked rather than left draggable.
+  flags.resizable = false
+  flags.minwidth, flags.minheight = w, h
+  love.window.setMode(w, h, flags)
+  FaithfulRes.locked = true
+  return true
+end
+
+function FaithfulRes.applyOptions(opts)
+  return FaithfulRes.apply(opts and opts.faithfulRes)
+end
+
+return FaithfulRes

src/core/FixedStep.lua

@@ -7,9 +7,22 @@ local FixedStep = {}
 FixedStep.STEP = 1 / 60
 local MAX_ACCUM = 0.25 -- avoid spiral of death after a stall
 
+-- Phase the accumulator is re-seeded with once an absorbed hitch frame has
+-- been paid for.  Half a step is the balanced point: a frame has to come in
+-- ~8ms short before it drops a step and ~8ms long before it doubles one up.
+-- Zero -- what this used to leave behind -- has no margin at all on the long
+-- side, so the accumulator settles a hair BELOW one step and parks there, and
+-- ordinary sub-millisecond vsync wobble then flips it between 0 and 2 steps
+-- every few frames for the rest of the session.  That is why pacing stayed
+-- visibly broken after a route/city seam and nowhere else: crossConnection in
+-- src/world/OverworldController.lua is the only caller of discardCatchup, and
+-- warps go through Transition instead (issue #487).
+local RESEED_PHASE = 0.5
+
 function FixedStep:init(callback)
   self.accum = 0
   self.callback = callback
+  self.suppressCatchup = false
 end
 
 -- The anti-spiral clamp doubles as a steps-per-frame ceiling (0.25s = 15
@@ -20,6 +33,16 @@ end
 FixedStep.maxAccum = MAX_ACCUM
 
 function FixedStep:update(dt)
+  -- A hitch's oversized dt lands on the frame AFTER discardCatchup was
+  -- called (the hitch itself already ran inside the current step); absorb
+  -- that one frame as a single step instead of the normal accumulator so
+  -- the burst it would otherwise release doesn't play out as a slide.
+  if self.suppressCatchup then
+    self.suppressCatchup = false
+    self.accum = self.STEP * RESEED_PHASE
+    self.callback(self.STEP)
+    return
+  end
   self.accum = math.min(self.accum + dt, self.maxAccum or MAX_ACCUM)
   while self.accum >= self.STEP do
     self.accum = self.accum - self.STEP
@@ -27,12 +50,14 @@ function FixedStep:update(dt)
   end
 end
 
--- Drop any pending catch-up steps.  A hitch inside one logic step (map
--- seam setMap / song start) makes the next real-time dt huge; without this
--- the while-loop above would advance many walk frames before the next
--- draw, which looks like a slide with no leg animation (issue #93).
+-- Drop any pending catch-up steps and arm the one-frame clamp above.  A
+-- hitch inside one logic step (map seam setMap / song start) makes the
+-- next real-time dt huge; without this the while-loop above would advance
+-- many walk frames before the next draw, which looks like a slide with no
+-- leg animation (issue #93).
 function FixedStep:discardCatchup()
   self.accum = 0
+  self.suppressCatchup = true
 end
 
 return FixedStep

src/core/Game.lua

@@ -172,7 +172,28 @@ function Game:returnToTitle()
 end
 
 function Game:step(dt)
+  -- Tool mods (autoplay, accessibility drivers, input visualizers) act on
+  -- the same fixed-step boundary as a physical controller.  Run them before
+  -- Input:step promotes queued edges so a button chosen here is visible to
+  -- this logic tick, not one tick later.  With no wrapper this is a no-op.
+  ModRuntime.call("input.step", function() end, self, dt)
   self.input:step()
+  -- A+B+SELECT+START held for 16 steps: SoftReset (home/init.asm) stops the
+  -- audio, whites the palettes out and falls through into Init, i.e. the
+  -- power-on boot, so everything unsaved is gone and the title sequence
+  -- comes back -- exactly what returnToTitle does for the START menu's QUIT.
+  -- The check lives here, above stack:update, so it fires from any state:
+  -- overworld, battle, a menu or a cutscene, the way _Joypad's does (#563).
+  -- Input:reset clears the four still-physically-held buttons so the title
+  -- screen does not read A as a menu choice on its first frame.
+  -- a tool mod (or a harness) may hand Game a stand-in input with no
+  -- chord bookkeeping; those simply never soft reset
+  if self.input.softResetStep and self.input:softResetStep() then
+    Input:reset()
+    TouchControls:reset()
+    self:returnToTitle()
+    return
+  end
   -- serviced unconditionally: a link battle's ENet transport must not
   -- stall just because PartyMenu/ChoiceBox/NamingScreen is temporarily
   -- on top of BattleState (see LinkBattle.new)
@@ -244,6 +265,38 @@ end
 -- exactly as the owning state computed it
 local function sameZones(_, zones) return zones end
 
+-- Dim alpha for a BATTLE BG "world" battle anywhere in the stack, or nil.
+-- Same whole-stack rule as fillScaleInStack: a party menu or text box opened
+-- during the battle must not drop the dim for a frame.
+function Game.worldBgBattleDim(stack)
+  for i = #(stack and stack.states or {}), 1, -1 do
+    local state = stack.states[i]
+    if state and state.bgMode and state:bgMode() == "world" then
+      return state.BG_WORLD_DIM or 0.55
+    end
+  end
+  return nil
+end
+
+-- Does anything on the stack want the surface scaled to FILL the window
+-- (aspect preserved, bars on the long axis) rather than sit at the fixed
+-- integer scale?
+--
+-- Asked of the WHOLE stack, not just the top.  For BATTLE SIZE "fill" that is
+-- because the party menu, bag and text boxes a battle opens must not snap the
+-- surface back to the fixed scale for a frame; the title screen and intro want
+-- it unconditionally, since neither has a world behind it and neither has any
+-- reason to sit in a small box in the middle of a large window.
+function Game.fillScaleInStack(stack)
+  for i = #(stack and stack.states or {}), 1, -1 do
+    local state = stack.states[i]
+    if state and state.wantsFillScale and state:wantsFillScale() then
+      return true
+    end
+  end
+  return false
+end
+
 -- A wide battle owns the surface until it leaves the stack.  The party,
 -- bag, choice and text states it opens still draw their original 160px UI,
 -- but the canvas must not snap to 160px between those states.
@@ -257,6 +310,58 @@ function Game.wideBattleInStack(stack)
   return nil
 end
 
+-- Whether a state on the stack composes its own screen and so wants the
+-- edge anchors held off (BattleState.holdsUIAnchors).  Whole-stack, like
+-- everything else here: the text box and YES/NO a battle puts up are states
+-- of their own sitting above it, and they are exactly the elements that must
+-- stay inside the battle's composition rather than dock to the window.
+-- UI LAYOUT: is edge docking switched on?  Only the explicit "dynamic" turns
+-- it on, so a save written before the option existed -- and any caller with no
+-- save at all, which is most of the headless suites -- gets CENTERED, the
+-- behaviour the port shipped with.
+function Game.dynamicUI(save)
+  local options = save and save.options
+  return options ~= nil and options.uiLayout == "dynamic"
+end
+
+function Game.uiAnchorsHeldInStack(stack)
+  for i = #(stack and stack.states or {}), 1, -1 do
+    local state = stack.states[i]
+    if state and state.holdsUIAnchors then return true end
+  end
+  return false
+end
+
+-- Where Game:draw starts drawing this frame.  Normally the topmost opaque
+-- state (StateStack:visibleBase) -- but BATTLE BG "world" composes the battle
+-- over the LIVE map, and an opaque state pushed on top of it (the party menu,
+-- the bag) becomes that base, cutting the overworld -- and with it the world
+-- pass -- out of the frame entirely.  The backdrop the battle established
+-- then collapses to endFrame's flat black clear for as long as the menu is
+-- up.  So a world-bg battle keeps the frame starting from underneath itself
+-- until it leaves the stack, the same hold uiFill and the dim already use.
+--
+-- Only the START of the draw moves.  The clear stays keyed to the real
+-- visibleBase, so the menu still gets its opaque canvas and draws exactly as
+-- before; what changes is the window AROUND its letterbox, which keeps
+-- showing the map instead of going black.  Both menus fill their own
+-- 160x144 field first, so nothing beneath them shows through it.
+function Game.drawBaseInStack(stack, visibleBase)
+  local states = stack and stack.states or {}
+  for i = visibleBase - 1, 1, -1 do
+    local state = states[i]
+    if state and state.bgMode and state:bgMode() == "world" then
+      -- restart the search from under the battle: the highest opaque state at
+      -- or below it (the overworld), not the menu sitting over it
+      for j = i, 1, -1 do
+        if states[j].isOpaque then return j end
+      end
+      return 1
+    end
+  end
+  return visibleBase
+end
+
 -- Shift classic SGB zones to the centred UI. A full-width base zone extends
 -- into both margins, keeping the canvas' paper color continuous; narrower
 -- sprite and status zones move with the classic UI content.
@@ -282,6 +387,10 @@ function Game:draw()
   -- white clear
   local base = self.stack:visibleBase()
   local worldBelow = self.stack.states[base] == self.overworld
+  -- a world-bg battle keeps the map drawing under whatever it opened, so the
+  -- world pass can run for a frame whose CLEAR is still an opaque menu's
+  local drawFrom = Game.drawBaseInStack(self.stack, base)
+  local worldDrawn = self.stack.states[drawFrom] == self.overworld
   -- A wide battle holds its 304px surface through every menu or prompt it
   -- opens. States that do not draw the wide battle composition are centred
   -- in that surface below, so their classic coordinates and hit testing stay
@@ -298,8 +407,33 @@ function Game:draw()
   else
     Renderer:setUISize(Renderer.WIDTH, Renderer.HEIGHT)
   end
+  -- BATTLE SIZE: scale the battle surface to the window instead of the
+  -- classic integer letterbox.  Read from the whole stack, not just the top,
+  -- so a party menu or text box opened mid-battle keeps the same surface.
+  Renderer.uiFill = Game.fillScaleInStack(self.stack)
+  -- BATTLE BG "world": dim the overworld the battle is drawn over.  Read off
+  -- the stack for the same reason as uiFill above -- a prompt opened during
+  -- the battle must not drop the dim for a frame.
+  Renderer.battleDim = Game.worldBgBattleDim(self.stack)
+  -- ...and for the same reason the UI's own scale has to know the world is
+  -- still the backdrop while an opaque menu covers it.  Renderer:uiScale
+  -- steps the UI down with the survey zoom only while a world is behind it,
+  -- gated on this frame's world pass -- which the party menu and the bag end
+  -- by being opaque.  Without this hold they lose the step-down and blit at
+  -- full fit scale over a battle drawn at the zoomed-out one.
+  Renderer.uiWorldHold = Renderer.battleDim ~= nil
+  -- ...and a battle keeps its dialogue box and YES/NO inside its own screen
+  -- instead of letting them dock to the window edge.
+  -- UI LAYOUT: CENTERED (the default) is a fixed letterbox -- every element
+  -- stays inside the 160x144 canvas and the UI does not follow the survey
+  -- zoom, so the screen furniture never moves or resizes under the player.
+  -- That is the composition the port shipped with.  DYNAMIC opts into both
+  -- halves: the dialogue box docks to the window's bottom edge, the START
+  -- menu to its top right, and the whole UI steps down with the zoom.
+  Renderer.uiCentered = not Game.dynamicUI(self.save)
+  Renderer.uiAnchorHold = Game.uiAnchorsHeldInStack(self.stack)
   Renderer:beginFrame(worldBelow)
-  for i = self.stack:visibleBase(), #self.stack.states do
+  for i = drawFrom, #self.stack.states do
     local state = self.stack.states[i]
     local wideState = state and state.isWideBattleLayout
       and state:isWideBattleLayout()
@@ -336,10 +470,22 @@ function Game:draw()
   if ModRuntime.wantsHook("render.zones") then
     zones = ModRuntime.call("render.zones", sameZones, self, zones)
   end
-  if worldBelow and self.overworld.sgbWorldZones then
+  -- Keyed to whether the map actually DREW, not to whether it is the clear's
+  -- base: an opaque menu over a world-bg battle still renders the world pass
+  -- (drawBaseInStack), and leaving worldZones nil there drops endFrame's
+  -- world blit onto the UI zone list instead -- the party menu's own HP-bar
+  -- palettes, in 160x144 space, smeared across a world-canvas-sized image.
+  -- That is the offset, red-for-green map behind the menu.
+  if worldDrawn and self.overworld.sgbWorldZones then
     worldZones = self.overworld:sgbWorldZones()
   end
-  Renderer:endFrame(zones, worldZones)
+  local viewport = Renderer:endFrame(zones, worldZones)
+  -- Persistent tool status is screen-space UI: draw it over the completed
+  -- render pipeline with exact playfield/margin geometry, but below mobile
+  -- controls. It never becomes an updating game state.
+  if ModRuntime.wantsHook("render.hud") then
+    ModRuntime.call("render.hud", function() end, self, viewport)
+  end
   -- on-screen mobile controls: pure screen-space, over the finished frame
   TouchControls:draw()
 end
@@ -363,6 +509,24 @@ function Game:wheelmoved(_, dy)
   end
 end
 
+function Game:_cycleSpeed(dir)
+  if not (self.save and self.save.options) then return end
+  local busy
+  local ow = self.overworld
+  if ow then
+    local top = self.stack:top()
+    busy = ow.transitioning
+      or (top == ow and (
+           (ow.runner and ow.runner.isRunning and ow.runner:isRunning())
+        or (ow.scriptMoves and #ow.scriptMoves > 0)
+        or ow.engaging or ow.emote))
+  end
+  if busy then return end
+  local GameSpeed = require("src.core.GameSpeed")
+  self.save.options.speed = GameSpeed.cycle(self.save.options.speed, dir)
+  self:writeOptions()
+end
+
 function Game:keypressed(key)
   if self.stack and self.stack:top() and self.stack:top().onKeyPressed then
     self.stack:top():onKeyPressed(key)
@@ -400,6 +564,11 @@ function Game:keypressed(key)
   elseif key == "=" then
     self:zoomStep(1)
     return
+  elseif key == "1" then
+    -- cycle GAME SPEED (0.25X → 200X, logic only; audio unaffected);
+    -- R2/L2 on gamepad do the same (see gamepadpressed)
+    self:_cycleSpeed(1)
+    return
   elseif key == "2" then
     -- cycle COLORS (GBC / OG / OG INV / GBC INV / CLASSIC); the pack change
     -- forces Game.overworld:reloadMap, which rebuilds the live NPC array, so
@@ -464,14 +633,31 @@ function Game:restartWithMods()
   require("src.core.HostShell").restart()
 end
 
+-- Releases reach Input even while a top state captures raw input: a
+-- swallowed key-up would strand a held-state flag for a key Input saw go
+-- down before the capture armed (the stuck-flag hazard Input:reset
+-- exists for).  The top state only OBSERVES the release afterwards,
+-- unlike onKeyPressed above which owns the press, so BindingsMenu can
+-- commit a capture on the key-up (#589).
 function Game:keyreleased(key)
   Input:keyreleased(key)
+  local top = self.stack and self.stack:top()
+  if top and top.onKeyReleased then top:onKeyReleased(key) end
 end
 
 function Game:gamepadpressed(joystick, button)
   -- a controller is being used: the touch overlay steps aside until the
   -- next screen touch (mobile only; a no-op elsewhere)
   TouchControls:noteGamepad()
+  -- shoulder buttons cycle GAME SPEED (R2/rightshoulder = faster,
+  -- L2/leftshoulder = slower; same as keyboard hotkey 1)
+  if button == "rightshoulder" then
+    self:_cycleSpeed(1)
+    return
+  elseif button == "leftshoulder" then
+    self:_cycleSpeed(-1)
+    return
+  end
   -- BindingsMenu's pad capture rides the same top-state routing as keys
   local top = self.stack and self.stack:top()
   if top and top.onGamepadPressed then
@@ -482,7 +668,10 @@ function Game:gamepadpressed(joystick, button)
 end
 
 function Game:gamepadreleased(joystick, button)
+  -- same observe-after-Input contract as Game:keyreleased (#589)
   Input:gamepadreleased(joystick, button)
+  local top = self.stack and self.stack:top()
+  if top and top.onGamepadReleased then top:onGamepadReleased(button) end
 end
 
 function Game:gamepadaxis(joystick, axis, value)
@@ -502,15 +691,38 @@ local function isAccelerometer(joystick)
   return name ~= nil and name:lower():find("accelerometer", 1, true) ~= nil
 end
 
+-- BindingsMenu's raw-stick capture rides the same top-state routing as the
+-- keyboard and gamepad paths (#632).  Only a stick SDL does not recognize
+-- as a gamepad reaches the capture: a recognized pad raises BOTH
+-- joystickpressed and gamepadpressed for one press, and the joystick half
+-- would otherwise beat its own gamepadpressed to the armed row and record
+-- "JOY1" for a button the player can plainly see is A.  Same predicate as
+-- Input's, kept local here so Game never reaches into Input's internals.
+local function isRawStick(joystick)
+  return not (joystick and joystick.isGamepad and joystick:isGamepad())
+end
+
 function Game:joystickpressed(joystick, button)
   if isAccelerometer(joystick) then return end
   TouchControls:noteGamepad()
+  local top = self.stack and self.stack:top()
+  if isRawStick(joystick) and top and top.onJoystickPressed then
+    top:onJoystickPressed(button)
+    return
+  end
   Input:joystickpressed(joystick, button)
 end
 
 function Game:joystickreleased(joystick, button)
   if isAccelerometer(joystick) then return end
+  -- same observe-after-Input contract as Game:keyreleased (#589): the
+  -- capture watches the release, it never owns it, so a held-state flag
+  -- Input saw go down before the capture armed cannot be stranded
   Input:joystickreleased(joystick, button)
+  local top = self.stack and self.stack:top()
+  if isRawStick(joystick) and top and top.onJoystickReleased then
+    top:onJoystickReleased(button)
+  end
 end
 
 function Game:joystickaxis(joystick, axis, value)
@@ -578,6 +790,11 @@ end
 -- Capture the live world state into the save table and persist it.
 -- Options are flushed to options.lua as part of SaveData.save.
 function Game:writeSave()
+  -- Tool sessions can be deliberately ephemeral. Give them one narrow veto
+  -- before captureSave mutates the snapshot or any progress bytes reach disk.
+  if ModRuntime.call("save.write", function() return true end, self) == false then
+    return false
+  end
   if self.overworld and self.overworld.captureSave then
     self.overworld:captureSave(self.save)
   end
@@ -588,7 +805,7 @@ function Game:writeSave()
   if ModRuntime.wants("save.writing") then
     ModRuntime.emit("save.writing", { save = self.save, meta = self.save.meta })
   end
-  SaveData.save(self.save)
+  return SaveData.save(self.save)
 end
 
 -- Persist options.lua only (Options menu / hotkeys 2-5).  Keeps settings
@@ -615,10 +832,31 @@ function Game:applyOptions(opts)
   -- returns true when a persisted GBC FX level was cleared on mobile
   local gbcCleared = require("src.render.GBCFX").applyOptions(opts)
   require("src.core.VideoMode").applyOptions(opts)
+  -- after VideoMode: a faithful-resolution lock is an exact window size, so
+  -- it has to be the last word on the window (it drops fullscreen to hold)
+  require("src.core.FaithfulRes").applyOptions(opts)
   -- normalizes a nil/garbage cap to the 60 default, so old saves with no
   -- fpsCap key pace at the standard rate (issue #88)
   require("src.core.FrameCap").applyOptions(opts)
+  -- Scale the optional presentation extras to the device's performance
+  -- tier.  Every heavy feature was just applied from the stored options
+  -- above; here we clamp the *live* state down for a weaker device without
+  -- rewriting what the player saved, so raising the tier later restores
+  -- their exact TILT / GBC FX / ZOOM / MAX FPS choices.  A HIGH tier (the
+  -- default on a normal desktop, and every options.lua predating this
+  -- option) clamps nothing, so it is a no-op for the common case.
+  local caps = require("src.core.Performance").applyOptions(opts)
+  if not caps.tilt then require("src.render.Tilt").setLevel(0) end
+  if not caps.gbcfx then require("src.render.GBCFX").setLevel(0) end
+  local Zoom = require("src.render.Zoom")
+  Zoom.allowSurvey = caps.survey
+  if not caps.survey and Zoom.offset < 0 then Zoom.offset = 0 end
+  if caps.fpsMax then
+    local FrameCap = require("src.core.FrameCap")
+    if FrameCap.current > caps.fpsMax then FrameCap.apply(caps.fpsMax) end
+  end
   Input:applyBindings(opts.bindings)
+  TouchControls:applyOptions(opts)
   -- heal soft-bricked APK installs that already saved gbcfx > 0 (#136)
   if gbcCleared then self:writeOptions() end
 end

src/core/GameSpeed.lua

@@ -18,7 +18,7 @@ local GameSpeed = {}
 -- attempt is long enough that the iteration loop, not the engine, is the
 -- bottleneck. Vsync caps how much a real frame can do, so past 10X the
 -- multiplier is increasingly a ceiling rather than a rate.
-GameSpeed.LEVELS = { 1, 2, 4, 10, 20, 30, 50, 75, 100,200 }
+GameSpeed.LEVELS = { 1, 2, 3, 4, 10, 20, 30, 50, 75, 100, 200 }
 GameSpeed.DEFAULT = 1
 
 function GameSpeed.levelLabel(v)

src/core/HostShell.lua

@@ -13,6 +13,55 @@ function HostShell.envPrefix()
   return ""
 end
 
+-- Windows: every host tool we shell out to (curl for the update and mod-index
+-- fetches, the PowerShell ROM picker, the update downloader's `start /b`) is
+-- spawned through io.popen / os.execute, which run it under cmd.exe.  A
+-- GUI-subsystem process owns no console, so each of those children allocates
+-- its own -- one console window flashing per call, several stacking up during
+-- a mod install or an update (#606).  #74 fixed the same storm for the
+-- per-file cache mkdir by dropping the shell entirely (src/import/CacheFs.lua);
+-- the callers above genuinely need one, so we do the other half: allocate a
+-- single console for ourselves, once, and hide it.  A child inherits the
+-- parent's console when the parent has one, so every later spawn attaches to
+-- that invisible console and pops up nothing.  GUI dialogs the children raise
+-- (the PowerShell OpenFileDialog) are desktop windows and still appear.
+--
+-- Skipped when a console already exists, which is the developer case
+-- (lovec.exe, what scripts/run.ps1 prefers, or t.console), so printed output
+-- keeps landing in the terminal the game was launched from.  POKEPORT_CONSOLE=1
+-- opts out entirely and restores the old behaviour.  Memoized; non-Windows and
+-- FFI-less builds no-op.  Called once from love.load before anything shells
+-- out (main.lua).
+local consoleHidden = nil
+
+function HostShell.hideHostConsole()
+  if consoleHidden ~= nil then return consoleHidden end
+  consoleHidden = false
+  if os.getenv("POKEPORT_CONSOLE") == "1" then return consoleHidden end
+
+  local okFfi, ffi = pcall(require, "ffi")
+  if not okFfi or ffi.os ~= "Windows" then return consoleHidden end
+
+  -- kernel32 (AllocConsole/GetConsoleWindow) and user32 (ShowWindow) are
+  -- already loaded in any LOVE process, so ffi.C resolves both -- the same
+  -- assumption CacheFs makes for CreateDirectoryA.
+  pcall(ffi.cdef, [[
+    void *GetConsoleWindow(void);
+    int AllocConsole(void);
+    int ShowWindow(void *hWnd, int nCmdShow);
+  ]])
+  local ok, hidden = pcall(function()
+    if ffi.C.GetConsoleWindow() ~= nil then return false end
+    if ffi.C.AllocConsole() == 0 then return false end
+    local hwnd = ffi.C.GetConsoleWindow()
+    if hwnd == nil then return false end
+    ffi.C.ShowWindow(hwnd, 0) -- SW_HIDE
+    return true
+  end)
+  consoleHidden = (ok and hidden) or false
+  return consoleHidden
+end
+
 -- Wraps io.popen with the AppImage env fix applied and lua errors swallowed
 function HostShell.popen(command, mode)
   local ok, pipe = pcall(io.popen, HostShell.envPrefix() .. command, mode or "r")
@@ -26,9 +75,30 @@ end
 -- ("Failed to initialize filesystem: already initialized") and the relaunch
 -- crashes. So on an AppImage we relaunch the executable; the fresh process's
 -- Boot step mounts any downloaded update exactly as a manual relaunch would.
+-- Android hits the same wall (#575): the vendored love.cpp loops runlove()
+-- in-process on "restart", and PHYSFS_deinit in the old Filesystem module's
+-- destructor fails ("files still open") whenever any physfs handle survives
+-- lua_close, so the second PHYSFS_init throws the same "already initialized"
+-- and the app dies. There we relaunch through the GameActivity.restartApp
+-- JNI bridge (love.system.restartApp), which schedules our launch intent
+-- and kills the process so no native state can leak into the fresh run.
 -- On every other platform the in-process restart works, so keep it.
 function HostShell.restart()
   if not (love and love.event and love.event.quit) then return end
+
+  local osName = love.system and love.system.getOS and love.system.getOS()
+  if osName == "Android" then
+    -- restartApp kills the process on success, so a true return is never
+    -- observed; false means the bridge could not schedule the relaunch.
+    -- An older APK whose liblove predates the bridge (love.system.restartApp
+    -- is nil) has no crash-free in-process restart, so quit to the OS
+    -- cleanly and let the player relaunch by hand -- worse than restarting,
+    -- but better than the guaranteed crash of quit("restart") (#575).
+    if love.system.restartApp and love.system.restartApp() then return end
+    love.event.quit()
+    return
+  end
+
   local appimage = os.getenv("APPIMAGE")
   if not appimage then
     love.event.quit("restart")
@@ -48,4 +118,121 @@ function HostShell.restart()
   ffi.C.execv(appimage, ffi.cast("char *const *", argv))
 end
 
+-- ------- HTTP transport ----------------------------------------------------
+--
+-- Every remote fetch (mod index, mod releases, thumbnails) used to shell out
+-- to curl, which macOS / Windows 10+ / desktop Linux all ship and Android does
+-- not: adding a mod index on Android died with "curl is not available on this
+-- platform" (#597).  Android goes through the GameActivity.httpDownload JNI
+-- bridge instead (HttpsURLConnection, using the INTERNET permission link play
+-- already needs), surfaced by our vendored liblove as
+-- love.system.httpDownload(url, absPath, userAgent, accept).  Both transports
+-- block the calling thread and deal in whole files, so callers keep exactly
+-- the contract they had with curl.
+
+-- Shell quoting for one curl argument; cmd.exe has no single-quote form.
+function HostShell.quote(s)
+  s = tostring(s)
+  if love and love.system and love.system.getOS
+      and love.system.getOS() == "Windows" then
+    return '"' .. s:gsub('"', '') .. '"'
+  end
+  return "'" .. s:gsub("'", "'\\''") .. "'"
+end
+
+function HostShell.haveCurl()
+  local pipe = HostShell.popen("curl --version")
+  if not pipe then return false end
+  local readOk, out = pcall(function() return pipe:read("*a") end)
+  pcall(function() pipe:close() end)
+  return readOk and out ~= nil and out:find("curl", 1, true) ~= nil
+end
+
+-- The bridge only exists in our Android liblove.  An older APK reports nil
+-- here and falls back to the "no transport" error the callers already show;
+-- the iOS build compiles the same wrapper but always returns false, so gate
+-- on the OS as well and keep its error message honest.
+local function haveBridge()
+  if not (love and love.system and type(love.system.httpDownload) == "function") then
+    return false
+  end
+  return love.system.getOS and love.system.getOS() == "Android"
+end
+
+-- Is any transport available at all?  Callers gate on this, never on curl.
+function HostShell.canFetch()
+  return HostShell.haveCurl() or haveBridge()
+end
+
+-- Download url to an absolute host path.  Returns true, or nil plus an error.
+-- The curl branch deliberately ignores curl's exit code, as the download paths
+-- always did: callers judge the result by the file they got.
+function HostShell.httpDownload(url, absPath, userAgent, accept)
+  if type(url) ~= "string" or url == "" then return nil, "missing url" end
+  if type(absPath) ~= "string" or absPath == "" then return nil, "missing path" end
+  userAgent = userAgent or "gen1recomp"
+  if HostShell.haveCurl() then
+    local cmd = "curl -fsSL --connect-timeout 15 --max-time 300 "
+      .. "-H " .. HostShell.quote("User-Agent: " .. userAgent) .. " "
+    if accept then
+      cmd = cmd .. "-H " .. HostShell.quote("Accept: " .. accept) .. " "
+    end
+    cmd = cmd .. "-o " .. HostShell.quote(absPath) .. " " .. HostShell.quote(url)
+    local pipe = HostShell.popen(cmd)
+    if not pipe then return nil, "could not start download" end
+    pcall(function() pipe:read("*a") end)
+    pcall(function() pipe:close() end)
+    return true
+  end
+  if not haveBridge() then
+    return nil, "no network transport on this platform"
+  end
+  local ok, done = pcall(love.system.httpDownload, url, absPath, userAgent, accept)
+  if ok and done then return true end
+  return nil, "download failed"
+end
+
+-- GET returning the body.  curl streams it through a pipe; the Android bridge
+-- can only write a file, so there we fetch into the save directory (the only
+-- writable root on Android) and read it back.
+function HostShell.httpGet(url, userAgent, accept)
+  if type(url) ~= "string" or url == "" then return nil, "missing url" end
+  userAgent = userAgent or "gen1recomp"
+  if HostShell.haveCurl() then
+    local cmd = "curl -fsSL --connect-timeout 10 --max-time 40 "
+      .. "-H " .. HostShell.quote("User-Agent: " .. userAgent) .. " "
+    if accept then
+      cmd = cmd .. "-H " .. HostShell.quote("Accept: " .. accept) .. " "
+    end
+    cmd = cmd .. HostShell.quote(url)
+    local pipe = HostShell.popen(cmd)
+    if not pipe then return nil, "could not run curl" end
+    local readOk, out = pcall(function() return pipe:read("*a") end)
+    pcall(function() pipe:close() end)
+    if not readOk then return nil, "fetch failed: " .. tostring(out) end
+    if not out or out == "" then return nil, "empty response from " .. url end
+    return out
+  end
+  if not haveBridge() then
+    return nil, "no network transport on this platform"
+  end
+  if not (love.filesystem and love.filesystem.getSaveDirectory) then
+    return nil, "fetch needs LOVE"
+  end
+  local dirOk, saveDir = pcall(love.filesystem.getSaveDirectory)
+  if not dirOk or not saveDir or saveDir == "" then
+    return nil, "no save directory"
+  end
+  local name = "http_fetch.tmp"
+  pcall(love.filesystem.remove, name)
+  local ok, err = HostShell.httpDownload(url, saveDir .. "/" .. name, userAgent, accept)
+  if not ok then return nil, err end
+  local readOk, body = pcall(love.filesystem.read, name)
+  pcall(love.filesystem.remove, name)
+  if not readOk or type(body) ~= "string" or body == "" then
+    return nil, "empty response from " .. url
+  end
+  return body
+end
+
 return HostShell

src/core/Input.lua

@@ -41,7 +41,14 @@ local STICK_OFF = 0.3
 
 -- Generic SDL joysticks expose the left stick as the first two numbered
 -- axes and the D-pad as a hat.  This is common on Linux handhelds whose
--- controller has no game-controller database entry.
+-- controller has no game-controller database entry.  The indices below are
+-- the desktop XInput order and are only meaningful for such pads: raw
+-- numbering is per-driver, and SDL's iOS/MFi driver packs only the buttons
+-- a pad actually reports, which slides the D-pad down onto 7..10 (#620).
+-- These are the raw DEFAULTS only: applyBindings layers the player's
+-- "joyN" pad bindings over them (#632), and only a stick SDL does NOT
+-- recognize as a gamepad is ever served out of this table -- see
+-- joystickpressed below.
 local RAW_BUTTON_BINDINGS = {
   [1] = "a", [2] = "b",
   [7] = "select", [8] = "start", [9] = "select", [10] = "start",
@@ -66,9 +73,10 @@ end
 -- BindingsMenu:storeBinding) -- without this the menu records a choice
 -- that never actually reaches gameplay.
 function Input:applyBindings(overlay)
-  local keys, pads = {}, {}
+  local keys, pads, joys = {}, {}, {}
   for key, action in pairs(DEFAULT_BINDINGS) do keys[key] = action end
   for button, action in pairs(DEFAULT_GAMEPAD_BINDINGS) do pads[button] = action end
+  for index, action in pairs(RAW_BUTTON_BINDINGS) do joys[index] = action end
   for actionId, binding in pairs(overlay or {}) do
     if type(binding) == "table" then
       if binding.key then keys[binding.key] = actionId end
@@ -77,8 +85,20 @@ function Input:applyBindings(overlay)
       keys[binding] = actionId
     end
   end
+  -- A pad binding named "joyN" is the Nth button of a stick SDL has no
+  -- game-controller-database entry for, captured on the joystick path by
+  -- src/ui/BindingsMenu.lua (#632).  It deliberately rides the existing
+  -- pad slot: the CONTROLS row, the swap in BindingsMenu:storeBinding and
+  -- START's reset-all then all stay one code path, and this loop is the
+  -- only place that has to know what the name means.  Laid over the raw
+  -- defaults AFTER them, so a rebind wins the button it claims.
+  for padName, action in pairs(pads) do
+    local n = tonumber(padName:match("^joy(%d+)$"))
+    if n then joys[n] = action end
+  end
   self.keyBindings = keys
   self.padBindings = pads
+  self.joyBindings = joys
 end
 
 -- Purely event-driven state (press sets true, release sets false) has no
@@ -194,13 +214,30 @@ function Input:gamepadreleased(joystick, button)
   end
 end
 
+-- LOVE raises love.joystickpressed for EVERY stick, including ones SDL
+-- recognizes as gamepads, which raise love.gamepadpressed for the same
+-- physical press as well.  Answering both meant the fixed raw table
+-- re-asserted the factory A/B/START/SELECT map underneath the player's
+-- rebinds, so swapping A and B in CONTROLS pressed both at once and any
+-- controller rebind of those four looked ignored; on iOS the MFi driver's
+-- packing put the D-pad on 7..10, so a D-pad press also fired SELECT or
+-- START (#620, #632).  A recognized pad is served by the gamepad path
+-- alone; the raw path exists for sticks with no game-controller-database
+-- entry.  A nil joystick is a raw stick: that is how
+-- tests/input_hold_test.lua and the drivers drive this path.
+local function isRawStick(joystick)
+  return not (joystick and joystick.isGamepad and joystick:isGamepad())
+end
+
 function Input:joystickpressed(joystick, button)
-  local btn = RAW_BUTTON_BINDINGS[button]
+  if not isRawStick(joystick) then return end
+  local btn = self.joyBindings[button]
   if btn then press(self, btn, "joy:" .. button) end
 end
 
 function Input:joystickreleased(joystick, button)
-  local btn = RAW_BUTTON_BINDINGS[button]
+  if not isRawStick(joystick) then return end
+  local btn = self.joyBindings[button]
   if btn then release(self, btn, "joy:" .. button) end
 end
 
@@ -240,6 +277,7 @@ function Input:gamepadaxis(joystick, axis, value)
 end
 
 function Input:joystickaxis(joystick, axis, value)
+  if not isRawStick(joystick) then return end
   if axis == 1 then
     self:gamepadaxis(joystick, "leftx", value)
   elseif axis == 2 then
@@ -247,7 +285,12 @@ function Input:joystickaxis(joystick, axis, value)
   end
 end
 
+-- Same duplicate-event rule as joystickpressed (#620, #632): a recognized
+-- pad's D-pad already arrived as dpup/dpdown/dpleft/dpright through the
+-- gamepad map, so letting the hat answer too would re-assert the factory
+-- directions on top of a direction rebind.
 function Input:joystickhat(joystick, hat, direction)
+  if not isRawStick(joystick) then return end
   local source = "hat:" .. hat
   for _, btn in ipairs(self.hatDirs[hat] or {}) do
     release(self, btn, source)
@@ -263,8 +306,56 @@ function Input:isDown(btn)
   return self.state[btn] or false
 end
 
+-- True when the on-screen overlay is one of the live sources holding this
+-- button (see overlayPressed above).  Player:turnWindow widens the
+-- turn-in-place tap window on touch, where a press and release can never be
+-- as short as a physical d-pad's (#415).
+function Input:isTouchDown(btn)
+  local sources = self.sources[btn]
+  return (sources and sources["touch:" .. btn]) and true or false
+end
+
 function Input:wasPressed(btn)
   return self.pressed[btn] or false
 end
 
+-- Soft reset (#563).  _Joypad (engine/joypad.asm) tests the RAW joypad read
+-- with `cp PAD_BUTTONS` -- an equality, not a mask -- so the combo counts
+-- only while A, B, SELECT and START are the only buttons down; any d-pad
+-- direction in the mix cancels it.  That test sits ahead of the wJoyIgnore
+-- and BIT_DISABLE_JOYPAD masking below it, which is why the reset still
+-- works mid-battle and mid-cutscene where ordinary input is thrown away.
+-- TrySoftReset then burns one DelayFrame per pass and decrements hSoftReset,
+-- seeded with 16 by Init (home/init.asm), so the combo has to survive 16
+-- consecutive polls.  That hold is also what keeps the on-screen overlay
+-- safe: it already takes four separate fingers on four separate controls,
+-- and they all have to stay put for better than a quarter of a second.
+local SOFT_RESET_FRAMES = 16
+
+function Input:softResetHeld()
+  if not (self.state.a and self.state.b
+          and self.state.start and self.state.select) then
+    return false
+  end
+  return not (self.state.up or self.state.down
+              or self.state.left or self.state.right)
+end
+
+-- Ticked once per fixed step by Game:step; true on the step the countdown
+-- runs out.  hSoftReset is never re-seeded on release in the original, so
+-- its count leaks across a whole session; a port that copied that would
+-- eventually reset on a stray four-button press, so the counter re-arms as
+-- soon as the combo drops.
+function Input:softResetStep()
+  if not self:softResetHeld() then
+    self.softResetFrames = nil
+    return false
+  end
+  local left = (self.softResetFrames or SOFT_RESET_FRAMES) - 1
+  self.softResetFrames = left
+  if left > 0 then return false end
+  self.softResetFrames = nil
+  return true
+end
+
 return Input

src/core/Music.lua

@@ -23,6 +23,13 @@ local volumeScale = 1
 local FILTER_HIGHGAIN = { 0.4, 0.16, 0.064 }
 local filterLevel = 0
 
+-- Forward-declared here so applyVolume (below) closes over the real playback
+-- state rather than a nil global: the table literal is assigned further down,
+-- but a `local state = {}` there would leave every reference above it bound
+-- to the global `state`.  Before this, registering the `music.volume` mod
+-- hook crashed applyVolume on `state.current` (a nil index).
+local state
+
 local function applyVolume(src)
   if not src then return end
   local vol = VOLUME * volumeScale
@@ -63,7 +70,7 @@ local function applyFilter(src)
   end
 end
 
-local state = {
+state = {
   current = nil,      -- song label
   chip = false,       -- the playing song is a synthesized channel program
   source = nil,       -- currently playing source

src/core/Performance.lua

@@ -0,0 +1,156 @@
+-- Graphics performance tier: one knob that scales the port's optional,
+-- non-faithful presentation extras down for weaker hardware.
+--
+-- The heavy extras are all things the Game Boy never had and this port
+-- adds on top: the whole-screen 3D TILT (transforms the entire map as a
+-- ground plane), the GBC FX post-process shader (a fullscreen pass), and
+-- survey ZOOM (zooming out renders the connected neighbor maps -- a lot of
+-- extra overdraw).  A hard FPS ceiling caps present cost on top of that.
+-- None of this touches game logic, which is fixed-step off dt
+-- (src/core/FixedStep.lua), so every tier plays identically; they differ
+-- only in how much optional eye-candy the renderer is allowed to do.
+--
+-- The tier is persisted as save.options.performance:
+--   auto      pick a default from the device (see detect())
+--   high      everything on -- the historical behavior
+--   balanced  no TILT, no GBC FX (kept: survey zoom, colors, uncapped FPS)
+--   low       no TILT, no GBC FX, no survey zoom, FPS capped
+--
+-- AUTO only chooses the *default* for the current device; every tier is
+-- selectable in OPTIONS, so a heuristic that guesses wrong is one row away
+-- from being overridden.  The clamps are applied live in Game:applyOptions
+-- against the stored options without rewriting them, so raising the tier
+-- restores exactly the TILT / GBC FX / ZOOM / FPS the player had.
+--
+-- Zero requires: loads during love.conf and under plain Lua for tools and
+-- tests, the same way src/core/GameVersion.lua does.
+
+local Performance = {}
+
+-- Option-row order (auto first, then most to least capable).
+Performance.TIERS = { "auto", "high", "balanced", "low" }
+
+Performance.LABELS = {
+  auto = "AUTO",
+  high = "HIGH",
+  balanced = "BALANCED",
+  low = "LOW",
+}
+
+-- What each concrete tier permits.  `auto` is resolved to one of these
+-- before caps are read, so it has no row here.  fpsMax = false means no
+-- extra ceiling (the player's own MAX FPS still applies).
+Performance.CAPS = {
+  high     = { tilt = true,  gbcfx = true,  survey = true,  fpsMax = false },
+  balanced = { tilt = false, gbcfx = false, survey = true,  fpsMax = false },
+  low      = { tilt = false, gbcfx = false, survey = false, fpsMax = 60 },
+}
+
+-- Live resolved tier (never "auto"); Game:applyOptions sets it and the
+-- renderer / options row read it back.  Defaults to the unclamped tier so
+-- a pre-boot launcher behaves exactly as it always did.
+Performance.tier = "high"
+
+local function loveOS()
+  if love and love.system and love.system.getOS then
+    return love.system.getOS()
+  end
+  return nil
+end
+
+local function processorCount()
+  if love and love.system and love.system.getProcessorCount then
+    return love.system.getProcessorCount()
+  end
+  return nil
+end
+
+-- CPU architecture via LuaJIT's jit.arch when present: "arm"/"arm64" on
+-- phones and PortMaster handhelds, "x86"/"x64" on desktops.  nil under a
+-- plain-Lua tool or test with no jit table, which resolves to HIGH (no
+-- clamping) so tooling is never surprised.
+local function cpuArch()
+  return (jit and jit.arch) or nil
+end
+
+-- Default tier for the current device.  Deliberately conservative: only
+-- the platforms that are reliably weak drop below HIGH, and AUTO is always
+-- overridable, so a wrong guess costs one OPTIONS row.  A normal
+-- multi-core desktop -- the common case, and every existing install whose
+-- options.lua predates this option -- resolves to HIGH and behaves exactly
+-- as before.
+function Performance.detect()
+  local os = loveOS()
+  local arch = cpuArch()
+  local isArm = arch == "arm" or arch == "arm64"
+  local cores = processorCount()
+
+  -- PortMaster-style ARM Linux handhelds (e.g. the RG34XXSP the project
+  -- already ships a build for): the weakest target here.
+  if isArm and os ~= "Android" and os ~= "iOS" then
+    return "low"
+  end
+  -- Phones and tablets: GBC FX is already force-disabled here (issue #136);
+  -- balanced additionally drops the 3D tilt, the heaviest remaining extra.
+  if os == "Android" or os == "iOS" then
+    return "balanced"
+  end
+  -- Desktop: a dual-core (or single-core) box is the low-end line.
+  if cores and cores <= 2 then
+    return "balanced"
+  end
+  return "high"
+end
+
+-- Fold a stored option value to a concrete tier, resolving "auto" (and any
+-- hand-edited garbage) through detect().
+function Performance.resolve(value)
+  if value == "high" or value == "balanced" or value == "low" then
+    return value
+  end
+  return Performance.detect()
+end
+
+-- Normalize a stored value to a valid option id (keeps "auto"); a bad value
+-- degrades to auto so a corrupt options.lua still lands on something sane.
+function Performance.normalize(value)
+  for _, id in ipairs(Performance.TIERS) do
+    if value == id then return id end
+  end
+  return "auto"
+end
+
+-- Row label for a stored value: the tier's own name (AUTO / HIGH / ...).
+function Performance.label(value)
+  return Performance.LABELS[Performance.normalize(value)]
+end
+
+-- Concrete caps for a stored option value (resolving auto).
+function Performance.caps(value)
+  return Performance.CAPS[Performance.resolve(value)]
+end
+
+-- Resolve the tier for these options, record it live, and return its caps.
+-- Called from Game:applyOptions, which clamps the live presentation modules
+-- against the returned caps.
+function Performance.applyOptions(opts)
+  local tier = Performance.resolve(opts and opts.performance)
+  Performance.tier = tier
+  return Performance.CAPS[tier]
+end
+
+-- Cycle the OPTIONS row: auto -> high -> balanced -> low -> auto (dir -1
+-- reverses).  Lua's `%` is non-negative for a positive modulus, so a
+-- negative dir wraps correctly.
+function Performance.cycle(value, dir)
+  value = Performance.normalize(value)
+  local i = 1
+  for idx, id in ipairs(Performance.TIERS) do
+    if id == value then i = idx break end
+  end
+  local n = #Performance.TIERS
+  local nextIdx = (i - 1 + (dir or 1)) % n + 1
+  return Performance.TIERS[nextIdx]
+end
+
+return Performance

src/core/SafeArea.lua

@@ -0,0 +1,40 @@
+-- Usable window rect for mobile chrome (notch / Dynamic Island / home
+-- indicator / Android display cutouts).  Wraps love.window.getSafeArea when
+-- the engine provides it; otherwise the full graphics window.
+--
+-- Desktop and headless stubs return the full window, so callers can always
+-- layout against this rect without platform branches.  Interactive chrome
+-- (touch overlay, launcher) should prefer this over getDimensions; the game
+-- canvas may still letterbox into the full framebuffer for immersion.
+
+local SafeArea = {}
+
+function SafeArea.rect()
+  local ww, wh = 0, 0
+  if love and love.graphics and love.graphics.getDimensions then
+    ww, wh = love.graphics.getDimensions()
+  end
+  if ww <= 0 then ww = 1 end
+  if wh <= 0 then wh = 1 end
+
+  if not (love and love.window and love.window.getSafeArea) then
+    return 0, 0, ww, wh
+  end
+
+  local x, y, w, h = love.window.getSafeArea()
+  if type(x) ~= "number" or type(y) ~= "number"
+     or type(w) ~= "number" or type(h) ~= "number"
+     or w <= 0 or h <= 0 then
+    return 0, 0, ww, wh
+  end
+
+  -- Clamp to the drawable window so a bad / mid-rotation backend cannot
+  -- push layout outside the surface.
+  x = math.max(0, math.min(x, ww))
+  y = math.max(0, math.min(y, wh))
+  w = math.max(1, math.min(w, ww - x))
+  h = math.max(1, math.min(h, wh - y))
+  return x, y, w, h
+end
+
+return SafeArea

src/core/SaveData.lua

@@ -219,6 +219,24 @@ function SaveData.defaultOptions()
     -- battle screen composition: og (the 160x144 original) | wide
     -- (304x144, src/battle/WideBattle.lua)
     battleLayout = "og",
+    -- BATTLE SIZE: "fixed" = the classic integer-scaled letterbox; "fill" =
+    -- scale the battle surface to the window so it fills vertically.  See
+    -- BattleState:wantsFillScale.
+    battleFit = "fixed",
+    -- BATTLE BG: what fills the screen behind and around the battle.
+    -- "white" = the display mode's paper shade (the classic look),
+    -- "black" = plain black bars, "world" = the frozen overworld showing
+    -- through, dimmed.  See BattleState:bgMode.
+    battleBg = "white",
+    -- UI LAYOUT: "centered" = a fixed letterbox.  Every element sits where it
+    -- was drawn in the 160x144 canvas and the UI does not follow the survey
+    -- zoom, so nothing moves or resizes under the player.  The original
+    -- composition.  "dynamic" = the dialogue box docks to the window's bottom
+    -- edge, the START menu to its top right, and the UI steps down with the
+    -- zoom.  Centered is the default: dynamic reads better zoomed out, but it
+    -- moves the screen furniture, so it is opt-in.
+    -- See Game.dynamicUI, Renderer:setUIAnchor and Renderer:uiScale.
+    uiLayout = "centered",
     ruleset = "gen1_faithful",
     -- 0-7 like the GB's NR50 master volume
     musicVol = 7,
@@ -239,8 +257,16 @@ function SaveData.defaultOptions()
     voidFill = "trees",
     -- windowed | borderless (desktop fullscreen); ignored on mobile
     videoMode = "windowed",
+    -- lock the window to an exact 160x144 multiple, 1..4 (0 = OFF); see
+    -- src/core/FaithfulRes.lua.  Ignored on mobile.
+    faithfulRes = 0,
     -- hard render frame-rate cap; render-only pacing (issue #88, FrameCap.lua)
     fpsCap = 60,
+    -- graphics performance tier: auto | high | balanced | low.  "auto"
+    -- picks a default from the device (ARM handhelds/phones drop the heavy
+    -- extras); scales TILT / GBC FX / survey ZOOM / FPS but never game
+    -- logic.  See src/core/Performance.lua.
+    performance = "auto",
     -- Per-pipeline display levels, keyed by render_pipelines id (see
     -- src/render/Pipelines.lua).  A level for a mod that is not installed
     -- is kept rather than pruned, so re-enabling the mod restores the mode
@@ -249,6 +275,36 @@ function SaveData.defaultOptions()
     -- Native mod enablement is an installation option, not save-slot data.
     -- Missing entries mean enabled so newly installed mods work by default.
     mods = {},
+    -- Named setups the player can switch between (#593; src/mods/ModProfile.lua
+    -- owns the shape, src/mods/ManagerState.lua the UI): each row is
+    -- { name, enabled = {id=bool}, options = {id={k=v}}, slots = {version=slotId} }.
+    -- activeProfile names the row the live set currently matches (nil for
+    -- ad-hoc, so it has no default entry here; mergeOptions preserves it).
+    -- modProfilesSeeded records that the pre-profiles setup was already
+    -- migrated into PROFILE 1, so deleting every profile does not re-seed one.
+    modProfiles = {},
+    modProfilesSeeded = false,
+    -- GitHub release checks for mods with a manifest "github" field
+    -- (src/mods/ModUpdate.lua). Keyed by owner/repo; TTL is six hours.
+    modUpdateCache = {},
+    -- Community mod indexes the player has chosen to browse
+    -- (src/mods/ModIndex.lua), in the order they added them.  Empty by
+    -- default and never populated automatically: adding an index is how a
+    -- player says they trust whoever publishes it, so the launcher asks
+    -- rather than shipping one.  Rows are { url, feed, base, fallback,
+    -- label }.
+    modIndexes = {},
+    -- Parsed index listings keyed by feed URL; TTL is 24 hours, matching how
+    -- often the feeds themselves rebuild.
+    modIndexCache = {},
+    -- On-screen touch overlay (Android/iOS; see src/core/TouchControls.lua).
+    -- enabled=false hides it permanently (distinct from auto-hide-on-gamepad).
+    -- layouts.portrait / layouts.landscape each hold optional normalized
+    -- centers {x=0..1, y=0..1} per control (dpad/a/b/start/select) plus a
+    -- size scale; nil positions mean that orientation draws the default
+    -- layout (#633).  Pre-#633 files stored one top-level positions table;
+    -- TouchControls.normalizeConfig folds it into both orientations on load.
+    touchControls = { enabled = true },
   }
 end
 
@@ -1035,7 +1091,7 @@ local function reclaim(save, data, report)
     if type(entry) == "table" and known(data.items, entry.id) then
       table.remove(orphaned.items, i)
       if entry.from == "pcItems" or type(save.inventory) ~= "table"
-          or not Bag.add(save, entry.id, entry.count or 1) then
+          or not Bag.add(save, entry.id, entry.count or 1, data) then
         save.pcItems = save.pcItems or {}
         save.pcItems[entry.id] = (save.pcItems[entry.id] or 0) + (entry.count or 1)
       end

src/core/Sound.lua

@@ -82,6 +82,40 @@ local function isChipDef(def)
   return type(def) == "table" and (def.chip ~= nil or def.address ~= nil)
 end
 
+-- OpenAL only spatializes 1-channel Sources, and one left at the default
+-- (0,0,0) position sits on top of the listener, which OpenAL renders as an
+-- ambient sound spread over every output channel the device has: on an
+-- interface with more than two outputs the SFX also came out of outputs 5+6
+-- while the 2-channel music stayed on 1+2 (#626).  A Source cannot change its
+-- channel count after the fact, so a mono file def is re-decoded and its
+-- sample duplicated into a stereo buffer, which OpenAL never spatializes.
+-- Chip SFX and cries are already stereo at the source (ChipSynth
+-- renderEffectData); this covers file defs, i.e. Yellow's 8-bit mono PCM
+-- Pikachu clips (RomExtractor extractPikachuCries) and mod-supplied wav/ogg
+-- SFX.  Every step is guarded: a headless love stub without love.sound, or a
+-- decoder that will not hand back SoundData, keeps the original Source.
+local function widenMono(source, file)
+  if not (source and love.sound and love.sound.newSoundData) then
+    return source
+  end
+  local ok, channels = pcall(function() return source:getChannelCount() end)
+  if not ok or channels ~= 1 then return source end
+  local built, widened = pcall(function()
+    local mono = love.sound.newSoundData(file)
+    local frames = mono:getSampleCount()
+    local stereo = love.sound.newSoundData(frames, mono:getSampleRate(),
+                                           mono:getBitDepth(), 2)
+    for index = 0, frames - 1 do
+      local value = mono:getSample(index)
+      stereo:setSample(index, 1, value)
+      stereo:setSample(index, 2, value)
+    end
+    return love.audio.newSource(stereo, "static")
+  end)
+  if built and widened then return widened end
+  return source
+end
+
 -- a file def carries an optional playback rate; a bare string is shorthand
 -- for { file = <string> }
 local function newFileSource(def)
@@ -89,6 +123,7 @@ local function newFileSource(def)
   if type(file) ~= "string" then return nil, "no chip program and no file" end
   local ok, s = pcall(love.audio.newSource, file, "static")
   if not ok or not s then return nil, ok and "no source" or tostring(s) end
+  s = widenMono(s, file) -- keep mono defs off the surround channels (#626)
   if type(def) == "table" and def.pitch then pcall(s.setPitch, s, def.pitch) end
   return s
 end
@@ -233,12 +268,16 @@ function Sound.playPikaCry(data, n)
   local src = cache[key]
   if src == false then return nil end
   if not src then
-    local ok, s = pcall(love.audio.newSource,
-      ("assets/generated/audio/pika_cries/cry_%02d.wav"):format(n), "static")
-    if not ok then
+    local path = ("assets/generated/audio/pika_cries/cry_%02d.wav"):format(n)
+    local ok, s = pcall(love.audio.newSource, path, "static")
+    if not ok or not s then
       cache[key] = false
       return nil
     end
+    -- the importer writes these clips as 8-bit mono (RomExtractor
+    -- extractPikachuCries), so they need the same widening as the chip
+    -- effects to stay off a multi-output device's surround channels (#626)
+    s = widenMono(s, path)
     s:setVolume(volumeFor(key))
     cache[key] = s
     src = s

src/core/Timing.lua

@@ -0,0 +1,198 @@
+-- Hardware frame budgets, in fixed 60Hz logic steps.
+--
+-- The original spends a large share of its running time inside DelayFrames
+-- calls that produce no visible change -- the pause after a page break, the
+-- beat before a status move resolves, the one-HP-at-a-time drain of an HP
+-- bar.  Porting the visible half of a sequence and dropping the wait is what
+-- makes a port read as snappier than hardware, so every one of those waits
+-- lives here with its asm citation instead of as a file-local constant.
+--
+-- See docs/timing-parity.md for the full catalog and the measurement method;
+-- tools/scan_pokered_delays.ps1 regenerates the hardware side from a
+-- disassembly checkout.
+
+local Timing = {}
+
+-- home/palettes.asm:14 -- three frames to let the bg map fully update
+Timing.DELAY3 = 3
+
+-- home/fade.asm: each fade is a loop of `ld c, 8 / call DelayFrames`
+Timing.FADE_IN_FROM_BLACK  = 32 -- fade.asm:21, b = 4
+Timing.FADE_OUT_TO_BLACK   = 32 -- fade.asm:43, b = 4
+Timing.FADE_OUT_TO_WHITE   = 24 -- fade.asm:26, b = 3
+Timing.FADE_IN_FROM_WHITE  = 24 -- fade.asm:48, b = 3
+
+-- Overworld -----------------------------------------------------------------
+
+-- home/overworld.asm:703 PlayMapChangeSound tail-calls GBFadeOutToBlack on
+-- every map change.  There is no matching fade in: the new map is drawn while
+-- the palettes are still blacked out and LoadGBPal restores them in one write,
+-- so the map appears instantly.
+Timing.WARP_FADE_OUT = Timing.FADE_OUT_TO_BLACK
+Timing.WARP_FADE_IN  = 0
+
+-- home/overworld.asm:351-352 -- after a battle, before EnterMap
+Timing.POST_BATTLE_RETURN = 10
+
+-- engine/overworld/player_animations.asm:5-7 -- EnterMapAnim, the fly /
+-- teleport / dungeon-warp arrival: Delay3 then GBFadeInFromWhite
+Timing.SPECIAL_WARP_ENTRY = Timing.DELAY3 + Timing.FADE_IN_FROM_WHITE
+-- player_animations.asm:43 -- dungeon warp holds before handing back control
+Timing.DUNGEON_WARP_ARRIVAL = 50
+
+-- Text ----------------------------------------------------------------------
+
+-- home/text.asm:283-307 ScrollTextUpOneLine is `ld b, 5` of DelayFrame, and
+-- its own comment notes it is "always called twice in a row"
+Timing.TEXT_SCROLL_LINE = 5
+Timing.TEXT_SCROLL_PAIR = Timing.TEXT_SCROLL_LINE * 2
+
+-- Both _ContText (home/text.asm:262-277) and Paragraph (:230-243) print the
+-- â–¼ and call ProtectedDelay3 *before* ManualTextScroll starts watching the
+-- joypad, so three frames pass with the arrow up and the button ignored.
+Timing.TEXT_PRE_ADVANCE = Timing.DELAY3
+
+-- Paragraph / PageChar clear the box and then hold (home/text.asm:239-240,
+-- :254-255) before the next page starts typing.
+Timing.TEXT_PAGE_CLEAR = 20
+
+-- Totals, for the catalog and the parity tests.
+Timing.TEXT_CONT      = Timing.TEXT_PRE_ADVANCE + Timing.TEXT_SCROLL_PAIR
+Timing.TEXT_PARAGRAPH = Timing.TEXT_PRE_ADVANCE + Timing.TEXT_PAGE_CLEAR
+Timing.TEXT_PAGE      = Timing.TEXT_PARAGRAPH
+
+Timing.TEXT_PAUSE = 30 -- home/text.asm:500 TextCommand_PAUSE
+Timing.TEXT_DOT   = 10 -- home/text.asm:576 TextCommand_DOTS, per dot
+
+-- Menus ---------------------------------------------------------------------
+
+-- engine/menus/text_box.asm:322-323 / :333-334 -- both branches of a
+-- two-option (yes/no) menu hold before restoring the screen tiles
+Timing.YES_NO_ANSWER = 15
+
+Timing.LIST_MENU_OPEN   = 10             -- home/list_menu.asm:55-56
+Timing.LIST_MENU_REDRAW = Timing.DELAY3  -- home/list_menu.asm:64
+
+-- engine/menus/start_sub_menus.asm:224-225
+Timing.FIELD_TELEPORT = 60 + Timing.DELAY3
+
+-- Battle --------------------------------------------------------------------
+
+-- SlidePlayerAndEnemySilhouettesOnScreen (engine/battle/core.asm:9-49):
+-- the enemy comes in on BG SCX $90 -> $00 and the player's back pic on
+-- decrementing OAM x, both 2 px per frame -- so 144 px over 72 frames.  The
+-- port ran 160 px at 4 px/frame (40 frames), a little under twice too fast.
+Timing.BATTLE_SLIDE_IN_FRAMES = 72
+Timing.BATTLE_SLIDE_PX_PER_FRAME = 2
+
+-- PrintBeginningBattleText .trainerBattle (engine/battle/common_text.asm):
+-- SFX_SILPH_SCOPE plays into a clear window (PlaySound then
+-- WaitForSoundToFinish, which blocks), and only after `ld c, 20 /
+-- DelayFrames` do DrawAllPokeballs and the "wants to fight!" text run.
+Timing.TRAINER_INTRO_SFX_GAP = 20
+
+Timing.BATTLE_START_SENDOUT = 40 -- engine/battle/core.asm:155-156
+Timing.MOVE_ANIM_PRE        = Timing.DELAY3 -- core.asm:6638 PlayMoveAnimation
+
+-- core.asm:3185-3186 (player) / :5587-5588 (enemy).  Reached when the move
+-- has 0 BP (core.asm:3145 -- every status move) or missed (:3158), so this
+-- beat is paid on a large fraction of all turns.
+Timing.MOVE_STATUS_OR_MISS = 30
+
+-- PlayApplyingAttackAnimation's six types (AnimationTypePointerTable,
+-- engine/battle/animations.asm:490-524).  The two shake families are
+-- `AnimationShakeScreenHorizontallySlow`, whose double push/pop makes each
+-- outer pass cost 4b frames and run c times -- so c * 4b.
+Timing.SHAKE_VERTICAL     = 48 -- type 1, b=8: 8 x 6
+Timing.SHAKE_HORIZ_HEAVY  = 72 -- type 2, b=8: 8 x 9
+Timing.SHAKE_HORIZ_SLOW   = 48 -- type 3, lb bc, 6, 2: 2 x 4x6
+Timing.SHAKE_HORIZ_LIGHT  = 18 -- type 5, b=2: 2 x 9
+Timing.SHAKE_HORIZ_SLOW2  = 24 -- type 6, lb bc, 3, 2: 2 x 4x3
+
+-- Type 4 -- the player's damaging move with no added effect, and so the
+-- single most common animation in the game -- is AnimationBlinkMon
+-- (animations.asm:1360-1376): `ld c, 6` iterations of hide + DelayFrames 5
+-- + show + DelayFrames 5.  The asm's own comment calls it "a second or
+-- two"; the port ran it in 20 frames, three times too fast, which is a
+-- large part of why trading blows felt hurried.
+Timing.BLINK_MON = 60
+
+-- SlideDownFaintedMonPic (engine/battle/core.asm:1181-1222): b = PIC_HEIGHT
+-- (7) outer iterations, each closing with `ld c, 2 / call DelayFrames`.
+-- This one the port ran SLOWER than hardware, at 30.
+Timing.FAINT_SLIDE = 14
+
+Timing.RESIDUAL_TICK      = 20 -- core.asm:529-530 poison/burn/leech seed
+Timing.CRIT_OHKO_TEXT     = 20 -- core.asm:3813-3814
+Timing.SWITCH_PLAYER_MON  = 50 -- core.asm:2421-2422
+Timing.NO_MOVES_LEFT      = 60 -- core.asm:2753-2754
+Timing.TRAINER_VICTORY    = 40 -- core.asm:940-941
+Timing.PLAYER_BLACKOUT    = 40 -- core.asm:1143-1144
+Timing.FAINT_SLIDE_ROW    = 2  -- core.asm:1216-1217, per row
+Timing.FAINT_SLIDE_STEP   = 8 / Timing.FAINT_SLIDE_ROW -- 4px per frame at 1x
+Timing.TRAINER_SLIDE_COL  = 2  -- core.asm:1267-1268, per column
+
+-- HP bar (engine/gfx/hp_bar.asm) ---------------------------------------------
+--
+-- UpdateHPBar steps ONE HP point per loop iteration (:81-120).  Each
+-- iteration pays:
+--   * 1 frame in UpdateHPBar_PrintHPNumber's DelayFrame (:234) -- but only
+--     when wHPBarType is nonzero (:207-209), i.e. the player's own HUD and
+--     the party menu, never the enemy HUD; and
+--   * 2 frames per pixel the bar actually moved, from
+--     UpdateHPBar_AnimateHPBar's `ld c, 2 / call DelayFrames` (:147-148).
+-- The drain closes with one more pixel step and a Delay3 (:133-135).
+--
+-- So a player-side drain of D HP across P pixels costs D + 2P + 6 frames,
+-- while the same drain on the enemy HUD costs only 2P + 5.  A 150 HP mon
+-- losing everything takes 150 + 96 + 6 = 252 frames on hardware.
+
+Timing.HP_BAR_PIXELS      = 48 -- the bar is 48 px wide (GetHPBarLength)
+Timing.HP_BAR_PIXEL_STEP  = 2  -- frames per pixel of bar movement
+Timing.HP_BAR_HP_STEP     = 1  -- frames per HP point, player-side HUD only
+
+-- Pixels the bar shows for `hp` out of `maxHP`.  GetHPBarLength floors the
+-- 48ths and clamps the result to at least 1 for any nonzero HP
+-- (engine/gfx/hp_bar.asm:42-45); an empty bar is 0.
+function Timing.hpBarPixels(hp, maxHP)
+  if not maxHP or maxHP <= 0 then return 0 end
+  if hp <= 0 then return 0 end
+  local px = math.floor(hp * Timing.HP_BAR_PIXELS / maxHP)
+  if px < 1 then px = 1 end
+  return px
+end
+
+-- Frames one single-HP step of the drain costs: the per-HP number print
+-- (player side only) plus two frames for every pixel that step moved.
+function Timing.hpDrainStepFrames(fromHP, toHP, maxHP, playerSide)
+  local pixels = math.abs(Timing.hpBarPixels(toHP, maxHP)
+                          - Timing.hpBarPixels(fromHP, maxHP))
+  local frames = pixels * Timing.HP_BAR_PIXEL_STEP
+  if playerSide then frames = frames + Timing.HP_BAR_HP_STEP end
+  return frames
+end
+
+-- After the loop, .animateHPBarDone prints the number one last time, runs
+-- AnimateHPBar for a single pixel and falls into Delay3 (hp_bar.asm:132-135)
+-- -- so the tail costs 6 frames on the player's HUD and 5 on the enemy's.
+function Timing.hpDrainClosingFrames(playerSide)
+  local frames = Timing.HP_BAR_PIXEL_STEP + Timing.DELAY3
+  if playerSide then frames = frames + Timing.HP_BAR_HP_STEP end
+  return frames
+end
+
+-- Total cost of draining `fromHP` to `toHP`, for tests and for anything that
+-- needs to budget the whole animation up front.
+function Timing.hpDrainFrames(fromHP, toHP, maxHP, playerSide)
+  local total = 0
+  local hp = fromHP
+  local dir = (toHP < fromHP) and -1 or 1
+  while hp ~= toHP do
+    local nextHP = hp + dir
+    total = total + Timing.hpDrainStepFrames(hp, nextHP, maxHP, playerSide)
+    hp = nextHP
+  end
+  return total + Timing.hpDrainClosingFrames(playerSide)
+end
+
+return Timing

src/core/TouchControls.lua

@@ -12,12 +12,22 @@
 -- (main.lua then drives it with the mouse); POKEPORT_TOUCH=0 forces it
 -- off everywhere.
 --
+-- Player preferences (options.touchControls) can permanently disable the
+-- overlay and/or override per-control positions as normalized window
+-- fractions.  Positions and a size multiplier are stored per orientation
+-- (#633): options.touchControls.layouts.portrait / .landscape, picked from
+-- the safe rect's aspect, so laying the pad out in landscape never moves
+-- the portrait one.  The launcher editor (src/ui/TouchControlsEditor.lua)
+-- writes those; applyOptions reads them at boot and whenever options
+-- change.
+--
 -- Controls press GB buttons through Input:overlayPressed/Released -- their
 -- own input source, not a keyboard alias -- so a held overlay direction
 -- merges cleanly with a keyboard key or stick holding the same button,
 -- and a player rebind can never detach the overlay.
 
 local Input = require("src.core.Input")
+local SafeArea = require("src.core.SafeArea")
 
 local TouchControls = {}
 
@@ -39,6 +49,16 @@ local DPAD_DEAD = 0.16
 local SLOP = { a = 1.3, b = 1.3, start = 1.4, select = 1.4 }
 
 local BUTTONS = { "a", "b", "start", "select" }
+local CONTROLS = { "dpad", "a", "b", "start", "select" }
+
+-- Per-orientation layout buckets (#633).  Orientation comes from the safe
+-- rect, not the device: sw > sh is landscape, so a resized desktop window
+-- under POKEPORT_TOUCH exercises the same path a phone rotation does.
+local ORIENTATIONS = { "portrait", "landscape" }
+
+-- Control size multiplier bounds for the editor's -/+ (#633).  1.0 is the
+-- historical size, so an install that never touches it draws as before.
+local SCALE_MIN, SCALE_MAX, SCALE_STEP = 0.6, 1.6, 0.1
 
 local IMAGES = {
   dpad = "assets/touch/dpad.png",
@@ -52,6 +72,39 @@ local IMAGES = {
   select = "assets/touch/select.png",
 }
 
+local function clamp01(v)
+  if v < 0 then return 0 end
+  if v > 1 then return 1 end
+  return v
+end
+
+local function clampScale(v)
+  if type(v) ~= "number" or v ~= v then return 1 end
+  if v < SCALE_MIN then return SCALE_MIN end
+  if v > SCALE_MAX then return SCALE_MAX end
+  return v
+end
+
+-- Copy a persisted positions table, dropping unknown / non-numeric entries.
+-- Always a fresh table: two orientations seeded from the same pre-#633
+-- layout must not alias, or dragging one would still move the other.
+local function normalizePositions(src)
+  if type(src) ~= "table" then return nil end
+  local pos = {}
+  for _, name in ipairs(CONTROLS) do
+    local p = src[name]
+    if type(p) == "table" and type(p.x) == "number" and type(p.y) == "number" then
+      pos[name] = { x = clamp01(p.x), y = clamp01(p.y) }
+    end
+  end
+  if not next(pos) then return nil end
+  return pos
+end
+
+local function orientationFor(sw, sh)
+  return (sw or 0) > (sh or 0) and "landscape" or "portrait"
+end
+
 local function wantsOverlay()
   local env = os.getenv("POKEPORT_TOUCH")
   if env == "1" then return true end
@@ -60,8 +113,75 @@ local function wantsOverlay()
   return osName == "Android" or osName == "iOS"
 end
 
+-- Normalize a persisted touchControls table into
+-- {enabled, layouts = {portrait = {positions, scale}, landscape = {...}}}.
+-- Unknown / garbage keys are dropped so a bad options.lua cannot brick
+-- the overlay.  Pre-#633 files stored one top-level positions table and no
+-- scale; that layout seeds both orientations, so an upgrading player keeps
+-- what they had until they edit one of them.
+function TouchControls.normalizeConfig(tc)
+  local out = { enabled = true, layouts = { portrait = {}, landscape = {} } }
+  -- a nil / garbage table still yields full buckets (scale defaulted), so
+  -- no caller ever has to nil-check a bucket's scale
+  if type(tc) ~= "table" then tc = {} end
+  if tc.enabled == false then out.enabled = false end
+  local saved = type(tc.layouts) == "table" and tc.layouts or nil
+  for _, o in ipairs(ORIENTATIONS) do
+    local b = saved and saved[o]
+    if type(b) ~= "table" then b = { positions = tc.positions, scale = tc.scale } end
+    out.layouts[o] = {
+      positions = normalizePositions(b.positions),
+      scale = clampScale(b.scale),
+    }
+  end
+  return out
+end
+
+-- Pure default layout in LOVE units for a usable rect of size ww x wh at
+-- origin (ox, oy).  Shared by layout() and the editor's Reset path so
+-- defaults stay in one place.  ox/oy default to 0 for the headless tests
+-- and for callers that already pass a full-window size.  scale (#633) is
+-- the orientation's size multiplier: every width and the margin derive
+-- from dpadW, so scaling it moves the default centers with the art
+-- instead of letting bigger buttons hang off the edge.
+function TouchControls.defaultLayout(ww, wh, ox, oy, scale)
+  ox, oy = ox or 0, oy or 0
+  local short = math.min(ww, wh)
+  local dpadW = math.min(180, short * 0.34) * clampScale(scale)
+  local abW = dpadW * 0.46
+  local ssW = dpadW * 0.30
+  local margin = dpadW * 0.12
+  return {
+    dpad = { cx = ox + margin + dpadW / 2, cy = oy + wh - margin - dpadW / 2, w = dpadW },
+    a = { cx = ox + ww - margin - abW * 0.55, cy = oy + wh - margin - abW * 1.75, w = abW },
+    b = { cx = ox + ww - margin - abW * 1.60, cy = oy + wh - margin - abW * 0.55, w = abW },
+    start = { cx = ox + ww / 2 + ssW * 0.60, cy = oy + wh - margin - ssW * 0.95, w = ssW },
+    select = { cx = ox + ww / 2 - ssW * 0.60, cy = oy + wh - margin - ssW * 0.95, w = ssW },
+  }
+end
+
+local function loadImages()
+  local img = {}
+  for name, path in pairs(IMAGES) do
+    local ok, im = pcall(love.graphics.newImage, path)
+    if not ok then return nil end
+    im:setFilter("linear", "linear")
+    img[name] = im
+  end
+  return img
+end
+
 function TouchControls:init()
   self.active = wantsOverlay()
+  self.enabled = true
+  -- per-orientation buckets (#633); self.positions / self.scale mirror the
+  -- one currently on screen so layout(), the editor and the tests keep a
+  -- single lookup
+  self.layouts = { portrait = {}, landscape = {} }
+  self.orientation = nil
+  self.positions = nil
+  self.scale = 1
+  self.preview = false
   self.controllerHidden = false
   self.touches = {}
   -- per-GB-button owner count: two fingers on A must not double-press it,
@@ -70,51 +190,127 @@ function TouchControls:init()
   self.dpadTouch = nil
   self.layoutW, self.layoutH = nil, nil
   self.img = nil
-  if not self.active then return end
-  -- soft-fail: a missing/corrupt PNG must never block boot; the overlay
-  -- stays off and keyboard/controller play still works
-  local img = {}
-  for name, path in pairs(IMAGES) do
-    local ok, im = pcall(love.graphics.newImage, path)
-    if not ok then
-      img = nil
-      break
-    end
-    -- smooth UI icons; the global default filter is nearest for GB pixels
-    im:setFilter("linear", "linear")
-    img[name] = im
+  -- Images load whenever the platform wants the overlay OR the launcher
+  -- editor forces a preview (desktop testing of the editor).
+  if self.active then
+    self.img = loadImages()
+  end
+end
+
+-- Ensure art is loaded for the launcher editor even when wantsOverlay()
+-- is false (desktop without POKEPORT_TOUCH).
+function TouchControls:ensureImages()
+  if self.img then return true end
+  self.img = loadImages()
+  return self.img ~= nil
+end
+
+-- Apply options.touchControls.  Called from Game:applyOptions and from
+-- the launcher editor after a save.
+function TouchControls:applyOptions(opts)
+  local cfg = TouchControls.normalizeConfig(opts and opts.touchControls)
+  self.enabled = cfg.enabled
+  self.layouts = cfg.layouts
+  self.layoutW, self.layoutH = nil, nil
+  self.layoutOx, self.layoutOy = nil, nil
+  -- prime positions/scale for the orientation on screen so callers that
+  -- read them before the next layout() (editor chrome, tests) see the file
+  self:currentBucket()
+  if not self.enabled then
+    self.controllerHidden = false
+    self:reset()
+  end
+end
+
+-- Snapshot for the editor's save path: enabled plus both orientation
+-- buckets, matching what options.lua stores (#633).
+function TouchControls:config()
+  local out = { enabled = self.enabled ~= false, layouts = {} }
+  for _, o in ipairs(ORIENTATIONS) do
+    local b = self.layouts and self.layouts[o] or nil
+    out.layouts[o] = {
+      positions = b and b.positions or nil,
+      scale = clampScale(b and b.scale),
+    }
+  end
+  return out
+end
+
+-- Preview mode: force-draw the overlay for the layout editor, ignoring
+-- platform / enabled / gamepad gates.  Gameplay input still respects
+-- enabled via touchpressed.
+function TouchControls:setPreview(on)
+  self.preview = on and true or false
+  if on then
+    self:ensureImages()
+    self.controllerHidden = false
   end
-  self.img = img
 end
 
 function TouchControls:visible()
-  return self.active and self.img ~= nil and not self.controllerHidden
+  if self.preview then return self.img ~= nil end
+  return self.active and self.enabled ~= false and self.img ~= nil
+     and not self.controllerHidden
+end
+
+-- Keep a control fully inside the usable rect [x0,y0]..[x1,y1].
+local function clampZone(zone, x0, y0, x1, y1)
+  local half = zone.w * 0.5
+  zone.cx = math.max(x0 + half, math.min(x1 - half, zone.cx))
+  zone.cy = math.max(y0 + half, math.min(y1 - half, zone.cy))
+end
+
+-- The bucket for the orientation currently on screen (#633), created on
+-- demand.  Mirrors it into self.orientation / self.positions / self.scale,
+-- which layout(), the editor chrome and the tests read.
+function TouchControls:currentBucket()
+  local _, _, sw, sh = SafeArea.rect()
+  local o = orientationFor(sw, sh)
+  self.layouts = self.layouts or { portrait = {}, landscape = {} }
+  local b = self.layouts[o]
+  if type(b) ~= "table" then
+    b = {}
+    self.layouts[o] = b
+  end
+  b.scale = clampScale(b.scale)
+  self.orientation = o
+  self.positions = b.positions
+  self.scale = b.scale
+  return b
 end
 
 -- Layout in LOVE units (density-independent on mobile), recomputed when
--- the window size changes (rotation, resize).  D-pad bottom-left, B/A
--- bottom-right with A above B (the Game Boy diagonal), START/SELECT
--- flanking the bottom center.
+-- the window or safe area changes (rotation, resize, notch insets).
+-- Default: d-pad bottom-left, B/A bottom-right with A above B (the Game Boy
+-- diagonal), START/SELECT flanking the bottom center -- all inside the
+-- device safe area so thumbs clear the home indicator / cutouts.
+-- Custom positions (normalized 0..1 within the safe rect) override centers
+-- while sizes stay derived from the short edge, times the orientation's
+-- size setting (#633).
 function TouchControls:layout()
-  local ww, wh = love.graphics.getDimensions()
-  if self.layoutW == ww and self.layoutH == wh then return self.L end
-  self.layoutW, self.layoutH = ww, wh
-  local short = math.min(ww, wh)
-  -- ~a third of the short edge, capped so tablets don't get a dinner plate
-  local dpadW = math.min(180, short * 0.34)
-  local abW = dpadW * 0.46
-  local ssW = dpadW * 0.30
-  local margin = dpadW * 0.12
-  -- START/SELECT hug the bottom center: on a narrow portrait phone the
-  -- d-pad and B leave little room, so a tight pair is what keeps them off
-  -- the neighboring controls
-  self.L = {
-    dpad = { cx = margin + dpadW / 2, cy = wh - margin - dpadW / 2, w = dpadW },
-    a = { cx = ww - margin - abW * 0.55, cy = wh - margin - abW * 1.75, w = abW },
-    b = { cx = ww - margin - abW * 1.60, cy = wh - margin - abW * 0.55, w = abW },
-    start = { cx = ww / 2 + ssW * 0.60, cy = wh - margin - ssW * 0.95, w = ssW },
-    select = { cx = ww / 2 - ssW * 0.60, cy = wh - margin - ssW * 0.95, w = ssW },
-  }
+  local ox, oy, sw, sh = SafeArea.rect()
+  if self.layoutW == sw and self.layoutH == sh
+     and self.layoutOx == ox and self.layoutOy == oy and self.L then
+    return self.L
+  end
+  self.layoutW, self.layoutH = sw, sh
+  self.layoutOx, self.layoutOy = ox, oy
+  -- orientation picks which saved layout applies; rotating swaps buckets
+  -- because sw/sh swapped, which is already the cache key above (#633)
+  local bucket = self:currentBucket()
+  self.L = TouchControls.defaultLayout(sw, sh, ox, oy, bucket.scale)
+  if bucket.positions then
+    for _, name in ipairs(CONTROLS) do
+      local p = bucket.positions[name]
+      local zone = self.L[name]
+      if p and zone then
+        zone.cx = ox + p.x * sw
+        zone.cy = oy + p.y * sh
+        clampZone(zone, ox, oy, ox + sw, oy + sh)
+      end
+    end
+  end
+  local ssW = self.L.start.w
   local fontSize = math.max(8, math.floor(ssW * 0.26))
   if not self.labelFont or self.fontSize ~= fontSize then
     self.fontSize = fontSize
@@ -123,12 +319,75 @@ function TouchControls:layout()
   return self.L
 end
 
+-- Move one control to a screen-space point and persist its normalized
+-- position within the safe rect.  Used by the layout editor while dragging.
+function TouchControls:setControlCenter(name, cx, cy)
+  local ox, oy, sw, sh = SafeArea.rect()
+  local L = self:layout()
+  local zone = L[name]
+  if not zone then return end
+  zone.cx, zone.cy = cx, cy
+  clampZone(zone, ox, oy, ox + sw, oy + sh)
+  -- writes land in the orientation on screen only (#633)
+  local bucket = self:currentBucket()
+  bucket.positions = bucket.positions or {}
+  self.positions = bucket.positions
+  bucket.positions[name] = {
+    x = sw > 0 and (zone.cx - ox) / sw or 0,
+    y = sh > 0 and (zone.cy - oy) / sh or 0,
+  }
+end
+
+-- Editor Reset: defaults for the orientation on screen only (#633), so
+-- resetting landscape never throws away the portrait layout.
+function TouchControls:clearPositions()
+  local bucket = self:currentBucket()
+  bucket.positions = nil
+  bucket.scale = 1
+  self.positions = nil
+  self.scale = 1
+  self.layoutW, self.layoutH = nil, nil
+  self.layoutOx, self.layoutOy = nil, nil
+end
+
+-- Control size multiplier for the orientation on screen (#633).  Widths and
+-- the default centers both derive from it in defaultLayout; custom centers
+-- keep their normalized spot and re-clamp inside the safe rect on the next
+-- layout().
+function TouchControls:setScale(scale)
+  local bucket = self:currentBucket()
+  bucket.scale = clampScale(scale)
+  self.scale = bucket.scale
+  self.layoutW, self.layoutH = nil, nil
+  self.layoutOx, self.layoutOy = nil, nil
+  return self.scale
+end
+
+function TouchControls:nudgeScale(delta)
+  return self:setScale((self.scale or 1) + delta)
+end
+
 local function inCircle(zone, x, y, slop)
   local r = zone.w * 0.5 * slop
   local dx, dy = x - zone.cx, y - zone.cy
   return dx * dx + dy * dy <= r * r
 end
 
+-- Which control (if any) contains (x, y).  Prefer face buttons over the
+-- d-pad when they overlap, matching touchpressed's order.
+function TouchControls:hitTest(x, y)
+  local L = self:layout()
+  for _, btn in ipairs(BUTTONS) do
+    if inCircle(L[btn], x, y, SLOP[btn]) then return btn end
+  end
+  local dz = L.dpad
+  local half = dz.w * 0.65
+  if math.abs(x - dz.cx) <= half and math.abs(y - dz.cy) <= half then
+    return "dpad"
+  end
+  return nil
+end
+
 local function dpadDir(zone, x, y)
   local dx, dy = x - zone.cx, y - zone.cy
   local dead = zone.w * DPAD_DEAD
@@ -165,7 +424,9 @@ local function setDpad(self, touch, dir)
 end
 
 function TouchControls:touchpressed(id, x, y)
-  if not (self.active and self.img) then return end
+  -- preview mode is layout-edit only: never press GB buttons
+  if self.preview then return end
+  if not (self.active and self.enabled ~= false and self.img) then return end
   -- a controller hid the overlay; the first touch only brings it back
   if self.controllerHidden then
     self.controllerHidden = false
@@ -192,6 +453,7 @@ function TouchControls:touchpressed(id, x, y)
 end
 
 function TouchControls:touchmoved(id, x, y)
+  if self.preview then return end
   local touch = self.touches[id]
   -- only the d-pad tracks movement (slide between directions without
   -- lifting); buttons hold until release wherever the finger wanders
@@ -200,6 +462,7 @@ function TouchControls:touchmoved(id, x, y)
 end
 
 function TouchControls:touchreleased(id, x, y)
+  if self.preview then return end
   local touch = self.touches[id]
   if not touch then return end
   self.touches[id] = nil
@@ -216,7 +479,7 @@ end
 -- touchreleased and would strand its button held forever.  Called from
 -- Game alongside Input:reset() on focus/visibility loss.
 function TouchControls:reset()
-  for btn in pairs(self.held) do
+  for btn in pairs(self.held or {}) do
     Input:overlayReleased(btn)
   end
   self.held = {}
@@ -225,9 +488,13 @@ function TouchControls:reset()
 end
 
 -- a gamepad is being used: hide the overlay (dropping anything it held)
--- until the next screen touch asks for it back
+-- until the next screen touch asks for it back.  No-op when the player
+-- permanently disabled the overlay -- there is nothing to hide, and a
+-- later accidental touch must not resurrect it.
 function TouchControls:noteGamepad()
-  if not self.active or self.controllerHidden then return end
+  if not self.active or self.enabled == false or self.controllerHidden then
+    return
+  end
   self.controllerHidden = true
   self:reset()
 end
@@ -242,40 +509,46 @@ function TouchControls:joystickremoved()
   end
 end
 
-local function drawIcon(img, zone, pressed)
-  love.graphics.setColor(1, 1, 1, pressed and BACK_PRESSED or BACK)
+local function drawIcon(img, zone, pressed, alphaMul)
+  alphaMul = alphaMul or 1
+  love.graphics.setColor(1, 1, 1, (pressed and BACK_PRESSED or BACK) * alphaMul)
   love.graphics.circle("fill", zone.cx, zone.cy, zone.w * 0.58)
   local scale = zone.w / img:getWidth()
-  love.graphics.setColor(1, 1, 1, pressed and ALPHA_PRESSED or ALPHA)
+  love.graphics.setColor(1, 1, 1, (pressed and ALPHA_PRESSED or ALPHA) * alphaMul)
   love.graphics.draw(img, zone.cx - zone.w / 2,
                      zone.cy - img:getHeight() * scale / 2, 0, scale, scale)
 end
 
 -- Screen-space, called by Game:draw after Renderer:endFrame so the
 -- overlay rides on top of everything (world, UI, CRT/GBC FX included).
+-- Also used by the launcher layout editor under preview mode.
 function TouchControls:draw()
   if not self:visible() then return end
   local L = self:layout()
+  -- when the player disabled the overlay but the editor is previewing,
+  -- draw dimmed so the layout is still editable
+  local alphaMul = (self.preview and self.enabled == false) and 0.45 or 1
   love.graphics.push("all")
   love.graphics.origin()
 
   local dpadTouch = self.dpadTouch and self.touches[self.dpadTouch]
   local dir = dpadTouch and dpadTouch.dir
   drawIcon(dir and self.img["dpad_" .. dir] or self.img.dpad, L.dpad,
-           dir ~= nil)
+           dir ~= nil, alphaMul)
   for _, btn in ipairs(BUTTONS) do
-    drawIcon(self.img[btn], L[btn], self.held[btn] ~= nil)
+    drawIcon(self.img[btn], L[btn], self.held[btn] ~= nil, alphaMul)
   end
 
   -- the +/- glyphs alone don't say which is which; shadowed so the text
-  -- reads on both the black letterbox and battle's white one
+  -- reads on both the black letterbox and battle's white one.  Each label
+  -- tracks its own control's cy/w so dragging START cannot move SELECT.
   love.graphics.setFont(self.labelFont)
-  local ly = L.start.cy + L.start.w * 0.66
   local function label(text, zone)
+    local ly = zone.cy + zone.w * 0.66
     local w = self.labelFont:getWidth(text)
-    love.graphics.setColor(0, 0, 0, 0.6)
+    love.graphics.setColor(0, 0, 0, 0.6 * alphaMul)
     love.graphics.print(text, zone.cx - w / 2 + 1, ly + 1)
-    love.graphics.setColor(1, 1, 1, ALPHA + 0.2)
+    love.graphics.setColor(1, 1, 1, (ALPHA + 0.2) * alphaMul)
     love.graphics.print(text, zone.cx - w / 2, ly)
   end
   label("START", L.start)
@@ -284,4 +557,9 @@ function TouchControls:draw()
   love.graphics.pop()
 end
 
+TouchControls.CONTROLS = CONTROLS
+TouchControls.ORIENTATIONS = ORIENTATIONS
+TouchControls.SCALE_MIN, TouchControls.SCALE_MAX = SCALE_MIN, SCALE_MAX
+TouchControls.SCALE_STEP = SCALE_STEP
+
 return TouchControls

src/dev/Console.lua

@@ -214,7 +214,7 @@ function VERBS.give(self, rest)
     end
   elseif game.data.items and game.data.items[id] then
     local n = tonumber(count) or 1
-    if require("src.inventory.Bag").add(save, id, n) then
+    if require("src.inventory.Bag").add(save, id, n, game.data) then
       self:print(("%s x%d added"):format(id, n))
     else
       self:print("bag full")

src/import/RomExtractor.lua

@@ -495,6 +495,25 @@ function RomExtractor:extractSprites()
     image = "assets/generated/sprites/red_bike.png",
     frames = bikeFrames, walker = bikeFrames >= 6,
   }
+  -- Yellow-only: the surfing-Pikachu overworld sheet, loaded outside
+  -- SpriteSheetPointerTable (LoadSurfingPlayerSpriteGraphics2) -- same
+  -- extra-extract shape as RedBikeSprite. (RFC 0001)
+  local surfPika = self.manifest.sprites.surfPikachu
+  if surfPika and self.symbols[surfPika.label] then
+    local spSymbol = self:symbol(surfPika.label)
+    self:write2bpp(
+      self.rom:bytes(spSymbol.bank, spSymbol.address,
+        surfPika.imageWidth * surfPika.imageHeight / 4),
+      surfPika.imageWidth, surfPika.imageHeight,
+      "sprites/" .. surfPika.imageBase .. ".png", true)
+    local spFrames = surfPika.imageHeight / 16
+    out.SPRITE_SURFING_PIKACHU = {
+      id = "SPRITE_SURFING_PIKACHU",
+      source = ("ROM:%s"):format(surfPika.label),
+      image = "assets/generated/sprites/" .. surfPika.imageBase .. ".png",
+      frames = spFrames, walker = spFrames >= 6,
+    }
+  end
   self:write("sprites", out)
   self:tick("Overworld sprites", #order + 1, #order + 1)
   return out
@@ -1179,6 +1198,13 @@ function RomExtractor:extractPokemon()
     completed = completed + 1
     self:tick("Pokemon", completed, #self.manifest.dexOrder + 10)
   end
+  -- Yellow-only third back pic: LoadPlayerBackPic (engine/battle/core.asm)
+  -- picks OldManPicBack for BATTLE_TYPE_OLD_MAN but ProfOakPicBack for
+  -- BATTLE_TYPE_PIKACHU, the Pallet Town catch scene (#557).  Outside the
+  -- ticked loop so the progress denominator stays as it was.
+  if self.symbols["ProfOakPicBack"] then
+    self:writeCompressedPic("ProfOakPicBack", "battle/profoakb.png")
+  end
   local balls = self:symbol("PokeballTileGraphics")
   self:write2bpp(self.rom:bytes(balls.bank, balls.address, 64),
     32, 8, "battle/balls.png", true)
@@ -1826,6 +1852,35 @@ function RomExtractor:extractField()
     end
   end
 
+  -- Yellow-only: TalkToPikachu's framed portrait, one 5x5 base frame per
+  -- PikaPicAnimScript -- each script's FIRST pikapic_loadgfx in
+  -- data/pikachu/pikachu_pic_animation.asm, the pic PikaPicAnimBGFrames_4
+  -- (PikaAnimTilemap_1, column order) paints.  Scripts 18/22/23/24 have no
+  -- compressed base and take PikaPicAnimBGFrames_5 -> PikaAnimTilemap_9,
+  -- which is ROW order over a raw 25-tile sheet, hence no columns flag.
+  -- Script 26 shares script 11's base.  The pikaframe overlays each script
+  -- draws ON TOP of the base are a second full pose out of the same blob and
+  -- stay unripped: PikachuFollower.picLift stands in for their motion
+  -- (#561, still on #407's stand-in).
+  local PIKAPIC_BASE = {
+    "Pic_e4000", "Pic_e411c", "Pic_e4272", "Pic_e4383", "Pic_e458b",
+    "Pic_e467b", "Pic_e476e", "Pic_e49d1", "Pic_e4b39", "Pic_e4c3e",
+    "Pic_e5000", "Pic_e523f", "Pic_e548e", "Pic_e56d1", "Pic_e5924",
+    "Pic_e5b7d", "Pic_e5ddd", "GFX_e6020", "Pic_e6340", "Pic_e6587",
+    "Pic_e67d6", "GFX_e6e6f", "GFX_e718f", "GFX_e74af", "Pic_e77cf",
+    "Pic_e5000", "Pic_f0abf", "Pic_f0cf4",
+  }
+  if self.symbols[PIKAPIC_BASE[1]] then
+    for script, label in ipairs(PIKAPIC_BASE) do
+      local path = "pikachu/pikapic_" .. script .. ".png"
+      if label:sub(1, 4) == "GFX_" then
+        self:raw2bpp(label, 40, 40, path, { matte = true })
+      else
+        self:writeCompressedPic(label, path)
+      end
+    end
+  end
+
   self:raw1bpp("LedgeHoppingShadow", 8, 8,
     "fx/shadow.png", true); tick()
   for _, spec in ipairs({

src/inventory/Bag.lua

@@ -1,11 +1,26 @@
--- The 20-slot bag (BAG_ITEM_CAPACITY, constants/menu_constants.asm):
--- a distinct item id occupies one slot regardless of quantity; badges
--- live in the inventory table but are not bag items.  save.bagOrder
--- keeps acquisition order like wBagItems (SELECT can reorder it).
+-- The bag defaults to 20 slots (BAG_ITEM_CAPACITY,
+-- constants/menu_constants.asm), but mods may replace that limit through
+-- Data.constants.bagSize.  A distinct item id occupies one slot regardless
+-- of quantity; badges live in the inventory table but are not bag items.
+-- save.bagOrder keeps acquisition order like wBagItems (SELECT can reorder
+-- it).
 
 local Bag = {}
 
-Bag.CAPACITY = 20
+local DEFAULT_CAPACITY = 20
+
+-- `data` is injectable for the save editor and headless mod tests.  Normal
+-- gameplay may omit it because the loader merges mods into the Data
+-- singleton before any item can be added.  The fallback keeps old/stale
+-- generated caches and isolated callers at the vanilla limit.
+function Bag.capacity(data)
+  data = data or require("src.core.Data")
+  local configured = data and data.constants and data.constants.bagSize
+  if type(configured) == "number" and configured >= 1 then
+    return math.floor(configured)
+  end
+  return DEFAULT_CAPACITY
+end
 
 local function isBadge(id)
   return id:find("BADGE", 1, true) ~= nil
@@ -55,9 +70,10 @@ end
 -- Add qty of an item; returns false (and adds nothing) when a new slot
 -- is needed and the bag is full, or when the stack would pass 99
 -- (AddItemToInventory's per-slot quantity cap).
-function Bag.add(save, id, qty)
+function Bag.add(save, id, qty, data)
   local inv = save.inventory
-  if not inv[id] and not isBadge(id) and Bag.slots(save) >= Bag.CAPACITY then
+  if not inv[id] and not isBadge(id)
+      and Bag.slots(save) >= Bag.capacity(data) then
     return false
   end
   if not isBadge(id) and (inv[id] or 0) + (qty or 1) > 99 then

src/inventory/ItemEffects.lua

@@ -10,7 +10,6 @@
 --   "ball"                          caller must throw it (battle only)
 --   "learn", moveId                 caller must run the learn-move flow
 
-local Pokemon = require("src.pokemon.Pokemon")
 local Flags = require("src.script.Flags")
 local Strings = require("src.core.Strings")
 
@@ -325,6 +324,11 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
     require("src.core.Sound").play(data, "Heal_HP")
     -- a revive takes the same .healHP -> .doneHealing route, animating up
     -- from the fainted mon's 0 HP (#252)
+    -- re-add to participants so the revived mon gets its share of exp
+    -- at battle end (onFaint clears the flag; revive must restore it)
+    if battle and battle.participants then
+      battle.participants[target] = true
+    end
     return "consumed", { Strings("%s\nis revitalized!", monName(data, target)) },
            { healedFrom = 0 }
   end
@@ -433,6 +437,13 @@ function ItemEffects.use(data, save, itemId, target, battle, moveIndex, ow)
     if battle then
       return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
     end
+    -- FishingInit (engine/items/item_effects.asm): cp wWalkBikeSurfState, 2
+    -- (surfing) sets carry, and every ItemUseXRod does jp c, ItemUseNotTime
+    -- on that carry -- surfing refuses the rod with the same OAK text as
+    -- the mid-battle case above, no rod-specific message (#533)
+    if ow and ow.player and ow.player.surfing then
+      return "failed", { Strings("OAK: %s!\nThis isn't the\ntime to use that!", save.player.name) }
+    end
     return "fish", itemId
   end
 

src/link/Fingerprint.lua

@@ -128,7 +128,14 @@ end
 
 -- ------- the link surface
 
-local SPECIES_FIELDS = { "baseStats", "types", "catchRate", "baseExp",
+-- catchRate stays out (#511): no link mode ever reads it -- a ball thrown
+-- in a link battle is a trainer-battle throw and always refused (pokered
+-- engine/items/item_effects.asm ItemUseBall), and the trade rebuild never
+-- touches it.  Hashing it split Red/Blue from Yellow, whose only link
+-- surface delta is the Dragonair/Dragonite catch-rate bytes
+-- (data/pokemon/base_stats/dragonair.asm db 45 vs 27, dragonite.asm 45
+-- vs 9), when the real cable links R/B/Y freely.
+local SPECIES_FIELDS = { "baseStats", "types", "baseExp",
                          "growthRate", "evolutions" }
 local MOVE_FIELDS = { "power", "type", "accuracy", "pp", "effect", "category",
                       "priority", "highCrit", "fixedDamage", "multiHit",

src/link/Handshake.lua

@@ -40,7 +40,8 @@ function Handshake.mods(game)
   if not ok or not status then return mods end
   for _, manifest in ipairs(status.loaded or {}) do
     mods[#mods + 1] = { id = manifest.id, version = manifest.version,
-                        affectsLink = manifest.affects_link ~= false }
+                        affectsLink = manifest.affects_link ~= false,
+                        language = manifest.language == true }
   end
   table.sort(mods, function(a, b) return tostring(a.id) < tostring(b.id) end)
   return mods
@@ -67,15 +68,82 @@ function Handshake.linkModified(game)
   return false
 end
 
+-- #501: the registries a declared translation may write, and nothing else.
+-- `text` is the ROM's dialogue, `strings` the engine's own authored text
+-- (src/mods/Schemas.lua R.text / R.strings) and `font` the glyphs a
+-- language with accents needs.  None of the three is hashed into the
+-- fingerprint (src/link/Fingerprint.lua header), so two peers reading the
+-- same game in different languages stay in lockstep -- which is also what
+-- the cable did: TradeCenter_PrintPartyListNames (pokered
+-- engine/link/cable_club.asm) names the peer's party out of the local
+-- ROM's table, only the trainer name and the party bytes travel.
+-- text_pointers is deliberately out: its rows carry mart inventories and
+-- nurse/pc flags, which are gameplay, not language.
+local LANGUAGE_REGISTRIES = { text = true, strings = true, font = true }
+
+Handshake.LANGUAGE_REGISTRIES = LANGUAGE_REGISTRIES
+
+-- The manifest's `language = true` is the author's claim; this is the
+-- check.  A mod counts as a translation only if every op it appended
+-- landed in a language registry, it subscribed no code (a hook or listener
+-- runs inside the battle the two peers are lockstepping) and it asked for
+-- no permission.  Online play meets strangers, so nothing here may rest on
+-- the manifest alone.  A patched client can still lie about its own mods --
+-- the fingerprint, not this, is what keeps the shared simulation honest;
+-- this gate is what keeps an honest install from being told to turn its
+-- language off.
+local function translationOnly(mod, id)
+  local record = mod.mods and mod.mods[id]
+  local manifest = record and record.manifest
+  if manifest and #(manifest.permissions or {}) > 0 then return false end
+  for name, registry in pairs(mod.content or {}) do
+    if not LANGUAGE_REGISTRIES[name] then
+      for _, list in pairs(registry.ops or {}) do
+        for _, entry in ipairs(list) do
+          if entry.owner == id then return false end
+        end
+      end
+    end
+  end
+  for _, chain in pairs((mod.hooks and mod.hooks.chains) or {}) do
+    for _, entry in ipairs(chain) do
+      if entry.owner == id then return false end
+    end
+  end
+  for _, list in pairs((mod.events and mod.events.listeners) or {}) do
+    for _, entry in ipairs(list) do
+      if entry.owner == id then return false end
+    end
+  end
+  return true
+end
+
+-- the enabled mods that keep this install out of online play, in the
+-- id order Handshake.mods sorts: everything except verified translations.
+-- LinkState:offerVanillaRestart names these and switches off exactly these.
+function Handshake.onlineBlockers(game)
+  local mod = loader(game)
+  local blockers = {}
+  for _, entry in ipairs(Handshake.mods(game)) do
+    local allowed = entry.language and not entry.affectsLink
+      and mod ~= nil and translationOnly(mod, entry.id)
+    if not allowed then blockers[#blockers + 1] = entry end
+  end
+  return blockers
+end
+
 -- online play (the relay-based online match / tournament flows in
 -- LinkState/Tournament) meets strangers, not a coordinating friend, so it
 -- skips the LAN path's per-peer compatibility negotiation entirely and
--- just requires vanilla on both ends: no mod-added Pokemon, no surprises.
--- Mods only ever get baked in at boot (Loader:load), so this is a gate on
--- attempting to go online, not a live mod toggle -- the player disables
--- mods via the mod manager and relaunches.
+-- just requires a vanilla simulation on both ends: no mod-added Pokemon, no
+-- surprises.  #501 carves out translations, because a language is not a
+-- simulation: a mod that only rewrites text is invisible to the wire and
+-- may stay on, so an English player and a Spanish one can meet the way two
+-- regional carts always could.  Mods only ever get baked in at boot
+-- (Loader:load), so this is a gate on attempting to go online, not a live
+-- mod toggle -- the player disables mods via the mod manager and relaunches.
 function Handshake.onlineAllowed(game)
-  return #Handshake.mods(game) == 0
+  return #Handshake.onlineBlockers(game) == 0
 end
 
 -- mode is nil on the guest: it pairs and announces itself before the host

src/link/LinkState.lua

@@ -110,17 +110,19 @@ function LinkState:exitWith(message, reason)
   end
 end
 
--- Online play meets strangers, so it requires vanilla on both ends
--- (Handshake.onlineAllowed).  Mods merge into the shared Data registries at
--- boot and there is no unmerge, so switching them off has to go through a
--- relaunch -- but the player should not have to go find the mod manager and
--- work out which mods count.  This turns every enabled mod off, records
--- them so the mod manager can put them back, and relaunches.  The restart
+-- Online play meets strangers, so it requires a vanilla simulation on both
+-- ends (Handshake.onlineAllowed).  Mods merge into the shared Data
+-- registries at boot and there is no unmerge, so switching them off has to
+-- go through a relaunch -- but the player should not have to go find the
+-- mod manager and work out which mods count.  This turns the blocking mods
+-- off, records them so the mod manager can put them back, and relaunches.
+-- Verified translations are not blockers (#501), so a player keeps their
+-- language across the restart and only the gameplay mods go.  The restart
 -- is confirmed rather than silent: it drops unsaved progress.
 function LinkState:offerVanillaRestart()
   local game = self.game
   local loader = game.mods
-  local mods = Handshake.mods(game)
+  local mods = Handshake.onlineBlockers(game)
   local names = {}
   for i, mod in ipairs(mods) do
     if i > 2 then break end

src/link/Protocol.lua

@@ -178,19 +178,16 @@ end
 
 -- ------- subset negotiation
 
--- the species and moves this party actually references, so the exchange
--- stays small (six mons) instead of shipping the whole catalog
+-- every record hash, not just this party's slice: the receiver filters
+-- its OWN party against these (eligibleParty), so a message limited to the
+-- sender's party read "not on the other game" for every species the two
+-- parties did not happen to share, and a subset trade between different
+-- games showed neither side (#511).  The full catalog is ~300 short hash
+-- strings -- still one message.
 function Protocol.recordsMessage(data, party)
-  local species = Fingerprint.records(data, "pokemon")
-  local moves = Fingerprint.records(data, "moves")
-  local outSpecies, outMoves = {}, {}
-  for _, mon in ipairs(party or {}) do
-    if species[mon.species] then outSpecies[mon.species] = species[mon.species] end
-    for _, mv in ipairs(mon.moves or {}) do
-      if moves[mv.id] then outMoves[mv.id] = moves[mv.id] end
-    end
-  end
-  return { type = "records", pokemon = outSpecies, moves = outMoves }
+  return { type = "records",
+           pokemon = Fingerprint.records(data, "pokemon"),
+           moves = Fingerprint.records(data, "moves") }
 end
 
 -- a mon may cross the wire only if both peers rebuild it identically: the

src/link/Tournament.lua

@@ -384,9 +384,16 @@ function Tournament:update(dt)
         else
           self.pendingBattleOpts.seed = msg.seed
         end
-        local battle, why = self.isHost
-          and LinkBattle.newHost(self.game, self.net, self.pendingBattleOpts)
-          or LinkBattle.newGuest(self.game, self.net, self.pendingBattleOpts)
+        -- Split rather than `cond and newHost() or newGuest()`: the and/or
+        -- idiom truncates a call to its first result, so the second return
+        -- (the specific reason) was always dropped and every failure showed
+        -- the generic fallback instead of "same mods on both games" etc.
+        local battle, why
+        if self.isHost then
+          battle, why = LinkBattle.newHost(self.game, self.net, self.pendingBattleOpts)
+        else
+          battle, why = LinkBattle.newGuest(self.game, self.net, self.pendingBattleOpts)
+        end
         if not battle then
           self:exitWith(why or Strings("Link battle\ncan't start."))
           return

src/mods/LauncherMods.lua

@@ -95,8 +95,15 @@ function LauncherMods.deriveList(manifests, options)
   local byId, enabledSet = {}, {}
   for _, m in ipairs(ordered) do
     byId[m.id] = m
-    -- missing entry means enabled, matching the loader's default
-    if mods[m.id] ~= false then enabledSet[m.id] = true end
+    -- missing entry means enabled, matching the loader -- except experimental
+    -- mods, which stay off until the player opts in
+    if mods[m.id] == false then
+      -- stay off
+    elseif mods[m.id] == true then
+      enabledSet[m.id] = true
+    elseif not m.experimental then
+      enabledSet[m.id] = true
+    end
   end
 
   local out = {}
@@ -104,16 +111,19 @@ function LauncherMods.deriveList(manifests, options)
     local enabled = enabledSet[m.id] == true
     local status, detail = statusFor(byId, m.id, enabledSet, enabled)
     local raw = m.raw or {}
+    local badge = tostring(raw.category or m.profile or "MOD"):upper()
+    if m.experimental then badge = "EXPERIMENTAL" end
     out[#out + 1] = {
       id = m.id,
       name = m.name or m.id,
       version = m.version,
-      -- category, then profile, then a generic fallback -- uppercased
-      badge = tostring(raw.category or m.profile or "MOD"):upper(),
+      badge = badge,
       description = m.description or "",
       enabled = enabled,
       status = status,
       statusDetail = detail,
+      github = m.github,
+      experimental = m.experimental == true,
     }
   end
   return out
@@ -213,7 +223,9 @@ local function discover()
   for _, name in ipairs(fs.getDirectoryItems("mods")) do
     local path = "mods/" .. name
     local info = fs.getInfo(path)
-    if info and info.type == "directory" then
+    -- a dev-linked mod dir (ln -s) reports type "symlink" even with
+    -- setSymlinksEnabled(true); see the matching note in Loader:_discover.
+    if info and (info.type == "directory" or info.type == "symlink") then
       local raw = fs.read(path .. "/manifest.json")
       if raw then
         local manifest = decodeManifest(raw, path)
@@ -231,8 +243,15 @@ end
 -- options.mods enable-state the loader persists, so a toggle here is what the
 -- game sees on its next boot.
 function LauncherMods.list()
-  local options = SaveData.loadOptions()
-  return LauncherMods.deriveList(discover(), options)
+  local ok, result = pcall(function()
+    local options = SaveData.loadOptions()
+    return LauncherMods.deriveList(discover(), options)
+  end)
+  if not ok then
+    -- a single bad options/mod file must not blank the launcher
+    return {}
+  end
+  return result or {}
 end
 
 -- setEnabled(id, enabled): persist options.mods[id] in the exact shape
@@ -246,6 +265,21 @@ function LauncherMods.setEnabled(id, enabled)
   return true
 end
 
+-- setAllEnabled(ids, enabled): the launcher's Enable all / Disable all buttons
+-- (#647).  Writes exactly the options.mods shape setEnabled does, but loads and
+-- saves once for the whole list: saveOptions rewrites the whole options file per
+-- call, so looping setEnabled over a big mods folder is one disk write per mod
+-- and leaves a half-applied state behind if one of them fails.
+function LauncherMods.setAllEnabled(ids, enabled)
+  local options = SaveData.loadOptions()
+  options.mods = options.mods or {}
+  for _, id in ipairs(ids or {}) do
+    options.mods[id] = enabled and true or false
+  end
+  SaveData.saveOptions(options)
+  return true
+end
+
 -- ------- install (love.filesystem)
 
 -- Read a .zip source into bytes.  A string is an external absolute path (like
@@ -454,13 +488,22 @@ function LauncherMods.strays() return scanStrays(false) end
 -- on the player's behalf is not this function's call to make.
 function LauncherMods.adoptStrays() return scanStrays(true) end
 
--- installZip(source) -> true, id  |  nil, errString
+-- installZip(source [, opts]) -> true, id  |  nil, errString
 -- source is an external path or a love DroppedFile.  The archive is validated
 -- BEFORE anything is copied; every path unmounts and clears the staged temp
 -- file, and a failed copy rolls its partial tree back.  A dropped file outside
 -- the save dir is staged into a save-dir temp first, because
 -- love.filesystem.mount only reaches a save-directory-relative path.
-function LauncherMods.installZip(source)
+-- opts.replace = true uninstalls an existing same-id mod first (updates /
+-- rollbacks).  opts.expectId, when set, refuses a zip whose manifest id differs.
+function LauncherMods.installZip(source, opts)
+  local ok, result, err = pcall(LauncherMods._installZipInner, source, opts)
+  if not ok then return nil, "import failed: " .. tostring(result) end
+  return result, err
+end
+
+function LauncherMods._installZipInner(source, opts)
+  opts = opts or {}
   if not (love and love.filesystem) then
     return nil, "mod install needs LOVE"
   end
@@ -501,12 +544,24 @@ function LauncherMods.installZip(source)
     cleanup()
     return nil, "invalid mod manifest: " .. tostring(manifestErr)
   end
+  if opts.expectId and manifest.id ~= opts.expectId then
+    cleanup()
+    return nil, ("zip is for '%s', expected '%s'")
+      :format(manifest.id, opts.expectId)
+  end
 
-  -- reject a duplicate before touching the mods tree
   local dest = "mods/" .. manifest.id
   if fs.getInfo(dest) then
-    cleanup()
-    return nil, "a mod named '" .. manifest.id .. "' is already installed"
+    if not opts.replace then
+      cleanup()
+      return nil, "a mod named '" .. manifest.id .. "' is already installed"
+    end
+    -- drop the old tree before copy; enable-flag is preserved (uninstall
+    -- would clear it, which would surprise an update)
+    local savedPrefix = CacheFs.prefix
+    CacheFs.prefix = ""
+    removeTree(dest)
+    CacheFs.prefix = savedPrefix
   end
 
   -- CacheFs.prefix steers ROM-cache writes into a version subtree (blue/...);
@@ -529,6 +584,56 @@ function LauncherMods.installZip(source)
   return true, manifest.id
 end
 
+-- Install (or replace) a mod from a GitHub release zip URL.
+-- Returns true, version  |  nil, errString. Soft-fails: download / install /
+-- cleanup errors never throw into the launcher UI.
+function LauncherMods.installFromRelease(modId, release)
+  local ok, result, err = pcall(function()
+    if type(modId) ~= "string" or modId == "" then
+      return nil, "missing mod id"
+    end
+    if type(release) ~= "table" or not release.zip or not release.zip.url then
+      return nil, "release has no downloadable .zip"
+    end
+    local ModUpdate = require("src.mods.ModUpdate")
+    local tmpName = ("mod_update_%s_%s.zip"):format(
+      tostring(modId), tostring(release.version or os.time()))
+    local localPath, dlErr = ModUpdate.downloadZip(release.zip.url, tmpName)
+    if not localPath then return nil, dlErr end
+    local installed, res = LauncherMods.installZip(localPath, {
+      replace = true, expectId = modId,
+    })
+    pcall(love.filesystem.remove, localPath)
+    if not installed then return nil, res end
+    return true, release.version or res
+  end)
+  if not ok then return nil, "install failed: " .. tostring(result) end
+  return result, err
+end
+
+-- Install a mod listed in a community index (src/mods/ModIndex.lua).
+-- The index only ever tells us WHERE the zip is; resolving that URL is
+-- ModIndex's job and installing it is installFromRelease's, so this is the
+-- seam between them and nothing about the archive is special-cased.  expectId
+-- comes from the listing, so a feed that points an entry at somebody else's
+-- zip fails the manifest check instead of installing the wrong mod.
+-- Returns true, version | nil, errString.
+function LauncherMods.installFromIndex(entry)
+  local ok, result, err = pcall(function()
+    if type(entry) ~= "table" or type(entry.id) ~= "string" then
+      return nil, "index entry has no mod id"
+    end
+    local ModIndex = require("src.mods.ModIndex")
+    local release, why = ModIndex.releaseFor(entry)
+    if not release then
+      return nil, why or "this mod cannot be installed from the index"
+    end
+    return LauncherMods.installFromRelease(entry.id, release)
+  end)
+  if not ok then return nil, "install failed: " .. tostring(result) end
+  return result, err
+end
+
 -- uninstall(id) -> true  |  nil, errString
 -- Removes mods/<id>/ from wherever it was installed (the portable game folder
 -- or the save directory, CacheFs decides -- #330) and clears options.mods[id]

src/mods/Loader.lua

@@ -206,7 +206,11 @@ function Loader:_discover()
       for _, name in ipairs(self.fs.getDirectoryItems(root)) do
         local path = root .. "/" .. name
         local info = self.fs.getInfo(path)
-        if info and info.type == "directory" then
+        -- a dev-linked mod dir (ln -s) reports type "symlink" even with
+        -- setSymlinksEnabled(true) -- PhysFS never resolves the symlink's
+        -- own getInfo, only traversal into it. readManifest below still
+        -- correctly no-ops on a symlink that isn't a directory.
+        if info and (info.type == "directory" or info.type == "symlink") then
           local manifest, err = readManifest(self.fs, path)
           if manifest then
             if self.mods[manifest.id] then
@@ -834,6 +838,18 @@ function Loader:load(data)
   require("src.mods.Builtins").install(self.content, data)
   self:_loadState()
   self:_discover()
+  -- Experimental mods stay off until the player opts in: a missing
+  -- options.mods entry normally means enabled, but experimental flips that.
+  do
+    local options = SaveData.loadOptions(self.fs)
+    local modsOpt = options.mods or {}
+    for id, mod in pairs(self.mods) do
+      if not self.disabled[id] and modsOpt[id] == nil
+          and mod.manifest.experimental then
+        self.disabled[id] = true
+      end
+    end
+  end
   for id, mod in pairs(self.mods) do
     mod.enabled = not self.disabled[id]
     mod.state = mod.enabled and "pending" or "disabled"

src/mods/ManagerState.lua

@@ -11,6 +11,7 @@ local Version = require("src.core.Version")
 local Theme = require("src.ui.Theme")
 local OptionRows = require("src.ui.OptionRows")
 local Strings = require("src.core.Strings")
+local ModProfile = require("src.mods.ModProfile")
 
 local ManagerState = {}
 ManagerState.__index = ManagerState
@@ -180,6 +181,16 @@ end
 
 function ManagerState:enter()
   self:refresh()
+  -- #593: the setup that existed before profiles shipped becomes PROFILE 1
+  -- the first time the manager opens, so switching away from it is always a
+  -- round trip.  Seeded here rather than at boot because profiles are only
+  -- ever read on this screen.
+  local seeded = ModProfile.ensureFirst(self:optionsTable(),
+    self.status.available, self:modOptionsTable())
+  if seeded then
+    self:persistOptions()
+    self:refresh()
+  end
   if Runtime.safeMode then
     self.banner = "SAFE MODE - ALL MODS OFF"
   end
@@ -213,6 +224,12 @@ function ManagerState:optionsTable()
   return (save and save.options) or {}
 end
 
+-- Per-mod option values as persisted (options.modOptions; setOption below is
+-- the only writer).  A profile captures this alongside the enable set.
+function ManagerState:modOptionsTable()
+  return self:optionsTable().modOptions or {}
+end
+
 function ManagerState:manifestMap()
   return self.byId or {}
 end
@@ -283,6 +300,10 @@ function ManagerState:profileRows()
       glyph = opts.activeProfile == p.name and GLYPH.errored or " " }
   end
   rows[#rows + 1] = { saveAs = true, label = Strings("SAVE CURRENT AS..") }
+  -- #593 sharing: EXPORT writes the focused profile to profiles/*.g1rmodlist
+  -- in the save dir, IMPORT reads back every file dropped in that folder.
+  rows[#rows + 1] = { exportProfile = true, label = Strings("EXPORT..") }
+  rows[#rows + 1] = { importProfile = true, label = Strings("IMPORT..") }
   rows[#rows + 1] = { adhoc = true,
     label = opts.activeProfile and "[AD-HOC]" or "[AD-HOC] (LIVE)" }
   return rows
@@ -324,6 +345,12 @@ function ManagerState:detailRows(m)
     rows[#rows + 1] = { label = Strings("PERMISSIONS.."),
       action = function() self:goTo("permissions") end }
   end
+  if m.github then
+    rows[#rows + 1] = { inert = true, label = "GH " .. m.github }
+  end
+  if m.experimental then
+    rows[#rows + 1] = { inert = true, label = "EXPERIMENTAL" }
+  end
   if m.error then
     rows[#rows + 1] = { label = Strings("VIEW ERROR.."),
       action = function() self:goTo("errors") end }
@@ -472,6 +499,10 @@ function ManagerState:activate()
     self:applyProfile(row.profile)
   elseif row.saveAs then
     self:saveCurrentAs()
+  elseif row.exportProfile then
+    self:exportActiveProfile()
+  elseif row.importProfile then
+    self:importProfiles()
   elseif row.adhoc then
     self:optionsTable().activeProfile = nil
     self:notify("AD-HOC SET ACTIVE")
@@ -607,13 +638,26 @@ function ManagerState:beginToggle(m)
     r = ManagerState.resolveToggle(self:manifestMap(), m.id, want,
                                    self:enabledSet())
   end
-  if #r.missing > 0 or #r.conflicts > 0 or #r.badVersion > 0 then
-    self:openBlocked(r)
-  elseif #r.alsoEnable > 0 or #r.alsoDisable > 0 then
-    self:openCascade(r, m, want)
-  else
-    self:commitToggle(r.apply)
+  local function proceed()
+    if #r.missing > 0 or #r.conflicts > 0 or #r.badVersion > 0 then
+      self:openBlocked(r)
+    elseif #r.alsoEnable > 0 or #r.alsoDisable > 0 then
+      self:openCascade(r, m, want)
+    else
+      self:commitToggle(r.apply)
+    end
   end
+  -- Experimental mods ask once on enable; disable is silent.
+  if want and m.experimental then
+    self:openConfirm({
+      "EXPERIMENTAL MOD",
+      "THIS MOD IS MARKED",
+      "EXPERIMENTAL.",
+      "ENABLE ANYWAY?",
+    }, proceed)
+    return
+  end
+  proceed()
 end
 
 function ManagerState:commitToggle(apply)
@@ -693,9 +737,26 @@ function ManagerState:applyProfile(p)
     end
   end
   self:commitToggle(combined)
+  -- #593: a profile is the whole setup, not just the enable set.  Options go
+  -- through setOption so loader.modOptions and mod.options_changed stay in
+  -- step; save slots move only to slots that version already registered
+  -- (SaveData.setActiveSlot would otherwise conjure one).
+  for modId, bucket in pairs(p.options or {}) do
+    if self.byId[modId] then
+      for key, value in pairs(bucket) do self:setOption(modId, key, value) end
+    end
+  end
+  for _, move in ipairs(ModProfile.slotMoves(p)) do
+    require("src.core.SaveData").setActiveSlot(move[1], move[2])
+  end
   self:optionsTable().activeProfile = p.name
   self:persistOptions()
-  self:notify("PROFILE STAGED")
+  local missing = ModProfile.missingIds(p, self.byId)
+  if #missing > 0 then
+    self:notify(#missing .. " MODS MISSING")
+  else
+    self:notify("PROFILE STAGED")
+  end
 end
 
 function ManagerState:saveCurrentAs()
@@ -706,16 +767,15 @@ function ManagerState:saveCurrentAs()
     onDone = function(name)
       local opts = self:optionsTable()
       opts.modProfiles = opts.modProfiles or {}
-      local enabled = {}
-      for _, m in ipairs(self.status.available or {}) do
-        enabled[m.id] = m.enabled and true or false
-      end
+      local snap = ModProfile.capture(self.status.available,
+        self:modOptionsTable())
       local existing = self:findProfile(name)
       if existing then
-        existing.enabled = enabled
+        existing.enabled, existing.options, existing.slots =
+          snap.enabled, snap.options, snap.slots
       else
-        opts.modProfiles[#opts.modProfiles + 1] =
-          { name = name, enabled = enabled }
+        snap.name = name
+        opts.modProfiles[#opts.modProfiles + 1] = snap
       end
       opts.activeProfile = name
       self:persistOptions()
@@ -724,6 +784,33 @@ function ManagerState:saveCurrentAs()
   }))
 end
 
+-- #593 sharing.  Export drops the active profile (or the focused one) in the
+-- save directory's profiles/ folder as <NAME>.g1rmodlist; import reads every
+-- file already there.  Deliberately folder-based rather than a native file
+-- picker: the same shape SaveFileIO uses for exports/, and it works on the
+-- mobile builds where no picker exists.
+function ManagerState:exportActiveProfile()
+  local row = self:focusedRow()
+  local p = (row and row.profile)
+    or self:findProfile(self:optionsTable().activeProfile)
+  if not p then return self:notify("NO PROFILE") end
+  local ok = ModProfile.export(p)
+  self:notify(ok and ("SAVED " .. p.name) or "EXPORT FAILED")
+end
+
+function ManagerState:importProfiles()
+  local opts = self:optionsTable()
+  opts.modProfiles = opts.modProfiles or {}
+  local n = 0
+  for _, path in ipairs(ModProfile.files()) do
+    if ModProfile.import(path, opts.modProfiles) then n = n + 1 end
+  end
+  if n == 0 then return self:notify("NO MODLISTS") end
+  self:persistOptions()
+  self:snapCursor()
+  self:notify(n .. " IMPORTED")
+end
+
 function ManagerState:renameProfile(p)
   local NamingScreen = require("src.ui.NamingScreen")
   self.game.stack:push(NamingScreen.new(self.game, {

src/mods/Manifest.lua

@@ -50,8 +50,94 @@ local function parseSpecs(list, field)
   return specs
 end
 
+-- Optional GitHub repo for launcher auto-update / other-versions.
+-- Accepts "owner/repo" or a github.com URL; empty/absent means no updates.
+function Manifest.parseGithub(value)
+  if value == nil or value == "" then return nil end
+  assert(type(value) == "string", "github must be a string")
+  local trimmed = value:match("^%s*(.-)%s*$") or value
+  if trimmed == "" then return nil end
+  local owner, repo = trimmed:match(
+    "^https?://github%.com/([%w%._%-]+)/([%w%._%-]+)/?$")
+  if not owner then
+    owner, repo = trimmed:match(
+      "^https?://github%.com/([%w%._%-]+)/([%w%._%-]+)%.git/?$")
+  end
+  if not owner then
+    owner, repo = trimmed:match("^([%w%._%-]+)/([%w%._%-]+)$")
+  end
+  assert(owner and repo and owner ~= "" and repo ~= "",
+    "github must be owner/repo or a github.com URL")
+  repo = repo:gsub("%.git$", "")
+  return owner .. "/" .. repo
+end
+
+-- conflicts + incompatible (alias) merged, first-wins on duplicate ids
+local function mergeConflictLists(conflicts, incompatible)
+  local seen, out = {}, {}
+  for _, list in ipairs({ array(conflicts), array(incompatible) }) do
+    for _, entry in ipairs(list) do
+      if not seen[entry] then
+        seen[entry] = true
+        out[#out + 1] = entry
+      end
+    end
+  end
+  return out
+end
+
+-- Drop bytes that are not valid UTF-8 (malformed sequences, overlongs,
+-- surrogates, > U+10FFFF) and a leading BOM.  LÖVE's text renderer raises
+-- "Invalid UTF-8" from love.graphics.print/printf, so any manifest string a
+-- panel may draw must be scrubbed here -- the one place every mod manifest
+-- passes through -- or a single mangled description crashes the whole MODS
+-- panel instead of misrendering one card.
+local function scrubUtf8(s)
+  if type(s) ~= "string" then return s end
+  s = s:gsub("^\239\187\191", "")
+  local out, i, n = {}, 1, #s
+  while i <= n do
+    local b = s:byte(i)
+    local len
+    if b < 0x80 then len = 1
+    elseif b >= 0xC2 and b <= 0xDF then len = 2
+    elseif b >= 0xE0 and b <= 0xEF then len = 3
+    elseif b >= 0xF0 and b <= 0xF4 then len = 4
+    end
+    local ok = len ~= nil and i + len - 1 <= n
+    if ok and len > 1 then
+      for j = i + 1, i + len - 1 do
+        local c = s:byte(j)
+        if c < 0x80 or c > 0xBF then ok = false; break end
+      end
+      if ok then
+        -- boundary lead bytes narrow their second byte: no overlongs
+        -- (E0/F0), no surrogates (ED), nothing past U+10FFFF (F4)
+        local b2 = s:byte(i + 1)
+        if (b == 0xE0 and b2 < 0xA0) or (b == 0xED and b2 > 0x9F)
+            or (b == 0xF0 and b2 < 0x90) or (b == 0xF4 and b2 > 0x8F) then
+          ok = false
+        end
+      end
+    end
+    if ok then
+      out[#out + 1] = s:sub(i, i + len - 1)
+      i = i + len
+    else
+      i = i + 1
+    end
+  end
+  return table.concat(out)
+end
+
 function Manifest.validate(raw, path)
   assert(type(raw) == "table", "manifest must be an object")
+  -- scrubbed in place so every later reader agrees, including the launcher's
+  -- badge derivation, which reads raw.category rather than the validated copy
+  raw.name = scrubUtf8(raw.name)
+  raw.version = scrubUtf8(raw.version)
+  raw.description = scrubUtf8(raw.description)
+  raw.category = scrubUtf8(raw.category)
   assert(type(raw.id) == "string" and raw.id:match("^[%w_%-]+$"),
     "manifest id must contain only letters, numbers, _ or -")
   assert(type(raw.name) == "string" and raw.name ~= "", "manifest name is required")
@@ -86,9 +172,27 @@ function Manifest.validate(raw, path)
   assert(gameVersionOk, ("malformed game_version %q: %s")
     :format(tostring(raw.game_version), tostring(gameVersionErr)))
 
+  local github = Manifest.parseGithub(raw.github)
+
+  assert(raw.experimental == nil or type(raw.experimental) == "boolean",
+    "experimental must be a boolean")
+  local experimental = raw.experimental == true
+
+  -- #501: a translation declares itself here.  Neither the ROM's dialogue
+  -- nor the engine's own strings are hashed into the link surface
+  -- (src/link/Fingerprint.lua header), so an English install and a Spanish
+  -- one run the same lockstep simulation, exactly as two regional carts on
+  -- a real cable did.  The flag is only the author's claim;
+  -- Handshake.onlineBlockers checks it against the ops the mod actually
+  -- appended before online play trusts it.
+  assert(raw.language == nil or type(raw.language) == "boolean",
+    "language must be a boolean")
+  local language = raw.language == true
+
   -- overhauls and total conversions are assumed to move the link
-  -- fingerprint unless the manifest says otherwise; content packs are not
-  local affectsLink = profile ~= "content"
+  -- fingerprint unless the manifest says otherwise; content packs and
+  -- declared translations are not
+  local affectsLink = profile ~= "content" and not language
   if type(raw.affects_link) == "boolean" then affectsLink = raw.affects_link end
 
   local function optionalFile(value, field)
@@ -97,6 +201,8 @@ function Manifest.validate(raw, path)
     return value
   end
 
+  local conflicts = mergeConflictLists(raw.conflicts, raw.incompatible)
+
   return {
     id = raw.id,
     name = raw.name,
@@ -106,14 +212,18 @@ function Manifest.validate(raw, path)
     priority = tonumber(raw.priority) or 0,
     dependencies = array(raw.dependencies),
     optional_dependencies = array(raw.optional_dependencies),
-    conflicts = array(raw.conflicts),
+    conflicts = conflicts,
+    incompatible = array(raw.incompatible),
     dependencySpecs = parseSpecs(array(raw.dependencies), "dependencies"),
     optionalSpecs = parseSpecs(array(raw.optional_dependencies), "optional_dependencies"),
-    conflictSpecs = parseSpecs(array(raw.conflicts), "conflicts"),
+    conflictSpecs = parseSpecs(conflicts, "conflicts"),
     category = raw.category or "OTHER",
     game_version = raw.game_version,
     description = raw.description or "",
+    github = github,
+    experimental = experimental,
     profile = profile,
+    language = language,
     affects_link = affectsLink,
     permissions = permissions,
     permissionSet = permissionSet,

src/mods/ModIndex.lua

@@ -0,0 +1,606 @@
+-- Community mod index consumer (the "Find mods" launcher tab).
+--
+-- An index is metadata only: a published index.json feed listing mods that
+-- live in their authors' own repos.  Nothing here clones or vendors the index
+-- repo -- the feed is the whole contract, and every install still goes through
+-- the same LauncherMods.installZip path an "Import mod .zip" does, so a listing
+-- buys a mod no trust it would not otherwise have.
+--
+-- Shape of the split mirrors src/mods/ModUpdate.lua, which this borrows its
+-- host I/O from: everything above "host I/O" is pure (no love, no filesystem,
+-- no network) so the engine tier can table-drive it, and the fetch/cache half
+-- reaches for curl and options.lua.
+--
+-- Sources are never added automatically.  options.modIndexes is a player-built
+-- list -- adding an index is a deliberate act of trusting whoever publishes it,
+-- so the launcher ships with none and asks.
+--
+-- schema_version is a hard gate, not a hint: a bumped feed may reuse a field
+-- name for something else, so an unknown version is refused outright rather
+-- than parsed hopefully.
+
+local ModIndex = {}
+
+-- The feed is rebuilt on every push and refreshed nightly, so a day-old copy
+-- is the worst a cached listing can be.  ModUpdate's six hours is tuned for a
+-- single repo's releases; a whole index is heavier and changes more slowly.
+ModIndex.CACHE_TTL = 24 * 60 * 60
+ModIndex.SCHEMA_VERSION = 1
+
+-- ------- pure: source resolution
+
+local function trim(s)
+  return (tostring(s):gsub("^%s+", ""):gsub("%s+$", ""))
+end
+
+-- Split "owner/repo" out of the several ways a player can name a GitHub repo.
+local function githubSlug(url)
+  local owner, repo = url:match("^https?://github%.com/([%w%-%.]+)/([%w%-%.]+)")
+  if not owner then
+    owner, repo = url:match("^([%w%-%.]+)/([%w%-%.]+)$")
+  end
+  if not owner then return nil end
+  repo = repo:gsub("%.git$", "")
+  return owner, repo
+end
+
+-- resolveSource(input) -> { feed, base, fallback, label } | nil, err
+--
+-- Players paste whichever URL they happened to have, so all four shapes of the
+-- same index resolve to one source: the Pages root, the feed file itself, the
+-- GitHub repo page, or a bare "owner/repo".  `base` is what relative thumbnail
+-- and description_url paths resolve against, and it always keeps its trailing
+-- slash so joinUrl can stay a concatenation.
+--
+-- The raw.githubusercontent fallback exists because Pages deploys lag a push
+-- by a minute or two; it is only ever consulted when the feed fetch fails.
+function ModIndex.resolveSource(input)
+  if type(input) ~= "string" then return nil, "missing index URL" end
+  local url = trim(input)
+  if url == "" then return nil, "missing index URL" end
+
+  local owner, repo = githubSlug(url)
+  if owner then
+    return {
+      feed = ("https://%s.github.io/%s/data/index.json"):format(owner, repo),
+      base = ("https://%s.github.io/%s/"):format(owner, repo),
+      fallback = ("https://raw.githubusercontent.com/%s/%s/main/site/data/index.json")
+        :format(owner, repo),
+      label = owner .. "/" .. repo,
+    }
+  end
+
+  if not url:match("^https?://") then
+    return nil, "index must be an http(s) URL or owner/repo"
+  end
+
+  -- A feed URL names the file; the Pages root is what is left once the
+  -- "data/index.json" tail comes off (any other .json keeps only its folder).
+  if url:match("%.json$") then
+    local base = url:match("^(.*/)data/index%.json$") or url:match("^(.*/)")
+    return { feed = url, base = base or url, label = ModIndex.labelFor(base or url) }
+  end
+
+  local base = url:match("/$") and url or (url .. "/")
+  return {
+    feed = base .. "data/index.json",
+    base = base,
+    label = ModIndex.labelFor(base),
+  }
+end
+
+-- A short human name for a source row: "owner/repo" for a Pages host, else the
+-- host plus first path segment.  Only ever cosmetic.
+function ModIndex.labelFor(url)
+  url = tostring(url or "")
+  local owner, repo = url:match("^https?://([%w%-%.]+)%.github%.io/([%w%-%.]+)/")
+  if owner then return owner .. "/" .. repo end
+  local host, first = url:match("^https?://([^/]+)/([^/]*)")
+  if host and first and first ~= "" then return host .. "/" .. first end
+  return host or url
+end
+
+-- joinUrl(base, rel) -> absolute URL | nil
+-- Relative feed paths resolve against the Pages root; an already-absolute one
+-- is handed back untouched (the schema allows either), and anything else --
+-- nil, "", a non-string -- is simply absent rather than an error, because a
+-- missing thumbnail is not a broken index.
+function ModIndex.joinUrl(base, rel)
+  if type(rel) ~= "string" or rel == "" then return nil end
+  if rel:match("^https?://") then return rel end
+  if type(base) ~= "string" or base == "" then return nil end
+  if not base:match("/$") then base = base .. "/" end
+  return base .. (rel:gsub("^/", ""))
+end
+
+-- ------- pure: feed parsing
+
+local function str(v)
+  return type(v) == "string" and v or nil
+end
+
+local function strArray(v)
+  local out = {}
+  if type(v) == "table" then
+    for _, entry in ipairs(v) do
+      if type(entry) == "string" then out[#out + 1] = entry end
+    end
+  end
+  return out
+end
+
+-- Decode one release blob from the feed's `latest` field into the same shape
+-- ModUpdate.parseRelease produces, so LauncherMods.installFromRelease takes it
+-- without a translation layer.
+local function parseLatest(raw)
+  if type(raw) ~= "table" then return nil end
+  local zip = nil
+  if type(raw.zip) == "table" and str(raw.zip.url) then
+    zip = { name = str(raw.zip.name), url = raw.zip.url,
+            size = tonumber(raw.zip.size) }
+  end
+  return {
+    version = str(raw.version),
+    tag = str(raw.tag),
+    name = str(raw.name),
+    prerelease = raw.prerelease == true,
+    published_at = str(raw.published_at),
+    zip = zip,
+  }
+end
+
+local function parseEntry(raw)
+  if type(raw) ~= "table" or not str(raw.id) then return nil end
+  return {
+    folder = str(raw.folder),
+    id = raw.id,
+    title = str(raw.title) or raw.id,
+    author = str(raw.author),
+    version = str(raw.version),
+    summary = str(raw.summary) or "",
+    categories = strArray(raw.categories),
+    tags = strArray(raw.tags),
+    license = str(raw.license),
+    repo = str(raw.repo),
+    github = str(raw.github),
+    downloadURL = str(raw.downloadURL),
+    api = tonumber(raw.api),
+    game_version = str(raw.game_version),
+    profile = str(raw.profile),
+    affects_link = raw.affects_link == true,
+    experimental = raw.experimental == true,
+    permissions = strArray(raw.permissions),
+    dependencies = raw.dependencies,
+    conflicts = raw.conflicts,
+    thumbnail = str(raw.thumbnail),
+    description_url = str(raw.description_url),
+    latest = parseLatest(raw.latest),
+    update_check = str(raw.update_check) or "pending",
+  }
+end
+
+-- parse(jsonText [, Json]) -> { schemaVersion, generatedAt, categories, mods }
+--                          |  nil, err
+-- Never throws: a truncated download, an HTML error page, or a feed from a
+-- future schema all come back as a message the panel can print.
+function ModIndex.parse(jsonText, Json)
+  local ok, result, err = pcall(function()
+    Json = Json or require("src.link.Json")
+    local doc, decodeErr = Json.decode(jsonText)
+    if type(doc) ~= "table" then
+      return nil, decodeErr or "index.json is not an object"
+    end
+    local schema = tonumber(doc.schema_version)
+    if schema == nil then
+      return nil, "index.json has no schema_version"
+    end
+    if schema ~= ModIndex.SCHEMA_VERSION then
+      return nil, ("index schema %d is not supported (this build reads %d)")
+        :format(schema, ModIndex.SCHEMA_VERSION)
+    end
+    if type(doc.mods) ~= "table" then
+      return nil, "index.json has no mods array"
+    end
+    local mods = {}
+    for _, raw in ipairs(doc.mods) do
+      local entry = parseEntry(raw)
+      if entry then mods[#mods + 1] = entry end
+    end
+    return {
+      schemaVersion = schema,
+      generatedAt = str(doc.generated_at),
+      categories = strArray(doc.categories),
+      mods = mods,
+    }
+  end)
+  if not ok then return nil, "could not read the index: " .. tostring(result) end
+  return result, err
+end
+
+-- ------- pure: install resolution
+
+-- installUrl(entry) -> url, kind  |  nil, reason
+--
+-- The same order the engine's zip import already implies: a verified release
+-- asset first, then the author's fixed downloadURL.  A GitHub source-archive
+-- URL is never invented -- codeload gives you the repo, not the built mod, and
+-- the folder layout would be wrong even when the download succeeds.
+function ModIndex.installUrl(entry)
+  if type(entry) ~= "table" then return nil, "no entry" end
+  if entry.update_check == "ok" and entry.latest and entry.latest.zip
+      and entry.latest.zip.url then
+    return entry.latest.zip.url, "release"
+  end
+  if entry.downloadURL and entry.downloadURL ~= "" then
+    return entry.downloadURL, "download"
+  end
+  if entry.update_check == "off" then
+    return nil, "the author does not publish installable releases"
+  end
+  if entry.update_check == "no installable release" then
+    return nil, "no release with a .zip asset yet"
+  end
+  if type(entry.update_check) == "string"
+      and entry.update_check:match("^error") then
+    return nil, entry.update_check
+  end
+  return nil, "nothing installable listed"
+end
+
+function ModIndex.canInstall(entry)
+  return ModIndex.installUrl(entry) ~= nil
+end
+
+-- The version to show on a card: the release the index resolved when it could
+-- reach GitHub, else whatever meta.json declared.
+function ModIndex.displayVersion(entry)
+  if type(entry) ~= "table" then return "?" end
+  if entry.update_check == "ok" and entry.latest and entry.latest.version then
+    return entry.latest.version
+  end
+  return entry.version or "?"
+end
+
+-- The release table LauncherMods.installFromRelease wants.  A downloadURL
+-- entry has no release behind it, so one is synthesised around the URL; the
+-- installer still validates the manifest inside and still refuses a zip whose
+-- id is not the one being installed.
+function ModIndex.releaseFor(entry)
+  local url, kind = ModIndex.installUrl(entry)
+  if not url then return nil, kind end
+  if kind == "release" then return entry.latest end
+  return {
+    version = ModIndex.displayVersion(entry),
+    zip = { url = url, name = entry.id .. ".zip" },
+  }
+end
+
+-- ------- pure: compatibility
+
+-- compatIssues(entry, ctx) -> array of { level, text }
+--
+-- Soft gate by design: an index entry is metadata an author wrote, possibly
+-- months ago, and hiding a mod because a range looks wrong is how a working
+-- mod becomes invisible.  Everything here warns; the confirm dialog shows the
+-- list and the player decides.  ctx carries { modApi, engineVersion,
+-- installed = { id -> version }, enabled = { id -> true } }.
+function ModIndex.compatIssues(entry, ctx)
+  local out = {}
+  if type(entry) ~= "table" then return out end
+  ctx = ctx or {}
+  local function warn(text) out[#out + 1] = { level = "warn", text = text } end
+
+  local modApi = tonumber(ctx.modApi)
+  if entry.api and modApi and entry.api > modApi then
+    warn(("Needs mod API %d; this build provides %d")
+      :format(entry.api, modApi))
+  end
+
+  if entry.game_version and ctx.engineVersion then
+    local okSemver, Semver = pcall(require, "src.mods.Semver")
+    if okSemver and not Semver.satisfies(ctx.engineVersion, entry.game_version) then
+      warn(("Needs engine %s (have %s)")
+        :format(entry.game_version, ctx.engineVersion))
+    end
+  end
+
+  if entry.profile and entry.profile ~= "content" then
+    warn(("Profile '%s' changes engine behaviour beyond content")
+      :format(entry.profile))
+  end
+  if entry.affects_link then
+    warn("Changes link play; both sides need the same mods")
+  end
+  if entry.experimental then
+    warn("Marked experimental by its author")
+  end
+
+  for _, name in ipairs(entry.permissions or {}) do
+    warn("Requests permission: " .. name)
+  end
+
+  -- dependencies / conflicts arrive as the manifest's own vocabulary: either
+  -- an array of "id" / "id@<range>" strings or an id -> range map.
+  local installed = ctx.installed or {}
+  local function eachSpec(spec, fn)
+    if type(spec) ~= "table" then return end
+    for k, v in pairs(spec) do
+      if type(k) == "number" and type(v) == "string" then
+        local id, range = v:match("^([^@]+)@(.+)$")
+        fn(id or v, range)
+      elseif type(k) == "string" then
+        fn(k, type(v) == "string" and v or nil)
+      end
+    end
+  end
+
+  eachSpec(entry.dependencies, function(id, range)
+    if installed[id] == nil then
+      warn("Needs " .. id .. (range and (" " .. range) or "") .. " (not installed)")
+    end
+  end)
+  eachSpec(entry.conflicts, function(id)
+    if installed[id] ~= nil then
+      warn("Conflicts with installed " .. id)
+    end
+  end)
+
+  return out
+end
+
+-- ------- pure: search / filter
+
+local function haystack(entry)
+  return (tostring(entry.title or "") .. " " .. tostring(entry.author or "")
+    .. " " .. tostring(entry.summary or "") .. " " .. tostring(entry.id or ""))
+    :lower()
+end
+
+-- matches(entry, query) -> bool.  Every whitespace-separated term must appear
+-- somewhere in title / author / summary / id, so typing more narrows.
+function ModIndex.matches(entry, query)
+  if type(query) ~= "string" or trim(query) == "" then return true end
+  local hay = haystack(entry)
+  for term in trim(query):lower():gmatch("%S+") do
+    if not hay:find(term, 1, true) then return false end
+  end
+  return true
+end
+
+-- filter(mods, opts) -> a new array.  opts = { query, category, tag }.
+-- Category and tag compare case-insensitively; feed order (already sorted by
+-- title) is preserved.
+function ModIndex.filter(mods, opts)
+  opts = opts or {}
+  local want = opts.category and tostring(opts.category):lower() or nil
+  local wantTag = opts.tag and tostring(opts.tag):lower() or nil
+  local out = {}
+  for _, entry in ipairs(mods or {}) do
+    local keep = ModIndex.matches(entry, opts.query)
+    if keep and want then
+      keep = false
+      for _, c in ipairs(entry.categories or {}) do
+        if tostring(c):lower() == want then keep = true; break end
+      end
+    end
+    if keep and wantTag then
+      keep = false
+      for _, t in ipairs(entry.tags or {}) do
+        if tostring(t):lower() == wantTag then keep = true; break end
+      end
+    end
+    if keep then out[#out + 1] = entry end
+  end
+  return out
+end
+
+-- Every category actually used by a feed, in the feed's declared order, with
+-- anything an entry names that the header forgot appended.  Drives the filter
+-- row without hard-coding the vocabulary.
+function ModIndex.categoriesIn(index)
+  local out, seen = {}, {}
+  if type(index) ~= "table" then return out end
+  local used = {}
+  for _, entry in ipairs(index.mods or {}) do
+    for _, c in ipairs(entry.categories or {}) do used[c] = true end
+  end
+  for _, c in ipairs(index.categories or {}) do
+    if used[c] and not seen[c] then seen[c] = true; out[#out + 1] = c end
+  end
+  for _, entry in ipairs(index.mods or {}) do
+    for _, c in ipairs(entry.categories or {}) do
+      if not seen[c] then seen[c] = true; out[#out + 1] = c end
+    end
+  end
+  return out
+end
+
+-- ------- sources (options.modIndexes)
+
+local function loadOptions()
+  return require("src.core.SaveData").loadOptions()
+end
+
+-- The player's index list, normalised.  Rows are { url, feed, base, fallback,
+-- label }; `url` is what they typed, kept so the row reads back the way they
+-- entered it.
+function ModIndex.sources()
+  local ok, opts = pcall(loadOptions)
+  if not ok or type(opts) ~= "table" then return {} end
+  local out = {}
+  for _, row in ipairs(opts.modIndexes or {}) do
+    if type(row) == "table" and type(row.feed) == "string" then
+      out[#out + 1] = row
+    end
+  end
+  return out
+end
+
+-- addSource(input) -> row | nil, err.  Idempotent on the resolved feed URL, so
+-- pasting the repo page and the Pages root in either order adds one source.
+function ModIndex.addSource(input)
+  local source, err = ModIndex.resolveSource(input)
+  if not source then return nil, err end
+  local ok, result, addErr = pcall(function()
+    local SaveData = require("src.core.SaveData")
+    local opts = loadOptions()
+    opts.modIndexes = opts.modIndexes or {}
+    for _, row in ipairs(opts.modIndexes) do
+      if row.feed == source.feed then
+        return nil, "that index is already added"
+      end
+    end
+    source.url = trim(input)
+    opts.modIndexes[#opts.modIndexes + 1] = source
+    SaveData.saveOptions(opts)
+    return source
+  end)
+  if not ok then return nil, "could not save the index: " .. tostring(result) end
+  return result, addErr
+end
+
+-- removeSource(feed) -> true | nil, err.  Drops the cached listing with it:
+-- keeping a feed's mods around after its source is gone is how a stale card
+-- outlives the index it came from.
+function ModIndex.removeSource(feed)
+  if type(feed) ~= "string" or feed == "" then return nil, "missing index" end
+  local ok, result = pcall(function()
+    local SaveData = require("src.core.SaveData")
+    local opts = loadOptions()
+    local kept, found = {}, false
+    for _, row in ipairs(opts.modIndexes or {}) do
+      if row.feed == feed then found = true else kept[#kept + 1] = row end
+    end
+    if not found then return nil end
+    opts.modIndexes = kept
+    if type(opts.modIndexCache) == "table" then opts.modIndexCache[feed] = nil end
+    SaveData.saveOptions(opts)
+    return true
+  end)
+  if not ok then return nil, tostring(result) end
+  if not result then return nil, "that index is not in the list" end
+  return true
+end
+
+-- ------- cache (options.modIndexCache[feed])
+
+function ModIndex.readCache(feed)
+  if type(feed) ~= "string" or feed == "" then return nil end
+  local ok, opts = pcall(loadOptions)
+  if not ok or type(opts) ~= "table" then return nil end
+  local entry = opts.modIndexCache and opts.modIndexCache[feed]
+  if type(entry) ~= "table" or type(entry.checkedAt) ~= "number" then
+    return nil
+  end
+  if type(entry.mods) ~= "table" then return nil end
+  return entry
+end
+
+function ModIndex.cacheFresh(entry, now, ttl)
+  now = now or os.time()
+  ttl = ttl or ModIndex.CACHE_TTL
+  return entry ~= nil and type(entry.checkedAt) == "number"
+    and (now - entry.checkedAt) < ttl
+end
+
+function ModIndex.writeCache(feed, index)
+  if type(feed) ~= "string" or feed == "" then return false end
+  local ok = pcall(function()
+    local SaveData = require("src.core.SaveData")
+    local opts = loadOptions()
+    opts.modIndexCache = opts.modIndexCache or {}
+    opts.modIndexCache[feed] = {
+      checkedAt = os.time(),
+      generatedAt = index.generatedAt,
+      categories = index.categories,
+      mods = index.mods,
+    }
+    SaveData.saveOptions(opts)
+  end)
+  return ok
+end
+
+-- ------- host I/O (HostShell's transport: curl, or the Android JNI bridge)
+
+-- Plain GET returning the body.  No GitHub Accept header: the feed and the
+-- description markdown are static files on Pages, and the public feed is
+-- explicitly unauthenticated.  The transport itself lives in
+-- src/core/HostShell.lua because Android has no curl and has to fetch through
+-- love.system.httpDownload instead (#597).
+function ModIndex.httpGet(url)
+  local HostShell = require("src.core.HostShell")
+  if not HostShell.canFetch() then
+    return nil, "no network transport on this platform"
+  end
+  return HostShell.httpGet(url, "gen1recomp-mod-index")
+end
+
+-- fetch(source, opts) -> index, err, meta
+-- index is the parse() table; meta is { fromCache, stale }.  opts.force skips
+-- the 24h cache.  A failed live fetch falls back to whatever is cached, marked
+-- stale, so going offline degrades the listing rather than emptying it.
+function ModIndex.fetch(source, opts)
+  opts = opts or {}
+  if type(source) ~= "table" or type(source.feed) ~= "string" then
+    return nil, "missing index source"
+  end
+  local feed = source.feed
+
+  local function cached(stale)
+    local entry = ModIndex.readCache(feed)
+    if not entry then return nil end
+    return {
+      schemaVersion = ModIndex.SCHEMA_VERSION,
+      generatedAt = entry.generatedAt,
+      categories = entry.categories or {},
+      mods = entry.mods or {},
+    }, nil, { fromCache = true, stale = stale, checkedAt = entry.checkedAt }
+  end
+
+  if not opts.force then
+    local entry = ModIndex.readCache(feed)
+    if ModIndex.cacheFresh(entry) then return cached(false) end
+  end
+
+  local body, err = ModIndex.httpGet(feed)
+  -- Pages deploys trail a push; the raw mirror is the same file, so a feed
+  -- that 404s right after a release is worth one retry elsewhere before it
+  -- counts as an outage.
+  if not body and source.fallback then
+    body = ModIndex.httpGet(source.fallback)
+  end
+  if not body then
+    local index, _, meta = cached(true)
+    if index then return index, nil, meta end
+    return nil, err
+  end
+
+  local index, parseErr = ModIndex.parse(body)
+  if not index then
+    local stale, _, meta = cached(true)
+    if stale then return stale, parseErr, meta end
+    return nil, parseErr
+  end
+  ModIndex.writeCache(feed, index)
+  return index, nil, { fromCache = false, checkedAt = os.time() }
+end
+
+-- Fetch a description_url / any index-relative text file.  Returns the raw
+-- markdown; callers run it through ModUpdate.cleanBody for display.
+function ModIndex.fetchText(url)
+  if type(url) ~= "string" or url == "" then return nil, "no description" end
+  return ModIndex.httpGet(url)
+end
+
+-- Download a thumbnail into the save directory and return the love.filesystem
+-- relative path.  Reuses ModUpdate.downloadZip, which is a plain curl -o with
+-- a non-empty-file check -- nothing in it is zip-specific.
+function ModIndex.downloadThumbnail(url, modId)
+  if type(url) ~= "string" or url == "" then return nil, "no thumbnail" end
+  local ModUpdate = require("src.mods.ModUpdate")
+  local ext = url:match("%.(%a%a%a?%a?)$") or "png"
+  local name = ("mod_thumb_%s.%s"):format(tostring(modId):gsub("[^%w%-_]", "_"), ext)
+  return ModUpdate.downloadZip(url, name)
+end
+
+return ModIndex

src/mods/ModProfile.lua

@@ -0,0 +1,206 @@
+-- Mod profiles (#593): a named snapshot of one whole setup -- which mods are
+-- enabled, each mod's own options, and which save slot every game version
+-- plays -- plus the shareable .g1rmodlist file the manager writes and reads.
+-- Pure data and filesystem: src/mods/ManagerState.lua owns the UI and the
+-- staged toggles, and is the only caller.
+--
+-- Records live in options.modProfiles (src/core/SaveData.lua defaultOptions),
+-- so a profile survives New Game exactly like the mod enable-state does:
+--   { name    = "PROFILE 1",
+--     enabled = { [modId] = true|false },     -- missing means enabled
+--     options = { [modId] = { key = value } },-- mirrors options.modOptions
+--     slots   = { red = "slot1", blue = "slot2", yellow = nil } }
+-- Exports are SaveSerializer-encoded (data-only parse, an imported file can
+-- never execute code) under profiles/<NAME>.g1rmodlist in the save dir, the
+-- same shape SaveFileIO uses for exports/ (src/import/SaveFileIO.lua).
+
+local SaveSerializer = require("src.core.SaveSerializer")
+local SaveData = require("src.core.SaveData")
+local GameVersion = require("src.core.GameVersion")
+
+local ModProfile = {}
+
+ModProfile.EXT = ".g1rmodlist"
+ModProfile.DIR = "profiles"
+ModProfile.FORMAT = "g1rmodlist"
+ModProfile.FORMAT_VERSION = 1
+
+-- deterministic order; GameVersion.VERSIONS is a map, and a profile file has
+-- to encode the same way twice for a diff to mean anything
+local VERSION_ORDER = { "red", "blue", "yellow" }
+
+local function fsOr(fs)
+  return fs or (love and love.filesystem) or nil
+end
+
+-- Capture the live setup.  `available` is ManagerState.status.available (the
+-- loader's status manifests, m.enabled = the desired set including staged
+-- flips); `modOptions` is options.modOptions.
+function ModProfile.capture(available, modOptions)
+  local enabled, options = {}, {}
+  for _, m in ipairs(available or {}) do
+    enabled[m.id] = m.enabled and true or false
+    local bucket = modOptions and modOptions[m.id]
+    if type(bucket) == "table" then
+      local copy = {}
+      for k, v in pairs(bucket) do
+        local t = type(v)
+        if t == "string" or t == "number" or t == "boolean" then copy[k] = v end
+      end
+      options[m.id] = copy
+    end
+  end
+  local slots = {}
+  for _, id in ipairs(VERSION_ORDER) do
+    local ok, slot = pcall(SaveData.activeSlot, id)
+    if ok and slot then slots[id] = slot end
+  end
+  return { enabled = enabled, options = options, slots = slots }
+end
+
+-- The slot moves a profile may actually make: a slot id has to be registered
+-- for that version already, because SaveData.setActiveSlot registers an
+-- unknown id and would conjure a phantom slot the player never made.
+function ModProfile.slotMoves(p)
+  local moves = {}
+  for _, version in ipairs(VERSION_ORDER) do
+    local want = p.slots and p.slots[version]
+    if want then
+      local ok, list = pcall(SaveData.listSlots, version)
+      if ok then
+        for _, row in ipairs(list or {}) do
+          if row.id == want then moves[#moves + 1] = { version, want } end
+        end
+      end
+    end
+  end
+  return moves
+end
+
+-- ids the profile wants enabled that are not installed here.  Import cannot
+-- fetch them (community-index install is deferred), so the manager reports
+-- them rather than silently playing a different setup than the sharer's.
+function ModProfile.missingIds(p, byId)
+  local out = {}
+  for id, on in pairs(p.enabled or {}) do
+    if on and not (byId or {})[id] then out[#out + 1] = id end
+  end
+  table.sort(out)
+  return out
+end
+
+function ModProfile.encode(p)
+  return SaveSerializer.encode({
+    format = ModProfile.FORMAT,
+    formatVersion = ModProfile.FORMAT_VERSION,
+    profile = { name = p.name, enabled = p.enabled,
+                options = p.options, slots = p.slots },
+  })
+end
+
+-- Shape-validate rather than trust: a shared file is untrusted input, and the
+-- manager indexes p.enabled/p.options straight into its row models.
+function ModProfile.decode(body)
+  if type(body) ~= "string" then return nil, "EMPTY FILE" end
+  local ok, data = pcall(SaveSerializer.decode, body)
+  if not ok or type(data) ~= "table" then return nil, "BAD FILE" end
+  if data.format ~= ModProfile.FORMAT then return nil, "NOT A MODLIST" end
+  local raw = data.profile
+  if type(raw) ~= "table" or type(raw.name) ~= "string" or raw.name == "" then
+    return nil, "BAD FILE"
+  end
+  local p = { name = raw.name:sub(1, 10), enabled = {}, options = {}, slots = {} }
+  for id, on in pairs(type(raw.enabled) == "table" and raw.enabled or {}) do
+    if type(id) == "string" then p.enabled[id] = on and true or false end
+  end
+  for id, bucket in pairs(type(raw.options) == "table" and raw.options or {}) do
+    if type(id) == "string" and type(bucket) == "table" then
+      local copy = {}
+      for k, v in pairs(bucket) do
+        local t = type(v)
+        if type(k) == "string" and (t == "string" or t == "number" or t == "boolean") then
+          copy[k] = v
+        end
+      end
+      p.options[id] = copy
+    end
+  end
+  for version, slot in pairs(type(raw.slots) == "table" and raw.slots or {}) do
+    if GameVersion.VERSIONS[version] and type(slot) == "string" then
+      p.slots[version] = slot
+    end
+  end
+  return p
+end
+
+-- profiles/<NAME>.g1rmodlist; letters, digits and dashes only so a shared
+-- name can never escape the folder
+local function fileFor(name)
+  return ModProfile.DIR .. "/" ..
+    tostring(name):upper():gsub("[^%w%-]", "_") .. ModProfile.EXT
+end
+ModProfile.fileFor = fileFor
+
+function ModProfile.export(p, fs)
+  fs = fsOr(fs)
+  if not (fs and fs.write) then return false, "NO FILESYSTEM" end
+  if fs.createDirectory then fs.createDirectory(ModProfile.DIR) end
+  local rel = fileFor(p.name)
+  local ok, err = fs.write(rel, ModProfile.encode(p))
+  if not ok then return false, tostring(err) end
+  local base = fs.getSaveDirectory and fs.getSaveDirectory() or ""
+  if base ~= "" then return true, base .. "/" .. rel end
+  return true, rel
+end
+
+-- every .g1rmodlist sitting in profiles/, sorted, as relative paths
+function ModProfile.files(fs)
+  fs = fsOr(fs)
+  local out = {}
+  if not (fs and fs.getDirectoryItems) then return out end
+  if fs.getInfo and not fs.getInfo(ModProfile.DIR) then return out end
+  for _, name in ipairs(fs.getDirectoryItems(ModProfile.DIR) or {}) do
+    if name:sub(-#ModProfile.EXT) == ModProfile.EXT then
+      out[#out + 1] = ModProfile.DIR .. "/" .. name
+    end
+  end
+  table.sort(out)
+  return out
+end
+
+-- Read one export and land it in `profiles` (options.modProfiles) under a
+-- non-colliding name, so importing twice never overwrites what the player
+-- already tuned.  Returns the stored record, or nil + a short reason.
+function ModProfile.import(path, profiles, fs)
+  fs = fsOr(fs)
+  if not (fs and fs.read) then return nil, "NO FILESYSTEM" end
+  local p, err = ModProfile.decode(fs.read(path))
+  if not p then return nil, err end
+  local taken = {}
+  for _, existing in ipairs(profiles) do taken[existing.name] = true end
+  local name, n = p.name, 1
+  while taken[name] do
+    n = n + 1
+    name = (p.name:sub(1, 8) .. n)
+  end
+  p.name = name
+  profiles[#profiles + 1] = p
+  return p
+end
+
+-- First run after this update: the setup the player already has becomes
+-- PROFILE 1, then they can add more (#593).  Seeded once and remembered by
+-- options.modProfilesSeeded, so deleting every profile does not resurrect it.
+function ModProfile.ensureFirst(opts, available, modOptions)
+  if opts.modProfilesSeeded then return nil end
+  opts.modProfilesSeeded = true
+  opts.modProfiles = opts.modProfiles or {}
+  if #opts.modProfiles > 0 then return nil end
+  local p = ModProfile.capture(available, modOptions)
+  p.name = "PROFILE 1"
+  opts.modProfiles[1] = p
+  opts.activeProfile = p.name
+  return p
+end
+
+return ModProfile

src/mods/ModUpdate.lua

@@ -0,0 +1,341 @@
+-- GitHub release helpers for mod auto-update / other-versions.
+-- Pure parsing is love-free; fetch/download use HostShell + curl when available.
+-- Release lists are cached in options.modUpdateCache for CACHE_TTL seconds
+-- (default 6 hours). The launcher owns UI and install.
+
+local ModUpdate = {}
+
+ModUpdate.CACHE_TTL = 6 * 60 * 60  -- six hours
+
+local function stripV(tag)
+  return (tostring(tag):gsub("^[vV]", ""))
+end
+
+-- Prefer "<id>-<version>.zip", then any "<id>*.zip", then the first .zip.
+function ModUpdate.pickZipAsset(assets, modId, version)
+  if type(assets) ~= "table" then return nil end
+  local prefer = nil
+  if modId and version then
+    prefer = tostring(modId) .. "-" .. tostring(version) .. ".zip"
+  end
+  local idPrefix, idPrefixZip, anyZip = nil, nil, nil
+  if modId then idPrefix = tostring(modId):lower() end
+  for _, a in ipairs(assets) do
+    if type(a) == "table" and type(a.name) == "string" then
+      local name = a.name
+      if name:lower():match("%.zip$") then
+        local row = {
+          name = name,
+          url = a.browser_download_url,
+          size = tonumber(a.size),
+        }
+        if prefer and name == prefer then return row end
+        if idPrefix and not idPrefixZip
+            and name:lower():find(idPrefix, 1, true) == 1 then
+          idPrefixZip = row
+        end
+        if not anyZip then anyZip = row end
+      end
+    end
+  end
+  return idPrefixZip or anyZip
+end
+
+-- Byte-length cut that never lands mid UTF-8 codepoint.
+local function utf8Cut(s, maxBytes)
+  if type(s) ~= "string" or maxBytes <= 0 then return "" end
+  if #s <= maxBytes then return s end
+  s = s:sub(1, maxBytes)
+  -- Drop trailing continuation bytes (10xxxxxx).
+  while #s > 0 do
+    local b = s:byte(#s)
+    if b < 0x80 or b >= 0xC0 then break end
+    s = s:sub(1, #s - 1)
+  end
+  -- Drop a lead byte whose continuation was truncated away.
+  if #s > 0 then
+    local b = s:byte(#s)
+    if b >= 0xC0 then
+      s = s:sub(1, #s - 1)
+    end
+  end
+  return s
+end
+
+-- Strip common markdown / HTML noise for the launcher changelog preview.
+function ModUpdate.cleanBody(text, maxChars)
+  if type(text) ~= "string" or text == "" then return "" end
+  local s = text
+  s = s:gsub("\r\n", "\n"):gsub("\r", "\n")
+  s = s:gsub("<!%-%-.-%-%->", "")
+  s = s:gsub("<[^>]+>", "")
+  s = s:gsub("%[%!%[[^%]]*%]%([^%)]*%)%]", "") -- images ![alt](url)
+  s = s:gsub("%[([^%]]+)%]%([^%)]+%)", "%1")   -- links [text](url) -> text
+  s = s:gsub("```[^\n]*\n(.-)```", "%1")
+  s = s:gsub("`([^`]+)`", "%1")
+  s = s:gsub("^#+%s*", "", 1)
+  s = s:gsub("\n#+%s*", "\n")
+  s = s:gsub("%*%*([^*]+)%*%*", "%1")
+  s = s:gsub("%*([^*]+)%*", "%1")
+  s = s:gsub("__([^_]+)__", "%1")
+  s = s:gsub("_([^_]+)_", "%1")
+  s = s:gsub("^\n+", ""):gsub("\n+$", "")
+  s = s:gsub("\n\n\n+", "\n\n")
+  maxChars = tonumber(maxChars) or 0
+  if maxChars > 0 and #s > maxChars then
+    -- ASCII "..." (not U+2026) so later pixel ellipsize stays byte-safe.
+    s = utf8Cut(s, maxChars):gsub("%s+%S*$", "") .. "..."
+  end
+  return s
+end
+
+-- One-line preview for tight UI rows: cleaned, newlines collapsed, ellipsized.
+function ModUpdate.previewLine(text, maxChars)
+  local s = ModUpdate.cleanBody(text, 0)
+  if s == "" then return "" end
+  s = s:gsub("\n+", " "):gsub("%s+", " ")
+  s = s:match("^%s*(.-)%s*$") or s
+  maxChars = tonumber(maxChars) or 80
+  if #s > maxChars then
+    s = utf8Cut(s, maxChars):gsub("%s+%S*$", "") .. "..."
+  end
+  return s
+end
+
+-- Decode one GitHub release object into { version, tag, zip, prerelease, body }.
+function ModUpdate.parseRelease(doc, modId)
+  if type(doc) ~= "table" or not doc.tag_name then
+    return nil, "no tag_name in release"
+  end
+  local version = stripV(doc.tag_name)
+  if not version:match("^%d+%.%d+%.%d+") then
+    return nil, "release tag is not semver-like: " .. tostring(doc.tag_name)
+  end
+  local triple = version:match("^(%d+%.%d+%.%d+)")
+  local zip = ModUpdate.pickZipAsset(doc.assets, modId, triple)
+  local body = type(doc.body) == "string" and doc.body or ""
+  return {
+    version = triple,
+    tag = tostring(doc.tag_name),
+    zip = zip,
+    prerelease = doc.prerelease == true,
+    name = type(doc.name) == "string" and doc.name or triple,
+    body = body,
+  }
+end
+
+-- Decode a releases array (GET /repos/.../releases) into a sorted list
+-- (newest first). Releases without a .zip asset are dropped. Never throws.
+function ModUpdate.parseReleases(jsonText, modId, Json)
+  local ok, result, err = pcall(function()
+    Json = Json or require("src.link.Json")
+    local doc, decodeErr = Json.decode(jsonText)
+    if type(doc) ~= "table" then
+      return nil, decodeErr or "releases json is not an array"
+    end
+    if type(doc.message) == "string" and not doc.tag_name and not doc[1] then
+      return nil, "GitHub: " .. doc.message
+    end
+    if doc.tag_name then
+      local one, oneErr = ModUpdate.parseRelease(doc, modId)
+      if not one then return nil, oneErr end
+      if not one.zip then return nil, "latest release has no .zip asset" end
+      return { one }
+    end
+    local out = {}
+    for _, entry in ipairs(doc) do
+      local rel = ModUpdate.parseRelease(entry, modId)
+      if rel and rel.zip then out[#out + 1] = rel end
+    end
+    return out
+  end)
+  if not ok then return nil, "could not parse releases: " .. tostring(result) end
+  return result, err
+end
+
+function ModUpdate.apiReleasesUrl(repo)
+  return "https://api.github.com/repos/" .. repo .. "/releases?per_page=30"
+end
+
+function ModUpdate.apiLatestUrl(repo)
+  return "https://api.github.com/repos/" .. repo .. "/releases/latest"
+end
+
+function ModUpdate.isNewer(installed, candidate)
+  local Semver = require("src.mods.Semver")
+  if type(installed) ~= "string" or type(candidate) ~= "string" then
+    return false
+  end
+  local a, b = Semver.parse(installed), Semver.parse(candidate)
+  if not a or not b then return false end
+  return Semver.compare(candidate, installed) > 0
+end
+
+-- Newest non-prerelease, else newest overall.
+function ModUpdate.pickBest(releases)
+  if type(releases) ~= "table" or #releases == 0 then return nil end
+  for _, rel in ipairs(releases) do
+    if not rel.prerelease then return rel end
+  end
+  return releases[1]
+end
+
+-- ------- cache (options.modUpdateCache[repo])
+
+local function cacheStore()
+  local SaveData = require("src.core.SaveData")
+  local opts = SaveData.loadOptions()
+  opts.modUpdateCache = opts.modUpdateCache or {}
+  return opts
+end
+
+function ModUpdate.readCache(repo)
+  if type(repo) ~= "string" or repo == "" then return nil end
+  local ok, opts = pcall(function()
+    return require("src.core.SaveData").loadOptions()
+  end)
+  if not ok or type(opts) ~= "table" then return nil end
+  local entry = opts.modUpdateCache and opts.modUpdateCache[repo]
+  if type(entry) ~= "table" or type(entry.checkedAt) ~= "number" then
+    return nil
+  end
+  if type(entry.releases) ~= "table" then return nil end
+  return entry
+end
+
+function ModUpdate.cacheFresh(entry, now, ttl)
+  now = now or os.time()
+  ttl = ttl or ModUpdate.CACHE_TTL
+  return entry and type(entry.checkedAt) == "number"
+    and (now - entry.checkedAt) < ttl
+end
+
+function ModUpdate.writeCache(repo, releases)
+  if type(repo) ~= "string" or repo == "" then return false end
+  local ok = pcall(function()
+    local SaveData = require("src.core.SaveData")
+    local opts = cacheStore()
+    local best = ModUpdate.pickBest(releases)
+    -- Persist a lean copy: enough to paint the UI and reinstall without
+    -- re-fetching within the TTL.
+    local lean = {}
+    for i, rel in ipairs(releases or {}) do
+      lean[i] = {
+        version = rel.version,
+        tag = rel.tag,
+        name = rel.name,
+        prerelease = rel.prerelease == true,
+        body = type(rel.body) == "string" and rel.body or "",
+        zip = rel.zip and {
+          name = rel.zip.name,
+          url = rel.zip.url,
+          size = rel.zip.size,
+        } or nil,
+      }
+    end
+    opts.modUpdateCache[repo] = {
+      checkedAt = os.time(),
+      latest = best and best.version or nil,
+      releases = lean,
+    }
+    SaveData.saveOptions(opts)
+  end)
+  return ok
+end
+
+-- Status vs an installed version using a cache entry / release list.
+-- Returns "available" | "current" | "unknown".
+function ModUpdate.statusFor(installedVersion, releases)
+  local best = ModUpdate.pickBest(releases)
+  if not best then return "unknown", nil end
+  if ModUpdate.isNewer(installedVersion, best.version) then
+    return "available", best
+  end
+  return "current", best
+end
+
+-- ------- host I/O (HostShell's transport: curl, or the Android JNI bridge)
+
+-- GitHub's API wants a User-Agent and answers the versioned Accept.
+local function apiFetch(url)
+  local HostShell = require("src.core.HostShell")
+  return HostShell.httpGet(url, "gen1recomp-mod-updater",
+    "application/vnd.github+json")
+end
+
+-- Still just the curl probe it always was.  "Can we fetch at all" is
+-- HostShell.canFetch, which also knows about the Android bridge (#597); every
+-- gate below asks that instead.
+function ModUpdate.haveCurl()
+  local HostShell = require("src.core.HostShell")
+  return HostShell.haveCurl()
+end
+
+-- Fetch release list. opts.force bypasses the 6h cache.
+-- Returns releases, err, meta where meta = { fromCache = bool }.
+function ModUpdate.fetchReleases(repo, modId, opts)
+  opts = opts or {}
+  if type(repo) ~= "string" or repo == "" then
+    return nil, "missing github repo"
+  end
+  if not opts.force then
+    local cached = ModUpdate.readCache(repo)
+    if ModUpdate.cacheFresh(cached) then
+      return cached.releases, nil, { fromCache = true }
+    end
+  end
+  local HostShell = require("src.core.HostShell")
+  if not HostShell.canFetch() then
+    -- Stale cache is better than nothing when offline
+    local cached = ModUpdate.readCache(repo)
+    if cached and cached.releases then
+      return cached.releases, nil, { fromCache = true, stale = true }
+    end
+    return nil, "no network transport on this platform"
+  end
+  local body, curlErr = apiFetch(ModUpdate.apiReleasesUrl(repo))
+  if not body then
+    local cached = ModUpdate.readCache(repo)
+    if cached and cached.releases then
+      return cached.releases, nil, { fromCache = true, stale = true }
+    end
+    return nil, curlErr
+  end
+  local list, parseErr = ModUpdate.parseReleases(body, modId)
+  if not list then return nil, parseErr end
+  ModUpdate.writeCache(repo, list)
+  return list, nil, { fromCache = false }
+end
+
+function ModUpdate.downloadZip(url, destName)
+  if type(url) ~= "string" or url == "" then
+    return nil, "missing download url"
+  end
+  if not (love and love.filesystem) then
+    return nil, "download needs LOVE"
+  end
+  local HostShell = require("src.core.HostShell")
+  if not HostShell.canFetch() then
+    return nil, "no network transport on this platform"
+  end
+  local name = destName or ("mod_update_" .. tostring(os.time()) .. ".zip")
+  name = tostring(name):gsub("[/\\]", "_")
+  local saveOk, saveDir = pcall(function()
+    return love.filesystem.getSaveDirectory()
+  end)
+  if not saveOk or not saveDir or saveDir == "" then
+    return nil, "no save directory"
+  end
+  local abs = saveDir .. "/" .. name
+  -- Either transport can fail quietly; the getInfo size check below is what
+  -- actually decides whether we got a file (#597).
+  HostShell.httpDownload(url, abs, "gen1recomp-mod-updater")
+  local infoOk, info = pcall(love.filesystem.getInfo, name)
+  if not infoOk or not info or (info.size or 0) == 0 then
+    pcall(love.filesystem.remove, name)
+    return nil, "download failed"
+  end
+  return name
+end
+
+return ModUpdate

src/mods/Schemas.lua

@@ -1186,11 +1186,13 @@ R.field = {
       nest = f.opt(f.any) },
     flyOrder = f.list(f.str),
     -- the player's own trainer art (FieldDefaults.PLAYER_PICS): the battle
-    -- back pic, the catch tutorial's old man, and the front pic the intro,
-    -- trainer card and Hall of Fame share.  Every key is optional so a
-    -- conversion can replace one pic and inherit the rest.
+    -- back pic, the catch tutorial's old man, Yellow's PROF.OAK variant of
+    -- it (#557), and the front pic the intro, trainer card and Hall of Fame
+    -- share.  Every key is optional so a conversion can replace one pic and
+    -- inherit the rest.
     playerPics = f.rec{
-      back = f.opt(f.str), demoBack = f.opt(f.str), front = f.opt(f.str) },
+      back = f.opt(f.str), demoBack = f.opt(f.str),
+      oakBack = f.opt(f.str), front = f.opt(f.str) },
     -- the new-game and boot config a total conversion replaces
     boot = f.rec{
       startMap = f.opt(f.str), startX = f.opt(f.int(0)), startY = f.opt(f.int(0)),

src/pokemon/Sprites.lua

@@ -46,20 +46,32 @@ end
 -- opts.kind: "battle" | "intro" | "trainer_card" | "hof"
 -- opts.demo: the catch tutorial, where the old man fights in the player's
 --            place and stands in for the back pic
+-- opts.oakDemo: the Yellow variant of that demo (BATTLE_TYPE_PIKACHU), where
+--            PROF.OAK fights in the player's place behind his own back pic
 -- opts.battle: the live battle, for kind == "battle"
 -- Returns path, trueColor.
 function Sprites.playerPath(data, side, opts)
   opts = opts or {}
   side = side == "back" and "back" or "front"
   -- one key per pic, so a conversion can replace the back and inherit the
-  -- rest; fieldValue folds data.field over FieldDefaults per key
+  -- rest; fieldValue folds data.field over FieldDefaults per key.  The two
+  -- demo keys mirror LoadPlayerBackPic's wBattleType branch (#557).
   local key = side == "front" and "front"
+              or (opts.oakDemo and "oakBack")
               or (opts.demo and "demoBack" or "back")
   local path = FieldDefaults.fieldValue(data, "playerPics", key)
+  -- ProfOakPicBack is a Yellow-only rip, so a cache imported before it
+  -- existed has no file there; fall back to the old man rather than hand a
+  -- missing path to getImage (#557)
+  if key == "oakBack" and path
+     and not require("src.render.Assets").exists(path) then
+    path = FieldDefaults.fieldValue(data, "playerPics", "demoBack")
+  end
   local ctx = {
     side = side,
     kind = opts.kind or "battle",
     demo = opts.demo and true or false,
+    oakDemo = opts.oakDemo and true or false,
     battle = opts.battle,
     trueColor = false,
     data = data,