Intrepid/prometeu-studio
Intrepid/prometeu-studio
4
0
Fork 0
Code Pull Requests Activity
prometeu-studio/discussion/workflow/decisions/DEC-0030-studio-native-scene-canonical-model-with-tiled-import-export.md

7.5 KiB
Raw Blame History

id ticket title status created accepted agenda plans tags
DEC-0030 studio-scene-pack-runtime-binary-contract Studio-native scene canonical model with Tiled import-export compatibility accepted 2026-04-30 2026-04-30 AGD-0033
PLN-0062
PLN-0063
PLN-0064
studio
packer
runtime
scene
asset-pack
tiled
import-export
revision

Decision

Scene Bank authoring in studio SHALL move to a Studio-native canonical scene model.

TMX and TSX SHALL remain supported formats, but only as import/export and compatibility surfaces. They MUST NOT be treated as the primary editorial model, the validation target, or the canonical publication state.

The Studio workflow for scenes SHALL NOT use generate, validate, or accept over TMX, per-layer TMX, or any equivalent editor-owned surface. Instead, Studio SHALL own:

  • a canonical scene entity for the asset itself;
  • import from supported external formats into that canonical scene entity;
  • export from that canonical scene entity into supported external formats.

For wave 1 of this revision:

  • Tiled SHALL be the first supported import/export option;
  • TMX scene import SHALL update the canonical scene entity from the external file;
  • TMX scene export SHALL overwrite the target TMX or create it if missing;
  • glyph-bank TSX generation SHALL be treated as TSX (Tiled) export and SHALL overwrite the target TSX or create it if missing.

Validation SHALL occur over the canonical Studio scene entity during Analyse and/or Pack. The canonical Studio scene entity SHALL remain distinct from the studio -> packer scene-pack request, and that request SHALL remain distinct from the runtime SCENE binary payload.

This decision SHALL supersede the editorial-model portion of DEC-0029. It SHALL preserve the parts of DEC-0029 that define:

  • the canonical studio -> packer boundary as normative for publication;
  • TMX/TSX as non-canonical supported surfaces;
  • prometeu-packer as compiler of the canonical request only;
  • runtime ownership of glyph_asset_id -> slot resolution and of the final SCENE payload contract.

Rationale

The previous direction corrected the publication boundary but still modeled the editorial surface around the wrong unit. Treating layers as separate TMX files forced the Studio workflow to move against the natural structure of supported external editors and produced a brittle acceptance model.

Even revising that approach to a single TMX per scene would still make the external format too central. The selected direction avoids that trap by making the Studio's own scene entity the owner of editorial truth, while keeping Tiled available as an interoperability surface.

This preserves long-term flexibility:

  • multiple external scene editors MAY be supported later;
  • the packer boundary remains editor-agnostic;
  • the runtime contract remains untouched;
  • editorial tooling can evolve independently of external file formats.

Technical Specification

1. Canonical Scene Ownership

  • studio SHALL persist and operate on a canonical scene entity owned by the Studio domain.
  • That canonical scene entity MUST be the source of truth for scene editorial state.
  • The canonical scene entity MUST NOT be conflated with a TMX, TSX, or any other editor-specific file.
  • The canonical scene entity MUST NOT be conflated with the studio -> packer request.

2. External Format Support

  • TMX and TSX SHALL be treated as supported interoperability formats.
  • Studio SHALL expose import/export operations for supported formats through wizard-driven workflow.
  • Tiled SHALL be the initial supported option for both scene and glyph-bank interoperability.
  • Import/export MAY later support additional formats without changing the canonical publication boundary.

3. Import Semantics

  • import MUST read a supported external file and project its compatible content into the canonical Studio entity.
  • import MUST perform minimum structural compatibility validation before mutating canonical state.
  • import MUST fail explicitly, with logs or diagnostics, when the external file diverges in unsupported structural ways.

Examples of structural divergence that MUST be treated as import failures unless explicitly supported by a later decision:

  • unexpected new layers;

  • unexpected new tilesets;

  • unexpected structural modification of existing layers or tilesets;

  • equivalent external mutations that the Studio compatibility contract does not accept.

  • Failed import MUST NOT silently partially rewrite canonical scene state.

4. Export Semantics

  • export MUST serialize the canonical Studio entity into the selected supported format.
  • TMX export MUST overwrite the destination file if present, or create it if absent.
  • TSX export for glyph tilesets MUST overwrite the destination file if present, or create it if absent.
  • Exported files are compatibility artifacts. They MUST NOT become the canonical source of truth by virtue of existing on disk.

5. Validation Surface

  • Validation of scene correctness SHALL target the canonical Studio scene entity.
  • Analyse and Pack SHALL be the normative validation surfaces for canonical scene integrity.
  • External files MAY be validated for import compatibility during import, but that validation does not replace canonical scene validation.
  • The old validate layer, accept layer, validate scene from TMX, and accept scene from TMX workflow MUST be removed or replaced so it no longer defines the editorial lifecycle.

6. Separation of Contracts

The system SHALL preserve three distinct layers of representation:

  1. the canonical Studio-owned scene entity;
  2. the canonical studio -> packer scene-pack request derived from that entity;
  3. the runtime SCENE binary payload derived by prometeu-packer.

Normative implications:

  • the canonical scene entity MAY evolve editorially without forcing the same shape onto the pack request;
  • the pack request MUST remain a publication projection, not the editorial persistence model;
  • packer MUST continue compiling only the canonical request, never TMX, TSX, or any other editor-native file directly.

7. Preserved Rules from DEC-0029

This decision intentionally preserves the following normative rules from DEC-0029:

  • TMX/TSX remain supported but non-canonical;
  • the publication contract remains the canonical studio -> packer request;
  • prometeu-packer MUST NOT parse editor-specific formats directly;
  • runtime SCENE continues to depend on glyph_asset_id per layer;
  • runtime slot resolution remains runtime-owned;
  • any future change to the request shape or runtime payload contract still requires explicit decision review.

Constraints

  • This decision MUST NOT be interpreted as making Tiled deprecated or unsupported.
  • This decision MUST NOT be interpreted as collapsing the canonical Studio scene entity into the pack request.
  • This decision MUST NOT be interpreted as allowing import to accept arbitrary external edits without compatibility checks.
  • This decision MUST NOT be interpreted as preserving the old TMX per layer model.
  • This decision does not yet define the full canonical scene schema; that schema SHALL be specified by downstream plans and spec propagation derived from this decision.

Revision Log

  • 2026-04-30: Initial draft from AGD-0033.
  • 2026-04-30: Explicitly supersedes the editorial-model portion of DEC-0029 while preserving its canonical publication boundary.
  • 2026-04-30: Accepted and decomposed into implementation plans PLN-0062, PLN-0063, and PLN-0064.