Decomp updates

docs/map_renderer/map-editing.md

@@ -0,0 +1,123 @@
+# Map Editing Workflow
+
+## Current Scope
+
+The browser renderer now supports these in-memory map edits:
+
+- add a new teleporter egg to the currently loaded map
+- add a new teleport destination egg to the currently loaded map
+- edit the teleport id for existing or newly placed teleporter and teleport destination eggs
+
+This works in both dynamic and static site modes because the edit only changes the client-side map source held in memory. Nothing is written back to the original Crusader data files from the browser.
+
+## Browser Behavior
+
+### Add Teleporter Or Destination Egg
+
+- Open the `Eggs` panel.
+- The `New teleport ID` field is prefilled with the next free teleport id the renderer can find.
+- Change it if you want a different id.
+- Click `Add Teleporter` or `Add Destination`.
+- Move the cursor over the map. A preview egg follows the pointer.
+- Click to place the egg.
+- Press `Esc` or click the active button again to cancel placement.
+
+Placement rules:
+
+- if the cursor is over empty space, the new egg is placed at `Z = 0`
+- if the cursor is over a rendered item, the new egg uses the top height of that item: `item.world.z + shape_definition.dimensions.z * 8`
+- the world position is reconstructed from the current screen point and chosen `Z` using the same isometric projection the renderer already uses for scene items
+
+The current implementation uses the scene's default teleport-egg template shape plus the teleporter or destination frame from the Crusader data set.
+
+If the chosen teleport id is already used by another teleporter or destination egg, the UI warns but still allows the placement.
+
+After a successful placement, the field advances to the next free id again.
+
+### Edit Teleport IDs
+
+- Pin a teleporter or teleport destination egg.
+- Click the pen button in the tooltip header.
+- Use the modal editor that opens.
+- Change the `Teleport ID` and save.
+
+The duplicate-id check is warning-only. The edit is still applied so you can intentionally create or inspect collisions.
+
+For teleport destination eggs, this edits the destination egg's own id.
+
+These edits do not require admin mode because they only change the in-memory FIXED map payload used by the renderer and exports.
+
+### Downloads
+
+The `Downloads` panel now includes:
+
+- `Download Map Binary`: exports the current map as a raw per-map FIXED payload (`16` bytes per item record)
+- `Download Map JSON`: exports the current scene JSON, including the editable `mapSource` block
+
+The binary export is the direct payload for a single map entry inside `FIXED.DAT`, not a full rebuilt archive.
+
+## Lossless Map Source
+
+Each built scene now carries a `mapSource` block. That block is the source of truth for editing/export and contains:
+
+- the game id and map id
+- the original per-map byte length
+- the fixed record size (`16`)
+- the default teleport egg template shape/frame
+- the full list of FIXED item records decoded into JSON fields
+
+This exists because the painted scene is not a lossless representation of `FIXED.DAT`: invalid or fully occluded records can be dropped during scene generation.
+
+## Offline Split/Rebuild Tool
+
+Use the new npm entry point:
+
+```text
+npm run map-compiler -- split --game=remorse
+npm run map-compiler -- rebuild --game=remorse --from=json
+npm run map-compiler -- rebuild --game=remorse --from=binary
+```
+
+If no parameters are supplied, the tool enters an interactive console mode.
+
+### Split Output
+
+Default split output:
+
+```text
+generated/map-compiler/<game>/split/
+```
+
+Each map is written to its own folder:
+
+```text
+map-<id>/map.bin
+map-<id>/map.json
+```
+
+`map.bin` is the raw per-map FIXED payload. `map.json` is the decoded JSON form using the same item structure as the browser `mapSource`.
+
+If you changed teleport ids or placed new teleport-related eggs in the browser before exporting, those in-memory changes are reflected in the exported JSON and map binary output.
+
+### Rebuild Output
+
+Default rebuild output:
+
+```text
+generated/map-compiler/<game>/rebuilt/FIXED.DAT
+```
+
+The tool always writes rebuilt archives into a generated subfolder and refuses to overwrite the original `FIXED.DAT`.
+
+Rebuild modes:
+
+- `--from=json`: rebuild each map payload from `map.json`
+- `--from=binary`: rebuild each map payload from `map.bin`
+
+Maps without a replacement file keep their original payload from the source archive.
+
+## Notes
+
+- The browser does not currently write changes back into the source static asset tree.
+- The browser edit path currently only creates teleport eggs.
+- The archive rebuild preserves the original non-map header region and rewrites the map table/payload layout into a generated output directory.