# mudlet-map-binary-reader

> Reads and writes Mudlet's map binary file (v20), with read-only support for older formats (v16-v19). Can output .js files needed for Mudlet Map Reader.

Latest version **2.0.0** (published 2026-08-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install mudlet-map-binary-reader
pnpm add mudlet-map-binary-reader
yarn add mudlet-map-binary-reader
bun add mudlet-map-binary-reader
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2026-08-25 |
| First published | 2021-10-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 249.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 2 |
| Author | Delwing |
| Maintainers | delwing |
| Keywords | mudlet, map, mud |

## Links

- npm: https://www.npmjs.com/package/mudlet-map-binary-reader
- Repository: https://github.com/Delwing/node-mudlet-map-binary-reader
- Homepage: https://github.com/Delwing/node-mudlet-map-binary-reader#readme
- Issues: https://github.com/Delwing/node-mudlet-map-binary-reader/issues
- npm.io page: https://npm.io/package/mudlet-map-binary-reader

## Dependencies (1)

- [qtdatastream-web](https://npm.io/package/qtdatastream-web.md) ^0.0.1

## Recent versions

- 2.0.0 (latest) — 2026-08-25
- 1.3.0 — 2026-08-25
- 1.2.0 — 2026-07-09
- 1.1.0 — 2026-06-24
- 1.0.3 — 2026-06-20
- 1.0.2 — 2026-06-20
- 1.0.1 — 2026-06-20
- 1.0.0 — 2026-06-20
- 0.9.0 — 2026-04-24
- 0.8.0 — 2026-04-21
- 0.7.3 — 2026-04-18
- 0.7.2 — 2026-04-18
- 0.7.1 — 2026-04-17
- 0.7.0 — 2026-04-14
- 0.6.1 — 2026-04-08
- … 16 more at https://npm.io/package/mudlet-map-binary-reader/versions

## README

# Mudlet Map Binary Reader

[![NPM](https://nodei.co/npm/mudlet-map-binary-reader.png)](https://nodei.co/npm/mudlet-map-binary-reader/)

Reads and writes Mudlet's map binary file (v20), and additionally reads the older formats v16–v19 (read-only). Can also convert a map to the [JS Mudlet Map Renderer](https://github.com/Delwing/js-mudlet-map-renderer) format or to Mudlet's JSON format.

The library works with **bytes** and never touches the filesystem — you handle reading and writing files yourself.

This project follows [Semantic Versioning](https://semver.org/).

## Supported map versions

| Version   | Read | Write |
| --------- | :--: | :---: |
| v20       |  ✅  |  ✅   |
| v16 – v19 |  ✅  |  ❌   |

Older maps (v16–v19) are read into the same canonical model as v20, so all the
read examples below work unchanged. To save a legacy map, set `map.version = 20`
before calling `writeBuffer` — reading backfills every field the v20 writer
needs, so the round-trip preserves areas, rooms, and converted legacy fields
(symbol char, custom-line colour and style).

## Usage

The library is browser-pure: it reads and writes **bytes** (`Uint8Array`), and never touches the filesystem itself. You supply the bytes — from Node's `fs`, a `fetch`/`Blob`, a file input, etc.

### Reading a map

```ts
import { readFileSync } from "node:fs";
import { MudletMapReader } from "mudlet-map-binary-reader";

// In Node, read the bytes yourself; in the browser, use fetch/File instead.
const map = MudletMapReader.readBuffer(readFileSync("map.dat"));

console.log(`Map version: ${map.version}`);
console.log(`Areas: ${Object.keys(map.areas).length}`);
console.log(`Rooms: ${Object.keys(map.rooms).length}`);
```

### Inspecting rooms and exits

```ts
const map = MudletMapReader.readBuffer(readFileSync("map.dat"));

for (const [id, room] of Object.entries(map.rooms)) {
  console.log(`Room ${id}: ${room.name} (env ${room.environment})`);

  if (room.north !== -1) console.log(`  north -> ${room.north}`);
  if (room.south !== -1) console.log(`  south -> ${room.south}`);

  for (const [exitName, destId] of Object.entries(room.mSpecialExits)) {
    const locked = room.mSpecialExitLocks.includes(destId) ? " [locked]" : "";
    console.log(`  special: ${exitName} -> ${destId}${locked}`);
  }
}
```

### Modifying and saving

```ts
import { readFileSync, writeFileSync } from "node:fs";

const map = MudletMapReader.readBuffer(readFileSync("map.dat"));

// Rename a room
map.rooms[1].name = "Grand Hall";

// Add user data to a room
map.rooms[1].userData["notes"] = "quest start";

// Move a room
map.rooms[1].x = 10;
map.rooms[1].y = -5;

// Serialize back to bytes, then persist them however you like
const bytes = MudletMapReader.writeBuffer(map);
writeFileSync("map-modified.dat", bytes);
```

### Exporting for JS Mudlet Map Renderer

Converts the map into the data structure used by [js-mudlet-map-renderer](https://github.com/Delwing/js-mudlet-map-renderer). It returns the data — persisting it is up to you.

```ts
import { writeFileSync } from "node:fs";

const map = MudletMapReader.readBuffer(readFileSync("map.dat"));

const { mapData, colors } = MudletMapReader.export(map);
console.log(`Exported ${mapData.length} areas, ${colors.length} colors`);

// Persist however you like:
writeFileSync("mapExport.json", JSON.stringify(mapData));
writeFileSync("colors.json", JSON.stringify(colors));
```

### Exporting to Mudlet JSON format

`exportJson` returns the JSON as a string — write it out yourself.

```ts
import { writeFileSync } from "node:fs";

const map = MudletMapReader.readBuffer(readFileSync("map.dat"));

// Pretty-printed
writeFileSync("map.json", MudletMapReader.exportJson(map));

// Minified
writeFileSync("map.min.json", MudletMapReader.exportJson(map, true));
```

### Working with areas and labels

```ts
const map = MudletMapReader.readBuffer(readFileSync("map.dat"));

for (const [id, name] of Object.entries(map.areaNames)) {
  const area = map.areas[id as unknown as number];
  console.log(`Area ${id}: ${name} (${area.rooms.length} rooms)`);

  const labels = map.labels[id as unknown as number] ?? [];
  for (const label of labels) {
    console.log(`  Label: "${label.text}" at (${label.pos.join(", ")})`);
  }
}
```

### Using with TypeScript types

All model types are exported for use in your own code:

```ts
import { MudletMapReader } from "mudlet-map-binary-reader";
import type { MudletMap, MudletRoom, MudletColor } from "mudlet-map-binary-reader";

function getRoomsByEnvironment(map: MudletMap, envId: number): MudletRoom[] {
  return Object.values(map.rooms).filter((room) => room.environment === envId);
}

function formatColor(color: MudletColor): string {
  return `rgba(${color.r}, ${color.g}, ${color.b}, ${color.alpha})`;
}

const map = MudletMapReader.readBuffer(readFileSync("map.dat"));
const outdoorRooms = getRoomsByEnvironment(map, 1);
console.log(`Found ${outdoorRooms.length} outdoor rooms`);
```

---
_Source: https://npm.io/package/mudlet-map-binary-reader · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._