okooooooo/nxnative-easy
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
363 Commits 1 Branch 0 Tags
3a993fa3feaa1071cece5677b4c1b752973b956e
T
Clone
Open with VS Code Open with VSCodium Open with Intellij IDEA
Download ZIP Download TAR.GZ Download BUNDLE
seedds 3a993fa3fe Subsystem references and a symptom index: the failure catalogue of docs/agents/03-bringup.md and the per-title material of docs/agents/04-graphics.md (section 1's container list, section 6 and its "Seen in <game>" subsections) move into docs/reference/, one heading per mechanism: rewriter.md, memory.md, threads.md, services.md, movies.md, audio.md, frame-rate.md, nvn-objects.md, rendering.md (with the Vulkan and OpenGL layers), shaders.md and game-state.md, indexed by docs/reference/README.md. Each entry gives the symptom, the cause, the fix (file and function), the games it was found on (linked to their notes in dm/games/<id>/README.md) and any check, caveat or later change; one mechanism met on several games is one entry. docs/agents/symptoms.md lists every entry's symptom (an assertion, a [RED] line, an abort or crash site, a visible result) with a link to it, 350 lines, generated from the Symptom bullets. 03 keeps the loop and reading the log, and its Failure catalogue section now points to the references, the index and where a new finding goes; 04 keeps sections 1-5 and 7 (the container list is shaders.md's Containers by engine), and section 6 says where each kind of finding is. Facts in the old sections about one game only were checked against that game's note, where they already were. Statements the code no longer matches are marked as history beside the current value (movie output slots: MD_NOUT 64, MD_NOUT_AAC 32, MD_NOUT_VIDEO 16; APP_POOL is the profile key app_pool; Engage's layout is 5 / 4.375 GB; inline uniform updates are deferred by default; scaled copies are drawn), and Tears of the Kingdom joins the node-area entry's build list (issue #70). The game notes, docs/agents/README.md, 02 and 05 link to the exact entries, and so do the comments in nvn_mtl.m (nvnTextureCompare) and hle_audio.c (the RemoteIO buffer) and the provisional-profile note in profile_guess.py. 03 goes from 29,600 to 470 words, 04 from 34,400 to 3,500. Checked: every backticked span, module address, issue / PR number and 16-digit hash of AGENTS.md, development.md, dm/games/README.md and docs/agents/01-05 at 6a06877 (4,600 items) still appears in the repository's Markdown (the same five file patterns as before appear as the full names they stood for), every relative link and heading anchor in the repository's Markdown resolves, and the tool tests pass (the four that need capstone or lz4 in the T7 venv)
2026-10-25 12:31:58 +08:00
.github/workflows
CI on GitHub's macOS runners (from PR #132): .github/workflows/tests.yml runs, for pull requests, pushes to main and manual dispatch, three jobs on macos-26 in parallel: the host unit tests and the graphics tests that need no GPU (t_dirty_slots, t_dirty_race, t_pace, t_fstep, t_hmap, t_cover, t_pso_skey, t_refl and t_rt_range_ro, the last two skipping their sample checks); every test_*.py of dm/tools/tests, dm/ios/tests and dm/gfx/tests on Python 3.14 with lz4, capstone and fonttools; and a build check: dmhost for Wonder (NVN), Hades (Vulkan) and Digimon Story Cyber Sleuth (GL), every graphics test compiled but not run, and the iOS host sources compiled for the iPhone SDK by a new helper, dm/ios/tools/compile_check.py (the host Makefile's file list and flags as gen_build.py takes them, the host's own command first so its header paths come before libvpx's; 133 files, no game files, signing or Xcode project). Read-only permissions, superseded runs cancelled, a timeout per job, logs uploaded only on failure, actions pinned to commit SHAs (checkout v7.0.1, setup-python v7.1.0, upload-artifact v7.0.2, each checked against its tag). The GPU tests stay local (the hosted runners are virtual Macs without Metal 4, issue #112), and so does profile_guess.py --check (it reads game extractions). test_xcode_workflow.py: the stand-in profile carries the registered profile's title_id, which report_profile_status reads since ce17300 (the test had 3 errors on main). Checked by replaying the three jobs on this Mac on current main: all pass, the tool tests in a fresh Python 3.14 venv with only the three packages
2026-10-25 01:58:01 +08:00
dm
Subsystem references and a symptom index: the failure catalogue of docs/agents/03-bringup.md and the per-title material of docs/agents/04-graphics.md (section 1's container list, section 6 and its "Seen in <game>" subsections) move into docs/reference/, one heading per mechanism: rewriter.md, memory.md, threads.md, services.md, movies.md, audio.md, frame-rate.md, nvn-objects.md, rendering.md (with the Vulkan and OpenGL layers), shaders.md and game-state.md, indexed by docs/reference/README.md. Each entry gives the symptom, the cause, the fix (file and function), the games it was found on (linked to their notes in dm/games/<id>/README.md) and any check, caveat or later change; one mechanism met on several games is one entry. docs/agents/symptoms.md lists every entry's symptom (an assertion, a [RED] line, an abort or crash site, a visible result) with a link to it, 350 lines, generated from the Symptom bullets. 03 keeps the loop and reading the log, and its Failure catalogue section now points to the references, the index and where a new finding goes; 04 keeps sections 1-5 and 7 (the container list is shaders.md's Containers by engine), and section 6 says where each kind of finding is. Facts in the old sections about one game only were checked against that game's note, where they already were. Statements the code no longer matches are marked as history beside the current value (movie output slots: MD_NOUT 64, MD_NOUT_AAC 32, MD_NOUT_VIDEO 16; APP_POOL is the profile key app_pool; Engage's layout is 5 / 4.375 GB; inline uniform updates are deferred by default; scaled copies are drawn), and Tears of the Kingdom joins the node-area entry's build list (issue #70). The game notes, docs/agents/README.md, 02 and 05 link to the exact entries, and so do the comments in nvn_mtl.m (nvnTextureCompare) and hle_audio.c (the RemoteIO buffer) and the provisional-profile note in profile_guess.py. 03 goes from 29,600 to 470 words, 04 from 34,400 to 3,500. Checked: every backticked span, module address, issue / PR number and 16-digit hash of AGENTS.md, development.md, dm/games/README.md and docs/agents/01-05 at 6a06877 (4,600 items) still appears in the repository's Markdown (the same five file patterns as before appear as the full names they stood for), every relative link and heading anchor in the repository's Markdown resolves, and the tool tests pass (the four that need capstone or lz4 in the T7 venv)
2026-10-25 12:31:58 +08:00
docs
Subsystem references and a symptom index: the failure catalogue of docs/agents/03-bringup.md and the per-title material of docs/agents/04-graphics.md (section 1's container list, section 6 and its "Seen in <game>" subsections) move into docs/reference/, one heading per mechanism: rewriter.md, memory.md, threads.md, services.md, movies.md, audio.md, frame-rate.md, nvn-objects.md, rendering.md (with the Vulkan and OpenGL layers), shaders.md and game-state.md, indexed by docs/reference/README.md. Each entry gives the symptom, the cause, the fix (file and function), the games it was found on (linked to their notes in dm/games/<id>/README.md) and any check, caveat or later change; one mechanism met on several games is one entry. docs/agents/symptoms.md lists every entry's symptom (an assertion, a [RED] line, an abort or crash site, a visible result) with a link to it, 350 lines, generated from the Symptom bullets. 03 keeps the loop and reading the log, and its Failure catalogue section now points to the references, the index and where a new finding goes; 04 keeps sections 1-5 and 7 (the container list is shaders.md's Containers by engine), and section 6 says where each kind of finding is. Facts in the old sections about one game only were checked against that game's note, where they already were. Statements the code no longer matches are marked as history beside the current value (movie output slots: MD_NOUT 64, MD_NOUT_AAC 32, MD_NOUT_VIDEO 16; APP_POOL is the profile key app_pool; Engage's layout is 5 / 4.375 GB; inline uniform updates are deferred by default; scaled copies are drawn), and Tears of the Kingdom joins the node-area entry's build list (issue #70). The game notes, docs/agents/README.md, 02 and 05 link to the exact entries, and so do the comments in nvn_mtl.m (nvnTextureCompare) and hle_audio.c (the RemoteIO buffer) and the provisional-profile note in profile_guess.py. 03 goes from 29,600 to 470 words, 04 from 34,400 to 3,500. Checked: every backticked span, module address, issue / PR number and 16-digit hash of AGENTS.md, development.md, dm/games/README.md and docs/agents/01-05 at 6a06877 (4,600 items) still appears in the repository's Markdown (the same five file patterns as before appear as the full names they stood for), every relative link and heading anchor in the repository's Markdown resolves, and the tool tests pass (the four that need capstone or lz4 in the T7 venv)
2026-10-25 12:31:58 +08:00
scripts
Bayonetta 2 (01007960049A0000, update 1.2 = v131072, PlatinumGames' engine in its Wii U form on SDK 3.6.0, the oldest SDK so far): game profile, a CRI CPK reader for the shader split, and two general NVN fixes. Plays on the iPhone (IPA 12.5 GB, user). On the Mac from a fresh save: the boot, the PlatinumGames logo movie (USM), the title, a new game (slot 1, the auto-save notice, Story, Normal), the opening narration (which cannot be skipped on a first play), the prologue cutscene (skipped: Plus, Down, A, A), the tutorial (closed: Plus, Down x4, A), Verse 1 on the jet, Rodin's cutscene and the next fight with an Umbran Climax and a torture attack, with Wwise sound through two 6-channel AudioOuts: 60 fps in play (frame time p50 16.67 ms, p95 about 17.5 ms; GPU 2-3.5 ms a frame on an M6), 30 in its cutscenes as the game asks, about 1.6 GB resident and 1.75 GB of Metal allocations. No host change was needed for SDK 3.6.0 itself (NVN API 53); no virtual address memory (a 3.11 GB heap in the 4 GB layout, mem_used 102 MB). Files: six CPK archives (9.5 GB, 6,091 files, 12 GB of them CRILAYLA-compressed) of PlatinumGames DAT archives. New dm/gfx/tools/cpk.py: the @UTF tables (and the masked ones of Unicorn Overlord's CPKs, the same tables as before once unmasked), the TOC and CRILAYLA (a decoder over a bit string, about 29 MB/s); shader_split.py cpk_jobs splits the CPKs into jobs and scans each entry (a CPK it cannot read is scanned as one file, with a [RED] line). Shaders: 1,856 BNSH files of one stage each (.vso / .pso) in shader.dat, shader2.dat and shadereff.dat of data000.cpk, all built for the Mac and iOS. nvn_mtl.m, both general: a cleared attachment larger than the render pass (Metal's render area is the smallest attachment) is now cleared in a pass of its own and loaded by the pass, as NVN clears the whole target (rp_begin_ex_): the game's 32x32 and 256x256 passes cleared only that corner of its full-size depth target, so the opening narration drew in a corner of a black screen and the opening scenes were speckled; and Downsample of a single-sample texture is a filtered scaling copy of the whole level that may convert the format (copy_t2t, its bloom chain 320x176 -> 80x48 and its 1280x720 BGRA8 frame into an RGBA8 texture), which logged red lines before. build_ipa_from_nsp.py: a survey note for CPK archives. Profile: the 3D pad layout (the camera is on the right stick; the game's touch controls are handheld only), a prewarm list recorded on the Mac over the route above (974 lines). Checked: the graphics run list, the host unit tests and the 49 tool tests pass; Unicorn Overlord's CPKs split as before. Not checked: 13 Sentinels and Catherine: Full Body's CPKs (no files on the drives), the clear fix in other games beyond the unit tests. README (games gallery, a Mac picture of Verse 1), AGENTS.md (58 -> 59), docs/development.md and docs/agents 01 / 03 / 04 say so
2026-10-25 08:56:02 +08:00
.gitignore
c1_full.tsv and cb_extent.tsv are no longer committed: each checkout makes them from its own shader build's Mac outputs (git ignores them in dm/games/*/), as the NSP script does after its iOS shader build. They follow from the MSL this Mac built, every chain change rewrote about 90 of them, and 56704a0 could only carry most over unchecked; 81 files, 18.7 MB. The NSP script makes a missing one as a stale one (chain_tables now says whether both name the chain: with no Mac outputs a reuse builds again and a build stops), and no step's reuse key counts them (profile_files), so the run after they were made does not split again. build_ipa.sh stops for an NVN game whose c1_full.tsv is missing or names another chain, with the c1_guard.py command, before generating anything (the host would give every c1 its own 64 KiB). Checked on The Great Ace Attorney Chronicles from a checkout without them: the first pack made both (0 and 409 entries, as committed), the second reused the split and the iOS shaders with no table lines, a third with them deleted made them from the reused build's Mac outputs; build_ipa.sh stops on a missing and a stale c1_full.tsv. AGENTS.md's chain procedure, dm/games/README.md, dm/gfx/README.md and docs/development.md say so
2026-10-23 22:24:10 +08:00
AGENTS.md
Per-game notes beside each profile: dm/games/<id>/README.md for all 58 games, and the games table in dm/games/README.md. Each note says what the profile needs and why (a table of its game.tsv keys, patches.py cuts and frame-step stubs, sdk_patches.py cuts for its sdk build, manual shader rows), the game's own findings by topic (frame rate, memory, rendering, audio, movies, services, files and shaders, input, Mac routes), each marked current or resolved, a "Found on this game" list of the general host changes first needed there (one line each, linked to where they are explained), and what is still open, including stale profile comments and figures the sources disagree on. The notes gather what was spread over AGENTS.md, docs/development.md (Game notes and Power), docs/agents/01-05 and the profiles' own comments. The Game notes section of docs/development.md (523 lines, 53 games) is now a pointer to the table; development.md goes from 33,300 to 8,600 words. README.md, AGENTS.md and the Breath of the Wild link in 04-graphics.md point to the notes. A README.md in a profile folder changes no shader cache key (dmsh_chain.inputs hashes only the named tables and keys) and no profile listing (game.py lists folders with a game.tsv). Checked: every backticked span, module address, issue / PR number and 16-digit hash of AGENTS.md, development.md, dm/games/README.md and docs/agents/01-05 at 6a06877 (4,600 items) still appears in the repository's Markdown (five file patterns now appear as the full names they stood for), and every relative link and heading anchor in the repository's Markdown resolves
2026-10-25 12:28:47 +08:00
LICENSE
LICENSE: copyright holder seedds
2026-10-23 10:49:32 +08:00
README.md
Per-game notes beside each profile: dm/games/<id>/README.md for all 58 games, and the games table in dm/games/README.md. Each note says what the profile needs and why (a table of its game.tsv keys, patches.py cuts and frame-step stubs, sdk_patches.py cuts for its sdk build, manual shader rows), the game's own findings by topic (frame rate, memory, rendering, audio, movies, services, files and shaders, input, Mac routes), each marked current or resolved, a "Found on this game" list of the general host changes first needed there (one line each, linked to where they are explained), and what is still open, including stale profile comments and figures the sources disagree on. The notes gather what was spread over AGENTS.md, docs/development.md (Game notes and Power), docs/agents/01-05 and the profiles' own comments. The Game notes section of docs/development.md (523 lines, 53 games) is now a pointer to the table; development.md goes from 33,300 to 8,600 words. README.md, AGENTS.md and the Breath of the Wild link in 04-graphics.md point to the notes. A README.md in a profile folder changes no shader cache key (dmsh_chain.inputs hashes only the named tables and keys) and no profile listing (game.py lists folders with a game.tsv). Checked: every backticked span, module address, issue / PR number and 16-digit hash of AGENTS.md, development.md, dm/games/README.md and docs/agents/01-05 at 6a06877 (4,600 items) still appears in the repository's Markdown (five file patterns now appear as the full names they stood for), and every relative link and heading anchor in the repository's Markdown resolves
2026-10-25 12:28:47 +08:00

README.md

nxnative

Play your own Nintendo Switch games natively on iPhone and iPad. Bring your game (its NSP files) and your prod.keys; one script turns them into an IPA that you sideload.

It is not an emulator: the game's own code runs directly on the Apple chip, with Switch graphics rebuilt on Metal. Nothing from any game is in this repository, and the project is not affiliated with Nintendo or any game publisher.

Acknowledgements

This project is built on other people's work:

  • d2r-mobile (MIT) developed this native-execution approach, for Diablo II: Resurrected. nxnative started as a copy of its generic parts: the NSO rewriter, the host that stands in for Horizon, the NVN-on-Metal layer and the iOS app shell. Fixes go both ways.
  • Ryujinx (MIT): its shader translator (Ryujinx.Graphics.Shader, Ryujinx.Common and Spv.Generator 1.3.2, in dm/third_party/ryujinx with a few fixes listed in its README) turns the games' Maxwell shaders into SPIR-V. Its emulation of the kernel and system services is also a reference when the host's behaviour is in doubt.
  • Atmosphère: its kernel, mesosphère, is the reference for Horizon's synchronization semantics (address arbiter, condition variables).
  • yuzu: Maxwell instruction encodings for the shader reference tool, and a cross-check for kernel behaviour.
  • LibHac: reads NSPs and layers updates over the base game in dm/tools/nx_extract. hactool did the first extractions.
  • SPIRV-Cross: SPIR-V to Metal Shading Language. glslang compiles the GLSL of OpenGL games to SPIR-V for it.
  • deko3d (zlib): its texture layout size algorithm is ported in dm/gfx/nvn/nvn_tex.c.
  • libvpx (VP9 movies), stb_vorbis (movie sound), the Vulkan headers and NVIDIA FLIP ship in dm/third_party with their licenses (list).
  • Capstone, lz4, fontTools and XcodeGen are used by the build.

Games

All of these are tested on an iPhone and playable:

Needs iOS / iPadOS 26 or later on an iPhone 15 Pro or newer (A17 Pro chip or later) or an iPad with an M1 chip or later: the games' textures are BC-compressed, and older iPhones can't read that format. Other games aren't supported yet. For them the script writes a survey and still tries its best to pack an IPA, guessing the game's settings; such an IPA may not start.

Under each game: the IPA's size, and "60 fps with 1.2.0" where the game runs at 60 fps (30 on the Switch) with that update.

Mario Kart 8 Deluxe
Mario Kart 8 Deluxe
~11.9 GB · no Mii heads		 Mario vs. Donkey Kong
Mario vs. Donkey Kong
~1.6 GB		 Paper Mario: The Thousand-Year Door
Paper Mario: The Thousand-Year Door
~5 GB · 60 fps with 1.0.1
Super Mario 3D World + Bowser's Fury
Super Mario 3D World + Bowser's Fury
~3 GB		 Super Mario Bros. Wonder
Super Mario Bros. Wonder
~4 GB		 Super Mario Galaxy
Super Mario Galaxy
~3 GB
Super Mario Galaxy 2
Super Mario Galaxy 2
~3 GB		 Super Mario Odyssey
Super Mario Odyssey
~6 GB		 The Legend of Zelda: Breath of the Wild
The Legend of Zelda: Breath of the Wild
~16 GB · 60 fps with 1.9.0
The Legend of Zelda: Link's Awakening
The Legend of Zelda: Link's Awakening
~6 GB		 The Legend of Zelda: Tears of the Kingdom
The Legend of Zelda: Tears of the Kingdom
~17 GB · 60 fps with 1.4.3		 13 Sentinels: Aegis Rim
13 Sentinels: Aegis Rim
~5 GB
Absolum
Absolum
~2 GB		 Ace Attorney Investigations Collection
Ace Attorney Investigations Collection
~7 GB		 Advance Wars 1+2: Re-Boot Camp
Advance Wars 1+2: Re-Boot Camp
~7.1 GB
AI: THE SOMNIUM FILES
AI: THE SOMNIUM FILES
~8.3 GB		 AI: THE SOMNIUM FILES - nirvanA Initiative
AI: THE SOMNIUM FILES - nirvanA Initiative
~11.6 GB		 Animal Crossing: New Horizons
Animal Crossing: New Horizons
~10.5 GB
ANIMAL WELL
ANIMAL WELL
~54 MB		 Balatro
Balatro
~82 MB · played by touch		 BALL x PIT
BALL x PIT
~1.1 GB
Bayonetta
Bayonetta
~8.8 GB		 Bayonetta 2
Bayonetta 2
~12.5 GB		 Bayonetta 3
Bayonetta 3
~14.2 GB
Big Brain Academy: Brain vs. Brain
Big Brain Academy: Brain vs. Brain
~0.8 GB		 Brain Memory Training Academy
Brain Memory Training Academy
~0.1 GB		 Captain Toad: Treasure Tracker
Captain Toad: Treasure Tracker
~2 GB
Catherine: Full Body
Catherine: Full Body
~14 GB		 Celeste
Celeste
~0.9 GB		 Cuphead
Cuphead
~5 GB
DARK SOULS: REMASTERED
DARK SOULS: REMASTERED
~4 GB · 60 fps with 1.0.3		 Digimon Story Cyber Sleuth: Complete Edition
Digimon Story Cyber Sleuth: Complete Edition
~5 GB		 DRAGON QUEST VII Reimagined
DRAGON QUEST VII Reimagined
~5.9 GB
DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition
DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition
~15 GB · 60 fps with 1.0.4		 FINAL FANTASY RESONANCE
FINAL FANTASY RESONANCE
~10 GB · 60 fps with 1.0.1		 FINAL FANTASY TACTICS - The Ivalice Chronicles
FINAL FANTASY TACTICS - The Ivalice Chronicles
~11 GB
Fire Emblem Engage
Fire Emblem Engage
~15 GB · 60 fps with 2.0.0		 Fire Emblem: Three Houses
Fire Emblem: Three Houses
~13 GB · 60 fps with 1.2.0		 The Great Ace Attorney Chronicles
The Great Ace Attorney Chronicles
~4 GB
Hades
Hades
~4 GB		 Hades II
Hades II
~4 GB		 Hollow Knight: Silksong
Hollow Knight: Silksong
~6.4 GB
Hyrule Warriors: Age of Calamity
Hyrule Warriors: Age of Calamity
~15 GB · 60 fps with 1.3.0		 Luigi's Mansion 3
Luigi's Mansion 3
~7.5 GB · 60 fps with 1.4.0		 Metroid Dread
Metroid Dread
~5 GB
Monster Hunter Rise
Monster Hunter Rise
~22 GB · 60 fps with 16.0.2		 Monster Train 2
Monster Train 2
~1.6 GB · 60 fps with 1.1.1		 Octopath Traveler 0
Octopath Traveler 0
~4 GB · 60 fps with 1.0.5
Patrick's Parabox
Patrick's Parabox
~0.2 GB		 Pikmin 4
Pikmin 4
~10.8 GB		 Pokémon Legends: Z-A
Pokémon Legends: Z-A
~6 GB
Pokémon Sword
Pokémon Sword
~12.4 GB		 Raging Loop
Raging Loop
~0.9 GB		 Rhythm Heaven Groove
Rhythm Heaven Groove
~3 GB
ROMANCE OF THE THREE KINGDOMS 8 REMAKE
ROMANCE OF THE THREE KINGDOMS 8 REMAKE
~16.8 GB · controller only		 Stardew Valley
Stardew Valley
~0.6 GB		 STEINS;GATE RE:BOOT
STEINS;GATE RE:BOOT
~6 GB
Super Smash Bros. Ultimate
Super Smash Bros. Ultimate
~17.5 GB · offline		 Taiko Risshiden V DX
Taiko Risshiden V DX
~3.3 GB · Japanese · played by touch		 Unicorn Overlord
Unicorn Overlord
~4 GB

Pack an IPA

Prefer a graphical interface to the command line? NX2Apple is a community fork with a macOS app that runs this whole pipeline for you and packs the game files into a sharded RomFS archive for a slimmer IPA. It is a separate project that follows this one; the steps below are nxnative's own command-line way.

1. Get nxnative and its tools (once, on a Mac with Xcode and Homebrew):

git clone https://github.com/seedds/nxnative.git && cd nxnative
brew install xcodegen zstd spirv-cross glslang
brew install --cask dotnet-sdk
python3 -m pip install lz4 capstone fonttools "backports.zstd; python_version < '3.14'"

2. Put one game's NSPs in a folder: the base game (an NSP, or an XCI cartridge dump), plus its update and DLC if you have them:

~/Games/MarioWonder/
  Super Mario Bros. Wonder [010015100B514000][v0].nsp
  Super Mario Bros. Wonder [010015100B514800][v327680].nsp

NSZ and XCZ files (compressed NSPs and XCIs) work too: the script converts them once with nsz (python3 -m pip install nsz) and keeps the NSPs in <title ID>_build/nsp/, which takes their full size on disk.

Any version works, with or without an update: the script packs the newest version in the folder. DLC is optional too: the DLC in the folder is packed, and without it the game sees none, as on a Switch without it. Each game was tested on one version (an update named in the table above is the one its 60 fps needs). With another version the script builds the game with that version's own shaders and says that the version was not tested; fixes made for the tested version's code, such as the 60 fps ones, don't apply to it.

3. Run the script:

python3 scripts/build_ipa_from_nsp.py ~/Games/MarioWonder -k ~/keys/prod.keys

The IPA appears in the same folder (here ~/Games/MarioWonder/SMBWMobile.ipa). The first build takes 30–60 minutes, later ones about 10. You need free disk space of about twice the NSPs' size plus 10 GB. Options such as -o (output path) and --app-name are listed by -h.

4. Install the IPA with your sideloading tool (AltStore, Sideloadly, LiveContainer, …). The app gets the game's name, icon and version (the update's version, for example 1.2.1 for Mario Wonder; the base game's when there is no update). Sign it with the Increased Memory Limit capability (com.apple.developer.kernel.increased-memory-limit) if your tool can: without it iOS gives the app about 3.4 GB and closes the bigger games (Hyrule Warriors: Age of Calamity and Hades II use more, Breath of the Wild and Cuphead come close); with it a recent iPhone gives about 6 GB.

With an Apple developer account you can instead build and install from Xcode: --prepare-xcode makes an Xcode project for the game rather than an IPA (Build and run on a device with Xcode).

Play

Settings. A screen before the game starts offers what the game supports: frame rate, render scale, docked or handheld mode, game language, the frame-rate counter and Apple's performance HUD. Tap Play to start; the app remembers your choices.

Touch controls. Tap 2D / 3D at the top to switch layouts; the app remembers your choice. Wonder, Engage, Dread, 13 Sentinels, Link's Awakening, Ace Attorney Investigations Collection, Unicorn Overlord, Rhythm Heaven Groove, Octopath Traveler 0, Pokémon Legends: Z-A, Cuphead, Absolum, Brain Memory Training Academy, The Great Ace Attorney Chronicles, STEINS;GATE RE:BOOT, Big Brain Academy: Brain vs. Brain, Patrick's Parabox, Celeste, Raging Loop and Mario vs. Donkey Kong start in 2D, the other games in 3D (STEINS;GATE RE:BOOT's quick save is R3, in the 3D layout). In 3D, the right stick (the camera in most games) is not drawn: swipe on the right third of the screen, starting anywhere off the buttons. In Super Mario Galaxy and Super Mario Galaxy 2, other touches outside the controls move the pointer; in Captain Toad: Treasure Tracker they touch the game's screen (touch blocks, stun enemies), and in Big Brain Academy: Brain vs. Brain too (its menus and activities). A connected game controller hides the touch controls and keeps every button.

Rumble. Game vibration uses the iPhone's haptic engine or a compatible connected controller. Controllers with separate left/right haptic outputs keep those effects separate. The launcher's Game rumble and Rumble strength settings control it independently of Touch feedback. Phone rumble approximates the Switch's effects; physical feel and controller compatibility still need device testing.

Shaking. Shake the iPhone to shake the controller, in games that read its motion: Super Mario Odyssey's motion moves (such as the cap throw on a shake) need it, and Odyssey only takes them in its default docked mode. A light bump does not count; a sharp flick of the phone does.

  • Game language is English by default. Pick another when packing with --language (-l), by code or by name: -l ja, -l zh-Hans, -l French (LANGUAGE in Spyder). It must be one the game has; the script prints the game's languages and stops on one it lacks. To change it without rebuilding, pick another on the settings screen.
  • Saves and logs are in the Files app, under the app's name: save/ and log.txt. When something goes wrong, send log.txt (the previous run is log.prev.txt).
  • Short stutters the first time a new scene appears are normal: the app compiles graphics for it once and remembers them for the next launch.
  • Reinstalling: some sideloading tools give a reinstalled app a new data folder. Copy save/ and pso_user.tsv over from the old one to keep your progress.
  • Settings in a file: lines like DM_OPMODE=0 (handheld mode: lower resolution, higher frame rate) in Documents/env.txt win over the settings screen, which then shows them greyed out. DM_FPS_TARGET=30 keeps Breath of the Wild, Tears of the Kingdom and Octopath Traveler 0 at their original 30 fps, which saves battery; DM_PRESENT_INTERVAL=game does the same for Monster Train 2. DM_SHOW_FPS=1 shows the frame rate at the top left (--show-fps when packing turns it on from the start). DM_LAUNCHER=0 skips the settings screen.

Known issues

  • No amiibo and no online features.
  • Fire Emblem Engage: after switching away from the app and back, some sounds may stay silent until you restart it.
  • Fire Emblem: Three Houses: small square patches on the ground where decals land.
  • Super Mario Galaxy and Super Mario Galaxy 2: effects drawn as points or lines come out one pixel wide.

For developers

How it works, the script's options, running games on the Mac and adding a game: docs/development.md. Per-game notes: dm/games. In-depth bring-up and debugging notes: docs/agents.

License

MIT (see LICENSE). Third-party code keeps its own license; see dm/third_party.

Reference in new issue View Git Blame Copy Permalink
S
Description
Run supported Nintendo Switch games natively on Mac, iPhone & iPad. One-command setup, complete Mac apps, lightweight iOS builds, Xbox/PS4/PS5 controllers and editable touch controls. Built on seedds/nxnative. Bring your own games and keys.
Readme MIT
108 MiB
0 Stars 1 Watchers 0 Forks
Languages
Objective-C 31.3%
C 28.4%
Python 28.4%
Swift 5.7%
Assembly 2.6%
Other 3.5%