Skip to content

Saved choices: one store and one order for every way a game starts (#388) - #431

Merged
seedds merged 1 commit into
mainfrom
mac-saved-choices
Oct 27, 2026
Merged

seedds merged 1 commit into
mainfrom
mac-saved-choices

Conversation

@seedds

@seedds seedds commented Oct 27, 2026

Copy link
Copy Markdown
Owner

Step 3 of #388: one store for a player's choices, read the same way however the game starts.

The problem

A Mac app had no store for a player's choices. Settings chosen in a front end applied only when that front end started the game, and a start from Finder or the Dock used the tested defaults. On the iPhone, DM_LAUNCHER=0 skipped the screen and the saved choices with it.

The change

  • The store is the iPhone app's: launcher.<VAR> strings in the app's preferences domain, its bundle ID (org.nxnative.<title ID>). dm/mac/launcher.c reads it at every start with CFPreferences. A front end writes the same keys, and so would Mac: settings window before the game starts #379's window.
  • Checked when read. pack_app.py copies what launcher.json offers into Info.plist as DMSettings (a choice's options, a toggle's on and off, a range's bounds). A value the build no longer offers, a non-string or an unknown key is ignored and stays saved, so a rebuild with changed settings falls back to its tested default.
  • The order, the first that sets a variable winning: the launch environment, the player's env.txt, the bundle's env.txt, saved choices, the tested defaults. Launch overrides are temporary: the launcher never writes the store.
  • Two separate switches. DM_SAVED_CHOICES=0 (new) starts with the tested defaults and leaves the store as it is, on the Mac and the iPhone. DM_LAUNCHER=0 only skips the iPhone's screen: saved choices now still apply.
  • Docs. docs/frontends.md gets a Saved choices section for front-end authors. docs/development.md, docs/settings.md and docs/env_switches.tsv are updated.

Checked (the list from #388)

test_nsp_mac_app.py packs an app under a throwaway bundle ID (never a real game's domain, removed afterwards) and starts it with a stand-in host:

  • Start without an environment (as from Finder): saved choices are used. A saved DM_LANG wins over the packed language. A value the toggle never takes, and a key no setting has, are ignored.
  • Explicit overrides: a front end's launch environment wins, and the store keeps its value.
  • Env files: the player's env.txt and the bundle's win over a saved choice.
  • DM_SAVED_CHOICES=0: no saved choice is used.
  • A non-string value (defaults write -float) is ignored.
  • Rebuild with changed settings: the app repacked without the 30 fps option ignores the saved 30 and logs why. The other saved choices still hold.

launcher_storage_check.swift checks that on the iPhone DM_LAUNCHER=0 applies saved choices without writing, and that DM_SAVED_CHOICES=0 starts from the defaults and leaves the store untouched when Play is pressed.

Every dm/tools/tests and dm/ios/tests file passes. The lint ratchet finds 0 new findings. The iOS Swift sources typecheck for iPhone, and launcher.c compiles cleanly with -Wall -Wextra.

Not run:

  • A packed real game started from Finder through LaunchServices. The tests run the launcher directly, which reads the same preferences domain.
  • An iPhone build.
  • regress.py: nothing here reaches the shader chain, the host or a game's frames.

For #379

The window can now read and write this store, and should treat a variable that is already set (environment or env.txt) as fixed, as the launcher does.

)

A Mac app had no store for a player's choices: a front end's settings
applied only when that front end started the game, and a start from
Finder or the Dock used the tested defaults. The launcher now reads the
same store the iPhone app keeps: launcher.<VAR> strings in the app's
preferences domain (its bundle ID, org.nxnative.<title ID>), which a
front end or a settings window inside the app writes.

Each saved value is checked against this build's settings, which the
packer copies from launcher.json into Info.plist as DMSettings (a
choice's options, a toggle's on and off, a range's bounds): a value the
build no longer offers, a non-string or an unknown key is ignored and
stays saved, so a rebuild with changed settings falls back to its
tested default. The order, the first that sets a variable winning:
the launch environment, the player's env.txt, the bundle's env.txt,
saved choices, the tested defaults. A front end's launch overrides are
temporary: the launcher never writes the store.

Skipping the screen and ignoring saved choices are separate switches.
DM_SAVED_CHOICES=0 starts with the tested defaults and leaves the store
as it is, on the Mac and the iPhone. DM_LAUNCHER=0 only skips the
iPhone's settings screen: the saved choices now still apply, as #388
agreed (before, it ignored them).

docs/frontends.md, Saved choices, documents the store, the check and
the order. test_nsp_mac_app.py packs an app under a throwaway bundle ID
and checks a start without environment, launch overrides, both env
files, DM_SAVED_CHOICES=0, a non-string value and a rebuild that drops
a saved value; launcher_storage_check.swift checks DM_LAUNCHER=0 and
DM_SAVED_CHOICES=0 on the iPhone's model.

Co-authored-by: v0lumehi <[email protected]>
@seedds
seedds force-pushed the mac-saved-choices branch from feff4dc to 6d1e07b Compare October 27, 2026 14:02
@seedds
seedds merged commit 6d1e07b into main Oct 27, 2026
@seedds
seedds deleted the mac-saved-choices branch October 27, 2026 14:13
seedds added a commit that referenced this pull request Oct 27, 2026
A Mac app now shows its settings in a native window before the host
starts (dm/mac/Launcher.swift, linked into the launcher by pack_app.py
with swiftc), drawn from its launcher.json with the iOS launcher's
model and rows (LauncherSettings.swift, and LauncherRow.swift, moved out
of the iOS launcher to be shared). The settings marked level=basic come
first; the others are under a remembered Advanced settings disclosure,
in the list's usual sections, with Reset to tested defaults. The
render scale shows its size in pixels for the chosen console mode when
the list carries the profile's base size. Play puts the settings into
the environment the host inherits; Quit, Cmd-Q and closing the window
end the app without the game.

The window keeps its choices in the saved-choices store (#431), so a
start from a front end or with the window turned off gets the same
settings. A variable the launch environment or an env file set is
shown fixed and left as it is: the launcher passes the names in
DM_ENV_LAUNCH_KEYS and DM_ENV_FILE_KEYS. DM_LAUNCHER=0, --no-launcher
(open <app> --args --no-launcher) and "Show this window at launch"
turned off skip the window, and the launcher then applies the saved
choices itself; Option at launch shows it again. The window's own
state is window.show and window.advanced, outside the launcher.
namespace a front end resets.

Display mode is a Mac row, 0=Window,1=Fullscreen. front_mac.m now reads
DM_FULLSCREEN by value (any value but 0 is fullscreen), so the row
needs no special empty value that unsets the variable.

Changes from #379: the Mac uses the same sections and labels as the
iPhone instead of its own (one list, one set of names, as #388 agreed);
the level, the base size and the platform split come from the meta
column, render_base and platform:mac already on main; no api field.

Checked: test_launcher_storage compiles the window with the model and
rows and measures the real grouped Form (Basic and Advanced, fitting
and growing from the top edge) and checks Basic/Advanced rows, Display
mode, the size in pixels and launch overrides shown fixed;
test_nsp_mac_app checks the launcher is linked from its C and Swift
sources, the reuse key covers swiftc and the Swift files, and the
launch and env-file keys and --no-launcher with saved choices. A Mario
Wonder Mac app packed by the NSP script showed the window from Finder
(open; 12 settings), and started without it with --no-launcher played
on (2,700 frames presented). Play in the live window was not clicked:
this session cannot send input to it.

Co-authored-by: Suraj Mandal <[email protected]>
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
…#374, seedds#388)

A Mac app now shows its settings in a native window before the host
starts (dm/mac/Launcher.swift, linked into the launcher by pack_app.py
with swiftc), drawn from its launcher.json with the iOS launcher's
model and rows (LauncherSettings.swift, and LauncherRow.swift, moved out
of the iOS launcher to be shared). The settings marked level=basic come
first; the others are under a remembered Advanced settings disclosure,
in the list's usual sections, with Reset to tested defaults. The
render scale shows its size in pixels for the chosen console mode when
the list carries the profile's base size. Play puts the settings into
the environment the host inherits; Quit, Cmd-Q and closing the window
end the app without the game.

The window keeps its choices in the saved-choices store (seedds#431), so a
start from a front end or with the window turned off gets the same
settings. A variable the launch environment or an env file set is
shown fixed and left as it is: the launcher passes the names in
DM_ENV_LAUNCH_KEYS and DM_ENV_FILE_KEYS. DM_LAUNCHER=0, --no-launcher
(open <app> --args --no-launcher) and "Show this window at launch"
turned off skip the window, and the launcher then applies the saved
choices itself; Option at launch shows it again. The window's own
state is window.show and window.advanced, outside the launcher.
namespace a front end resets.

Display mode is a Mac row, 0=Window,1=Fullscreen. front_mac.m now reads
DM_FULLSCREEN by value (any value but 0 is fullscreen), so the row
needs no special empty value that unsets the variable.

Changes from seedds#379: the Mac uses the same sections and labels as the
iPhone instead of its own (one list, one set of names, as seedds#388 agreed);
the level, the base size and the platform split come from the meta
column, render_base and platform:mac already on main; no api field.

Checked: test_launcher_storage compiles the window with the model and
rows and measures the real grouped Form (Basic and Advanced, fitting
and growing from the top edge) and checks Basic/Advanced rows, Display
mode, the size in pixels and launch overrides shown fixed;
test_nsp_mac_app checks the launcher is linked from its C and Swift
sources, the reuse key covers swiftc and the Swift files, and the
launch and env-file keys and --no-launcher with saved choices. A Mario
Wonder Mac app packed by the NSP script showed the window from Finder
(open; 12 settings), and started without it with --no-launcher played
on (2,700 frames presented). Play in the live window was not clicked:
this session cannot send input to it.

Co-authored-by: Suraj Mandal <[email protected]>
chgpalmer added a commit to chgpalmer/nxnative that referenced this pull request Nov 17, 2026
The Mac keyboard's keys were fixed in front_mac.m (key_bit, on_key), and
issues seedds#1216, seedds#2572 and seedds#2346 ask to change them. They now come from a map,
dm/host/keymap.h, a pure header with tests (t_keymap), as pad_hid.h and
ctrl_prompt.h are: each key presses a button, a stick direction or the shake,
a target may have several keys, and the default map is the previous layout,
Shift + arrows as the right stick included.

How it is built, and where each choice comes from:

- Keys are macOS virtual key codes (Carbon's kVK_*), as front_mac.m read them
  before: a binding is a key's place, so AZERTY's ZQSD works as WASD. They are
  named by the US layout (DM_KEYMAP=A=space RUP=up DUP=1), or #<code>.
- Shift, Control and Option are keys too. macOS reports them as flagsChanged,
  not key downs, so a modifier event is read with the device-dependent
  NX_DEVICE*KEYMASK bits (the trap seedds#1216's reporter names); Command (the
  menus'), Caps Lock and fn are never bound.
- A binding can be a chord, as in a game's own keybinding screen: hold
  Shift, Control or Option and press a key (shift+up; shown as the menus'
  symbols). A key pressed with a modifier held is the chord's target when
  the chord is bound, else the key's own, so ZL on Shift with the D-pad on 1
  is still ZL + D-pad up. Shift + arrows as the right stick (4de40e6, for
  Donkey Kong Bananza's camera) was a fixed branch of on_key; it is now the
  default map's RLEFT=shift+left ... RDOWN=shift+down, shown and editable
  like any other binding. Either side's modifier makes the chord.
- A key goes back up as it went down, and each target counts the keys that
  hold it: two keys on one target, or Shift let go before an arrow, release
  correctly. These are the two faults reviewers found in PR seedds#386's per-function
  bits (jonpage0, akratch on seedds#386).
- Stored as the saved choice launcher.DM_KEYMAP, the store and precedence
  decided on seedds#388 and landed with seedds#431 (launch environment, env.txt, saved
  choices, defaults; DM_SAVED_CHOICES=0). As seedds#386 proposed, the launcher checks
  it with the host's own parser and ignores a value the host would not take
  whole. PR seedds#386's form, <name>=<key code>,... with its names, reads too, so a
  value NX2Apple's patch of seedds#386 saved still applies.
- Remapping happens where it can be tested: Window > Keyboard Map... (Cmd-Shift-K)
  shows the map beside the running game, a click then a key press binds it
  (Esc stops; right-click: No Key, or Add Key... for another key as well),
  and the change applies at once and is saved. The panel never
  takes the key window, as the Cheats panel. The settings window's Keyboard
  section, right below Controls, opens the same map before the game.
- Presets are INI files, as controller profiles are in other emulators (one
  file per profile): the original layout, then
  ~/Library/Application Support/nxnative/keymaps/*.ini by their Name line.
  Save as Preset... writes one; they can be written by hand. The Preset
  pop-up at the top of the map names the preset the map is (Custom once
  changed), as emulators show the active profile.

keyboard_mac.h holds the keyboard part of the front end, as home_quit_mac.h
and pad_hid_mac.h hold theirs: front_mac.m's key monitor hands it each key of
the game window that is no menu shortcut, and input_release, the controller
applet's prompt and the text box let go of what it holds. The prompt takes
the map's keys of A and B as well as Return and Escape. pack_app.py rebuilds
the launcher when keymap.h changes.

Tests: t_keymap (71 checks, ASan and UBSan: the default map, chords (either
side, Control and Option, a key with no chord its own, a bound Shift both a
button and a chord's modifier, Shift let go first), repeats, two keys on one
target, errors, the full form and keymap files read back, the presets
folder, seedds#386's form); test_nsp_mac_app with a new test_saved_keymap (a real
launcher: the saved choice, a launch override, DM_SAVED_CHOICES=0, a value
the host rejects, seedds#386's form); test_docs, test_env_switches, test_usage,
test_launcher_settings; lint_c.py tidy with LLVM 23: no findings.
scripts/regress.py was not run: nothing below the Mac front end changes, and
its scripted input (DM_KEYS, DM_CTL) takes another path.

Played on a MacBook Pro (M3 Pro, 18 GB, macOS 27.2.1) with Ocarina of Time
(0400486024DEC000, v131072), handheld and docked: the map, the panel, presets
and the saved choice across starts; no added input lag noticed. The host was
built from this branch's front-end files on the commit the app's shader
library was packed with, since main's shader chain has moved on;
front_mac.m's keyboard code is the same on both.

Covers the keyboard part of PR seedds#386; DM_PAD_MAP (controller buttons) is not
touched.

Front-ends: new: launcher.DM_KEYMAP is a saved choice, checked by the host's parser (docs/frontends.md, Saved choices)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
chgpalmer added a commit to chgpalmer/nxnative that referenced this pull request Nov 18, 2026
The Mac keyboard's keys were fixed in front_mac.m (key_bit, on_key), and
issues seedds#1216, seedds#2572 and seedds#2346 ask to change them. They now come from a map,
dm/host/keymap.h, a pure header with tests (t_keymap), as pad_hid.h and
ctrl_prompt.h are: each key presses a button, a stick direction or the shake,
a target may have several keys, and the default map is the previous layout,
Shift + arrows as the right stick included.

How it is built, and where each choice comes from:

- Keys are macOS virtual key codes (Carbon's kVK_*), as front_mac.m read them
  before: a binding is a key's place, so AZERTY's ZQSD works as WASD. They are
  named by the US layout (DM_KEYMAP=A=space RUP=up DUP=1), or #<code>.
- Shift, Control and Option are keys too. macOS reports them as flagsChanged,
  not key downs, so a modifier event is read with the device-dependent
  NX_DEVICE*KEYMASK bits (the trap seedds#1216's reporter names); Command (the
  menus'), Caps Lock and fn are never bound.
- A binding can be a chord, as in a game's own keybinding screen: hold
  Shift, Control or Option and press a key (shift+up; shown as the menus'
  symbols). A key pressed with a modifier held is the chord's target when
  the chord is bound, else the key's own, so ZL on Shift with the D-pad on 1
  is still ZL + D-pad up. Shift + arrows as the right stick (4de40e6, for
  Donkey Kong Bananza's camera) was a fixed branch of on_key; it is now the
  default map's RLEFT=shift+left ... RDOWN=shift+down, shown and editable
  like any other binding. Either side's modifier makes the chord.
- A key goes back up as it went down, and each target counts the keys that
  hold it: two keys on one target, or Shift let go before an arrow, release
  correctly. These are the two faults reviewers found in PR seedds#386's per-function
  bits (jonpage0, akratch on seedds#386).
- Stored as the saved choice launcher.DM_KEYMAP, the store and precedence
  decided on seedds#388 and landed with seedds#431 (launch environment, env.txt, saved
  choices, defaults; DM_SAVED_CHOICES=0). As seedds#386 proposed, the launcher checks
  it with the host's own parser and ignores a value the host would not take
  whole. PR seedds#386's form, <name>=<key code>,... with its names, reads too, so a
  value NX2Apple's patch of seedds#386 saved still applies.
- Remapping happens where it can be tested: Window > Keyboard Map... (Cmd-Shift-K)
  shows the map beside the running game, a click then a key press binds it
  (Esc stops; right-click: No Key, or Add Key... for another key as well),
  and the change applies at once and is saved. The panel never
  takes the key window, as the Cheats panel. The settings window's Keyboard
  section, right below Controls, opens the same map before the game.
- Presets are INI files, as controller profiles are in other emulators (one
  file per profile): the original layout, then
  ~/Library/Application Support/nxnative/keymaps/*.ini by their Name line.
  Save as Preset... writes one; they can be written by hand. The Preset
  pop-up at the top of the map names the preset the map is (Custom once
  changed), as emulators show the active profile.

keyboard_mac.h holds the keyboard part of the front end, as home_quit_mac.h
and pad_hid_mac.h hold theirs: front_mac.m's key monitor hands it each key of
the game window that is no menu shortcut, and input_release, the controller
applet's prompt and the text box let go of what it holds. The prompt takes
the map's keys of A and B as well as Return and Escape. pack_app.py rebuilds
the launcher when keymap.h changes.

Tests: t_keymap (71 checks, ASan and UBSan: the default map, chords (either
side, Control and Option, a key with no chord its own, a bound Shift both a
button and a chord's modifier, Shift let go first), repeats, two keys on one
target, errors, the full form and keymap files read back, the presets
folder, seedds#386's form); test_nsp_mac_app with a new test_saved_keymap (a real
launcher: the saved choice, a launch override, DM_SAVED_CHOICES=0, a value
the host rejects, seedds#386's form); test_docs, test_env_switches, test_usage,
test_launcher_settings; lint_c.py tidy with LLVM 23: no findings.
scripts/regress.py was not run: nothing below the Mac front end changes, and
its scripted input (DM_KEYS, DM_CTL) takes another path.

Played on a MacBook Pro (M3 Pro, 18 GB, macOS 27.2.1) with Ocarina of Time
(0400486024DEC000, v131072), handheld and docked: the map, the panel, presets
and the saved choice across starts; no added input lag noticed. The host was
built from this branch's front-end files on the commit the app's shader
library was packed with, since main's shader chain has moved on;
front_mac.m's keyboard code is the same on both.

Covers the keyboard part of PR seedds#386; DM_PAD_MAP (controller buttons) is not
touched.

Front-ends: new: launcher.DM_KEYMAP is a saved choice, checked by the host's parser (docs/frontends.md, Saved choices)

Co-Authored-By: Claude Opus 5.5 <[email protected]>
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.

1 participant