Skip to content

Mac: native AppKit app bundle, preferences, and controller mapping - #104

Closed
jamessturges wants to merge 1 commit into
seedds:mainfrom
jamessturges:feat/macos-app-bundle
Closed

jamessturges wants to merge 1 commit into
seedds:mainfrom
jamessturges:feat/macos-app-bundle

Conversation

@jamessturges

@jamessturges jamessturges commented Oct 24, 2026 •

Copy link
Copy Markdown

Before this, --platform mac (#82) compiled the host and printed a terminal command with ten environment variables and paths pointing into the build directory. The game had to be run from the shell, saves stayed in <id>_build/run/save, logs went to terminal stdout, keyboard controls were fixed to a single hardcoded layout, and the window had no standard macOS menu bar or settings interface.

build_ipa_from_nsp.py --platform mac now packages a <Game Name>.app bundle via dm/tools/pack_mac_app.py:

  • Packaging: generates multi-resolution AppIcon.icns from icon.jpg using sips and iconutil, writes Info.plist (LSSupportsGameMode, NSHighResolutionCapable, category games), and ad-hoc signs with codesign. --mode thin (default) symlinks RomFS and the MSL cache into Contents/Resources/ so repacking takes two seconds and negligible disk space; --mode standalone copies everything for a portable app.
  • Bundle bootstrap: front_mac_bundle_setup (hooked in main.c before host_preload; inline no-op on iOS) detects when launched from an app bundle without arguments (open Game.app or Finder). It discovers romfs, msl, font, shader_map.tsv, and points the guest module loader to Contents/Resources/dm.
  • System paths: save data defaults to ~/Library/Application Support/NxNative/<Game Name>/save/ (overrideable via launcher.DM_CUSTOM_SAVE), stdout/stderr rotate to ~/Library/Logs/NxNative/<Game Name>.log and <Game Name>.prev.log, temporary files go to ~/Library/Caches/NxNative/<Game Name>/temp/, and screenshots (⌘S / F12) write to ~/Pictures/NxNative/<Game Name>/. File menu actions allow revealing the save folder in Finder, viewing the log, and exporting/restoring save backups (.zip).
  • Menu bar & Settings: AppKit menus for File, Game, Audio, View, and Controllers. Supports dynamic docked/handheld switching (dm_set_opmode), mute/volume, window scale presets (1.0x, 1.5x, 2.0x, 3.0x), Metal HUD toggle, Player 1–4 device mapping (Game Controller, Keyboard, and None for P2–P4; P1 is always active and falls back to keyboard if a controller disconnects), Core Haptics integration, and Nintendo vs Xbox button layouts. Preferences (⌘,) provides a clean settings panel with live keyboard remapping persisted in NSUserDefaults. Window tabbing is explicitly disallowed (NSWindowTabbingModeDisallowed). Target Frame Rate and Render Scale menus are dynamically hidden when unsupported by the game profile.
  • Supersampling: loader.c raises the DM_RENDER_SCALE clamp ceiling on macOS from 1.0 to 2.0, keeping the 1.0 clamp on iOS.
  • Compatibility: fixed syntax errors in scripts/build_ipa_from_nsp.py where nested quotes in f-strings broke on Python < 3.12.
image image

Checked:

  • Host unit tests (make -C dm/host/tests run): all test suites passed with 0 failures (including t_touch, t_oe, t_fs, t_audio, t_hid, t_haptics, t_haptics_apple, t_swkbd).
  • Tool and pipeline tests: dm/tools/tests 46 of 46 passed (including new AppBundle tests in test_nsp_mac.py verifying --mode thin asset symlinks, standalone copies, and bundle structures).
  • App bundle packaging & runtime:
    • Packaged Metroid Dread (010093801237C000) .app bundle via pack_mac_app.py --mode thin.
    • Booted cleanly to the title screen and intro loop at 60 fps (2560x1440), audio rendered through AudioUnit, stdout redirected to ~/Library/Logs/NxNative/, and menu toggles functioned smoothly without dropping frames.
  • CLI / windowless regression check: running dmhost directly with existing CLI arguments and environment variables continues to behave identically.

@jamessturges
jamessturges force-pushed the feat/macos-app-bundle branch 2 times, most recently from ce8400e to 0f77a00 Compare October 24, 2026 04:12
@jamessturges jamessturges changed the title feat(macos): native AppKit app bundle, preferences, and controller mapping Mac: native AppKit app bundle, preferences, and controller mapping Oct 24, 2026
@jamessturges
jamessturges force-pushed the feat/macos-app-bundle branch from 0f77a00 to 1fc1ca5 Compare October 24, 2026 04:24
@jamessturges
jamessturges marked this pull request as ready for review October 24, 2026 04:24
@jamessturges

Copy link
Copy Markdown
Author

Hope you don't mind me barging in here and submitting a PR. I just wanted the Mac experience to be a little more polished and thought I'd see if you might like to have the results upstream. I tried to keep it clean, but if there's anything against best practices, apologies in advance :)

seedds added a commit that referenced this pull request Oct 24, 2026
…ral, found on Luigi's Mansion 3): no blending on integer targets, primitive restart in fan and quad expansion, partial depth-stencil clears, every name of an upgraded texture, the SDK's AudioOut fields. nvn_mtl.m pso_desc (#105): an integer colour target took the game's blend enable, and Metal refuses such a pipeline with an assertion even without the API validation layer (checked on this Mac); Maxwell ignores blending on integer targets, so it is off for them. draw (#110): indexed triangle fans and quads expanded on the CPU read the restart index as a vertex and joined the polygons across it, and the extra triangles cleared parts of Luigi's Mansion 3's cached shadow depth; nvn_primitive.h ends a polygon at the restart index (compared before the base vertex), at most as many triangles as before. OP_CLEAR_DS (#108): a depth-stencil clear whose scissor does not cover the target, or whose stencil mask is partial, cleared the whole target before the first draw, and a partial stencil mask did so in a pass too; both are drawn as a triangle now (clear_ds_tri), full clears stay load actions. Logs on the T7 show who takes the new path: Tears of the Kingdom clears 8x8 tiles of a 64x64 depth target (each clear wiped the whole target), AI: THE SOMNIUM FILES clears 1280x720 of a 1920x1080 one. tex_upgrade (#107): a texture recreated to add a usage replaced only the asking serial and one sharing-table entry, so other serials on the same storage read the old copy; every entry in g_by_serial, g_ghost and g_alias now moves to the new texture in place, g_alias_set follows, and the old one is retired after the submissions that used it. hle_audio.c (#109, reworked): the host left the guest AudioOut zero, and middleware that checks its first word before Stop / Close skipped the close, freed its PCM and the host's consumer read freed memory (SIGBUS on resume in Luigi's Mansion 3). The PR wrote 1 and cleared it on close; the SDK's OpenAudioOut (SDK 8, 12, 18 and 20 checked) writes sample rate, channel count, sample format and state at +0 / +4 / +8 / +0xc, its getters load from there, and CloseAudioOut only sets the state to stopped, so the host now writes the same (au_info). New tests t_integer_blend (63 checks), t_primitive_restart (37), t_clear_ds (43), t_upgrade_alias (10) in the gfx run list, and an AudioOut fields and lifetime case in t_audio (12 guarded open / close / unmap / resume cycles, silent sink and real output). Checked: the four new tests pass under Metal validation; every other gfx test gives the same result as on main (t_fuse_check, t_reorder_chain, t_defer_chain, t_mip_extent, t_rt_range_ro and t_rt_range fail the same cases on both; t_refl finds no reflection samples in this checkout's shader cache); the host unit tests pass; on the Mac host for 90 s from boot, against main built the same way: Breath of the Wild over the title, 60 fps and the same red lines; AI: THE SOMNIUM FILES (shaders built by the NSP script on this chain), whose 1280x720 depth clears at the start of a pass now take the triangle path too (from pass 119), 60 fps, no red line, 5 long frames against 12. Not taken from this batch: #106 (the stencil-only view of a depth-stencil texture works without format-view usage; only the validation layer asks for it, and the PR would put that usage on every depth-stencil buffer), #111 (an opt-in draft with no memory saving shown), #104 (Mac app bundle)

Co-authored-by: João Karalkovas <[email protected]>
@v0lumehi

Copy link
Copy Markdown
Contributor

Love it, could have implemented something like that as well when doing the implementation for controller support

@jamessturges

Copy link
Copy Markdown
Author

Rebased cleanly on latest main (399fd2c), resolved conflicts, and polished the branch down to a single clean commit:

  • Integrated with upstream swkbd input-release and minimum character verification logic (g_swkbd_min_chars) in front_mac.m.
  • Omitted already-merged upstream changes from our diff (such as the hle_audren nested open fix taken in fc6c0a2), keeping the diff tightly scoped to macOS app bundle packaging, menu bar, preferences, and controller mapping.
  • Cleaned up controller assignment handling: Player 1 has no 'None' option and automatically falls back to keyboard if a controller disconnects so the player is never locked out; Players 2–4 use 'None' when unassigned.
  • Full quality pass: stripped noisy divider comments, restored repo-level .gitignore byte-for-byte, and verified all 46 tool tests (dm/tools/tests) and all host unit test suites pass cleanly with 0 failures.

…pping

Package a native macOS .app bundle from build_ipa_from_nsp.py via
dm/tools/pack_mac_app.py (--mode thin symlinking RomFS and MSL shaders for rapid
re-runs, --mode standalone for self-contained bundles) with icon generation
via sips and iconutil.

front_mac.m enhancements:
- front_mac_bundle_setup auto-configures paths, launcher settings, and guest
  loader targets when launched from an app bundle.
- Standard macOS paths for save data (~/Library/Application Support/NxNative/<Game>/save),
  logs (~/Library/Logs/NxNative/<Game>.log), caches, and screenshots (~/Pictures/NxNative).
- Save archive export and restore (.zip) with safety backups.
- Native AppKit menu bar: File, Game, Audio, View, Controllers.
- Player 1–4 device mapping (Game Controller, Keyboard, None) with
  Nintendo vs Xbox button layout options and Core Haptics integration.
- Dynamic docked/handheld switching (dm_set_opmode), Metal Performance HUD toggle,
  and window scale presets (1.0x-3.0x).
- Target Frame Rate and Render Scale menus dynamically hidden when unsupported
  by the title's profile.
- Preferences window (Cmd+,) with interactive keyboard remapping persisted in NSUserDefaults.
- Fullscreen mode, screenshot capture (Cmd+S / F12), audio volume and mute controls.

Host and pipeline:
- loader.c: raise DM_RENDER_SCALE clamp on macOS from 1.0 to 2.0 for supersampling.
@jamessturges
jamessturges force-pushed the feat/macos-app-bundle branch from 668ba4d to 48c615d Compare October 25, 2026 02:37
@jamessturges

Copy link
Copy Markdown
Author

Rebased onto latest main (7afd90b). Resolved the small conflict in docs/development.md alongside upstream's new Core Haptics notes, and verified all 55 tool tests and host unit tests pass cleanly.

@stan69b

stan69b commented Oct 25, 2026

Copy link
Copy Markdown
Contributor

Hi, I opened #150, which overlaps with the packaging part of this PR. Most of the two looks complementary to me: your menus, preferences and controller mapping in front_mac.m don't exist in #150, which only packs and launches the game.

On the packaging, some things I ran into that may be worth comparing:

  • The host reads c1_full.tsv, cb_extent.tsv and pso_manifest.tsv from the folder that holds shader_map.tsv. Here only shader_map.tsv goes into Resources/dm, so the app runs without the c1 guard, the uniform extents and the prewarm list.
  • Standalone mode copies all of shader/cache, including cas/, which the host never reads. A self-contained Mac app of a game (--platform mac-app) #150 copies only b-<chain>/ and uses APFS clones (cp -c) when it can.
  • With the game files on an external drive, a launcher script that exec'ed dmhost got EPERM on every open (macOS privacy checks, no prompt). A compiled launcher that spawns dmhost as a child fixed it. I haven't tested whether dmhost as the main executable runs into the same thing.

One way to fit them together would be to keep this PR's front end and #150's packing, with one save location (Application Support/nxnative/<title ID> vs NxNative/<Game Name>). Happy to rebase #150 onto this one if it goes in first.

@varyform

Copy link
Copy Markdown
Contributor

Cool... this one is better than mine :)
image

razzamatazm pushed a commit to razzamatazm/nxnative that referenced this pull request Oct 26, 2026
…from PR seedds#104)

The front end of PR seedds#104 (jamessturges) on top of the Mac app (--platform mac-app); its packer and
bundle bootstrap are left out, since dm/mac/pack_app.py and dm/mac/launcher.c already pack and launch the game.
front_mac.m: File (screenshot of the next frame to ~/Pictures/nxnative/<game name>/, the save in Finder,
save backup export and restore as a zip, the log), Game (pause, docked / handheld at once), Audio (mute,
mute in background), View (fullscreen, window sizes, Apple's performance HUD), Controllers (each player's
controller or the keyboard, buttons by position or by label). Settings (Cmd-,): the game's player settings
from dm/games/settings.tsv (packed as dm/launcher.json, applied before main), the controller layout and
stick dead zone, a key map kept in NSUserDefaults, and the save. pad_slots.h pad_slot_put moves a holder
to another player (t_hid covers it). The launcher passes DM_ENV_FILE_KEYS, so a setting an env file sets
is shown but kept. settings.tsv: platform:<ios|mac> condition; touch feedback is the iPhone's only.
Left out: the 2.0 render-scale ceiling (the BotW stub refuses factors above 1.0: the per-frame texture
pool's size is unknown).

Checked: the Mac host builds (Mario's profile), host unit tests pass, dm/tools/tests 99 passed; 30XX packed
as a Mac app boots to the title, its menus, screenshot, console mode and Settings work.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01PmHzWqfuDHu31tEDuCehkS
seedds pushed a commit that referenced this pull request Oct 27, 2026
…what a front end builds on

People keep proposing or building graphical front ends here (#104, #244,
#264, #332, #374), although README names NX2Apple, a community app that
builds games, keeps a library and starts them with their settings. That
mention is one sentence in "Pack an IPA". README now says it in a tip right
under the introduction, and "Play" says how to start a Mac app with other
settings than the tested ones (NX2Apple's library, or the env.txt in its
Application Support folder) and where its log is.

docs/frontends.md describes what such an app can rely on without changing
nxnative: the NSP script's --progress json events and exit codes, the
settings list a built app carries (dm/launcher.json, with Breath of the
Wild's list as the example), how a Mac app takes settings from its
environment and where its save and log are. It also says what a front end
cannot see yet: while a game runs, the host reports only in its log, as
text for people.
v0lumehi added a commit to v0lumehi/nxnative that referenced this pull request Oct 27, 2026
…n issue

Requests and PRs for graphical front ends keep coming in (seedds#104, seedds#244, seedds#264,
seedds#332, seedds#374), although README names NX2Apple, a community app that packs
games, keeps a library and starts them with their settings. The mention sits
in "Pack an IPA", where someone about to build a front end does not look.

The issue chooser now lists NX2Apple first among its links, so it shows
before any form opens. A feature request form says that a new front end is a
project of its own and what is welcome here instead: the piece a front end
needs from nxnative. CONTRIBUTING.md has a section on graphical front ends:
the interfaces one builds on (the NSP script's --progress json events, the
settings list a built app carries, environment switches), and that the
settings screen inside the iPhone app is part of nxnative.
@v0lumehi

Copy link
Copy Markdown
Contributor

Heads-up: seedds asked in #388 to settle one settings schema and one store before the Mac UIs grow, and he plans to review this PR's menus, controller assignment and remapping as smaller changes on top of the current packaging. I posted a proposal there (#388 (comment)): nxnative provides the model (launcher.json, the controls as data, one per-game store), and every UI is a view of it, this one included. Would you split this PR along those lines: the app bundle and preferences on one side, the mapping UI on the shared store on the other? Happy to help.

@jamessturges

Copy link
Copy Markdown
Author

@v0lumehi I see there’s quite the flurry of movement on this today, which is very exciting to see! I’m happy to help where I can, for whatever bit still belongs in the product from my PR. I know things are moving quickly, and I may not be able to get to this before the weekend. If, in the meantime, you or someone else wants to do the splitting work, as long as I still get attribution, that’s great. If it can wait until the weekend, and I can get clear direction on what you and the maintainer would like to see, I’ll handle it then. Thanks for remembering this, and it was good to see you in the wild on Andrew Tsai’s comment section!

@v0lumehi

Copy link
Copy Markdown
Contributor

@jamessturges thanks, and no rush: the weekend is fine. Since my heads-up, main has taken over the packaging and the preferences: the Mac app is a bundle with a settings window before the game starts (#379), and every way a game starts reads one saved-choices store (#431). The controls as data are in #386 (launcher.DM_KEYMAP and launcher.DM_PAD_MAP). What's still yours, as two small PRs:

  1. A controller mapping UI (the Player 1–4 devices, the keyboard and pad remapping) that writes those two keys, ideally as a Controls part of Mac: settings window before the game starts #379's window. It builds on Mac front end: DM_KEYMAP and DM_PAD_MAP move buttons to other keys and controller buttons #386, so after it lands or on its branch.
  2. The remaining menus (docked/handheld, volume, window scale, the Metal HUD, screenshots, save backup export and restore) on the current packaging.

The rest of this PR is covered by main now. If you'd rather someone else does the split, say so: those commits will carry Co-authored-by: jamessturges.

jamessturges added a commit to jamessturges/nxnative that referenced this pull request Nov 2, 2026
Extract the remaining menu actions from seedds#104 without its superseded packaging or controls UI. Keep console mode in the shared saved choices and mute output independently of lifecycle suspension.

Use checked save backups with recovery copies and restore only after the supervising launcher has waited for the host. Add AppKit, audio callback, save rollback and launcher handoff coverage.
@jamessturges

Copy link
Copy Markdown
Author

@v0lumehi I’ve picked up the split you suggested and opened #921 for the remaining Mac menus, on a fresh branch based on current main.

It includes docked/handheld switching, a volume slider and mute controls, window scaling, screenshots, save/log access, and save backup export/restore. It also restores standard App/Window actions and exposes frame-rate/render-scale choices where the existing settings and runtime support them. For the Metal HUD, it keeps the existing startup setting and Apple’s native live menu.

The controller work is deferred to a separate Controls PR: Player 1–4 device assignment, keyboard remapping, and controller-button remapping. I’m waiting for #386 to land so that work can build on the shared input model and saved-choice keys (launcher.DM_KEYMAP and launcher.DM_PAD_MAP), with the UI integrated into the existing startup window.

The packaging and preferences implementation from this PR is already covered upstream. Manual pause/resume and cache deletion remain outside the menus PR.

I’ve tested the menu extraction with Metroid Dread and automated fixtures; the validation details are in #921. I’ll leave #104 open while the remaining work is accounted for, then close it as superseded with links to the replacement PRs.

@github-actions github-actions Bot added host The Horizon host: SVCs, services, threads, memory (dm/host) packing Building an IPA or a Mac app: the NSP script, extraction, the shader split, the packers mac The Mac front end and app (dm/mac, front_mac.m) tools Tools and scripts (dm/tools, scripts) docs Documentation labels Nov 3, 2026
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
…eedds#109 and seedds#110 (general, found on Luigi's Mansion 3): no blending on integer targets, primitive restart in fan and quad expansion, partial depth-stencil clears, every name of an upgraded texture, the SDK's AudioOut fields. nvn_mtl.m pso_desc (seedds#105): an integer colour target took the game's blend enable, and Metal refuses such a pipeline with an assertion even without the API validation layer (checked on this Mac); Maxwell ignores blending on integer targets, so it is off for them. draw (seedds#110): indexed triangle fans and quads expanded on the CPU read the restart index as a vertex and joined the polygons across it, and the extra triangles cleared parts of Luigi's Mansion 3's cached shadow depth; nvn_primitive.h ends a polygon at the restart index (compared before the base vertex), at most as many triangles as before. OP_CLEAR_DS (seedds#108): a depth-stencil clear whose scissor does not cover the target, or whose stencil mask is partial, cleared the whole target before the first draw, and a partial stencil mask did so in a pass too; both are drawn as a triangle now (clear_ds_tri), full clears stay load actions. Logs on the T7 show who takes the new path: Tears of the Kingdom clears 8x8 tiles of a 64x64 depth target (each clear wiped the whole target), AI: THE SOMNIUM FILES clears 1280x720 of a 1920x1080 one. tex_upgrade (seedds#107): a texture recreated to add a usage replaced only the asking serial and one sharing-table entry, so other serials on the same storage read the old copy; every entry in g_by_serial, g_ghost and g_alias now moves to the new texture in place, g_alias_set follows, and the old one is retired after the submissions that used it. hle_audio.c (seedds#109, reworked): the host left the guest AudioOut zero, and middleware that checks its first word before Stop / Close skipped the close, freed its PCM and the host's consumer read freed memory (SIGBUS on resume in Luigi's Mansion 3). The PR wrote 1 and cleared it on close; the SDK's OpenAudioOut (SDK 8, 12, 18 and 20 checked) writes sample rate, channel count, sample format and state at +0 / +4 / +8 / +0xc, its getters load from there, and CloseAudioOut only sets the state to stopped, so the host now writes the same (au_info). New tests t_integer_blend (63 checks), t_primitive_restart (37), t_clear_ds (43), t_upgrade_alias (10) in the gfx run list, and an AudioOut fields and lifetime case in t_audio (12 guarded open / close / unmap / resume cycles, silent sink and real output). Checked: the four new tests pass under Metal validation; every other gfx test gives the same result as on main (t_fuse_check, t_reorder_chain, t_defer_chain, t_mip_extent, t_rt_range_ro and t_rt_range fail the same cases on both; t_refl finds no reflection samples in this checkout's shader cache); the host unit tests pass; on the Mac host for 90 s from boot, against main built the same way: Breath of the Wild over the title, 60 fps and the same red lines; AI: THE SOMNIUM FILES (shaders built by the NSP script on this chain), whose 1280x720 depth clears at the start of a pass now take the triangle path too (from pass 119), 60 fps, no red line, 5 long frames against 12. Not taken from this batch: seedds#106 (the stencil-only view of a depth-stencil texture works without format-view usage; only the validation layer asks for it, and the PR would put that usage on every depth-stencil buffer), seedds#111 (an opt-in draft with no memory saving shown), seedds#104 (Mac app bundle)

Co-authored-by: João Karalkovas <[email protected]>
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
…what a front end builds on

People keep proposing or building graphical front ends here (seedds#104, seedds#244,
seedds#264, seedds#332, seedds#374), although README names NX2Apple, a community app that
builds games, keeps a library and starts them with their settings. That
mention is one sentence in "Pack an IPA". README now says it in a tip right
under the introduction, and "Play" says how to start a Mac app with other
settings than the tested ones (NX2Apple's library, or the env.txt in its
Application Support folder) and where its log is.

docs/frontends.md describes what such an app can rely on without changing
nxnative: the NSP script's --progress json events and exit codes, the
settings list a built app carries (dm/launcher.json, with Breath of the
Wild's list as the example), how a Mac app takes settings from its
environment and where its save and log are. It also says what a front end
cannot see yet: while a game runs, the host reports only in its log, as
text for people.
@seedds

seedds commented Nov 15, 2026

Copy link
Copy Markdown
Owner

Closing this umbrella. As the 2 November reply says, its parts have moved. The app bundle and preferences window are on main (#379, #431). The Mac menus, screenshots and save management are in #921. Controller mapping as data is #386, and the Steam Controller is #221. Closing this doesn't mean those controls have landed: #921, #386 and #221 are still open and get reviewed on their own. Thanks for starting this, and for splitting it up.

@seedds seedds closed this Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation host The Horizon host: SVCs, services, threads, memory (dm/host) mac The Mac front end and app (dm/mac, front_mac.m) packing Building an IPA or a Mac app: the NSP script, extraction, the shader split, the packers tools Tools and scripts (dm/tools, scripts)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants