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
Outside contributors: talk about features first, send game profiles to seedds/nxnative first
v0lumehiba8cd69dcbe4
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlindex 43e61f6f..a0b2d729 100644--- a/.github/ISSUE_TEMPLATE/config.yml+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -5,7 +5,7 @@ contact_links:about: Ask how something works in Q&A, or suggest and talk over an idea in Ideas. Bugs stay as issues, with the forms here.- name: The engine and game compatibility (seedds/nxnative)url: https://github.com/seedds/nxnative/issues- about: NX2Apple packs and starts games with the nxnative engine. Go there for how the engine itself works, for porting a new game or for a rendering fault you have traced into it. For a game that fails on your Mac or iPhone, use the Game problem form here first.+ about: NX2Apple packs and starts games with the nxnative engine. Go there for how the engine itself works, for porting a new game (send its profile there as a pull request first) or for a rendering fault you have traced into it. For a game that fails on your Mac or iPhone, use the Game problem form here first.- name: Install and build instructions (README)url: https://github.com/LNPANDY/NX2Apple#readmeabout: How to install the app, what you need on disk, how to build and install a game, and the games that are known to work.diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.mdindex 72c382f9..2d9a53ee 100644--- a/.github/copilot-instructions.md+++ b/.github/copilot-instructions.md@@ -5,6 +5,7 @@ Read [AGENTS.md](../AGENTS.md) (the fork's, at the root) and [CONTRIBUTING.md](.- First, in your checkout, run `git config core.hooksPath .githooks`. The hooks run the checks before a commit and a push. Keep them installed, never use `--no-verify`, and never push to `main`: every change goes through a PR. The pre-push hook rejects a push to `main` for every tool, and the "Main rule" ruleset on GitHub rejects it for everyone, with no bypass.- `frontend/` and `frontend-qt/` are this fork's own: change them directly. `cd frontend && swift test` is the check.- The engine (`dm/`, `scripts/`, `docs/`, `ref/`) is not in this repository: it is seedds/nxnative at `.upstream-ref` plus `patches/`, built into `engine/` by `python3 tools/engine.py sync`. Do not add files under those paths in a PR (the `pr-scope` check fails it). A change to the engine is a pull request to seedds/nxnative first, and a patch in `patches/` (a commit in `engine/`, then `python3 tools/engine.py export`) only while the fork has to carry it.+- A feature or a proposal from outside needs an issue or a discussion with a maintainer's go (the label `help wanted`) before you build it. Check that it exists or ask the user. A new game profile goes to seedds/nxnative first (CONTRIBUTING.md, "Fixes, features and ideas" and "Helping with games").- Never touch the shader translation chain (`dm/gfx/tools/dmsh_*`, `dm/gfx/nvn/dmsh_chain.h`, `dmsh_chain.lock`, the translator).- A fix merges when CI is green, unless a maintainer's "changes requested" review is unanswered. A plain review comment does not block. The maintainer who requested the changes reviews again after your push. The owner decides only when the maintainers disagree. A feature PR from a maintainer waits 48 hours before it merges. A feature from outside never merges by waiting: a maintainer has to agree to the idea, try the app and review the code. A fix from outside gets the same maintainer check before it merges. Whoever merges a patch renumbers it from `patches/series` on `main`, so do not rebase to chase free numbers. Releases (version bumps, tags, update-history rows) are the owner's.- Never attach or commit keys, game files or anything extracted from a game.diff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdindex dfbfd1a2..ae4f6cca 100644--- a/.github/pull_request_template.md+++ b/.github/pull_request_template.md@@ -6,6 +6,8 @@- [ ] Fix- [ ] Feature+Feature from outside: the issue with the go is linked.+## What and why<!-- The symptom or the need, the cause, and the change. Link the issue (Fixes #...). -->diff --git a/AGENTS.md b/AGENTS.mdindex e4b86bb7..3a3ea790 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -5,7 +5,8 @@ This is the fork's guide. The engine has its own, upstream's: [engine/AGENTS.md]- **Install the git hooks first.** In every clone and worktree, before any other work, run `git config core.hooksPath .githooks`. `python3 tools/engine.py sync`, `check` and `export` and the Claude Code session start do it when it is unset. Keep the hooks installed. Never use `--no-verify` on `git commit` or `git push`. Never push to `main` directly, every change goes through a PR, patches included. The pre-push hook rejects a push to `main` for every tool, and the "Main rule" ruleset on GitHub rejects it for everyone, with no bypass.- **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, `try-pr`, `try-local`), `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`, `RELEASING.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.-- **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.+- **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. Outside contributors start upstream: a new game profile goes to seedds/nxnative first ([CONTRIBUTING.md](CONTRIBUTING.md#helping-with-games)). 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.+- **Work for an outside contributor.** Before you build a feature or a proposal, check that an issue or a discussion with a maintainer's go exists (the label `help wanted`), or ask the user ([CONTRIBUTING.md](CONTRIBUTING.md#fixes-features-and-ideas)). A new game profile goes to seedds/nxnative first. The maintainers' own work is not bound by this.- **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: every fix goes through a PR and merges when CI is green, unless a maintainer's "changes requested" review is unanswered (a plain review comment does not block, and @LNPANDY decides only when the maintainers disagree), a maintainer's own feature after 48 hours (a feature from outside never merges by waiting, a maintainer has to agree, try the app and review the code), a patch is renumbered by whoever merges it, releases and version bumps are the owner's ([RELEASING.md](RELEASING.md): a release candidate tag first, the final tag on its commit). `tools/try-pr <PR number|main|tag>` opens the app CI built. `tools/try-local` builds the app from your checkout without CI and opens it (engine tree, launcher, bundled tools, ad-hoc signed, version `<appVersion>-local`). The first run builds the bundled tools, which it caches (minutes), a later one takes about the time of `swift build`. It is not a release and cannot sign: an rc tag still needs CI and the owner's key. Never attach or commit keys, game files or data extracted from a game.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 1bee29f9..414a4bda 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -10,7 +10,7 @@ Game problems, build problems and launcher problems each have an issue form (`.g- **Here:** the app, a build or install that fails, and a game that does not run well on your Mac or iPhone or iPad.- **[Discussions](https://github.com/LNPANDY/NX2Apple/discussions):** questions (Q&A) and ideas (Ideas). Bugs stay issues.-- **[seedds/nxnative](https://github.com/seedds/nxnative/issues):** how the engine works, porting a new game, a rendering fault you have traced into the engine itself.+- **[seedds/nxnative](https://github.com/seedds/nxnative/issues):** how the engine works, porting a new game (its profile goes there as a pull request, see "Helping with games"), a rendering fault you have traced into the engine itself.## What a report needs@@ -21,11 +21,20 @@ Pick a form: **Game problem**, **Build problem** or **Launcher problem or idea**## Helping with gamesEach new game needs its own bring-up: a profile (build IDs, memory layout, texture slots), a shader-reader if it packs them in a form we do not read, and patch points. **Two ways to help, both+reader if it packs them in a form we do not read, and patch points. A game profile is engine code+(`dm/games/<id>/`), and the engine lives in [seedds/nxnative](https://github.com/seedds/nxnative). **Ways to help, alluseful:**- **Report a game that works** — if you got a title outside the verified list running, open an issue- with the title ID, the update version, and what you did. It becomes a profile others can use.+ with the title ID, the update version, and what you did. It becomes an entry in [GAMES.md](GAMES.md)+ that others can use.+- **Send a new game profile, or a fix to the engine, to seedds/nxnative first.** Open the pull request+ there and follow their [CONTRIBUTING.md](https://github.com/seedds/nxnative/blob/main/CONTRIBUTING.md)+ (a new game takes its profile, its note and its row in the games table). If the game also matters for+ Apple devices here, link your pull request in a Game problem issue here, or in a comment on the issue+ that already exists. Please do not send it here as a patch. If upstream is slow and the game is+ verified here, a maintainer may carry it in `patches/` as a bridge (`Upstream-Status: forwarded`)+ and credit you. If you cannot open the upstream pull request, a maintainer sends it.- **Send the shaders that are missing** — if a game runs but stutters on first use of an effect, itsshader variants are missing from the map. The host can dump what it cannot find(`DM_NVN_SHDUMP=<dir>`). Attach those and we add them to `shader_map.tsv` for everyone.@@ -44,11 +53,17 @@ missing piece.### Fixes, features and ideas-A fix is welcome without asking first.+This section is for contributions from outside. The maintainers (v0lumehi and LNPANDY) keep their own rules, see "When a PR merges".-A feature can be opened as a pull request on its own. It needs an issue that describes the idea. Write it within 48 hours of the first reply from a maintainer. One maintainer has to agree to the idea before the PR merges. If the issue is never written, the PR is closed with a note that it can be reopened. A PR is not closed on arrival for a missing issue.+We want to help you build what fits and to spare you work that cannot go in. The launcher code is being reorganized, so many open PRs will need a rebase, and a change is easier to land when we agree on the design before the code is written. So new features and proposals are talked about first. Fixes stay welcome without asking. There are three sizes:-To talk about an idea before you write code, use [Discussions](https://github.com/LNPANDY/NX2Apple/discussions).+- **Small: open a PR directly, no asking.** A fix, a test, docs, a typo, a report that a game works.+- **Medium: talk first.** A feature, a change to how the launcher works or looks, a new setting, a new dependency, a new way to build or install. Open an issue with the form "Launcher problem or idea" (`This is: An idea`), or an idea in [Discussions](https://github.com/LNPANDY/NX2Apple/discussions) (Ideas). A maintainer says "go" by adding the label `help wanted` to the issue. Then build it, and link that issue in your PR. A feature PR without a linked issue that has the go is not reviewed. It is closed with a friendly note after 14 days, and you can reopen it once the go is there.+- **Large: talk first, with a short design note.** Architecture, or a change across the Mac launcher, the Windows launcher and the iOS shell. The same steps as Medium, and the issue also holds a short design note: what you want to change, why, and the alternatives you looked at. A draft PR as a sketch is fine, but it waits for the go like any other.++A new game profile or an engine fix goes to seedds/nxnative first, see "Helping with games".++PRs opened before this rule keep the old path: an issue within 48 hours of the first reply from a maintainer, and one maintainer agrees to the idea before the PR merges.### What happens to your PR@@ -76,7 +91,8 @@ Issue forms and the PR template apply in the browser only. `gh issue create`, th- **Problem reports.** Write the body as `###` headings with the same names as the form's fields (for example `### Game and title ID`, `### Copy diagnostics`, `### The game's log`) and fill every required field from [.github/ISSUE_TEMPLATE](.github/ISSUE_TEMPLATE). Ask the user for what you cannot read yourself: the Copy diagnostics output, the log, the versions. If a required field is missing, do not open the issue.- **Ideas and plans.** These have no form. Write plain sections that fit the content, for example `### Idea`, `### Plan` and `### Done when`. Leave out the problem fields (`This is`, `NX2Apple version`, `Computer and OS`, `Copy diagnostics`). Open it with the labels `idea` and `no-triage`.-- **Pull requests.** Use the sections of [.github/pull_request_template.md](.github/pull_request_template.md): `gh pr create --template .github/pull_request_template.md`, or the same headings in `--body`. Answer each section and remove the `<!-- -->` hints. Under Fix or feature, tick one box. A change to the engine follows the rule above.+- **Before you build.** If you work for an outside contributor, a feature or a proposal needs an issue or a discussion with a maintainer's go (see "Fixes, features and ideas"). Check that it exists or ask the user. A new game profile or an engine fix goes to seedds/nxnative first (see "Helping with games").+- **Pull requests.** Use the sections of [.github/pull_request_template.md](.github/pull_request_template.md): `gh pr create --template .github/pull_request_template.md`, or the same headings in `--body`. Answer each section and remove the `<!-- -->` hints. Under Fix or feature, tick one box. A feature from outside links the issue with the go. A change to the engine follows the rule above.- **Screenshots.** A PR that changes the launcher needs before and after images in its body (see "A pull request"). On a Mac, capture the changed views of `frontend/` with `NX_LAUNCHER_CAPTURE_DIR=<dir> swift test` and `NX_CAPTURE_LANG` for the language (`de`, `sv` or `zh`, English is the default). `frontend-qt/` has no capture, so take its screenshots by hand. Attach the images with `gh pr create --attach` or `gh pr edit --attach`, once per file. Write `` in the body and pass `--attach ./before.png`. `gh` uploads the file and rewrites the path to a `https://github.com/user-attachments/assets/...` URL. This needs `gh` 2.99.0 or newer, push access to the repository, and an OAuth or personal access token (a GitHub App token is rejected). Afterwards, read the body back and check that it holds the asset URLs and no local paths. If your `gh` or token cannot attach, say so under Screenshots, give the paths of the captures, and ask the user to attach them. An agent without a Mac (a Linux runner) says under Screenshots that it could not capture the views and asks for screenshots in the PR.- **Release notes.** They follow `.github/release_notes_template.md`, English first, then Chinese, no emojis.- Never attach or commit keys, game files or data extracted from a game, and do not paste key values into a log or a diagnostics report.