Merge pull request #1601 from bryanthaboi/dev

bug fixes and uncles neighbor

.github/CODEOWNERS

@@ -0,0 +1 @@
+* @bryanthaboi

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -5,6 +5,10 @@ body:
   - type: markdown
     attributes:
       value: |
+        **Turn off all mods before filing.** Disable everything in the launcher's MODS
+        tab, confirm the bug still happens, then open this. Bugs that only show up with
+        mods on belong with the mod author, not here.
+
         A screenshot is worth more than any description. If you can grab one, grab one.
         If you genuinely can't, that's fine, but then the details below need to be thorough
         enough that someone can find the bug without ever seeing your screen.
@@ -51,22 +55,24 @@ body:
     validations:
       required: true
 
-  - type: dropdown
+  - type: checkboxes
-    id: mods_enabled
+    id: mods_off
     attributes:
-      label: Were any mods on
+      label: Mods off
-      description: Check the MODS tab in the launcher if you're not sure.
+      description: >
+        Turn off every mod in the launcher's MODS tab and reproduce the bug
+        before submitting. Do not file vanilla bugs with mods still enabled.
       options:
-        - "No"
+        - label: I turned off all mods and can still reproduce this
-        - "Yes"
-    validations:
           required: true
 
   - type: input
     id: mods_which
     attributes:
