42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# Glyph Bank Artifact Naming Alignment
|
|
|
|
The graphical bank artifact, which stores indexed graphical data (glyphs) for runtime consumption, has been aligned with the unified project vocabulary across `packer`, `studio`, and `runtime`.
|
|
|
|
### Original Problem
|
|
|
|
Previously, the project used inconsistent terminology for the same concrete artifact:
|
|
- `tile_bank` in some packer configurations.
|
|
- `TILES/indexed_v1` as an output format.
|
|
- `TILES` as a runtime-facing `bank_type`.
|
|
- `TileBank` or `tile bank` in Studio UI and internal code.
|
|
|
|
This created a conceptual overlap with the "tile" domain, which properly refers to geometric sizes, map layers, and grid-based rendering logic. Keeping the artifact named "tile bank" made it difficult to distinguish between the storage container (the bank) and the geometric entities (the tiles) stored within or referenced by it.
|
|
|
|
### Consolidated Decision
|
|
|
|
Following `DEC-0025` (this repository) and `DEC-0006` (runtime repository), the concrete graphical bank artifact is now exclusively referred to as **Glyph Bank**.
|
|
|
|
1. **Artifact Name**: `glyph_bank` (serialized asset-family).
|
|
2. **Output Format**: `GLYPH/indexed_v1`.
|
|
3. **Runtime ID**: `GLYPH` (bank_type).
|
|
4. **Vocabulary Split**:
|
|
- Use **Glyph** when referring to the graphical data bank, its capacity, or its storage format.
|
|
- Use **Tile** only for geometric concepts (tile size, tile maps, tile layers, coordinate grids).
|
|
|
|
### Implementation Results
|
|
|
|
- **Packer**: All `AssetFamilyCatalog`, `OutputFormatCatalog`, and walker implementations now use the `Glyph*` vocabulary. Parser validation now expects `type: glyph_bank`.
|
|
- **Studio**: UI labels, composition coordinators, and internal services have been renamed to `Glyph Bank` to match the packer and runtime contracts.
|
|
- **Contract**: No compatibility layer was introduced. All fixtures and test assets were migrated in a single wave to ensure a clean, unified contract.
|
|
|
|
### Common Pitfalls and Anti-patterns
|
|
|
|
- **Incorrect Rename**: Do not rename `tileSize` to `glyphSize`. A tile is a geometric unit; a glyph is the graphical content within that unit or the bank that stores it.
|
|
- **Legacy Fixtures**: Since there is no compatibility layer, old `asset.json` files with `type: tile_bank` will fail to parse. They must be updated to `type: glyph_bank`.
|
|
|
|
### References
|
|
|
|
- `DEC-0025`: Local decision for Glyph Bank alignment.
|
|
- `PLN-0048`: Implementation plan for the naming migration.
|
|
- `docs/specs/packer/`: Updated specifications for asset declarations.
|