- recompute mAreaExits on every writeMap / writeMapToBuffer call so cross-area routing data stays in sync with the room graph. Mirrors Mudlet's TArea::determineAreaExits: cardinal exits encode as [targetId, DIR_*] with DIR_NORTH=1..DIR_OUT=12, string-named special exits encode as [targetId, DIR_OTHER=13], and dangling or same-area exits are excluded.

Delwing · Delwing · commit fcb90834fa06 · 2026-04-24T11:06:32.000+02:00
- recompute per-area spatial extents (`zLevels`, `min_x`/`max_x`/`min_y`/`max_y`/`min_z`/`max_z`, and the per-Z `xminForZ`/`xmaxForZ`/`yminForZ`/`ymaxForZ` maps) on every `writeMap` / `writeMapToBuffer` call so Mudlet's renderer gets the right bounding box and Z-level list after any editor mutation. Mirrors `TArea::calcSpan` in Mudlet's `src/TArea.cpp`, including two C++ quirks: y is negated when stored on the area (`area.min_y = -room.y`), and the `span` / `pos` `QVector3D` fields are deliberately left untouched because C++ never writes them either. Areas with zero rooms have their per-Z maps and `zLevels` cleared but their min/max preserved, again matching C++.
- recompute `mpRoomDbHashToRoomId` on every `writeMap` / `writeMapToBuffer` call so the room content-hash index stays in sync with the room graph. Mirrors `TRoomDB::hashToRoomID` in Mudlet's C++ source. On load, `room.hash` is populated from the inverse of the on-disk index (the binary format carries hashes only on the map, not per room), so callers can treat `room.hash` as the source of truth. On save, the index is rebuilt from each room's `hash` field: rooms with `undefined` / `''` / `null` are skipped, and colliding hashes log a warning with last-write-wins. `mRoomIdHash` (per-profile player cursor) is deliberately left alone — do not confuse the two.
- callers that were maintaining `mAreaExits`, per-area spatial extents, or `mpRoomDbHashToRoomId` by hand will have their values overwritten — the computed values are now authoritative.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,9 @@
+# 0.11.0
+- recompute `mAreaExits` on every `writeMap` / `writeMapToBuffer` call so cross-area routing data stays in sync with the room graph. Mirrors Mudlet's `TArea::determineAreaExits`: cardinal exits encode as `[targetId, DIR_*]` with DIR_NORTH=1..DIR_OUT=12, string-named special exits encode as `[targetId, DIR_OTHER=13]`, and dangling or same-area exits are excluded.
+- recompute per-area spatial extents (`zLevels`, `min_x`/`max_x`/`min_y`/`max_y`/`min_z`/`max_z`, and the per-Z `xminForZ`/`xmaxForZ`/`yminForZ`/`ymaxForZ` maps) on every `writeMap` / `writeMapToBuffer` call so Mudlet's renderer gets the right bounding box and Z-level list after any editor mutation. Mirrors `TArea::calcSpan` in Mudlet's `src/TArea.cpp`, including two C++ quirks: y is negated when stored on the area (`area.min_y = -room.y`), and the `span` / `pos` `QVector3D` fields are deliberately left untouched because C++ never writes them either. Areas with zero rooms have their per-Z maps and `zLevels` cleared but their min/max preserved, again matching C++.
+- recompute `mpRoomDbHashToRoomId` on every `writeMap` / `writeMapToBuffer` call so the room content-hash index stays in sync with the room graph. Mirrors `TRoomDB::hashToRoomID` in Mudlet's C++ source. On load, `room.hash` is populated from the inverse of the on-disk index (the binary format carries hashes only on the map, not per room), so callers can treat `room.hash` as the source of truth. On save, the index is rebuilt from each room's `hash` field: rooms with `undefined` / `''` / `null` are skipped, and colliding hashes log a warning with last-write-wins. `mRoomIdHash` (per-profile player cursor) is deliberately left alone — do not confuse the two.
+- callers that were maintaining `mAreaExits`, per-area spatial extents, or `mpRoomDbHashToRoomId` by hand will have their values overwritten — the computed values are now authoritative.
+
 # 0.8.0
 - remove `fs` dependency from core modules; file I/O is now the caller's responsibility
 - add `readMapFromBuffer` and `writeMapToBuffer` for buffer-based read/write without touching the filesystem
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mudlet-map-binary-reader",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "keywords": [
     "mudlet",
     "map",
