diff --git a/discussion/workflow/agendas/AGD-0030-tiled-parser-and-scene-asset-type.md b/discussion/workflow/agendas/AGD-0030-tiled-parser-and-scene-asset-type.md index d4532eb4..898d19e5 100644 --- a/discussion/workflow/agendas/AGD-0030-tiled-parser-and-scene-asset-type.md +++ b/discussion/workflow/agendas/AGD-0030-tiled-parser-and-scene-asset-type.md @@ -41,6 +41,7 @@ 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: @@ -49,24 +50,39 @@ User direction explicitly provided on 2026-04-15: - 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 -- [ ] Which `Tiled` surface is the primary input contract: TMX XML, JSON export, TSX, or a constrained subset of those? -- [ ] Is the new asset type a raw imported `Tiled` document, a normalized Studio-owned intermediate asset, or a published runtime-facing `SCENE` derivative? -- [ ] Should `Assets` own only creation/import and metadata management, or also the main editing/reimport flow for this new asset type? -- [ ] How should tileset references inside `Tiled` map onto existing glyph-bank assets and asset identity rules in Studio? -- [ ] What parts of `Tiled` are intentionally out of scope for the first wave: object layers, properties, flips, collisions, infinite maps, templates, Wang sets, animations? -- [ ] Does the parser need to preserve full round-trip fidelity with `Tiled`, or only import the supported subset into Studio-owned structures? -- [ ] What is the canonical failure model when a `Tiled` document references unsupported constructs or broken external assets? +- [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 new Studio-owned scene asset type in `Assets` -- **Approach:** Introduce a new asset type in `Assets`; parse supported `Tiled` files into a Studio-owned asset model managed from that workspace. -- **Pro:** Aligns with the requested ownership shift, keeps authoring/import centered in `Assets`, and allows Studio to define a strict supported subset. -- **Con:** Requires defining a clean normalized asset contract and a mapping layer from `Tiled` concepts to Studio/runtime concepts. +### 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 @@ -90,26 +106,187 @@ 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 glyph banks and tilesets map without creating identity ambiguity; -4. how much of `Tiled` fidelity is preserved versus normalized away; -5. whether editing is a reimport/update flow, a direct managed-asset flow, or some hybrid. +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. -That makes Option A the current best fit for convergence, but it still needs the agenda to narrow the supported `Tiled` subset and the resulting asset contract before a new decision can be written. +The current direction also suggests an important simplification: + +- Prometeu can assume one tileset per tilemap in its first wave; +- 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 its own Studio-owned asset format. + +Implications: + +- the `Scene Bank` is not a raw persisted `TMX` document; +- the Studio-owned format MUST retain the identity relationships and internal references needed to regenerate `TMX` deterministically; +- the Studio may generate and keep the corresponding `TMX` as a derived Tiled-facing artifact for the asset; +- final pack materialization into a dedicated `assets.pa` representation is explicitly outside this wave. + +#### 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. + +#### 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 normalized; +- no packer-facing publication or final asset-pack contract is required to move this agenda forward; +- later pack work can materialize a dedicated `assets.pa` representation once the Studio-side model has stabilized. + +#### 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. + +#### 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, but it still needs the agenda to narrow the supported `Tiled` subset, the one-tileset-per-map constraint, and the editorial-role contract before a new decision can be written. ## Resolution Recommended next step: - converge this agenda around a first-wave `Tiled` subset; -- define whether the new asset type is raw-imported or normalized; +- define whether the new scene asset is raw-imported or normalized; +- lock the Studio-only glyph-bank specialization-flag model for `Tileset`, `Sprites`, and `UI`; +- lock the first-wave one-tileset-per-map rule; - then write a replacement decision for asset ownership, parser boundary, and wave-1 scope. diff --git a/test-projects/main/assets/Zelda3/primeiro tileset.tsx b/test-projects/main/assets/Zelda3/primeiro tileset.tsx new file mode 100644 index 00000000..8c6d5f60 --- /dev/null +++ b/test-projects/main/assets/Zelda3/primeiro tileset.tsx @@ -0,0 +1,50 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/test-projects/main/assets/scenes/primeiro mapa.tmx b/test-projects/main/assets/scenes/primeiro mapa.tmx index 7e9d8842..58d07a55 100644 --- a/test-projects/main/assets/scenes/primeiro mapa.tmx +++ b/test-projects/main/assets/scenes/primeiro mapa.tmx @@ -1,6 +1,6 @@ - - + + 1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1,1, @@ -32,5 +32,8 @@ + + + diff --git a/test-projects/main/assets/scenes/primeiro tileset.tsx b/test-projects/main/assets/scenes/primeiro tileset.tsx deleted file mode 100644 index 897df20e..00000000 --- a/test-projects/main/assets/scenes/primeiro tileset.tsx +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - diff --git a/test-projects/main/assets/scenes/scene1.tiled-project b/test-projects/main/assets/scenes/scene1.tiled-project deleted file mode 100644 index d0eb5920..00000000 --- a/test-projects/main/assets/scenes/scene1.tiled-project +++ /dev/null @@ -1,14 +0,0 @@ -{ - "automappingRulesFile": "", - "commands": [ - ], - "compatibilityVersion": 1100, - "extensionsPath": "extensions", - "folders": [ - "." - ], - "properties": [ - ], - "propertyTypes": [ - ] -} diff --git a/test-projects/main/assets/scenes/scene1.tiled-session b/test-projects/main/assets/scenes/scene1.tiled-session deleted file mode 100644 index 79d10b59..00000000 --- a/test-projects/main/assets/scenes/scene1.tiled-session +++ /dev/null @@ -1,38 +0,0 @@ -{ - "activeFile": "primeiro tileset.tsx", - "expandedProjectPaths": [ - "." - ], - "fileStates": { - "primeiro mapa.tmx": { - "scale": 2.55, - "selectedLayer": 1, - "viewCenter": { - "x": 200, - "y": 200.58823529411768 - } - }, - "primeiro tileset.tsx": { - "dynamicWrapping": true, - "scaleInDock": 1, - "scaleInEditor": 1 - } - }, - "last.imagePath": "/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/studio/test-projects/main/assets/recovered/atlas2", - "map.height": 25, - "map.lastUsedFormat": "tmx", - "map.tileHeight": 16, - "map.tileWidth": 16, - "map.width": 25, - "openFiles": [ - "primeiro mapa.tmx", - "primeiro tileset.tsx" - ], - "project": "scene1.tiled-project", - "recentFiles": [ - "primeiro mapa.tmx", - "primeiro tileset.tsx" - ], - "tileset.lastUsedFormat": "tsx", - "tileset.type": 1 -}