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 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.

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

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.constmap=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

constmap=MudletMapReader.readBuffer(readFileSync("map.dat"));for(const[id,room]ofObject.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]ofObject.entries(room.mSpecialExits)){constlocked=room.mSpecialExitLocks.includes(destId) ? " [locked]" : "";console.log(` special: ${exitName} -> ${destId}${locked}`);}}

Modifying and saving

import{readFileSync,writeFileSync}from"node:fs";constmap=MudletMapReader.readBuffer(readFileSync("map.dat"));// Rename a roommap.rooms[1].name="Grand Hall";// Add user data to a roommap.rooms[1].userData["notes"]="quest start";// Move a roommap.rooms[1].x=10;map.rooms[1].y=-5;// Serialize back to bytes, then persist them however you likeconstbytes=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. It returns the data — persisting it is up to you.

import{writeFileSync}from"node:fs";constmap=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.

import{writeFileSync}from"node:fs";constmap=MudletMapReader.readBuffer(readFileSync("map.dat"));// Pretty-printedwriteFileSync("map.json",MudletMapReader.exportJson(map));// MinifiedwriteFileSync("map.min.json",MudletMapReader.exportJson(map,true));

Working with areas and labels

constmap=MudletMapReader.readBuffer(readFileSync("map.dat"));for(const[id,name]ofObject.entries(map.areaNames)){constarea=map.areas[idasunknownasnumber];console.log(`Area ${id}: ${name} (${area.rooms.length} rooms)`);constlabels=map.labels[idasunknownasnumber]??[];for(constlabeloflabels){console.log(` Label: "${label.text}" at (${label.pos.join(", ")})`);}}

Using with TypeScript types

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

import{MudletMapReader}from"mudlet-map-binary-reader";importtype{MudletMap,MudletRoom,MudletColor}from"mudlet-map-binary-reader";functiongetRoomsByEnvironment(map: MudletMap,envId: number): MudletRoom[]{returnObject.values(map.rooms).filter((room)=>room.environment===envId);}functionformatColor(color: MudletColor): string{return`rgba(${color.r}, ${color.g}, ${color.b}, ${color.alpha})`;}constmap=MudletMapReader.readBuffer(readFileSync("map.dat"));constoutdoorRooms=getRoomsByEnvironment(map,1);console.log(`Found ${outdoorRooms.length} outdoor rooms`);