---
id: LSN-0045
ticket: studio-tiled-parser-assets-scene-asset-type
title: Asset-Owned Scene Bank and Tiled XML Workflow
created: 2026-04-23
tags:
  - studio
  - assets
  - scene-bank
  - tiled
  - tmx
  - tsx
---

## Context

The abandoned scene-workspace direction was replaced by an asset-first model. Scene authoring and validation now belong to the `Assets` workspace, while heavy map editing remains external in Tiled.

The final model keeps runtime asset families disciplined:

- `Scene Bank` is the scene-facing asset managed by Studio.
- `Glyph Bank` remains the base family for tilesets.
- `Tileset`, `Sprites`, and `UI` are Studio-only glyph-bank specializations, not new runtime families.

## Key Decisions

### Scene Banks Are Assets, Not Workspaces

**What:** Scene-bank lifecycle is owned by the `Assets` workspace: creation, metadata, layer configuration, validation, acceptance, and diagnostics.

**Why:** The product direction explicitly discarded a dedicated scene workspace. Asset ownership keeps scene work aligned with existing asset actions, summaries, diagnostics, and refresh flows.

**Trade-offs:** Studio does not provide a heavy map editor in this wave. Users edit `TMX` and `TSX` externally in Tiled, then return to Studio for validation and acceptance.

### TMX and TSX Are the Wave-1 XML Surfaces

**What:** Wave 1 supports XML read/write for `TMX` map documents and `TSX` tileset documents.

**Why:** Tiled is the interoperability surface. Keeping `TMX` as the maintained scene document avoids inventing a parallel normalized scene schema too early.

**Trade-offs:** Unsupported Tiled features must fail explicitly rather than being silently normalized away.

### Tileset Specialization Stays Studio-Only

**What:** A `Glyph Bank / Tileset` specialization generates the Tiled-facing `TSX` document for that glyph bank.

**Why:** Tileset generation is editorial Studio behavior over a glyph bank. It should not leak into runtime family identity.

**Trade-offs:** The asset summary must show both the base type and specialization so users understand the role without confusing it for a new runtime asset family.

### Scene Validation Requires Explicit Acceptance

**What:** A scene bank is not ready merely because files exist. Studio validates the current `TMX`/`TSX` state and requires explicit acceptance of the converged result.

**Why:** External editing can change files behind Studio's back. Acceptance makes the boundary deliberate and auditable.

**Trade-offs:** Users must perform an extra validation/accept step after external edits, but Studio avoids silently blessing invalid or unsupported scene state.

## Patterns and Algorithms

### Scene-Bank Support Metadata

Scene-bank support metadata lives with the scene asset and records the wave-1 layer model:

- fixed `1..4` scene layers;
- per-layer enabled state;
- per-layer `tilemap` filename;
- per-layer linked `tileset_asset_root`;
- map dimensions and explicit layer-to-tilemap binding.

This support file is the Studio-owned convention that lets a scene bank contain multiple maintained `TMX` documents while preserving deterministic layer mapping.

### Tiled File Generation

`Tileset` glyph banks generate `TSX` files. Scene banks generate or maintain layer-specific `TMX` files that reference those generated `TSX` files.

Each wave-1 tilemap references exactly one generated `TSX`. Multi-tileset maps remain outside this wave.

### Validation and Acceptance Files

Scene validation records the inspected file state and diagnostics. Acceptance records the validated state that Studio has explicitly approved.

This creates a useful external-edit loop:

1. generate or edit `TMX`/`TSX`;
2. validate in Studio;
3. inspect diagnostics;
4. accept only after validation succeeds.

## Pitfalls

- Do not reintroduce a dedicated scene workspace for wave 1.
- Do not turn `Tileset` specialization into a runtime asset family.
- Do not silently auto-accept external Tiled edits after refresh.
- Do not treat `TMX`/`TSX` generation as pack publication. Runtime scene packing remains a separate later concern.
- Do not allow unsupported Tiled constructs to disappear quietly. They must surface as diagnostics.

## Takeaways

- Scene Bank belongs in Assets, not in a separate authoring workspace.
- `TMX` remains the maintained scene document for wave 1.
- `TSX` generation belongs to `Glyph Bank / Tileset`.
- Validation plus explicit acceptance is the core safety gate for external Tiled editing.
