Mudlet Map Browser Script

A browser front-end for exploring Mudlet maps. It wraps mudlet-map-renderer and wires it up to a full interactive UI — area navigation, room search, path finding, image export, multiple visual styles, and more — so a Mudlet map export can be browsed from any web page.

A working deployment is available at https://delwing.github.io/arkadia-mapa/.

Capabilities

• Area & level navigation — area dropdown (sorted by name), per-level (z-index) buttons, with a dropdown fallback for areas with more than 10 levels.
• Room inspection — click any room to see its id, name, environment, coordinates, hash, normal and special exits (with cross-area links), custom Mudlet user data, and NPCs present in the room.
• Search — find rooms by id (single or comma-separated list) or by NPC name with autocomplete; matching rooms are centered and highlighted.
• Path finding — Dijkstra shortest path between two rooms; multiple paths can be drawn at once, each with its own editable color, and removed individually.
• Image export — download the current area as PNG or SVG, or copy a PNG straight to the clipboard.
• Render modes — switch the visual style of the map: normal, pencil (sketchy), parchment, parchment-pencil, isometric (with adjustable rotation), isometric-parchment, blueprint, neon, and gradient.
• Customizable settings — background/line colors, room size and shape, line width, label rendering, area names, area-exit labels, and more. Settings persist in localStorage and are migrated forward across versions.
• Minimap preview — a low-res overlay of the current area with a live viewport indicator that tracks zoom and pan.
• Keyboard shortcuts — F1 help, Ctrl+F search, Ctrl+S save image, +/- zoom, and numpad keys (1–9, *, /) to step through exits from the selected room.
• Internationalization — built-in Polish/English translation, switchable from the UI and persisted between visits.
• Theme selector — pick any Bootswatch theme plus a dark-mode toggle, persisted in localStorage.
• Version switcher — load older map versions from GitHub release tags and view their release notes without leaving the page.
• Deep links — open the page on a specific room (?loc=), area (?area=), or map version (?version=).

Usage

The script is published to npm and is consumed in the browser as a bundled IIFE (dist/index.min.js) plus a companion stylesheet (dist/index.min.css). The easiest way to include them is via a CDN such as jsDelivr:

<!-- Latest version -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/mudlet-map-browser-script/dist/index.min.css" />
<script src="https://cdn.jsdelivr.net/npm/mudlet-map-browser-script/dist/index.min.js"></script>

<!-- Pinned version -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.min.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.min.js"></script>

Or install it from npm to bundle yourself:

npm install mudlet-map-browser-script
# or
yarn add mudlet-map-browser-script

Map data source

Point the script at a map via window.MAP_CONFIG. There are three ways to supply it, checked in this order:

| Config | Source | | --------------------------- | ------------------------------------------------------------------------------------------------------- | | mapUrl | A Mudlet binary map (.dat) — decoded in-browser via mudlet-map-binary-reader — or a combined { mapData, colors } JSON file (extension decides). | | mapDataUrl + colorsUrl | The renderer export served as two JSON arrays (the .json equivalent of the old mapExport.js / colors.js). | | legacy globals | mapData / colors defined on window before the script runs. Deprecated — kept for back-compat; prefer mapUrl. |

Loading a .dat directly is the simplest setup — no export step, and the binary is smaller than the generated JS. Requires mudlet-map-binary-reader ≥ 1.0.1 (bundled into dist/index.min.js).

Required page structure

