Skip to content

launcher.json schema 1: a meta column for optional fields, and a JSON Schema for front ends (draft for #388) - #418

Closed
v0lumehi wants to merge 3 commits into
seedds:mainfrom
v0lumehi:settings-meta-schema
Closed

v0lumehi wants to merge 3 commits into
seedds:mainfrom
v0lumehi:settings-meta-schema

Conversation

@v0lumehi

Copy link
Copy Markdown
Contributor

Draft for the discussion in #388. Not for merge until we agree on the shape there.

This is section 1 of the proposal as code, so we can discuss a concrete diff.

The problem

#355 (needs) and #399 (level) both claim settings.tsv's ninth column, and #379 brings its own metadata.

The change

  • The ninth column becomes one optional meta column of key=value pairs separated by ;. For example level=basic or needs=DM_RUMBLE=1. Any number of optional fields fit.

  • settings.py's META lists the allowed keys, each with the pattern its value must match. settings.py stops when:

    • a key is unknown;
    • a key appears twice;
    • a value doesn't match its pattern;
    • needs names a variable that no row sets.

    The fields go into that row of launcher.json.

  • launcher.json gets "schema": 1. Schema 1 grows only by optional fields: a reader ignores fields it doesn't know, and a field keeps its meaning.

  • docs/launcher.schema.json describes the file as a JSON Schema, so a front end can validate it and generate its types from it. docs/frontends.md documents the fields and these rules.

  • Example rows: the five settings a front end shows first carry level=basic, and Rumble strength carries needs=DM_RUMBLE=1, as launcher: sub-settings that appear only when they can do anything (needs column) #355 has it.

The platform split stays where #352 put it: the shown column's platform:<ios|mac>.

What it means for the open PRs

Checked

  • test_launcher_settings.py (13 tests) checks:

    • the fields and the version in a written list;
    • strict meta parsing;
    • that META agrees with docs/frontends.md and the schema;
    • that every list written for Breath of the Wild, Wonder and Hades, iOS and Mac, conforms to the schema.

    CI has no jsonschema package, so the test carries a small validator for the keywords the schema uses. Broken lists are caught: a wrong level, a range without step, malformed needs, schema 2, an unknown section.

  • test_docs, test_lint_python, test_launcher_storage, test_nsp_mac_app and test_pso_offline pass.

  • The iOS launcher decodes rows with Decodable, so the new fields are ignored there.

…ON Schema front ends read

Draft for the discussion in seedds#388. Two open PRs want the ninth column of
settings.tsv for different things (seedds#355: needs, seedds#399: level), and seedds#379
brings its own metadata. This makes the ninth column one optional meta
column of key=value pairs, so any number of optional fields fit:

- settings.py's META lists the keys with the pattern each value must
  match (level=basic, needs=<VAR>=<value>); an unknown key, a key given
  twice, a value that does not match, or needs naming a variable no row
  sets stops settings.py. The fields go into the row of launcher.json.
- launcher.json gets "schema": 1. Schema 1 grows only by optional
  fields: a reader ignores fields it does not know, and a field keeps its
  meaning. docs/launcher.schema.json describes the file as a JSON Schema,
  so a front end can check it and generate types from it.
- The five settings a front end shows first carry level=basic, and
  Rumble strength carries needs=DM_RUMBLE=1, as seedds#355 has it.

The platform split stays the shown column's platform:<ios|mac> (seedds#352).

test_launcher_settings.py: the fields and the version in a written list,
the strict meta parsing, META agreeing with docs/frontends.md and the
schema, and every list written for Breath of the Wild, Wonder and Hades
(iOS and Mac) conforming to the schema (a small validator for the
keywords the schema uses, as CI has no jsonschema package).
test_docs, test_lint_python, test_launcher_storage, test_nsp_mac_app and
test_pso_offline pass.

@seedds seedds left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved in shape. Before it leaves draft: make section a string in launcher.schema.json, and document in docs/frontends.md how a reader handles an unknown section. Then mark it ready and I'll merge it.

seedds and others added 2 commits October 27, 2026 21:39
A reader draws a section it does not know under its name, as the iPhone
app already does (sections in the order of their first rows). A new kind
stays a schema change, since a reader cannot draw it.

Co-authored-by: v0lumehi <[email protected]>
A needs value the parent row never takes (needs=DM_RUMBLE=on, when the
toggle takes 1 and 0) would hide the sub-setting for good. settings.py
now stops on it, for toggles and choices; a range or the game's languages
take any value.

Co-authored-by: v0lumehi <[email protected]>
seedds added a commit to v0lumehi/nxnative that referenced this pull request Oct 27, 2026
…r_base

A profile's render_base (the 3D views' base size, docked then handheld)
goes into the render scale's row as base, so a front end can show 0.75
as 1200x675 docked instead of 75%. Breath of the Wild's is 1600x900
1280x720, from its note's Render scale section. base is an optional
field of schema 1, in docs/frontends.md and docs/launcher.schema.json.

The level half of the first version of this change is level=basic in
the meta column (seedds#418).

Co-authored-by: v0lumehi <[email protected]>
seedds added a commit to Xipzer/nxnative that referenced this pull request Oct 27, 2026
The settings screen draws every row the game supports, including rows that
cannot change anything in the state the screen is in: Rumble strength is
offered with rumble off. A row whose launcher.json entry has needs
(<VAR>=<value>, from settings.tsv's meta column, seedds#418) is drawn only while
that setting has that value, and reappears at once when it changes back.
A row naming a setting this game does not have stays drawn, since there is
nothing for it to hide behind. A section whose rows are all hidden draws
no heading. Settings keep their values while hidden.

dm/ios/tests/launcher_storage_check.swift covers the three cases.

Co-authored-by: Xipzer <[email protected]>
seedds added a commit that referenced this pull request Oct 27, 2026
… Schema for front ends (#418, #388)

settings.tsv's ninth column becomes one optional meta column of
key=value pairs separated by ;, so the optional fields #355 (needs) and
#399 (level) wanted no longer compete for it. settings.py's META lists
the keys with the pattern each value must match. It stops on an unknown
or repeated key, a value that does not match, and a needs that names a
variable no row sets or a value that row never takes (needs=DM_RUMBLE=on,
when the toggle takes 1 and 0, would hide the row for good). The fields
go into the row of launcher.json.

launcher.json gets "schema": 1, described by docs/launcher.schema.json,
so a front end can validate the list and generate its types. Schema 1
grows only by optional fields and new sections: a reader ignores fields
it does not know and draws a section it does not know under its name, as
the iPhone app already does; a new kind would be schema 2.
docs/frontends.md documents the fields and these rules.

The five settings a front end shows first carry level=basic, and Rumble
strength carries needs=DM_RUMBLE=1.

test_launcher_settings.py checks the fields and the version, the strict
meta parsing, that META agrees with docs/frontends.md and the schema,
that the lists written for Breath of the Wild, Wonder and Hades (iOS and
Mac) conform to the schema, and that a new section conforms while a new
kind does not.

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

seedds commented Oct 27, 2026

Copy link
Copy Markdown
Owner

Thanks, @v0lumehi. This landed on main as f646545, with you as co-author.

Two changes from the draft, as agreed in #388:

  • section is a plain string in docs/launcher.schema.json, so a new section (ios/launcher: a Picture section, and the thermal cap as a setting #357's Picture) stays schema 1. docs/frontends.md says a reader draws a section it does not know under its name, which is what the iPhone app already does (sections in the order of their first rows). A new kind would still be schema 2. A test checks both.
  • needs must name a value its row can take. needs=DM_RUMBLE=on (the toggle takes 1 and 0) passed before and would have hidden Rumble strength for good on the iPhone. settings.py now stops on it for toggles and choices.

The pushed branch had one new pyright finding from that check. The commit on main doesn't (lint_python --against: 0 new with the pinned tools). All dm/tools/tests and dm/ios/tests files pass. Closing this PR.

@seedds seedds closed this Oct 27, 2026
seedds added a commit that referenced this pull request Oct 27, 2026
f646545 (launcher.json schema 1, #418) was made from a diff against a
branch based on 6138a54, so it also reverted the two commits main had
gained since: Mario Wonder's two same-pass feedback draws in
feedback_snap (1963fab, #192, #377) and shader_split feeding zstd the
bytes of a .zs file inside a RomFS image (35e1b6e). This puts their
seven files back as those commits left them; nothing else touched them
since. Found when a Mario Wonder Mac app pack failed its shader split
with zstd exit status 1 on every .zs file in RomFS.img.

Co-authored-by: spedmo <[email protected]>
Xipzer added a commit to Xipzer/nxnative that referenced this pull request Oct 27, 2026
The settings screen draws every row the game supports, including rows that
cannot change anything in the state the screen is in: Rumble strength is
offered with rumble off. A row whose launcher.json entry has needs
(<VAR>=<value>, from settings.tsv's meta column, seedds#418) is drawn only while
that setting has that value, and reappears at once when it changes back.
A row naming a setting this game does not have stays drawn, since there is
nothing for it to hide behind. A section whose rows are all hidden draws
no heading. Settings keep their values while hidden.

dm/ios/tests/launcher_storage_check.swift covers the three cases.

Co-authored-by: Xipzer <[email protected]>
Xipzer added a commit to Xipzer/nxnative that referenced this pull request Nov 1, 2026
Know-It-All-Brother pushed a commit to Know-It-All-Brother/nxnative that referenced this pull request Nov 9, 2026
… Schema for front ends (seedds#418, seedds#388)

settings.tsv's ninth column becomes one optional meta column of
key=value pairs separated by ;, so the optional fields seedds#355 (needs) and
seedds#399 (level) wanted no longer compete for it. settings.py's META lists
the keys with the pattern each value must match. It stops on an unknown
or repeated key, a value that does not match, and a needs that names a
variable no row sets or a value that row never takes (needs=DM_RUMBLE=on,
when the toggle takes 1 and 0, would hide the row for good). The fields
go into the row of launcher.json.

launcher.json gets "schema": 1, described by docs/launcher.schema.json,
so a front end can validate the list and generate its types. Schema 1
grows only by optional fields and new sections: a reader ignores fields
it does not know and draws a section it does not know under its name, as
the iPhone app already does; a new kind would be schema 2.
docs/frontends.md documents the fields and these rules.

The five settings a front end shows first carry level=basic, and Rumble
strength carries needs=DM_RUMBLE=1.

test_launcher_settings.py checks the fields and the version, the strict
meta parsing, that META agrees with docs/frontends.md and the schema,
that the lists written for Breath of the Wild, Wonder and Hades (iOS and
Mac) conform to the schema, and that a new section conforms while a new
kind does not.

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
5acb436 (launcher.json schema 1, seedds#418) was made from a diff against a
branch based on 0b0c9bf, so it also reverted the two commits main had
gained since: Mario Wonder's two same-pass feedback draws in
feedback_snap (679c65c, seedds#192, seedds#377) and shader_split feeding zstd the
bytes of a .zs file inside a RomFS image (0388e2d). This puts their
seven files back as those commits left them; nothing else touched them
since. Found when a Mario Wonder Mac app pack failed its shader split
with zstd exit status 1 on every .zs file in RomFS.img.

Co-authored-by: spedmo <[email protected]>
Xipzer added a commit to Xipzer/nxnative that referenced this pull request Nov 13, 2026
Two additions to the present pass, both of which work for any game because
neither needs anything from the game.

DM_PRESENT_UPSCALE_OUT=1.0..4.0 reconstructs above the viewport and averages
back down. The present shader took one bilinear sample, which reads 4 texels
whatever the reduction, so reconstructing larger and sampling down this way
threw nearly all of it away. The tap count now follows the reduction ratio,
capped at 4x4, which makes it real supersampling. At 1.0, the default, the
scaler still targets the viewport and the shader still takes one tap, so
nothing changes.

In the launcher it is Upscaling detail, a sub-setting of Upscaling
(needs=DM_PRESENT_UPSCALE=metalfx, seedds#418): its row is drawn only while MetalFX
is chosen.

DM_SHARPEN=0..1 is contrast adaptive sharpening of the finished picture: the
5 tap cross, clamped to the neighbourhood's own range so it cannot ring or
halo. It is a second fragment function taken instead of the blit, not after
it, so it adds no pass and costs nothing when off.

The present without a Metal 4 queue passes one tap and no sharpening, so it
draws as before.

Measured with the same two changes in a fork, on Breath of the Wild 1.9.0 on
an iPad Pro 13" M4, 1920x1080 content into a 2752x1548 viewport, all at
60.00 fps with thermal state nominal and a 16.67 ms budget:

  upscaling  output  scaler target  GPU
  off        -       -               8.53 ms
  metalfx    1.0     2752x1548       9.09 ms
  metalfx    2.0     5504x3096      11.34 ms

Before the box filter, output 2.0 looked identical to 1.0 while costing the
same 11 ms, which is what led to the change.

Compiles. Not yet run against this main: our devices are built from an older
chain and rebuilding them is a long job, so the device numbers above come
from the fork. Opening it now because both settings are off by default.
khalilgharbaoui pushed a commit to khalilgharbaoui/nxnative-ultimate that referenced this pull request Nov 14, 2026
Two additions to the present pass, both of which work for any game because
neither needs anything from the game.

DM_PRESENT_UPSCALE_OUT=1.0..4.0 reconstructs above the viewport and averages
back down. The present shader took one bilinear sample, which reads 4 texels
whatever the reduction, so reconstructing larger and sampling down this way
threw nearly all of it away. The tap count now follows the reduction ratio,
capped at 4x4, which makes it real supersampling. At 1.0, the default, the
scaler still targets the viewport and the shader still takes one tap, so
nothing changes.

In the launcher it is Upscaling detail, a sub-setting of Upscaling
(needs=DM_PRESENT_UPSCALE=metalfx, seedds#418): its row is drawn only while MetalFX
is chosen.

DM_SHARPEN=0..1 is contrast adaptive sharpening of the finished picture: the
5 tap cross, clamped to the neighbourhood's own range so it cannot ring or
halo. It is a second fragment function taken instead of the blit, not after
it, so it adds no pass and costs nothing when off.

The present without a Metal 4 queue passes one tap and no sharpening, so it
draws as before.

Measured with the same two changes in a fork, on Breath of the Wild 1.9.0 on
an iPad Pro 13" M4, 1920x1080 content into a 2752x1548 viewport, all at
60.00 fps with thermal state nominal and a 16.67 ms budget:

  upscaling  output  scaler target  GPU
  off        -       -               8.53 ms
  metalfx    1.0     2752x1548       9.09 ms
  metalfx    2.0     5504x3096      11.34 ms

Before the box filter, output 2.0 looked identical to 1.0 while costing the
same 11 ms, which is what led to the change.

Compiles. Not yet run against this main: our devices are built from an older
chain and rebuilding them is a long job, so the device numbers above come
from the fork. Opening it now because both settings are off by default.

Hand merge (present.metal, nvn_mtl.m, settings, docs): the present's constants (Crop) carry the fork's HDR conversion (PR seedds#1176, mode) in the slots this change used, so Crop has a fourth float4, box (taps, one texel, sharpening), and every buffer of it is 16 floats; fs and sharp both end in present_convert, the conversion fs did. The taps are more than 1 only for MetalFX's output reconstructed above the viewport (DM_PRESENT_UPSCALE_OUT above 1.0): at the default a picture shown smaller than rendered still takes one tap, as before (the change computed taps from any reduction). fx_encode's output size takes DM_PRESENT_UPSCALE_OUT ahead of main's scaler check (fx->sc fields), and a larger output is never the drawable written directly; snap_take (PR seedds#1045) scales at the snapshot only at 1.0. FSR 1 (easu) wins over sharpening when both are set. Upscaling detail, Sharpening and FSR 1 are all off by default.

(cherry picked from commit 704ca34)
Xipzer added a commit to Xipzer/nxnative that referenced this pull request Nov 18, 2026
Two additions to the present pass, both of which work for any game because
neither needs anything from the game.

DM_PRESENT_UPSCALE_OUT=1.0..4.0 reconstructs above the viewport and averages
back down. The present shader took one bilinear sample, which reads 4 texels
whatever the reduction, so reconstructing larger and sampling down this way
threw nearly all of it away. The tap count now follows the reduction ratio,
capped at 4x4, which makes it real supersampling. At 1.0, the default, the
scaler still targets the viewport and the shader still takes one tap, so
nothing changes.

In the launcher it is Upscaling detail, a sub-setting of Upscaling
(needs=DM_PRESENT_UPSCALE=metalfx, seedds#418): its row is drawn only while MetalFX
is chosen.

DM_SHARPEN=0..1 is contrast adaptive sharpening of the finished picture: the
5 tap cross, clamped to the neighbourhood's own range so it cannot ring or
halo. It is a second fragment function taken instead of the blit, not after
it, so it adds no pass and costs nothing when off.

The present without a Metal 4 queue passes one tap and no sharpening, so it
draws as before.

Measured with the same two changes in a fork, on Breath of the Wild 1.9.0 on
an iPad Pro 13" M4, 1920x1080 content into a 2752x1548 viewport, all at
60.00 fps with thermal state nominal and a 16.67 ms budget:

  upscaling  output  scaler target  GPU
  off        -       -               8.53 ms
  metalfx    1.0     2752x1548       9.09 ms
  metalfx    2.0     5504x3096      11.34 ms

Before the box filter, output 2.0 looked identical to 1.0 while costing the
same 11 ms, which is what led to the change.

Compiles. Not yet run against this main: our devices are built from an older
chain and rebuilding them is a long job, so the device numbers above come
from the fork. Opening it now because both settings are off by default.
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