107 lines
3.8 KiB
Markdown
107 lines
3.8 KiB
Markdown
---
|
|
id: PLN-0028
|
|
ticket: deferred-overlay-and-primitive-composition
|
|
title: Plan - Runtime Frame-End Overlay Integration and Parity
|
|
status: accepted
|
|
created: 2026-04-18
|
|
completed:
|
|
tags: [runtime, overlay, frame-composer, no-scene, regression, stress]
|
|
---
|
|
|
|
## Objective
|
|
|
|
Integrate deferred overlay/debug draining into the runtime frame-end sequence so scene-bound and no-scene frames both present the same final `gfx.*` primitive behavior after `hud_fade`.
|
|
|
|
## Background
|
|
|
|
After `PLN-0027`, the overlay/debug subsystem will exist but still needs to be drained in the correct place relative to `FrameComposer.render_frame()`, fades, and present/present-adjacent behavior. This plan closes the observable runtime semantics required by `DEC-0016`.
|
|
|
|
## Scope
|
|
|
|
### Included
|
|
- runtime frame-end ordering changes
|
|
- scene-bound and no-scene parity
|
|
- regression coverage for overlay visibility above the canonical game frame
|
|
- stress-cartridge adjustments if needed to prove text/primitives now survive frame composition
|
|
|
|
### Excluded
|
|
- broad renderer optimization work
|
|
- final repository-wide CI
|
|
|
|
## Execution Steps
|
|
|
|
### Step 1 - Insert overlay/debug drain into the frame-end path
|
|
|
|
**What:**
|
|
Drain deferred overlay/debug after canonical game composition is complete.
|
|
|
|
**How:**
|
|
- Update the runtime frame-end path so overlay/debug drain occurs after:
|
|
- `FrameComposer.render_frame()`
|
|
- `scene_fade`
|
|
- `hud_fade`
|
|
- Ensure the same ordering is respected in the no-scene path.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/tick.rs`
|
|
- `crates/console/prometeu-drivers/src/hardware.rs`
|
|
- `crates/console/prometeu-drivers/src/gfx.rs`
|
|
- any bridge traits needed by the runtime/hardware path
|
|
|
|
### Step 2 - Add runtime and driver regressions for final visual ordering
|
|
|
|
**What:**
|
|
Lock the new visible behavior.
|
|
|
|
**How:**
|
|
- Add tests proving `gfx.draw_text(...)` remains visible after scene-backed frame composition.
|
|
- Add tests proving the same behavior with no scene bound.
|
|
- Add tests proving overlay/debug sits above the canonical game frame rather than being erased by it.
|
|
|
|
**File(s):**
|
|
- `crates/console/prometeu-system/src/virtual_machine_runtime/tests.rs`
|
|
- driver-level render tests where helpful
|
|
|
|
### Step 3 - Update stress/integration fixtures if needed
|
|
|
|
**What:**
|
|
Restore or improve stress scenarios that rely on visible text/primitives.
|
|
|
|
**How:**
|
|
- Update `pbxgen-stress` or related stress fixtures so text/primitives are once again a valid visible overlay signal.
|
|
- Keep the stress focused on the new model rather than reintroducing obsolete immediate-write assumptions.
|
|
|
|
**File(s):**
|
|
- `crates/tools/pbxgen-stress/src/lib.rs`
|
|
- `test-cartridges/stress-console/*`
|
|
|
|
## Test Requirements
|
|
|
|
### Unit Tests
|
|
- local ordering tests where runtime integration depends on helper sequencing
|
|
|
|
### Integration Tests
|
|
- runtime tests for scene-bound overlay/debug visibility
|
|
- runtime tests for no-scene parity
|
|
- stress/tooling validation that text or primitives are visible again as final overlay/debug
|
|
|
|
### Manual Verification
|
|
- run the stress path and visually confirm overlay/debug survives on top of scene/sprites after frame composition
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [ ] The runtime drains deferred overlay/debug after canonical game composition and after `hud_fade`.
|
|
- [ ] Scene-bound and no-scene paths expose the same overlay/debug semantics.
|
|
- [ ] Regression tests prove `draw_text(...)` is no longer erased by scene-backed frame composition.
|
|
- [ ] Stress/integration fixtures reflect the new final-overlay semantics where applicable.
|
|
|
|
## Dependencies
|
|
|
|
- Source decision: `DEC-0016`
|
|
- Depends on `PLN-0027`
|
|
|
|
## Risks
|
|
|
|
- If fades are still applied after overlay/debug drain, the visible contract will contradict `DEC-0016`.
|
|
- Incomplete parity between scene-bound and no-scene paths would leave runtime behavior mode-dependent.
|