0 Fork 0

T

seeddsandv0lumehi 4e91a3d053 Readable-tile variants compile again for pixel shaders with an integer-output entry point (main0_u), from PR #83

Since 626e6a6 a pixel shader whose outputs look like integer writes gets a second entry point, main0_u, appended
after main0. dmsh_fetch.variant, which makes the framebuffer-fetch variant (_bf), rewrote samples to fb0..fb7 in
the whole source, main0_u included, but declared them only on main0, and renamed main0_out's members, which
main0_u still reads: every variant of such a shader failed to compile (use of undeclared identifier 'fb0'), and
the shader lost the tile read (its render passes are not merged). The host takes main0_u from the shader's own
library (nvn_mtl.m entry_u), never from the variant, so the variant is now made from the source cut at
struct main0_out_u, which dmsh_build.py always appends with main0_u at the end. A main0 with no parameters
also got its fb parameters with a leading comma (main0(, float4 fb0 ...)); output-mapping-only variants only.

Checked on Breath of the Wild's library MSL (chain 534b10d1d578, 10,560 pixel shaders), old and new variant()
side by side: the 8,659 shaders without main0_u give byte-identical variants, with and without
output-mapping-only; all 1,639 changed variants of shaders with main0_u failed to compile before and compile now
(Mac), and 1,897 of 1,897 output-mapping-only ones when forced for every key (30 of them the leading comma; no
profile's bf_want.tsv lists a key today); 40 of them compiled for iOS too. A full Mac dmsh_build.py run on the
new chain 657c42552d82: 19,592 of 19,592 shaders and 6,254 variants with no compile failure (main's chain would
lose the 1,639), stamped, both tables made; the Mac host booted Breath of the Wild with it past frame 5,100, its
title presses into play, with no red line. dm/tools/tests pass. dmsh_fetch.py is part of the chain, so
dm/gfx/nvn/dmsh_chain.h is written again and every game's shaders rebuild at their next build.

Co-authored-by: v0lumehi <34629096+v0lumehi@users.noreply.github.com>

2026-10-24 01:40:58 +08:00

Readable-tile variants compile again for pixel shaders with an integer-output entry point (main0_u), from PR #83

2026-10-24 01:40:58 +08:00

docs

Mac: each controller is a player of its own, for local co-op (GitHub issue #74 ), from PR #84

2026-10-24 01:40:58 +08:00

scripts

NSP script: --platform mac (PLATFORM = 'mac') builds only what running a game on this Mac needs, from PR #82

2026-10-24 01:40:58 +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

One translation chain version for every game: DMSH_CHAIN in dm/gfx/nvn/dmsh_chain.h replaces the 47 dm/games/<id>/dmsh_chain.h, which every chain change rewrote and some were left behind (GitHub issue #78 ). The version hashed each profile's shader tables and nvn_* / shader_* keys too, once the only thing that kept the host off a library built from older tables; each shader's cache key (dmsh_build.py shader_key) has covered them since, so the version now covers only the chain's tools (dmsh_chain.py, dmsh_build.py, dmsh_fetch.py, dmsh_vin.py, dmsh_geometry.py, dmsh_facts.py, the translator's source, ios_metal.py, the lock) and the options, and needs no DM_GAME. What the per-game part still did is done by the library itself: a full dmsh_build.py run stamps b-<V>/inputs.tsv (Mac and iOS) with the game and the digest of the profile's inputs (dmsh_chain.py inputs / --inputs: the four shader tables, bf_want.tsv, which the variants use but the version never counted, and the keys), starts from no shader outputs (a partial one from none of the keys it builds), so a key that left the map, a shader that no longer builds or a variant no longer made keeps no old library, refuses a directory stamped for another game, and writes the profile's c1_full.tsv and cb_extent.tsv from its Mac outputs; a partial build keeps the stamp only while it names the current inputs. c1_guard.py / cb_extent.py head their table with the library's chain version and stamp (table_head), and the host takes a table only beside that stamp, logs the stamp and reports one of another game; build_ipa.sh reads the one header and stops when the iOS libraries' stamp is not this profile's current inputs or c1_full.tsv names another. NSP script: chain_header writes the one header when stale, before any host is built; provisional and derived profiles no longer write one; chain_tables makes a table again when it does not name the reused library's stamp (False without one). Makefiles take the header beside nvn_mtl.m; Xcode projects prepared earlier point at a profile header that is gone and are told to prepare again. Tests: test_nsp_chain.py (the committed header is current, stale and missing ones are written, tables against the stamp). Checked on The Great Ace Attorney Chronicles: a full build gave 460 of 460 shaders and both tables (0 and 409 entries, as before), the Mac host booted with the stamp and both tables past frame 900; one added facts row rebuilt one shader under the same chain version with a new digest and new tables, and the host refused the old tables beside the new stamp; a full build removed planted outputs, another game's build into that directory stopped, a partial build after an input change dropped the stamp; build_ipa.sh stopped on a stale stamp, a missing one and a stale or old-form c1_full.tsv; three NSP packs built (no table lines: dmsh_build made them), reused everything, and remade deleted tables from the reused build. Graphics unit tests give the same results as before (on this Mac t_refl needs ~/dm-work's libraries and several GPU tests fail on the previous commit too). AGENTS.md's chain procedure (header once after a tool change; a full shader build makes the tables), dm/games/README.md, dm/gfx/README.md and docs/development.md say so

2026-10-23 23:37:03 +08:00

LICENSE

LICENSE: copyright holder seedds

2026-10-23 10:49:32 +08:00

README.md

README / AGENTS: Mario Kart 8 Deluxe plays on the iPhone (games table with a Mac picture of Mario Kart Stadium's anti-gravity section, IPA ~11.9 GB, Mii heads not drawn without the firmware; AGENTS.md list 46 → 47 with its notes; the profile says so). On an A20 Pro: 60 fps docked, about 6 ms of GPU time a frame, 2.4 GB footprint with 3.7 GB of headroom, no audio underruns

2026-10-23 20:37:01 +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.


Super Mario Bros. Wonder _{IPA ~4 GB}	Fire Emblem Engage _{IPA ~15 GB · 60 fps (30 on Switch) with update 2.0.0}
Metroid Dread _{IPA ~5 GB}	13 Sentinels: Aegis Rim _{IPA ~5 GB}
Super Mario 3D World + Bowser's Fury _{IPA ~3 GB}	The Legend of Zelda: Breath of the Wild _{IPA ~16 GB · 60 fps (30 on Switch) with update 1.9.0}
The Legend of Zelda: Link's Awakening _{IPA ~6 GB}	Super Mario Odyssey _{IPA ~6 GB}
Hades _{IPA ~4 GB}	Hyrule Warriors: Age of Calamity _{IPA ~15 GB · 60 fps (30 on Switch) with update 1.3.0}
Fire Emblem: Three Houses _{IPA ~13 GB · 60 fps (30 on Switch) with update 1.2.0}	Super Mario Galaxy _{IPA ~3 GB}
The Legend of Zelda: Tears of the Kingdom _{IPA ~17 GB · 60 fps (30 on Switch) with update 1.4.3}	Monster Hunter Rise _{IPA ~22 GB · 60 fps (30 on Switch) with update 16.0.2}
Ace Attorney Investigations Collection _{IPA ~7 GB}	Hades II _{IPA ~4 GB}
Unicorn Overlord _{IPA ~4 GB}	Rhythm Heaven Groove _{IPA ~3 GB}
Octopath Traveler 0 _{IPA ~4 GB · 60 fps (30 on Switch) with update 1.0.5}	Pokémon Legends: Z-A _{IPA ~6 GB}
Cuphead _{IPA ~5 GB}	Super Mario Galaxy 2 _{IPA ~3 GB}
FINAL FANTASY TACTICS - The Ivalice Chronicles _{IPA ~11 GB}	Absolum _{IPA ~2 GB}
Captain Toad: Treasure Tracker _{IPA ~2 GB}	Brain Memory Training Academy _{IPA ~0.1 GB}
The Great Ace Attorney Chronicles _{IPA ~4 GB}	STEINS;GATE RE:BOOT _{IPA ~6 GB}
Big Brain Academy: Brain vs. Brain _{IPA ~0.8 GB}	Patrick's Parabox _{IPA ~0.2 GB}
Celeste _{IPA ~0.9 GB}	DRAGON QUEST XI S: Echoes of an Elusive Age – Definitive Edition _{IPA ~15 GB · 60 fps (30 on Switch) with update 1.0.4}
Monster Train 2 _{IPA ~1.6 GB · 60 fps (30 on Switch) with update 1.1.1}	Raging Loop _{IPA ~0.9 GB}
DARK SOULS: REMASTERED _{IPA ~4 GB · 60 fps (30 on Switch) with update 1.0.3}	Paper Mario: The Thousand-Year Door _{IPA ~5 GB · 60 fps (30 on Switch) with update 1.0.1}
Hollow Knight: Silksong _{IPA ~6.4 GB}	Catherine: Full Body _{IPA ~14 GB}
Digimon Story Cyber Sleuth: Complete Edition _{IPA ~5 GB}	Animal Crossing: New Horizons _{IPA ~10.5 GB with update 3.0.3}
DRAGON QUEST VII Reimagined _{IPA ~5.9 GB with update 1.2.0}	FINAL FANTASY RESONANCE _{IPA ~10 GB · 60 fps (30 on Switch) with update 1.0.1}
Luigi's Mansion 3 _{IPA ~7.5 GB · 60 fps (30 on Switch) with update 1.4.0}	AI: THE SOMNIUM FILES _{IPA ~8.3 GB}
ANIMAL WELL _{IPA ~54 MB · update 1.0.10}	AI: THE SOMNIUM FILES - nirvanA Initiative _{IPA ~11.6 GB · update 1.0.2}
Mario Kart 8 Deluxe _{IPA ~11.9 GB · update 4.0.0 · Mii heads not drawn (no firmware)}

Pack an IPA

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

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 and Raging Loop 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.

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, adding a game, and per-game notes: docs/development.md. In-depth bring-up and debugging notes: docs/agents.

License

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

README.md Unescape Escape

nxnative

Acknowledgements

Games

Pack an IPA

Play

Known issues

For developers

License

README.md