|
| 1 | +# PLAN_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION |
| 2 | + |
| 3 | +## Purpose |
| 4 | +Adopt the shared project asset registry in Tile Map Editor using the Sprite Editor registry contracts already present in the latest uploaded Sprite Editor code. This PR is docs-only and defines the next small, surgical implementation step for Codex. No implementation code is included in this bundle. |
| 5 | + |
| 6 | +## Why this PR now |
| 7 | +The uploaded Sprite Editor already shows additive project asset registry behavior: |
| 8 | +- registry load/save in Project I/O |
| 9 | +- sprite asset registration |
| 10 | +- palette asset registration |
| 11 | +- `assetRefs` persisted in sprite JSON |
| 12 | +- compatibility with engine-owned palette authority |
| 13 | + |
| 14 | +That means the next safest repo step is not more Sprite Editor coding. The next step is to let Tile Map Editor consume and publish the same registry contracts so sprite, palette, and tileset assets can be resolved through one project-owned asset graph. |
| 15 | + |
| 16 | +## Goals |
| 17 | +1. Make Tile Map Editor able to load and save `project.assets.json`. |
| 18 | +2. Register tilemap-owned assets additively without overwriting Sprite Editor entries. |
| 19 | +3. Resolve sprite and palette references from the shared registry by id, not by hard-coded editor-local paths. |
| 20 | +4. Preserve backward compatibility for older tilemap files that have no registry or `assetRefs`. |
| 21 | +5. Keep engine APIs unchanged and avoid runtime-breaking coupling. |
| 22 | + |
| 23 | +## Non-Goals |
| 24 | +- No engine core API changes. |
| 25 | +- No Sprite Editor rework in this PR. |
| 26 | +- No Parallax Editor adoption in this PR. |
| 27 | +- No forced migration of legacy tilemap JSON files. |
| 28 | +- No full-project asset browser UI in this PR. |
| 29 | + |
| 30 | +## Proposed Scope |
| 31 | +### In scope |
| 32 | +- Tile Map Editor project I/O integration for `project.assets.json` |
| 33 | +- Additive registry merge/update behavior |
| 34 | +- `assetRefs` support on tilemap project documents |
| 35 | +- Registry-based resolution for palette/tileset/sprite references where Tile Map Editor already has compatible hooks |
| 36 | +- Graceful fallback when registry entries are missing or stale |
| 37 | +- Minimal status messaging showing whether registry resolution succeeded or fell back |
| 38 | + |
| 39 | +### Out of scope |
| 40 | +- Registry garbage collection |
| 41 | +- Cross-tool rename propagation |
| 42 | +- Asset preview galleries |
| 43 | +- Registry schema expansion beyond what Tile Map Editor needs for adoption |
| 44 | + |
| 45 | +## Current reference state from uploaded Sprite Editor |
| 46 | +The uploaded Sprite Editor code indicates the following contracts are already live and should be treated as source constraints for this PR: |
| 47 | +- imports shared registry helpers from `../../shared/projectAssetRegistry.js` |
| 48 | +- uses additive upsert/merge flows instead of replacing the registry wholesale |
| 49 | +- persists `assetRefs.paletteId` and `assetRefs.spriteId` |
| 50 | +- keeps palette selection engine-owned and locked after selection |
| 51 | +- supports legacy JSON when registry refs are absent |
| 52 | + |
| 53 | +Tile Map Editor adoption must match these behaviors rather than inventing a parallel contract. |
| 54 | + |
| 55 | +## Target Contracts |
| 56 | +### 1. Shared registry ownership |
| 57 | +- Project registry remains project-owned, not editor-owned. |
| 58 | +- Tile Map Editor reads and writes the same `project.assets.json` used by Sprite Editor. |
| 59 | +- Tile Map Editor must preserve foreign asset groups and unknown fields when safely possible. |
| 60 | + |
| 61 | +### 2. Additive write contract |
| 62 | +- Saving from Tile Map Editor updates only relevant tilemap/tile-related entries. |
| 63 | +- Existing `sprites`, `palettes`, and future groups are preserved. |
| 64 | +- Registry writes must be deterministic and id-stable. |
| 65 | + |
| 66 | +### 3. Asset identity contract |
| 67 | +Use ids, not direct editor-local paths, for logical references: |
| 68 | +- `paletteId` |
| 69 | +- `spriteId` when tile placements or entity markers reference sprite assets |
| 70 | +- `tilesetId` |
| 71 | +- `tilemapId` |
| 72 | + |
| 73 | +Paths may still exist as metadata, but runtime/editor linkage should prefer ids. |
| 74 | + |
| 75 | +### 4. Legacy compatibility contract |
| 76 | +- Old tilemap files without `assetRefs` remain loadable. |
| 77 | +- Old tilemap files without registry access remain editable. |
| 78 | +- Missing registry entries produce soft warnings, not hard failure. |
| 79 | +- Editor may fall back to local embedded config/path behavior when registry lookup fails. |
| 80 | + |
| 81 | +### 5. Small-slice adoption contract |
| 82 | +- Only adopt the minimum registry surface Tile Map Editor needs. |
| 83 | +- Do not redesign Tile Map Editor data model beyond the registry seam. |
| 84 | +- Avoid coupling Tile Map Editor to Sprite Editor implementation details. |
| 85 | + |
| 86 | +## Expected data additions |
| 87 | +### Tile Map project document |
| 88 | +Add optional `assetRefs` block: |
| 89 | +```json |
| 90 | +{ |
| 91 | + "assetRefs": { |
| 92 | + "paletteId": "palette:arcade-classic", |
| 93 | + "tilesetId": "tileset:forest-pack", |
| 94 | + "spriteIds": ["sprite:hero-idle", "sprite:coin-spin"] |
| 95 | + } |
| 96 | +} |
| 97 | +``` |
| 98 | + |
| 99 | +### Registry groups used by Tile Map Editor |
| 100 | +Expected additive groups: |
| 101 | +- `palettes` |
| 102 | +- `sprites` |
| 103 | +- `tilesets` |
| 104 | +- `tilemaps` |
| 105 | + |
| 106 | +### Suggested tilemap registry entry |
| 107 | +```json |
| 108 | +{ |
| 109 | + "id": "tilemap:overworld-01", |
| 110 | + "name": "overworld-01", |
| 111 | + "path": "assets/tilemaps/overworld-01.json", |
| 112 | + "tilesetId": "tileset:forest-pack", |
| 113 | + "paletteId": "palette:arcade-classic", |
| 114 | + "sourceTool": "tile-map-editor" |
| 115 | +} |
| 116 | +``` |
| 117 | + |
| 118 | +## Likely files for Codex to inspect |
| 119 | +- `tools/Tile Map Editor/index.html` |
| 120 | +- `tools/Tile Map Editor/main.js` |
| 121 | +- `tools/Tile Map Editor/modules/*` |
| 122 | +- `shared/projectAssetRegistry.js` |
| 123 | +- any repo docs already describing project JSON or asset packaging |
| 124 | + |
| 125 | +## Implementation guidance for Codex |
| 126 | +### Do |
| 127 | +- Reuse shared registry helpers that Sprite Editor already uses. |
| 128 | +- Mirror Sprite Editor additive merge/upsert patterns where appropriate. |
| 129 | +- Keep UI additions minimal and status-oriented. |
| 130 | +- Preserve current Tile Map Editor flows first; add registry as an additive layer. |
| 131 | + |
| 132 | +### Do not |
| 133 | +- Do not rewrite Tile Map Editor architecture. |
| 134 | +- Do not break editor startup when registry file is absent. |
| 135 | +- Do not introduce engine dependency changes. |
| 136 | +- Do not silently discard foreign registry groups. |
| 137 | + |
| 138 | +## Manual validation checklist |
| 139 | +1. Load Tile Map Editor without a registry file; normal legacy editing still works. |
| 140 | +2. Load `project.assets.json`; existing sprite and palette entries remain visible/preserved after save. |
| 141 | +3. Save a tilemap; registry receives stable `tilemaps` entry and any needed `tilesets` linkage. |
| 142 | +4. Reload saved registry and tilemap; ids resolve correctly. |
| 143 | +5. Missing `tilesetId` or `paletteId` triggers soft warning only. |
| 144 | +6. Legacy tilemap JSON with no `assetRefs` loads and can be re-saved. |
| 145 | +7. Saving from Tile Map Editor does not delete Sprite Editor `sprites` or `palettes` entries. |
| 146 | +8. No engine core APIs are changed. |
| 147 | +9. Repo remains limited to this PR scope. |
| 148 | + |
| 149 | +## Risk notes |
| 150 | +- Highest risk is destructive registry overwrite. |
| 151 | +- Second highest risk is accidental path-based coupling that bypasses ids. |
| 152 | +- Third risk is mixed legacy/registry save behavior producing unstable ids. |
| 153 | + |
| 154 | +## BUILD command |
| 155 | +MODEL: GPT-5.4 |
| 156 | +REASONING: high |
| 157 | +COMMAND: |
| 158 | +Create BUILD_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION. |
| 159 | + |
| 160 | +Requirements: |
| 161 | +- Docs-first implementation of Tile Map Editor registry adoption only |
| 162 | +- Reuse shared registry helpers already used by Sprite Editor |
| 163 | +- Add support for loading/saving `project.assets.json` |
| 164 | +- Persist optional `assetRefs` for tilemap documents |
| 165 | +- Register/update `tilemaps` and relevant `tilesets` additively |
| 166 | +- Preserve existing registry groups and unknown safe fields |
| 167 | +- Backward compatibility required for legacy tilemap JSON |
| 168 | +- No engine core API changes |
| 169 | +- No Parallax Editor work in this PR |
| 170 | + |
| 171 | +Validation: |
| 172 | +- All checklist items in `docs/dev/reports/validation_checklist.txt` must pass |
| 173 | +- Include syntax validation for changed JS files |
| 174 | +- Package delta zip only |
| 175 | + |
| 176 | +Package: |
| 177 | +- Output zip to `HTML-JavaScript-Gaming/tmp/BUILD_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION_delta.zip` |
| 178 | + |
| 179 | +## Commit comment |
| 180 | +`plan(tilemap-editor): adopt shared project asset registry contracts` |
| 181 | + |
| 182 | +## Next command after BUILD |
| 183 | +`APPLY_PR_TILEMAP_EDITOR_ASSET_REGISTRY_ADOPTION` |
0 commit comments