-      label: Which mods (if any were on)
+      label: Which mods (if you first noticed this with any on)
-      description: List the enabled mods. Leave blank if none were on.
+      description: >
+        Optional. If you originally hit this with mods enabled, list them —
+        but only after you've confirmed it still happens with all of them off.
       placeholder: nuzlocke 1.0.0, running-shoes 0.3
     validations:
       required: false

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,118 +0,0 @@
-name: Feature request
-description: Ask for something new in the engine, launcher, or platform — not a content/gameplay mod.
-labels: ["enhancement"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Use this for **engine / launcher / platform** work (ports, video options, save
-        tooling, networking, mod API seams, docs).
-
-        If what you want is a gameplay, cosmetic, audio, or QoL change that a Lua mod
-        could ship — running shoes, alternate sprites, day/night, shiny indicators,
-        Gen 2-like battle toggles, soundtrack packs — open a
-        **[Mod request](https://github.com/bryanthaboi/gen1recomp/issues/new?template=mod_request.yml)**
-        instead.
-
-        "Can we add X" on its own is hard to act on. Say what you want, why you want it,
-        and how you picture it working.
-
-  - type: input
-    id: summary
-    attributes:
-      label: One line summary
-      description: What you want, in a sentence.
-      placeholder: Add Linux AppImage releases next to the macOS and Windows builds
-    validations:
-      required: true
-
-  - type: dropdown
-    id: game
-    attributes:
-      label: Which game is this about
-      description: Pick every version it applies to. Use N/A if it isn't game-specific.
-      multiple: true
-      options:
-        - Red
-        - Blue
-        - Yellow
-        - Gold
-        - N/A
-    validations:
-      required: true
-
-  - type: input
-    id: discord
-    attributes:
-      label: Discord username (optional)
-      description: >
-        So maintainers can ping you on Discord if they need a quick follow-up.
-        Leave blank if you'd rather keep everything on GitHub.
-      placeholder: yourname
-    validations:
-      required: false
-
-  - type: textarea
-    id: what
-    attributes:
-      label: What do you want
-      description: >
-        Describe it properly. What is it, where does it live (launcher, options,
-        engine), what does the player see or do. If it changes something that already
-        exists, say what it does today and what it should do instead.
-      placeholder: |
-        Ship a Linux AppImage on each release, same version as the macOS/Windows builds,
-        with the same save folder layout and mod discovery path.
-    validations:
-      required: true
-
-  - type: textarea
-    id: why
-    attributes:
-      label: Why is this worth doing
-      description: >
-        What's annoying or missing right now. What does this fix. If it's just because you
-        think it would be fun, say that, it's a real answer.
-      placeholder: |
-        LÖVE already runs on Linux; without a packaged build, players have to assemble
-        it themselves and miss release notes / update checks.
-    validations:
-      required: true
-
-  - type: textarea
-    id: how
-    attributes:
-      label: How should it work
-      description: >
-        The specifics. Which menu, what happens in the edge cases. If you don't
-        know, say what you'd expect as a player and leave the rest open.
-      placeholder: |
-        - GitHub Releases asset next to the .dmg / .exe
-        - Same options.lua / mods/ layout as desktop
-        - Documented in the README install section
-    validations:
-      required: true
-
-  - type: dropdown
-    id: scope
-    attributes:
-      label: Does this change how the original game plays
-      description: >
-        Some requests are quality of life, some change the actual game. Both are fine,
-        it just helps to know which one you're asking for.
-      options:
-        - Quality of life, original game is untouched
-        - Changes how the game plays
-        - Not sure
-    validations:
-      required: true
-
-  - type: textarea
-    id: extra
-    attributes:
-      label: Anything else
-      description: >
-        Reference screenshots, how another game does it, related issues. Leave blank
-        if nothing comes to mind.
-    validations:
-      required: false

.github/ISSUE_TEMPLATE/mod_request.yml

@@ -1,130 +0,0 @@
-name: Mod request
-description: Ask for a gameplay, cosmetic, audio, or QoL change that belongs as a Lua mod.
-labels: ["mod request"]
-body:
-  - type: markdown
-    attributes:
-      value: |
-        This tracker is for ideas that should ship as **mods**, not as core engine
-        features — alternate sprites, running shoes, day/night, shiny indicators,
-        soundtrack packs, Gen 2-like battle toggles, map cosmetics, bag QoL, etc.
-
-        The engine already exposes a lot of this through registries and hooks
-        ([modding wiki](https://github.com/bryanthaboi/gen1recomp/wiki)).
-        Use a **Feature request** instead for launcher / ports / video options /
-        networking / save tooling / new API seams.
-
-  - type: input
-    id: summary
-    attributes:
-      label: One line summary
-      description: What the mod should do, in a sentence.
-      placeholder: Hold B to run at bike speed on the overworld
-    validations:
-      required: true
-
-  - type: dropdown
-    id: game
-    attributes:
-      label: Which game is this for
-      description: Pick every version the mod should cover. Use N/A if it isn't game-specific.
-      multiple: true
-      options:
-        - Red
-        - Blue
-        - Yellow
-        - Gold
-        - N/A
-    validations:
-      required: true
-
-  - type: input
-    id: discord
-    attributes:
-      label: Discord username (optional)
-      description: >
-        So maintainers or mod authors can ping you on Discord if they pick this up.
-        Leave blank if you'd rather keep everything on GitHub.
-      placeholder: yourname
-    validations:
-      required: false
-
-  - type: textarea
-    id: what
-    attributes:
-      label: What should the mod do
-      description: >
-        Describe the player-facing behavior. What changes, where, what does the
-        player see or press. If it toggles from Options or a START-menu entry, say so.
-      placeholder: |
-        Hold B while walking outdoors to move at bike speed. Release to walk again.
-        Same places the bike is allowed; no effect in battles or menus.
-    validations:
-      required: true
-
-  - type: textarea
-    id: why
-    attributes:
-      label: Why is this worth doing as a mod
-      description: >
-        Why optional/modded rather than a core option. Who wants it on, who wants
-        vanilla left alone.
-      placeholder: |
-        Great for replaying and backtracking, but some people want a strict Gen 1
-        pace. A mod (or an opt-in mod option) keeps both camps happy.
-    validations:
-      required: true
-
-  - type: textarea
-    id: how
-    attributes:
-      label: How should it work
-      description: >
-        Buttons, menus, edge cases, whether it needs new art/audio. If you know a
-        hook or registry that fits (movement.speed, pokemon.sprite, rulesets, …),
-        mention it — otherwise leave it open.
-      placeholder: |
-        - Hold B on the overworld
-        - Same step timing as the bike
-        - Disabled where the bike is disabled
-        - Prefer hooks:wrap("movement.speed") if that still fits
-    validations:
-      required: true
-
-  - type: dropdown
-    id: vanilla
-    attributes:
-      label: With the mod off, is vanilla unchanged
-      options:
-        - Yes — parity when disabled
-        - No — it would replace something always-on
-        - Not sure
-    validations:
-      required: true
-
-  - type: dropdown
-    id: category
-    attributes:
-      label: Best-fit mod category
-      description: Same taxonomy as example mods (BALANCE, GRAPHICS, AUDIO, …).
-      options:
-        - GAMEPLAY / QoL
-        - GRAPHICS
-        - AUDIO
-        - BALANCE / ruleset
-        - CONTENT (maps, encounters, trainers)
-        - UI / TOOL
-        - TOTAL_CONVERSION-ish
-        - Not sure
-    validations:
-      required: true
-
-  - type: textarea
-    id: extra
-    attributes:
-      label: Anything else
-      description: >
-        Reference screenshots, other games/hacks that do it, related issues, or
-        "I'd like to try writing this myself." Leave blank if nothing comes to mind.
-    validations:
-      required: false

.github/workflows/ci.yml

@@ -12,10 +12,11 @@ name: ci
 #
 on:
   push:
-    # Integration branch + release branch. PRs already run via pull_request
-    # (any base); this list is only for post-merge push runs.
     branches: [dev, main]
+  # PRs into dev only: a dev -> main ship PR reuses the required checks the
+  # dev push already put on the same head SHA, so it needs no second run.
   pull_request:
+    branches: [dev]
 
 # a force-push while CI is mid-run should cancel the stale run, not queue
 concurrency:
@@ -120,7 +121,7 @@ jobs:
             echo "changed=true" >> "$GITHUB_OUTPUT"
             exit 0
           fi
-          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_switch\.sh$|scripts/switch/|docs/switch-.*\.md$|tests/switch_ci_workflows_test\.lua$|tests/switch_transfer_docs_test\.lua$|\.github/workflows/(ci|release|switch-artifact-comment)\.yml$|src/core/(NxAssetOverlay|Platform|GameVersion)\.lua$|src/import/CacheFs\.lua$|tests/engine/(assets_version_fallback|nx_generated_guard|nx_yellow_boot|switch_diagnostics)_test\.lua$|tests/engine/platform_nx)'; then
+          if git diff --name-only "$BASE_SHA" "$HEAD_SHA" | grep -Eq '^(scripts/build_switch\.sh$|scripts/switch/|docs/switch-.*\.md$|tests/switch_ci_workflows_test\.lua$|tests/switch_transfer_docs_test\.lua$|\.github/workflows/(ci|release|switch-artifact-comment)\.yml$|src/core/(NxAssetOverlay|Platform|GameVersion)\.lua$|src/import/CacheFs\.lua$|tests/engine/(assets_version_fallback|nx_generated_guard|nx_yellow_boot|switch_diagnostics|cache_fs_gold_nx_load)_test\.lua$|tests/engine/platform_nx)'; then
             echo "changed=true" >> "$GITHUB_OUTPUT"
           else
             echo "changed=false" >> "$GITHUB_OUTPUT"
@@ -151,6 +152,9 @@ jobs:
           luajit tests/engine/assets_version_fallback_test.lua
           luajit tests/engine/nx_generated_guard_test.lua
           luajit tests/engine/nx_yellow_boot_test.lua
+          luajit tests/engine/cache_fs_gold_nx_load_test.lua
+          luajit tests/engine/cache_fs_blue_mount_test.lua
+          luajit tests/engine/switch_diagnostics_test.lua
 
   switch-build:
     name: Switch fused build
@@ -315,52 +319,10 @@ jobs:
         run: |
           set -euo pipefail
           scripts/build_linux_arm64.sh --version 0.0.0
+      # Shared with the release workflow so shipped images get the same
+      # self-contained / glibc-floor checks as PR builds.
       - name: Verify the AppImage is self-contained and bullseye-compatible
-        run: |
+        run: bash scripts/linux-arm64/verify_appimage.sh dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage
-          set -euo pipefail
-          image="dist/linux-arm64/gen1recomp-0.0.0-linux-arm64.AppImage"
-
-          # --appimage-extract needs no FUSE, so this works on a runner
-          # without /dev/fuse and still exercises the real payload.
-          "$image" --appimage-extract >/dev/null
-          for required in AppRun bin/love game.love lib/liblove-11.5.so; do
-            [ -e "squashfs-root/$required" ] \
-              || { echo "::error::AppImage is missing $required"; exit 1; }
-          done
-
-          # Every bundled object must resolve once AppRun's LD_LIBRARY_PATH is
-          # applied; an unresolved soname here is a user-visible launch crash.
-          #
-          # This runs on a HEADLESS runner on purpose, and that is the point.
-          # The first version of this build bundled Debian's SDL2, which
-          # hard-links libpulse/libasound/libX11/libwayland, so it only ever
-          # started on a full desktop -- a bare runner is what exposed it.
-          missing="$(LD_LIBRARY_PATH="$PWD/squashfs-root/lib" \
-            ldd squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
-            | grep 'not found' || true)"
-          [ -z "$missing" ] || { echo "::error::unresolved deps:"; echo "$missing"; exit 1; }
-
-          # Nothing may hard-link a driver, session or audio-stack library:
-          # those must be reached through dlopen so the AppImage runs on a box
-          # with only ALSA, only Wayland, or only KMSDRM.
-          linked="$(for f in squashfs-root/bin/love squashfs-root/lib/*.so*; do
-            objdump -p "$f" 2>/dev/null | awk '/NEEDED/{print $2}'
-          done | sort -u | grep -E '^lib(pulse|asound|X11|wayland|GL|EGL|drm|gbm|xcb|cairo|sndio|dbus)' || true)"
-          [ -z "$linked" ] \
-            || { echo "::error::these must be dlopened, not linked:"; echo "$linked"; exit 1; }
-
-          # The whole point of compiling on bullseye. If a future change moves
-          # the builder to a newer base, the glibc floor silently rises and
-          # every user on an older distro gets "GLIBC_2.xx not found" -- catch
-          # it here instead of in a release.
-          floor="$(objdump -T squashfs-root/bin/love squashfs-root/lib/*.so* 2>/dev/null \
-            | grep -o 'GLIBC_[0-9.]*' | sort -V | tail -1)"
-          echo "highest required glibc symbol version: $floor"
-          [ -n "$floor" ] \
-            || { echo "::error::found no versioned glibc symbols -- objdump read nothing"; exit 1; }
-          highest="$(printf '%s\n' "$floor" "GLIBC_2.31" | sort -V | tail -1)"
-          [ "$highest" = "GLIBC_2.31" ] \
-            || { echo "::error::AppImage requires $floor, above the bullseye 2.31 floor"; exit 1; }
       - name: Upload the AppImage
         uses: actions/upload-artifact@v7
         with:
@@ -397,7 +359,6 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v7
-      - run: sudo apt-get update && sudo apt-get install -y luajit
       - run: python3 -m pip install --upgrade pillow
 
       # the fixture PNGs are committed (they are 8x8 placeholders, not
@@ -418,13 +379,8 @@ jobs:
           print(f"\n{len(paths)} fixture assets valid")
           PY
 
-      # the fingerprint golden is the parity tripwire; prove it still
+      # the fingerprint parity gates (gate_fingerprint / gate_meta_coverage)
-      # matches the dataset on a clean checkout
+      # run in the headless job via run_engine; this job only guards the PNGs
-      - name: fingerprint gate
-        run: luajit tests/engine/gate_fingerprint.lua
-
-      - name: parity-guarantee meta-test
-        run: luajit tests/engine/gate_meta_coverage.lua
 
   # Only the differ is under test here, and the job is named for that.  The
   # capture half of the golden pipeline does not exist: a POKEPORT_DRIVER

.github/workflows/release.yml

@@ -161,6 +161,8 @@ jobs:
           scripts/build_linux_arm64.sh \
             --version "${{ needs.version.outputs.version }}" \
             --game-love .bazinga/work/game.love
+      - name: Verify the AppImage is self-contained and bullseye-compatible
+        run: bash scripts/linux-arm64/verify_appimage.sh "dist/linux-arm64/gen1recomp-${{ needs.version.outputs.version }}-linux-arm64.AppImage"
       - name: Upload Linux arm64 release
         uses: actions/upload-artifact@v7
         with:
@@ -285,7 +287,7 @@ jobs:
           retention-days: 1
 
   release:
-    needs: [version, xbox-uwp, linux-arm64, native-tls-win]
+    needs: [version, love-payload, xbox-uwp, linux-arm64, native-tls-win]
     runs-on: ${{ fromJSON(github.repository == 'bryanthaboi/gen1recomp' && '["self-hosted", "macOS"]' || '"macos-latest"') }}
 
     steps:
@@ -307,6 +309,15 @@ jobs:
           name: gen1tls-win-x64
           path: dist/native/win-x64
 
+      # The same game.love the arm64 AppImage and Xbox UWP builds fused, so
+      # every release asset ships one identical payload (build.sh's own pack
+      # would omit PATCH_NOTES.md and mobile/ios/app-repo.json).
+      - name: Download shared payload
+        uses: actions/download-artifact@v8
+        with:
+          name: gen1recomp-release-love
+          path: dist/payload
+
       - name: Import signing certificate into a temporary keychain
         if: github.repository == 'bryanthaboi/gen1recomp'
         run: |
@@ -357,7 +368,8 @@ jobs:
             echo "::error::gen1tls.dll missing at $GEN1TLS_DLL (native-tls-win job)"
             exit 1
           fi
-          scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize
+          scripts/build.sh all --version "${{ needs.version.outputs.version }}" --no-notarize \
+            --game-love dist/payload/game.love
           unzip -l dist/win/gen1recomp-win64.zip | grep -F gen1tls.dll \
             || { echo "::error::Windows zip is missing gen1tls.dll"; exit 1; }
 

CONTRIBUTING-mods.md

@@ -140,17 +140,17 @@ ship text.
 
 ### 4. `games` (and the legacy `gen2compat`)
 
-Pokemon Gold is Gen 2, and it runs its own battle engine, overworld, script
+Pokemon Gold and Silver are Gen 2, and they run their own battle engine,
-VM and save format. The mod API is shared across both generations (same hook
+overworld, script VM and save format. The mod API is shared across both
-names, same event names, same registry names) but Gold cannot serve all of it
+generations (same hook names, same event names, same registry names) but Gen 2
-yet, so Gen 2 is opt-in. Say which games the mod is for:
+cannot serve all of it yet, so it is opt-in. Say which games the mod is for:
 
 ```json
 "games": ["gen1", "gen2"]
 ```
 
-Each entry is a version id (`"red"`, `"blue"`, `"yellow"`, `"gold"`), a
+Each entry is a version id (`"red"`, `"blue"`, `"yellow"`, `"gold"`,
-generation (`"gen1"`, `"gen2"`) or `"all"`;
+`"silver"`), a generation (`"gen1"`, `"gen2"`) or `"all"`;
 `src/mods/ModTargets.lua` resolves them off `GameVersion.ORDER` so nothing
 restates the game list. `python3 tools/modkit.py scaffold my_mod --games
 gen1,gen2` writes the key for you. The mod still installs to one directory,
@@ -159,10 +159,10 @@ gen1,gen2` writes the key for you. The mod still installs to one directory,
 Absent means Gen 1 only, which is what every mod written before the key existed
 was tested as. `"gen2compat": true` is the legacy spelling, still accepted and
 purely additive (it *adds* the Gen 2 games), so no manifest can lose a game it
-already ran on. On a Gold boot a mod claiming no Gen 2 game is not loaded at
+already ran on. On a Gold or Silver boot a mod claiming no Gen 2 game is not
-all: the manager lists it as `ENABLED (NOT THIS GAME)` and says why, because a
+loaded at all: the manager lists it as `ENABLED (NOT THIS GAME)` and says why,
-mod that half-applies reads as a broken mod. Claim Gen 2 once you have actually
+because a mod that half-applies reads as a broken mod. Claim Gen 2 once you
-run your mod on Gold.
+have actually run your mod on Gold or Silver.
 
 Every token is enforced, per game: the loader gates on the same
 `ModTargets.supports` answer both mod surfaces draw, so `"games": ["blue"]`
@@ -173,7 +173,7 @@ before the key existed changes behavior; list both generations or say `"all"`
 when you mean everywhere.
 
 `docs/mod-api-gen2-compat.md` is the compatibility matrix: what works on Gold
-today (40 of the 46 registries, 40 event and 43 hook names shared with Gen 1,
+and Silver today (40 of the 46 registries, 40 event and 43 hook names shared with Gen 1,
 and 24 Gen 2-only ones), which registries have no Gen 2 home and drop their
 writes with a report, and which hooks and events are still to come.
 `docs/preparing-your-mod-for-gen2.md` is the step-by-step migration guide for a

README.md

@@ -9,7 +9,7 @@ And before you say, "that's not a recomp", you're wrong. Recomp is an acronym. *
 [Click Here for the AI Use Disclosure!](AIDisclosure.md)
 
 > [!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.
+> **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. Also, as I assumed would eventually happen, the idiot that made that website now pumped it full of adware. Please stay away from that website.
 
 <p align="center"><img src="https://raw.githubusercontent.com/bryanthaboi/gen1recomp/refs/heads/dev/assets/logo/logo.png"></p>
 
@@ -53,18 +53,17 @@ And before you say, "that's not a recomp", you're wrong. Recomp is an acronym. *
 
 ### Watch the latest update video
 
-[![Watch the latest update video](https://img.youtube.com/vi/8IOgqbe4YvA/maxresdefault.jpg)](https://www.youtube.com/watch?v=8IOgqbe4YvA)
+[![Watch the latest update video](https://img.youtube.com/vi/yi7LkWQPKKM/maxresdefault.jpg)](https://youtu.be/yi7LkWQPKKM)
-
 
 This project does not include a ROM, emulate the Game Boy, transpile assembly,
-or download a disassembly. A canonical US Poke Red, Blue, Yellow, or Gold ROM
+or download a disassembly. A canonical US Poke Red, Blue, Yellow, Gold, or
-is the only game content input.
+Silver ROM is the only game content input.
 
 The ROM is verified, used during import, and then released from memory. It is
 not copied into the cache. Later launches load the private generated cache and
-do not ask for the ROM again. Red, Blue, Yellow, and Gold can all be imported
+do not ask for the ROM again. Red, Blue, Yellow, Gold, and Silver can all be
-side by side. Gold is Gen 2 Phase 1 (import + launcher; see
+imported side by side. Gold and Silver are Gen 2 Phase 1 (import + launcher;
-`docs/gold-phase1.md`): the Gen 2 engine is still under construction.
+see `docs/gold-phase1.md`): the Gen 2 engine is still under construction.
 
 ## Quick Start
 
@@ -72,13 +71,14 @@ Open the desktop app. On first boot, choose your legally obtained `.gb` /
 `.gbc` file or drop it onto the window. Import takes a few seconds and the
 game starts automatically.
 
-Only the canonical US Red, Blue, Yellow (1 MiB), and Gold (2 MiB) ROMs are
+Only the canonical US Red, Blue, Yellow (1 MiB), Gold, and Silver (2 MiB)
-accepted. The importer verifies SHA-1 before creating any game data:
+ROMs are accepted. The importer verifies SHA-1 before creating any game data:
 
 - Red: `ea9bcae617fdf159b045185467ae58b2e4a48b9a`
 - Blue: `d7037c83e1ae5b39bde3c30787637ba1d4c48ce2`
 - Yellow: `cc7d03262ebfaf2f06772c1a480c7d9d5f4a38e1`
 - Gold: `d8b8a3600a465308c9953dfa04f0081c05bdcb94`
+- Silver: `49b163f7e57702bc939d642a18f591de55d92dae`
 
 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
@@ -219,7 +219,7 @@ entry: a desktop shortcut per game, a Steam entry, or a handheld frontend.
 
 | Option | Effect |
 | --- | --- |
-| `--game=red` | boot Red, skipping the launcher (`blue` and `yellow` too, or just `r` / `b` / `y`) |
+| `--game=red` | boot Red, skipping the launcher (`blue`, `yellow`, `gold` and `silver` too, or just `r` / `b` / `y` / `g` / `s`) |
 | `--slot=2` | load that save slot; takes a slot number or a slot id |
 | `--launcher` | open the launcher anyway, so you can edit a shortcut you already made |
 
@@ -332,7 +332,7 @@ Maps can be edited in our own build of [Tiled](https://www.mapeditor.org),
 and exported back out as a mod; see
 [docs/tiled-map-editing.md](docs/tiled-map-editing.md).
 
-## Bugs and Ideas
+## Bugs
 
 Found a bug? A warp dropping you somewhere it shouldn't, a battle doing math
 that looks wrong, text in the wrong box, anything that does not match the
@@ -341,12 +341,6 @@ original game.
 Attach a screenshot if you can. It saves a lot of back and forth, and if you
 can't get one, the form asks you to describe what you saw instead.
 
-Thought of a feature that could be good, or a way to improve one that already
-exists?
-[Open a feature request](https://github.com/bryanthaboi/gen1recomp/issues/new?template=feature_request.yml).
-Say what you want, why it is worth doing, and how you picture it working. A
-request with real detail is one that can actually get built.
-
 ## More
 
 - [Link play](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Link-Play)
@@ -354,7 +348,8 @@ request with real detail is one that can actually get built.
 - [Save editor](https://github.com/bryanthaboi/gen1recomp/wiki/Guide-Save-Editor)
 — edit party, boxes, items, events, and Pokédex flags outside the game.
 - `docs/architecture.md` — runtime details;
-`docs/behavior-porting-notes.md` — formula provenance.
+`docs/behavior-porting-notes.md` — formula provenance;
+`docs/link-security.md` — what link play defends against, and what it doesn't.
 
 
 

build-linux-arm-sbc.sh

@@ -133,6 +133,8 @@ mkdir -p "$GAME_SRC"
 (cd "$SOURCE_DIR" && zip -q -9 -r "$WORK/game-payload.zip" \
   main.lua conf.lua src libs data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
+  tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  tools/rom_manifest_silver.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 if unzip -Z1 "$WORK/game-payload.zip" \
     | grep -Eq '^(data|assets)/generated/[^/]+|^(data|assets)/generated/.+/'; then

build-rg34xxsp.sh

@@ -92,6 +92,7 @@ mkdir -p "$GAME_SRC"
   main.lua conf.lua src libs data assets tools/save-editor \
   tools/rom_manifest.json tools/rom_manifest_blue.json \
   tools/rom_manifest_yellow.json tools/rom_manifest_gold.json \
+  tools/rom_manifest_silver.json \
   -x '*.DS_Store' 'data/generated/*' 'assets/generated/*')
 payload_list="$(unzip -Z1 "$WORK/game-payload.zip")"
 printf '%s\n' "$payload_list" \
@@ -99,6 +100,8 @@ printf '%s\n' "$payload_list" \
   && fail "payload unexpectedly contains generated ROM data"
 printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_gold.json" \
   || fail "payload is missing tools/rom_manifest_gold.json"
+printf '%s\n' "$payload_list" | grep -qxF "tools/rom_manifest_silver.json" \
+  || fail "payload is missing tools/rom_manifest_silver.json"
 unzip -q "$WORK/game-payload.zip" -d "$GAME_SRC"
 rm -f "$WORK/game-payload.zip"
 
@@ -193,6 +196,26 @@ get_controls
 [ -f "${controlfolder}/mod_${CFW_NAME}.txt" ] && source "${controlfolder}/mod_${CFW_NAME}.txt"
 
 GAMEDIR="$SHDIR/gen1recomp"
+# Anbernic stock keeps the launcher and the game folder side by side, so the
+# SHDIR-relative path above is correct there and is tried first.
+#
+# Other firmwares (muOS, and PortMaster's layout on several devices) keep
+# launcher scripts and port data in SEPARATE trees -- scripts under roms/ports,
+# data under ports -- so the sibling folder holds no game.
+#
+# Probe for the BINARY, not the directory: on a split layout this script has
+# usually already created "$SHDIR/gen1recomp/conf" and log.txt on an earlier
+# failed run (see mkdir/tee below), so an existence test matches a decoy of our
+# own making. Stock is unaffected -- its sibling holds the real binary and wins
+# on the first test.
+if [ ! -f "$GAMEDIR/bin/love.aarch64" ]; then
+  for candidate in "/$directory/ports/gen1recomp" \
+                   "/mnt/sdcard/ports/gen1recomp" \
+                   "/mnt/mmc/ports/gen1recomp" \
+                   "/roms/ports/gen1recomp"; do
+    if [ -f "$candidate/bin/love.aarch64" ]; then GAMEDIR="$candidate"; break; fi
+  done
+fi
 CONFDIR="$GAMEDIR/conf"
 mkdir -p "$CONFDIR"
 

data/scripts/celadon_eevee.lua

@@ -25,8 +25,10 @@
 local Menu = require("src.ui.Menu")
 local TextBox = require("src.render.TextBox")
 
--- TMNotebookText (data/text/text_2.asm) has no leading underscore, so the
+-- TMNotebookText (data/text/text_2.asm) has no leading underscore, but the
--- extractor never collects it and the pamphlet's text is inlined.
+-- extractor now collects any top-level label in a dedicated text file
+-- regardless (tools/extract/text.py), so this is the real ROM label --
+-- the literal below is only the fallback for a catalog without it.
 local TM_NOTEBOOK_TEXT = "It's a pamphlet\non TMs.\f...\f"
   .. "There are 50 TMs\nin all.\f"
   .. "There are also 5\nHMs that can be\vused repeatedly.\f"
@@ -70,7 +72,8 @@ return {
       return true
     end
     if fx == 3 and fy == 4 then
-      game.stack:push(TextBox.new(game, TM_NOTEBOOK_TEXT))
+      local text = game.data.text or {}
+      game.stack:push(TextBox.new(game, text.TMNotebookText or TM_NOTEBOOK_TEXT))
       return true
     end
     return false

data/scripts/flavor/bike_shop.lua

@@ -5,8 +5,27 @@
 -- voucher exchange and the BICYCLE/CANCEL price window need more than
 -- command rows (#568).
 
+local TextBox = require("src.render.TextBox")
+
+-- data/events/hidden_events.asm:542
+local BIKE_DISPLAYS = {
+  { 1, 0 }, { 2, 1 }, { 1, 2 }, { 3, 2 }, { 0, 4 }, { 1, 5 },
+}
+
 return {
   BIKE_SHOP = {
+    -- engine/events/hidden_events/new_bike.asm:1
+    onInteract = function(game, ow, fx, fy)
+      for _, c in ipairs(BIKE_DISPLAYS) do
+        if c[1] == fx and c[2] == fy then
+          game.stack:push(TextBox.new(game,
+            (game.data.text or {})._NewBicycleText or "A shiny new\nBICYCLE!"))
+          return true
+        end
+      end
+      return false
+    end,
+
     talk = {
       -- BikeShopMiddleAgedWomanText (pokered/scripts/BikeShop.asm):
       -- always shows the same flavor line, no branching.

data/scripts/flavor/ss_anne_kitchen.lua

@@ -15,10 +15,10 @@ return {
       -- pick the dish: bit 7 set (~50%) -> Salmon du Salad, else bit 4
       -- set (~25%) -> Eels au Barbecue, else (~25%) -> Prime Beef Steak.
       -- The three dish texts (SSAnneKitchenCook7SalmonDuSaladText /
-      -- ...EelsAuBarbecueText / ...PrimeBeefSteakText) aren't extracted
+      -- ...EelsAuBarbecueText / ...PrimeBeefSteakText) have no leading
-      -- into data/generated/text.lua (no leading underscore in
+      -- underscore in pokered/text/SSAnneKitchen.asm, but the extractor
-      -- pokered/text/SSAnneKitchen.asm), so their literal strings are
+      -- collects them regardless (tools/extract/text.py); the literals
-      -- ported here verbatim.
+      -- below are only the fallback for a catalog without them.
       TEXT_SSANNEKITCHEN_COOK7 = function(game, ow, npc, done)
         local t = game.data.text
         push(game, t._SSAnneKitchenCook7MainCourseIsText
@@ -27,13 +27,16 @@ return {
           local dish
           if roll <= 2 then
             -- bit 7 of hRandomAdd set (~50%)
-            dish = "Salmon du Salad!\fLes guests may\ngripe it's fish\vagain, however!"
+            dish = t.SSAnneKitchenCook7SalmonDuSaladText
+              or "Salmon du Salad!\fLes guests may\ngripe it's fish\vagain, however!"
           elseif roll == 3 then
             -- bit 4 set, bit 7 clear (~25%)
-            dish = "Eels au Barbecue!\fLes guests will\nmutiny, I fear."
+            dish = t.SSAnneKitchenCook7EelsAuBarbecueText
+              or "Eels au Barbecue!\fLes guests will\nmutiny, I fear."
           else
             -- neither bit set (~25%)
-            dish = "Prime Beef Steak!\fBut, have I enough\nfillets du beef?"
+            dish = t.SSAnneKitchenCook7PrimeBeefSteakText
+              or "Prime Beef Steak!\fBut, have I enough\nfillets du beef?"
           end
           push(game, dish, done)
         end)

data/scripts/flavor/viridian_city.lua

@@ -60,22 +60,23 @@ M.VIRIDIAN_CITY = {
     -- you want to know about the two kinds of caterpillar Pokemon;
     -- YES -> CATERPIE/WEEDLE description, NO -> "Oh, OK then!".
     -- ViridianCityYoungster2OkThenText and
-    -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are
+    -- ViridianCityYoungster2CaterpieAndWeedleDescriptionText are defined
-    -- defined without a leading underscore in pokered/text/ViridianCity.asm
+    -- without a leading underscore in pokered/text/ViridianCity.asm, but
-    -- and aren't present in data/generated/text.lua, so we fall back to
+    -- tools/extract/text.py now collects them regardless -- the literal
-    -- the literal strings from pokered.  Those fallbacks have to carry the
+    -- strings below are only the fallback for a catalog without them.
-    -- extractor's markers, not plain newlines: line -> \n, cont -> \v,
+    -- Those fallbacks have to carry the extractor's markers, not plain
-    -- para -> \f.  Spelling cont/para as \n and \n\n put all six lines on
+    -- newlines: line -> \n, cont -> \v, para -> \f.  Spelling cont/para as
-    -- one page with nothing to wait on, so the whole speech scrolled past
+    -- \n and \n\n put all six lines on one page with nothing to wait on,
-    -- without a button press (#250).
+    -- so the whole speech scrolled past without a button press (#250).
     TEXT_VIRIDIANCITY_YOUNGSTER2 = function(game, ow, npc, done)
       local t = text(game)
       ask(game, t._ViridianCityYoungster2YouWantToKnowAboutText
         or "You want to know\nabout the 2 kinds\vof caterpillar\vPOKéMON?", function(yes)
         if yes then
-          push(game, "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
+          push(game, t.ViridianCityYoungster2CaterpieAndWeedleDescriptionText
+            or "CATERPIE has no\npoison, but\vWEEDLE does.\fWatch out for its\nPOISON STING!", done)
         else
-          push(game, "Oh, OK then!", done)
+          push(game, t.ViridianCityYoungster2OkThenText or "Oh, OK then!", done)
         end
       end)
     end,

data/scripts/oaks_lab.lua

@@ -168,6 +168,7 @@ return {
       { "jump_if_true", "come_see" },
       { "set_flag", "EVENT_GOT_POKEBALLS_FROM_OAK" },
       { "give_item", "POKE_BALL", 5, false },
+      { "text_sound", "Get_Key_Item" },  -- OaksLab.asm:1060
       { "show_text", "_OaksLabOak1ReceivedPokeballsText" },
       { "show_text", "_OaksLabGivePokeballsExplanationText" },
       { "jump", "end" },

data/scripts/story2.lua

@@ -733,7 +733,8 @@ local function museumClerk(game, ow, done, onDecline)
   local t = game.data.text or {}
   if game.save.flags.EVENT_BOUGHT_MUSEUM_TICKET then
     game.stack:push(TextBox.new(game,
-      "Take your time,\nand enjoy it all!", done))
+      t._Museum1FScientist1TakePlentyOfTimeText
+        or "Take your time,\nand enjoy it all!", done))
     return
   end
   -- scripts/Museum1F.asm:72
@@ -751,10 +752,12 @@ local function museumClerk(game, ow, done, onDecline)
           { money = money }))
       elseif yes then
         game.stack:push(TextBox.new(game,
-          "You don't have\nenough money.", onDecline or done, { money = money }))
+          t._Museum1FScientist1DontHaveEnoughMoneyText
+            or "You don't have\nenough money.", onDecline or done, { money = money }))
       else
         game.stack:push(TextBox.new(game,
-          "Come again!", onDecline or done, { money = money }))
+          t._Museum1FScientist1ComeAgainText
+            or "Come again!", onDecline or done, { money = money }))
       end
     end }))
 end

data/scripts/story4.lua

@@ -516,7 +516,17 @@ M.ROUTE_24 = {
           push(game, text(game)._Route24CooltrainerM1YouCouldBecomeATopLeaderText,
             done)
         else
-          ow:engageTrainer(npc, done)
+          -- scripts/Route24.asm:125
+          ow:engageTrainer(npc, function()
+            if ow:trainerDefeated(npc) then
+              -- scripts/Route24.asm:62
+              push(game,
+                text(game)._Route24CooltrainerM1YouCouldBecomeATopLeaderText,
+                done)
+            else
+              done()
+            end
+          end, text(game)._Route24CooltrainerM1DefeatedText, true)
         end
       end
       if not flags.EVENT_GOT_NUGGET then

data/scripts/story5.lua

@@ -122,9 +122,8 @@ M.CINNABAR_LAB_METRONOME_ROOM = {
 -- TM42 Dream Eater (scripts/ViridianCity.asm, the fisher).  The fisher's
 -- YouCanHaveThisText prints before GiveItem, so this gift needs a pre
 -- text (#775).  Like the SilphCo2F worker (#393) that label carries no
--- leading underscore, and on Red it sits outside the extractor's symbol
+-- leading underscore; tools/extract/text.py now collects it regardless,
--- set, so the literal from text/ViridianCity.asm rides along as the
+-- so preFallback below is just the safety net for a catalog without it.
--- fallback; Yellow resolves the ROM string instead.
 M.VIRIDIAN_CITY = {
   talk = {
     TEXT_VIRIDIANCITY_FISHER = gift({
@@ -146,9 +145,11 @@ M.SILPH_CO_2F = {
   talk = {
     TEXT_SILPHCO2F_SILPH_WORKER_F = gift({
       flag = "EVENT_GOT_TM36", item = "TM_SELFDESTRUCT",
-      -- the label carries no leading underscore: pokered keeps this one in
+      -- the label carries no leading underscore (#393); collected like any
-      -- the script bank, not the far-text bank (#393)
+      -- other text/*.asm label now, preFallback is just the safety net
       pre = "SilphCo2FSilphWorkerFPleaseTakeThisText",
+      preFallback = "Eeek!\nNo! Stop! Help!\fOh, you're not\nwith TEAM ROCKET."
+        .. "\vI thought...\vI'm sorry. Here,\vplease take this!",
       received = "_SilphCo2FSilphWorkerFReceivedTM36Text",
       explain = "_SilphCo2FSilphWorkerFTM36ExplanationText",
       noRoom = "_SilphCo2FSilphWorkerFTM36NoRoomText",

data/scripts/story6.lua

@@ -7,9 +7,9 @@ local M = {}
 
 local function text(game) return game.data.text end
 
-local function push(game, s, done)
+local function push(game, s, done, opts)
   local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, s, done))
+  game.stack:push(TextBox.new(game, s, done, opts))
 end
 
 -- PrintText on a text_end string returns with the box still drawn and
@@ -236,7 +236,6 @@ M.CINNABAR_GYM = {
           if yes == machine.yes then
             -- CinnabarGymQuizCorrectText: item jingle, then the gate
             -- slides open (SFX_GO_INSIDE) if it was still locked
-            Sound.play(game.data, "Get_Item1")
             push(game, t._CinnabarGymQuizCorrectText
               or "You're absolutely\ncorrect!\fGo on through!", function()
               if not game.save.flags[gymGateFlag(index)] then
@@ -244,7 +243,9 @@ M.CINNABAR_GYM = {
                 Sound.play(game.data, "Go_Inside")
               end
               applyGymGates(game, ow)
-            end)
+            end, { preSound = function()
+              return Sound.play(game.data, "Get_Item1")
+            end })
             return
           end
           Sound.play(game.data, "Denied")

data/scripts/yellow_beach_house.lua

@@ -17,9 +17,9 @@ local function surfingPikachu(game)
   return nil
 end
 
-local function push(game, text, done)
+local function push(game, text, done, opts)
   local TextBox = require("src.render.TextBox")
-  game.stack:push(TextBox.new(game, text, done))
+  game.stack:push(TextBox.new(game, text, done, opts))
 end
 
 -- the two-variant posters: the surf-capable line once a surfing
@@ -69,11 +69,11 @@ return {
 
       TEXT_SUMMERBEACHHOUSE_PIKACHU = function(game, ow, npc, done)
         local t = game.data.text
+        -- scripts/SummerBeachHouse.asm:68
         push(game, t._SummerBeachHousePikachuText or "PIKACHU: Pikaa!",
-          function()
+          done, { auto = { wait = true, delay = 0, sound = function()
-            require("src.core.Sound").playCry(game.data, "PIKACHU")
+            return require("src.core.Sound").playCry(game.data, "PIKACHU")
-            done()
+          end } })
-          end)
       end,
 
       TEXT_SUMMERBEACHHOUSE_POSTER1 = poster(1),

docs/link-security.md

@@ -0,0 +1,120 @@
+# Link play: threat model and what the code actually guarantees
+
+Link play is the only part of this game that reads bytes written by
+somebody else. This is what it defends against, what it does not, and
+where each guarantee lives.
+
+## The boundary
+
+Everything a peer or the relay sends arrives as one JSON object per line.
+There is exactly one place it becomes a message:
+
+    src/link/Net.lua        reads bytes, frames lines, decodes JSON
+    src/link/Wire.lua       rebuilds each line as a typed message
+    src/link/Session.lua    the only path from a transport into a mode
+
+`Session:update` runs `Wire.sanitize` on every message before anything
+else sees it. A schema returns a **new** table holding only the fields it
+names, at the Lua types it names, so the rest of `src/link/` can read
+`msg.slot`, `msg.parts.actives` or `msg.mons[i].dvs.hp` directly and be
+right by construction. A message with no schema (a mod's, or a future
+build's) keeps a bounded, scalar-only copy of its payload instead of
+being dropped.
+
+A message that fails its schema is **dropped and logged**, never fatal.
+Latching a terminal failure would hand a hostile peer a cheaper
+disconnect than sending nothing at all.
+
+### Why the bounds are loose
+
+Wire's numeric bounds are deliberately wider than the game's own clamps in
+`Protocol.unpackMon`. Both peers run identical clamps over identical
+packets; a bound that bit an honest value would change one side's copy of
+a mon and desync the lockstep. Wire's job is types and sizes. Rules are
+`Protocol`'s job, and it keeps its own clamps for the callers that reach
+it without a Session (the mod API, `tests/`).
+
+### Containment behind it
+
+Assume something still gets through:
+
+- `Game:step` pcalls the link pump, and pcalls `stack:update` **only
+  while a link session is active**. On a throw, `Game:breakLink` closes
+  the connection, unwinds to the overworld and says "The link was
+  broken." Outside link play the stack is unguarded on purpose: a blanket
+  pcall would swallow real engine bugs and leave the game silently wrong
+  instead of loudly broken.
+- `Net` caps `rxBuf` at 256KB and its per-frame read at 512KB, so a peer
+  that never sends a newline ends as a clean disconnect.
+- `Json.decode` refuses documents nested past 64 levels, and takes an
+  optional length cap that the link path passes and the mod-manifest path
+  does not.
+
+## The relay (`../pokeserver`)
+
+- A line that is not a JSON **object** with a string `type` is dropped
+  before any handler runs, and `onLine` is wrapped in try/catch.
+  `server.js` installs `uncaughtException`/`unhandledRejection` handlers:
+  one bad packet must never take every live match down with the process.
+- Line buffers are capped, lines per second are capped, connections per
+  IP and in total are capped, and an unbound connection that never hosts
+  or joins is swept after 30s.
+- `SERVER_ONLY` is the set of message types the server is the only
+  legitimate author of (`peer_gone`, `bracket_update`, `match_start`,
+  `tournament_over`, `spectate`, ...). A peer that sends one has them
+  dropped rather than forwarded, so a bracket opponent cannot forge a
+  tournament result or fake "your opponent left".
+- Trainer names are reduced to a printable subset and capped at the same
+  10 characters the game enforces, on the way in, because they are
+  rendered by the dashboard and broadcast to every participant.
+
+`pokeserver/test/hostile.js` is the regression net for all of that.
+
+## What is NOT defended
+
+**Party legality is trust-the-client.** Online play meets strangers, and
+`Handshake.onlineAllowed` is a Lua function in the same VM the mods load
+into. It cannot be made tamper-proof in-process, and pretending otherwise
+would only cost honest mod authors. What lockstep and
+`Protocol.unpackMon`'s recompute-from-species-data *do* guarantee is that
+a cheater cannot invent stats, moves, or a shiny: every derived value is
+rebuilt locally from real species data. They can send a legal party they
+farmed or edited. That is the honest boundary.
+
+What the relay does instead is **observe and record**. It already sees
+every `hello`, so it keeps each connection's self-reported
+`engineVersion`, `fingerprint` and `linkModified`, compares the two sides
+of a room or a live tournament match, and logs and surfaces a
+`modded` / `fingerprint_mismatch` / `version_skew` flag on the dashboard.
+A patched client can still lie; what it cannot do is lie without the
+tournament organizer having a record of it.
+
+Client-side attestation is deliberately not built. This is an
+open-source Lua game: it would be theater, and it would break honest
+mods.
+
+**The relay has no TLS.** Port 7778 is plaintext, so party contents,
+trades and trainer names are visible to anyone on the network path. There
+is nothing secret in a Pokemon party, but it is a real property of the
+system and not an oversight. Fixing it means a TLS terminator in front of
+the relay and a client that speaks it, which is a version break for every
+shipped build.
+
+**The dashboard has no default password.** `DASHBOARD_PASSWORD` is
+required; with it unset the relay runs and the dashboard simply does not
+start. It is still Basic Auth over plain HTTP, so it belongs behind an
+IP restriction or an SSH tunnel (`pokeserver/DEPLOY.md`).
+
+## Tests
+
+    luajit tests/link_hostile.lua        every message type x every wrong type
+    luajit tests/link_desync_fuzz.lua    lockstep fuzz, plus a mutation mode
+    luajit tests/run_link_tests.lua      both of the above, plus the rest
+    cd ../pokeserver && npm test         relay smoke, 16-player bracket, hostile
+
+`tests/link_hostile.lua` builds its corpus from a template per message
+type, replaces each field (and several nested ones) with every wrong Lua
+type, and drives the survivors through the real trade session, a real
+lockstep battle, a real spectator battle, and the tournament screen
+**including its draw** -- because the two nastiest payloads are
+delayed-fuse ones that crash on render rather than on receipt.

docs/linux-arm64-build.md

@@ -105,8 +105,9 @@ trixie.
 This is a statement about the *compile environment*, not about where the
 artifact runs — building on your own newer distro would silently raise that
 floor and strand every user on an older one, with no symptom until they
-download it. CI enforces the floor: `linux-arm64-build` fails if the highest
+download it. `scripts/linux-arm64/verify_appimage.sh` enforces the floor in
-required glibc symbol version climbs above 2.31.
+both CI (`linux-arm64-build`) and the release workflow: the build fails if
+the highest required glibc symbol version climbs above 2.31.
 
 ### Why five libraries are built from source
 
@@ -172,13 +173,15 @@ Three jobs, path-gated on `scripts/build_linux_arm64.sh`,
   exclude list still classifies known sonames correctly, that AppRun still
   launches `game.love` with `--fused`, and that the host-arch guard actually
   fires. Needs no container and no arm64 machine.
-- **`linux-arm64-build`** (`ubuntu-24.04-arm`) — the real build, then extracts
+- **`linux-arm64-build`** (`ubuntu-24.04-arm`) — the real build, then
-  the artifact and asserts the layout, that every bundled object resolves
+  `scripts/linux-arm64/verify_appimage.sh` extracts the artifact and asserts
-  under AppRun's `LD_LIBRARY_PATH`, and that the glibc floor is still ≤ 2.31.
+  the layout, that every bundled object resolves under AppRun's
-  Uploads the AppImage for 7 days.
+  `LD_LIBRARY_PATH`, and that the glibc floor is still ≤ 2.31. Uploads the
+  AppImage for 7 days.
 - **release** — `linux-arm64` runs on `ubuntu-24.04-arm`, reuses the shared
-  `game.love` from the `love-payload` job, and the AppImage is staged and
+  `game.love` from the `love-payload` job, runs the same
-  published like every other release asset.
+  `verify_appimage.sh` checks on the shipped image, and the AppImage is
+  staged and published like every other release asset.
 
 Unlike the Switch job, none of this needs secrets or self-hosted hardware, so
 it runs on fork PRs too.

docs/mod-api-gen2-compat.md

@@ -55,9 +55,10 @@ The short version, for an author deciding what to write:
 ```
 
 `games` is an optional array of version ids (`"red"`, `"blue"`, `"yellow"`,
-`"gold"`), generations (`"gen1"`, `"gen2"`, case-insensitive) or `"all"`.
+`"gold"`, `"silver"`), generations (`"gen1"`, `"gen2"`, case-insensitive) or
-`src/mods/ModTargets.lua` resolves the tokens off `GameVersion.ORDER` and
+`"all"`. `src/mods/ModTargets.lua` resolves the tokens off `GameVersion.ORDER`
-`GameVersion.generation`, so nothing anywhere restates the game list.
+and `GameVersion.generation`, so nothing anywhere restates the game list.
+`"gen2"` now expands to both Gold and Silver.
 `Manifest.validate` stores the resolved, ORDER-sorted ids on `manifest.games`
 and **derives** `manifest.gen2compat` from them, which is the one field the
 loader's gate reads.
