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
Issue forms for game, build and launcher problems, a PR template and contribution rules that tools follow too
v0lumehie08d1f266d0a
diff --git a/.github/ISSUE_TEMPLATE/build_problem.yml b/.github/ISSUE_TEMPLATE/build_problem.ymlnew file mode 100644index 00000000..ede8145c--- /dev/null+++ b/.github/ISSUE_TEMPLATE/build_problem.yml@@ -0,0 +1,90 @@+name: Build problem+description: Building a game, or installing it to a device, fails+body:+ - type: markdown+ attributes:+ value: |+ Thanks for the report. A build fails at one step with one message; the fields below find it.+ **Never attach game files, keys, title keys or anything extracted from a game.** Logs and screenshots are fine.+ If the game builds but then crashes, freezes or looks wrong, use the Game problem form.+ - type: dropdown+ id: step+ attributes:+ label: Which step failed+ options:+ - The key check, before the build+ - Extracting the game (NSP / NSZ / XCI)+ - Packing the RomFS+ - Shaders+ - Building the app or IPA+ - Install to an iPhone or iPad (Xcode, devicectl)+ - Updating the build tools+ - Something else+ validations:+ required: true+ - type: textarea+ id: message+ attributes:+ label: The message+ description: The error the launcher shows or the red line in the log, copied as text. A screenshot is welcome too.+ validations:+ required: true+ - type: textarea+ id: buildlog+ attributes:+ label: Build log+ description: In the launcher, the Builds page > Build log. Paste the whole log, or attach it as a file if it is long.+ render: text+ validations:+ required: true+ - type: textarea+ id: diagnostics+ attributes:+ label: Copy diagnostics+ description: In the launcher, Settings > Copy diagnostics, then paste it here. It holds the app version, the build tools' commit, Python and .NET, and the dependency check. Keys are left out and your home folder is shortened to `~`.+ render: markdown+ validations:+ required: true+ - type: input+ id: game+ attributes:+ label: Game, title ID and versions+ description: The game's name, its title ID, the base version and the update version.+ placeholder: "NieR:Automata The End of YoRHa Edition, 0100B8E016F76000, base 1.0.0, update 1.0.1"+ validations:+ required: true+ - type: dropdown+ id: target+ attributes:+ label: Built for+ options:+ - This Mac+ - iPhone / iPad+ validations:+ required: true+ - type: dropdown+ id: format+ attributes:+ label: Game files+ description: What the games folder holds for this game.+ options:+ - NSP+ - NSZ+ - XCI+ - Several of these, or a base game with updates and DLC+ validations:+ required: true+ - type: input+ id: system+ attributes:+ label: Computer and OS+ placeholder: MacBook Pro M2 Max, macOS 26.1+ validations:+ required: true+ - type: checkboxes+ id: no-game-files+ attributes:+ label: No keys, no game files+ options:+ - label: Nothing attached here contains keys, game files or data extracted from a game.+ required: truediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 00000000..b4890cb6--- /dev/null+++ b/.github/ISSUE_TEMPLATE/config.yml@@ -0,0 +1,8 @@+blank_issues_enabled: false+contact_links:+ - 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.+ - name: Install and build instructions (README)+ url: https://github.com/LNPANDY/NX2Apple#readme+ about: 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/ISSUE_TEMPLATE/game_problem.yml b/.github/ISSUE_TEMPLATE/game_problem.ymlnew file mode 100644index 00000000..e99664b0--- /dev/null+++ b/.github/ISSUE_TEMPLATE/game_problem.yml@@ -0,0 +1,110 @@+name: Game problem+description: A game crashes, freezes, runs slowly or looks wrong+body:+ - type: markdown+ attributes:+ value: |+ Thanks for the report. The fields below are what a game problem is traced with; without them the first reply is a request for them.+ **Never attach game files, keys, title keys or anything extracted from a game** (RomFS, NSOs, shaders). Logs and screenshots are fine.+ If the problem is that the build or the install to a device fails, use the Build problem form instead.+ - type: input+ id: game+ attributes:+ label: Game, title ID and versions+ description: The game's name, its title ID, the base version and the update version, as the launcher shows them for the game (or as you packed them).+ placeholder: "NieR:Automata The End of YoRHa Edition, 0100B8E016F76000, base 1.0.0, update 1.0.1"+ validations:+ required: true+ - type: dropdown+ id: target+ attributes:+ label: Where it runs+ options:+ - Mac app (built for This Mac)+ - iPhone or iPad (built for iPhone / iPad)+ validations:+ required: true+ - type: input+ id: device+ attributes:+ label: Device, chip and RAM+ description: The Mac, iPhone or iPad model with its chip and memory (Apple menu > About This Mac, or Settings > General > About).+ placeholder: iPad Pro 11-inch, M1, 16 GB+ validations:+ required: true+ - type: input+ id: os+ attributes:+ label: macOS or iOS / iPadOS version+ placeholder: iPadOS 26.1+ validations:+ required: true+ - type: input+ id: install+ attributes:+ label: How it was installed+ description: For an iPhone or iPad, "from the launcher" (Install on device) or the sideloading tool and its version (Sideloadly, AltStore, SideStore, Xcode...). For a Mac app, say that you run the app the launcher built.+ placeholder: Sideloadly 0.50, free Apple ID+ validations:+ required: true+ - type: input+ id: version+ attributes:+ label: NX2Apple version+ description: The version shown under Settings, or the release you downloaded. Copy diagnostics (below) also has it.+ placeholder: v0.4.8+ validations:+ required: true+ - type: textarea+ id: what+ attributes:+ label: What happens, and when+ description: What you did and what you saw, and when (at the menu, in game, after how many minutes). Say whether it happens every time.+ validations:+ required: true+ - type: textarea+ id: expected+ attributes:+ label: What you expected+ validations:+ required: false+ - type: textarea+ id: options+ attributes:+ label: Launch options changed from the defaults+ description: The game's launch options (the button beside Play, with render scale, frame rate and more) that you changed, and any mods. Write "none" if you changed nothing.+ placeholder: "Render scale 100%, Frame rate 30"+ validations:+ required: true+ - type: textarea+ id: diagnostics+ attributes:+ label: Copy diagnostics+ description: In the launcher, Settings > Copy diagnostics, then paste it here. It holds the app version, the build tools' commit, Python and .NET, the dependency check and the last build log lines. Keys are left out and your home folder is shortened to `~`.+ render: markdown+ validations:+ required: true+ - type: textarea+ id: log+ attributes:+ label: The game's log+ description: |+ Attach the whole log of the run (drag the file here), not excerpts:+ - Mac app: `log/<title ID>.log` in the library folder next to the game's app (the run before is `<title ID>.prev.log`). A game outside a library folder writes `~/Library/Logs/nxnative/<title ID>.log`.+ - iPhone or iPad: `log.txt` in the Files app, under the app's name (the run before is `log.prev.txt`).+ validations:+ required: true+ - type: textarea+ id: performance+ attributes:+ label: Screenshots and performance numbers+ description: For a wrong picture, a screenshot. For slow running, the Metal HUD (set `DM_METAL_HUD=1`, or turn it on in the launch options) with the frame rate it shows, and the render scale and frame rate you used.+ validations:+ required: false+ - type: checkboxes+ id: no-game-files+ attributes:+ label: No keys, no game files+ options:+ - label: Nothing attached here contains keys, game files or data extracted from a game.+ required: truediff --git a/.github/ISSUE_TEMPLATE/launcher.yml b/.github/ISSUE_TEMPLATE/launcher.ymlnew file mode 100644index 00000000..0dd75c2d--- /dev/null+++ b/.github/ISSUE_TEMPLATE/launcher.yml@@ -0,0 +1,60 @@+name: Launcher problem or idea+description: A problem with the NX2Apple app itself (library, settings, update, controller) or an idea for it+body:+ - type: markdown+ attributes:+ value: |+ For a game that crashes or looks wrong, use the Game problem form; for a failing build, the Build problem form.+ Never attach keys, game files or anything extracted from a game.+ - type: dropdown+ id: kind+ attributes:+ label: This is+ options:+ - A problem+ - An idea+ validations:+ required: true+ - type: textarea+ id: what+ attributes:+ label: What happens, or what you would like+ description: For a problem, the steps and what you saw (a screenshot helps). For an idea, what you want to do and what is in the way.+ validations:+ required: true+ - type: textarea+ id: expected+ attributes:+ label: What you expected+ validations:+ required: false+ - type: input+ id: version+ attributes:+ label: NX2Apple version+ description: The version shown under Settings, or the release you downloaded.+ placeholder: v0.4.8+ validations:+ required: true+ - type: input+ id: system+ attributes:+ label: Computer and OS+ placeholder: MacBook Pro M2 Max, macOS 26.1+ validations:+ required: true+ - type: textarea+ id: diagnostics+ attributes:+ label: Copy diagnostics+ description: For a problem, Settings > Copy diagnostics, pasted here. Keys are left out and your home folder is shortened to `~`. Not needed for an idea.+ render: markdown+ validations:+ required: false+ - type: checkboxes+ id: no-game-files+ attributes:+ label: No keys, no game files+ options:+ - label: Nothing attached here contains keys, game files or data extracted from a game.+ required: truediff --git a/.github/pull_request_template.md b/.github/pull_request_template.mdnew file mode 100644index 00000000..c6a37809--- /dev/null+++ b/.github/pull_request_template.md@@ -0,0 +1,21 @@+<!-- One change per PR. CONTRIBUTING.md says where a change may go; read it before touching dm/, scripts/, docs/, ref/ or AGENTS.md. -->++## What and why++<!-- The symptom or the need, the cause, and the change. Link the issue (Fixes #...). -->++## Checked++<!-- Delete what does not apply. Say what was not checked too. -->+- Tests: <!-- `cd frontend && swift test`; frontend-qt tests if you changed it; for scripts/sync_upstream.py, the sync run on a scratch checkout -->+- 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 -->++## Screenshots++<!-- For a UI change: before and after, in the languages it touches. -->++## Scope++- [ ] No vendored file (`dm/`, `scripts/`, `docs/`, `ref/`, `AGENTS.md`) is edited, or it goes through a sync patcher or upstream first (`pr-scope`)+- [ ] No keys, game files or data extracted from a game in the change or the attachmentsdiff --git a/CLAUDE.md b/CLAUDE.mdnew file mode 100644index 00000000..54534ad7--- /dev/null+++ b/CLAUDE.md@@ -0,0 +1,5 @@+# Notes for Claude++- Read [AGENTS.md](AGENTS.md) first.+- For an issue or a pull request, follow [CONTRIBUTING.md](CONTRIBUTING.md), section "For AI agents and other tools", and the templates in `.github/`.+- `dm/`, `scripts/`, `docs/`, `ref/` and `AGENTS.md` are vendored from upstream; do not edit them in a PR (see CONTRIBUTING.md).diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 00000000..46886904--- /dev/null+++ b/CONTRIBUTING.md@@ -0,0 +1,29 @@+# Contributing++Issues and pull requests are welcome. NX2Apple is the launcher (`frontend/`, `frontend-qt/`) and the glue around the [nxnative](https://github.com/seedds/nxnative) engine, which is vendored here and synced from upstream every day. [AGENTS.md](AGENTS.md) describes the engine.++## Where an issue goes++- **Here:** the app, a build or install that fails, and a game that does not run well on your Mac or iPhone or iPad.+- **[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.++## What a report needs++Pick a form: **Game problem**, **Build problem** or **Launcher problem or idea**. Each asks for what the problem is traced with: the game, its title ID and versions, the target, the device and OS, the NX2Apple version, **Settings > Copy diagnostics**, and the log (a game's log, or the Build log on the Builds page). A report without them gets a request for them first. Where a game's log is: a Mac game in a library folder writes `log/<title ID>.log` beside its app, otherwise `~/Library/Logs/nxnative/<title ID>.log`; on an iPhone or iPad it is `log.txt` in the Files app.++**Never attach keys, game files or anything extracted from a game.** Logs, screenshots, title IDs and build IDs are fine.++## A pull request++- One change per PR, off `main`. Commit messages say what changed and why, in plain English, as `git log` does.+- Fill in the PR template: what and why, what was checked, screenshots for UI changes.+- **`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 vendored from upstream.** The daily sync takes them file by file, so an edit there is reverted the next time upstream touches the file. The `pr-scope` check fails a PR that edits one. Send the change to seedds/nxnative first (it comes back with the sync), or ask a maintainer to add a patcher in `scripts/sync_upstream.py`. 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++Issue forms and the PR template apply in the browser only. `gh issue create`, the API and MCP tools skip the forms, so follow them yourself:++- **Issues.** Write the body as `###` headings with the same names as the form's fields (for example `### Game, title ID and versions`, `### 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.+- **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`. A change to a vendored path follows the rule above.+- 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.diff --git a/README.md b/README.mdindex 5c8374d3..9d3755eb 100644--- a/README.md+++ b/README.md@@ -237,6 +237,8 @@ useful:**Issues with a full `Documents/log.txt` get looked at first — that log usually names the exactmissing piece.+Open an issue with one of the [issue forms](https://github.com/LNPANDY/NX2Apple/issues/new/choose) (game problem, build problem, launcher); [CONTRIBUTING.md](CONTRIBUTING.md) says what a report needs.+## Staying current with upstreamA scheduled GitHub Actions workflow (`.github/workflows/sync-upstream.yml`, daily 21:30 UTC, alsodiff --git a/README.zh-CN.md b/README.zh-CN.mdindex e81404ad..f186fdf4 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -235,6 +235,8 @@ cd frontend && swift run # 或直接双击 frontend/nxnative.app带完整 `Documents/log.txt` 的 issue 会优先看——那份日志通常能直接指出缺的是什么。+开 issue 请用[问题表单](https://github.com/LNPANDY/NX2Apple/issues/new/choose)(游戏问题、构建问题、启动器);需要附什么见 [CONTRIBUTING.md](CONTRIBUTING.md)(英文)。+## 跟随上游更新一个定时的 GitHub Actions 工作流(`.github/workflows/sync-upstream.yml`,每天 21:30 UTC,也可手动