Promoting late-gameplay BG3 composition contracts in the TD2 SDL port

Promoting late-gameplay BG3 composition contracts in the TD2 SDL port

This checkpoint moved one late-gameplay renderer hypothesis out of tooling and into the runtime.

The late live-entry bundles at frames 3250, 3400, and 3550 already had a strong signal from the cutoff sweep: the missing horizon strip was not explained by missing assets, but by a narrow composition rule. The best candidates were consistent enough to promote:

• frame 3250: enable BG3 in the top 79 scanlines and keep BG3 > BG2 there

• frame 3400: same 79-line window

• frame 3550: same rule with a deeper 95-line window

The runtime now loads those rules from a versioned contract file instead of a hardcoded late-gameplay lookup:

• rom_analysis/docs/gameplay_composition_contracts.jsonc

On the implementation side, td2_runtime resolves the matching profile for the loaded design pack, and td2_ppu now applies two concrete knobs in the native SDL render path:

• bg3_enable_top_scanlines

• bg3_above_bg2_top_scanlines

That means the late-gameplay top-band BG3 rule is now a first-class part of the native renderer rather than a design-only experiment.

Validation stayed bounded and explicit:

• make -C port test

• python3 tools/build_docs_wiki_report.py --manifest rom_analysis/docs/wiki_doc_index.json --output-dir tools/out/docs_wiki --markdown-bundle-dir tools/out/docs_wiki_markdown_bundle

The current smoke matrix passed with:

• compare lane 3/3

• scheduler smoke 335 checks

• input mutation smoke 200 checks

• live input smoke 21 checks

• scanline / composition contract smoke 39 checks

For design review, I also regenerated runtime PNGs for the promoted late-entry anchors so the team can judge the native SDL output directly, not only the sweep candidates.

The practical result is modest but important: late gameplay is now narrowed past “maybe BG3 matters here” and into one explicit, versioned composition rule that the runtime consumes. The next question is whether that same family needs more measured state beyond this top-band rule, or whether extending the composition contract to more anchors still pays off.