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
Notes for agents
This is the fork's guide. The engine has its own, upstream's: engine/AGENTS.md (after python3 tools/engine.py sync, or seedds/nxnative's AGENTS.md). Read this file first, the engine's for any work in engine/.
- 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,checkandexportand the Claude Code session start do it when it is unset. Keep the hooks installed. Never use--no-verifyongit commitorgit push. Never push tomaindirectly, every change goes through a PR, patches included. The pre-push hook rejects a push tomainfor 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, 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.pyand 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 pluspatches/, built intoengine/bypython3 tools/engine.py sync.engine/is a real git repository that this one ignores. A root.ignorekeeps 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.mdends with agit -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 theFrom:line of patches made withtools/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. Outside contributors start upstream: a new game profile goes to seedds/nxnative first (CONTRIBUTING.md). A patch here is a bridge until upstream has it, and the next bump drops it once the change is in. patches/README.md has the rule and theUpstream-Statusvalues. - Work for an outside contributor. Before you build a feature or a proposal, check that an issue in a milestone exists (a maintainer puts an idea there when it gets a yes), or ask the user (CONTRIBUTING.md). 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 inengine/(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 exportturns the commits made since the last sync intopatches/NNNN-*.patchwith the headerUpstream-Status,ReasonandIssue(fill them in,--status,--reasonand--issueset them) and adds them topatches/series.python3 tools/engine.py checkmust 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 sayspendinguntil that pull request is open, thenforwarded seedds/nxnative#<n>. Commitpatches/in a PR here.syncnever throws away work inengine/: it stops and namesexport. - Never add engine files to this repository. Files under
dm/,scripts/,docs/andref/at the root are ignored by.gitignore, and thepr-scopecheck 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, 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: 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-localbuilds 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 ofswift 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. - Merging with admin rights. An admin merge never goes over a red check. That holds even when @LNPANDY overrides an objection. If a re-review is slow, the other maintainer pings the reviewer and does not merge with admin rights.
- Mac launcher layers.
frontend/is four SwiftPM targets (NXCore,NXModel,NXLauncher,NX2Apple) and the compiler enforces which may import which. Read frontend/ARCHITECTURE.md before you add a file tofrontend/Sources. It says where a new feature goes.BuildModelis gone: the stores are inNXModelandLauncherStoresonly wires them. No Swift file there is above 800 lines (SourceSizeTests), and the larger ones may only shrink. - Checks.
cd frontend && swift build && swift testfor the Mac launcher (its tests readengine/, so sync first),python3 -m unittest discover -s frontend-qt/testsfor the Qt front end,python3 -m unittest discover tools/testsfor the tools. The engine's own tests run inengine/astests.ymldoes. The pre-commit hook runspython3 tools/engine.py checkwhenpatches/or.upstream-refis staged. The pre-push hook runs the checks above for the files the push changes,tools/githooks.pyhas the list. Fix the failure, do not bypass the hook. - CI on stacks. The heavy macOS jobs (Mac launcher with
swift test, Tool tests, the engine jobs) run on the tip of a stack only, and the app build runs only for a packaging change or the labelfull-build. A lower PR of a stack shows them as skipped, which counts as passed. Never skip a whole workflow with apaths:filter, a required check must always report. Merge a stack through its top PR with the async API. CONTRIBUTING.md, section "CI on stacks", has the details. - Language and text. Everything is in English except the Chinese pages (
*.zh-CN.md) and the launcher's strings. No semicolons in UI strings, READMEs and docs. The launcher's strings are not in Swift or Python code. They are one JSON file per language infrontend/l10n/, read by the Mac launcher and the Windows launcher. A new string is a line inen.jsonandzh.json(English and Chinese have every key, the other languages may miss one and then show English). The language list is in the files too (the_languageentry: name, locale prefixes, order).Langis not an enum, so a new language is one new file underfrontend/l10n/for the Mac and Windows launchers (the iOS shell's texts are in the same files underios.ui.andios.host., need every language, andpython3 tools/l10n_shell_catalogs.pywrites the shell'sLocalizable.xcstringsfrom them, never edit those by hand). The files go into the apps by the build workflows, seefrontend/README.md, section "Language". - Release notes. They follow
.github/release_notes_template.md, English first, then Chinese, no emojis.