67 lines
2.3 KiB
Markdown
67 lines
2.3 KiB
Markdown
---
|
|
id: PLN-0077
|
|
ticket: render-frame-packet-boundary
|
|
title: Composer Buffer and Game2D Packet
|
|
status: done
|
|
created: 2026-05-25
|
|
ref_decisions: [DEC-0030]
|
|
tags: [gfx, renderer, runtime, frame-composer, architecture, ui, pipeline]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
Source decision: `DEC-0030`.
|
|
|
|
Convert current `composer.*` frame state into a mutable `ComposerBuffer` that closes into `Game2DFramePacket` at frame boundary.
|
|
|
|
## Target
|
|
|
|
Game 2D scene, camera, sprites, HUD, and frame orchestration are represented as domain-owned state until `RenderManager` closes them into a typed packet.
|
|
|
|
## Scope
|
|
|
|
- Add `ComposerBuffer`.
|
|
- Move scene, camera, sprite, HUD, layer ordering, and Game 2D orchestration state into the buffer.
|
|
- Close the buffer into `Game2DFramePacket`.
|
|
- Preserve the v1 four-layer scene/sprite composition model and HUD-above-game rule.
|
|
- Ensure fade is absent from Game 2D packet state.
|
|
|
|
## Out of Scope
|
|
|
|
- Primitive `gfx2d.*` command buffering.
|
|
- Shell UI packet work.
|
|
- Renderer consumption refactor beyond packet shape.
|
|
- New Game 2D features.
|
|
|
|
## Execution Sequence
|
|
|
|
1. Locate current `FrameComposer`, composer syscalls, scene/camera/sprite/HUD state, and tests.
|
|
2. Introduce `ComposerBuffer` and migrate composer mutation paths into it.
|
|
3. Implement closure into `Game2DFramePacket` with immutable packet contents.
|
|
4. Preserve integer layer ordering across the four Game 2D layers and HUD final composition.
|
|
5. Route frame closure through `RenderManager`.
|
|
6. Update tests that currently inspect `FrameComposer` internals.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `composer.*` owns Game 2D high-level frame state.
|
|
- Closed `Game2DFramePacket` contains all data required by the Game 2D renderer without live VM or `Gfx` access.
|
|
- Scene/sprite layer behavior and HUD ordering are preserved.
|
|
- Fade is not represented.
|
|
|
|
## Tests / Validation
|
|
|
|
- Add unit tests for buffer mutation and packet closure.
|
|
- Add composition ordering tests for scene, sprites, and HUD.
|
|
- Run current frame composer/render tests and compare existing expected output.
|
|
|
|
## Risks
|
|
|
|
- Existing composer code may mix orchestration with drawing; split state capture from rendering before deeper migration.
|
|
- Layer behavior is user-visible and must not drift.
|
|
|
|
## Affected Artifacts
|
|
|
|
- Composer/frame-composer modules under `crates/`
|
|
- Game 2D tests
|