discussion framework migration
This commit is contained in:
@@ -0,0 +1,116 @@
|
||||
---
|
||||
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 `tile 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 `tile bank`.
|
||||
|
||||
The imported context keeps the same baseline:
|
||||
|
||||
- every `*.png` input of a tile 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 `tile bank`-specific, and which parts are reusable Studio form-session primitives?
|
||||
- [ ] Does the first release need only an asset-scoped `tile 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 `tile 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 `tile 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 `tile 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 `tile 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.
|
||||
@@ -0,0 +1,97 @@
|
||||
---
|
||||
id: AGD-0004
|
||||
ticket: tilemap-and-metatile-runtime-binary-layout
|
||||
title: Tilemap and Metatile Runtime Binary Layout
|
||||
status: open
|
||||
created: 2026-03-26
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- tilemap
|
||||
- metatile
|
||||
- runtime-layout
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The repository has conceptual alignment around map responsibility split and active-window residency, but still lacks a closed runtime binary contract for handheld maps.
|
||||
|
||||
Without a canonical decision:
|
||||
|
||||
- packer cannot close the output specification for map artifacts;
|
||||
- runtime lacks one stable reading baseline;
|
||||
- Studio cannot align authoring and preview schemas with one binary target.
|
||||
|
||||
## Context
|
||||
|
||||
Legacy source: `docs/packer/agendas/Tilemap and Metatile Runtime Binary Layout Agenda.md`
|
||||
|
||||
Domain owner: `docs/packer`
|
||||
Cross-domain impact:
|
||||
|
||||
- `docs/vm-arch`
|
||||
- `docs/studio`
|
||||
- `docs/compiler/pbs`
|
||||
|
||||
Current discussion premises retained from source:
|
||||
|
||||
- visual and collision concerns should remain separated;
|
||||
- map cells should not duplicate large metadata per tile;
|
||||
- only a `3x3` active window of maps should remain resident in memory;
|
||||
- a `64 KiB` target budget per map bank has been discussed;
|
||||
- `map bank` and `tileset bank` do not need identical size rules.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Is `collisionId` with `5` bits (`32` classes) sufficient for expected projects?
|
||||
- [ ] Should `flag0` be reserved for fast trigger semantics or contextual visual variation?
|
||||
- [ ] Which optional chunks belong in `V1`, and which should wait for a later version?
|
||||
- [ ] Must `map bank` stay strictly at `64 KiB`, or should capacity be variable with explicit metadata?
|
||||
- [ ] What compression policy should the packer adopt by default for the stream?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - `u8` cells with auxiliary tables
|
||||
- **Approach:** Store only one `metatileId` per cell and derive collision/flags from side tables.
|
||||
- **Pro:** Smallest RAM and I/O footprint.
|
||||
- **Con:** Pushes too much semantic meaning into external lookup tables.
|
||||
- **Maintainability:** Medium.
|
||||
|
||||
### Option B - `u16` bit-packed cells
|
||||
- **Approach:** Use `16` bits per cell, with a compact split such as `visualId`, `collisionId`, and `flag0`.
|
||||
- **Pro:** Balances compactness, deterministic decoding, and enough expressivity for many handheld cases.
|
||||
- **Con:** Leaves less room for inline per-cell growth than `u32`.
|
||||
- **Maintainability:** Strong.
|
||||
|
||||
### Option C - `u32` cells
|
||||
- **Approach:** Use larger cells to keep more event/flag space inline.
|
||||
- **Pro:** Highest flexibility for per-cell triggers and future expansion.
|
||||
- **Con:** Doubles memory cost versus `u16` without current evidence that it is needed.
|
||||
- **Maintainability:** Weak for the current budget target.
|
||||
|
||||
## Discussion
|
||||
|
||||
The retained source already converged toward `u16` as the best baseline.
|
||||
|
||||
The suggested runtime shape is:
|
||||
|
||||
- fixed map header;
|
||||
- contiguous cell stream;
|
||||
- optional future-proof chunks.
|
||||
|
||||
The proposed `U16_PACKED_V1` split keeps visual and collision references compact while preserving predictable memory usage and straightforward streaming behavior for a handheld target.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: adopt **Option B** as the baseline.
|
||||
|
||||
Imported retained recommendation:
|
||||
|
||||
1. authorship stays JSON-oriented around compact ids;
|
||||
2. build output packs deterministically into `U16_PACKED_V1`;
|
||||
3. runtime active-window budget remains explicit;
|
||||
4. any move to `u32` should happen only through a later versioned encoding with evidence of need.
|
||||
|
||||
Next step suggestion: convert this agenda into a decision that closes `U16_PACKED_V1`, propagation to `docs/vm-arch`, Studio editing schema alignment, and implementation planning for roundtrip tests.
|
||||
@@ -0,0 +1,87 @@
|
||||
---
|
||||
id: AGD-0005
|
||||
ticket: variable-tile-bank-palette-serialization
|
||||
title: Variable Tile Bank Palette Serialization
|
||||
status: open
|
||||
created: 2026-03-26
|
||||
resolved:
|
||||
decision:
|
||||
tags:
|
||||
- packer
|
||||
- legacy-import
|
||||
- tile-bank
|
||||
- palette-serialization
|
||||
- versioning
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
The current tile-bank contract serializes a fixed block of `64` palettes in v1 even when an asset authors far fewer palettes.
|
||||
|
||||
That keeps decoding simple, but it wastes cartridge space and leaves the system with a deliberate mismatch between authored and serialized palette counts.
|
||||
|
||||
## Context
|
||||
|
||||
Legacy source: `docs/packer/agendas/Variable Tile Bank Palette Serialization Agenda.md`
|
||||
|
||||
Domain owner: `docs/packer`
|
||||
Cross-domain dependency:
|
||||
|
||||
- runtime
|
||||
|
||||
Current aligned v1 contract:
|
||||
|
||||
- pixels are serialized as packed `u4`;
|
||||
- palettes are serialized as `RGB565 u16`;
|
||||
- `palette_count = 64`;
|
||||
- payload size includes a fixed `64 * 16 * 2` palette block.
|
||||
|
||||
The packer now exposes:
|
||||
|
||||
- `metadata.palette_count = 64`
|
||||
- `metadata.palette_authored = <actual authored count>`
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Should variable palette serialization arrive as a new payload version or as an incompatible change to the current one?
|
||||
- [ ] If `palette_count` becomes variable, should runtime still materialize a 64-slot resident bank, or truly shrink in-memory representation too?
|
||||
- [ ] Should sparse authored palette indices remain sparse in serialization, or be canonicalized into a dense runtime block?
|
||||
- [ ] Which domain owns compatibility for existing cartridges: `packer`, `runtime`, or `shipper`?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Keep fixed 64-palette serialization
|
||||
- **Approach:** Preserve the current fixed v1 payload with zero-filled unused palette slots.
|
||||
- **Pro:** No runtime change and current specs/tests remain stable.
|
||||
- **Con:** Every tile bank keeps paying the full palette cost.
|
||||
- **Maintainability:** Medium.
|
||||
|
||||
### Option B - Move to variable palette serialization now
|
||||
- **Approach:** Serialize only authored palettes and shrink payload size immediately.
|
||||
- **Pro:** Better cartridge efficiency and tighter semantics for `palette_count`.
|
||||
- **Con:** Reopens a just-stabilized cross-domain runtime contract and forces compatibility decisions now.
|
||||
- **Maintainability:** Medium if done carefully, risky if done incidentally.
|
||||
|
||||
### Option C - Keep v1 fixed and design variable serialization for v2
|
||||
- **Approach:** Preserve v1 stability now and open a later versioned follow-up for variable palette serialization.
|
||||
- **Pro:** Keeps current work stable while preserving a clean path for future optimization.
|
||||
- **Con:** Known waste remains in v1.
|
||||
- **Maintainability:** Strong.
|
||||
|
||||
## Discussion
|
||||
|
||||
The retained agenda recommendation is already clear: the waste is real, but it is not a correctness bug, and reopening the runtime-facing contract immediately would mix optimization work into a freshly stabilized path.
|
||||
|
||||
That makes versioned follow-up a cleaner vehicle than incidental mutation of the current contract.
|
||||
|
||||
## Resolution
|
||||
|
||||
Recommended direction: adopt **Option C**.
|
||||
|
||||
Imported retained recommendation:
|
||||
|
||||
1. keep the current fixed 64-palette contract for v1;
|
||||
2. if variable serialization is desired, design it explicitly as a versioned follow-up;
|
||||
3. treat compatibility, runtime representation, and sparse-vs-dense palette identity as explicit next-wave questions rather than silent payload tweaks.
|
||||
|
||||
Next step suggestion: if the team wants to remove the fixed padding, open the corresponding runtime-side discussion and close the versioning/compatibility story before planning implementation.
|
||||
+94
@@ -0,0 +1,94 @@
|
||||
---
|
||||
id: AGD-0006
|
||||
ticket: pbs-game-facing-asset-refs-and-call-result-discard
|
||||
title: PBS Game-Facing Asset References and Ignored Call Result Lowering
|
||||
status: open
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: [compiler, pbs, ergonomics, lowering, runtime, asset-identity, expression-statements]
|
||||
---
|
||||
|
||||
## Pain
|
||||
|
||||
PBS ainda tem dois atritos abertos na fronteira entre ergonomia de código de jogo e lowering executável:
|
||||
|
||||
1. referências a assets continuam centradas em `asset_name` no código-fonte, enquanto packer/runtime já convergiram para identidade estável por `asset_id`;
|
||||
2. `expression statements` com retorno materializado ainda precisam de política explícita de descarte, para não vazar regra de stack do backend para o código de usuário.
|
||||
|
||||
Os dois temas pertencem à mesma discussão porque tratam da mesma pergunta arquitetural:
|
||||
|
||||
Como PBS deve preservar uma superfície de autoria natural sem sacrificar determinismo no lowering e no runtime?
|
||||
|
||||
## Context
|
||||
|
||||
Esta agenda consolida dois tópicos legados do domínio PBS:
|
||||
|
||||
- `18.4. Asset References in Game Code - Names vs Compile-Time Lowering`
|
||||
- `18.5. Ignored Call Results in Executable Lowering`
|
||||
|
||||
Os pontos estáveis já conhecidos são:
|
||||
|
||||
- packer/runtime tratam `asset_id` como identidade estável;
|
||||
- `asset_name` ainda é a superfície mais natural para autoria e tooling;
|
||||
- o pipeline executável hoje já exige disciplina explícita de stack;
|
||||
- a família `19` reforçou a direção de compiler-owned lowering e publication protocol, reduzindo espaço para ambiguidades “aceitas pelo frontend, rejeitadas mais tarde”.
|
||||
|
||||
Isso sugere um princípio comum:
|
||||
|
||||
- a linguagem pode continuar amigável na superfície,
|
||||
- mas o compiler precisa assumir explicitamente o trabalho de normalizar essa superfície para um contrato executável estável.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] Referências a asset devem permanecer nomeadas na superfície PBS, mesmo se o lowering resolver parte delas para identidade estável?
|
||||
- [ ] O descarte de retorno ignorado deve ser uma regra geral de `expression statement`, ou uma exceção localizada para certos callsites?
|
||||
- [ ] Até onde PBS quer empurrar “surface ergonomics, compiler normalization” como princípio geral para APIs de jogo?
|
||||
- [ ] Quais casos precisam continuar dinâmicos em runtime e portanto não podem ser lowered agressivamente em compile time?
|
||||
- [ ] Devemos publicar warnings opcionais para retorno ignorado ou rename-fragile asset references, ou isso fica fora do escopo inicial?
|
||||
|
||||
## Options
|
||||
|
||||
### Option A - Keep Surface Simple, Keep Runtime Rules Visible
|
||||
- **Approach:** manter `asset_name` como referência de longo prazo e exigir consumo explícito de retornos quando houver valor materializado.
|
||||
- **Pro:** modelo simples e pouco invasivo.
|
||||
- **Con:** vaza custo operacional e detalhe de lowering para código-fonte; mantém fragilidade de rename e lookup tardio.
|
||||
- **Maintainability:** baixa a média, porque o autor continua negociando diretamente com limites do backend/runtime.
|
||||
|
||||
### Option B - Preserve Surface Ergonomics, Normalize in the Compiler
|
||||
- **Approach:** manter superfície amigável (`asset_name`, `foo();`) e explicitar no compiler as normalizações necessárias, como lowering para identidade estável quando possível e descarte automático de resultados ignorados em `expression statement`.
|
||||
- **Pro:** separa melhor autoria de protocolo executável; fica alinhado com a direção já adotada na família `19`.
|
||||
- **Con:** aumenta responsabilidade do compiler e exige regras claras de quando a normalização pode ou não ocorrer.
|
||||
- **Maintainability:** alta, porque o contrato passa a ficar onde ele deveria estar: no compiler e nas specs de lowering.
|
||||
|
||||
### Option C - Introduce Rich Resource and Effect Surfaces
|
||||
- **Approach:** criar abstrações mais fortes para recursos e resultados descartáveis, com novos tipos/superfícies na linguagem.
|
||||
- **Pro:** potencialmente o modelo mais explícito e expressivo no longo prazo.
|
||||
- **Con:** escopo bem maior; mistura redesign de linguagem com problemas que talvez possam ser resolvidos por lowering.
|
||||
- **Maintainability:** incerta no curto prazo; só compensa se PBS quiser investir em abstrações novas, não apenas fechar lacunas atuais.
|
||||
|
||||
## Discussion
|
||||
|
||||
As duas agendas legadas apontam para a mesma direção recomendada:
|
||||
|
||||
- preservar ergonomia de autoria;
|
||||
- e mover o peso de normalização para o compiler.
|
||||
|
||||
Isso não significa “magia implícita sem limite”.
|
||||
Significa assumir, de forma normativa, que a superfície PBS pode ser mais estável e legível do que o protocolo executável final.
|
||||
|
||||
O ponto central desta discussão é definir o limite dessa política:
|
||||
|
||||
- quando PBS só normaliza lowering,
|
||||
- e quando precisa criar uma abstração nova de linguagem.
|
||||
|
||||
## Resolution
|
||||
|
||||
Direção recomendada por enquanto:
|
||||
|
||||
1. tratar os dois temas como uma única discussão de política de surface-versus-lowering em PBS;
|
||||
2. preferir a direção **Option B** como baseline;
|
||||
3. fechar depois duas decisões derivadas:
|
||||
- política de asset references para código de jogo;
|
||||
- política de descarte de retorno ignorado em `expression statement`;
|
||||
4. evitar introduzir nova abstração de linguagem antes de esgotar a via de normalização no compiler.
|
||||
Reference in New Issue
Block a user