Crusader_Decomp/docs/map-renderer-shared-scene-data.md

# Map Renderer Shared Scene Data

The map-viewer originally embedded a large amount of game-level data into every per-map `scene.json`. The first obvious duplication was `shapeDefinitions`, but the real repeated payload was larger: the same catalog-derived shape metadata, sprite metadata, and atlas packing output were being rebuilt and reserialized for each map.

The current layout moves that shared data to per-logical-game reference payloads and keeps per-map scenes focused on actual level content.

## What Was Repeated Per Map

- `shapeDefinitions[]` was repeated in every map scene even though each definition is derived from logical game data, not map-local state.
- `shapeDefinitions[].catalogEntry`, `catalogOverrides`, and `tableFallback` were repeated anywhere the same shape appeared.
- `sprites[]` metadata was repeated per map even though sprite records are also game-level assets.
- Atlas packing output was effectively repeated per map because each map serialized or referenced its own local atlas build even when the packed sprite set overlapped heavily with other maps from the same logical game.
- `metadata.gameLabel` repeated catalog data that the viewer can recover from the selected game entry.
- `metadata.usage.tableAddress`, `metadata.usage.entryCount`, and `metadata.usage.baseMaps` repeated mission-table data already available through the shared `mission-map-data.json` cache.
- `metadata.usage.game` and `metadata.usage.map` duplicated `metadata.game` and `metadata.map`.

## What Changed

- Build-cache output now stays under `.cache`.
- Shared reference payloads are built once per logical game under `.cache/reference-data/<referenceId>/`.
- Static export copies those already-built shared payloads into:
  - `map_renderer/site/data/reference-data/<referenceId>.json`
  - `map_renderer/site/data/reference-atlases/<referenceId>/atlas-*.png`
- Per-map `scene.json` files now carry map-specific scene data plus a compact `references` block:
  - `references.referenceId`
  - `references.atlasIds[]`
  - `references.spriteIds[]`
  - `references.shapeDefinitionIds[]`
- The shared reference payload now contains the full game-level asset metadata needed to hydrate compact scenes:
  - `shapeDefinitions[]`
  - `sprites[]`
  - `atlases[]`
- Static export no longer writes per-map atlas copies.
- Dynamic loading now reuses the same per-game shared references and shared atlas files instead of treating atlas generation as map-local output.
- `metadata.gameLabel` is no longer serialized into static map scenes; the viewer rehydrates it from the selected catalog entry.
- Mission-table fields already present in `mission-map-data.json` are no longer duplicated into each static map scene usage block.

## Why This Split Is Safe

- `buildShapeDefinition(...)` depends only on game-level inputs, not map-local state.
- Sprite metadata and atlas placement are functions of the logical game's referenced asset set, so they can be cached once and reused across maps.
- Items already reference shapes indirectly through `shapeDefId`, so map scenes only need the referenced ids, not inline copies of the full definitions.
- Catalog edits are already scoped per logical game (`remorse`, `regret`), so the shared reference payload matches the existing catalog model.
- Versioned releases like `remorse`, `remorse-101`, `remorse-demo`, and `remorse-jp` already share a logical catalog id, so they also share the same reference payload.

## Measured Duplication Before The Change

From the earlier generated static site:

- `remorse`: about 10.08 MB of serialized shape-definition JSON repeated across 63 maps
- `remorse-101`: about 10.08 MB repeated across 63 maps
- `remorse-jp`: about 10.08 MB repeated across 63 maps
- `regret`: about 6.13 MB repeated across 38 maps

Those totals only covered serialized `shapeDefinitions`. They did not include the repeated sprite metadata, atlas duplication, or the extra metadata duplication removed from static map scenes.

## New Layout

- Per-map scene: map-specific items, bounds, map source, scene summaries, and compact references only.
- Per-game reference data: shape definitions, sprite metadata, atlas metadata, catalog-derived names and flags, and dtable fallbacks.
- Shared atlas images: one atlas set per logical game, copied from `.cache/reference-data/<referenceId>/` into the static site only during explicit export.
- Global caches that remain global: `mission-map-data.json`, `npc-spawner-data.json`, and the CSV catalog exports.

## Cache And Export Behavior

- `npm run build-cache` without `--game` or `--map` clears `.cache` first and rebuilds from scratch.
- `build-cache` can warm multiple logical games in parallel via `--threads=`.
- `--threads=0` means auto, `--threads=-1` forces serial execution, and a positive value caps worker concurrency.
- Dynamic scene builds first try to reuse shared per-game reference data and only rebuild that global data when the fingerprint is stale or the required referenced ids are missing.
- Static export clears `site` and then copies the already-built shared reference data out of `.cache` instead of regenerating separate per-map atlas payloads.

## Notes

- Dynamic and static loading remain backward-compatible because the viewer accepts both older inline scenes and the newer compact reference-based scenes.
- The scene JSON download button in the viewer still exports the fully hydrated in-memory scene, which remains useful for inspection even though the on-disk static representation is compact.