@@ -512,8 +513,9 @@ gains a field instead of the name gaining a prefix.
   id under Gen 1's `name` key, which is the one payload difference the
   numeric flag space forces.
 - *Menus (`src/ui/gen2/`):* `ui.start_menu.items`, `ui.title_menu.items`,
-  `ui.options.rows`, `ui.party.submenu`, `ui.naming.grid`, `ui.pc.items`,
+  `ui.options.rows`, `ui.party.submenu`, `ui.party.grid_navigation`,
-  `ui.list_menu`, `transition.style`. `ui.list_menu` covers Gold's script
+  `ui.naming.grid`, `ui.pc.items`, `ui.list_menu`, `transition.style`.
+  `ui.list_menu` covers Gold's script
   menus (`ScriptMenu.lua`); the `Chrome.List` widget the START and title
   menus draw with does not raise it yet, so those two are composed through
   their own hooks only.
@@ -540,8 +542,9 @@ gains a field instead of the name gaining a prefix.
   `battle.crit`, `battle.accuracy`, `battle.turn_order`,
   `battle.enemy_action`, `battle.run`, `battle.exp_award`, `exp.gain`,
   `catch.rate`, `trainer.party`, `battle.overlay`, `battle.low_health_alarm`,
-  `battle.catch_exp`, `battle.bottom_ui_visible` and
+  `battle.catch_exp`, `battle.bottom_ui_visible`,
-  `battle.status_hud_visible`. One payload difference: Gen 1's vanilla
+  `battle.status_hud_visible` and `battle.move_grid_navigation`. One payload
+  difference: Gen 1's vanilla
   `battle.low_health_alarm` link reads `ctx.battle.data`, and Gold's battle
   screen has no `.data` field, so the Gen 2 site **adds** `ctx.data` beside the
   Gen 1 keys. A mod that calls `nextFn` is unaffected; one that reaches through

docs/modding.md

@@ -81,7 +81,7 @@ Every mod contains a root `manifest.json` defining its metadata, supported games
 | `entry` | `string` | Entry Lua file path relative to mod root (usually `"main.lua"`). |
 | `profile` | `string` | Mod profile: `"content"`, `"overhaul"`, or `"total_conversion"`. |
 | `category` | `string` | Categorization chip (e.g. `"GAMEPLAY"`, `"CONTENT"`, `"UI"`, `"AUDIO"`). |
-| `games` | `array` | Supported game versions: `["gen1"]`, `["gen2"]`, `["red"]`, `["blue"]`, `["yellow"]`, `["gold"]`, or `["all"]`. |
+| `games` | `array` | Supported game versions: `["gen1"]`, `["gen2"]`, `["red"]`, `["blue"]`, `["yellow"]`, `["gold"]`, `["silver"]`, or `["all"]`. |
 | `game_version`| `string` | Semver range of required engine version (e.g. `">=0.0.0-dev <2.0.0"`). |
 | `priority` | `integer` | Load priority order (lower numbers load earlier; dependencies always precede dependents regardless of priority). |
 | `dependencies` | `array` | Hard required dependencies. A mod will not load if a required dependency is missing or disabled for the active game. |
@@ -268,10 +268,10 @@ an optional stock `catchChance` percentage.
 `prompt` describes the currently visible choice (`menu`, `moves`, `party`,
 `advance`, `safari`, or `mimic`) and is `locked` when another screen or battle
 phase owns input. Generation-specific features remain optional: Gen 1 includes
-battle medicine, balls, catch previews, Safari balls, and Mimic choices;
+battle medicine, balls, catch previews, Safari balls, and Mimic choices. Gold
-Gold currently returns an empty `items` list rather than guessing at its
+exposes balls and their exact stock catch previews; targeted medicine remains
-pocketed PACK flow. Callers should ignore unknown fields and tolerate absent
+screen-owned and is omitted rather than guessing at its pocketed PACK flow.
-optional ones.
+Callers should ignore unknown fields and tolerate absent optional ones.
 
 ## Battle menu intents
 

docs/new-features.md

@@ -11,10 +11,12 @@ Features intentionally added beyond the original Pokémon Red, Blue, and Yellow
 * **Persistent custom options** stored separately from game saves
 * **Optional widescreen battle layout**
 * **Mobile touch controls** with editable layouts, vibration, and orientation settings
-* **Touch skins** in RetroArch overlay format, with bezel art, per-button press states, and Super Game Boy borders
+* **Screen position setting** (center, upper, top) shared across all games, for clamp-on controllers that cover the lower screen
+* **Touch skins** in RetroArch overlay format and Delta `.deltaskin` (including PDF-wrapped bezel art), with per-button press states and Super Game Boy borders
 * **Pokédex diploma and printer image exports**
 
 ## Gen 2 Specifics
 
+* **Pokémon Silver** as an importable, launcher-selectable version alongside Gold
 * **Mod manager** with Gen 1 mod adapters, per-game targeting, and `modkit gen2check`
 * **Followers** for mods, plus Gen 2-only registries and hooks

docs/preparing-your-mod-for-gen2.md

@@ -176,7 +176,7 @@ something the filesystem encodes.
 
 | token | means |
 | --- | --- |
-| `"red"`, `"blue"`, `"yellow"`, `"gold"` | that one game (a version id from `GameVersion.ORDER`) |
+| `"red"`, `"blue"`, `"yellow"`, `"gold"`, `"silver"` | that one game (a version id from `GameVersion.ORDER`) |
 | `"gen1"`, `"gen2"` | every game of that generation (case-insensitive; `"gen 2"` also parses) |
 | `"all"` | every game this engine has |
 

docs/required-to-function.md

@@ -1,7 +1,8 @@
 # What This Port Requires
 
 The packaged desktop app requires one user-supplied input on first boot: a
-canonical 1 MiB US Pokemon Red, Blue, or Yellow ROM.
+canonical 1 MiB US Pokemon Red, Blue, or Yellow ROM, or a canonical 2 MiB US
+Pokemon Gold or Silver ROM.
 
 The importer verifies the SHA-1 for the game (see `src/core/GameVersion.lua`
 for specific hashes). Other revisions and Virtual Console releases are rejected
@@ -15,7 +16,8 @@ Python and Pillow are not required by the packaged app.
 
 Assembly removes high-level names and some relationships that the Lua port
 needs. The version-specific files `tools/rom_manifest.json`,
-`tools/rom_manifest_blue.json`, and `tools/rom_manifest_yellow.json` therefore
+`tools/rom_manifest_blue.json`, `tools/rom_manifest_yellow.json`,
+`tools/rom_manifest_gold.json`, and `tools/rom_manifest_silver.json` therefore
 contain:
 
 - the ROM symbol addresses actually read by the extractor

docs/skin-studio.md

@@ -4,16 +4,23 @@ A **skin** replaces the on-screen controls wholesale: a bezel image, a
 control layout, and the rectangle the Game Boy screen is drawn into. Engine:
 `src/core/TouchSkin.lua` (model, parsers, zip export), `src/core/TouchControls.lua`
 (draw and input), `src/render/Renderer.lua` (the screen viewport),
+`src/core/DeltaSkin.lua` (Delta `.deltaskin` import and export),
 `src/ui/SkinStudio.lua` (the desktop editor). Tests:
 `tests/engine/touch_skin_test.lua`, `tests/engine/skin_studio_test.lua`,
-`tests/engine/launcher_skins_tab.lua`.
+`tests/engine/skin_studio_ux.lua`,
+`tests/engine/skin_studio_image_import.lua`,
+`tests/engine/skin_format_import_test.lua`,
+`tests/engine/launcher_skins_tab.lua`,
+`tests/engine/launcher_skins_ux.lua`.
 
 Skins are picked in the launcher's **Skins** tab, which also imports them and
 opens the studio. `options.touchControls.skin` holds the folder name.
 
 ## Formats
 
-Two load. `skin.lua` wins when a folder has both.
+Three load: the native `skin.lua`, a RetroArch overlay `.cfg`, and a Delta
+`.deltaskin`. `skin.lua` wins when a folder has more than one. The launcher
+badges each installed skin with the format it was read from.
 
 **RetroArch overlay `.cfg`.** The libretro `common-overlays` collection loads
 as-is. Supported keys:
@@ -25,7 +32,7 @@ as-is. Supported keys:
 | `overlayN_overlay` | bezel image |
 | `overlayN_full_screen` | stretch the page to the window |
 | `overlayN_rect` | page placement, default `0,0,1,1` |
-| `overlayN_aspect_ratio` | fallback aspect when not full screen |
+| `overlayN_aspect_ratio` | design aspect; the overlay letterboxes to it even when full screen |
 | `overlayN_range_mod`, `overlayN_alpha_mod` | desc defaults |
 | `overlayN_viewport` | `x,y,w,h`, the screen cutout |
 | `overlayN_viewport_fill` | parsed; the engine always fits, see below |
@@ -40,6 +47,15 @@ Hitboxes are `radial` or `rect`. Pipe-separated binds (`left|down`) are one
 control that holds both. A `nul` desc is decoration: it draws and never
 captures a touch.
 
+The area desc types are expanded rather than ignored: `dpad_area`,
+`abxy_area`, `analog_left` and `analog_right` each become eight hitboxes over
+the same area, one per 45 degree sector measured from its centre, the way
+RetroArch resolves them: there is no neutral middle, and the four corner
+sectors fire two inputs. Any `_up` / `_down` / `_left` / `_right` override and
+the per-side reach are honoured, and the desc's own art is kept as decoration
+over the top. Exporting a cfg folds the eight back into the one area desc they
+came from. `retrok_<key>` is a keyboard bind.
+
 Alpha follows RetroArch (`input_driver.c`, `input_overlay_post_poll`): every
 image sits at the overlay opacity, and a pressed control's image swaps to
 `opacity * alpha_mod`. So `alpha_mod` above 1 lights a control up and below 1
