prometeu-studio/discussion/workflow/decisions/DEC-0027-tiled-parser-and-scene-bank-asset-ownership.md

id	ticket	title	status	created	accepted	agenda	plans	tags
DEC-0027	studio-tiled-parser-assets-scene-asset-type	Tiled Parser and Scene Bank Asset Ownership in Assets Workspace	accepted	2026-04-17	2026-04-17	AGD-0030		studio assets scene tiled parser asset-type

Context

The previous Scene Workspace direction was explicitly abandoned and MUST NOT be reused as the basis for new planning or implementation.

The replacement direction is asset-first:

• scene-facing ownership belongs to the Assets workspace;
• Tiled is the external authoring and interchange surface for wave 1;
• Glyph Bank remains the base runtime asset family for bank assets;
• Studio-specific roles such as Tileset, Sprites, and UI are editorial specializations only and MUST NOT create new runtime asset families.

This decision closes the ownership, persistence, interoperability, and validation baseline needed to plan and implement the first wave.

Decision

The Studio SHALL adopt an asset-first Scene Bank model managed from the Assets workspace.

Wave 1 SHALL use TMX and TSX as the Tiled-facing asset formats:

• a Scene Bank MUST maintain full TMX documents as its canonical map-side asset documents;
• a Glyph Bank specialized as Tileset MUST generate the TSX files used by scene tilemaps;
• each tilemap MUST reference exactly one generated TSX file in wave 1;
• a Scene Bank MAY contain more than one tilemap and therefore more than one TMX file in the same asset directory;
• each scene MAY contain up to 4 layers in wave 1;
• each scene layer MUST map to exactly one tilemap;
• the layer-to-tilemap convention MUST be owned by Studio support files that live with the scene-facing asset.

The Studio SHALL own creation, metadata, validation, consistency checks, and asset-facing operations for Scene Bank assets.

Heavy map editing for wave 1 SHALL occur in Tiled, not in a dedicated Studio scene editor workspace.

Rationale

This direction preserves the explicit user request to replace the discarded scene-workspace model with:

• a parser for Tiled;
• a new scene-facing asset managed from Assets;
• Studio-only specialization over existing Glyph Bank assets instead of runtime-family multiplication.

Keeping TMX as the maintained scene document avoids inventing a parallel normalized scene schema before the Tiled integration boundary is proven in practice.

Keeping TSX generation attached to Tileset-specialized glyph banks preserves a clear ownership split:

• tileset-facing generation belongs to the specialized glyph-bank asset;
• scene-facing tilemap maintenance belongs to the scene asset;
• runtime publication remains deferred until the Studio-side asset model stabilizes.

The explicit acceptance workflow also prevents silent drift between Studio-owned asset state and externally edited Tiled documents.

Technical Specification

1. Asset ownership and specialization

• The Assets workspace MUST remain the management surface for Scene Bank assets.
• Glyph Bank MUST remain the base asset type shown in summaries.
• The Studio-only specialization flag MUST be stored on Studio-controlled asset metadata.
• The specialization flag MUST be represented as an internal enum or equivalent closed set.
• The specialization flag MUST NOT redefine the runtime asset family.
• Specialization-specific actions MUST appear in the existing asset actions surface.
• The summary SHOULD present the base type plus specialization chip, for example Glyph Bank / Tileset.

2. Scene Bank persistence

• A scene-facing asset directory MAY contain multiple TMX files.
• The maintained scene-bank format MUST keep TMX in full rather than translating the asset into a separate normalized Studio scene format.
• The asset MAY contain additional support files owned by Studio.
• Those support files MUST encode the mapping between scene layers and tilemaps.
• The exact support-file schema is intentionally deferred to implementation and MAY be discovered on the fly, but the resulting contract MUST remain explicit and deterministic.

3. Tiled surfaces and parser contract

• Wave 1 MUST support XML read/write for both TMX and TSX.
• JSON export MUST NOT be treated as the primary interoperability surface in wave 1.
• Studio MUST be able to ingest supported TMX and TSX documents.
• Studio MUST be able to emit supported TMX and TSX documents from its owned asset state.

4. Tilemap, tileset, and layer rules

• Each tilemap MUST reference exactly one Tileset glyph-bank generated TSX.
• One scene MAY contain multiple tilemaps.
• Each scene MAY contain at most 4 layers in wave 1.
• Each layer MUST point to one tilemap through the scene-bank support files.
• The naming convention for multiple TMX files in one scene-bank directory is deferred, but the final convention MUST be canonical and MUST remain compatible with the layer-to-tilemap mapping.

5. Supported Tiled subset in wave 1

• Wave 1 MUST support Object Layers, properties, flips, and collisions.
• Tile-owned collision MAY be represented on the TSX side of a Tileset glyph bank.
• Map-owned collision MUST be represented through Object Layer content on the TMX side of the Scene Bank.
• Infinite maps, templates, Wang sets, and animations are outside wave 1 unless revised by a later decision.

6. Validation and acceptance workflow

• The initial workflow SHALL be:
  1. create the scene-facing asset in Studio;
  2. edit the generated TMX and TSX documents in Tiled;
  3. return to Studio;
  4. validate the resulting state;
  5. explicitly accept the converged changes.
• Studio MUST surface invalid, unsupported, or broken references as diagnostics using the same general diagnostic discipline already used for glyph assets.
• Studio MUST NOT silently auto-accept external Tiled edits.
• A Scene Bank is ready only after Studio validation succeeds and the user explicitly accepts the resulting state.
• The same diagnostic discipline SHOULD block later pack publication when inconsistencies remain.

7. Pack boundary

• Pack integration is explicitly outside this wave.
• Wave-1 work MUST stay inside Studio asset management and Tiled interoperability.
• Later pack work MAY materialize the TMX/TSX asset mass plus support files into a dedicated binary representation.

Constraints

• This decision supersedes the abandoned Scene Workspace direction and MUST be treated as the normative replacement for wave-1 planning.
• Plans derived from this decision MUST NOT reintroduce a dedicated scene workspace or a separate normalized Studio-owned scene format unless the user explicitly requests a revised decision.
• Plans derived from this decision MUST preserve the external-edit acceptance step as a required gate.
• Plans derived from this decision MUST treat the support-file schema and multi-TMX naming convention as deferred implementation details, not as permission to weaken the layer-to-tilemap contract.
• Any future move toward automatic convergence, multi-tileset tilemaps, or pack-facing publication contracts requires a new decision or explicit revision of this one.

Revision Log

• 2026-04-17: Initial accepted decision from AGD-0030.