Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

Docs and agents: engine work happens in engine/

v0lumehi844211e79b59
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 00000000..3d61d567
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,16 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "matcher": "startup|resume|clear",
+ "hooks": [
+ {
+ "type": "command",
+ "command": "python3 \"$CLAUDE_PROJECT_DIR/tools/engine.py\" hook",
+ "timeout": 300
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
index 6a4c2da1..c3ed2128 100644
--- a/.github/pull_request_template.md
+++ b/.github/pull_request_template.md
@@ -13,7 +13,7 @@
## Checked
<!-- Delete what does not apply. Say what was not checked too. -->
-- Tests: <!-- `cd frontend && swift test`, frontend-qt tests if you changed it, `python3 scripts/patches.py check` when `patches/` or a vendored path changed -->
+- Tests: <!-- `cd frontend && swift test`, frontend-qt tests if you changed it, `python3 tools/engine.py check --tree` when `patches/` or a vendored path changed -->
- Visual QA: <!-- `NX_LAUNCHER_CAPTURE_DIR=<dir> swift test` captures the views, for a UI change -->
- Run on a device or Mac: <!-- what was built, played or installed, with title ID and version, chip and OS -->
@@ -25,7 +25,7 @@
## Scope
-- [ ] No vendored file (`dm/`, `scripts/`, `docs/`, `ref/`, `AGENTS.md`) is edited directly: a change there is a patch in `patches/` (`scripts/patches.py export`, and `patches.py check` passes), with its `Upstream-Status`
+- [ ] No vendored file (`dm/`, `scripts/`, `docs/`, `ref/`, `AGENTS.md`) is edited directly: a change there is a patch in `patches/` (a commit in `engine/`, then `tools/engine.py export`, and `tools/engine.py check --tree` 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 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 attachments
diff --git a/CLAUDE.md b/CLAUDE.md
index e78a526b..badcf0e7 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,7 +1,7 @@
# Notes for Claude
-- Read [AGENTS.md](AGENTS.md) first.
+- Read [engine/AGENTS.md](engine/AGENTS.md) first: the engine'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). Until the committed copy goes (step 2 of #214), [AGENTS.md](AGENTS.md) at the root is the same file.
- 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`.
-- `dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue in `patches/`: a change there is a patch (`scripts/patches.py export`, see [patches/README.md](patches/README.md)), not a direct edit, and `scripts/patches.py check` fails otherwise.
-- **Commit with your own git identity.** Use the one configured for your clone, or your own name and email. AGENTS.md ends with `git -c user.name=seedds -c user.email=…`: that is seedds' own identity, written for his repository. Do not copy it unless you are seedds: it attributes your commits, and the `From:` line of patches made with `scripts/patches.py export`, to him (six commits on 2026-10-30 did, including `v0.7.2`, and patch 0033 in #230).
+- The engine is seedds/nxnative at `.upstream-ref` plus the patch queue in `patches/`. Work on it 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)). `dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` at the root are the same tree, still committed until step 2 of #214: never edit them directly, `tools/engine.py check --tree` fails otherwise.
+- **Commit with your own git identity, never upstream's.** Use the one configured for your clone, or your own name and email. 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.md
index 6fb399a5..d8d2a946 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -39,7 +39,8 @@ 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)).
-- **`dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue.** They are generated: seedds/nxnative at the commit in `.upstream-ref` with the patches in `patches/` applied, so a direct edit fails `scripts/patches.py check` (the `pr-scope` and `patch-queue` jobs) and would be lost on the next bump. The failure names the command: `python3 scripts/patches.py absorb <files>` folds a direct edit into the patch that already touches the file (a new file may need `--into <patch>`). Commit `patches/` with it. For a change that needs a patch of its own, commit the change, turn it into a patch with `scripts/patches.py export <commit>`, fill in its header (`Upstream-Status`, `Reason`, `Issue`), and send the same change to seedds/nxnative so the patch can go. Fixes to the engine and to game profiles go to seedds/nxnative first, as [patches/README.md](patches/README.md#upstream-first) states. That page walks through the steps and states the patch policy (what a patch may and may not change). Files under `.github/` and in the repository root that are not in that list (this file, `CLAUDE.md`, the README) are the fork's.
+- **The engine is upstream plus the patch queue, built into `engine/`** (#214): `python3 tools/engine.py sync` makes it, engine work is a commit in `engine/`, and `python3 tools/engine.py export` turns it into a patch with its header. Until step 2 of #214 the repository still commits the same tree:
+- **`dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are upstream plus the patch queue.** They are generated: seedds/nxnative at the commit in `.upstream-ref` with the patches in `patches/` applied, so a direct edit fails `tools/patches.py check` (the `pr-scope` and `patch-queue` jobs) and would be lost on the next bump. The failure names the command: `python3 tools/patches.py absorb <files>` folds a direct edit into the patch that already touches the file (a new file may need `--into <patch>`). Commit `patches/` with it. For a change that needs a patch of its own, commit the change, turn it into a patch with `tools/patches.py export <commit>`, fill in its header (`Upstream-Status`, `Reason`, `Issue`), and send the same change to seedds/nxnative so the patch can go. Fixes to the engine and to game profiles go to seedds/nxnative first, as [patches/README.md](patches/README.md#upstream-first) states. That page walks through the steps and states the patch policy (what a patch may and may not change). Files under `.github/` and in the repository root that are not in that list (this file, `CLAUDE.md`, the README) are the fork's.
## For AI agents and other tools
diff --git a/README.md b/README.md
index 2d9b7687..1d314c9d 100644
--- a/README.md
+++ b/README.md
@@ -149,7 +149,7 @@ display version must match the profile's, or the build says so.
- **What this fork changes in upstream:** the engine (`dm/`, `scripts/`, `docs/`, `ref/`,
`AGENTS.md`) is nxnative at a pinned commit plus a queue of patches, each saying why the fork
carries it. [patches/README.md](patches/README.md) explains it, and
- `python3 scripts/patches.py status` lists what is carried. A daily job moves the pin and opens a
+ `python3 tools/engine.py status` lists what is carried. A daily job moves the pin and opens a
pull request, or an issue naming the patch that no longer fits.
- **Another Switch game:** [docs/agents](docs/agents/README.md) (extraction, binary survey, bring-up).
- **Release history:** [CHANGELOG.md](CHANGELOG.md).
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 1fdc86bd..f423482b 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -131,7 +131,7 @@ iPhone 上在「文件」App 里该 App 名字下:`save/` 和 `log.txt`(上
- **从源码构建:** [BUILDING.zh-CN.md](BUILDING.zh-CN.md)。**报告或修复问题:** [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。
- **本 fork 对上游改了什么:** 引擎(`dm/`、`scripts/`、`docs/`、`ref/`、`AGENTS.md`)就是 nxnative 在固定提交上的
内容,加一组补丁,每个补丁写明本 fork 为什么带着它。见 [patches/README.md](patches/README.md);
- `python3 scripts/patches.py status` 列出带着的全部补丁。每天一次的任务移动固定提交并开 pull request,
+ `python3 tools/engine.py status` 列出带着的全部补丁。每天一次的任务移动固定提交并开 pull request,
某个补丁对不上时开一个点名该补丁的 issue。
- **其他 Switch 游戏:** [docs/agents](docs/agents/README.md)(解包、二进制调查、bring-up)。
- **版本历史:** [CHANGELOG.zh-CN.md](CHANGELOG.zh-CN.md)。
diff --git a/patches/README.md b/patches/README.md
index 626f4501..5e19013e 100644
--- a/patches/README.md
+++ b/patches/README.md
@@ -1,5 +1,23 @@
# The patch queue
+> **engine/ (issue #214, step 1).** The engine is now also built into `engine/`, a real git repository that git ignores:
+> `python3 tools/engine.py sync` fetches seedds/nxnative at the pin (one commit deep) and applies `series` there with `git am`, one
+> commit per patch. Engine work is a commit in `engine/`, and `python3 tools/engine.py export` turns it into a patch with the header
+> below. The launchers, CI and the release app use `engine/`. The committed copy in `dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md`
+> stays until one release has shipped with both layouts (step 2), and `tools/engine.py check --tree` keeps it equal to pin + series.
+> The patch tool moved from `tools/patches.py` to `tools/patches.py` (the old path forwards).
+>
+> ```sh
+> python3 tools/engine.py sync # engine/ = pin + series (a no-op when nothing changed)
+> python3 tools/engine.py status # what we carry, and the state of engine/
+> python3 tools/engine.py export # commits made in engine/ since the last sync become patches
+> python3 tools/engine.py check --tree # the series applies cleanly to the pin, and the committed tree matches
+> python3 tools/engine.py bump --dry --to main # which patches a bump would drop or conflict on
+> ```
+>
+> `sync` never throws away work in `engine/`: with commits or changes there it stops and names `export` (or `--force`, which keeps
+> them on a backup branch). Offline, it says so. A release app carries the pinned commit (`Resources/engine.git`) as a seed.
+
`dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are not edited by hand. They are
[seedds/nxnative](https://github.com/seedds/nxnative) at the commit in `../.upstream-ref`, plus the patches in this folder
applied in the order of `series` with `git am -3`. The same model carries Chromium's changes in Electron and the upstream
@@ -20,7 +38,7 @@ Issue: LNPANDY/NX2Apple#<n>
| `fork-only` | stays here: a fork product choice, or upstream declined it (`fork-only (declined seedds/nxnative#N)`) |
| `backport <sha>` | upstream has it (that commit), and the patch goes on the next bump |
-A status may carry a note in brackets. `scripts/patches.py status` lists every patch with its status, reason and age, so the
+A status may carry a note in brackets. `tools/patches.py status` lists every patch with its status, reason and age, so the
list of what the fork carries and why is one command, and it should keep shrinking.
## Upstream first
@@ -33,13 +51,13 @@ its status is `forwarded seedds/nxnative#<n>`, and the next bump drops it once t
## Day to day
```sh
-python3 scripts/patches.py status # what we carry, and why
-python3 scripts/patches.py check # series on the pin == the vendored tree of this checkout
-python3 scripts/patches.py apply # rebuild the vendored tree from the pin and the series
-python3 scripts/patches.py bump --to <sha> # move the pin (the nightly job does this)
-python3 scripts/patches.py bump --dry --to <sha> # which patches would conflict, changing nothing
-python3 scripts/patches.py export <commit> # a local commit becomes a patch
-python3 scripts/patches.py absorb [paths] # direct edits of vendored files fold into the patches that touch them
+python3 tools/patches.py status # what we carry, and why
+python3 tools/patches.py check # series on the pin == the vendored tree of this checkout
+python3 tools/patches.py apply # rebuild the vendored tree from the pin and the series
+python3 tools/patches.py bump --to <sha> # move the pin (the nightly job does this)
+python3 tools/patches.py bump --dry --to <sha> # which patches would conflict, changing nothing
+python3 tools/patches.py export <commit> # a local commit becomes a patch
+python3 tools/patches.py absorb [paths] # direct edits of vendored files fold into the patches that touch them
```
`apply` and `bump` need the upstream commit in the local repository (`git fetch seedds`, the remote
@@ -49,7 +67,7 @@ python3 scripts/patches.py absorb [paths] # direct edits of vendored files f
## You edited a vendored file directly (check fails)
`check` names every file that differs from pin + patches and the command to run, e.g. `docs/x.md differs from pin+patches: run
-`python3 scripts/patches.py absorb docs/x.md` and commit patches/`. `absorb [paths...]` takes the difference between the
+`python3 tools/patches.py absorb docs/x.md` and commit patches/`. `absorb [paths...]` takes the difference between the
vendored files of your checkout (working tree or already committed) and pin + series, and folds each file into the patch that
already touches it (the last one, when several do), keeping that patch's header. Then it runs `check`. Commit `patches/`.
@@ -62,11 +80,11 @@ already touches it (the last one, when several do), keeping that patch's header.
## Carrying a quick fix, and sending it upstream
1. Branch off `main`. Make the fix as an ordinary commit in the vendored files, with a message that says what and why.
-2. `python3 scripts/patches.py export HEAD` writes `patches/NNNN-<subject>.patch`, adds it to `series`, and puts the header
+2. `python3 tools/patches.py export HEAD` writes `patches/NNNN-<subject>.patch`, adds it to `series`, and puts the header
template into the message (`Upstream-Status: pending`, `Reason: TODO`, `Issue: TODO`, which `--status`, `--reason` and `--issue` set). Fill the three lines in. A range
(`export main..HEAD`) makes one patch per commit. Rename the file if you want a shorter name, because the name is what
`fork_patches.txt` and `status` show.
-3. `python3 scripts/patches.py check` must pass: the series applied to the pin gives exactly the tree you committed. Commit the
+3. `python3 tools/patches.py check` must pass: the series applied to the pin gives exactly the tree you committed. Commit the
patch file with the change in the same pull request. The files you edited are already in your commit, so they are part of the PR.
4. Send the same change to seedds/nxnative as a pull request from a branch off *their* main (`git fetch seedds`,
`git switch -c fix-x seedds/main`, `git cherry-pick <commit>`), and set the patch to `forwarded seedds/nxnative#<N>`.
@@ -82,7 +100,7 @@ leaves the conflict in a worktree.
1. In that worktree, resolve the conflict, `git add`, `git am --continue`. If upstream has taken the patch's change in another
form, `git am --skip` instead.
2. Apply the patches after it: `git am -3 <the remaining patch files>`.
-3. `python3 scripts/patches.py refresh <worktree> --to <sha>` writes the commits back as the series (patches with no commit are
+3. `python3 tools/patches.py refresh <worktree> --to <sha>` writes the commits back as the series (patches with no commit are
deleted), moves `.upstream-ref` and regenerates the vendored tree.
4. Run the checks (`check`, the tests, the host build), commit, open the pull request.
@@ -112,7 +130,7 @@ Upstream's compatibility is the baseline. A patch does not change it silently.
## What is not a patch
`.github/`, `frontend/`, `frontend-qt/`, the README, CONTRIBUTING.md, CLAUDE.md and everything else outside the five vendored paths
-belong to the fork and are edited directly. Inside the vendored paths, the tool's own files (`scripts/patches.py`,
+belong to the fork and are edited directly. Inside the vendored paths, the tool's own files (`tools/patches.py`,
`scripts/tests/test_patches.py`) and the generated `dm/fork_patches.txt` are not part of the generated tree.
## Generated files inside the vendored paths