@@ -70,6 +86,32 @@ return {
 }
 ```
 
+**Delta `.deltaskin`.** A zip (any wrapping folder is stripped) holding an
+`info.json` plus its art. The `representations` tree is walked
+device / display type / orientation, and every orientation that exists becomes
+a page; `page.orient` is the orientation key, so a portrait/landscape pair
+auto-rotates like a RetroArch one. Item `frame` rects are top-left plus size in
+`mappingSize` points and are converted to the native centre plus half extent;
+`extendedEdges` merge per key into the reach fields; `mask: "circle"` becomes a
+radial hitbox. A `dpad` or `thumbstick` item expands into the 3x3 grid, so the
+corners fire two directions. `screens[1].outputFrame` (or the legacy
+`gameScreenFrame`) becomes the screen cutout. A portrait page with neither
+keeps `mappingSize` as the overlay aspect, sits at the bottom of the
+window, and puts the Game Boy picture in the leftover space above -- the
+usual GBA4iOS controller-deck layout. Pages that name a screen rect still
+stretch to the window the way Delta does. Host functions map to
+engine hotkeys: `menu` to `menu_toggle`, `fastForward` to
+`hold_fast_forward`, `toggleFastForward` to `toggle_fast_forward`;
+`quickSave` and `quickLoad` have nothing to bind to and drop to decoration.
+Both `com.rileytestut.delta.game.*` and Manic's `public.aoshuang.game.*`
+identifiers are accepted, and a non Game Boy system warns instead of failing.
+
+PDF artwork is usually a JPEG wrapped so iOS can scale it (Delta's
+Image-to-PDF skins, Preview exports, and the like). Import extracts that
+JPEG and draws it; a true vector PDF with no embedded image is still refused,
+with a message asking for a PNG version. GBA4iOS `.gbcskin` / `.gbaskin` files
+are an older, incompatible schema and are refused by name.
+
 ## Bindable actions
 
 The eight Game Boy buttons: `a`, `b`, `start`, `select`, `up`, `down`,
@@ -118,10 +160,22 @@ them. Anything that binds a button still follows the usual mobile /
 
 ## Installing
 
-Drop a folder or a `.zip` into `skins/` in the save directory, or drop a zip on
+Four roads, all of them landing in `skins/` in the save directory:
-the launcher window while the Skins tab is open. A zip is mounted in place, so
+
-there is nothing to unpack. The folder needs one `skin.lua` or `.cfg`
+* **Import** on the Skins tab opens the host file picker for a `.zip` or a
-(`overlay.cfg` is preferred when there are several) and the images it names.
+  `.deltaskin`.
+* **Paste a skin link** in the tab's URL row, then **Add**. The download runs
+  on the fetch pool (`src/net/Fetch.lua`), so the launcher stays live, and the
+  row shows a spinner until it lands. A link to a bare `overlay.cfg` is wrapped
+  into an archive on the way in. This is the road that works on a phone, where
+  there is no file picker to speak of.
+* Drop a `.zip` or `.deltaskin` on the launcher window while the Skins tab is
+  open.
+* Copy a folder or archive into `skins/` by hand.
+
+An archive is mounted in place, so there is nothing to unpack. It needs one
+`skin.lua`, `.cfg` (`overlay.cfg` is preferred when there are several) or
+`info.json`, plus the images it names.
 
 Two ship bundled, both from libretro's `common-overlays` under CC-BY-4.0:
 
@@ -156,24 +210,69 @@ The Super Game Boy preset locks the viewport to the real screen window,
 160x144 at (48,40), so an SGB border cannot be drawn out of register.
 
 **Editing.** Click a control to select it, drag to move, eight handles to
-resize. X / Y / W / H are in canvas pixels, so a control can be typed to the
+resize. Arrow keys nudge the selection one canvas pixel, shift-arrow ten. While
-coordinate its art was drawn at. Bind, hitbox shape, hit reach and idle and
+a control is dragged it snaps to the centres and edges of the other controls
+and of the page itself when it comes within a few pixels, and the guide it
+snapped to is drawn. X / Y / W / H are in canvas pixels, so a control can be
+typed to the coordinate its art was drawn at. **Back** and **Front** move the
+selection through the draw order. Bind, hitbox shape, hit reach and idle and
 pressed images are per control; the bezel, the pages and the screen cutout are
-per page. The cutout is itself a draggable element with a 10:9 lock. Drop a PNG
+per page. The cutout is itself a draggable element with a 10:9 lock.
-or JPG on the window to import art into the skin.
+
+**Bind** opens a grid of every bind the engine understands: the eight Game Boy
+buttons, the diagonal pairs, every hotkey, a few `key:` entries, and
+decoration. The COMBINE chips at the top toggle one part at a time, which is
+how a pipe bind like `left|down` is built without typing it.
+
+**Undo** and **Redo** in the top bar cover every edit (ctrl+Z / ctrl+Y, or
+`u` / shift+`u` without a keyboard modifier). The stack holds the last 50
+actions. `L` toggles the bind captions drawn on the canvas.
+
+Each page can **Lock** to portrait or landscape. With **Match canvas** on
+(the default), the page list picks a matching mock device and the canvas preset
+picks a matching page. Turn Match canvas off to look at a portrait page on a
+landscape device. **Pages** opens the page list, where a page is selected,
+renamed or deleted.
+
+Starting a new skin, opening another one or closing the studio with unsaved
+edits prompts first, with Save first / Discard / Cancel.
+
+A RetroArch overlay whose pages are already named portrait / landscape
+(the auto-rotate convention) locks those pages and turns Match canvas on
+when you open it. You do not have to click Lock first.
+
+**Art.** The **Bezel**, **Idle art** and **Pressed art** rows open a
+thumbnail grid of the images already in the skin folder, with `(none)` first;
+the **Import** button there and beside each row opens the host file picker (`src/core/FilePicker.lua`: osascript, PowerShell,
+zenity/kdialog) and copies the chosen PNG or JPG into `img/` under the name in
+the SKIN field, then assigns it to that slot. Dropping a PNG or JPG on the
+window does the same for whichever slot was last touched. A new bezel does not
+move the screen cutout: press **Detect screen from bezel** to measure it out of
+the art's alpha.
 
 **Testing.** **Test** makes the canvas live: clicking presses real Game Boy
 buttons and the footer reports what is held. **Play** saves the skin, selects
 it, and boots the game with it.
 
 **Saving.** **Save** writes `skins/<name>/skin.lua` and copies every image the
-skin names, so the folder stands alone. **Export** packs it as one zip
+skin names, so the folder stands alone. **Export** offers three formats, and
-(`src/core/SkinZip.lua`, store-only) carrying the native `skin.lua`, the
+the Skins tab's gear offers the same three for any installed skin:
-images, and the original `.cfg` when it came from one. An exported skin drops
+
-straight back into `skins/` and still opens in RetroArch.
+| Export | Contents |
+| --- | --- |
+| gen1recomp `.zip` | the native `skin.lua`, the images, and the original `.cfg` when it came from one |
+| RetroArch `.zip` | an `overlay.cfg` generated from the model, plus the images |
+| Delta `.deltaskin` | an `info.json` generated from the model, plus the images |
+
+All three are written store-only (`src/core/SkinZip.lua`) into `skins/_export/`
+in the save directory, which is outside the folder the skin list scans, so an
+export can never shadow the skin it came from. The notice names the full path
+so a phone can find the file in its own file manager. On desktop **Show the
+exported file** opens that folder.
 
 ## Not implemented
 
-RetroArch's `analog_*`, `dpad_area`, `abxy_area` and `retrok_*` desc types.
+True vector Delta skins (PDF artwork with no embedded JPEG). Those still need
-Image assignment cycles through art already in the skin folder; there is no
+a PDF renderer this engine does not carry, so they are refused with a message
-file browser, so new art arrives by drag and drop.
+rather than imported half-drawn. PDF files that wrap a JPEG, the usual Delta
+skin case, extract on import.

docs/switch-build.md

@@ -169,6 +169,7 @@ the NX runtime modules `src/core/NxAssetOverlay.lua`, `src/core/Platform.lua`,
 `tests/engine/assets_version_fallback_test.lua`,
 `tests/engine/nx_generated_guard_test.lua`,
 `tests/engine/nx_yellow_boot_test.lua`,
+`tests/engine/cache_fs_gold_nx_load_test.lua`,
 `tests/engine/switch_diagnostics_test.lua`, `tests/engine/platform_nx_*`,
 or the Switch-related workflow YAML), CI runs:
 
@@ -179,7 +180,8 @@ or the Switch-related workflow YAML), CI runs:
    `luajit tests/switch_transfer_docs_test.lua`, and the NX engine suites
    headlessly (`luajit tests/engine/assets_version_fallback_test.lua`,
    `luajit tests/engine/nx_generated_guard_test.lua`,
-   `luajit tests/engine/nx_yellow_boot_test.lua`).
+   `luajit tests/engine/nx_yellow_boot_test.lua`,
+   `luajit tests/engine/cache_fs_gold_nx_load_test.lua`).
 2. **Fused NRO build** only on the **main** repository
    (`bryanthaboi/gen1recomp`), on the self-hosted Mac runner
    (`scripts/build_switch.sh --fetch --fused`), and only when the workflow

docs/switch-install.md

@@ -3,7 +3,7 @@
 Every GitHub Release that includes Switch support ships an SD-ready zip:
 `gen1recomp-*-switch.zip`. Extract it at the root of your microSD (install
 or update, same steps), launch with **title override**, then import your
-own legal `.gb` ROM.
+own legal `.gb` / `.gbc` ROM.
 
 > You need a console that can run Switch homebrew (custom firmware / hbmenu).
 > This project does not help you set that up.
@@ -91,13 +91,14 @@ Do **not** launch from the Album applet path for normal play.
 
 This project ships **no** game data. On first launch:
 
-1. Put your own legally obtained Pokémon Red, Blue (`.gb`), or Yellow
+1. Put your own legally obtained Pokémon Red, Blue (`.gb`), Yellow, Gold, or
-   (`.gbc`) dump into `switch/gen1recomp/pokemon-love2d/imports/` (the
+   Silver (`.gbc`) dump into `switch/gen1recomp/pokemon-love2d/imports/` (the
-   launcher also shows the live save-dir path). All three can sit in the
+   launcher also shows the live save-dir path). All five can sit in the
    same folder.
-2. Use **Scan again** on that game's tab (Red / Blue / Yellow). Rescan
+2. Use **Scan again** on that game's tab (Red / Blue / Yellow / Gold /
-   matches by ROM SHA-1 for the open tab only. A Red dump never imports
+   Silver). Rescan matches by ROM SHA-1 for the open tab only. A Red dump
-   from the Yellow tab (and vice versa).
+   never imports from the Yellow tab (and vice versa). Gold and Silver are
+   Beta in the launcher; a clean US dump of either is enough to Play.
 
 ## 5. Import / Export a raw `.sav`
 
@@ -109,8 +110,13 @@ SD / FTP, same transfer methods as ROMs. Paths are **per game**:
 | Red | `imports/saves/red/` | `exports/red/` |
 | Blue | `imports/saves/blue/` | `exports/blue/` |
 | Yellow | `imports/saves/yellow/` | `exports/yellow/` |
+| Gold | `imports/saves/gold/` | `exports/gold/` |
+| Silver | `imports/saves/silver/` | `exports/silver/` |
 
-(Under the save dir `pokemon-love2d/`. The zip already creates these folders.)
+(Under the save dir `pokemon-love2d/`. The zip already creates these folders.
+Gold and Silver cart `.sav` import/export is not supported yet -- the folders
+exist so MTP browsing matches the other games. Gold and Silver progress still
+saves in-engine.)
 
 1. Copy a Gen 1 `.sav` (32 KB) into that game's inbox under the save dir
    ([switch-transfer.md](switch-transfer.md)).

docs/switch-transfer.md

@@ -22,8 +22,8 @@ Player install (what to download, title override) stays in
 | Loose iteration pair | `sdmc:/switch/gen1recomp/gen1recomp.nro` **and** `game.love` beside it |
 | ROM inbox | LÖVE save dir → `imports/` (launcher shows the live `getSaveDirectory()` path; under MTP often `1: SD Card/<save identity>/imports/`) |
 | Mod zip inbox | Same save dir → `imports/mods/` then MODS → **Scan again** |
-| Save `.sav` inbox | Same save dir → `imports/saves/red\|blue\|yellow/` then that game's SAVE FILES → **Import save** |
+| Save `.sav` inbox | Same save dir → `imports/saves/red\|blue\|yellow\|gold\|silver/` then that game's SAVE FILES → **Import save** (Gold / Silver cart `.sav` not supported yet) |
-| Save exports | Same save dir → `exports/red\|blue\|yellow/` (pull after **Export save**; MTP / SD / FTP) |
+| Save exports | Same save dir → `exports/red\|blue\|yellow\|gold\|silver/` (pull after **Export save**; Gold / Silver cart `.sav` not supported yet) |
 | Opt-in diagnostics | Empty `switch-debug.txt` in the save dir → `switch.log` |
 | Lua error log | `lua-error.log` in the save dir |
 
@@ -54,8 +54,9 @@ macOS, not a Mac-only requirement.
 3. Create `switch/gen1recomp/` if needed; extract the release zip at SD root
    (or copy NRO / `game.love` for loose).
 4. For ROMs/mods/saves, open the save-dir `imports/`, `imports/mods/`,
-   `imports/saves/<red|blue|yellow>/`, or `exports/<red|blue|yellow>/` path the
+   `imports/saves/<red|blue|yellow|gold|silver>/`, or
-   launcher prints.
+   `exports/<red|blue|yellow|gold|silver>/`
+   path the launcher prints.
 5. Wait for the queue; refresh; exit MTP responder; title-override launch.
 
 macOS clients often create AppleDouble sidecars (`._Something.zip`,

docs/tiled-map-editing.md

@@ -0,0 +1,65 @@
+# Tiled map editing (mod authoring)
+
+`tools/tiled_export.py` turns the imported ROM cache into a
+[Tiled](https://www.mapeditor.org) workspace, so maps can be edited in a
+real map editor and exported back out as a mod. The original had no map
+editor at all; the port's own map data is plain Lua, which is what makes
+this a data path rather than an asset path.
+
+Editing is done in our own Tiled build,
+[bryanthaboi/tiled_gen1recomp](https://github.com/bryanthaboi/tiled_gen1recomp/releases),
+which ships the `gen1-mod-export` extension the workspace relies on. Grab it
+from that repo's releases; upstream Tiled opens the workspace but cannot
+export a mod out of it.
+
+```sh
+python3 tools/tiled_export.py          # -> build/tiled/ (gitignored)
+```
+
+Then open `build/tiled/gen1.tiled-project` in that build of Tiled.
+
+- **The overworld is one surface.** All 222 maps become `maps/*.tmj`, and
+  `kanto.world` places the 36 connected overworld maps at their real
+  connection offsets. That world is pre-loaded (seeded into the workspace's
+  Tiled session), so opening any one overworld map draws its neighbors around
+  it and you scroll and edit straight across the seams. Everything else is a
+  double-click away in Tiled's project panel.
+- **Extending Kanto wires both ends.** A connection lives on both maps, so
+  hooking a new map onto a base map also emits the return connection as a
+  patch on that base map, keeping its other directions intact. The return
+  offset is derived, not guessed: all 78 vanilla reciprocal pairs satisfy
+  `back.offset == -offset`.
+- **A Tiled tile is a gen1 block.** Each of the 24 tilesets becomes a Tiled
+  tileset whose tiles are its 32x32 blocks, composited from the 8x8 sheet,
+  so a tile layer *is* the map's `blocks` array. Warps, signs and objects
+  sit on the 16px cell grid in object layers, which is the grid the engine
+  addresses them on.
+- **Collision is visible.** View > Show Tile Collision Shapes draws the real
+  walkability: a rectangle covers each cell whose feet tile is not in the
+  tileset's `walkable` list, which is the rule `src/world/Map.lua` applies.
+- **Maps are shown in their real colors.** Each map is atlased in the SGB
+  palette it renders with, so Cerulean is blue and Lavender is purple in the
+  editor exactly as in game. Vanilla resolves that through a cascade with
+  interiors inheriting the last outdoor map, so the workspace mirrors the
+  cascade and walks the warp graph to colour interiors. Changing a map's
+  `palette` exports `palette = "..."` on the record, which beats the cascade,
+  and the editor offers the real palette names as a dropdown.
+- **New blocks and new tilesets.** `blocksets/*.tmj` show a tileset's blocks
+  as raw 8x8 tiles, four by four, so new blocks can be composed there;
+  per-tile flags on `tilesets/tiles_*.tsj` become `walkable`, `waterTiles`,
+  `doorTiles` and the rest.
+- **Export is a diff, not a fork of the data.** The `gen1-mod-export`
+  extension (shipped in `tiled_gen1recomp`) writes either one map file or a whole
+  loadable mod folder. An edited vanilla map diffs against the imported data
+  and emits `mod.content.maps:patch` carrying *only* the fields that moved, so
+  a mod covers the parts it changes and leaves the rest to the base game; a
+  new map gets `:register` at an index of 1000 or above. An unchanged map
+  exports nothing at all. Exports pass `tools/modkit.py validate` and `lint`.
+- **Or the whole record, on request.** Ticking `exactExport` on a map switches
+  it to `mod.content.maps:override`, pinning the map to exactly what the
+  editor shows. It is off by default because an override wins outright over
+  any other mod patching that map, where a patch composes.
+
+No ROM-derived art travels into an exported mod: a tileset still drawing on
+the player's own imported sheet references that path rather than shipping the
+pixels, and only a sheet the author supplied is copied in.

main.lua

@@ -291,6 +291,78 @@ function closeSkinStudio()
   end
 end
 
+local function makeLauncher()
+  local RomImporter = require("src.import.RomImporter")
+  local forceImport = os.getenv("POKEPORT_FORCE_IMPORT") == "1"
+  return RomImporter.new(function(version)
+    Importer = nil
+    bootGame(version)
+  end, {
+    launcher = true,
+    forceImport = forceImport,
+    onEditSave = openEditor,
+    onEditTouchControls = openTouchControlsEditor,
+    onOpenSkinStudio = require("src.ui.SkinStudio").available_desktop()
+      and openSkinStudio or nil,
+  })
+end
+
+local function returnToLauncher()
+  if not Game then return end
+
+  pcall(function() require("src.core.Music").stop() end)
+  pcall(function() require("src.core.Sound").stop() end)
+  if package.loaded["src.core.ChipAudio"] then
+    pcall(package.loaded["src.core.ChipAudio"].shutdown)
+  end
+  if package.loaded["src.core.DiscordPresence"] then
+    pcall(package.loaded["src.core.DiscordPresence"].shutdown)
+  end
+  if package.loaded["src.core.gen2.Clock"] then
+    pcall(package.loaded["src.core.gen2.Clock"].shutdown)
+  end
+  if package.loaded["src.net.Gen1Tls"] then
+    pcall(package.loaded["src.net.Gen1Tls"].shutdown)
+  end
+  if love.audio and love.audio.stop then
+    pcall(love.audio.stop)
+  end
+
+  local GameVersion = require("src.core.GameVersion")
+  local currentVersion = GameVersion.get()
+  if currentVersion then
+    require("src.import.CacheFs").unmountVersion(currentVersion)
+  end
+  require("src.core.Data"):unloadGenerated()
+
+  local Runtime = require("src.mods.Runtime")
+  if Runtime.reset then
+    Runtime.reset()
+  end
+
+  Game = nil
+  autopilot = nil
+  driverCo = nil
+
+  local Input = require("src.core.Input")
+  local TouchControls = require("src.core.TouchControls")
+  Input:reset()
+  TouchControls:reset()
+
+  require("src.core.Orientation").applyOptions(
+    require("src.core.SaveData").loadOptions())
+
+  local preload = require("src.mods.LauncherMods").translationStrings()
+  if preload then require("src.core.Strings").load({ strings = preload }) end
+
+  if love.window and love.window.setTitle then
+    local Version = require("src.core.Version")
+    love.window.setTitle(Version.title("Gen 1 Recompilation Project"))
+  end
+
+  Importer = makeLauncher()
+end
+
 function bootGame(version)
   -- The launcher hands us the chosen game (Red / Blue / Yellow / Gold);
   -- scripted and headless runs fall back to POKEPORT_VERSION, then Red.
@@ -314,11 +386,12 @@ function bootGame(version)
     love.window.setTitle(Version.title(
       GameVersion.info().displayName .. " (Gen 1 Recompilation Project)"))
   end
-  -- Gold: Gen 1 Game:load cannot consume a Gen 2 cache -- different generated
+  -- Gen 2: Gen 1 Game:load cannot consume a Gen 2 cache -- different generated
-  -- tables, save shape and screen registry -- so Gold boots its own service
+  -- tables, save shape and screen registry -- so Gold and Silver boot their
-  -- owner, which mounts src/world/gen2 (walk / warps / connections) and the
+  -- own service owner, which mounts src/world/gen2 (walk / warps /
-  -- Gen 2 screens instead of src/core/Game.lua's Gen 1 wiring.
+  -- connections) and the Gen 2 screens instead of src/core/Game.lua's Gen 1
-  if GameVersion.isGold() then
+  -- wiring.
+  if GameVersion.generation() == 2 then
     Game = require("src.core.Game2").new()
     Game:load()
   else
@@ -382,7 +455,7 @@ function love.load(args)
 
   -- Apply the persisted Android orientation lock (#592) before the launcher
   -- shows: SDL created the window with no orientation hint, so without this
-  -- the launcher would rotate freely until Game:applyOptions runs at boot.
+  -- the launcher would rotate freely until options are applied at boot.
   -- No-op on desktop / iOS / when options.lua does not exist yet.
   require("src.core.Orientation").applyOptions(
     require("src.core.SaveData").loadOptions())
@@ -442,8 +515,8 @@ function love.load(args)
   -- (#767) only pays off if something fills that catalog this early, and no
   -- restart could: the ordering is the same on every launch.  Read the
   -- enabled mods' string catalogs -- data only, no entry chunk -- so a
-  -- translation reaches the launcher too.  Game:load replaces this with the
+  -- translation reaches the launcher too.  The active game's loader replaces
-  -- real merged catalog once a version boots.
+  -- this with the real merged catalog once a version boots.
   do
     local preload = require("src.mods.LauncherMods").translationStrings()
     if preload then require("src.core.Strings").load({ strings = preload }) end
@@ -484,17 +557,7 @@ function love.load(args)
   -- by its SHA-1 (GameVersion.forSha1); pressing Play boots that game (Gold
   -- goes to its own service owner, src/core/Game2.lua -- docs/gold-phase1.md).
   -- Edit on a save row opens the bundled editor on that slot (openEditor).
-  Importer = RomImporter.new(function(version)
+  Importer = makeLauncher()
-    Importer = nil
-    bootGame(version)
-  end, {
-    launcher = true,
-    forceImport = forceImport,
-    onEditSave = openEditor,
-    onEditTouchControls = openTouchControlsEditor,
-    onOpenSkinStudio = require("src.ui.SkinStudio").available_desktop()
-      and openSkinStudio or nil,
-  })
 end
 
 function love.update(dt)
@@ -506,6 +569,7 @@ function love.update(dt)
   if TouchEditor then return TouchEditor.update(dt) end
   if Studio then return Studio.update(dt) end
   if Importer then return Importer:update(dt) end
+  if not Game then return end
 
   -- Scripted runs (autopilot / POKEPORT_DRIVER) observe and act exactly
   -- once per Game:update, so they must keep a 1:1 relationship with the
@@ -602,12 +666,14 @@ function love.keypressed(key, scancode, isrepeat)
   if TouchEditor then return TouchEditor.keypressed(key) end
   if Studio then return Studio.keypressed(key) end
   if Importer then return Importer:keypressed(key) end
+  if not Game then return end
   Game:keypressed(key)
 end
 
 function love.keyreleased(key)
   if editorMode or TouchEditor or Studio then return end
   if Importer then return end
+  if not Game then return end
   Game:keyreleased(key)
 end
 
@@ -625,7 +691,9 @@ function love.gamepadpressed(joystick, button)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:gamepadpressed(joystick, button) end
+  if not Game then return end
   Game:gamepadpressed(joystick, button)
 end
 
@@ -643,7 +711,9 @@ function love.gamepadreleased(joystick, button)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:gamepadreleased(joystick, button) end
+  if not Game then return end
   Game:gamepadreleased(joystick, button)
 end
 
@@ -661,7 +731,9 @@ function love.gamepadaxis(joystick, axis, value)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:gamepadaxis(joystick, axis, value) end
+  if not Game then return end
   Game:gamepadaxis(joystick, axis, value)
 end
 
@@ -679,7 +751,9 @@ function love.joystickpressed(joystick, button)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:joystickpressed(joystick, button) end
+  if not Game then return end
   Game:joystickpressed(joystick, button)
 end
 
@@ -697,7 +771,9 @@ function love.joystickreleased(joystick, button)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:joystickreleased(joystick, button) end
+  if not Game then return end
   Game:joystickreleased(joystick, button)
 end
 
@@ -715,7 +791,9 @@ function love.joystickaxis(joystick, axis, value)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:joystickaxis(joystick, axis, value) end
+  if not Game then return end
   Game:joystickaxis(joystick, axis, value)
 end
 
@@ -733,21 +811,25 @@ function love.joystickhat(joystick, hat, direction)
     end
     return
   end
+  if Studio then return end
   if Importer then return Importer:joystickhat(joystick, hat, direction) end
+  if not Game then return end
   Game:joystickhat(joystick, hat, direction)
 end
 
 function love.joystickadded(joystick)
   SwitchDiagnostics.onJoystickEvent("joystickadded", joystick)
-  if editorMode or TouchEditor then return end
+  if editorMode or TouchEditor or Studio then return end
   if Importer then return end
+  if not Game then return end
   Game:joystickadded(joystick)
 end
 
 function love.joystickremoved(joystick)
   SwitchDiagnostics.onJoystickEvent("joystickremoved", joystick)
-  if editorMode or TouchEditor then return end
+  if editorMode or TouchEditor or Studio then return end
   if Importer then return end
+  if not Game then return end
   Game:joystickremoved(joystick)
 end
 
@@ -756,29 +838,79 @@ end
 -- unfocused, so reset input on either transition rather than trust it.
 function love.focus(f)
   if editorMode or TouchEditor then return end
+  if Studio then
+    if Studio.focus then Studio.focus(f) end
+    return
+  end
   if Importer then
     require("src.core.Input"):reset()
     if Importer.focus then Importer:focus(f) end
     return
   end
+  if not Game then return end
   Game:focus(f)
 end
 
 -- v is true when the window becomes visible again, false on minimize.
 function love.visible(v)
   if editorMode or TouchEditor then return end
+  if Studio then
+    if Studio.visible then Studio.visible(v) end
+    return
+  end
   if Importer then
     require("src.core.Input"):reset()
     return
   end
+  if not Game then return end
   Game:visible(v)
 end
 
 function love.lowmemory()
-  if editorMode or TouchEditor or Importer then return end
+  if editorMode or TouchEditor or Studio or Importer then return end
   if Game then Game:onResume() end
 end
 
+love.handlers = love.handlers or {}
+
+function love.handlers.audiosuspend()
+  local ChipAudio = package.loaded["src.core.ChipAudio"]
+  if ChipAudio then pcall(ChipAudio.setSuspended, true) end
+end
+
+function love.handlers.audioreset()
+  local ChipAudio = package.loaded["src.core.ChipAudio"]
+  if ChipAudio then
+    pcall(ChipAudio.setSuspended, false)
+    pcall(ChipAudio.rebuildPlayback)
+  end
+  local Music = package.loaded["src.core.Music"]
+  if Music then pcall(Music.onDeviceReset) end
+  local Sound = package.loaded["src.core.Sound"]
+  if Sound then pcall(Sound.onDeviceReset) end
+end
+
+function love.handlers.intent_game(version)
+  if type(version) ~= "string" or version == "" then return end
+  version = version:lower():gsub("^%s+", ""):gsub("%s+$", "")
+  local GameVersion = require("src.core.GameVersion")
+  if GameVersion.VERSIONS and not GameVersion.VERSIONS[version] then return end
+
+  local RomImporter = require("src.import.RomImporter")
+  if not RomImporter.isReady(version) then return end
+
+  local currentVersion = GameVersion.get()
+  if Game and currentVersion == version then
+    return
+  end
+
+  if Game then
+    returnToLauncher()
+  end
+  Importer = nil
+  bootGame(version)
+end
+
 function love.touchpressed(id, x, y, dx, dy, pressure)
   if editorMode then
     -- iOS synthesizes mousepressed for the primary touch; forwarding here
@@ -796,12 +928,14 @@ function love.touchpressed(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchpressed(id, x, y)
   end
+  if Studio then return end
   if Importer then
     -- Both mobiles: FlexLove scroll needs the real touch stream. Clicks are
     -- polled inside the view; the istouch filter on mousepressed still drops
     -- Android's synthesized mouse twin so Import cannot double-fire (#553).
     return Importer:touchpressed(id, x, y, dx, dy, pressure)
   end
+  if not Game then return end
   Game:touchpressed(id, x, y, dx, dy, pressure)
 end
 
@@ -811,9 +945,11 @@ function love.touchmoved(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchmoved(id, x, y)
   end
+  if Studio then return end
   if Importer then
     return Importer:touchmoved(id, x, y, dx, dy, pressure)
   end
+  if not Game then return end
   Game:touchmoved(id, x, y, dx, dy, pressure)
 end
 
@@ -823,9 +959,11 @@ function love.touchreleased(id, x, y, dx, dy, pressure)
     if love.system.getOS() == "iOS" then return end
     return TouchEditor.touchreleased(id, x, y)
   end
+  if Studio then return end
   if Importer then
     return Importer:touchreleased(id, x, y, dx, dy, pressure)
   end
+  if not Game then return end
   Game:touchreleased(id, x, y, dx, dy, pressure)
 end
 
@@ -837,6 +975,7 @@ function love.wheelmoved(x, y)
   if TouchEditor then return end
   if Studio then return Studio.wheelmoved(x, y) end
   if Importer then return end
+  if not Game then return end
   Game:wheelmoved(x, y)
 end
 
@@ -977,11 +1116,16 @@ function love.quit()
   -- docs/modding.md's core.quit_to_launcher entry) may veto returning to
   -- this Lua launcher via that hook. Vanilla behavior (used when no mod
   -- claims the hook) is exactly the condition below.
+  local isAndroid = (love.system and love.system.getOS and love.system.getOS() == "Android")
   local wouldReturnToLauncher = PlatformHooks.quitToLauncher(function()
     return Game and not Importer and not quitToLauncher and not scripted
-      and not launchedIntoGame
+      and (isAndroid or not launchedIntoGame)
   end)
   if wouldReturnToLauncher then
+    if isAndroid then
+      returnToLauncher()
+      return true -- abort this quit; the restart lands back in the launcher
+    end
     quitToLauncher = true
     -- Tell the fresh boot to ignore any boot-straight-into-a-game option this
     -- once, so the restart really does land in the launcher (#887).  A failed

mobile/ANDROID.md

@@ -109,10 +109,10 @@ The APK lands under `app/build/outputs/apk/embedNoRecord/debug/`.
 
 `app/src/embed/assets/game.love` - zip of `main.lua`, `conf.lua`, `src/`,
 `libs/` (the vendored FlexLove toolkit the launcher UI needs), `data/`,
-`assets/`, and the Red, Blue, and Yellow ROM manifests. The Android
+`assets/`, and the Red, Blue, Yellow, Gold, and Silver ROM manifests. The
-packer verifies the Yellow manifest before it packages; if a partial source
+Android packer verifies the Yellow, Gold, and Silver manifests before it
-export omitted it, it restores the file from this checkout's Git data and then
+packages; if a partial source export omitted one, it restores the file from
-falls back to the project's GitHub copy. Generated game data,
+this checkout's Git data and then falls back to the project's GitHub copy. Generated game data,
 scripts, tests, and mobile build sources are excluded.
 
 ## Branding (applied by the build script)

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

@@ -29,7 +29,8 @@
 
   <application
       android:allowBackup="true"
-      android:icon="@drawable/love"
+      android:icon="@mipmap/ic_launcher"
+      android:roundIcon="@mipmap/ic_launcher_round"
       android:label="${NAME}" >
     <meta-data
         android:name="android.allow_multiple_resumed_activities"
@@ -39,7 +40,7 @@
         android:exported="true"
         android:configChanges="orientation|screenSize|smallestScreenSize|screenLayout|keyboard|keyboardHidden|navigation"
         android:label="${NAME}"
-        android:launchMode="singleInstance"
+        android:launchMode="singleTask"
         android:screenOrientation="${ORIENTATION}"
         android:resizeableActivity="false"
         android:theme="@android:style/Theme.NoTitleBar.Fullscreen" >

mobile/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

mobile/android/app/src/main/res/mipmap-anydpi-v26/ic_launcher_round.xml

@@ -0,0 +1,5 @@
+<?xml version="1.0" encoding="utf-8"?>
+<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
+    <background android:drawable="@color/ic_launcher_background" />
+    <foreground android:drawable="@drawable/ic_launcher_foreground" />
+</adaptive-icon>

mobile/android/app/src/main/res/values/colors.xml

@@ -3,4 +3,10 @@
     <color name="colorPrimary">#3F51B5</color>
     <color name="colorPrimaryDark">#303F9F</color>
     <color name="colorAccent">#FF4081</color>
+    <color name="ic_launcher_background">#FFFFFF</color>
+    <color name="shortcut_red">#E53935</color>
+    <color name="shortcut_blue">#1E88E5</color>
+    <color name="shortcut_yellow">#FDD835</color>
+    <color name="shortcut_gold">#D4AF37</color>
+    <color name="shortcut_silver">#BEC6D2</color>
 </resources>

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

@@ -45,6 +45,11 @@
 // own, which can name a different volume on merged / adopted-SD storage.
 #include "filesystem/Filesystem.h"
 
+#include "common/Module.h"
+#include "audio/Audio.h"
+#include "audio/openal/Audio.h"
+#include "event/Event.h"
+
 namespace love
 {
 namespace android
@@ -278,6 +283,70 @@ bool restartApp()
 	return result;
 }
 
+bool updateAppShortcuts(const std::vector<std::string> &versions)
+{
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+	if (activity == nullptr)
+		return false;
+
+	jmethodID method = env->GetStaticMethodID(activity, "updateAppShortcuts", "([Ljava/lang/String;)Z");
+	if (method == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return false;
+	}
+
+	jclass stringClass = env->FindClass("java/lang/String");
+	jobjectArray array = env->NewObjectArray((jsize) versions.size(), stringClass, nullptr);
+	for (size_t i = 0; i < versions.size(); ++i)
+	{
+		jstring jstr = env->NewStringUTF(versions[i].c_str());
+		env->SetObjectArrayElement(array, (jsize) i, jstr);
+		env->DeleteLocalRef(jstr);
+	}
+
+	jboolean result = env->CallStaticBooleanMethod(activity, method, array);
+
+	env->DeleteLocalRef(array);
+	env->DeleteLocalRef(stringClass);
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
+std::string getLaunchGame()
+{
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	jclass activity = env->FindClass("org/love2d/android/GameActivity");
+	if (activity == nullptr)
+		return "";
+
+	jmethodID method = env->GetStaticMethodID(activity, "getLaunchGame", "()Ljava/lang/String;");
+	if (method == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return "";
+	}
+
+	jstring jgame = (jstring) env->CallStaticObjectMethod(activity, method);
+	if (jgame == nullptr)
+	{
+		env->DeleteLocalRef(activity);
+		return "";
+	}
+
+	const char *str = env->GetStringUTFChars(jgame, nullptr);
+	std::string result = (str != nullptr) ? str : "";
+	if (str != nullptr)
+		env->ReleaseStringUTFChars(jgame, str);
+
+	env->DeleteLocalRef(jgame);
+	env->DeleteLocalRef(activity);
+	return result;
+}
+
 bool httpDownload(const char *url, const char *destPath, const char *userAgent, const char *accept)
 {
 	if (url == nullptr || destPath == nullptr)
@@ -374,6 +443,104 @@ bool httpPost(const char *url, const char *body, int bodyLen, const char *conten
 	return result;
 }
 
+bool httpRequest(const char *url, const char *method,
+	const char *const *headerPairs, int headerPairCount,
+	const char *body, int bodyLen, const char *userAgent, std::string &out)
+{
+	out.clear();
+	if (url == nullptr)
+		return false;
+	if (headerPairCount < 0 || (headerPairCount > 0 && headerPairs == nullptr))
+		return false;
+
+	JNIEnv *env = (JNIEnv*) SDL_AndroidGetJNIEnv();
+	// Same resolution rule as httpDownload: the activity's own class via
+	// SDL_AndroidGetActivity, never FindClass for an app class -- save sync
+	// runs on a love.thread worker, whose class loader cannot see them.
+	jobject activityObj = (jobject) SDL_AndroidGetActivity();
+	if (activityObj == nullptr)
+		return false;
+	jclass activity = env->GetObjectClass(activityObj);
+	env->DeleteLocalRef(activityObj);
+
+	// Old APK / new liblove skew: report "no transport" instead of aborting
+	// on a missing method (#597).
+	jmethodID method_id = env->GetStaticMethodID(activity, "httpRequest",
+		"(Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;[BLjava/lang/String;)[B");
+	if (method_id == nullptr)
+	{
+		env->ExceptionClear();
+		env->DeleteLocalRef(activity);
+		return false;
+	}
+
+	jobjectArray jheaders = nullptr;
+	if (headerPairCount > 0)
+	{
+		// java/lang/String, unlike an app class, resolves from any thread.
+		jclass stringClass = env->FindClass("java/lang/String");
+		if (stringClass == nullptr)
+		{
+			env->ExceptionClear();
+			env->DeleteLocalRef(activity);
+			return false;
+		}
+		jheaders = env->NewObjectArray((jsize) headerPairCount, stringClass, nullptr);
+		env->DeleteLocalRef(stringClass);
+		if (jheaders == nullptr)
+		{
+			env->ExceptionClear();
+			env->DeleteLocalRef(activity);
+			return false;
+		}
+		for (int i = 0; i < headerPairCount; i++)
+		{
+			jstring field = env->NewStringUTF(headerPairs[i] != nullptr ? headerPairs[i] : "");
+			env->SetObjectArrayElement(jheaders, (jsize) i, field);
+			if (field != nullptr)
+				env->DeleteLocalRef(field);
+		}
+	}
+
+	jstring jurl = env->NewStringUTF(url);
+	jstring jmethod = env->NewStringUTF(method != nullptr ? method : "GET");
+	// raw bytes across the bridge, as httpPost does: a request body is JSON
+	// carrying a base64 save, and a jstring would run it through modified UTF-8
+	jbyteArray jbody = nullptr;
+	if (body != nullptr && bodyLen >= 0)
+	{
+		jbody = env->NewByteArray((jsize) bodyLen);
+		if (jbody != nullptr && bodyLen > 0)
+			env->SetByteArrayRegion(jbody, 0, (jsize) bodyLen, (const jbyte*) body);
+	}
+	jstring jua = env->NewStringUTF(userAgent != nullptr ? userAgent : "gen1recomp");
+
+	jobject result = env->CallStaticObjectMethod(activity, method_id, jurl, jmethod,
+		jheaders, jbody, jua);
+
+	env->DeleteLocalRef(jurl);
+	env->DeleteLocalRef(jmethod);
+	if (jheaders != nullptr)
+		env->DeleteLocalRef(jheaders);
+	if (jbody != nullptr)
+		env->DeleteLocalRef(jbody);
+	env->DeleteLocalRef(jua);
+	env->DeleteLocalRef(activity);
+
+	if (result == nullptr)
+		return false;
+
+	jbyteArray bytes = (jbyteArray) result;
+	jsize length = env->GetArrayLength(bytes);
+	if (length > 0)
+	{
+		out.resize((size_t) length);
+		env->GetByteArrayRegion(bytes, 0, length, (jbyte*) &out[0]);
+	}
+	env->DeleteLocalRef(result);
+	return true;
+}
+
 /*
  * TLS sockets. Same resolution rule as httpDownload above -- the activity's
  * own class, never FindClass -- and the same tolerance for an old APK: a
@@ -1320,4 +1487,98 @@ const char *love_android_poll_secondary_touch()
 	return event.empty() ? nullptr : event.c_str();
 }
 
+static love::audio::openal::Audio *love_android_openal_audio()
+{
+	love::audio::Audio *audio = love::Module::getInstance<love::audio::Audio>(love::Module::M_AUDIO);
+
+	if (audio == nullptr)
+		return nullptr;
+
+	const char *name = audio->getName();
+
+	if (name == nullptr || strcmp(name, "love.audio.openal") != 0)
+		return nullptr;
+
+	return (love::audio::openal::Audio *) audio;
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_org_love2d_android_GameActivity_nativeAudioFocusLost(JNIEnv *env, jclass cls)
+{
+	(void) env;
+	(void) cls;
+
+	love::audio::openal::pushAudioSuspendEvent();
+
+	love::audio::openal::Audio *audio = love_android_openal_audio();
+
+	if (audio != nullptr)
+		audio->pauseContext();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_org_love2d_android_GameActivity_nativeAudioFocusGained(JNIEnv *env, jclass cls)
+{
+	(void) env;
+	(void) cls;
+
+	love::audio::openal::Audio *audio = love_android_openal_audio();
+
+	if (audio == nullptr)
+		return;
+
+	audio->resumeContext();
+
+	if (!audio->isDeviceConnected())
+		audio->reopenDevice();
+
+	love::audio::openal::pushAudioResetEvent();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_org_love2d_android_GameActivity_nativeAudioDeviceChanged(JNIEnv *env, jclass cls)
+{
+	(void) env;
+	(void) cls;
+
+	love::audio::openal::Audio *audio = love_android_openal_audio();
+
+	if (audio == nullptr)
+		return;
+
+	audio->pauseContext();
+	audio->reopenDevice();
+	audio->resumeContext();
+
+	love::audio::openal::pushAudioResetEvent();
+}
+
+static void pushGameIntentEvent(const char *game)
+{
+	auto eventmodule = love::Module::getInstance<love::event::Event>(love::Module::M_EVENT);
+	if (eventmodule == nullptr || game == nullptr)
+		return;
+
+	std::vector<love::Variant> args;
+	args.push_back(love::Variant(std::string(game)));
+
+	love::event::Message *msg = new love::event::Message("intent_game", args);
+	eventmodule->push(msg);
+	msg->release();
+}
+
+extern "C" JNIEXPORT void JNICALL
+Java_org_love2d_android_GameActivity_nativeOnGameIntent(JNIEnv *env, jclass cls, jstring game)
+{
+	(void) cls;
+	if (game == nullptr)
+		return;
+	const char *str = env->GetStringUTFChars(game, nullptr);
+	if (str != nullptr)
+	{
+		pushGameIntentEvent(str);
+		env->ReleaseStringUTFChars(game, str);
+	}
+}
+
 #endif // LOVE_ANDROID

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

@@ -90,6 +90,16 @@ bool syncHealthSteps();
  **/
 bool restartApp();
 
