Promoting Late-Gameplay BG3 Composition Contracts in the TD2 SDL Port

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

Developer Nivando Soares has transitioned late-gameplay renderer hypotheses from experimental tooling into the native TD2 SDL runtime. This update specifically targets frame bundles 3250, 3400, and 3550 to resolve rendering issues like the missing horizon strip through versioned composition contracts.

Why This Matters

In high-fidelity retro porting, technical reality often deviates from ideal models when assets interact with narrow composition rules. By moving from design-only experiments to first-class runtime logic, developers can eliminate hardcoded lookups and ensure that complex scanline priorities, such as BG3 over BG2, are consistently applied across specific gameplay windows.

Key Insights

• Frames 3250 and 3400 now enforce BG3 in the top 79 scanlines with a BG3 > BG2 priority rule.
• Frame 3550 extends the composition contract to a deeper 95-line scanline window using the same priority logic.
• The td2_runtime now consumes these rules from a versioned contract file located at rom_analysis/docs/gameplay_composition_contracts.jsonc.
• The native SDL render path in td2_ppu now supports concrete knobs: bg3_enable_top_scanlines and bg3_above_bg2_top_scanlines.
• Validation was confirmed via a smoke matrix including 335 scheduler checks and 39 scanline/composition contract checks.

Practical Applications

• Use Case: The TD2 SDL port uses versioned JSON contracts to resolve matching profiles for design packs, allowing the runtime to adjust renderer behavior dynamically.
• Pitfall: Hardcoding late-gameplay lookups instead of using a contract file can lead to unscalable design experiments and difficulties in direct design review.

References:

• https://dev.to/nivandosoares/promoting-late-gameplay-bg3-composition-contracts-in-the-td2-sdl-port-15gn