diff --git a/src/map-operations.ts b/src/map-operations.ts
@@ -6,6 +6,208 @@ const { ReadBuffer } = buffer;
 
 type RawRoom = MudletRoom & { rawSpecialExits: Record<number, string[]> };
 
+// Mirrors Mudlet's DIR_* constants from src/TMap.h. Used as the second element
+// of each QPair<int,int> entry in TArea::mAreaExits.
+const CARDINAL_DIRS = [
+  'north',
+  'northeast',
+  'east',
+  'southeast',
+  'south',
+  'southwest',
+  'west',
+  'northwest',
+  'up',
+  'down',
+  'in',
+  'out',
+] as const satisfies readonly (keyof MudletRoom)[];
+
+const DIR_INDEX: Record<(typeof CARDINAL_DIRS)[number], number> = {
+  north: 1,
+  northeast: 2,
+  northwest: 3,
+  east: 4,
+  west: 5,
+  south: 6,
+  southeast: 7,
+  southwest: 8,
+  up: 9,
+  down: 10,
+  in: 11,
+  out: 12,
+};
+
+const DIR_OTHER = 13;
+
+/**
+ * Rebuild every area's `mAreaExits` from the current room graph. This field
+ * is a cache Mudlet's autowalker/pathfinder uses to navigate between zones,
+ * and mirrors TArea::determineAreaExits in Mudlet's C++ source. Any editor
+ * that mutates rooms / exits and re-saves must regenerate it — otherwise the
+ * cache goes stale and Mudlet's routing breaks.
+ */
+function rebuildAreaExits(map: MudletMap): void {
+  for (const areaId in map.areas) {
+    if (!Object.hasOwn(map.areas, areaId)) continue;
+    map.areas[areaId as unknown as number].mAreaExits = {};
+  }
+
+  for (const idStr in map.rooms) {
+    if (!Object.hasOwn(map.rooms, idStr)) continue;
+    const roomId = Number(idStr);
+    const room = map.rooms[roomId];
+    const srcArea = map.areas[room.area];
+    if (!srcArea) continue;
+
+    const entries: [number, number][] = [];
+
+    for (const dir of CARDINAL_DIRS) {
+      const targetId = room[dir] as number;
+      if (!targetId || targetId < 1) continue;
+      const target = map.rooms[targetId];
+      if (!target || target.area === room.area) continue;
+      entries.push([targetId, DIR_INDEX[dir]]);
+    }
+
+    const specials = room.mSpecialExits ?? {};
+    const specialNames = Object.keys(specials).sort();
+    for (const name of specialNames) {
+      const targetId = specials[name];
+      if (!targetId || targetId < 1) continue;
+      const target = map.rooms[targetId];
+      if (!target || target.area === room.area) continue;
+      entries.push([targetId, DIR_OTHER]);
+    }
+
+    if (entries.length > 0) {
+      srcArea.mAreaExits[roomId] = entries;
+    }
+  }
+}
+
+/**
+ * Rebuild every area's spatial-extent cache (zLevels, min/max x/y/z, and the
+ * per-Z xminForZ/xmaxForZ/yminForZ/ymaxForZ maps) from the current room graph.
+ * Mirrors Mudlet's TArea::calcSpan in src/TArea.cpp.
+ *
+ * Two quirks inherited from C++:
+ *   1. y is negated when stored on the area. room.y is plain, but
+ *      area.min_y / max_y / yminForZ / ymaxForZ all hold `-room.y`.
+ *   2. span and pos are NOT recomputed. calcSpan never touches them, and
+ *      the TArea.h header flags them both as effectively dead. We leave
+ *      them as-is so round-tripping an untouched map stays byte-identical.
+ *   3. For an area with zero valid rooms, the per-Z maps and zLevels are
+ *      cleared but min/max are preserved — again, matching C++.
+ */
+function rebuildAreaExtents(map: MudletMap): void {
+  for (const areaIdStr in map.areas) {
+    if (!Object.hasOwn(map.areas, areaIdStr)) continue;
+    const area = map.areas[areaIdStr as unknown as number];
+
+    area.xminForZ = {};
+    area.xmaxForZ = {};
+    area.yminForZ = {};
+    area.ymaxForZ = {};
+    area.zLevels = [];
+
+    let first = true;
+    for (const roomId of area.rooms) {
+      const room = map.rooms[roomId];
+      if (!room) continue;
+      const x = room.x;
+      const y = -room.y;
+      const z = room.z;
+
+      if (first) {
+        area.min_x = x;
+        area.max_x = x;
+        area.min_y = y;
+        area.max_y = y;
+        area.min_z = z;
+        area.max_z = z;
+        area.zLevels.push(z);
+        area.xminForZ[z] = x;
+        area.xmaxForZ[z] = x;
+        area.yminForZ[z] = y;
+        area.ymaxForZ[z] = y;
+        first = false;
+        continue;
+      }
+
+      if (!area.zLevels.includes(z)) area.zLevels.push(z);
+
+      if (area.xminForZ[z] === undefined || x < area.xminForZ[z]) area.xminForZ[z] = x;
+      if (x < area.min_x) area.min_x = x;
+      if (area.xmaxForZ[z] === undefined || x > area.xmaxForZ[z]) area.xmaxForZ[z] = x;
+      if (x > area.max_x) area.max_x = x;
+
+      if (area.yminForZ[z] === undefined || y < area.yminForZ[z]) area.yminForZ[z] = y;
+      if (y < area.min_y) area.min_y = y;
+      if (y > area.max_y) area.max_y = y;
+      if (area.ymaxForZ[z] === undefined || y > area.ymaxForZ[z]) area.ymaxForZ[z] = y;
+
+      if (z < area.min_z) area.min_z = z;
+      if (z > area.max_z) area.max_z = z;
+    }
+
+    if (area.zLevels.length > 1) area.zLevels.sort((a, b) => a - b);
+  }
+}
+
+/**
+ * Populate each `room.hash` from the inverse of `map.mpRoomDbHashToRoomId`.
+ * The binary format doesn't carry a per-room hash field — the hash lives
+ * only in the map-level index. Copying it onto the room on load lets
+ * editors treat `room.hash` as the source of truth, and lets
+ * {@link rebuildRoomHashIndex} rebuild the index cleanly on save.
+ *
+ * NOTE: this is specifically about the content hash index
+ * (`mpRoomDbHashToRoomId` — mirrors Mudlet's `TRoomDB::hashToRoomID`).
+ * The similarly-named `mRoomIdHash` is something else entirely: it maps
+ * Mudlet profile name → player's current room ID. Do not touch it here.
+ */
+function populateRoomHashes(map: MudletMap): void {
+  for (const hash in map.mpRoomDbHashToRoomId) {
+    if (!Object.hasOwn(map.mpRoomDbHashToRoomId, hash)) continue;
+    const roomId = map.mpRoomDbHashToRoomId[hash];
+    const room = map.rooms[roomId];
+    if (room) room.hash = hash;
+  }
+}
+
+/**
+ * Rebuild `map.mpRoomDbHashToRoomId` from the `hash` field on each room.
+ * Mirrors Mudlet's `TRoomDB::hashToRoomID`. Callers can freely mutate
+ * `room.hash` (or add/remove rooms) between load and save; this helper
+ * keeps the on-disk index consistent.
+ *
+ * Rooms with `hash === undefined`, `''`, or `null` are skipped. If two
+ * rooms declare the same non-empty hash (should not happen in a sane
+ * map) the later iteration wins and a warning is logged — the underlying
+ * data is already inconsistent at that point.
+ *
+ * NOTE: does not touch `mRoomIdHash`. That's the per-profile player
+ * cursor (profile name → room ID) and is not derivable from rooms.
+ */
+function rebuildRoomHashIndex(map: MudletMap): void {
+  map.mpRoomDbHashToRoomId = {};
+  for (const idStr in map.rooms) {
+    if (!Object.hasOwn(map.rooms, idStr)) continue;
+    const room = map.rooms[idStr as unknown as number];
+    const hash = room.hash;
+    if (typeof hash !== 'string' || hash.length === 0) continue;
+    const roomId = Number(idStr);
+    if (Object.hasOwn(map.mpRoomDbHashToRoomId, hash)) {
+      const prev = map.mpRoomDbHashToRoomId[hash];
+      console.warn(
+        `[mudlet-map-binary-reader] duplicate room hash "${hash}" on rooms ${prev} and ${roomId}; last wins`
+      );
+    }
+    map.mpRoomDbHashToRoomId[hash] = roomId;
+  }
+}
+
 /**
  * Hydrate the `mSpecialExits` / `mSpecialExitLocks` fields on every room
  * by parsing the `rawSpecialExits` layout Qt stores on disk.
@@ -64,6 +266,7 @@ export function readMapFromBuffer(buf: Buffer): MudletMap {
   const rb = new ReadBuffer(buf);
   const map = QUserType.read(rb, 'MudletMap') as MudletMap;
   hydrateSpecialExits(map);
+  populateRoomHashes(map);
   return map;
 }
 
@@ -75,6 +278,9 @@ export function readMapFromBuffer(buf: Buffer): MudletMap {
  */
 export function writeMapToBuffer(map: MudletMap): Buffer {
   dehydrateSpecialExits(map);
+  rebuildAreaExits(map);
+  rebuildAreaExtents(map);
+  rebuildRoomHashIndex(map);
   return QUserType.get('MudletMap').from(map).toBuffer(true);
 }
 
