Skip to content

A self-contained Mac app of a game (--platform mac-app) - #150

Closed
stan69b wants to merge 2 commits into
seedds:mainfrom
stan69b:mac-app
Closed

stan69b wants to merge 2 commits into
seedds:mainfrom
stan69b:mac-app

Conversation

@stan69b

@stan69b stan69b commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

What. The NSP script's new --platform mac-app (Spyder: PLATFORM = 'mac-app') builds everything --platform mac builds, then packs <NSP folder>/<game name>.app (-o names another path). It is a double-clickable Mac app with everything inside it, and it boots the game from Finder, from any folder, without the build folder. Until now the Mac host was a development loop only: --platform mac printed a dmhost command line.

  • dm/mac/pack_app.py packs the bundle. The launcher (dm/mac/launcher.c, compiled for arm64 at the host's deployment target) is CFBundleExecutable, and the host sits beside it in Contents/MacOS. Contents/Resources holds what the IPA carries (build_ipa.sh's choice of files):

    • romfs/
    • msl/<b-chain | vk | gl>/: the Mac libraries only, not cas/, which the host never reads
    • aoc/<index>/
    • dm/: the rewritten modules and the rewriter tables the host reads, nro.tsv, the profile's shader_map.tsv / pso_manifest.tsv / c1_full.tsv / cb_extent.tsv, font/ and --env-file as env.txt

    Also AppIcon.icns, made from the game icon. Info.plist has the NACP name and display version, the IPA's bundle ID and the profile's app_category. The large folders are APFS clones (cp -c) when the app is on the build's APFS volume, and plain copies otherwise. The app is written as <app>.partial and swapped in whole.

  • The launcher sets the host's environment from the bundle, as main.m does on iOS. The save, pso_user.tsv and temporary files go to ~/Library/Application Support/nxnative/<title ID>/. The log goes to ~/Library/Logs/nxnative/<title ID>.log, and the previous run's is kept as .prev.log. Environment switches go in env.txt in that folder, then the bundle's dm/env.txt. The launcher forwards SIGTERM, SIGINT and SIGHUP to the host and returns its exit code. When the bundle's game data is missing, it shows an alert.

  • Signing: the inner host first, then the bundle. It signs ad-hoc by default; --mac-sign "<identity>" names another identity. It never uses the hardened runtime, which refuses the executable memory the host maps for the game's code, so the app cannot be notarized.

Why the launcher runs the host as a child process. macOS privacy checks (TCC) apply to files on removable volumes. A shell-script launcher that execed dmhost got EPERM on every fopen on the external drive, silently, with no prompt. That happened ad-hoc and Developer ID signed alike, and after tccutil reset. A compiled launcher that posix_spawns dmhost from Contents/MacOS can read those files. This was found on a hand-made wrapper for The Legend of Zelda: Echoes of Wisdom.

In the script, mac_run is split: mac_host builds the host and the font for both Mac platforms, mac_run makes the command as before, and mac_app runs the packer. docs/development.md gets a new "A Mac app" section (layout, saves and logs, signing, the TCC finding), and README "Pack an IPA" one line.

Checked.

  • New dm/tools/tests/test_nsp_mac_app.py, written first (it fails on main). It packs an app from stand-ins, with a stand-in host compiled in the test, and checks:

    • the layout and Info.plist
    • the ad-hoc signature, without the runtime flag
    • the launcher's environment, working folder, log rotation and both env files
    • the exit code and SIGTERM forwarding
    • the alert (with a stand-in osascript)
    • plain copies
    • the script's pack_app.py command line for an NVN and a Vulkan game
  • Every test of dm/tools/tests, dm/ios/tests and dm/gfx/tests, the host unit tests (GAME=010015100B514000) and dm/ios/tools/compile_check.py pass.

  • A real game: The Legend of Zelda: Echoes of Wisdom (01008CF01BAAC000, base game, provisional profile).

    • Built with --platform mac-app --mac-sign "Developer ID Application: …", reusing the extraction, the rewrite and the Mac shaders. The app is 9.3 GB; it sits on an external APFS drive, and its game files are clones of the extracted ones.
    • The packing stage took 1:16, mostly signing.
    • Opened with open: the log shows >>> nnMain, the prewarm list read from the bundle's pso_manifest.tsv and the player's pso_user.tsv, the uniform read extents taken (cb_extent.tsv, 9,717 shaders), and frames: 900 by about 30 s, 57.7 fps.
    • The only red line is a display-link stall at window start, which recovered.
    • No EPERM: the files are on the external drive.