+/**
+ * Dynamic App Shortcuts: updates Android ShortcutManager with ready game versions.
+ **/
+bool updateAppShortcuts(const std::vector<std::string> &versions);
+
+/**
+ * Returns the game version requested via initial launch Intent (if any).
+ **/
+std::string getLaunchGame();
+
 /**
  * Blocking HTTPS GET into destPath (GameActivity.httpDownload). Android has
  * no curl binary, so this is the transport src/core/HostShell.lua uses there
@@ -106,6 +116,21 @@ bool httpDownload(const char *url, const char *destPath, const char *userAgent,
  **/
 bool httpPost(const char *url, const char *body, int bodyLen, const char *contentType, const char *userAgent);
 
+/**
+ * Blocking HTTPS request with a method, headers and a byte body
+ * (GameActivity.httpRequest). What save sync needs and neither of the two
+ * above can give it: PUT, per-request auth headers, and the response body of
+ * a 4xx as well as a 2xx. headerPairs is a flat name, value array of
+ * headerPairCount entries; body/userAgent may be null. `out` receives the
+ * Java side's envelope -- a head line of "STATUS <code>" or "ERROR <text>",
+ * a newline, then the raw response bytes. False means the platform has no
+ * such bridge at all (an old APK under a newer liblove), which the Lua side
+ * reports as "update the app" rather than as a failed request.
+ **/
+bool httpRequest(const char *url, const char *method,
+	const char *const *headerPairs, int headerPairCount,
+	const char *body, int bodyLen, const char *userAgent, std::string &out);
+
 /**
  * TLS client sockets (GameActivity.tls*, implemented by TlsSocket.java).
  * LuaSocket, which is what LOVE ships, does TCP only, so wss:// is otherwise

mobile/android/love/src/jni/love/src/modules/audio/openal/Audio.cpp

@@ -22,6 +22,7 @@
 #include "common/delay.h"
 #include "RecordingDevice.h"
 #include "sound/Decoder.h"
+#include "event/Event.h"
 
 #include <cstdlib>
 #include <iostream>
@@ -30,6 +31,10 @@
 #include "common/ios.h"
 #endif
 
+#ifndef ALC_CONNECTED
+#define ALC_CONNECTED 0x313
+#endif
+
 namespace love
 {
 namespace audio
@@ -37,9 +42,35 @@ namespace audio
 namespace openal
 {
 
-Audio::PoolThread::PoolThread(Pool *pool)
+static const int DISCONNECT_CHECK_INTERVAL = 200;
-	: pool(pool)
+
+static void pushAudioEvent(const char *name)
+{
+	auto eventmodule = Module::getInstance<event::Event>(Module::M_EVENT);
+
+	if (eventmodule == nullptr)
+		return;
+
+	event::Message *msg = new event::Message(name);
+	eventmodule->push(msg);
+	msg->release();
+}
+
+void pushAudioSuspendEvent()
+{
+	pushAudioEvent("audiosuspend");
+}
+
+void pushAudioResetEvent()
+{
+	pushAudioEvent("audioreset");
+}
+
+Audio::PoolThread::PoolThread(Audio *audio, Pool *pool)
+	: audio(audio)
+	, pool(pool)
 	, finish(false)
+	, paused(false)
 {
 	threadName = "AudioPool";
 }
@@ -51,6 +82,8 @@ Audio::PoolThread::~PoolThread()
 
 void Audio::PoolThread::threadFunction()
 {
+	int disconnectCheck = 0;
+
 	while (true)
 	{
 		{
@@ -61,7 +94,23 @@ void Audio::PoolThread::threadFunction()
 			}
 		}
 
+		if (paused.load())
+		{
+			disconnectCheck = 0;
+			sleep(5);
+			continue;
+		}
+
 		pool->update();
+
+		if (audio != nullptr && ++disconnectCheck >= DISCONNECT_CHECK_INTERVAL)
+		{
+			disconnectCheck = 0;
+
+			if (!audio->isDeviceConnected() && audio->reopenDevice())
+				pushAudioResetEvent();
+		}
+
 		sleep(5);
 	}
 }
@@ -72,6 +121,11 @@ void Audio::PoolThread::setFinish()
 	finish = true;
 }
 
+void Audio::PoolThread::setPaused(bool paused)
+{
+	this->paused.store(paused);
+}
+
 ALenum Audio::getFormat(int bitDepth, int channels)
 {
 	if (bitDepth != 8 && bitDepth != 16)
@@ -99,6 +153,8 @@ Audio::Audio()
 	, pool(nullptr)
 	, poolThread(nullptr)
 	, distanceModel(DISTANCE_INVERSE_CLAMPED)
+	, alcReopenDeviceSOFT(nullptr)
+	, reopenChecked(false)
 {
 	// Before opening new device, check if recording
 	// is requested.
@@ -189,13 +245,6 @@ Audio::Audio()
 		throw;
 	}
 
-	poolThread = new PoolThread(pool);
-	poolThread->start();
-	
-#ifdef LOVE_IOS
-	love::ios::initAudioSessionInterruptionHandler();
-#endif
-
 #ifdef LOVE_ANDROID
 	bool hasPauseDeviceExt = alcIsExtensionPresent(device, "ALC_SOFT_pause_device") == ALC_TRUE;
 	alcDevicePauseSOFT = hasPauseDeviceExt
@@ -205,6 +254,13 @@ Audio::Audio()
 		? (LPALCDEVICERESUMESOFT) alcGetProcAddress(device, "alcDeviceResumeSOFT")
 		: nullptr;
 #endif
+
+	poolThread = new PoolThread(this, pool);
+	poolThread->start();
+
+#ifdef LOVE_IOS
+	love::ios::initAudioSessionInterruptionHandler();
+#endif
 }
 
 Audio::~Audio()
@@ -314,6 +370,9 @@ std::vector<love::audio::Source*> Audio::pause()
 
 void Audio::pauseContext()
 {
+	if (poolThread != nullptr)
+		poolThread->setPaused(true);
+
 #ifdef LOVE_ANDROID
 	if (alcDevicePauseSOFT)
 		alcDevicePauseSOFT(device);
@@ -350,6 +409,52 @@ void Audio::resumeContext()
 	if (context && alcGetCurrentContext() != context)
 		alcMakeContextCurrent(context);
 #endif
+
+	if (poolThread != nullptr)
+		poolThread->setPaused(false);
+}
+
+bool Audio::reopenDevice()
+{
+	if (device == nullptr)
+		return false;
+
+	thread::Lock lock(deviceMutex);
+
+	if (!reopenChecked)
+	{
+		reopenChecked = true;
+
+		if (alcIsExtensionPresent(device, "ALC_SOFT_reopen_device") == ALC_TRUE)
+			alcReopenDeviceSOFT = (LPALCREOPENDEVICESOFT) alcGetProcAddress(device, "alcReopenDeviceSOFT");
+	}
+
+	if (alcReopenDeviceSOFT == nullptr)
+		return false;
+
+	alcGetError(device);
+
+	return alcReopenDeviceSOFT(device, nullptr, nullptr) == ALC_TRUE;
+}
+
+bool Audio::isDeviceConnected()
+{
+	if (device == nullptr)
+		return false;
+
+	thread::Lock lock(deviceMutex);
+
+	if (alcIsExtensionPresent(device, "ALC_EXT_disconnect") != ALC_TRUE)
+		return true;
+
+	ALCint connected = 1;
+	alcGetError(device);
+	alcGetIntegerv(device, ALC_CONNECTED, 1, &connected);
+
+	if (alcGetError(device) != ALC_NO_ERROR)
+		return true;
+
+	return connected != 0;
 }
 
 void Audio::setVolume(float volume)

mobile/android/love/src/jni/love/src/modules/audio/openal/Audio.h

@@ -22,6 +22,7 @@
 #define LOVE_AUDIO_OPENAL_AUDIO_H
 
 // STD
+#include <atomic>
 #include <queue>
 #include <map>
 #include <vector>
@@ -97,6 +98,8 @@ public:
 	std::vector<love::audio::Source*> pause();
 	void pauseContext();
 	void resumeContext();
+	bool reopenDevice();
+	bool isDeviceConnected();
 	void setVolume(float volume);
 	float getVolume() const;
 
@@ -155,6 +158,7 @@ private:
 	class PoolThread: public thread::Threadable
 	{
 	protected:
+		Audio *audio;
 		Pool *pool;
 
 		// Set this to true when the thread should finish.
@@ -162,13 +166,16 @@ private:
 		// will read from it.
 		volatile bool finish;
 
+		std::atomic<bool> paused;
+
 		// finish lock
 		love::thread::MutexRef mutex;
 
 	public:
-		PoolThread(Pool *pool);
+		PoolThread(Audio *audio, Pool *pool);
 		virtual ~PoolThread();
 		void setFinish();
+		void setPaused(bool paused);
 		void threadFunction();
 	};
 
@@ -177,6 +184,13 @@ private:
 	DistanceModel distanceModel;
 	//float metersPerUnit = 1.0;
 
+#ifndef ALC_SOFT_reopen_device
+	typedef ALCboolean (ALC_APIENTRY*LPALCREOPENDEVICESOFT)(ALCdevice *device, const ALCchar *deviceName, const ALCint *attribs);
+#endif
+	LPALCREOPENDEVICESOFT alcReopenDeviceSOFT;
+	bool reopenChecked;
+	love::thread::MutexRef deviceMutex;
+
 #ifdef LOVE_ANDROID
 #	ifndef ALC_SOFT_pause_device
 	typedef void (ALC_APIENTRY*LPALCDEVICEPAUSESOFT)(ALCdevice *device);
@@ -188,6 +202,9 @@ private:
 #endif
 }; // Audio
 
+void pushAudioSuspendEvent();
+void pushAudioResetEvent();
+
 #ifdef ALC_EXT_EFX
  // Effect objects
 extern LPALGENEFFECTS alGenEffects;

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

@@ -245,6 +245,25 @@ bool System::restartApp() const
 #endif
 }
 
+bool System::updateShortcuts(const std::vector<std::string> &versions) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::updateAppShortcuts(versions);
+#else
+	LOVE_UNUSED(versions);
+	return false;
+#endif
+}
+
+std::string System::getLaunchGame() const
+{
+#ifdef LOVE_ANDROID
+	return love::android::getLaunchGame();
+#else
+	return "";
+#endif
+}
+
 bool System::httpDownload(const char *url, const char *destPath,
 	const char *userAgent, const char *accept) const
 {
@@ -274,6 +293,27 @@ bool System::httpPost(const char *url, const char *body, int bodyLen,
 #endif
 }
 
+bool System::httpRequest(const char *url, const char *method,
+	const char *const *headerPairs, int headerPairCount,
+	const char *body, int bodyLen, const char *userAgent,
+	std::string &out) const
+{
+#ifdef LOVE_ANDROID
+	return love::android::httpRequest(url, method, headerPairs, headerPairCount,
+		body, bodyLen, userAgent, out);
+#else
+	LOVE_UNUSED(url);
+	LOVE_UNUSED(method);
+	LOVE_UNUSED(headerPairs);
+	LOVE_UNUSED(headerPairCount);
+	LOVE_UNUSED(body);
+	LOVE_UNUSED(bodyLen);
+	LOVE_UNUSED(userAgent);
+	out.clear();
+	return false;
+#endif
+}
+
 int System::tlsOpen(const char *host, int port) const
 {
 #ifdef LOVE_ANDROID

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

@@ -143,6 +143,9 @@ public:
 	 **/
 	virtual bool restartApp() const;
 
