Tiled Parser and Scene & Palette Management in Studio
This commit is contained in:
+106
@@ -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
-1
@@ -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
|
||||
-16
@@ -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`.
|
||||
+45
@@ -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.
|
||||
+103
@@ -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.
|
||||
Reference in New Issue
Block a user