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

---
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.