+	virtual bool updateShortcuts(const std::vector<std::string> &versions) const;
+	virtual std::string getLaunchGame() const;
+
 	/**
 	 * Blocking HTTPS GET into an absolute host path (Android only; false
 	 * elsewhere). Android has no curl, which is what every other platform
@@ -159,6 +162,18 @@ public:
 	virtual bool httpPost(const char *url, const char *body, int bodyLen,
 		const char *contentType = nullptr, const char *userAgent = nullptr) const;
 
+	/**
+	 * Blocking HTTPS request with a method, headers and a byte body (Android
+	 * only; false elsewhere). Save sync needs PUT, auth headers and the body
+	 * of a 4xx, none of which the two bridges above can express. headerPairs
+	 * is a flat name, value array; `out` receives the response envelope
+	 * ("STATUS <code>" or "ERROR <text>", a newline, then the raw body).
+	 **/
+	virtual bool httpRequest(const char *url, const char *method,
+		const char *const *headerPairs, int headerPairCount,
+		const char *body, int bodyLen, const char *userAgent,
+		std::string &out) const;
+
 	/**
 	 * TLS client sockets (Android only; every call fails elsewhere, where
 	 * LuaSec or another provider is the answer). Non-blocking by contract:

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

@@ -22,6 +22,9 @@
 #include "wrap_System.h"
 #include "sdl/System.h"
 
+#include <string>
+#include <vector>
+
 namespace love
 {
 namespace system
@@ -150,6 +153,57 @@ int w_httpPost(lua_State *L)
 	return 1;
 }
 
+/*
+ * love.system.httpRequest(url, method, headers, body, userAgent) -> envelope
+ *
+ * `headers` is a flat array of alternating header name and value strings, so
+ * it maps straight onto the Java bridge's String[] without any parsing here.
+ * The single return is the response envelope -- a head line of
+ * "STATUS <code>" or "ERROR <text>", a newline, then the raw body -- or nil
+ * where the build has no bridge, which src/core/HostShell.lua turns into an
+ * "update the app" notice rather than a failed request.
+ */
+int w_httpRequest(lua_State *L)
+{
+	const char *url = luaL_checkstring(L, 1);
+	const char *method = luaL_optstring(L, 2, "GET");
+
+	std::vector<std::string> fields;
+	if (!lua_isnoneornil(L, 3))
+	{
+		luaL_checktype(L, 3, LUA_TTABLE);
+		size_t count = luax_objlen(L, 3);
+		for (size_t i = 1; i <= count; i++)
+		{
+			lua_rawgeti(L, 3, (int) i);
+			const char *field = lua_tostring(L, -1);
+			fields.push_back(field != nullptr ? field : "");
+			lua_pop(L, 1);
+		}
+	}
+	std::vector<const char *> pairs;
+	for (size_t i = 0; i < fields.size(); i++)
+		pairs.push_back(fields[i].c_str());
+
+	size_t bodyLen = 0;
+	const char *body = nullptr;
+	if (!lua_isnoneornil(L, 4))
+		body = luaL_checklstring(L, 4, &bodyLen);
+	const char *ua = luaL_optstring(L, 5, nullptr);
+
+	std::string out;
+	bool ok = instance()->httpRequest(url, method,
+		pairs.empty() ? nullptr : &pairs[0], (int) pairs.size(),
+		body, (int) bodyLen, ua, out);
+	if (!ok)
+	{
+		lua_pushnil(L);
+		return 1;
+	}
+	lua_pushlstring(L, out.data(), out.size());
+	return 1;
+}
+
 int w_hasBackgroundMusic(lua_State *L)
 {
 	lua_pushboolean(L, instance()->hasBackgroundMusic());
@@ -229,6 +283,34 @@ int w_tlsClose(lua_State *L)
 	return 0;
 }
 