The script is a self-contained React application that renders the entire UI itself. The host page only needs a mount point (a #root element is used if present, otherwise one is created and appended to <body>) and a configured map source:

<link rel="stylesheet" href="index.min.css" />
<div id="root"></div>
<script>
  window.MAP_CONFIG = { mapUrl: "data/map.dat" }; // a .dat (decoded in-browser) or a .json export
</script>
<script src="index.min.js"></script>

All styling (Bootstrap, the app's own CSS, and the flag sprite) ships in dist/index.min.css — the host needs no other stylesheet. The Polish and English UI translations are bundled too, so no i18n files are required; you can override strings or add languages via MAP_CONFIG (below). The only host-provided asset is the favicon.

Host configuration

The page is configured through a window.MAP_CONFIG global, set before the script runs:

<script>
  window.MAP_CONFIG = {
    // Map data — a .dat (decoded in-browser) or a .json export. See "Map data source" above.
    mapUrl: "data/map.dat",
    // ...or two JSON arrays instead: mapDataUrl: "data/mapExport.json", colorsUrl: "data/colors.json",

    // Optional endpoints — no defaults; omit one and its feature turns off:
    npcUrl: "...",          // makes NPCs searchable; unset → only room-id search
    versionsTagsUrl: "...", // version selector in the Help modal; unset → hidden
    versionsFilesUrl: "...",// fetches a selected version's map (%tag% substituted)

    // Branding — no defaults are baked into the bundle:
    title: { pl: "Mapa Arkadii", en: "Arkadia Map" }, // string, or per-language map
    logo: "images/logo.png",                           // URL/path to a logo image; omit for no logo
    credits: {                                          // Help-modal footer; omit to hide entirely
      author: "Dargoth",
      githubUrl: "https://github.com/Delwing/mudlet-map-reader",
      remark: { pl: "...", en: "..." },                 // string or per-language map; may contain inline HTML
    },

    // Translations — Polish + English are bundled; override or extend here:
    translations: { en: { search: "Find" }, de: { search: "Suchen", settings: "Einstellungen" } },
    languages: [{ code: "pl" }, { code: "en", flag: "gb" }, { code: "de" }], // picker entries + flag sprite
  };
</script>
<script src="index.min.js"></script>

title, logo, and credits carry no defaults — the bundle is brand-neutral, and any of them that you omit simply isn't shown (the header title falls back to the bundled title string). The bundled Polish/English strings work out of the box; translations merges on top of them (tweak a string or add a whole language) and languages controls the picker. See demo/index.html for a complete example.

URL parameters

| Parameter | Effect | | ---------- | --------------------------------------------------- | | ?loc=ID | Open centered on room ID and select it. | | ?area=ID | Open on area ID. | | ?version=TAG | Load the map version published under release TAG. |

Development

yarn install     # install dependencies
yarn dev         # run the demo (Vite dev server) — see below
yarn build       # produce dist/index.min.js (+ source map)
yarn typecheck   # run the TypeScript compiler with --noEmit

yarn dev serves the demo from the demo/ directory (Vite's dev root) — demo/index.html is the minimal host shell (a #root mount point, MAP_CONFIG.mapUrl pointing at a Mudlet .dat, and the app). It decodes the real Arkadia .dat in-browser and loads the favicon from the live deployment, so you can develop against production-like data with no extra setup. It doubles as the reference for how a host page wires the bundle in (the only difference in production is a <script src="index.min.js"> tag instead of the dev module).

The project is written in TypeScript + React and bundled with Vite into a single minified IIFE (see vite.config.ts); React is bundled in, so the host page needs no CDN script. Source modules of note:

• src/main.tsx — the bundle entry point; mounts the React app into #root.
• src/MapApp.tsx — top-level component; instantiates the controller and lays out the UI.
• src/map/MapController.ts — framework-agnostic controller wrapping mudlet-map-renderer (areas, rooms, paths, settings, render modes, image export) and emitting state to React.
• src/components/ — the UI (header, toolbar, modals, info box, minimap, paths, zoom, toasts).
• src/i18n/ — translation provider; bundled Polish + English dictionaries, overridable via config.
• src/preview.ts — the minimap preview overlay (driven imperatively by the controller).
• src/data/npc.ts — NPC data loading; src/versions.ts — GitHub release tags / map versions.

Bootstrap's modals, dropdowns, and toasts are driven through its data-bs-* data API (Bootstrap's JS is imported for its side effects in src/main.tsx).

Publishing

Pushing a *.*.* tag triggers the Publish to npm GitHub Action, which builds the bundle and runs npm publish --provenance --access public. The published package only ships the dist/ folder.

License

MIT