housekeep
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 60.68% (15277/25176)
* Branch Coverage: 53.63% (5781/10779)
* Lines of Code: 25176
* Cyclomatic Complexity: 9960
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 547
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 60.68% (15277/25176)
* Branch Coverage: 53.63% (5781/10779)
* Lines of Code: 25176
* Cyclomatic Complexity: 9960
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 547
Intrepid/Prometeu/Studio/pipeline/head This commit looks good
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
This commit is contained in:
-170
@@ -1,170 +0,0 @@
|
||||
---
|
||||
id: AGD-0031
|
||||
ticket: studio-frame-composer-syscall-and-sprite-alignment
|
||||
title: Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition
|
||||
status: in_progress
|
||||
created: 2026-04-18
|
||||
resolved: 2026-04-18
|
||||
decision: DEC-0027
|
||||
tags:
|
||||
- studio
|
||||
- compiler
|
||||
- pbs
|
||||
- stdlib
|
||||
- runtime-alignment
|
||||
- abi
|
||||
- syscall
|
||||
- frame-composer
|
||||
- sprites
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The sibling runtime has already moved the public frame-orchestration ABI to `composer.*`.
|
||||
|
||||
This repository still exposes the old model through `@sdk:gfx` and `Gfx.set_sprite`, which means:
|
||||
|
||||
- the Studio-side compiler and stdlib still teach a legacy public contract;
|
||||
- PBS examples and tests still lower sprite composition through the wrong owner;
|
||||
- specs still describe a source surface that no longer matches the runtime's canonical syscall boundary;
|
||||
- any new Studio work risks reinforcing a dual contract between `gfx.*` primitives and `composer.*` frame orchestration.
|
||||
|
||||
The user explicitly scoped this discussion to:
|
||||
|
||||
- ABI/syscall alignment with the current `../runtime`;
|
||||
- `FrameComposer` convergence for sprite composition;
|
||||
- Studio-side propagation across `compiler`, `pbs`, and `stdlib`;
|
||||
- `@sdk:composer` for the sprite-composition path;
|
||||
- removal of the legacy `Gfx.set_sprite` entrypoint;
|
||||
- no scene-bank implementation work in this ticket.
|
||||
|
||||
## Context
|
||||
|
||||
Domain owner: `studio`
|
||||
|
||||
Primary affected subdomains:
|
||||
|
||||
- `compiler/pbs`
|
||||
- `studio`
|
||||
|
||||
Expected propagation targets if this discussion closes:
|
||||
|
||||
- `docs/specs/compiler-languages/pbs`
|
||||
- `docs/specs/compiler`
|
||||
- PBS stdlib resources under `prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/resources/stdlib`
|
||||
- compiler/frontend/backend conformance tests
|
||||
- Studio-adjacent examples and fixtures that still import `@sdk:gfx` for sprite composition
|
||||
|
||||
Observed current state on 2026-04-18:
|
||||
|
||||
- `../runtime` lesson `DSC-0026` locks `FrameComposer` as the canonical frame owner above the render backend.
|
||||
- `../runtime` lesson `DSC-0027` locks the public VM-facing syscall ABI to `composer.bind_scene`, `composer.unbind_scene`, `composer.set_camera`, and `composer.emit_sprite`, and removes the legacy public `gfx.set_sprite` path.
|
||||
- `../runtime` lesson `DSC-0028` keeps immediate/debug primitives such as `gfx.draw_text` outside canonical game composition as a deferred overlay path.
|
||||
- this repository still ships `@sdk:gfx` with `LowGfx.set_sprite(...)` and `Gfx.set_sprite(...)`;
|
||||
- this repository does not yet expose a reserved `@sdk:composer` module;
|
||||
- docs and tests still use `@sdk:gfx` as the visible source surface for sprite composition.
|
||||
|
||||
This creates architectural drift:
|
||||
|
||||
- runtime public ownership says `composer.*` for frame composition;
|
||||
- Studio-side language and stdlib surfaces still say `gfx.*` for part of that same behavior.
|
||||
|
||||
The drift is specifically about syscall and sprite-composer alignment.
|
||||
|
||||
Out of scope for this agenda:
|
||||
|
||||
- `composer.bind_scene`, `composer.unbind_scene`, and `composer.set_camera` rollout in Studio;
|
||||
- scene-bank authoring workflows;
|
||||
- scene asset import/editor design;
|
||||
- scene bank build/materialization contracts beyond what is minimally needed to name ABI boundaries;
|
||||
- broader scene workspace/product decisions already separated into other discussions.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [x] Studio should expose a new reserved module `@sdk:composer` as the canonical public source surface for sprite composition.
|
||||
- [x] `@sdk:gfx` should remain limited to primitive/overlay/back-end-adjacent operations once sprite composition moves out.
|
||||
- [x] PBS should export `@sdk:composer` using the same source-level shape already used by `@sdk:gfx`: low-level host owner plus public service facade.
|
||||
- [x] Mutating composer operations should remain raw `int` status returns in v1 for now.
|
||||
- [x] Tests, fixtures, examples, and callsites should all migrate in this wave if possible; no compatibility path should be preserved.
|
||||
- [x] No temporary compatibility alias is acceptable; `Gfx.set_sprite` should be removed completely.
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Introduce `@sdk:composer` now for sprite emission only in this wave
|
||||
- **Approach:** Add a dedicated reserved stdlib module that exposes the sprite-composition path through `composer.emit_sprite`; migrate sprite composition calls, host metadata, docs, and tests to that module; keep `@sdk:gfx` for primitives/overlay-style operations only; defer Studio-side `bind_scene`, `unbind_scene`, and `set_camera`.
|
||||
- **Pro:** Matches the runtime's canonical service boundary, preserves the split between frame composition and render primitives, and avoids teaching the retired `gfx.set_sprite` contract.
|
||||
- **Con:** Introduces a partial first wave of the `composer` domain, so docs must be explicit that other composer operations are intentionally deferred rather than absent by accident.
|
||||
- **Maintainability:** Strong, because the public source surface mirrors the actual runtime ABI and ownership model.
|
||||
|
||||
### Option B - Keep `@sdk:gfx` as the user-facing module and only retarget its internals to `composer.*`
|
||||
- **Approach:** Preserve the visible `Gfx.set_sprite` API in Studio while changing lowering metadata underneath to hit `composer.emit_sprite`.
|
||||
- **Pro:** Smaller immediate source churn in examples and tests.
|
||||
- **Con:** Encodes the wrong owner in the public teaching surface, preserves the exact dual-contract problem the runtime discussion just removed, and makes later cleanup harder.
|
||||
- **Maintainability:** Weak, because it keeps historical naming instead of canonical service ownership.
|
||||
|
||||
### Option C - Add `@sdk:composer` but retain temporary `Gfx.set_sprite` compatibility in parallel
|
||||
- **Approach:** Introduce the new canonical module while leaving `Gfx.set_sprite` as an alias or transitional wrapper for one or more waves.
|
||||
- **Pro:** Softens migration pressure for existing examples and downstream users.
|
||||
- **Con:** Creates two public ways to express the same operation, invites drift in specs/tests/docs, and conflicts with the runtime lesson that legacy public fallbacks should be removed when they preserve the wrong model.
|
||||
- **Maintainability:** Medium at best in the short term, poor in the long term if the alias survives longer than intended.
|
||||
|
||||
## Discussion
|
||||
|
||||
The runtime side has already made two architectural facts explicit:
|
||||
|
||||
1. frame orchestration belongs to `FrameComposer`, not to `Gfx`;
|
||||
2. the public syscall namespace must reflect that ownership.
|
||||
|
||||
That means this repository is no longer choosing between equivalent naming styles.
|
||||
|
||||
It is choosing whether Studio will:
|
||||
|
||||
- align its source-facing contracts with the canonical runtime boundary; or
|
||||
- preserve a legacy public façade that the runtime has already declared misleading.
|
||||
|
||||
The user's scope also matters.
|
||||
|
||||
This ticket is not asking for scene-bank product work, and it also is not asking for Studio-side scene binding or camera rollout.
|
||||
So the migration target should stay narrow:
|
||||
|
||||
- syscall/domain alignment;
|
||||
- `@sdk:composer` surface alignment for sprite emission;
|
||||
- compiler/PBS/stdlib propagation;
|
||||
- tests and examples updated to stop asserting the retired path.
|
||||
- removal of the old `Gfx.set_sprite` path.
|
||||
|
||||
The remaining design work is therefore smaller and more concrete:
|
||||
|
||||
- define the Studio-side shape of `@sdk:composer` for sprite emission;
|
||||
- propagate `composer.emit_sprite` through stdlib, specs, compiler, and tests;
|
||||
- keep the deferred composer calls explicitly out of this ticket so the repository does not accidentally mix sprite convergence with unfinished scene-facing rollout.
|
||||
|
||||
The agenda questions are now resolved with explicit user direction:
|
||||
|
||||
1. `@sdk:composer` should follow the same editorial pattern already used by `@sdk:gfx`, meaning a low-level host owner plus a public service facade.
|
||||
2. `composer.emit_sprite` should continue returning a raw `int` status in this wave.
|
||||
3. Migration should be broad and immediate across tests, fixtures, and examples where feasible.
|
||||
4. `Gfx.set_sprite` should be removed entirely, with no compatibility alias or dual-path surface.
|
||||
5. Specs should document only what this wave actually implements, while leaving room for `bind_scene`, `unbind_scene`, and `set_camera` to be added later using the same pattern.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction:
|
||||
|
||||
- adopt Option A as the working direction for this discussion;
|
||||
- open a Studio-side canonical `@sdk:composer` surface aligned to the runtime ABI for sprite emission in this wave;
|
||||
- retire `Gfx.set_sprite` from normative Studio-facing contracts instead of preserving a compatibility façade;
|
||||
- defer `composer.bind_scene`, `composer.unbind_scene`, and `composer.set_camera` to a later ticket;
|
||||
- keep scene-bank authoring/editor work explicitly out of this ticket;
|
||||
- keep `@sdk:gfx` focused on primitive and overlay-style operations.
|
||||
|
||||
Recommended next step:
|
||||
|
||||
- treat the sprite-only `@sdk:composer` wave as the accepted scope of this agenda;
|
||||
- write a decision that locks:
|
||||
- `@sdk:composer` as the canonical Studio-side sprite-composition module;
|
||||
- the `LowComposer` + `Composer` shape matching the established `@sdk:gfx` pattern;
|
||||
- raw `int` status returns for this wave;
|
||||
- complete removal of `Gfx.set_sprite` with no compatibility path;
|
||||
- broad propagation across specs, stdlib, compiler, tests, fixtures, and examples;
|
||||
- deferred addition of `bind_scene`, `unbind_scene`, and `set_camera` in later work.
|
||||
Reference in New Issue
Block a user