Tiled Parser and Scene & Palette Management in Studio

This commit is contained in:
2026-04-23 18:19:45 +01:00
parent 1ec3723c74
commit c20591d638
101 changed files with 6065 additions and 1308 deletions
+6 -6
View File
@@ -1,19 +1,19 @@
{"type":"meta","next_id":{"DSC":30,"AGD":32,"DEC":28,"PLN":56,"LSN":42,"CLSN":1}}
{"type":"meta","next_id":{"DSC":30,"AGD":32,"DEC":29,"PLN":59,"LSN":46,"CLSN":1}}
{"type":"discussion","id":"DSC-0029","status":"done","ticket":"studio-frame-composer-syscall-and-sprite-alignment","title":"Studio Alignment with Runtime FrameComposer Syscalls and Sprite Composition","created_at":"2026-04-18","updated_at":"2026-04-18","tags":["studio","compiler","pbs","stdlib","runtime-alignment","abi","syscall","frame-composer","sprites"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0041","file":"discussion/lessons/DSC-0029-studio-frame-composer-syscall-and-sprite-alignment/LSN-0041-composer-must-own-public-sprite-composition.md","status":"done","created_at":"2026-04-18","updated_at":"2026-04-18"}]}
{"type":"discussion","id":"DSC-0028","status":"open","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-17","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[{"id":"AGD-0030","file":"AGD-0030-tiled-parser-and-scene-asset-type.md","status":"accepted","created_at":"2026-04-15","updated_at":"2026-04-17"}],"decisions":[{"id":"DEC-0027","file":"DEC-0027-tiled-parser-and-scene-bank-asset-ownership.md","status":"accepted","created_at":"2026-04-17","updated_at":"2026-04-17","ref_agenda":"AGD-0030"}],"plans":[{"id":"PLN-0053","file":"PLN-0053-scene-bank-asset-contract-and-studio-metadata-foundations.md","status":"open","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0027"]},{"id":"PLN-0054","file":"PLN-0054-tiled-xml-io-and-scene-bank-file-orchestration.md","status":"open","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0027"]},{"id":"PLN-0055","file":"PLN-0055-assets-workspace-scene-bank-validation-and-acceptance-flow.md","status":"open","created_at":"2026-04-17","updated_at":"2026-04-17","ref_decisions":["DEC-0027"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0028","status":"done","ticket":"studio-tiled-parser-assets-scene-asset-type","title":"Tiled Parser and Scene Asset-Type Ownership in Assets Workspace","created_at":"2026-04-15","updated_at":"2026-04-23","tags":["studio","assets","scene","tiled","parser","asset-type"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0028-studio-tiled-parser-assets-scene-asset-type/LSN-0045-asset-owned-scene-bank-and-tiled-xml-workflow.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
{"type":"discussion","id":"DSC-0027","status":"abandoned","ticket":"studio-scene-workspace","title":"Scene Workspace for SCENE Authoring","created_at":"2026-04-14","updated_at":"2026-04-15","tags":["studio","workspace","scene","tilemap","asset","runtime-alignment"],"agendas":[{"id":"AGD-0029","file":"AGD-0029-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted agenda and its downstream work."}],"decisions":[{"id":"DEC-0026","file":"DEC-0026-studio-scene-workspace.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_agenda":"AGD-0029","_override_reason":"Explicit user request on 2026-04-15 to abandon the accepted decision and stop using it as normative guidance."}],"plans":[{"id":"PLN-0049","file":"PLN-0049-scene-workspace-spec-and-boundary-propagation.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0050","file":"PLN-0050-scene-workspace-shell-and-project-state-foundations.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0051","file":"PLN-0051-scene-artifact-and-assets-handoff-contract.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."},{"id":"PLN-0052","file":"PLN-0052-scene-workspace-wave-1-tilemap-editor.md","status":"abandoned","created_at":"2026-04-14","updated_at":"2026-04-15","ref_decisions":["DEC-0026"],"_override_reason":"Explicit user request on 2026-04-15 to abandon all plans derived from DEC-0026."}],"lessons":[]}
{"type":"discussion","id":"DSC-0026","status":"done","ticket":"glyph-bank-naming-alignment-with-runtime","title":"Glyph Bank Naming Alignment with Runtime DEC-0006","created_at":"2026-04-10","updated_at":"2026-04-10","tags":["packer","studio","naming","asset-contract","runtime-alignment","glyph-bank"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0040","file":"discussion/lessons/DSC-0026-glyph-bank-naming-alignment-with-runtime/LSN-0040-glyph-bank-artifact-naming-alignment.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0025","status":"done","ticket":"packer-pipeline-metadata-ownership","title":"Pipeline Metadata Ownership and Runtime Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["packer","metadata","runtime-contract","tooling","studio"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0039","file":"discussion/lessons/DSC-0025-packer-pipeline-metadata-ownership/LSN-0039-runtime-header-boundary-and-tooling-owned-pipeline-metadata.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0024","status":"done","ticket":"jacoco-reports-consolidation","title":"JaCoCo Reports Consolidation in Gradle","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["infra","gradle","jacoco","coverage","jenkins"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0038","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0038-jacoco-reports-consolidation.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"},{"id":"LSN-0044","file":"discussion/lessons/DSC-0024-jacoco-reports-consolidation/LSN-0044-jenkins-jacoco-alignment.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"studio-docs-import","title":"Import docs/studio into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0001-assets-workspace-execution-wave-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0002-bank-composition-editor-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0003-mental-model-asset-mutations-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0004-mental-model-assets-workspace-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0005-mental-model-studio-events-and-components-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0006-mental-model-studio-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0007-pack-wizard-shell-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0008-project-scoped-state-and-activity-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-studio-docs-import/LSN-0016-studio-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0002","status":"open","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[{"id":"AGD-0002","file":"AGD-0002-palette-management-in-studio.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"palette-management-in-studio","title":"Palette Management in Studio","created_at":"2026-03-26","updated_at":"2026-04-23","tags":["studio","legacy-import","palette-management","tile-bank","packer-boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0002-palette-management-in-studio/LSN-0042-schema-driven-palette-authoring-and-local-metadata-events.md","status":"done","created_at":"2026-04-23","updated_at":"2026-04-23"}]}
{"type":"discussion","id":"DSC-0003","status":"done","ticket":"packer-docs-import","title":"Import docs/packer into discussion-framework artifacts","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","migration","discussion-framework","docs-import"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0009","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0009-mental-model-packer-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0010-asset-identity-and-runtime-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0011-foundations-workspace-runtime-and-build-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0012-runtime-ownership-and-studio-boundary-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0013-metadata-convergence-and-runtime-sink-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0014-pack-wizard-summary-validation-and-pack-execution-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0015-tile-bank-packing-contract-legacy.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0003-packer-docs-import/LSN-0017-packer-docs-import-pattern.md","status":"done","created_at":"2026-03-26","updated_at":"2026-03-26"}]}
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"tilemap-and-metatile-runtime-binary-layout","title":"Tilemap and Metatile Runtime Binary Layout","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tilemap","metatile","runtime-layout"],"agendas":[{"id":"AGD-0004","file":"AGD-0004-tilemap-and-metatile-runtime-binary-layout.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"variable-tile-bank-palette-serialization","title":"Variable Tile Bank Palette Serialization","created_at":"2026-03-26","updated_at":"2026-03-26","tags":["packer","legacy-import","tile-bank","palette-serialization","versioning"],"agendas":[{"id":"AGD-0005","file":"AGD-0005-variable-tile-bank-palette-serialization.md","status":"open","created_at":"2026-03-26","updated_at":"2026-03-26"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0006","status":"done","ticket":"pbs-game-facing-asset-refs-and-call-result-discard","title":"PBS Game-Facing Asset References and Ignored Call Result Lowering","created_at":"2026-03-27","updated_at":"2026-03-30","tags":["compiler","pbs","ergonomics","lowering","runtime","asset-identity","expression-statements"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0024","file":"discussion/lessons/DSC-0006-pbs-game-facing-asset-refs-and-call-result-discard/LSN-0024-addressable-surface-host-metadata-and-ignored-value-discipline.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0007","status":"done","ticket":"pbs-learn-to-discussion-lessons-migration","title":"Migrate PBS Learn Documents into Discussion Lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","migration","discussion-framework","lessons","learn-prune"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0018","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0018-pbs-ast-and-parser-contract-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0019","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0019-pbs-name-resolution-and-linking-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0020","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0020-pbs-runtime-values-identity-memory-boundaries-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0021","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0021-pbs-diagnostics-and-conformance-governance-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0022","file":"discussion/lessons/DSC-0007-pbs-learn-to-discussion-lessons-migration/LSN-0022-pbs-globals-lifecycle-and-published-entrypoint-legacy.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"pbs-low-level-asset-manager-surface","title":"PBS Low-Level Asset Manager Surface for Runtime AssetManager","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["compiler","pbs","runtime","asset-manager","host-abi","stdlib","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0023","file":"discussion/lessons/DSC-0008-pbs-low-level-asset-manager-surface/LSN-0023-lowassets-runtime-aligned-sdk-surface.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"studio-debugger-workspace-integration","title":"Integrate ../debugger into Studio as a dedicated workspace","created_at":"2026-03-30","updated_at":"2026-04-07","tags":["studio","debugger","workspace","integration","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"studio-code-editor-workspace-foundations","title":"Establish Code Editor workspace foundations in Studio without LSP","created_at":"2026-03-30","updated_at":"2026-03-31","tags":["studio","editor","workspace","multi-frontend","lsp-deferred"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0010-studio-code-editor-workspace-foundations/LSN-0026-read-only-editor-foundations-and-semantic-deferral.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
{"type":"discussion","id":"DSC-0011","status":"done","ticket":"compiler-analyze-compile-build-pipeline-split","title":"Split compiler pipeline into analyze, compile, and build entrypoints","created_at":"2026-03-30","updated_at":"2026-03-30","tags":["compiler","pipeline","artifacts","build","analysis"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0011-compiler-analyze-compile-build-pipeline-split/LSN-0025-compiler-pipeline-entrypoints-and-result-boundaries.md","status":"done","created_at":"2026-03-30","updated_at":"2026-03-30"}]}
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"studio-editor-document-vfs-boundary","title":"Definir um boundary de VFS documental para tree/view/open files no Code Editor do Studio","created_at":"2026-03-31","updated_at":"2026-03-31","tags":["studio","editor","workspace","vfs","filesystem","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0027","file":"discussion/lessons/DSC-0012-studio-editor-document-vfs-boundary/LSN-0027-project-document-vfs-and-session-owned-editor-boundary.md","status":"done","created_at":"2026-03-31","updated_at":"2026-03-31"}]}
@@ -26,5 +26,5 @@
{"type":"discussion","id":"DSC-0019","status":"done","ticket":"studio-project-local-setup-separate-from-main-studio-state","title":"Separate project-local setup from the main Studio state under .studio","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","project-session","project-state","persistence","dot-studio","setup","boundary"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0032","file":"discussion/lessons/DSC-0019-studio-project-local-setup-separate-from-main-studio-state/LSN-0032-separate-project-config-from-session-restoration-state.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0020","status":"done","ticket":"studio-editor-indentation-policy-and-project-setup","title":"Indentation Policy, Status-Bar Semantics, and Project-Local Editor Setup","created_at":"2026-04-04","updated_at":"2026-04-04","tags":["studio","editor","indentation","tabs","setup","dot-studio","configuration","ux"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0033","file":"discussion/lessons/DSC-0020-studio-editor-indentation-policy-and-project-setup/LSN-0033-setup-owned-indentation-policy-and-project-bootstrap-defaults.md","status":"done","created_at":"2026-04-04","updated_at":"2026-04-04"}]}
{"type":"discussion","id":"DSC-0021","status":"done","ticket":"studio-frontend-editor-write-and-save-wave","title":"Enable Frontend Editing and Save in the Studio Code Editor","created_at":"2026-04-04","updated_at":"2026-04-06","tags":["studio","editor","frontend","write","save","vfs","lsp","pbs","access-policy"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0021-studio-frontend-editor-write-and-save-wave/LSN-0036-vfs-owned-frontend-edit-and-save-wave.md","status":"done","created_at":"2026-04-06","updated_at":"2026-04-06"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0022","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0022-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"studio-play-stop-cartridge-flow","title":"Wire the Studio Play/Stop button to shipper phase 1 cartridge preparation and runtime execution","created_at":"2026-04-06","updated_at":"2026-04-07","tags":["studio","play-stop","shipper","runtime","cartridge","shell"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0043","file":"discussion/lessons/DSC-0022-studio-play-stop-and-debugger-integration/LSN-0043-studio-play-stop-and-debugger-integration.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
{"type":"discussion","id":"DSC-0023","status":"done","ticket":"gradle-version-catalog-migration","title":"Move dependency version management to Version Catalog (TOML)","created_at":"2026-04-07","updated_at":"2026-04-07","tags":["gradle","buildSrc","dependency-management","version-catalog"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0023-gradle-version-catalog-migration/LSN-0037-gradle-version-catalog-adoption.md","status":"done","created_at":"2026-04-07","updated_at":"2026-04-07"}]}
@@ -0,0 +1,106 @@
---
id: LSN-0042
ticket: palette-management-in-studio
title: Schema-Driven Palette Authoring and Local Metadata Events
created: 2026-04-23
tags:
- studio
- glyph-bank
- palette-management
- color-schema
- local-events
---
## Context
The glyph-bank palette workflow originally treated palette candidates as extracted tile artifacts. That made grouping, recoloring, and final bank palette selection compete in the same surface.
The completed palette-management work split the workflow into two authored layers:
1. `Color Schema Groups`, where selected tiles are grouped into a shared index structure.
2. `Palette Overhauling`, where palettes are authored and selected against already-ready schemas.
The durable implementation lesson is that schema edits, palette edits, and build selection are all local glyph-material metadata operations first. They should update local metadata projections directly instead of forcing a full asset-details reload.
## Key Decisions
### Schema Owns Index Semantics
**What:** A schema is the authored index structure for a group of selected glyph-bank tiles. It owns `material_indices`, artifact bindings, fingerprint snapshots, version, and status.
**Why:** The source PNG stays unchanged, while Studio records how tile colors map into stable bank-local indices. This keeps tile grouping separate from recoloring.
**Trade-offs:** Schema invalidation must be explicit. When selected tile fingerprints drift, the schema can become inconsistent and dependent palettes become invalid or stale.
### Palettes Are Schema-Scoped
**What:** A palette always belongs to exactly one schema. It stores concrete `#RRGGBB` colors for that schema's visible indices and carries the schema version it was authored against.
**Why:** Multiple recolors can safely exist for one index structure without duplicating tile grouping metadata.
**Trade-offs:** Duplicate detection must use the tuple `schemaId + colors + order`, not display name or source tile identity.
### Original Palettes Are Synthetic and Read-Only
**What:** The original palette is the synthetic `schema-<schemaId>-original` projection derived from the current schema colors. It is not a persisted user palette.
**Why:** Updating the schema should update the original palette automatically. The original represents the schema's source color meaning, not a user-authored recolor.
**Trade-offs:** Users cannot edit or delete the original palette directly. If they want a changed palette, they create or edit a separate persisted palette for the same schema.
### Local Metadata Events Beat Global Reloads
**What:** Schema and palette metadata mutations should publish `StudioGlyphMaterialMetadataChangedEvent` and let interested sections rebind local state.
**Why:** Global asset refresh and selection events can close edit mode, reset form state, and make small metadata edits feel destructive.
**Trade-offs:** Controls must keep their local coordinators robust: stale button handlers should read the current view model at click time, and metadata replacement must preserve edit-mode drafts where possible.
## Patterns and Algorithms
### `glyph-material.json`
`glyph-material.json` is the Studio-owned support file for glyph-bank material authoring. It persists schemas and user-authored palettes, while derived original palettes remain a view projection.
Schema records store:
- stable `schema_id`
- `status`
- `version`
- dense visible `material_indices`
- artifact bindings with fingerprint snapshots
Palette records store:
- stable `palette_id`
- persisted `name`
- parent `schema_id`
- schema `version`
- concrete `colors`
### Palette Names
Palette names are persisted even when the user leaves the name field blank. The blank-name path resolves to a deterministic, simple generated name such as `snow white`, `fog twist`, or `ember bloom`.
The generated name is a convenience label only. Palette identity remains `palette_id`, and duplicate detection remains schema plus ordered colors.
### Original Palette Projection
Every ready schema projects a synthetic original palette from the schema's current `material_indices`.
This projection must always exist in the palette view, even if a user-authored palette has the same colors. A saved palette with the same schema and colors is still user-authored and can be deleted.
## Pitfalls
- Do not treat same colors as proof that a palette is original. Original means "synthetic schema projection", not "matches current schema colors".
- Do not publish global asset refresh events for local schema or palette metadata changes. Use local metadata events unless pack/runtime state truly changed.
- Do not let button handlers capture stale preview objects. Fetch the current coordinator view model at click time for destructive actions.
- Do not let blank palette names remain blank on disk. Resolve the generated name before persisting.
- Do not open the palette wizard for synthetic original palettes. They are read-only projections.
## Takeaways
- Schema formation and palette authoring are separate lifecycle stages.
- Original palettes are derived views, not persisted editable records.
- User-created palettes remain editable and removable even when they share a schema or colors with an original.
- Local metadata events preserve form continuity better than full asset refreshes.
@@ -1,5 +1,5 @@
---
id: LSN-0022
id: LSN-0043
ticket: studio-play-stop-cartridge-flow
title: Studio Play/Stop and Debugger Workspace Integration
status: done
@@ -1,16 +0,0 @@
# LSN-0039: Jenkins + JaCoCo Integration with Multi-Module Gradle
- **Problem:** O Jenkinsfile estava desatualizado, tentando rodar uma task de cobertura inexistente (`testCodeCoverageReport`) em um subprojeto específico, ignorando a cobertura global e causando falhas no pipeline.
- **Decision:** Alinhar o `Jenkinsfile` com a task de agregação customizada no root project (`jacocoTestReport`), removendo a dependência de subprojetos específicos para métricas globais.
- **Implementation:**
- Atualizado o comando de execução no Jenkins: `./gradlew clean test jacocoTestReport`.
- Ajustado o `recordCoverage` para ler o XML consolidado em `build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml`.
- Ajustado o `publishHTML` para exibir o relatório consolidado em `build/reports/jacoco/jacocoTestReport/html`.
- **Example:**
- Antes: `SRS_APP/build/reports/...` (específico por app).
- Depois: `build/reports/...` (global do projeto).
- **Pitfalls:**
- Ao usar relatórios consolidados no root, deve-se garantir que o Gradle rode a task de agregação *após* os testes de todos os subprojetos.
- O Jenkins precisa de acesso ao workspace root para encontrar esses arquivos; caminhos relativos no `Jenkinsfile` geralmente partem do root do checkout.
- **References:**
- `DSC-0024`, `DEC-0025`, `PLN-0048`.
@@ -0,0 +1,45 @@
---
id: LSN-0044
ticket: jacoco-reports-consolidation
title: Jenkins Alignment with Consolidated JaCoCo Reports
created: 2026-04-07
tags:
- infra
- gradle
- jacoco
- jenkins
---
## Context
The Jenkins pipeline was still wired to an outdated coverage task and module-specific report paths. That made CI brittle after the project moved coverage reporting to the root-level consolidated `jacocoTestReport` task.
## Key Decisions
### Jenkins Reads Root-Level Coverage
**What:** Jenkins should run `./gradlew clean test jacocoTestReport` and publish coverage from the root project report directory.
**Why:** Coverage is aggregated across modules, so CI should not depend on a single application subproject path.
**Trade-offs:** The root task must run after all relevant tests. Jenkins paths must be rooted at the checkout workspace rather than a submodule directory.
## Patterns and Algorithms
The canonical report locations are:
- XML: `build/reports/jacoco/jacocoTestReport/jacocoTestReport.xml`
- HTML: `build/reports/jacoco/jacocoTestReport/html`
Jenkins `recordCoverage` should consume the XML report. Jenkins `publishHTML` should expose the HTML directory.
## Pitfalls
- Do not point Jenkins at `SRS_APP/build/reports/...` or another module-local report when the project expects consolidated root coverage.
- Do not run only the reporting task without ensuring tests have executed first.
- Do not assume Jenkins relative paths start inside a Gradle subproject; treat the checkout root as the base.
## Takeaways
- Root-level coverage aggregation needs root-level CI report paths.
- The Jenkinsfile and Gradle coverage task names must move together.
@@ -0,0 +1,103 @@
---
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.
@@ -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.
@@ -1,139 +0,0 @@
---
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.
@@ -1,121 +0,0 @@
---
id: PLN-0053
ticket: studio-tiled-parser-assets-scene-asset-type
title: Scene Bank Asset Contract and Studio Metadata Foundations
status: open
created: 2026-04-17
completed:
tags:
- studio
- assets
- scene
- tiled
- metadata
---
## Objective
Establish the asset contract and Studio-owned metadata foundations required by `DEC-0027` so `Scene Bank` assets and specialized `Glyph Bank` assets can exist in the `Assets` workspace without reintroducing a dedicated scene workspace or a separate normalized scene schema.
## Background
`DEC-0027` locks the following requirements that must be reflected in the asset contract before parser and UX work can be implemented safely:
- `Scene Bank` is an asset owned by the `Assets` workspace.
- `Glyph Bank` remains the base runtime asset family, with Studio-only specialization flags such as `Tileset`, `Sprites`, and `UI`.
- `TMX` remains the maintained scene document format.
- `Scene Bank` support files own the explicit `layer -> tilemap` mapping.
- one scene may contain multiple tilemaps, with up to `4` layers in wave 1.
The current repo already has the asset creation and detail surfaces under `prometeu-studio/src/main/java/p/studio/workspaces/assets` and the asset manifest/runtime contract under `prometeu-packer/prometeu-packer-v1`.
## Scope
### Included
- Add `Scene Bank` as a first-class asset option in the Studio asset creation and details pipeline.
- Add the Studio-only specialization model for `Glyph Bank` assets, including `Tileset`, `Sprites`, and `UI`.
- Define where Studio-owned scene support files and specialization metadata live relative to existing asset roots.
- Add summary/details projection support so the `Assets` workspace can display base family plus specialization chip.
- Define the wave-1 metadata contract for scene-layer mapping and scene-bank limits.
### Excluded
- TMX/TSX XML parsing and serialization logic.
- External-edit acceptance UI or file-diff validation flows.
- Pack publication of scene assets into runtime binary formats.
## Execution Steps
### Step 1 - Extend asset family and metadata models
**What:** Introduce the data models needed for `Scene Bank` assets and Studio-only glyph-bank specialization.
**How:** Update the packer/studio shared asset declarations and detail projection pipeline so `Scene Bank` can be created, read, and surfaced by the `Assets` workspace while keeping `Glyph Bank` as the underlying runtime family for specializations. Define the Studio-only specialization enum and the scene-bank support metadata surface that will later carry `layer -> tilemap` mapping and wave-1 constraints.
**File(s):**
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/FileSystemPackerWorkspaceService.java`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDeclarationParser.java`
- `prometeu-packer/prometeu-packer-v1/src/main/java/p/packer/services/PackerAssetDetailsService.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetSummary.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
- additional shared DTOs or catalogs discovered from the asset declaration flow
### Step 2 - Add creation and details support in Assets workspace
**What:** Make `Scene Bank` and glyph-bank specialization available in the actual Studio asset workflow.
**How:** Extend the add-asset wizard to expose `Scene Bank` as an asset type and add the minimum specialization capture or follow-up action path for `Glyph Bank`. Update details/summary rendering to show `Glyph Bank / Tileset`-style presentation and to surface scene-bank metadata ownership in the details view without inventing a separate workspace region.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/wizards/AddAssetWizard.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/summary/AssetDetailsSummaryControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`
- `prometeu-studio/src/main/resources/i18n/messages.properties`
### Step 3 - Define on-disk scene-bank support-file baseline
**What:** Establish the first implementation-owned support-file baseline for scene banks.
**How:** Introduce a concrete but implementation-scoped support-file format that records scene layer count, `layer -> tilemap` mapping, and references needed by the `Assets` workspace. The plan MUST preserve the decision rule that the exact shape can be discovered during implementation, but the result MUST be explicit, deterministic, and colocated with the scene asset root.
**File(s):**
- asset-root support files under `test-projects/main/assets/...` fixtures
- implementation targets discovered while wiring Studio asset persistence
- related tests in `prometeu-studio/src/test/java/p/studio/workspaces/assets/...` and `prometeu-packer/prometeu-packer-v1/src/test/java/p/packer/services/...`
## Test Requirements
### Unit Tests
- Add parser/service tests proving `Scene Bank` assets can be created and read through the asset declaration pipeline.
- Add Studio projection tests proving summary/details surfaces can represent base family plus specialization.
- Add tests for the support-file metadata model, including `1..4` layer constraints and explicit `layer -> tilemap` mapping requirements.
### Integration Tests
- Extend asset workspace service tests to verify end-to-end creation of a `Scene Bank` asset root and detail retrieval.
- Add or update test fixtures under `test-projects/main/assets` to cover specialized glyph banks and scene-bank roots with multiple tilemaps.
### Manual Verification
- Create a new `Scene Bank` from the Assets workspace and confirm the asset appears in the list/details flow.
- Create or mark a `Glyph Bank` as `Tileset` and confirm the summary shows base family plus specialization chip.
## Acceptance Criteria
- [ ] `Scene Bank` exists as a first-class asset choice in the Studio asset flow.
- [ ] Studio-only glyph-bank specialization is represented by a closed metadata set and does not redefine the runtime asset family.
- [ ] The Assets workspace can display base family and specialization together in the summary/details flow.
- [ ] Scene-bank support metadata explicitly records `layer -> tilemap` mapping and enforces the wave-1 `4`-layer limit.
- [ ] No plan step introduces a dedicated scene workspace or a normalized Studio-owned scene format.
## Dependencies
- Depends on `DEC-0027`.
- Unblocks `PLN-0054` and `PLN-0055`.
## Risks
- The current asset declaration pipeline may assume existing family/output combinations too rigidly, which can force deeper changes in packer services than the UI suggests.
- If specialization metadata is embedded in the wrong layer, Studio-only editorial flags may leak into runtime-facing contracts.
- If the support-file baseline is too vague, later parser and validation work will drift on naming and ownership.
@@ -1,120 +0,0 @@
---
id: PLN-0054
ticket: studio-tiled-parser-assets-scene-asset-type
title: Tiled XML IO and Scene Bank File Orchestration
status: open
created: 2026-04-17
completed:
tags:
- studio
- assets
- scene
- tiled
- parser
---
## Objective
Implement the wave-1 XML read/write pipeline for `TMX` and `TSX`, including deterministic file placement and reference orchestration between `Scene Bank` tilemaps and `Tileset`-specialized glyph-bank assets.
## Background
`DEC-0027` requires wave-1 XML read/write support for both `TMX` and `TSX`, keeps `TMX` as the maintained scene document, and requires each tilemap to reference exactly one generated `TSX`. It also keeps naming details implementation-owned, but requires the resulting convention to be canonical and compatible with explicit `layer -> tilemap` mapping.
The repository already contains example `TMX` and `TSX` files under `test-projects/main/assets/scenes` and `test-projects/main/assets/Zelda3`, which can be promoted into fixture coverage.
## Scope
### Included
- Add XML read/write support for supported `TMX` and `TSX` surfaces.
- Generate `TSX` from `Tileset`-specialized glyph-bank assets.
- Generate and maintain one or more `TMX` files inside a `Scene Bank` asset root.
- Define and implement a canonical naming/reference convention for multiple `TMX` files compatible with scene support metadata.
- Preserve supported wave-1 Tiled features: object layers, properties, flips, and collisions.
### Excluded
- Studio UX for validating and accepting external edits.
- Pack/runtime materialization of scene data.
- Support for infinite maps, templates, Wang sets, or animations.
## Execution Steps
### Step 1 - Introduce Tiled XML domain models and codecs
**What:** Create the XML-side models and serialization services for supported `TMX` and `TSX`.
**How:** Add parser/writer services that cover the accepted wave-1 subset, preserving round-trip stability for supported fields and producing explicit diagnostics for unsupported constructs. Keep the implementation aligned to XML as the primary interoperability surface and avoid JSON-export dependencies.
**File(s):**
- new `prometeu-studio/src/main/java/p/studio/.../tiled/...` package(s) discovered during implementation
- related tests under `prometeu-studio/src/test/java/p/studio/.../tiled/...`
### Step 2 - Generate TSX from Tileset-specialized glyph banks
**What:** Add the generation path that emits `TSX` for `Glyph Bank` assets specialized as `Tileset`.
**How:** Extend the asset action/details flow so a `Tileset` glyph bank can materialize its Tiled-facing `TSX` file in the asset root. The generated `TSX` MUST include the supported tileset-side collision/properties surface needed by wave 1 and MUST remain deterministic for later scene references.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetAction.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
- implementation packages created for Tiled file generation
### Step 3 - Generate and maintain TMX files inside Scene Bank assets
**What:** Add the file orchestration path for one scene with up to `4` layer-linked tilemaps.
**How:** Use the scene-bank support metadata from `PLN-0053` to generate and maintain one or more canonical `TMX` files in the scene asset root. Each `TMX` MUST reference exactly one generated `TSX` from a `Tileset` glyph-bank asset, and the chosen naming convention MUST remain stable across regenerate/validate cycles.
**File(s):**
- scene-bank persistence/orchestration services added under `prometeu-studio/src/main/java/p/studio/...`
- test fixtures under `test-projects/main/assets/scenes` and related asset roots
### Step 4 - Enforce supported subset and failure behavior
**What:** Formalize the wave-1 supported subset and rejection behavior for unsupported input.
**How:** Add diagnostic-producing validation around XML ingest so unsupported Tiled constructs fail explicitly and do not silently normalize away unsupported content. Cover tile-owned collision in `TSX` and map-owned collision via `Object Layer` in `TMX`.
**File(s):**
- Tiled parser/validator packages introduced in this plan
- diagnostics surfaces reused by the Assets workspace
## Test Requirements
### Unit Tests
- Add TMX parser/writer round-trip tests for supported map metadata, layers, object layers, properties, flips, and collision cases.
- Add TSX parser/writer round-trip tests for supported tileset metadata and tile-owned collision/properties.
- Add tests for rejection/diagnostics on unsupported features such as infinite maps, templates, Wang sets, and animations.
### Integration Tests
- Add end-to-end fixture tests proving a `Tileset` glyph bank can generate `TSX` and a `Scene Bank` can generate one or more `TMX` files referencing it.
- Add tests proving canonical `TMX` naming remains stable across regeneration using the same support metadata.
### Manual Verification
- Generate `TSX` from a `Tileset` glyph bank and open it in Tiled.
- Generate a multi-tilemap scene-bank root and confirm each `TMX` opens in Tiled and points to the expected `TSX`.
## Acceptance Criteria
- [ ] Studio can read and write the supported XML subset for both `TMX` and `TSX`.
- [ ] `Tileset`-specialized glyph banks can generate deterministic `TSX` files.
- [ ] `Scene Bank` assets can maintain multiple canonical `TMX` files in one asset root.
- [ ] Every generated tilemap references exactly one generated `TSX` in wave 1.
- [ ] Unsupported Tiled features fail with explicit diagnostics instead of silent degradation.
## Dependencies
- Depends on `DEC-0027`.
- Depends on `PLN-0053` for asset metadata and support-file ownership.
- Unblocks `PLN-0055`.
## Risks
- XML round-trip fidelity can drift if parser and writer models are not designed from the same canonical structure.
- Canonical naming and path resolution may become unstable if they are derived from mutable UI labels instead of explicit metadata.
- TSX generation can accidentally encode Studio-only specialization state into runtime-facing data if the boundary is not kept strict.
@@ -1,120 +0,0 @@
---
id: PLN-0055
ticket: studio-tiled-parser-assets-scene-asset-type
title: Assets Workspace Scene Bank Validation and Acceptance Flow
status: open
created: 2026-04-17
completed:
tags:
- studio
- assets
- scene
- validation
- ux
---
## Objective
Implement the `Assets` workspace flow that validates external `Tiled` edits, surfaces diagnostics, and requires explicit Studio-side acceptance before a `Scene Bank` is considered ready.
## Background
`DEC-0027` requires the initial workflow to be:
1. create the scene asset in Studio;
2. edit generated `TMX`/`TSX` in `Tiled`;
3. return to Studio;
4. validate;
5. explicitly accept the converged changes.
The decision explicitly forbids silent auto-acceptance and requires the same general diagnostic discipline already used for glyph assets. The current `Assets` workspace already contains refresh, detail, action, and diagnostics surfaces that can host this flow without creating a dedicated scene workspace.
## Scope
### Included
- Add scene-bank validation state to the `Assets` workspace projections.
- Add explicit actions to validate and accept external scene-bank changes.
- Surface scene/Tiled diagnostics in the existing asset details/logging patterns.
- Ensure readiness/build participation reflects acceptance state for scene banks.
### Excluded
- Automatic merge/convergence of external edits.
- A dedicated scene-editing workspace.
- Pack/runtime publication.
## Execution Steps
### Step 1 - Extend asset details state for scene-bank validation
**What:** Add the projection/state needed to represent scene-bank validation and acceptance status in the assets UI.
**How:** Extend the asset workspace message and detail-state models so scene-bank assets can expose pending external changes, validation result, acceptance readiness, and scene-specific actions while reusing the current details/action host rather than adding a separate workspace.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetDetails.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceDetailsViewState.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/AssetWorkspaceAssetAction.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/dialogs/AssetDiagnosticsDialog.java`
### Step 2 - Add validate/accept actions to existing assets action surface
**What:** Add the concrete user actions for scene-bank validation and explicit acceptance.
**How:** Extend the existing asset actions surface so scene-bank assets can trigger validation against current `TMX`/`TSX` and then explicitly accept the converged result. Keep these actions stacked with existing asset actions, in line with `DEC-0027`, and ensure availability is driven by asset family/state rather than a new intermediate panel.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/summary/AssetDetailsSummaryControl.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/AssetDetailsUiSupport.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/details/...` action-host controls discovered during implementation
- `prometeu-studio/src/main/resources/i18n/messages.properties`
### Step 3 - Connect validation results to diagnostics and readiness gates
**What:** Make validation outcome meaningful to the workflow.
**How:** Reuse the current diagnostic/log/event patterns so unsupported references, broken paths, invalid tilemap-to-layer mapping, and unsupported Tiled constructs surface as diagnostics. Mark the scene bank as not ready until validation succeeds and explicit acceptance is recorded. Reflect this status in build participation or equivalent readiness signals without implementing pack publication itself.
**File(s):**
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/messages/events/...`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetLogsPane.java`
- `prometeu-studio/src/main/java/p/studio/workspaces/assets/AssetWorkspace.java`
- any validation coordinator/services created for scene-bank acceptance
## Test Requirements
### Unit Tests
- Add tests for scene-bank details state transitions: created, externally changed, validation failed, validation passed, accepted.
- Add tests proving accept is unavailable when validation diagnostics remain.
- Add tests proving scene-bank actions are hosted in the existing asset actions surface.
### Integration Tests
- Add assets workspace tests covering refresh after external file edits, validation, diagnostics surfacing, and explicit acceptance.
- Add fixture-backed tests covering invalid TSX references, unsupported TMX features, and broken layer-to-tilemap mappings.
### Manual Verification
- Create a scene bank in Studio, edit its `TMX`/`TSX` externally in Tiled, return to Studio, validate, and explicitly accept.
- Confirm the asset stays unready when diagnostics remain and becomes ready only after successful validation plus explicit acceptance.
## Acceptance Criteria
- [ ] Scene-bank assets expose validate/accept actions in the existing asset action surface.
- [ ] Studio surfaces scene-bank diagnostics using the existing general diagnostic discipline.
- [ ] Studio does not silently auto-accept external `Tiled` edits.
- [ ] A scene bank is not considered ready until validation succeeds and the user explicitly accepts the result.
- [ ] No part of the workflow introduces a dedicated scene workspace.
## Dependencies
- Depends on `DEC-0027`.
- Depends on `PLN-0053` for asset/state foundations.
- Depends on `PLN-0054` for TMX/TSX ingest and validation inputs.
## Risks
- If refresh and validation state are coupled too loosely, the UI can show stale readiness after external edits.
- If acceptance is represented only in transient UI state, Studio may lose the required gate after reload.
- If diagnostics are not normalized with existing asset flows, scene-bank errors will feel like a separate subsystem.