Crusader_Decomp/docs/map_renderer/map-editing.md

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:

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:

generated/map-compiler/<game>/split/

Each map is written to its own folder:

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:

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.