Crusader_Decomp/map_renderer/README.md

# Crusader Map Renderer

Node web app that renders Crusader maps on the server and streams only finished PNG tiles to the browser.

## Goals

- Keep Crusader source assets server-side.
- Detect maps from `STATIC` and `STATIC_REGRET` automatically.
- Build map render state on demand after the user selects a map.
- Serve large maps as draggable and zoomable image tiles.
- 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 before building
- when editor-only elements are enabled, the base map excludes those records and the original editor shapes render as interactive overlay sprites with hover metadata

The app expects asset folders under the app root:

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

## Docker Run

The Docker image excludes the Crusader assets on purpose. Mount them at runtime so they stay outside the image and are never served directly to clients.

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

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

## Docker Compose

The compose file mounts `STATIC` and `STATIC_REGRET` from the host filesystem into the container as read-only volumes. They are excluded from the image build by `.dockerignore`, so the assets are never copied into the image.

```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 tile settings.
- `GET /api/maps/:game/:mapId/overlays?buildId=...` returns interactive overlay records for editor-only content.
- `GET /api/maps/:game/:mapId/overlays/:overlayId.webp?buildId=...` returns the rendered sprite for one overlay item.
- `GET /api/maps/:game/:mapId/tiles/:tileX/:tileY.png?buildId=...` returns rendered PNG tiles.

No raw Crusader asset files are exposed over HTTP.