# Map Renderer Phase Plan

## Phase 1

Goal: tighten the current viewer flow without changing the map semantics.

- remove the explicit manual build button because map selection and filter changes already trigger builds automatically
- hide the viewport's "choose a detected map" message as soon as a map is selected and a build starts
- add build feedback in the side panel with a spinner and a simple phase-based loading bar
- remove visible tile seam lines and the synthetic background grid so the map reads as one surface
- use a more efficient streamed visualization format for interactive tiles while keeping PNG as the final export format

Phase 1 implementation choice:

- interactive tiles switch from PNG to lossless WebP because it is broadly supported in current browsers and is more bandwidth-efficient for repeated server-rendered tile delivery
- full-map download remains PNG so export quality and compatibility stay unchanged

## Phase 2

Goal: promote editor-only content from "baked into the raster" to interactive overlay objects.

- completed: keep the base map rendered as a flat server-generated tile surface
- completed: extract editor-only objects into a standalone overlay data stream
- completed: render editor-only overlay items in the client as positioned sprite overlays above the base map
- completed: remove editor-only records from the base raster so overlay shapes are not duplicated in the map tiles
- completed: fix overlay transparency so the sprite background stays transparent instead of fading black
- completed: add an inspection mode checkbox that shows metadata for any rendered shape under the cursor, not just editor overlays
- improve roof detection before or during the overlay split because the current roof filtering still lets some roofs render when they should not
- identify occluding helper geometry such as invisible walls and render those semitransparently so they remain legible without hiding too much of the map beneath them
- fix pipe rendering because pipes currently are not showing up correctly
- investigate force-field rendering because they appear yellow instead of the expected blue semitransparent look; this may be a debug-shape choice issue or a palette/color-rendering issue
- likely revisit ScummVM Crusader handling in `D:\source\scummvm` to confirm what editor/debug records carry and how best to decode them for display

Current phase 2 status:

- the server now builds three outputs from one map build: base raster tiles, editor-only overlay sprites, and a shared inspectable-shape metadata stream
- editor-only shapes are interactive overlay sprites rendered from their original decoded frames rather than synthetic markers
- when inspect mode is active, the cursor reports metadata for whichever rendered shape is currently under it, including base-map shapes

Next steps:

- use inspect mode on representative maps to identify which visible structures are true roofs versus normal geometry so roof filtering can be tightened with evidence
- decide which helper/occluder families should stay semitransparent overlays and which should eventually be hidden or toggled separately
- inspect broken pipe shapes and compare their metadata against ScummVM handling to determine why they currently render incorrectly
- inspect force-field shapes and compare palette or translucency traits against expected in-game appearance

Open questions for phase 2:

- which helper/editor families should stay as overlay sprites versus gain their own visibility toggles
- what exact metadata fields are reliable enough to expose in the tooltip long-term
- whether some editor-only entries should be clustered, filtered, or toggled by family to keep dense maps usable