bQUARKz
1fa9d13044
All checks were successful
JaCoCo Coverage #### Project Overview
No changes detected, that affect the code coverage.
* Line Coverage: 59.32% (17061/28759)
* Branch Coverage: 51.84% (6536/12607)
* Lines of Code: 28759
* Cyclomatic Complexity: 11399
#### Quality Gates Summary
Output truncated.
Test / Build skipped: 11, passed: 601
Intrepid/Prometeu/Studio/pipeline/pr-master This commit looks good
61 lines
3.7 KiB
Markdown
61 lines
3.7 KiB
Markdown
---
|
|
id: LSN-0046
|
|
ticket: studio-scene-pack-runtime-binary-contract
|
|
title: Canonical scene owns editorial truth while pack stays request-driven
|
|
created: 2026-05-01
|
|
tags: [studio, packer, runtime, scene, tiled, import-export]
|
|
---
|
|
|
|
## Context
|
|
|
|
`Scene Bank` needed a stable path from Studio authoring to runtime `SCENE` bytes without letting editor-specific files become the product contract. The first accepted direction closed the `studio -> packer -> runtime` boundary correctly, but the initial editorial implementation still treated `TMX` as if it were the unit of truth. That created friction because the supported external editor (`Tiled`) was being modeled around the wrong ownership boundary.
|
|
|
|
The final state of `DSC-0030` keeps the publication contract from `DEC-0029` and replaces only the mistaken editorial model through `DEC-0030`.
|
|
|
|
## Key Decisions
|
|
|
|
### Request-driven publication boundary
|
|
|
|
**What:** Publication of `Scene Bank` assets uses a canonical `studio -> packer` request that packer compiles directly into runtime `SCENE` payload bytes.
|
|
|
|
**Why:** This keeps `prometeu-packer` isolated from `TMX`, `TSX`, and any future editor-specific format. It also preserves runtime ownership of `glyph_asset_id -> slot` resolution instead of leaking runtime operational details back into Studio.
|
|
|
|
**Trade-offs:** Studio must project editorial state into a separate publication representation, so the system carries more than one representation of the same scene on purpose.
|
|
|
|
### Studio-owned canonical scene entity
|
|
|
|
**What:** The primary editorial source of truth is a Studio-native canonical scene entity, not `TMX`, not `TSX`, and not the pack request itself.
|
|
|
|
**Why:** The external editor format should remain replaceable. If `TMX` becomes the canonical model, Studio evolution gets trapped by Tiled semantics and every future interoperability choice becomes harder.
|
|
|
|
**Trade-offs:** Studio now owns more editorial modeling and validation logic internally instead of delegating shape decisions to external files.
|
|
|
|
### Tiled as compatibility, not authority
|
|
|
|
**What:** `TMX (Tiled)` scene import/export and `TSX (Tiled)` glyph export are compatibility workflows around the canonical scene entity.
|
|
|
|
**Why:** This preserves interoperability with the supported wave-1 tooling while making it explicit that external files are adapters, not authoritative persistence.
|
|
|
|
**Trade-offs:** Import must reject unsupported structural mutations instead of silently absorbing arbitrary external edits.
|
|
|
|
## Patterns and Algorithms
|
|
|
|
- Keep three representations distinct: Studio canonical scene entity, canonical pack request, and runtime `SCENE` bytes.
|
|
- Validate canonical scene integrity in `Analyse` and/or `Pack`, not by treating editor files as the lifecycle owner.
|
|
- Use import compatibility checks before mutating canonical state, and fail without partial rewrite on unsupported structural divergence.
|
|
- Keep packer request-driven so tests can prove scene packing succeeds without parsing `TMX` or `TSX`.
|
|
|
|
## Pitfalls
|
|
|
|
- Do not let a supported editor file become a hidden canonical model just because it is easy to serialize.
|
|
- Do not collapse the canonical Studio scene entity into the pack request; publication shape and editorial shape serve different purposes.
|
|
- Do not reintroduce `TMX per layer` or any equivalent workflow that makes scene cohesion secondary.
|
|
- Do not relax the packer boundary by teaching packer to read editor-native files directly.
|
|
|
|
## Takeaways
|
|
|
|
- Scene editorial truth belongs to Studio.
|
|
- Scene publication truth belongs to the canonical request.
|
|
- Runtime operational truth belongs to the runtime `SCENE` contract and slot resolution logic.
|
|
- Import/export support should stay replaceable as long as it materializes the same request boundary.
|