Tiled Parser and Scene & Palette Management in Studio
Test / Build occurred while executing withChecks step.
Intrepid/Prometeu/Studio/pipeline/head There was a failure building this commit
Intrepid/Prometeu/Studio/pipeline/pr-master There was a failure building this commit

This commit is contained in:
2026-04-23 18:08:38 +01:00
parent 9e128988e1
commit 42daa49335
101 changed files with 6065 additions and 1308 deletions
@@ -1,116 +0,0 @@
---
id: AGD-0002
ticket: palette-management-in-studio
title: Palette Management in Studio
status: open
created: 2026-03-26
resolved:
decision:
tags:
- studio
- legacy-import
- palette-management
- tile-bank
- packer-boundary
---
## Pain
Studio already has a retained agenda for palette management in the `glyph bank` form session, but that agenda exists only under `docs/studio/agendas/` and therefore sits outside the discussion-framework lifecycle.
Without importing it into `discussion/`, the canonical discussion surface would lose the still-open Studio question about:
- how candidate palettes are presented;
- how `1..64` palette capacity is enforced and explained;
- how preview and selection behave inside the asset workflow;
- how Studio UX stays separate from packer-owned extraction, validation, identity, and persistence.
## Context
Legacy source: `docs/studio/agendas/Palette Management in Studio Agenda.md`
Domain owner: `docs/studio`
Cross-domain impact: `docs/packer`
The retained agenda is intentionally scoped to `glyph bank`.
The imported context keeps the same baseline:
- every `*.png` input of a glyph bank is one tile;
- each tile yields one extracted palette during cache construction;
- developers may also work with favorite palettes and asset palettes;
- each bank may integrate at most `64` palettes;
- each palette contains `16` colors with a default color-key baseline;
- Studio owns curation UX, while packer remains authoritative for extraction, identity, validation, and persistence.
The current UI shape already converged on:
- a left-side transfer list for candidate and selected palettes;
- custom palette rendering with swatches and source indicators;
- a right-side preview panel with tile/file selector, tile preview, and applied palette strip.
## Open Questions
- [ ] How should Studio detect and present duplicate or near-equivalent palettes across tile-derived, favorite, and asset-level sources?
- [ ] Are favorites project-scoped references to existing palettes, or can they diverge into editable copies before bank admission?
- [ ] What is the canonical user-facing identity of a candidate palette in Studio: source bucket plus logical name, file path, extraction origin tile, stable id, or a combination?
- [ ] Should extracted tile palettes always enter the candidate set automatically, or can the developer suppress some of them before curation?
- [ ] Should clicking a palette on the `selected` side be the only interaction needed to change the previewed palette in the first wave?
- [ ] Which palette operations are read-only in the first wave, and which require staged preview/apply treatment?
- [ ] Which parts of this interaction model should remain explicitly `glyph bank`-specific, and which parts are reusable Studio form-session primitives?
- [ ] Does the first release need only an asset-scoped `glyph bank` section, or also a project-level palette browser for discovery and favorites management?
## Options
### Option A - Automatic Integration
- **Approach:** Treat extracted tile palettes as implicit inputs and integrate them automatically without explicit user curation.
- **Pro:** Lowest immediate UX cost.
- **Con:** Hides palette-budget reasoning, weakens deliberate composition, and makes source distinctions harder to understand.
- **Maintainability:** Weak. It pushes important bank rules into implicit behavior.
### Option B - Asset-Scoped Curated Selection
- **Approach:** Treat bank palettes as an asset-scoped curated selection built from tile-derived palettes, favorites, and asset palettes, with Studio owning the curation UX and packer owning persistence.
- **Pro:** Matches the concrete `glyph bank` workflow and keeps authority boundaries clear.
- **Con:** Requires explicit UX for capacity, identity, deduplication, and preview semantics.
- **Maintainability:** Strong. It makes responsibilities explicit and keeps family-specific rules close to the workflow that needs them.
### Option C - Studio-Owned Palette Library
- **Approach:** Treat palettes as a broader Studio-owned library/workspace with direct local editing and persistence behavior.
- **Pro:** Potentially flexible for future palette-heavy features.
- **Con:** Duplicates packer ownership and risks creating a second authority for bank composition.
- **Maintainability:** Weak. It expands Studio responsibility before the persistence contract is closed.
## Discussion
The imported agenda keeps the original recommendation intact: palette management should be first-class for `glyph bank`, but Studio must not become the persistence authority.
That means the key open problem is not whether palettes exist. It is how Studio explains and curates them safely:
- candidate aggregation from multiple sources;
- clear source and identity display;
- explicit `1..64` capacity feedback;
- a preview model that stays tied to the selected bank palettes;
- a boundary between `glyph bank`-specific UX and reusable Studio primitives.
The retained source already converged on a pragmatic first wave:
- transfer-list selection on the left;
- palette-focused preview on the right;
- first selected palette as default preview;
- clicking on a selected palette changes the previewed palette;
- removing the current preview palette falls back to the first remaining selected palette.
## Resolution
Recommended direction: adopt **Option B**.
The imported agenda preserves the retained Studio direction:
1. palette management belongs to the `glyph bank` asset workflow;
2. Studio aggregates candidate palettes from tile-derived extraction, favorites, and asset palettes;
3. the first wave uses a custom-rendered transfer list with an explicit `1..64` selected range;
4. the right-side preview panel stays tied to the current selected palette set;
5. packer remains authoritative for extraction, identity, validation, and persistence;
6. broader standalone palette-authoring workflows remain deferred.
Next step suggestion: convert this imported agenda into a decision that closes the ownership boundary, candidate-source model, first-wave transfer-list UX, preview behavior, and reusable-vs-family-specific primitive boundary.
@@ -1,329 +0,0 @@
---
id: AGD-0030
ticket: studio-tiled-parser-assets-scene-asset-type
title: Tiled Parser and Scene Asset-Type Ownership in Assets Workspace
status: accepted
created: 2026-04-15
resolved: 2026-04-17
decision: DEC-0027
tags:
- studio
- assets
- scene
- tiled
- parser
- asset-type
---
## Pain
The current abandoned direction assumed a dedicated `Scene Workspace` as the primary authoring owner for scenes.
That no longer matches the intended product direction.
Without a new direction:
- the Studio has no agreed path for scene authoring;
- the `Assets` workspace still lacks a defined ownership model for scene-like content;
- there is no agreed contract for importing or interpreting `Tiled` data;
- implementation risks rebuilding a custom scene editor model that the team has already decided to discard.
## Context
Domain owner: `studio`
Expected documentation owner:
- `docs/studio/specs`
Cross-domain impact:
- asset typing and creation flows in the `Assets` workspace;
- Studio-side parsing/import rules for `Tiled`;
- possible downstream alignment with runtime-facing `SCENE` publication, depending on the chosen import boundary.
- Studio-only specialization of glyph-bank assets into map, sprite, and UI authoring roles.
User direction explicitly provided on 2026-04-15:
- abandon `DEC-0026` and its derived plans;
- do not proceed with a dedicated `Scene Workspace`;
- instead, write a parser for `Tiled`;
- create a new asset type managed from the `Assets` workspace.
Additional direction explicitly provided on 2026-04-15:
- Studio-specific asset roles such as `Tileset`, `Sprites`, and `UI` remain glyph banks internally;
- those roles are editorial specializations in Studio rather than distinct runtime asset families;
- the specialization is stored as a Studio-only flag attached to glyph-bank asset creation and management;
- specialization does not need to lock general glyph-bank editing fields in this wave;
- specialization should instead enable role-specific Studio actions and flows;
- the asset summary should continue to show the base bank type and add the specialization as a complementary chip, such as `Type: Glyph Bank / Tileset`;
- Studio will expose role-specific commands, such as building a `tileset.tsx` from a `Tileset` glyph bank;
- validation of map/tileset consistency should remain centered on the `Scene Bank` rather than on hard-locking the `Glyph Bank`.
- specialization-specific actions should be stacked with the existing asset actions instead of introducing a separate action region between summary and actions.
This agenda exists to turn that direction into a disciplined technical recommendation rather than jumping directly into implementation with undefined ownership and file-contract assumptions.
## Open Questions
- [x] Which `Tiled` surface is the primary input contract: TMX XML, JSON export, TSX, or a constrained subset of those?
- [x] Is the new scene-facing asset a raw imported `Tiled` document, a normalized Studio-owned intermediate asset, or a published runtime-facing `SCENE` derivative?
- [x] Should `Assets` own only creation/import and metadata management, or also the main editing/reimport flow for `Tiled`-backed scene assets?
- [x] How should `Tiled` tileset references map onto Studio-owned `Tileset` glyph banks and their identity rules?
- [x] What parts of `Tiled` are intentionally out of scope for the first wave: object layers, properties, flips, collisions, infinite maps, templates, Wang sets, animations?
- [x] Does the parser need to preserve full round-trip fidelity with `Tiled`, or only import the supported subset into Studio-owned structures?
- [x] What is the canonical failure model when a `Tiled` document references unsupported constructs or broken external assets?
- [x] How should Studio persist the editorial role flag of a glyph bank (`Tileset`, `Sprites`, `UI`) without inventing a separate runtime family?
- [x] Which defaults become mandatory or locked for each Studio specialization at creation time?
- [x] Where do Studio role-specific commands such as `build tileset.tsx` live in the `Assets` UX?
## Options
### Option A - Import `Tiled` into a Studio-owned scene asset model linked to flagged glyph banks
- **Approach:** Keep `Glyph Bank` as the canonical asset type, add a Studio-only specialization flag such as `Tileset`, `Sprites`, or `UI`, and parse supported `Tiled` files into a Studio-owned scene asset managed from `Assets`.
- **Pro:** Aligns with the requested ownership shift, preserves the existing glyph-bank runtime model, and lets Studio attach role-specific rules, chips, defaults, and commands without multiplying runtime asset families.
- **Con:** Requires a precise Studio metadata model for the specialization flag and a clear mapping from `Tiled` tilesets to flagged glyph-bank assets.
- **Maintainability:** Strong, if the supported subset and ownership boundary are made explicit early.
### Option B - Treat `Tiled` files as external source documents and keep Studio as a thin importer/viewer
- **Approach:** Keep `Tiled` as the primary authoring format and let Studio mostly import, validate, and publish from it.
- **Pro:** Minimizes Studio-owned scene-model invention and stays close to existing `Tiled` authoring workflows.
- **Con:** Couples Studio behavior heavily to `Tiled`'s full document model and makes partial support/error handling harder to reason about.
- **Maintainability:** Medium, because unsupported `Tiled` breadth can leak into every implementation phase.
### Option C - Create a new Studio asset type unrelated to `Tiled` and only offer one-time conversion
- **Approach:** Use `Tiled` only as an optional bootstrap/import tool, then move fully into a separate Studio-native asset format.
- **Pro:** Gives Studio maximum control over the final asset model and future editing behavior.
- **Con:** Moves away from the user's stated direction of writing a `Tiled` parser as a central path and may reintroduce the same custom-model burden the previous direction had.
- **Maintainability:** Medium, but only if the conversion boundary is very clearly justified.
## Discussion
The key architectural change here is not only "use `Tiled`".
It is also a change in ownership:
- scene-related authoring/import should no longer justify a dedicated `Scene Workspace`;
- the `Assets` workspace becomes the management surface for the relevant asset type;
- any parser choice must therefore fit an asset-first workflow instead of a separate editor-first workflow.
- asset specialization such as `Tileset`, `Sprites`, and `UI` is a Studio concern layered over the existing glyph-bank runtime family.
That creates several decisions that should be made deliberately:
1. what exact `Tiled` contract Studio supports in wave 1;
2. whether Studio stores `Tiled` data directly or through a normalized asset form;
3. how `Tileset` glyph banks map to `Tiled` tilesets without creating identity ambiguity;
4. how Studio persists the specialization flag and summary-chip presentation without changing the runtime family model;
5. which creation defaults become locked by each specialization;
6. how much of `Tiled` fidelity is preserved versus normalized away;
7. whether editing is a reimport/update flow, a direct managed-asset flow, or some hybrid.
There is already one strong constraint from the user:
- the previous `Scene Workspace` split should be considered discarded;
- the new work should be organized around `Assets` plus a `Tiled` parser.
The current direction also suggests an important simplification:
- Prometeu can assume exactly one tileset per tilemap in its first wave;
- a `Scene Bank` may contain more than one tilemap asset in the same bank scope;
- each scene may contain up to `4` layers in wave 1;
- each scene layer is associated with one tilemap, so a scene bank may keep more than one `TMX` file in the same asset directory;
- the parser still needs to understand `Tiled` identifiers correctly, but the Studio-side scene model can intentionally narrow to one linked `Tileset` glyph bank per map;
- this keeps the runtime/editor model simpler while still using `Tiled` as the interchange and tooling format.
Another important clarification is now explicit:
- the `Assets` workspace remains the owner of asset management;
- `Glyph Bank` remains the base type shown in the asset summary;
- the Studio-only specialization appears as a complementary suffix or chip such as `Glyph Bank / Tileset`;
- specialization-specific behavior such as locked dimensions or generated `TSX` output belongs strictly to Studio behavior rather than the runtime asset contract.
- specialization-specific actions should reuse the existing actions surface rather than creating a new intermediate panel between summary and actions.
### Convergence pass - accepted Tiled surfaces and tileset handoff
#### 1. Supported Tiled surfaces for wave 1
Direction: the Studio integration surface for wave 1 uses both `TMX` and `TSX`.
Implications:
- `TMX` is the map-side surface used for tilemap generation and interchange;
- `TSX` is the tileset-side surface generated from a Studio `Glyph Bank` specialized as `Tileset`;
- JSON export is not the primary interoperability surface for this wave.
#### 2. Mapping from `Tileset` glyph banks to Tiled tilesets
Direction: a `Glyph Bank` flagged as `Tileset` generates the `TSX` representation for that bank.
Implications:
- the generated `TSX` is the Tiled-facing tileset surface for that glyph bank;
- the new `Scene Bank` may point to that generated `TSX` when generating a tilemap;
- this coupling is scoped to tilemap generation and consumption, not to a runtime asset-family split;
- `TSX` generation remains owned by the `Assets` workspace as Studio behavior over a `Glyph Bank`.
### Convergence pass - accepted Scene Bank and parser direction
#### 1. Persistence model of the new `Scene Bank`
Direction: the new `Scene Bank` MUST persist full `TMX` documents as its maintained Studio asset format, plus any additional support files needed by the asset.
Implications:
- the `Scene Bank` keeps `TMX` as the authoritative map-side document format rather than normalizing into a separate Studio-owned scene schema;
- one scene-facing asset directory may contain more than one `TMX` file, because a scene may bind distinct tilemaps to distinct layers;
- wave 1 limits each scene to at most `4` layers;
- the asset may include additional Studio support files alongside the maintained `TMX`;
- those support files own the Studio-side convention that maps scene layers to the corresponding tilemaps;
- the `Assets` workspace may expose a dedicated area to inspect and edit that scene-bank support data;
- `TMX` generation remains part of the Studio asset flow, but the generated `TMX` is also the canonical maintained map document for the asset bank;
- final pack materialization into a dedicated `assets.pa` representation is explicitly outside this wave.
Implementation note accepted during agenda convergence:
- the exact shape of the support files is intentionally deferred and may be discovered during implementation, as long as the final direction preserves an explicit layer-to-tilemap mapping owned by the scene-facing asset.
#### 2. Ownership of scene-asset management in `Assets`
Direction: the `Assets` workspace MUST fully manage the scene-facing asset lifecycle.
Implications:
- `Assets` owns creation, metadata, validation, consistency checks, and asset-facing operations for the `Scene Bank`;
- the heavy map-editing interaction is expected to occur in `Tiled`;
- Studio-side asset management remains responsible for consistency and integration around that external editing loop.
#### 3. Wave-1 parser requirement
Direction: wave 1 MUST include an XML parser capable of both reading and writing `TMX` and `TSX`.
Implications:
- XML is the required implementation surface for this wave;
- the Studio must be able to ingest existing `TMX` and `TSX` documents;
- the Studio must also emit `TMX` and `TSX` documents from its owned asset state.
#### 3a. Asset-file placement and reference model
Direction: `TSX` files are generated by the `Glyph Bank` asset specialized as `Tileset`, and `TMX` files are generated inside the scene-facing asset and must reference those generated `TSX` files in the tileset asset directories.
Implications:
- a `Tileset` specialization on a `Glyph Bank` owns the generation of the Tiled-facing `TSX` files for that asset;
- the scene-facing asset owns the generation and maintenance of the corresponding `TMX` files;
- each tilemap inside the scene-facing asset must reference exactly one generated `TSX` in wave 1;
- the reference path model between `TMX` and `TSX` must remain deterministic so the asset bank can be regenerated and validated safely.
Open precision still to be normalized in the future:
- the exact canonical naming convention for multiple `TMX` files in the same scene-bank directory is not yet fixed, but it must be canonical and must remain compatible with the layer-to-tilemap support-file convention.
#### 4. Pack boundary for the current wave
Direction: pack integration is NOT part of the current wave.
Implications:
- the current work should stay inside Studio until the asset model and Tiled interop are stabilized;
- no packer-facing publication or final asset-pack contract is required to move this agenda forward;
- later pack work will materialize the `TMX`/`TSX` asset mass plus support files into a dedicated binary representation.
#### 5. Persistence of the Studio-only specialization flag
Direction: the editorial specialization should be represented internally as an enum and stored on the Studio-controlled asset entity that already owns asset metadata.
Implications:
- the flag remains Studio-only and does not redefine the runtime asset family;
- the enum should encode membership such as `Tileset (GlyphBank)`, making filtering and applicability rules explicit;
- persistence should reuse the existing Studio/asset metadata home rather than inventing a separate document just for the specialization flag;
- the current working assumption is that this persistence may belong alongside the asset entity already controlled by Studio tooling, pending code-level confirmation of the exact home.
#### 6. Validation ownership and specialization limits in wave 1
Direction: specialization should unlock Studio-specific actions, but it should NOT hard-lock general glyph-bank editing in this wave.
Implications:
- a specialization such as `Tileset`, `Sprites`, or `UI` primarily controls which Studio actions and flows are available for that glyph bank;
- the base glyph-bank runtime/editor model remains flexible in wave 1;
- consistency checks that depend on how the glyph bank is used in a map should be enforced by the `Scene Bank`;
- this keeps wave-1 constraints aligned with the runtime flexibility instead of prematurely freezing the glyph-bank editor surface.
#### 7. Diagnostic and blocking model
Direction: scene and Tiled consistency issues should use the same diagnostic pattern already used by glyph assets.
Implications:
- invalid or unsupported references should surface as Studio diagnostics;
- the same diagnostic discipline should block pack when inconsistencies remain;
- this keeps the failure model aligned with the existing asset-validation experience rather than introducing a second error system.
#### 7a. External-edit acceptance workflow
Direction: wave 1 MUST use an explicit acceptance workflow between Studio-owned scene assets and external `Tiled` edits.
Implications:
- the initial workflow is: create the scene asset in Studio, edit the generated `TMX`/`TSX` documents in `Tiled`, then return to Studio to validate and explicitly accept the resulting changes;
- a scene bank is considered ready only after Studio validation succeeds and the user explicitly accepts the converged state;
- Studio remains the place where external edits are reviewed and accepted, rather than auto-merging them silently.
#### 8. Supported Tiled feature subset in wave 1
Direction: wave 1 should support `Object Layers`, properties, flips, and collisions from the start.
Implications:
- collisions should be supported in both places that Tiled can represent them for this workflow;
- tile-owned collision may live in the `TSX` side of a specialized `Tileset` glyph bank;
- map-owned collision must be represented through `Object Layer` content in the `TMX` side of the `Scene Bank`;
- map-side `Object Group` support is useful because the pipeline will gradually absorb additional features such as collision, camera boundaries, lights, and similar scene annotations;
- the remaining unsupported Tiled features for this wave are the broader feature set outside this accepted subset, such as infinite maps, templates, Wang sets, and animations, unless later narrowed by a follow-up decision.
### Future note - possible collision-pipeline consolidation
This agenda also records a possible future pipeline direction that is explicitly outside the current wave:
- once collision support becomes mature enough, the pipeline may generate a canonical map-side `objectgroup` dedicated to collision, such as `collision`;
- that generated layer could read or derive effective collision information from tile-owned collision definitions and map-authored collision content;
- the pack pipeline could then consume that consolidated collision layer as the immediate source for collision materialization in the packed asset output.
Important boundary:
- this is a future optimization and publication-direction note, not a wave-1 authoring rule;
- authored collision and generated collision layers must remain conceptually separate until a later decision formalizes that pipeline stage.
### Convergence pass - accepted local UX direction
#### 1. Placement of specialization-specific actions in `Assets`
Recommendation: specialization-specific actions should be stacked together with the existing asset actions.
Reasoning:
- the current `Assets` workspace already has an established actions surface;
- introducing a second action region between summary and actions would fragment the UX without adding a clearer ownership model;
- specialization-specific commands remain asset actions and do not need a separate structural host.
Accepted local direction for this agenda:
- the `Assets` workspace MUST NOT introduce a separate action region between summary and actions for specialization-specific commands;
- commands such as `build tileset.tsx` SHOULD appear in the same action stack as the existing asset actions;
- visibility and enablement of those commands SHOULD be driven by the Studio-only specialization flag of the glyph bank;
- the summary remains responsible for identity and type presentation, including the complementary specialization chip.
That makes Option A the current best fit for convergence, and the latest discussion now also closes the first-wave one-tileset-per-tilemap rule, `TMX`/`TSX` asset ownership, and the explicit Studio-side acceptance workflow for external `Tiled` edits. The remaining work is to turn those accepted directions into a precise decision text while marking the support-file shape and multi-`TMX` naming convention as intentionally deferred implementation details.
## Resolution
Recommended next step:
- write a replacement decision for `Scene Bank` ownership in `Assets`;
- codify `TMX` as the maintained map document format and `TSX` as the tileset-facing generated format;
- codify the first-wave rule of exactly one tileset per tilemap, while allowing more than one tilemap inside a `Scene Bank`;
- codify the Studio-only glyph-bank specialization-flag model for `Tileset`, `Sprites`, and `UI`;
- codify the wave-1 supported `Tiled` subset, validation model, and explicit acceptance flow for external edits;
- carry forward the support-file shape and multi-`TMX` naming convention as deferred implementation details rather than pretending they are already closed.