Patch design: bind every patch as loosely as what it depends on (host, sdk, engine, game, build)

[seedds]

Goal

Keep game-specific code to the minimum. Every per-build patch has to be redone for each new game version (#375: Smash 13.0.1 lost its cuts). A general mechanism covers games and updates nobody has seen yet. This issue proposes rules for how general each patch must be, with a classification of every patch we have today (docs/agents/game-patches.md), and asks for input before the classes go into the patch files.

Binding: what a patch depends on

A patch's binding is what its correctness is anchored to. From the loosest to the tightest:

Binding	Anchored to	Found by	Survives
host	Horizon / NVN / Vulkan semantics	nothing in the binary	every game, every update
sdk	Nintendo SDK code (sdk module)	symbol, or a fingerprint per reviewed SDK implementation	any game shipping that SDK implementation
engine	middleware code: Unreal, Unity, Snowdrop, KTGL, sead, PhysX	registered name, string, or a fingerprint per engine version	any game on that engine version
game	the game's own code	function fingerprint (MATCH_CUTS)	the game's updates that keep the function
build	fixed offsets	NSO build ID	nothing: redone every update

A second axis is the purpose: address space (an iPhone's ~6 GB), race (a race or timing problem the host exposes), frame rate / resolution (an enhancement), power.

Rules (proposed)

1. Bind a patch as loosely as the thing it depends on. A patch is good design when its binding is the loosest that is correct. The gap between a patch's binding now and the loosest it could have is the work list.
2. Mechanism general, decision in the profile. Where only the decision is the game's (hold Unity's vSyncCount at 1, raise Unreal's t.MaxFPS), the code that finds the place is host / sdk / engine and the choice is a profile key. No per-game branch in the host.
3. Discover once, in the rewriter. Addresses found from the binary (names, strings, fingerprints) are found by patch_nso.py and passed to the host through the fixups. No fixed-address tables in dm/host.
4. A build row is a starting point, not a destination. A new CUTS row is fine for a bring-up; it should name the binding it can move to.
5. Correct semantics are defaults. A profile key that makes the host behave as Horizon or the GPU does is on for every game, after regress.py check. Keys stay per game only for real per-game data or decisions.
6. No game's choice in a shared file. sdk_patches.py holds fixes every game shipping that SDK build needs. A tuning one game needs goes in that game's profile.
7. Remove what a general mechanism replaced, after a boot check of the games that had it.
8. Every patch states its binding: now, the loosest it could have, purpose, why, and what was checked. This replaces the free-text GENERALIZE note, and docs_patches.py lists the gaps.

Where each patch stands

The classification lives with the patches and is generated, so it cannot drift: each patch file's BINDING table, and dm/tools/docs_patches.py for the host's build-keyed rows, translator rules and profile switches. The page is docs/agents/game-patches.md:

• Binding: the five classes, the statuses and the evidence kinds.
• Gaps: every patch bound tighter than it could be, the loosest goals first. That is the work list.
• Each game's section: every one of its patches with its binding now, goal, purpose, status and evidence.

Status is computed: at goal, gap, blocked (with the reason it cannot close yet) or kept (left open on purpose, with the decision). Evidence is checked (what was checked on game files, and when) or judgement. test_patches.py fails when a patch file has no BINDING or when an entry's goal is tighter than its binding now, and the generator stops on any unclassified host row, translator rule or switch.

The page shows this once the change that adds BINDING is on main.

Proposed order

1. Removals: Scarlet's cut, the dead NieR row, the SDK rows the rules reproduce.
2. Unreal discovery in the rewriter (cvars and allocator), replacing k_locks' Unreal rows, k_ue and the Unreal CUTS/OBS.
3. BINDING in every patch file; docs_patches.py lists the gaps.
4. Semantic profile keys to defaults, one at a time with regress.py check.
5. Function-matched rules (and a matched form of frame-step stubs) for the game-bound patches, as updates come.

Input wanted

• Are these the right five bindings? Is anything missing, for example a separate shader binding for translator rules, or data for profile keys?
• Rule 3: should the host keep a runtime search (as dm_ue_cvar does now), or should all discovery move to the rewriter?
• Rule 5: which of the semantic keys has a reason to stay off by default that this list misses?
• The 2 MB alignment rows: an SDK-wide rule for those SDK implementations, or per-game choices?
• Frame-rate enhancements: should they stay build-bound on purpose, so that a game update never inherits a 60 fps change nobody checked?

[v0lumehi]

Thanks for writing this up. Turning "prefer the general fix" into a measurable gap, with a generated work list, is the direction I'd hoped for, and it gives reviews something concrete to point at.

One rule I'd add: every locator fails closed. nso_match and dm_ue_cvar already do it: exactly one match with its assumptions checked, otherwise a red line and no change. Writing it down as a rule would carry it over to the Unreal discovery moving into the rewriter and to every future SDK or engine matcher. That is what makes a looser binding safe for builds nobody has seen.

On your questions:

• A shader binding? I'd apply the same ladder to translator rules instead of adding one class: NVN semantics for every shader (like the early fragment tests from control +0x718), then a pattern per compiler or engine version, then a single shader hash. Profile keys read to me as decisions rather than bindings, so I'd keep them on the purpose side.
• Rule 3: the rewriter finds the anchors, the host only follows them at run time. dm_ue_cvar shows the split: the object's offset comes from main's static code and strings, and only the value pointer at +0x10 is run-time state. The search could move to the rewriter and into the fixups, with the host keeping the read, and the first present would no longer pay for the search.
• Rule 5: agreed. regress.py check already compares frame times and footprint, so it's the right gate. I'd keep a per-game "kept off" with its reason, and flip one key per change so a regression points at one key.
• The 2 MB rows: SDK-wide per reviewed placement implementation. SDK 20 itself aligns only to 64 KB or 2 MB (Cult of the Lamb's 19.3.14 already does), so games of every engine run that way. It's the SDK's behaviour, not a game's choice, even if Unity's N MB + 252 KB reservations are what made it necessary. It would also settle a split we have today: nirvanA, Scarlet and Below Zero take 2 MB, while Sparks of Hope, with the same constructor and placement code, takes 32 MB for regions of 1 GB and more.
• Frame rate: agreed that what's on by default should stay build-bound. I'd separate that from availability: the mechanism as loose as it can be, on by default only for checked builds, and offered on an unchecked build as an explicit player choice in the launcher, so an update neither inherits an unchecked change nor silently loses the enhancement. Run-time patches chosen at launch (<module>.runtime.tsv) #519's run-time patches could carry that choice.

Two smaller points:

• A goal of "unreviewed". A bring-up, often written with an agent, shouldn't have to guess the loosest binding; a guessed class is worse than an open one. BINDING could accept "goal: unreviewed", listed as such under Gaps, while the test still requires the entry.
• The order of the gap list and rule 7's check. I'd order Gaps by payoff, meaning how many games and builds a move would cover and whether the game still gets updates. And I'd have rule 7's removal check drive the path the patch fixed (the game's smoke route, 18 games have one, or the note's steps), since many patches act well after boot.

[seedds]

Thanks, this sharpens it. Since you wrote, the first part landed in ed0360b: BINDING in every patch file, the generated table with status (at goal / gap / blocked / kept) and evidence (checked / judgement), the SDK-wide rules for every sdk build, 18 duplicate SDK rows removed, and Scarlet's cut removed after a route check to frame 9,900.

• Fail closed: agreed, it becomes a rule. One nuance: an SDK-wide rule that finds nothing is normal (most sdk builds ship another implementation), so a miss changes nothing and logs a plain line. The red line is for a patch that was expected to match that build, as a profile's own MATCH_CUTS is.
• Shaders: agreed, the same ladder for translator rules, no new class. Profile keys that are decisions stay on the purpose side, at game as their goal; keys with Horizon or GPU semantics move toward host defaults.
• Rule 3: agreed: the rewriter finds the anchors and passes them in the fixups, the host only reads them. dm_ue_cvar logs its search time, so we can measure what the first present saves.
• Rule 5: agreed. The kept status that just landed is the per-game "kept off" with its reason, and the keys flip one per change.
• 2 MB rows: you've convinced me. SDK 20 itself aligns only to 64 KB or 2 MB, so 2 MB is the SDK's own later behaviour, not a Unity choice. I'll make it one SDK-wide rule per reviewed placement implementation, which also ends the 2 MB / 32 MB split with Sparks of Hope. Since it moves region placement for many games, it goes in alone, with a regression check on a game of each placement implementation.
• Frame rate: agreed: on by default only for checked builds, the mechanism as loose as it can be, and an explicit player choice on unchecked builds. Run-time patches chosen at launch (<module>.runtime.tsv) #519 is the natural carrier once it lands.
• goal: unreviewed: yes, better than a guess. It will be accepted and listed under Gaps.
• Gap order and rule 7: agreed: payoff first (games and builds covered, whether the game still gets updates), and removal checks drive the path the patch fixed (the smoke route or the note's steps), not just a boot.

[seedds]

The four follow-ups landed in 17f670a:

• 2 MB alignment, SDK-wide: the rules now cut all three large size classes (4 MB, 32 MB, 1 GB) to 2 MB, as SDK 20 does, at the same function offsets in all four reviewed implementations. The 2 MB rows (Sea of Stars / Wonder 1.0, nirvanA / Scarlet / Below Zero) rebuild byte-identical from the rules and are removed; 19 other builds go from one cut to three. Regression check, one game per implementation: Pikmin 4, Pokémon Legends: Arceus, Paper Mario: The Thousand-Year Door, Wonder 1.2.1, all clean (frame times and screenshots match). SDK 4.4.0's row (Kingdom Battle) stays at 32 MB: no rule covers that implementation yet, and it is listed under Gaps as blocked.
• Fail closed: every locator, dm_ue_cvar included, needs exactly one match. An SDK-wide rule that finds nothing logs a plain line, no [RED].
• goal: unreviewed: accepted for a game's own build-bound patches (no blocked / kept with it) and listed under Gaps.
• Gap order: derived, not hand-kept: open gaps, then blocked, kept and unreviewed; in each, most games reached first, then farthest from the goal. The table has a Games column. I left out "still gets updates": it would be a field to keep by hand and would go stale, so games reached stands in for payoff.

[seedds]

Two more steps landed:

• ee6648c, SDK rows: the 2 MB rows of 5bcf525f, 2aef2cff and 60751516 are removed; the SDK-wide rules now give those builds the same cuts. Three rows (2d369d99, 12f16103, 311deab1) stay blocked: their games have no Mac build here to check them on.
• 51904e7, Unreal's allocator at engine: the rewriter now finds FMallocBinned3 from the engine's own code (dm/tools/ue_malloc.py), with no build ID. The chain is the UTF-16 Binned3 name, its getter, the one vtable slot holding the getter (relocations applied), the vtable's one constructor and that constructor's one call. The getter's slot names the layout: 19 for UE 4.26 / 4.27, 22 for UE 5, 26 for UE 5.6. The rewriter cuts the call, puts gate OBS_UE_MALLOC on it and passes the vtable and slot in the fixups (UE_MALLOC_VT, UE_MALLOC_SLOT), so this is rule 3: the host only reads them. It fails closed: when the name is there but a link is missing or not unique, or the slot is unknown, it logs a [RED] line and cuts nothing; with no name it logs a plain line.
  • This replaces the per-build cuts and fixed host rows of OCTOPATH TRAVELER 0 and II, DRAGON QUEST VII Reimagined, Pikmin 4, SHIN MEGAMI TENSEI V: Vengeance and FINAL FANTASY RESONANCE (global and Asia). Six patches.py files are gone.
  • Batman: Arkham Knight (Unreal Engine 3) has no Binned3 name, so it keeps its fixed row.
  • Checked offline on all 68 mains on the game drive: the rule finds exactly the five registered builds and nothing in the other 63. It also finds SMT V's registered call on that game's main, extracted from the archive drive.
  • Checked in game: OCTOPATH TRAVELER II passed regress.py check (frame times and screenshots match). Pikmin 4 got the host allocator through the new path and reached its screenshots. OCTOPATH TRAVELER 0, the only Unreal 5 game run here, has not run in game on the new path yet; for it, and for UE 5.6 (FINAL FANTASY RESONANCE), the offline check is all so far.

[seedds]

Two more commits landed:

• 602ed11, Unreal console variables at engine: the rewriter now finds the variables the host writes by their registered names (dm/tools/ue_cvar.py), with no build ID. These are t.MaxFPS, rhi.SyncInterval, nvn.SyncInterval, r.Streaming.PoolSize and Project.FrameRateLimit.
  • The search starts from the name (UTF-16 or UTF-32), the adrp + add that loads it into x1, and the first call after it. A bl is UE 4.18's TAutoConsoleVariable constructor, with the object in x0. A blr is the console manager's register call (UE 4.2x and 5); then the object is the one the returned value pointer is stored into, at +0x10.
  • The rewriter writes UE_CVAR:<name> rows into main's fixups, so this is rule 3 as well: hle_fpslock.c and hle_uecvar.c only read them, and the host's own search code is gone.
  • It fails closed: a name registered at two objects gives none, with a [RED] line. A name that is only looked up, never registered, is a plain miss.
  • This replaces the 13 fixed k_locks rows of OCTOPATH TRAVELER 0 and II, DRAGON QUEST VII Reimagined, FINAL FANTASY RESONANCE (global and Asia), SHIN MEGAMI TENSEI V: Vengeance and DRAGON QUEST XI S.
  • Which variable carries the frame limit is a profile decision: the new key ue_fps_cvar defaults to t.MaxFPS, and SMT V sets Project.FrameRateLimit.
  • Checked offline on 61 mains (the game drive, plus SMT V and DQ XI S from the archive drive): the search finds exactly the objects of the 13 removed rows, and nothing in the non-Unreal games.
  • Checked in game: OCTOPATH TRAVELER II passed regress.py check (frame times and screenshots match). The other six games have the offline check only.
  • Open: OCTOPATH TRAVELER keeps the game's 30 fps. Its registration is inlined (the object's page base is set long before the name), which the search does not cover yet.
• e513bfe, a regress.py fix that changes how earlier results here should be read: the harness took any <id>_build/profile/<id>/game.tsv as a derived profile and ran it instead of dm/games/<id>. The NSP script leaves a provisional profile there from a game's first packing, so 38 of the 57 games on the game drive were tested with their guessed profiles. Pikmin 4 and Pokémon Legends: Arceus, two of the games checked for 17f670a above, are among them.
  • The rewriter's cuts do not depend on the profile, so those runs still exercised the cuts. They did not run with the games' real settings.
  • A build's profile now runs only when it is derived (<id>.derived.key beside it) or the game has no profile in dm/games.

[seedds]

One more step landed:

• 8bdfcb7, Three Houses' frame-limiter cut moves to host: its limiter (main+0x5be430) yields and reads the clock until its deadline. The host's yield back-off spun such a loop for 2 ms and then ended each wait up to 250 µs late, which is why the cut made it sleep. Now every guest clock read counts on its thread, and a run of yields whose passes read the clock is a clock wait (clock_wait in hle_thread.c):
  • it backs off from its first yield (no 2 ms of plain yields: it waits for a time, not for another thread's handoff);
  • once its waits end at a steady period, it has learned its deadline (last end plus the period): each wait sleeps on time to 150 µs before the predicted end, then polls;
  • a wait that ends at the first poll after that sleep shortens the period once, and relearns it if that happens twice in a row, so a 30 → 60 change costs two late frames.
  • Three Houses on the Mac, 100 s to the title in a window, the same build rewritten with and without the cut: without it, the old back-off gave 59.4–59.5 fps at 0.28–0.79 W of CPU; backing off from the start alone 59.4–59.5 fps at 0.19–0.35 W; this change 59.8–60.0 fps, frame p50 16.67–16.81 ms, 0.09–0.16 W. With the cut it was 59.9 fps, 16.68 ms, 0.11–0.49 W. The cut and its row are gone; the render-wait timeout cut stays build.
  • New host test t_clockwait on a test clock.
  • regress.py check: OCTOPATH TRAVELER II passes, but none of its threads made a clock wait, so the change did not run there. Pokémon Legends: Arceus passed the chain checks only (no smoke route). No other game has been seen making a clock wait yet.

[seedds]

Two more steps landed:

• 8fd4b72, OCTOPATH TRAVELER's console variables at engine: UE 4.18 inlines the TAutoConsoleVariable constructor into a long static initializer that addresses every object from one page base, made about 700 instructions before the name (str x8, [x22, #k] the vtable, then, after the call that returns the value pointer, str x0, [x22, #k + 0x10]). ue_cvar.py now takes that base back to its adrp + add, across the forward branches over else blocks. It fails closed: nothing is found if another write to the register, or a branch from outside within 1 MB, lands between.
  • Offline, on the 43 mains on the game drive: only OCTOPATH TRAVELER's result changed (t.MaxFPS and nvn.SyncInterval found, the other variables as before).
  • In game: 300 s of the S'warkii route, frame time p50 16.7 ms at 60 against 33.5 ms at 30. Open: CPU-side long frames are 2 to 2.5 times as frequent at 60, and the speed at 60 has not been compared on a walk yet.
• 50aefc1, Fire Emblem Engage and Pokémon Brilliant Diamond: four build-bound patches gone.
  • Their SDK rows (56ec2474, 2d369d99) give way to the SDK-wide rules, which give the same node area cut plus the 2 MB alignment. Run on both games with the iPhone's alias region (DM_ALIAS_SIZE=0x118000000): StandardAllocator's region moves from alias +0.38 GB to +0.06 GB, and the gaps between live regions shrink (Engage 0.89 → 0.69 GB, Brilliant Diamond 0.41 → 0.07 GB).
  • Engage's vSyncCount cut is replaced by the host's write of the quality level's count (fps_target 60): its logic reads the count back, and the attract demo shows the same scenes at the same frames as with the cut.
  • Brilliant Diamond's fixed targetFrameRate row is replaced by unity_fps.py, which now reads Unity 2019.4 / 2017.4's internal calls registered from code (function in x1, name in x0; a name registered with two functions gives none). It finds exactly the row's field. On the 45 mains on the drive only Brilliant Diamond's and Return of the Obra Dinn's results changed.
  • Not run yet: Brilliant Diamond past its language menu, and Engage's save-list speed test.

Next: the remaining SDK rows (12f16103, 311deab1, 9c73fb73, e01950c5) with Brain Memory Training Academy, Ace Attorney Investigations Collection, Hollow Knight: Silksong and Patrick's Parabox.

[seedds]

6059cba, the last four SDK rows: Ace Attorney Investigations Collection's (311deab1), Brain Memory Training Academy's (12f16103) and Patrick's Parabox's (9c73fb73) give way to the SDK-wide rules, which add the 2 MB alignment to the row's node area cut. Hollow Knight: Silksong's (e01950c5) rewrites byte-identical with the rules (its SDK 20 placement aligns to 2 MB itself).

• Each of the three was run 240 s from a fresh save with the iPhone's alias region (DM_ALIAS_SIZE=0x118000000), with the row and with the rules. All reach nnMain and their first screen at 60 fps; the gaps between live address regions shrink (0.35 → 0.22, 0.19 → 0.11, 0.33 → 0.19 GB). None was played past the first screen.
• Only SDK 4.4.0's row (Mario + Rabbids Kingdom Battle) is left, an implementation no rule covers, blocked until a second game ships it.

Next on the gap list: Subnautica's bucket allocator and FFCC's ThreadedStreamBuffer race (Unity 2019 / 2018.4, now that their files are back), then a multi-function frame step for ASTRAL CHAIN, Tears of the Kingdom, Breath of the Wild and Age of Calamity.

[seedds]

2c2c549 + 56e4f2a, engine-wide rules for three more games' build cuts:

• Unity 2019's ALLOC_BUCKET (Subnautica, Below Zero): dm/tools/unity_bucket.py finds the bucket allocator's construction by its name and cuts its block limit when the reservation is over 256 MB (255 → 63 blocks of 4 MB), an iPhone address-space cut. Both mains rewrite byte-identical to their old per-build cuts; on the 48 other mains on the drive it cuts nothing (Unity 2020.3 passes 1 block, 2021 and later read boot.config). This lands at engine, looser than the game goal the gap list had.
• Unity 2018's ThreadedStreamBuffer race (FFCC): a new dm/tools/engine_patches.py holds function-matched rules for every game's main, loaded and applied like sdk_patches.py's, with no red line where nothing matches. The eight load-acquires are one rule over four functions. FFCC 1.0.3 rewrites byte-identical; FFCC 1.0.0 now gets the same eight sites, which no cut covered; Raging Loop (Unity 2018.3, the same four functions) gets them too and boots through its opening to the title at 60 fps. Unity 2017.4 (Cuphead, AI: THE SOMNIUM FILES) has other code there and matches nothing.

The three patches.py files are gone. Next on the gap list: a frame step matched across several functions (ASTRAL CHAIN, Tears of the Kingdom, Breath of the Wild, Age of Calamity), then NieR.

[seedds]

143c0d0, frame steps across several functions: the multi-function mechanism already existed (others, since Ocarina), so the gap entries' "blocked" reason was stale. Before converting anything I compared each frame step with its engine's other games: none of the four games' frame-step functions has an exact match (sead: BotW and TotK against 13 Nintendo mains; PlatinumGames: ASTRAL CHAIN against Bayonetta 1–3 and NieR; KTGL: Age of Calamity against Three Hopes, Taiko, Three Houses, HW: DE and Age of Imprisonment). So game is the loosest binding for them.

• Tears of the Kingdom: a six-function matched rule; 1.4.3 rewrites byte-identical, so its build entry is gone.
• Age of Calamity: the update on the drives (v458752) had fallen back to 30 fps. A four-function matched rule now places its five sites; the KTGL device global and the frame-rate block moved, so a matched stub reads them from its functions' adrp pairs (ctx.address). Through the opening at 60: game time 0.992 of real time (0.997 at 30), cutscenes in step with their subtitles. 1.3.0 keeps its build entry, its main being on neither drive. Packing it exposed a bug: a derived profile dropped fps_target when FRAME_STEP named other builds, even with a matched rule; fixed.
• Breath of the Wild (34 functions) and ASTRAL CHAIN (last update 2019): kept build-bound, with the evidence recorded.

Side finding: BotW's widescreen stubs patch sead::PerspectiveProjection, which TotK, Animal Crossing and Splatoon 3 share, a candidate engine rule for the screen-shape gap. Next on the list: NieR (both releases).

[seedds]

a9ee247, NieR:Automata: both releases' cuts and the host's fixed-address table stay build-bound, now marked kept. None of their sites has an exact match in ASTRAL CHAIN or Bayonetta 1–3, so game is their loosest binding; 1.0.3 is likely both releases' last update, so a matched rule would serve no other build, and moving the host table would also need a new mechanism (matched rules that write fixups and declare capabilities). Left on the gap list: the vertex-shader ballot lowering (with the next chain change), a sead screen-shape rule for Animal Crossing (from BotW's widescreen stubs), and the blocked one-engine rows.

[seedds]

06973c5, the vertex-shader ballot lowering: kept as Tears of the Kingdom's single-shader rule. The shader-build logs of the 51 game builds on the drive show no shader failing to translate or compile and no subgroup operation, so the only shader that needs the lowering is TotK's, which the rule already handles. A general lowering (subgroups of one invocation for ballots, votes, lane ids and counts, refusing shuffles) would be a chain change, every game's shaders rebuilt, for no measured gain; it is worth revisiting when a vertex shader with subgroup operations fails in another game.