Skip to content

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

8.3 KB
Raw Blame

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, 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, 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. 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 the Upstream-Status values.
  • 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 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, 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-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.
  • 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 to frontend/Sources. It says where a new feature goes. BuildModel is gone: the stores are in NXModel and LauncherStores only wires them. No Swift file there is above 800 lines (SourceSizeTests), and the larger ones may only shrink.
  • 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, python3 -m unittest discover tools/tests for the tools. The engine's own tests run in engine/ as tests.yml does. The pre-commit hook runs python3 tools/engine.py check when patches/ or .upstream-ref is staged. The pre-push hook runs the checks above for the files the push changes, tools/githooks.py has 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 label full-build. A lower PR of a stack shows them as skipped, which counts as passed. Never skip a whole workflow with a paths: 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 in frontend/l10n/, read by the Mac launcher and the Windows launcher. A new string is a line in en.json and zh.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 _language entry: name, locale prefixes, order). Lang is not an enum, so a new language is one new file under frontend/l10n/ for the Mac and Windows launchers (the iOS shell's texts are in the same files under ios.ui. and ios.host., need every language, and python3 tools/l10n_shell_catalogs.py writes the shell's Localizable.xcstrings from them, never edit those by hand). The files go into the apps by the build workflows, see frontend/README.md, section "Language".
  • Release notes. They follow .github/release_notes_template.md, English first, then Chinese, no emojis.