Crusader_Decomp/map_renderer/README.md

# Crusader Map Renderer

Node web app that decodes Crusader maps into cached sprite atlases plus scene JSON, then renders the scene directly in the browser.

## Goals

- Keep Crusader source assets server-side.
- Detect maps from `STATIC` and `STATIC_REGRET` automatically.
- Build map scene caches on demand after the user selects a map.
- Serve cached atlas images and scene JSON so the browser reconstructs the view client-side.
- Run locally with Node or inside Docker.

## Local Run

```powershell
cd map_renderer
npm install
npm start
```

Open `http://localhost:3000`.

Viewer behavior:

- drag with the mouse or one finger to pan
- use the scroll wheel to zoom directly at the pointer
- pinch to zoom on touch devices
- toggle roofs and editor-only elements independently without rebuilding; the client filters one full cached scene payload
- inspect mode lets you pin a shape tooltip, hide a single instance, and restore hidden instances from the left panel
- PNG export is generated in the browser from the cached scene instead of being rasterized server-side
- hidden instances can be exported as JSON and each catalog CSV can be downloaded from the viewer
- the left panel includes a `Reload Current Map` button that forces a fresh rebuild/load of the currently selected map after catalog edits
- catalog CSV rows support `roof` and `semitransparency` boolean overrides; the catalog is authoritative for those properties, so blank means `false` and only explicit `true` turns them on
- cache builds automatically add any newly observed shapes into the matching game catalog CSV without overwriting existing rows, then rewrite the file sorted by `shape_code`
- catalog CSV rows also support non-authoritative `categorization` and `qualities` columns; cache builds auto-fill them when blank from the existing derived categorization and observed per-shape quality values

## Cache Warming

Build atlas and scene cache artifacts outside the request path:

```powershell
cd map_renderer
npm run build-cache
```

Optional focused warmup:

```powershell
cd map_renderer
npm run build-cache -- remorse 1
```

The app expects asset folders under the app root:

- `map_renderer/STATIC`
- `map_renderer/STATIC_REGRET`

## Docker Run

The `dev` image stays light and expects Crusader assets to be mounted at runtime.

```powershell
cd map_renderer
docker build --target dev -t crusader-map-renderer:dev .
docker run --rm -p 3000:3000 `
  -v ${PWD}/STATIC:/app/STATIC:ro `
  -v ${PWD}/STATIC_REGRET:/app/STATIC_REGRET:ro `
  crusader-map-renderer:dev
```

If only one game is available, mount only that folder.

Production image with prebuilt cache artifacts and no raw `STATIC` assets in the final layer:

```powershell
cd map_renderer
docker build --target production -t crusader-map-renderer:prod .
docker run --rm -p 3000:3000 crusader-map-renderer:prod
```

The production target copies `STATIC` and `STATIC_REGRET` only into the intermediate precache stage, runs `npm run build-cache`, then ships just `src`, `Catalogs`, `node_modules`, and `.cache` in the final image.

## Docker Compose

The compose file targets the lightweight `dev` image and mounts `STATIC` and `STATIC_REGRET` from the host filesystem as read-only volumes.

```powershell
cd map_renderer
docker compose up --build
```

## HTTP Surface

- `GET /api/maps` returns the detected catalog.
- `POST /api/builds` starts or reuses a build.
- `GET /api/builds/:id` returns build status.
- `GET /api/maps/:game/:mapId/metadata?buildId=...` returns map bounds and scene metadata.
- `GET /api/maps/:game/:mapId/scene?buildId=...` returns the cached atlas-backed scene payload.
- `GET /api/maps/:game/:mapId/atlases/:atlasId.png?buildId=...` returns a cached packed sprite atlas.
- `GET /api/maps/:game/:mapId/inspect?buildId=...` returns the same per-instance shape metadata used for inspection.
- `GET /api/catalogs/:game.csv` returns the source catalog CSV for that game.

No raw Crusader asset files are exposed over HTTP.