diff --git a/test/fixtures.ts b/test/fixtures.ts
@@ -142,6 +142,58 @@ export const makeMultiAreaMap = (): MudletMap => {
   return map;
 };
 
+// Map with 2 areas: A=1 (rooms 1,2,3) and B=2 (rooms 10,11).
+// Cross-area exits: room 2 (area 1) east → room 10 (area 2);
+//                   room 10 (area 2) west → room 2 (area 1).
+// Intra-area exits left as stubs/unset so they don't muddy mAreaExits.
+export const makeCrossAreaMap = (): MudletMap => {
+  const map = makeMinimalMap();
+  map.areaNames[2] = 'Area B';
+  map.areas[1] = makeMinimalArea([1, 2, 3]);
+  map.areas[2] = makeMinimalArea([10, 11]);
+  map.rooms[1] = makeMinimalRoom(1, 1);
+  map.rooms[2] = makeMinimalRoom(2, 1);
+  map.rooms[3] = makeMinimalRoom(3, 1);
+  map.rooms[10] = makeMinimalRoom(10, 2);
+  map.rooms[11] = makeMinimalRoom(11, 2);
+  map.rooms[2].east = 10;
+  map.rooms[10].west = 2;
+  return map;
+};
+
+// Map with 4 rooms in area 1 spread across 2 z-levels with varying x/y,
+// for exercising rebuildAreaExtents. Coordinates are picked so every
+// min/max and every per-Z bound is distinct and so the y-sign inversion
+// is observable (areas store -room.y; see TArea::calcSpan in Mudlet).
+//
+//   z=0: room 1 at (1,  2), room 2 at (5, -3)
+//   z=1: room 3 at (0,  0), room 4 at (7,  4)
+export const makeExtentsFixture = (): MudletMap => {
+  const map = makeMinimalMap();
+  map.areas[1] = makeMinimalArea([1, 2, 3, 4]);
+  map.rooms[1] = { ...makeMinimalRoom(1, 1), x: 1, y: 2, z: 0 };
+  map.rooms[2] = { ...makeMinimalRoom(2, 1), x: 5, y: -3, z: 0 };
+  map.rooms[3] = { ...makeMinimalRoom(3, 1), x: 0, y: 0, z: 1 };
+  map.rooms[4] = { ...makeMinimalRoom(4, 1), x: 7, y: 4, z: 1 };
+  return map;
+};
+
+// Map with 3 rooms in area 1: rooms 1 and 2 carry distinct non-empty hashes,
+// room 3 has no hash. Used to exercise rebuildRoomHashIndex — after a round
+// trip, mpRoomDbHashToRoomId should contain the two hash keys and nothing else.
+export const makeMapWithHashes = (): MudletMap => {
+  const map = makeMinimalMap();
+  map.areas[1] = makeMinimalArea([1, 2, 3]);
+  map.rooms[1] = { ...makeMinimalRoom(1, 1), hash: 'hash-room-1' };
+  map.rooms[2] = { ...makeMinimalRoom(2, 1), hash: 'hash-room-2' };
+  map.rooms[3] = makeMinimalRoom(3, 1);
+  map.mpRoomDbHashToRoomId = {
+    'hash-room-1': 1,
+    'hash-room-2': 2,
+  };
+  return map;
+};
+
 export const makeMinimalLabel = (): MudletLabel => ({
   id: 1,
   pos: [0, 0, 0],
diff --git a/test/map-operations.test.ts b/test/map-operations.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "mudlet-map-binary-reader",`
`3`		`- "version": "0.8.0",`
	`3`	`+ "version": "0.9.0",`
`4`	`4`	`"keywords": [`
`5`	`5`	`"mudlet",`
`6`	`6`	`"map",`