Skip to content

README points players to NX2Apple at the top; docs/frontends.md says what a front end builds on - #387

Merged
seedds merged 3 commits into
seedds:mainfrom
v0lumehi:frontends
Oct 27, 2026
Merged

seedds merged 3 commits into
seedds:mainfrom
v0lumehi:frontends

Conversation

@v0lumehi

@v0lumehi v0lumehi commented Oct 27, 2026 •

Copy link
Copy Markdown
Contributor

Part of #388 (front ends: one interface between the engine and graphical apps).

Merge order: this builds on #352 (the Mac app carries launcher.json, which the new page describes). Only the last commit is new here: compare.

Problem

Requests and PRs for graphical front ends keep coming in: #104, #244, #264, #332, and #374 today. README already names NX2Apple, a community Mac app that builds games, keeps a library and starts them with their settings. But it's one sentence inside "Pack an IPA", where nobody who is about to build a front end looks. And someone who wants to build one has no page that says what nxnative already offers a front end.

Change

  • README: a tip right under the introduction that points to NX2Apple and to the new page. "Play" gets a line for the Mac: how to start a game's app with other settings than the tested ones (NX2Apple's library, or env.txt in its Application Support folder), and where its log is.
  • docs/frontends.md (new), the interface a front end can rely on without changing nxnative:
    • the NSP script's --progress json events (stage, step, progress, stage_end, say, with their fields) and exit codes;
    • the settings list a built app carries (dm/launcher.json), with Breath of the Wild's real Mac list as the example;
    • how a Mac app takes settings from its environment, the order of env.txt files, where the save and log are;
    • what a front end can't see yet: while a game runs, the host reports only in its log, as text for people. Runtime events a program can read would be the next piece.
  • docs/settings.md links the page from its Mac line.

No code changes. Together with #306 (NX2Apple first in the issue chooser, a "Graphical front ends" section in CONTRIBUTING.md), this should catch people before they start a front end here.

Checked

  • Each event and field against Progress in scripts/build_ipa_from_nsp.py. Exit codes against main(). The settings fields against dm/games/settings.py. The Mac launcher's environment order and paths against dm/mac/launcher.c and A Mac app.
  • The JSON example is generated from Breath of the Wild 1.9.0 (SETTINGS_PLATFORM=mac settings.py), shortened.
  • python3 -m unittest dm/tools/tests/test_docs.py: OK.

The IPA carries dm/launcher.json, the game's settings from settings.tsv,
which the iOS launcher draws its screen from. The Mac app had no such list,
so a Mac front end could not offer a game's settings. The NSP script now
writes the Mac app's list (settings.py with SETTINGS_PLATFORM=mac) and
pack_app.py --settings puts it at Contents/Resources/dm/launcher.json.

The two settings only the iOS front end reads (the frame-rate counter in
front_ios.m, touch feedback in DmGamepad.m) are marked platform:ios, a new
condition in settings.tsv, and left out of the Mac list; build_ipa.sh keeps
the iOS list as it was (ios is the default).
The shader split printed nothing until it ended, so the NSP script showed
the stage as a spinner although shader_split.py knows how many files and
archive ranges it hands to its pool. It now prints 'progress: done/total'
at most twice a second, which split_shaders forwards as the stage's count.

The count is of the jobs finished in any order: pool.map yields in job
order, so counted that way it would stand still behind one slow archive
range while the other workers go on. The jobs are submitted as futures and
the results are still collected in job order, so the tables do not change
(checked against the previous version on Breath of the Wild's packs).
…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 Oct 27, 2026

Copy link
Copy Markdown
Owner

Reviewed after merging #352 as 2a4a1e30da3e6cff437011f118f3d4496a20d3d9. The remaining diff from main to 78b73f3c683652bb1f87de51dba7839fda432cb6 contains only README.md, docs/frontends.md and docs/settings.md (58 insertions, 2 deletions); the #352 commits are ancestors of main.

  • All five GitHub CI checks pass.
  • python3 -m unittest -v dm/tools/tests/test_docs.py: 4 tests, OK.
  • git diff --check origin/main...origin/pr-387: passed.
  • Checked the documented build event fields and exit handling against the NSP script, settings fields against settings.py, and Mac launch environment precedence, signal forwarding, saves and log paths against launcher.c.

The code validation and the explicitly waived full-game shader rebuild are recorded in #352 (comment). This PR adds no further code changes.

@seedds
seedds merged commit 3b5215a into seedds:main Oct 27, 2026
5 checks passed
seedds added a commit that referenced this pull request Oct 27, 2026
Mac launcher metadata inherited the iOS defaults for Metal 4 pipelines
and deferred encoding. A frontend applying those values could disable
the Mac pipeline archive and enable its normally disabled encode thread.
Resolve ios|mac defaults in the shared table before profile macros, and
check both native defaults across profiles with Metal 4 on and off.

Release the shader-progress test's blocked worker directly from the
observed progress line, with bounded failure and executor cleanup.
Document and test argparse's exit 2 and stderr-only error path before
JSON progress starts. Record the metadata finding in the packing
reference and Wonder's note.

Follow-up to #352 and #387.

Co-authored-by: v0lumehi <[email protected]>
@seedds

seedds commented Oct 27, 2026

Copy link
Copy Markdown
Owner

The documentation review follow-up is on main in 6138a54, co-authored with v0lumehi.

docs/frontends.md now documents argument errors: exit code 2, usage/error on stderr, and no JSON events because parsing happens before JSON mode starts. Frontends are told to check the exit status and capture stderr. A subprocess regression test verifies that exact behavior. The settings contract also makes clear that exported defaults are resolved for the app's platform; the Mac default fix and its validation are recorded on #352.

The focused settings/progress/docs run passes all 22 tests, the full tool suite passes 352 tests (16 skipped), and the iOS suite passes 31 tests. The lint/type ratchet and whitespace check pass. The full-game regression waiver is unchanged; no new gameplay pass is claimed.

Xipzer pushed a commit to Xipzer/nxnative that referenced this pull request Oct 27, 2026
README points players to NX2Apple at the top; docs/frontends.md says what a front end builds on
Xipzer pushed a commit to Xipzer/nxnative that referenced this pull request Oct 27, 2026
Mac launcher metadata inherited the iOS defaults for Metal 4 pipelines
and deferred encoding. A frontend applying those values could disable
the Mac pipeline archive and enable its normally disabled encode thread.
Resolve ios|mac defaults in the shared table before profile macros, and
check both native defaults across profiles with Metal 4 on and off.

Release the shader-progress test's blocked worker directly from the
observed progress line, with bounded failure and executor cleanup.
Document and test argparse's exit 2 and stderr-only error path before
JSON progress starts. Record the metadata finding in the packing
reference and Wonder's note.

Follow-up to seedds#352 and seedds#387.

Co-authored-by: v0lumehi <[email protected]>
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
README points players to NX2Apple at the top; docs/frontends.md says what a front end builds on
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
Mac launcher metadata inherited the iOS defaults for Metal 4 pipelines
and deferred encoding. A frontend applying those values could disable
the Mac pipeline archive and enable its normally disabled encode thread.
Resolve ios|mac defaults in the shared table before profile macros, and
check both native defaults across profiles with Metal 4 on and off.

Release the shader-progress test's blocked worker directly from the
observed progress line, with bounded failure and executor cleanup.
Document and test argparse's exit 2 and stderr-only error path before
JSON progress starts. Record the metadata finding in the packing
reference and Wonder's note.

Follow-up to seedds#352 and seedds#387.

Co-authored-by: v0lumehi <[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.

2 participants