Not checked: a Vulkan or GL game's app, and an app copied to another Mac.

stan69b and others added 2 commits October 25, 2026 03:14
The NSP script's --platform mac-app (Spyder: PLATFORM = 'mac-app') does everything --platform mac builds (the Mac shaders, the Mac host for the profile, the button-icon font), then packs <NSP folder>/<game name>.app (-o / OUT_IPA names another path; ':' and '/' in the game name become ' - '), which boots the game when opened from Finder, from any folder, without the build folder. New dm/mac/pack_app.py packs it: the launcher dm/mac/launcher.c (compiled for arm64 at the host's deployment target) as CFBundleExecutable, the host beside it in Contents/MacOS, and in Contents/Resources what the IPA carries (build_ipa.sh's choice): romfs/, msl/<b-chain | vk | gl>/ (the Mac libraries only, not the cas/ compile cache, which the host never reads), aoc/<index>/, and dm/ with the rewritten modules and the rewriter tables the host reads (*.patched.bin, fixups, gates, cuts, obs, nro.tsv; not sites.tsv), the profile's shader_map.tsv, pso_manifest.tsv, c1_full.tsv and cb_extent.tsv when present, font/ and the --env-file as env.txt; AppIcon.icns from the game icon (sips, iconutil); Info.plist with the NACP name and display version, the IPA's bundle ID and the profile's app_category, plus DMTitleID, DMRomfsMarker and DMLanguage for the launcher. The large folders are APFS clones (cp -c) when a clonefile into the app works (the same APFS volume), plain copies otherwise after a free space check. The app is written as <app>.partial and swapped in whole.

The launcher sets the host's environment from the bundle (as the iOS app's main.m does) and runs the host as a child with posix_spawn, never exec: macOS privacy (TCC) attributes a child's file access to the app, while a launcher that hands its process over (a shell script exec'ing dmhost) got EPERM on every open on the external drive, silently, signed or not (found on Echoes of Wisdom's hand-made wrapper). Save and temporary files go to ~/Library/Application Support/nxnative/<title ID>/ (save/, temp/; pso_user.tsv lands beside save/, which is also DM_ROOT and the working folder), the host's output to ~/Library/Logs/nxnative/<title ID>.log (the previous one kept as .prev.log). Environment switches: <Application Support folder>/env.txt, then the bundle's dm/env.txt; neither replaces a variable already set. It forwards SIGTERM, SIGINT and SIGHUP to the host, returns its exit code (128 + the signal when it was killed), and shows an alert (osascript) when the bundle's game data is missing.

Signing: the inner host first, then the bundle, codesign --force --sign <identity>, ad-hoc by default, --mac-sign / MAC_SIGN names an identity; never with the hardened runtime (it refuses the executable memory the host maps for the game's code), so the app cannot be notarized. Finder information on copied files, which codesign refuses, is removed and the signing tried again.

In the script, mac_run is split: mac_host builds the host and the font (the stage "Mac host", for both platforms), mac_run makes the command of --platform mac as before, and mac_app runs pack_app.py (the stage "Mac app", its steps from pack_app.py's step lines); --platform mac-app plans the same number of stages as an IPA build.

New test dm/tools/tests/test_nsp_mac_app.py (written first; on main it fails: no dm/mac/pack_app.py, no --platform mac-app): packs an app from stand-ins with a stand-in host compiled there, and checks the layout, Info.plist, the ad-hoc signature without the runtime flag, the launcher's environment, working folder and log rotation, both env files, the exit code, SIGTERM forwarding, the alert (a stand-in osascript), plain copies, and the script's options and pack_app.py command line for an NVN and a Vulkan game. Checked: every test of dm/tools/tests, dm/ios/tests and dm/gfx/tests, make -C dm/host/tests GAME=010015100B514000 run and dm/ios/tools/compile_check.py pass. Not checked here: an app of a real game (next), a GL game, an app moved to another Mac.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
docs/development.md: a new section "A Mac app" after "A Mac-only build for development": what --platform mac-app builds and where the app goes (-o), the bundle's layout, APFS clones or copies, where the save, pso_user.tsv, temporary files, env.txt and the log go, signal forwarding and the alert, why the launcher runs the host as a child process (macOS privacy checks on removable volumes: a launcher that exec'ed dmhost got EPERM on every open on the external drive, signed or not), and signing (ad-hoc or --mac-sign, never the hardened runtime, so no notarization). "A Mac-only build for development" no longer says there is no Mac app. The script's examples get one for --platform mac-app --mac-sign, and a line lists the three --platform values. README.md "Pack an IPA": one line pointing at the Mac app.

Docs only; no test ran for this commit.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@stan69b

stan69b commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

Note: #104 also packs a Mac app, and adds a full AppKit front end (menus, preferences, controller mapping) that this PR doesn't have. The two overlap only in the packing and in the script's Mac branch. Packing differences are summed up in my comment on #104. If #104 is merged first, I'll rebase this PR onto it, keep its front end, and agree on one save location.

@stan69b
stan69b marked this pull request as ready for review October 25, 2026 03:03
@v0lumehi

Copy link
Copy Markdown
Contributor

@seedds is the ––platform mac flag needed when merging this? I think I'd rather have the ––platform mac spit out a .app instead of having two arguments

@stan69b

stan69b commented Oct 25, 2026

Copy link
Copy Markdown
Contributor Author

I'll update the PR if you decide you'd rather have this on the existing mac argument instead of a new one. i tend to not change existing arguments when i'm not the creator of a code.

@seedds

seedds commented Oct 25, 2026

Copy link
Copy Markdown
Owner

Integrated into main as ffcd910 and 4213e5e, with review fixes in 7a3b958.

The fixes add a packed module-file inventory so missing binaries or rewriter tables trigger the launcher’s alert before the host starts, and pass alert text as AppleScript arguments so quotes and backslashes in game names work correctly. Regression tests cover both cases, incomplete-module packing, and running a relocated app with the original build folder unavailable.

Validation on the integrated branch: all 50 NSP tests and 4 documentation tests passed, along with a strict launcher compiler check. A relocated Super Mario Galaxy 2 Vulkan app also reached 900 frames and exited cleanly during a 45-second smoke test using isolated saves. That run still reported missing shaders and unsupported graphics features, so it does not establish full visual correctness.

Closing because the changes and fixes are now on main. Thanks for the Mac-app support.

@seedds seedds closed this Oct 25, 2026
ltrdpper pushed a commit to ltrdpper/BananaNative that referenced this pull request Nov 12, 2026
…ative 4:3 option (Game settings › Aspect ratio)' (seedds#150) from FrenklinFish/BananaNative:weave-43only into android

Reviewed-on: https://git.eden-emu.dev/moceure/BananaNative/pulls/150
ltrdpper pushed a commit to ltrdpper/BananaNative that referenced this pull request Nov 12, 2026
…settings, Ocarina of Time on Qualcomm

- Game language: Polish (pl) and Thai (th), from SDK 21's own settings table (sdk+0xc62b5c in Ocarina of Time lists pt-BR, pl, th); the launcher list, the host's DM_LANG mapping and GetAvailableLanguageCodes. Ocarina of Time (`0400486024DEC000`) carries EUpl messages, Donkey Kong Bananza (`040074A01BF12000`) 1.1 EUpl and THth.
- Launcher: one full page per game with tabs Performance (Picture, Speed, Advanced), Game (options, Game language, Controls), Saves and Storage; rows wrap and say what they do; profile options keep their description and say when they need Prepare again.
- Recommended settings per game and phone (game.tsv recommend rows, Recommend.java): a card with Recommended / Custom and tags on the rows; facts from GLES at launcher start before the first readiness check. Ocarina of Time on Qualcomm: system driver, Performance preset, Full vegetation off.
- Resolution presets (res_preset, scene_output rows) and Scene resolution overlays from a game's own dynamic resolution palette (scene_res.py, DM_ROMFS_OVERLAY).
- Qualcomm's own driver: mesh draws through compute by default (full Ocarina of Time foliage; DM_VK_MESH=1 keeps native mesh shading).
- Mesh draws through compute: a draw takes its own record's entry, and prewarm drops mesh / pixel pairings that do not feed each other (see-through on Adreno 830, black-line flicker on Turnip, issue seedds#180).
- Texture serial map: probes past tombstones, live and tombstone counts apart (the table no longer grows with every serial ever registered).
- pack_android.py: a profile with a selected shader set builds that set on the Mac and Windows (issue seedds#178).
- PRs seedds#150, seedds#151, seedds#171 (FrenklinFish) and seedds#156, seedds#163 (Omnicrash) were merged on Forgejo before this update.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants