Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.
Swift apple-siliconcustom-formathomebrewiosipaipadipadosiphonemetalnative-portnintendo-switchnxnativeromfsswitch-games
docs: an engine fix lands here as a patch and goes upstream in parallel
v0lumehic02c4f6ac7a0
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex 5e9e0155..8190995d 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -26,6 +26,6 @@## Scope- [ ] No engine file (`dm/`, `scripts/`, `docs/`, `ref/`) is added to the repository: a change there is a patch in `patches/` (a commit in `engine/`, then `tools/engine.py export`, and `tools/engine.py check` passes), with its `Upstream-Status`-- [ ] A fix to the engine or a game profile is also (or first) a PR at seedds/nxnative: this PR's patch says `forwarded seedds/nxnative#...`+- [ ] A fix to the engine or a game profile also goes to seedds/nxnative as a PR in parallel: this PR's patch says `forwarded seedds/nxnative#...`, or `pending` until that PR is open- [ ] A change to a launcher view has before and after screenshots above- [ ] No keys, game files or data extracted from a game in the change or the attachmentsdiff --git a/.github/workflows/pr-scope.yml b/.github/workflows/pr-scope.ymlindex d22e044f..1ccb71b4 100644--- a/.github/workflows/pr-scope.yml+++ b/.github/workflows/pr-scope.yml@@ -2,9 +2,9 @@## The engine is seedds/nxnative at the commit in .upstream-ref plus the patches in patches/. It is built into engine/ by# `tools/engine.py sync` and not committed (issue #214, step 2): dm/, scripts/, docs/ and ref/ do not exist in this repository, so a PR-# that adds files there (a direct edit of the engine, made from an old checkout or by hand) fails with the way out. Engine work is a pull-# request to seedds/nxnative first, and a commit in engine/ that `tools/engine.py export` turns into a patch when the fork has to carry it-# before upstream merges. The other half: the series applies cleanly to the pin and every header is complete.+# that adds files there (a direct edit of the engine, made from an old checkout or by hand) fails with the way out. Engine work is a+# commit in engine/ that `tools/engine.py export` turns into a patch, and the same change goes to seedds/nxnative as a pull request in parallel.+# The other half: the series applies cleanly to the pin and every header is complete.# A sync PR (branch sync/upstream-*) is checked too, on purpose: it must still apply.# The same check is a job in tests.yml; this one starts on the engine's paths and the patch queue only, and says so in its own name.name: PR scope (sync safety)@@ -28,7 +28,7 @@ jobs:files=$(git ls-files -- dm scripts docs ref)if [ -n "$files" ]; thenecho "$files" | head -20- echo "::error title=Engine files::This PR adds files under dm/, scripts/, docs/ or ref/, which this repository does not commit any more (the engine is seedds/nxnative at .upstream-ref plus patches/, built into engine/ by python3 tools/engine.py sync). Send the change to seedds/nxnative as a pull request first. If the fork has to carry it before upstream merges, make it a patch: commit in engine/, then python3 tools/engine.py export (patches/README.md). Do not copy engine files into the repository."+ echo "::error title=Engine files::This PR adds files under dm/, scripts/, docs/ or ref/, which this repository does not commit any more (the engine is seedds/nxnative at .upstream-ref plus patches/, built into engine/ by python3 tools/engine.py sync). Make the change a patch: commit in engine/, then python3 tools/engine.py export (patches/README.md). Send the same change to seedds/nxnative as a pull request in parallel. Do not copy engine files into the repository."exit 1fi- name: The series applies to the pindiff --git a/AGENTS.md b/AGENTS.mdindex b6cb6a50..eb1d4682 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -4,8 +4,8 @@ This is the fork's guide. The engine has its own, upstream's: [engine/AGENTS.md]- **Layout.** NX2Apple is the launcher and the glue around [seedds/nxnative](https://github.com/seedds/nxnative), which runs Nintendo Switch games natively on Apple platforms. This repository commits: `frontend/` (the Mac launcher, SwiftUI), `frontend-qt/` (the Qt front end), `frontend-ios/` (the iPhone shell), `tools/` (`engine.py`, `patches.py`, `release_manifest.py` and their tests), `patches/` (the series), `.upstream-ref` (the nxnative commit we build on), `.github/` (CI, forms, triage), the player and developer pages (`README*.md`, `GAMES*.md`, `BUILDING*.md`, `CONTRIBUTING*.md`, `CHANGELOG*.md`). The engine (`dm/`, `scripts/`, `docs/`, `ref/`) is **not** here: it is nxnative at the pin plus `patches/`, built into `engine/` by `python3 tools/engine.py sync`. `engine/` is a real git repository that this one ignores. A root `.ignore` keeps it visible to ripgrep.- **Commit with your own git identity, never upstream's.** Use the identity configured for your clone, or your own name and email. `engine/AGENTS.md` ends with a `git -c user.name=seedds -c user.email=…` line because it is written for seedds/nxnative, where seedds is the maintainer. Do not copy it here: it makes fork commits, and the `From:` line of patches made with `tools/engine.py export`, show upstream's author. Commit only when asked.-- **Upstream first.** A fix to the engine, to a game profile or to upstream's docs is a pull request to seedds/nxnative, from a branch off their main (`git -C engine fetch seedds`, `engine/` has the remote). A patch here is only a bridge until upstream has it, and the next bump drops it once the change is in. [patches/README.md](patches/README.md#upstream-first) has the rule and the `Upstream-Status` values.-- **How a commit in `engine/` becomes a patch.** Work in `engine/` (it holds upstream's tree with our patches as commits on top): change, test, commit with a message that says what and why. `python3 tools/engine.py export` turns the commits made since the last sync into `patches/NNNN-*.patch` with the header `Upstream-Status`, `Reason` and `Issue` (fill them in, `--status`, `--reason` and `--issue` set them) and adds them to `patches/series`. `python3 tools/engine.py check` must pass (headers, no patch on the shader chain, the series applies to the pin). The same commit goes to seedds/nxnative as a pull request, and the patch says `forwarded seedds/nxnative#<n>`. Commit `patches/` in a PR here. `sync` never throws away work in `engine/`: it stops and names `export`.+- **Here first, upstream in parallel.** A fix to the engine, to a game profile or to upstream's docs may land here first, as a patch. The same change goes to seedds/nxnative as a pull request in parallel, from a branch off their main (`git -C engine fetch seedds`, `engine/` has the remote). If you cannot open that pull request, a maintainer sends it. A patch here is a bridge until upstream has it, and the next bump drops it once the change is in. [patches/README.md](patches/README.md#here-first-upstream-in-parallel) has the rule and the `Upstream-Status` values.+- **How a commit in `engine/` becomes a patch.** Work in `engine/` (it holds upstream's tree with our patches as commits on top): change, test, commit with a message that says what and why. `python3 tools/engine.py export` turns the commits made since the last sync into `patches/NNNN-*.patch` with the header `Upstream-Status`, `Reason` and `Issue` (fill them in, `--status`, `--reason` and `--issue` set them) and adds them to `patches/series`. `python3 tools/engine.py check` must pass (headers, no patch on the shader chain, the series applies to the pin). The same commit goes to seedds/nxnative as a pull request in parallel. The patch says `pending` until that pull request is open, then `forwarded seedds/nxnative#<n>`. Commit `patches/` in a PR here. `sync` never throws away work in `engine/`: it stops and names `export`.- **Never add engine files to this repository.** Files under `dm/`, `scripts/`, `docs/` and `ref/` at the root are ignored by `.gitignore`, and the `pr-scope` check fails a PR that adds them. A direct edit of engine files is lost on the next sync.- **Issues and pull requests.** Follow [CONTRIBUTING.md](CONTRIBUTING.md), section "For AI agents and other tools", and the forms and the PR template in `.github/`. Fix or feature: a fix merges once CI is green, a feature after 48 hours, releases and version bumps are the owner's. No AI attribution in commits, PRs or issues. Never attach or commit keys, game files or data extracted from a game.- **Checks.** `cd frontend && swift build && swift test` for the Mac launcher (its tests read `engine/`, so sync first), `python3 -m unittest discover -s frontend-qt/tests` for the Qt front end (and `python3 frontend-qt/gen_localization.py` leaves `frontend-qt/nspb_qt/localization.py` unchanged), `python3 -m unittest discover tools/tests` for the tools. The engine's own tests run in `engine/` as `tests.yml` does.diff --git a/CLAUDE.md b/CLAUDE.mdindex ed07e6f1..90316bd4 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -3,5 +3,5 @@- Read [AGENTS.md](AGENTS.md) first: this repository's layout and rules. For engine work read [engine/AGENTS.md](engine/AGENTS.md) too, upstream's guide from seedds/nxnative at the pin. `engine/` is made by `python3 tools/engine.py sync` (the SessionStart hook in `.claude/settings.json` runs it).- For an issue or a pull request, follow [CONTRIBUTING.md](CONTRIBUTING.md), section "For AI agents and other tools", and the templates in `.github/`.- A PR that changes the launcher needs before and after screenshots: see "For AI agents and other tools" in CONTRIBUTING.md for how to capture them and attach them with `gh pr create --attach`.-- The engine (`dm/`, `scripts/`, `docs/`, `ref/` and upstream's `AGENTS.md`) is not committed here: it is seedds/nxnative at `.upstream-ref` plus the patch queue in `patches/`, built into `engine/` (git-ignored). The `AGENTS.md` at the root is this fork's own. Upstream first: a fix goes to seedds/nxnative as a pull request, and becomes a patch only while the fork has to carry it. Work in `engine/`: commit there, then `python3 tools/engine.py export` turns the commits into patches with their header (see [patches/README.md](patches/README.md)). Never add files under `dm/`, `scripts/`, `docs/` or `ref/` at the root: `pr-scope` fails it and `.gitignore` ignores them.+- The engine (`dm/`, `scripts/`, `docs/`, `ref/` and upstream's `AGENTS.md`) is not committed here: it is seedds/nxnative at `.upstream-ref` plus the patch queue in `patches/`, built into `engine/` (git-ignored). The `AGENTS.md` at the root is this fork's own. A fix lands here as a patch and goes to seedds/nxnative as a pull request in parallel. Work in `engine/`: commit there, then `python3 tools/engine.py export` turns the commits into patches with their header (see [patches/README.md](patches/README.md)). Never add files under `dm/`, `scripts/`, `docs/` or `ref/` at the root: `pr-scope` fails it and `.gitignore` ignores them.- **Commit with your own git identity, never upstream's.** Use the one configured for your clone, or your own name and email. `engine/AGENTS.md` ends with `git -c user.name=seedds -c user.email=…` because it is written for seedds/nxnative, where seedds is the maintainer. Do not copy that line here: it makes fork commits, and the `From:` line of patches made with `tools/engine.py export`, show upstream's author (six commits on 2026-10-30 did, including `v0.7.2`, and patch 0033 in #230).diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 910ef005..9b83bc89 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -39,7 +39,7 @@ missing piece.- Fill in the PR template: what and why, what was checked, screenshots for UI changes.- A PR that changes anything visible in the launcher attaches before and after screenshots to the PR, under Screenshots. Show every view the PR changes, in each language it touches. A PR without them is not reviewed. A PR with no visible change writes "None, no visible change".- **`frontend/` and `frontend-qt/` are the fork's own:** change them freely. Run `cd frontend && swift test`. For a UI change also capture the views for visual QA (`NX_LAUNCHER_CAPTURE_DIR`, see [frontend/README.md](frontend/README.md#verification)).-- **The engine is not in this repository.** `dm/`, `scripts/`, `docs/` and `ref/` are seedds/nxnative at the commit in `.upstream-ref` with the patches in `patches/` applied, built into `engine/` by `python3 tools/engine.py sync` (a git repository that git ignores here, #214). A PR that adds files under those paths fails the `pr-scope` check, because the next sync would not carry them. Fixes to the engine and to game profiles go to seedds/nxnative first, as a pull request there, as [patches/README.md](patches/README.md#upstream-first) states. Only while the fork has to carry a change before upstream merges it, it is a patch: commit the change in `engine/`, run `python3 tools/engine.py export`, fill in the header of the new patch (`Upstream-Status`, `Reason`, `Issue`), run `python3 tools/engine.py check`, and commit `patches/` with it. That page walks through the steps and states the patch policy (what a patch may and may not change). Everything else in the repository root and under `.github/` (this file, `CLAUDE.md`, `AGENTS.md`, the README) is the fork's.+- **The engine is not in this repository.** `dm/`, `scripts/`, `docs/` and `ref/` are seedds/nxnative at the commit in `.upstream-ref` with the patches in `patches/` applied, built into `engine/` by `python3 tools/engine.py sync` (a git repository that git ignores here, #214). A PR that adds files under those paths fails the `pr-scope` check, because the next sync would not carry them. A fix to the engine or to a game profile lands here first, as a patch, and goes to seedds/nxnative as a pull request in parallel, as [patches/README.md](patches/README.md#here-first-upstream-in-parallel) states. If you cannot open the upstream pull request, a maintainer sends it. To make the patch, commit the change in `engine/`, run `python3 tools/engine.py export`, fill in the header of the new patch (`Upstream-Status`, `Reason`, `Issue`), run `python3 tools/engine.py check`, and commit `patches/` with it. That page walks through the steps and states the patch policy (what a patch may and may not change). Everything else in the repository root and under `.github/` (this file, `CLAUDE.md`, `AGENTS.md`, the README) is the fork's.## For AI agents and other toolsdiff --git a/patches/README.md b/patches/README.mdindex fc6bcf0a..1093309b 100644--- a/patches/README.md+++ b/patches/README.md@@ -38,12 +38,15 @@ Issue: LNPANDY/NX2Apple#<n>A status may carry a note in brackets. `tools/patches.py status` lists every patch with its status, reason and age, so thelist of what the fork carries and why is one command, and it should keep shrinking.-## Upstream first+## Here first, upstream in parallel-A fix to the engine (`dm/`, `scripts/`, `ref/`), to a game profile (`dm/games/<id>/`) or to upstream's docs is a pull request to-[seedds/nxnative](https://github.com/seedds/nxnative) first, or at least also. A patch here is only a bridge until upstream has it:-its status is `forwarded seedds/nxnative#<n>`, and the next bump drops it once the change is in. Do not open a fork patch with-`pending` for something that belongs upstream. A feature upstream does not want is `fork-only`, with the reason in `Reason:`.+A fix to the engine (`dm/`, `scripts/`, `ref/`), to a game profile (`dm/games/<id>/`) or to upstream's docs may land here first, as a+patch in `patches/`. The same change goes to [seedds/nxnative](https://github.com/seedds/nxnative) as a pull request in parallel.+Nobody has to wait for upstream. A patch here is a bridge until upstream has it, and the next bump drops it once the change is in.++The patch starts as `pending` while the upstream pull request is not open. It becomes `forwarded seedds/nxnative#<n>` once it is.+If you cannot open the upstream pull request, a maintainer sends it. A feature upstream declines stays here as+`fork-only (declined seedds/nxnative#N)`, with the reason in `Reason:`.## Day to day