--- id: DEC-0027 ticket: studio-tiled-parser-assets-scene-asset-type title: Tiled Parser and Scene Bank Asset Ownership in Assets Workspace status: accepted created: 2026-04-17 accepted: 2026-04-17 agenda: AGD-0030 plans: [] tags: - 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.