0 Fork 0

T

seeddsandv0lumehi a6787033eb Mac, in fullscreen: a screen whose refresh rate is not a multiple of the game's frame rate switches to one that is (144 → 120 Hz), from PR #79

60 fps on a 144 Hz screen cannot be paced evenly: the display link counts a tick on the refresh nearest each 1/60 s
slot (link_range's virtual ticks), so frames stay up two and three refreshes in turn (13.9 / 20.8 ms) and Apple's HUD
shows the frame interval jumping between them. link_sync now tells the front end the link's rate (60, 30, or 120
with DM_PRESENT_LINK=2; front_screen_match), and in fullscreen front_mac.m switches a screen whose mode is not a
multiple of it to the mode of the same size with the highest rate that is, with kCGConfigureForAppOnly, so macOS
switches it back when the host quits; leaving fullscreen or that screen switches it back at once. A window keeps
the screen's rate and the virtual ticks: the switch changes the whole screen for every app and most external
screens go black for a second or more. DM_SCREEN_MATCH=0 keeps the rate in fullscreen too.

Changes to the PR: the switch only in fullscreen, with the way back on leaving it (the PR switched in a window
too); no switch without a window (the windowless host's main thread runs the guest); the rate to match is
atomic; the link takes a rate change only once its object exists, so one made while its thread starts is not lost,
and sets the range directly instead of logging a pacing mode -1; the screen this host switched takes its rate
from its mode, which maximumFramesPerSecond may not show yet. The link now also sets its range again when the
window moves to another screen, which kept the first screen's range before.

Checked on this Mac's built-in 120 Hz screen (a multiple of every link rate) with a harness that drives
front_mac.m asked for 50 fps: no switch in the window, 120 → 50 Hz in fullscreen, 120 Hz again on leaving it, and
120 Hz after quitting in fullscreen; at 60 fps and with DM_SCREEN_MATCH=0 nothing switched. Hades windowed and
fullscreen (DM_FULLSCREEN=1) paced at 60 as before, the unchanged host alike. nvn_mtl.m passes an iOS SDK
syntax check. The link's new range after a switch has not run here (it needs a 144 or 165 Hz screen); the PR's
author measured the windowed switch on a 144 Hz XB273U at 2560x1440: 120 Hz, the HUD's frame interval steady at
16.7 ms, 144 Hz again after quitting.

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

2026-10-24 00:39:05 +08:00

Mac, in fullscreen: a screen whose refresh rate is not a multiple of the game's frame rate switches to one that is (144 → 120 Hz), from PR #79

2026-10-24 00:39:05 +08:00

docs

Mac, in fullscreen: a screen whose refresh rate is not a multiple of the game's frame rate switches to one that is (144 → 120 Hz), from PR #79

2026-10-24 00:39:05 +08:00

scripts

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

.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

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