Add shared human/task asset batches with reviewed atomic publication, explicit reference rebinds, ownership inspection and qualified glyph/scene budgets. Expose the same authoring and capacity results through Assets and MCP. Deliver isolated guest test targets, retained visual evidence and immutable runtime lifecycle/control observations. Preserve provider qualification and installed authoring examples alongside the completed discussion lessons. Close AGD-106 coordination and the delivered discussion workflows through housekeeping, updating lesson references and preserving qualification limits. Sound remains outside the asset delivery wave. Validation: 579 module tests and 31 additional desktop, process and installed checks passed; native glyph/scene 16/17 boundaries qualified. Discussion validation passed after housekeeping.
184 lines
10 KiB
Markdown
184 lines
10 KiB
Markdown
---
|
|
id: LSN-0108
|
|
ticket: pbs-logical-viewport-composition
|
|
title: Composition Reference Coverage and Studio Boundaries
|
|
created: 2026-11-10
|
|
tags: [studio, composer, documentation, diagnostics]
|
|
---
|
|
|
|
## Original problem and accepted outcome
|
|
|
|
**Owner:** `studio`, composition knowledge and authoring support independent of UI.
|
|
**Discussion:** DSC-0109, originating in AGD-0111.
|
|
|
|
A separate Zelda port exposed difficulty understanding the relationship between
|
|
terrain, camera, sprites, HUD, Gfx overlays and frame clearing. It also needed to
|
|
fit its original image into the Prometeu framebuffer. These observations prompted
|
|
an evaluation of useful support in Studio.
|
|
|
|
The user accepted the completed evaluation on 2026-11-10, requested coordination
|
|
with the umbrella and then explicitly requested housekeeping. The accepted
|
|
outcome is to retain the existing Studio product interfaces for this scope and
|
|
record the documentation/example gaps for the `compiler/pbs` content owner.
|
|
No Studio feature or service change was justified by the evaluated cases.
|
|
|
|
The evaluation and coordination are complete. No product implementation remains
|
|
in this discussion. The user requested direct housekeeping of this accepted
|
|
evaluation; no implementation plan or artificial code-change stage was created.
|
|
This lesson preserves the accepted conclusion after removal of the agenda.
|
|
|
|
## Responsibility boundaries
|
|
|
|
- The game project owns its presentation policy: viewport placement, borders,
|
|
offsets and rules needed to reproduce its original game. Existing HUD/layer
|
|
composition may implement borders, for example.
|
|
- Studio owns its integration of project knowledge and its existing automation
|
|
services. The language/SDK provider owns the content of its references.
|
|
- The runtime retains its existing execution and rendering contracts. This
|
|
discussion did not authorize runtime changes or commits.
|
|
- All UI improvements were excluded because a Studio UI replacement is planned.
|
|
That exclusion also prevents speculative services created only for a future UI.
|
|
- General authoring problems remain worth evaluating even if first observed in a
|
|
single game. Their origin does not make every local workaround a tool feature.
|
|
|
|
## What the audit established
|
|
|
|
Studio already exposes the project reference index through
|
|
`studio_project_context` and paginated text through `studio_reference_read`.
|
|
`CompilerProjectKnowledge` selects installed provider references for the current
|
|
project's SDK/target. The PBS build projects its canonical specifications, SDK
|
|
resources and example files into the installed reference index.
|
|
|
|
The installed Game/SDK 1 bundle contained **176 reference entries**:
|
|
|
|
| Kind | Entries |
|
|
| --- | ---: |
|
|
| SEMANTICS | 40 |
|
|
| SYNTAX | 1 |
|
|
| QUICKSTART | 1 |
|
|
| SDK | 28 |
|
|
| EXAMPLE | 106 |
|
|
|
|
EXAMPLE counts indexed files, not independent example projects. All 176 resources
|
|
matched their indexed SHA-256 hashes. The isolated installed probe paginated every
|
|
reference through the Studio knowledge service and reconstructed exactly the
|
|
provider's text. No reference-delivery defect was demonstrated in this scope.
|
|
|
|
The runtime's graphics specification is not an input of the PBS reference build.
|
|
Its absence from that catalog is not evidence that Studio dropped a page.
|
|
|
|
### Content coverage
|
|
|
|
| Topic | Existing coverage | Remaining content opportunity |
|
|
| --- | --- | --- |
|
|
| Composer/Gfx order | PBS chapter 5 calls Gfx primitive/overlay-oriented; bindings and signatures are available. | Explain final overlay order and why a clear can cover composed content. |
|
|
| Layers, priority and transparency | Parameter descriptions and the sprite-emission signature exist. | Explain operational composition with a small example, without assuming NES equivalence. |
|
|
| Camera, sprites and HUD | Camera bindings and sprite screen-coordinate descriptions exist. | Demonstrate the relationship between coordinate spaces and caller-owned transforms. |
|
|
| Empty background and clearing | Isolated Gfx examples exist. | Explain existing scene/no-scene behavior and demonstrate an appropriate empty-scene setup. |
|
|
| Visual query versus animation advance | PBS chapter 27 explicitly separates query/emission from playback advance. | No additional work justified by this question. |
|
|
| Fixed terrain and mutable objects | No complete general composition example was found in the audited example files. | Evaluate a neutral example independent of any port. |
|
|
|
|
`src/main.pbs` draws a moving Gfx rectangle. The production Gfx example uses
|
|
`fill_rect`. `src/animation.pbs` includes a helper calling `emit_sprite`, but the
|
|
audited PBS example files do not call `Composer.bind_scene` or
|
|
`Composer.set_camera`. These facts identify a content opportunity, rather than a
|
|
missing Studio operation.
|
|
|
|
The existing runtime contracts and sources were inspected read-only to check the
|
|
reported behavior. Future explanatory material must distinguish public contract
|
|
from implementation observations and preserve runtime ownership of execution.
|
|
|
|
## Recorded handoff to compiler/pbs
|
|
|
|
The owner of the distributed Composer/Gfx documentation and Game SDK 1 examples
|
|
can evaluate the following work in its own scope:
|
|
|
|
1. Improve explanations of composition order, coordinate spaces, priority,
|
|
transparency and clearing, using the existing execution contracts as authority.
|
|
2. Evaluate one complete neutral example with minimal owned resources, terrain,
|
|
actor, HUD, camera movement and mutable objects. Reuse the current reference
|
|
mechanism and SDK APIs; keep game-specific layout and occlusion policy local.
|
|
3. If an example is produced, qualify compilation, graphical execution and pixel
|
|
expectations separately through the existing headless path. A successful
|
|
compile alone does not establish correct visual output.
|
|
|
|
This handoff records a destination and concrete content gaps. It does not open a
|
|
new discussion, authorize implementation in another domain or promise a new SDK
|
|
API. Studio must not compensate with duplicated specifications or diagnostics
|
|
that classify valid game presentation choices as errors.
|
|
|
|
## Verification and evidence
|
|
|
|
The audit used Studio revision
|
|
`b351f2e5823039f82e3cd9666547578add13bebb`. The installed frontend JAR SHA-256 was
|
|
`780dc6f72755692731291d169d6f161eb47d0401579731753c5f59aa4a702f0e`.
|
|
|
|
**13 tests passed**, with no failures, errors or skips:
|
|
|
|
| Suite | Tests | What it verifies |
|
|
| --- | ---: | --- |
|
|
| ProjectReferencesTest | 6 | Studio reference integration, pagination, SDK selection and unavailable-reference handling. |
|
|
| PbsDocumentationTest | 5 | Provider/index consistency, exact SDK resources and supported selection. |
|
|
| InstalledKnowledgeTest | 2 | Isolated installed-JAR reads, complete paginated text and example compilation. |
|
|
|
|
The installed task was explicitly executed with `--rerun`; the result was not
|
|
merely reused from Gradle's up-to-date state.
|
|
|
|
```bash
|
|
./gradlew :prometeu-app:test --tests p.studio.app.compiler.ProjectReferencesTest :prometeu-compiler:frontends:prometeu-frontend-pbs:test --tests p.studio.compiler.pbs.documentation.PbsDocumentationTest --console=plain
|
|
./gradlew :prometeu-app:installedKnowledgeTest --rerun --console=plain
|
|
```
|
|
|
|
Preserved evidence:
|
|
|
|
- [Audit identity, integrity results and example occurrences](evidence/audit.json).
|
|
- [Installed reference-index snapshot](evidence/installed-reference-index.json).
|
|
- [Focused test log](evidence/knowledge-validation.log) and
|
|
[explicit installed-test execution log](evidence/installed-knowledge.log).
|
|
- [Studio reference test results](evidence/TEST-p.studio.app.compiler.ProjectReferencesTest.xml),
|
|
[provider test results](evidence/TEST-p.studio.compiler.pbs.documentation.PbsDocumentationTest.xml)
|
|
and [installed test results](evidence/TEST-p.studio.app.compiler.InstalledKnowledgeTest.xml).
|
|
|
|
The audit did not execute graphical rendering, compare pixels or exercise a
|
|
complete authenticated MCP HTTP session. Its evidence covers the neutral
|
|
knowledge integration, installed texts and compilation, not visual correctness.
|
|
No product code, specification, UI, SDK, runtime or port was changed.
|
|
|
|
## Coordination and remaining work
|
|
|
|
The [DSC-0104 / AGD-0106 umbrella](../DSC-0104-compiler-game-production-reliability/LSN-0113-coordinating-compiler-reliability-and-diagnostic-delivery.md)
|
|
preserves this accepted outcome as an external interface, preserving its existing
|
|
compiler reliability and diagnostics scope and its two agreed deliveries. This
|
|
content handoff does not become a new child, implementation gate or prerequisite
|
|
for closing that umbrella. The related assets discussion refers to this lesson
|
|
for the completed knowledge evaluation; it retains its own authoring/budget scope.
|
|
|
|
The prior [DSC-0108 installed examples lesson](../DSC-0108-pbs-production-contracts-executable-examples/LSN-0107-quoted-project-identities-and-installed-authoring-contracts.md)
|
|
remains valid. This later audit identifies composition coverage outside its
|
|
qualified corpus and does not reinterpret its acceptance or claim that graphics
|
|
were already tested there.
|
|
|
|
No further Studio implementation is pending for DSC-0109. Potential content work
|
|
remains a recorded handoff for its owner; UI improvements remain outside this
|
|
ticket and require their own future scope.
|
|
|
|
## Common mistakes
|
|
|
|
- Treating difficulty adapting a game's presentation as proof of a runtime gap.
|
|
- Adding a Studio endpoint before checking existing knowledge and headless APIs.
|
|
- Confusing incomplete source content with a broken Studio reference index.
|
|
- Duplicating language/SDK specifications in Studio to make text more accessible.
|
|
- Counting compilation or a reference hash match as proof of pixel correctness.
|
|
- Allowing a deferred UI feature to introduce speculative backend obligations.
|
|
- Reopening an umbrella's accepted deliverables through an external content handoff.
|
|
|
|
## Maintenance references
|
|
|
|
- [Studio 11, project knowledge and installed references](../../../docs/specs/studio/11.%20MCP%20Tools%20and%20Project%20Knowledge%20Contract.md).
|
|
- [Studio 10, automation and canonical capture](../../../docs/specs/studio/10.%20DEV%20and%20Automation%20Specification.md).
|
|
- [CompilerProjectKnowledge](../../../prometeu-app/src/main/java/p/studio/app/compiler/CompilerProjectKnowledge.java).
|
|
- [PBS reference generation](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/build.gradle.kts).
|
|
- [PBS documentation provider](../../../prometeu-compiler/frontends/prometeu-frontend-pbs/src/main/java/p/studio/compiler/pbs/documentation/PbsDocumentation.java).
|
|
- [InstalledKnowledgeProbe](../../../prometeu-app/src/test/java/p/studio/app/compiler/InstalledKnowledgeProbe.java).
|
|
- [Runtime graphics authority, read-only reference](../../../../runtime/docs/specs/runtime/04-gfx-peripheral.md).
|