+int w_updateShortcuts(lua_State *L)
+{
+	if (!lua_istable(L, 1))
+		return luaL_error(L, "Expected table of game version strings");
+
+	std::vector<std::string> versions;
+	int len = (int) luax_objlen(L, 1);
+	for (int i = 1; i <= len; ++i)
+	{
+		lua_rawgeti(L, 1, i);
+		if (lua_isstring(L, -1))
+			versions.push_back(lua_tostring(L, -1));
+		lua_pop(L, 1);
+	}
+	luax_pushboolean(L, instance()->updateShortcuts(versions));
+	return 1;
+}
+
+int w_getLaunchGame(lua_State *L)
+{
+	std::string game = instance()->getLaunchGame();
+	if (game.empty())
+		lua_pushnil(L);
+	else
+		luax_pushstring(L, game);
+	return 1;
+}
+
 static const luaL_Reg functions[] =
 {
 	{ "getOS", w_getOS },
@@ -243,8 +325,11 @@ static const luaL_Reg functions[] =
 	{ "createFile", w_createFile },
 	{ "syncHealthSteps", w_syncHealthSteps },
 	{ "restartApp", w_restartApp },
+	{ "updateShortcuts", w_updateShortcuts },
+	{ "getLaunchGame", w_getLaunchGame },
 	{ "httpDownload", w_httpDownload },
 	{ "httpPost", w_httpPost },
+	{ "httpRequest", w_httpRequest },
 	{ "tlsOpen", w_tlsOpen },
 	{ "tlsStatus", w_tlsStatus },
 	{ "tlsSend", w_tlsSend },

mobile/android/love/src/jni/oboe/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Create a report to help us improve Oboe
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+Android version(s):
+Android device(s):
+Oboe version:
+App name used for testing: 
+(Please try to reproduce the issue using the OboeTester or an Oboe sample.)
+ 
+**Short description**
+(Please only report one bug per Issue. Do not combine multiple bugs.)
+
+**Steps to reproduce**
+
+**Expected behavior**
+
+**Actual behavior**
+
+**Device**
+
+Please list which devices have this bug.
+If device specific, and you are on Linux or a Macintosh, connect the device and please share the result for the following script. This gets properties of the device. 
+
+```
+for p in \
+    ro.product.brand ro.product.manufacturer ro.product.model \
+    ro.product.device ro.product.cpu.abi ro.build.description \
+    ro.hardware ro.hardware.chipname ro.arch "| grep aaudio";
+    do echo "$p = $(adb shell getprop $p)"; done
+```
+
+**Any additional context**
+
+If applicable, please attach a few seconds of an uncompressed recording of the sound in a WAV or AIFF file.

mobile/android/love/src/jni/oboe/.github/dependabot.yml

@@ -0,0 +1,36 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+
+#Workaround for https://github.com/dependabot/dependabot-core/issues/6888#issuecomment-1539501116
+registries:
+  maven-google:
+    type: maven-repository
+    url: "https://dl.google.com/dl/android/maven2/"
+
+updates:
+  #Check for updates to Github Actions
+  - package-ecosystem: "github-actions"
+    directory: "/"               #Location of package manifests
+    target-branch: "main"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "dependencies/github-actions"
+    schedule:
+      interval: "daily"
+
+  #Check updates for Gradle dependencies
+  - package-ecosystem: "gradle"
+    registries:
+      - maven-google
+    directory: "/"               #Location of package manifests
+    target-branch: "main"
+    open-pull-requests-limit: 10
+    labels:
+      - "dependencies"
+      - "dependencies/gradle"
+    schedule:
+      interval: "daily"

mobile/android/love/src/jni/oboe/.github/workflows/build-ci.yml

@@ -0,0 +1,38 @@
+name: Build CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+    - name: set up JDK 17
+      uses: actions/setup-java@v4
+      with:
+        distribution: 'temurin'
+        java-version: 17
+    - name: build samples and apps
+      uses: github/codeql-action/init@v3
+      with:
+        languages: cpp
+    - run: |
+        pushd samples
+        chmod +x gradlew
+        ./gradlew -q clean bundleDebug
+        popd
+        pushd apps/OboeTester
+        chmod +x gradlew
+        ./gradlew -q clean bundleDebug
+        popd
+        pushd apps/fxlab
+        chmod +x gradlew
+        ./gradlew -q clean bundleDebug
+        popd
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3

mobile/android/love/src/jni/oboe/.github/workflows/update-docs.yml

@@ -0,0 +1,24 @@
+name: Update Docs
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Doxygen Action
+      uses: mattnotmitt/doxygen-action@v1.9.8
+      with:
+        doxyfile-path: "./Doxyfile"
+        working-directory: "."
+
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v4
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/reference

mobile/android/love/src/jni/oboe/.gitignore

@@ -4,3 +4,5 @@
 .cxx/
 .idea
 build
+.logpile
+

mobile/android/love/src/jni/oboe/Android.mk

@@ -1,32 +1,21 @@
 LOCAL_PATH:= $(call my-dir)
 include $(CLEAR_VARS)
 
-#
-# Module
-#
 LOCAL_MODULE := oboe
 LOCAL_ARM_NEON := true
 
-#
-# Flags
-#
 LOCAL_CFLAGS := -Wall -Wextra-semi -Wshadow -Wshadow-field
-LOCAL_CPPFLAGS := -std=c++14 
+LOCAL_CPPFLAGS := -std=c++17
 
-#
-# Include paths
-#
 LOCAL_C_INCLUDES := \
 	$(LOCAL_PATH)/include \
 	$(LOCAL_PATH)/src
 LOCAL_EXPORT_C_INCLUDES := $(LOCAL_PATH)/include
 
-#
-# Source files
-#
 LOCAL_SRC_FILES := \
     src/aaudio/AAudioLoader.cpp \
     src/aaudio/AudioStreamAAudio.cpp \
+    src/common/AdpfWrapper.cpp \
     src/common/AudioSourceCaller.cpp \
     src/common/AudioStream.cpp \
     src/common/AudioStreamBuilder.cpp \
@@ -36,8 +25,11 @@ LOCAL_SRC_FILES := \
     src/common/FixedBlockReader.cpp \
     src/common/FixedBlockWriter.cpp \
     src/common/LatencyTuner.cpp \
+    src/common/OboeExtensions.cpp \
     src/common/SourceFloatCaller.cpp \
     src/common/SourceI16Caller.cpp \
+    src/common/SourceI24Caller.cpp \
+    src/common/SourceI32Caller.cpp \
     src/common/Utilities.cpp \
     src/common/QuirksManager.cpp \
     src/fifo/FifoBuffer.cpp \
@@ -45,17 +37,26 @@ LOCAL_SRC_FILES := \
     src/fifo/FifoControllerBase.cpp \
     src/fifo/FifoControllerIndirect.cpp \
     src/flowgraph/FlowGraphNode.cpp \
+    src/flowgraph/ChannelCountConverter.cpp \
     src/flowgraph/ClipToRange.cpp \
+    src/flowgraph/Limiter.cpp \
     src/flowgraph/ManyToMultiConverter.cpp \
+    src/flowgraph/MonoBlend.cpp \
     src/flowgraph/MonoToMultiConverter.cpp \
+    src/flowgraph/MultiToManyConverter.cpp \
+    src/flowgraph/MultiToMonoConverter.cpp \
     src/flowgraph/RampLinear.cpp \
     src/flowgraph/SampleRateConverter.cpp \
     src/flowgraph/SinkFloat.cpp \
     src/flowgraph/SinkI16.cpp \
     src/flowgraph/SinkI24.cpp \
+    src/flowgraph/SinkI32.cpp \
+    src/flowgraph/SinkI8_24.cpp \
     src/flowgraph/SourceFloat.cpp \
     src/flowgraph/SourceI16.cpp \
     src/flowgraph/SourceI24.cpp \
+    src/flowgraph/SourceI32.cpp \
+    src/flowgraph/SourceI8_24.cpp \
     src/flowgraph/resampler/IntegerRatio.cpp \
     src/flowgraph/resampler/LinearResampler.cpp \
     src/flowgraph/resampler/MultiChannelResampler.cpp \
@@ -75,10 +76,6 @@ LOCAL_SRC_FILES := \
     src/common/Trace.cpp \
     src/common/Version.cpp
 
-#
-# Libraries related
-#
 LOCAL_LDLIBS := -llog
 
-# Build
 include $(BUILD_STATIC_LIBRARY)

mobile/android/love/src/jni/oboe/CMakeLists.txt

@@ -9,6 +9,7 @@ project(oboe)
 set (oboe_sources
     src/aaudio/AAudioLoader.cpp
     src/aaudio/AudioStreamAAudio.cpp
+    src/common/AdpfWrapper.cpp
     src/common/AudioSourceCaller.cpp
     src/common/AudioStream.cpp
     src/common/AudioStreamBuilder.cpp
@@ -18,8 +19,11 @@ set (oboe_sources
     src/common/FixedBlockReader.cpp
     src/common/FixedBlockWriter.cpp
     src/common/LatencyTuner.cpp
+    src/common/OboeExtensions.cpp
     src/common/SourceFloatCaller.cpp
     src/common/SourceI16Caller.cpp
+    src/common/SourceI24Caller.cpp
+    src/common/SourceI32Caller.cpp
     src/common/Utilities.cpp
     src/common/QuirksManager.cpp
     src/fifo/FifoBuffer.cpp
@@ -27,17 +31,26 @@ set (oboe_sources
     src/fifo/FifoControllerBase.cpp
     src/fifo/FifoControllerIndirect.cpp
     src/flowgraph/FlowGraphNode.cpp
+    src/flowgraph/ChannelCountConverter.cpp
     src/flowgraph/ClipToRange.cpp
+    src/flowgraph/Limiter.cpp
     src/flowgraph/ManyToMultiConverter.cpp
+    src/flowgraph/MonoBlend.cpp
     src/flowgraph/MonoToMultiConverter.cpp
+    src/flowgraph/MultiToManyConverter.cpp
+    src/flowgraph/MultiToMonoConverter.cpp
     src/flowgraph/RampLinear.cpp
     src/flowgraph/SampleRateConverter.cpp
     src/flowgraph/SinkFloat.cpp
     src/flowgraph/SinkI16.cpp
     src/flowgraph/SinkI24.cpp
+    src/flowgraph/SinkI32.cpp
+    src/flowgraph/SinkI8_24.cpp
     src/flowgraph/SourceFloat.cpp
     src/flowgraph/SourceI16.cpp
     src/flowgraph/SourceI24.cpp
+    src/flowgraph/SourceI32.cpp
+    src/flowgraph/SourceI8_24.cpp
     src/flowgraph/resampler/IntegerRatio.cpp
     src/flowgraph/resampler/LinearResampler.cpp
     src/flowgraph/resampler/MultiChannelResampler.cpp
@@ -70,18 +83,23 @@ target_include_directories(oboe
 #     Enable -Ofast
 target_compile_options(oboe
         PRIVATE
-        -std=c++14
+        -std=c++17
         -Wall
         -Wextra-semi
         -Wshadow
         -Wshadow-field
-        -Ofast
+        "$<$<CONFIG:RELEASE>:-Ofast>"
+        "$<$<CONFIG:DEBUG>:-O3>"
         "$<$<CONFIG:DEBUG>:-Werror>")
 
 # Enable logging of D,V for debug builds
 target_compile_definitions(oboe PUBLIC $<$<CONFIG:DEBUG>:OBOE_ENABLE_LOGGING=1>)
 
+option(OBOE_DO_NOT_DEFINE_OPENSL_ES_CONSTANTS "Do not define OpenSLES constants" OFF)
+target_compile_definitions(oboe PRIVATE $<$<BOOL:${OBOE_DO_NOT_DEFINE_OPENSL_ES_CONSTANTS}>:DO_NOT_DEFINE_OPENSL_ES_CONSTANTS=1>)
+
 target_link_libraries(oboe PRIVATE log OpenSLES)
+target_link_options(oboe PRIVATE "-Wl,-z,max-page-size=16384")
 
 # When installing oboe put the libraries in the lib/<ABI> folder e.g. lib/arm64-v8a
 install(TARGETS oboe

mobile/android/love/src/jni/oboe/CONTRIBUTING

@@ -1 +0,0 @@
-Please see the CONTRIBUTING.md file for more information.

mobile/android/love/src/jni/oboe/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Oboe"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.2
+PROJECT_NUMBER         =
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = docs
+OUTPUT_DIRECTORY       = ./docs
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and

mobile/android/love/src/jni/oboe/README

@@ -1 +0,0 @@
-Please see the README.md file for more information.

mobile/android/love/src/jni/oboe/README.md

@@ -1,4 +1,4 @@
-# Oboe [![Build Status](https://travis-ci.org/google/oboe.svg?branch=master)](https://travis-ci.org/google/oboe)
+# Oboe [![Build CI](https://github.com/google/oboe/workflows/Build%20CI/badge.svg)](https://github.com/google/oboe/actions)
 
 [![Introduction to Oboe video](docs/images/getting-started-video.jpg)](https://www.youtube.com/watch?v=csfHAbr5ilI&list=PLWz5rJ2EKKc_duWv9IPNvx9YBudNMmLSa)
 
@@ -9,35 +9,36 @@ Oboe is a C++ library which makes it easy to build high-performance audio apps o
 - Chooses the audio API (OpenSL ES on API 16+ or AAudio on API 27+) which will give the best audio performance on the target Android device
 - Automatic latency tuning
 - Modern C++ allowing you to write clean, elegant code
-- [Used by popular apps and frameworks](docs/AppsUsingOboe.md)
+- Workarounds for some known issues
+- [Used by popular apps and frameworks](https://github.com/google/oboe/wiki/AppsUsingOboe)
 
-## Requirements
+## Documentation
-To build Oboe you'll need a compiler which supports C++14 and the Android header files. The easiest way to obtain these is by downloading the Android NDK r17 or above. It can be installed using Android Studio's SDK manager, or via [direct download](https://developer.android.com/ndk/downloads/).
-
-## API Documentation
 - [Getting Started Guide](docs/GettingStarted.md)
 - [Full Guide to Oboe](docs/FullGuide.md)
-- [API reference](https://google.github.io/oboe/reference)
+- [API reference](https://google.github.io/oboe)
-- [Tech Notes](docs/notes/)
 - [History of Audio features/bugs by Android version](docs/AndroidAudioHistory.md)
+- [Migration guide for apps using OpenSL ES](docs/OpenSLESMigration.md)
 - [Frequently Asked Questions](docs/FAQ.md) (FAQ)
+- [Wiki](https://github.com/google/oboe/wiki)
 - [Our roadmap](https://github.com/google/oboe/milestones) - Vote on a feature/issue by adding a thumbs up to the first comment.
 
+### Community
+- Reddit: [r/androidaudiodev](https://www.reddit.com/r/androidaudiodev/)
+- StackOverflow: [#oboe](https://stackoverflow.com/questions/tagged/oboe)
+
 ## Testing
-- [**OboeTester** app for measuring latency, glitches, etc.](https://github.com/google/oboe/tree/master/apps/OboeTester/docs)
+- [**OboeTester** app for measuring latency, glitches, etc.](apps/OboeTester/docs)
-- [Oboe unit tests](https://github.com/google/oboe/tree/master/tests)
+- [Oboe unit tests](tests)
 
 ## Videos
 - [Getting started with Oboe](https://www.youtube.com/playlist?list=PLWz5rJ2EKKc_duWv9IPNvx9YBudNMmLSa)
 - [Low Latency Audio - Because Your Ears Are Worth It](https://www.youtube.com/watch?v=8vOf_fDtur4) (Android Dev Summit '18)
-- [Real-time audio with the 100 oscillator synthesizer](https://www.youtube.com/watch?v=J04iPJBkAKs) (DroidCon Berlin '18)
 - [Winning on Android](https://www.youtube.com/watch?v=tWBojmBpS74) - How to optimize an Android audio app. (ADC '18)
-- [Real-Time Processing on Android](https://youtu.be/hY9BrS2uX-c) (ADC '19)
 
 ## Sample code and apps
 - Sample apps can be found in the [samples directory](samples). 
 - A complete "effects processor" app called FXLab can  be found in the [apps/fxlab folder](apps/fxlab). 
-- Also check out the [Rhythm Game codelab](https://codelabs.developers.google.com/codelabs/musicalgame-using-oboe/index.html#0).
+- Also check out the [Rhythm Game codelab](https://developer.android.com/codelabs/musicalgame-using-oboe?hl=en#0).
 
 ### Third party sample code
 - [Ableton Link integration demo](https://github.com/jbloit/AndroidLinkAudio) (author: jbloit)

mobile/android/love/src/jni/oboe/apps/OboeTester/.gitignore

@@ -6,6 +6,8 @@
 /build/
 .idea/
 /app/build/
+/app/release/
+/app/debug/
 /app/app.iml
 *.iml
 /app/externalNativeBuild/

mobile/android/love/src/jni/oboe/apps/OboeTester/app/CMakeLists.txt

@@ -1,11 +1,14 @@
 cmake_minimum_required(VERSION 3.4.1)
 
-set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Werror -Wall -std=c++14")
+set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Werror -Wall -std=c++17 -fvisibility=hidden")
 set(CMAKE_CXX_FLAGS_DEBUG "${CMAKE_CXX_FLAGS_DEBUG} -O2")
 set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3")
 
 link_directories(${CMAKE_CURRENT_LIST_DIR}/..)
 
+# Increment this number when adding files to OboeTester => 105
+# The change in this file will help Android Studio resync
+# and generate new build files that reference the new code.
 file(GLOB_RECURSE app_native_sources src/main/cpp/*)
 
 ### Name must match loadLibrary() call in MainActivity.java
@@ -30,5 +33,4 @@ include_directories(
 
 # link to oboe
 target_link_libraries(oboetester log oboe atomic)
-
+target_link_options(oboetester PRIVATE "-Wl,-z,max-page-size=16384")
-# bump 2 to resync CMake

mobile/android/love/src/jni/oboe/apps/OboeTester/app/build.gradle

@@ -1,18 +1,17 @@
 apply plugin: 'com.android.application'
 
 android {
-    compileSdkVersion 28
+    compileSdkVersion 34
     defaultConfig {
-        applicationId = "com.google.sample.oboe.manualtest"
+        applicationId = "com.mobileer.oboetester"
         minSdkVersion 23
-        targetSdkVersion 28
+        targetSdkVersion 34
-        // Also update the version in the AndroidManifest.xml file.
+        versionCode 91
-        versionCode 32
+        versionName "2.7.2"
-        versionName "1.5.24"
         testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
         externalNativeBuild {
             cmake {
-                cppFlags "-std=c++14"
+                cppFlags "-std=c++17"
                 abiFilters "x86", "x86_64", "armeabi-v7a", "arm64-v8a"
             }
         }
@@ -31,14 +30,15 @@ android {
             path "CMakeLists.txt"
         }
     }
+    namespace 'com.mobileer.oboetester'
 }
 
 dependencies {
     implementation fileTree(include: ['*.jar'], dir: 'libs')
-    implementation 'com.android.support.constraint:constraint-layout:2.0.0-beta4'
+    implementation "androidx.core:core-ktx:1.9.0"
+    implementation 'androidx.constraintlayout:constraintlayout:2.1.4'
+    implementation 'androidx.appcompat:appcompat:1.6.1'
 
-    testImplementation 'junit:junit:4.13-beta-3'
+    androidTestImplementation 'androidx.test.ext:junit:1.1.5'
-    implementation 'com.android.support:appcompat-v7:28.0.0'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.5.1'
-    androidTestImplementation 'com.android.support.test:runner:1.0.2'
-    androidTestImplementation 'com.android.support.test.espresso:espresso-core:3.0.2'
 }

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/AndroidManifest.xml

@@ -1,100 +1,138 @@
 <?xml version="1.0" encoding="utf-8"?>
-<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
-    package="com.google.sample.oboe.manualtest"
+    <uses-feature
-    android:versionCode="32"
+        android:name="android.hardware.microphone"
-    android:versionName="1.5.24">
+        android:required="false" />
-    <!-- versionCode and versionName also have to be updated in build.gradle -->
+    <uses-feature
-
+        android:name="android.hardware.audio.output"
-    <uses-feature android:name="android.hardware.microphone" android:required="true" />
+        android:required="true" />
-    <uses-feature android:name="android.hardware.audio.output" android:required="true" />
+    <uses-feature
-    <uses-feature android:name="android.software.midi" android:required="true" />
+        android:name="android.hardware.touchscreen"
+        android:required="false" />
+    <uses-feature
+        android:name="android.software.midi"
+        android:required="false" />
+    <uses-feature
+        android:name="android.software.leanback"
+        android:required="false" />
 
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
     <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
     <uses-permission android:name="android.permission.INTERNET" />
-    <!-- debug-writing file need external storage writing -->
-    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
-
     <uses-permission android:name="android.permission.READ_PHONE_STATE" />
-    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
 
     <application
-        android:allowBackup="false"
-        android:fullBackupContent="false"
         android:icon="@mipmap/ic_launcher"
         android:label="@string/app_name"
         android:supportsRtl="true"
-        android:theme="@style/AppTheme">
+        android:theme="@style/AppTheme"
-
+        android:requestLegacyExternalStorage="true"
+        android:banner="@mipmap/ic_launcher">
         <activity
-            android:name="com.google.sample.oboe.manualtest.MainActivity"
+            android:name=".MainActivity"
             android:launchMode="singleTask"
-            android:label="@string/app_name"
+            android:screenOrientation="portrait"
-            android:screenOrientation="portrait">
+            android:exported="true">
             <intent-filter>
                 <action android:name="android.intent.action.MAIN" />
 
                 <category android:name="android.intent.category.LAUNCHER" />
+                <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
             </intent-filter>
         </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.TestOutputActivity"
+            android:name=".TestOutputActivity"
             android:label="@string/title_activity_test_output"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.TestInputActivity"
+            android:name=".TestInputActivity"
             android:label="@string/title_activity_test_input"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.TapToToneActivity"
+            android:name=".TapToToneActivity"
             android:label="@string/title_activity_output_latency"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.RecorderActivity"
+            android:name=".RecorderActivity"
             android:label="@string/title_activity_recorder"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.EchoActivity"
+            android:name=".EchoActivity"
             android:label="@string/title_activity_echo"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.RoundTripLatencyActivity"
+            android:name=".RoundTripLatencyActivity"
             android:label="@string/title_activity_rt_latency"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.ManualGlitchActivity"
+            android:name=".ManualGlitchActivity"
             android:label="@string/title_activity_glitches"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.AutoGlitchActivity"
+            android:name=".AutomatedGlitchActivity"
-            android:label="@string/title_activity_glitches"
+            android:label="@string/title_activity_auto_glitches"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
-
         <activity
-            android:name="com.google.sample.oboe.manualtest.TestDisconnectActivity"
+            android:name=".TestDisconnectActivity"
             android:label="@string/title_test_disconnect"
-            android:screenOrientation="portrait">
+            android:screenOrientation="portrait" />
-        </activity>
+        <activity
+            android:name=".DeviceReportActivity"
+            android:label="@string/title_report_devices"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".TestDataPathsActivity"
+            android:label="@string/title_data_paths"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".ExtraTestsActivity"
+            android:exported="true"
+            android:label="@string/title_extra_tests"
+            android:screenOrientation="portrait" />
+
+        <activity
+            android:name=".ExternalTapToToneActivity"
+            android:label="@string/title_external_tap"
+            android:exported="true"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".TestPlugLatencyActivity"
+            android:label="@string/title_plug_latency"
+            android:exported="true"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".TestErrorCallbackActivity"
+            android:label="@string/title_error_callback"
+            android:exported="true"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".TestRouteDuringCallbackActivity"
+            android:label="@string/title_route_during_callback"
+            android:exported="true"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".DynamicWorkloadActivity"
+            android:label="@string/title_dynamic_load"
+            android:exported="true"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".TestColdStartLatencyActivity"
+            android:label="@string/title_cold_start_latency"
+            android:exported="true"
+            android:screenOrientation="portrait" />
+        <activity
+            android:name=".TestRapidCycleActivity"
+            android:label="@string/title_rapid_cycle"
+            android:exported="true"
+            android:screenOrientation="portrait" />
 
         <service
-            android:name="com.google.sample.oboe.manualtest.AudioMidiTester"
+            android:name=".MidiTapTester"
-            android:permission="android.permission.BIND_MIDI_DEVICE_SERVICE">
+            android:permission="android.permission.BIND_MIDI_DEVICE_SERVICE"
+            android:exported="true">
             <intent-filter>
                 <action android:name="android.media.midi.MidiDeviceService" />
             </intent-filter>
@@ -104,8 +142,14 @@
                 android:resource="@xml/service_device_info" />
         </service>
 
+        <service
+            android:name=".AudioForegroundService"
+            android:foregroundServiceType="mediaPlayback|microphone"
+            android:exported="false">
+        </service>
+
         <provider
-            android:name="android.support.v4.content.FileProvider"
+            android:name="androidx.core.content.FileProvider"
             android:authorities="${applicationId}.provider"
             android:exported="false"
             android:grantUriPermissions="true">
@@ -113,7 +157,6 @@
                 android:name="android.support.FILE_PROVIDER_PATHS"
                 android:resource="@xml/provider_paths" />
         </provider>
-
     </application>
 
 </manifest>

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/AudioStreamGateway.cpp

@@ -17,29 +17,24 @@
 #include <cstring>
 #include <sched.h>
 
+#include "common/OboeDebug.h"
 #include "oboe/Oboe.h"
 #include "AudioStreamGateway.h"
 
-using namespace flowgraph;
+using namespace oboe::flowgraph;
 
 oboe::DataCallbackResult AudioStreamGateway::onAudioReady(
         oboe::AudioStream *audioStream,
         void *audioData,
         int numFrames) {
 
-    if (!mSchedulerChecked) {
+    maybeHang(getNanoseconds());
-        mScheduler = sched_getscheduler(gettid());
+    printScheduler();
-        mSchedulerChecked = true;
-    }
 
     if (mAudioSink != nullptr) {
-        mAudioSink->read(mFramePosition, audioData, numFrames);
+        mAudioSink->read(audioData, numFrames);
-        mFramePosition += numFrames;
     }
 
     return oboe::DataCallbackResult::Continue;
 }
 
-int AudioStreamGateway::getScheduler() {
-    return mScheduler;
-}

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/AudioStreamGateway.h

@@ -21,24 +21,21 @@
 
 #include "flowgraph/FlowGraphNode.h"
 #include "oboe/Oboe.h"
+#include "OboeTesterStreamCallback.h"
 
-using namespace flowgraph;
+using namespace oboe::flowgraph;
 
 /**
  * Bridge between an audio flowgraph and an audio device.
  * Pass in an AudioSink and then pass
  * this object to the AudioStreamBuilder as a callback.
  */
-class AudioStreamGateway : public oboe::AudioStreamCallback {
+class AudioStreamGateway : public OboeTesterStreamCallback {
 public:
-//    AudioStreamGateway(int samplesPerFrame);
     virtual ~AudioStreamGateway() = default;
 
-    void setAudioSink(std::shared_ptr<flowgraph::FlowGraphSink>  sink) {
+    void setAudioSink(std::shared_ptr<oboe::flowgraph::FlowGraphSink>  sink) {
         mAudioSink = sink;
-        if (sink) {
-            mFramePosition = sink->getLastFramePosition();
-        }
     }
 
     /**
@@ -49,13 +46,9 @@ public:
             void *audioData,
             int numFrames) override;
 
-    int getScheduler();
-
 private:
-    int64_t  mFramePosition = 0;
+
-    bool     mSchedulerChecked = false;
+    std::shared_ptr<oboe::flowgraph::FlowGraphSink>  mAudioSink;
-    int      mScheduler;
-    std::shared_ptr<flowgraph::FlowGraphSink>  mAudioSink;
 };
 
 

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/FormatConverterBox.cpp

@@ -0,0 +1,91 @@
+/*
+ * Copyright 2021 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include "FormatConverterBox.h"
+
+FormatConverterBox::FormatConverterBox(int32_t maxSamples,
+                                       oboe::AudioFormat inputFormat,
+                                       oboe::AudioFormat outputFormat) {
+    mInputFormat = inputFormat;
+    mOutputFormat = outputFormat;
+
+    mMaxSamples = maxSamples;
+    mInputBuffer = std::make_unique<uint8_t[]>(maxSamples * sizeof(int32_t));
+    mOutputBuffer = std::make_unique<uint8_t[]>(maxSamples * sizeof(int32_t));
+
+    mSource.reset();
+    switch (mInputFormat) {
+        case oboe::AudioFormat::I16:
+        case oboe::AudioFormat::IEC61937:
+            mSource = std::make_unique<oboe::flowgraph::SourceI16>(1);
+            break;
+        case oboe::AudioFormat::I24:
+            mSource = std::make_unique<oboe::flowgraph::SourceI24>(1);
+            break;
+        case oboe::AudioFormat::I32:
+            mSource = std::make_unique<oboe::flowgraph::SourceI32>(1);
+            break;
+        case oboe::AudioFormat::Float:
+        case oboe::AudioFormat::Invalid:
+        case oboe::AudioFormat::Unspecified:
+            mSource = std::make_unique<oboe::flowgraph::SourceFloat>(1);
+            break;
+    }
+
+    mSink.reset();
+    switch (mOutputFormat) {
+        case oboe::AudioFormat::I16:
+        case oboe::AudioFormat::IEC61937:
+            mSink = std::make_unique<oboe::flowgraph::SinkI16>(1);
+            break;
+        case oboe::AudioFormat::I24:
+            mSink = std::make_unique<oboe::flowgraph::SinkI24>(1);
+            break;
+        case oboe::AudioFormat::I32:
+            mSink = std::make_unique<oboe::flowgraph::SinkI32>(1);
+            break;
+        case oboe::AudioFormat::Float:
+        case oboe::AudioFormat::Invalid:
+        case oboe::AudioFormat::Unspecified:
+            mSink = std::make_unique<oboe::flowgraph::SinkFloat>(1);
+            break;
+    }
+
+    if (mSource && mSink) {
+        mSource->output.connect(&mSink->input);
+        mSink->pullReset();
+    }
+}
+
+int32_t FormatConverterBox::convertInternalBuffers(int32_t numSamples) {
+    assert(numSamples <= mMaxSamples);
+    return convert(getOutputBuffer(), numSamples, getInputBuffer());
+}
+
+int32_t FormatConverterBox::convertToInternalOutput(int32_t numSamples, const void *inputBuffer) {
+    assert(numSamples <= mMaxSamples);
+    return convert(getOutputBuffer(), numSamples, inputBuffer);
+}
+
+int32_t FormatConverterBox::convertFromInternalInput(void *outputBuffer, int32_t numSamples) {
+    assert(numSamples <= mMaxSamples);
+    return convert(outputBuffer, numSamples, getInputBuffer());
+}
+
+int32_t FormatConverterBox::convert(void *outputBuffer, int32_t numSamples, const void *inputBuffer) {
+    mSource->setData(inputBuffer, numSamples);
+    return mSink->read(outputBuffer, numSamples);
+}

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/FormatConverterBox.h

@@ -0,0 +1,102 @@
+/*
+ * Copyright 2021 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef OBOETESTER_FORMAT_CONVERTER_BOX_H
+#define OBOETESTER_FORMAT_CONVERTER_BOX_H
+
+#include <unistd.h>
+#include <sys/types.h>
+
+#include "oboe/Oboe.h"
+#include "flowgraph/SinkFloat.h"
+#include "flowgraph/SinkI16.h"
+#include "flowgraph/SinkI24.h"
+#include "flowgraph/SinkI32.h"
+#include "flowgraph/SourceFloat.h"
+#include "flowgraph/SourceI16.h"
+#include "flowgraph/SourceI24.h"
+#include "flowgraph/SourceI32.h"
+
+/**
+ * Use flowgraph modules to convert between the various data formats.
+ *
+ * Note that this does not do channel conversions.
+ */
+
+class FormatConverterBox {
+public:
+    FormatConverterBox(int32_t maxSamples,
+                       oboe::AudioFormat inputFormat,
+                       oboe::AudioFormat outputFormat);
+
+    /**
+     * @return internal buffer used to store input data
+     */
+    void *getOutputBuffer() {
+        return (void *) mOutputBuffer.get();
+    };
+    /**
+     * @return internal buffer used to store output data
+     */
+    void *getInputBuffer() {
+        return (void *) mInputBuffer.get();
+    };
+
+    /** Convert the data from inputFormat to outputFormat
+     * using both internal buffers.
+     */
+    int32_t convertInternalBuffers(int32_t numSamples);
+
+    /**
+     * Convert data from external buffer into internal output buffer.
+     * @param numSamples
+     * @param inputBuffer
+     * @return
+     */
+    int32_t convertToInternalOutput(int32_t numSamples, const void *inputBuffer);
+
+    /**
+     *
+     * Convert data from internal input buffer into external output buffer.
+     * @param outputBuffer
+     * @param numSamples
+     * @return
+     */
+    int32_t convertFromInternalInput(void *outputBuffer, int32_t numSamples);
+
+    /**
+     * Convert data formats between the specified external buffers.
+     * @param outputBuffer
+     * @param numSamples
+     * @param inputBuffer
+     * @return
+     */
+    int32_t convert(void *outputBuffer, int32_t numSamples, const void *inputBuffer);
+
+private:
+    oboe::AudioFormat mInputFormat{oboe::AudioFormat::Invalid};
+    oboe::AudioFormat mOutputFormat{oboe::AudioFormat::Invalid};
+
+    int32_t mMaxSamples = 0;
+    std::unique_ptr<uint8_t[]> mInputBuffer;
+    std::unique_ptr<uint8_t[]> mOutputBuffer;
+
+    std::unique_ptr<oboe::flowgraph::FlowGraphSourceBuffered>  mSource;
+    std::unique_ptr<oboe::flowgraph::FlowGraphSink>  mSink;
+};
+
+
+#endif //OBOETESTER_FORMAT_CONVERTER_BOX_H

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/FullDuplexAnalyzer.cpp

@@ -19,28 +19,39 @@
 
 oboe::Result  FullDuplexAnalyzer::start() {
     getLoopbackProcessor()->setSampleRate(getOutputStream()->getSampleRate());
-    getLoopbackProcessor()->onStartTest();
+    getLoopbackProcessor()->prepareToTest();
-    return FullDuplexStream::start();
+    mWriteReadDeltaValid = false;
+    return FullDuplexStreamWithConversion::start();
 }
 
-oboe::DataCallbackResult FullDuplexAnalyzer::onBothStreamsReady(
+oboe::DataCallbackResult FullDuplexAnalyzer::onBothStreamsReadyFloat(
-        const void *inputData,
+        const float *inputData,
         int   numInputFrames,
-        void *outputData,
+        float *outputData,
         int   numOutputFrames) {
 
     int32_t inputStride = getInputStream()->getChannelCount();
     int32_t outputStride = getOutputStream()->getChannelCount();
-    float *inputFloat = (float *) inputData;
+    auto *inputFloat = static_cast<const float *>(inputData);
-    float *outputFloat = (float *) outputData;
+    float *outputFloat = outputData;
+
+    // Get atomic snapshot of the relative frame positions so they
+    // can be used to calculate timestamp latency.
+    int64_t framesRead = getInputStream()->getFramesRead();
+    int64_t framesWritten = getOutputStream()->getFramesWritten();
+    mWriteReadDelta = framesWritten - framesRead;
+    mWriteReadDeltaValid = true;
 
     (void) getLoopbackProcessor()->process(inputFloat, inputStride, numInputFrames,
                                    outputFloat, outputStride, numOutputFrames);
 
-    // write the first channel of output and input to the stereo recorder
+    // Save data for later analysis or for writing to a WAVE file.
     if (mRecording != nullptr) {
         float buffer[2];
         int numBoth = std::min(numInputFrames, numOutputFrames);
+        // Offset to the selected channels that we are analyzing.
+        inputFloat += getLoopbackProcessor()->getInputChannel();
+        outputFloat += getLoopbackProcessor()->getOutputChannel();
         for (int i = 0; i < numBoth; i++) {
             buffer[0] = *outputFloat;
             outputFloat += outputStride;
@@ -48,14 +59,15 @@ oboe::DataCallbackResult FullDuplexAnalyzer::onBothStreamsReady(
             inputFloat += inputStride;
             mRecording->write(buffer, 1);
         }
-        // Handle mismatch in in numFrames.
+        // Handle mismatch in numFrames.
-        buffer[0] = 0.0f; // gap in output
+        const float gapMarker = -0.9f; // Recognizable value so we can tell underruns from DSP gaps.
+        buffer[0] = gapMarker; // gap in output
         for (int i = numBoth; i < numInputFrames; i++) {
             buffer[1] = *inputFloat;
             inputFloat += inputStride;
             mRecording->write(buffer, 1);
         }
-        buffer[1] = 0.0f; // gap in input
+        buffer[1] = gapMarker; // gap in input
         for (int i = numBoth; i < numOutputFrames; i++) {
             buffer[0] = *outputFloat;
             outputFloat += outputStride;

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/FullDuplexAnalyzer.h

@@ -21,40 +21,52 @@
 #include <sys/types.h>
 
 #include "oboe/Oboe.h"
-#include "FullDuplexStream.h"
 #include "analyzer/LatencyAnalyzer.h"
+#include "FullDuplexStreamWithConversion.h"
 #include "MultiChannelRecording.h"
 
-class FullDuplexAnalyzer : public FullDuplexStream {
+class FullDuplexAnalyzer : public FullDuplexStreamWithConversion {
 public:
-    FullDuplexAnalyzer() {}
+    FullDuplexAnalyzer(LoopbackProcessor *processor)
+            : mLoopbackProcessor(processor) {
+    }
 
     /**
      * Called when data is available on both streams.
      * Caller should override this method.
      */
-    oboe::DataCallbackResult onBothStreamsReady(
+    oboe::DataCallbackResult onBothStreamsReadyFloat(
-            const void *inputData,
+            const float *inputData,
             int   numInputFrames,
-            void *outputData,
+            float *outputData,
             int   numOutputFrames
     ) override;
 
     oboe::Result start() override;
 
-    bool isDone() {
+    LoopbackProcessor *getLoopbackProcessor() {
-        return false;
+        return mLoopbackProcessor;
     }
 
-    virtual LoopbackProcessor *getLoopbackProcessor() = 0;
-
     void setRecording(MultiChannelRecording *recording) {
         mRecording = recording;
     }
 
+    bool isWriteReadDeltaValid() {
+        return mWriteReadDeltaValid;
+    }
+
+    int64_t getWriteReadDelta() {
+        return mWriteReadDelta;
+    }
+
 private:
     MultiChannelRecording  *mRecording = nullptr;
 
+    LoopbackProcessor * const mLoopbackProcessor;
+
+    std::atomic<bool> mWriteReadDeltaValid{false};
+    std::atomic<int64_t> mWriteReadDelta{0};
 };
 
 

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/FullDuplexEcho.cpp

@@ -20,28 +20,46 @@
 oboe::Result  FullDuplexEcho::start() {
     int32_t delayFrames = (int32_t) (kMaxDelayTimeSeconds * getOutputStream()->getSampleRate());
     mDelayLine = std::make_unique<InterpolatingDelayLine>(delayFrames);
-    return FullDuplexStream::start();
+    // Use peak detector for input streams
+    mNumChannels = getInputStream()->getChannelCount();
+    mPeakDetectors = std::make_unique<PeakDetector[]>(mNumChannels);
+    return FullDuplexStreamWithConversion::start();
 }
 
-oboe::DataCallbackResult FullDuplexEcho::onBothStreamsReady(
+double FullDuplexEcho::getPeakLevel(int index) {
-        const void *inputData,
+    if (mPeakDetectors == nullptr) {
+        LOGE("%s() called before setup()", __func__);
+        return -1.0;
+    } else if (index < 0 || index >= mNumChannels) {
+        LOGE("%s(), index out of range, 0 <= %d < %d", __func__, index, mNumChannels.load());
+        return -2.0;
+    }
+    return mPeakDetectors[index].getLevel();
+}
+
+oboe::DataCallbackResult FullDuplexEcho::onBothStreamsReadyFloat(
+        const float *inputData,
         int   numInputFrames,
-        void *outputData,
+        float *outputData,
         int   numOutputFrames) {
-    // FIXME only handles matching stream formats.
-    // TODO Add delay node
-    // TODO use flowgraph to handle format conversion
     int32_t framesToEcho = std::min(numInputFrames, numOutputFrames);
-    float *inputFloat = (float *)inputData;
+    auto *inputFloat = const_cast<float *>(inputData);
-    float *outputFloat = (float *)outputData;
+    float *outputFloat = outputData;
     // zero out entire output array
-    memset(outputFloat, 0, numOutputFrames * getOutputStream()->getBytesPerFrame());
+    memset(outputFloat, 0, static_cast<size_t>(numOutputFrames)
+            * static_cast<size_t>(getOutputStream()->getBytesPerFrame()));
 
     int32_t inputStride = getInputStream()->getChannelCount();
     int32_t outputStride = getOutputStream()->getChannelCount();
     float delayFrames = mDelayTimeSeconds * getOutputStream()->getSampleRate();
     while (framesToEcho-- > 0) {
         *outputFloat = mDelayLine->process(delayFrames, *inputFloat); // mono delay
+
+        for (int iChannel = 0; iChannel < inputStride; iChannel++) {
+            float sample = * (inputFloat + iChannel);
+            mPeakDetectors[iChannel].process(sample);
+        }
+
         inputFloat += inputStride;
         outputFloat += outputStride;
     }

mobile/android/love/src/jni/oboe/apps/OboeTester/app/src/main/cpp/FullDuplexEcho.h

@@ -21,28 +21,31 @@
 #include <sys/types.h>
 
 #include "oboe/Oboe.h"
-#include "FullDuplexStream.h"
+#include "analyzer/LatencyAnalyzer.h"
+#include "FullDuplexStreamWithConversion.h"
 #include "InterpolatingDelayLine.h"
 
-class FullDuplexEcho : public FullDuplexStream {
+class FullDuplexEcho : public FullDuplexStreamWithConversion {
 public:
     FullDuplexEcho() {
-        setMNumInputBurstsCushion(0);
+        setNumInputBurstsCushion(0);
     }
 
     /**
      * Called when data is available on both streams.
      * Caller should override this method.
      */
-    oboe::DataCallbackResult onBothStreamsReady(
+    oboe::DataCallbackResult onBothStreamsReadyFloat(
-            const void *inputData,
+            const float *inputData,
             int   numInputFrames,
-            void *outputData,
+            float *outputData,
             int   numOutputFrames
     ) override;
 
     oboe::Result start() override;
 
+    double getPeakLevel(int index);
+
     void setDelayTime(double delayTimeSeconds) {
         mDelayTimeSeconds = delayTimeSeconds;
     }
@@ -51,6 +54,9 @@ private:
     std::unique_ptr<InterpolatingDelayLine> mDelayLine;
     static constexpr double kMaxDelayTimeSeconds = 4.0;
     double mDelayTimeSeconds = kMaxDelayTimeSeconds;
+    std::atomic<int32_t> mNumChannels{0};
+    std::unique_ptr<PeakDetector[]> mPeakDetectors;
+
 };