140 lines
7.1 KiB
Markdown
140 lines
7.1 KiB
Markdown
---
|
|
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.
|