.arkmap Format Specification

1. Overview

The .arkmap format is a JSON-based file format for storing MUD map data. It is designed as the canonical format for ArkMap Studio, a web-based map viewer and editor for the Arkadia MUD game world.

Key design goals:

• Lossless round-trip with Mudlet's binary .dat format (version 20) — converting .dat → .arkmap → .dat produces a byte-identical result for files already in the canonical Qt layout (i.e. written by ArkMap Studio); files written by external tools are preserved semantically but normalized on import (see §19)
• Human-readable — JSON with deterministic key ordering and compact inline arrays
• Git-friendly — sorted keys and stable serialization produce clean, meaningful diffs
• Extensible — .arkmap-only fields (notes, tags) extend the Mudlet data model without breaking compatibility; unknown keys at any level are preserved verbatim across load/save round-trips (forward compatibility — see §17)
• Self-validating — hierarchical XXH3-64 checksums for corruption detection

2. Top-Level Structure

{
  "format":         "arkmap",      // REQUIRED — magic string, must be exactly "arkmap"
  "format_version": 2,              // REQUIRED — integer, format version (currently 2)
  "meta":          { ... },         // REQUIRED — metadata object (see §3)
  "colors":        { ... },         // REQUIRED — color palette object (see §4)
  "areas":         [ ... ],         // REQUIRED — array of Area objects (see §5)
  "checksums":     { ... },         // optional — XXH3-64 checksums, added by ArkMap Studio on save (see §15)
  "transports":    { ... }          // optional — transport lines, arkmap-transports v1 (see §21)
}

3. meta Object

{
  "map_name":                 "Arkadia",
  "symbol_font":              { /* Font object */ },
  "symbol_font_fudge_factor": 1.0,
  "use_only_map_font":        false,
  "user_data":                { /* optional string→string map (see §14) */ },
  "app_version":              "v1.51.0",  /* optional, informational — writer's version */
  "accepted_dir_issues":     [ /* optional, .arkmap-only — direction-validator acceptances */ ]
}

4. colors Object

{
  "env_colors":        { "258": 34, "272": 248 },
  "custom_env_colors": { "258": [0, 179, 0], "301": [255, 114, 14] }
}

Color resolution order

1. custom_env_colors[envId] — direct RGB, highest priority
2. env_colors[envId] → ANSI 256-color palette lookup (explicit override)
3. Hardcoded Arkadia environment table (ARKADIA_ENVS, 51 entries covering all known Arkadia envIds) — overrides implicit ANSI for Arkadia-specific envIds (200+). Applied only when the loaded map is detected as an Arkadia map (map-level user_data.map_sync_version present, "arkadia" in the map/file name, or ≥2 signature envIds >255 in use); maps from other MUDs skip this layer entirely and render from the ANSI palette plus their own env_colors / custom_env_colors — matching the official Mudlet renderer behavior.
4. Implicit ANSI mapping: envId 1–255 → ANSI palette (lowest priority). Mudlet offset applies: envId 8 → ANSI index 0, envId 16 → ANSI index 8, all others → ANSI index = envId.

If none of the four layers provides a color for a given envId, the room renders with the Mudlet default color (rgb(114,1,0)).

ANSI 256-color palette

The env_colors mapping and the implicit ANSI layer resolve indices to RGB using the standard xterm-256 palette:

• 0–15 — system colors (fixed, matching ANSI SGR 30–37 / 90–97)
• 16–231 — 6×6×6 color cube. For index i: n = i − 16, channel levels = [0, 95, 135, 175, 215, 255], RGB = [levels[⌊n/36⌋ mod 6], levels[⌊n/6⌋ mod 6], levels[n mod 6]]
• 232–255 — grayscale ramp: v = 8 + (i − 232) × 10, RGB = [v, v, v]

5. areas Array

An ordered array of Area objects. Must be sorted by id ascending for deterministic serialization.

{
  "id":             7,
  "name":           "Miasto",
  "rooms":          [ /* Room objects */ ],
  "labels":         [ /* Label objects — optional */ ],
  "grid_mode":      false,           // optional, default false
  "is_zone":        false,           // optional, default false
  "zone_area_ref":  0,               // optional, default 0
  "pos":            [0, 0, 0],       // optional, area position on overview
  "user_data":      { ... }           // optional
}

6. Room Object

{
  "id":                   12847,
  "x":                    15,
  "y":                    -3,
  "z":                    0,
  "env":                  272,
  "name":                 "Skrzyżowanie dróg",
  "weight":               1,
  "symbol":               "K",
  "locked":               false,
  "hash":                 "abc123def456",
  "exits":                { "n": 12840, "e": 12848 },
  "stubs":                ["sw"],
  "doors":                { "n": "closed" },
  "exit_weights":         { "e": 3 },
  "exit_locks":           ["n"],
  "special_exits":        { "wejdz do jaskini": 15001 },
  "special_exit_locks":   ["wejdz do jaskini"],
  "custom_lines":         { /* see §10 */ },
  "user_data":            { "zone": "handlowa" },
  "notes":                "Tu jest kowal",
  "tags":                 ["shop", "blacksmith"]
}

7. Exits & Directions

Valid direction strings

Exits use short direction strings as keys. The complete set of 12 valid directions:

exits object

Maps direction → target room ID. Keys are short direction strings; values are integers (room IDs). Only existing exits are listed.

{ "n": 12840, "e": 12848, "up": 12900 }

exit_weights object

Per-exit pathfinding cost overrides. Keys must be valid direction strings that exist in exits or special_exits. Values are integers ≥ 1. A weight of 1 is allowed and meaningful: in Mudlet's .dat an absent weight entry means weight 0, so explicit 1s are preserved across .dat round-trips (both from import and from the editor). In ArkMap Studio's own routing an absent weight falls back to the target room's weight.

{ "e": 3 }

stubs array

Directions where an exit is "hinted" but the target room is unknown. Sorted alphabetically. May coexist with entries in exits (Mudlet allows this).

["sw", "w"]

exit_locks array

Directions where the exit is programmatically locked (distinct from doors). Sorted alphabetically. Locked exits are ignored by the pathfinder.

8. Doors

Maps direction string → door type string.

{ "n": "closed", "e": "locked" }

9. Special Exits

Maps command string → target room ID. The command is a text string used in the MUD client (e.g. "wejdz do jaskini").

{
  "special_exits": { "wejdz do jaskini": 15001, "przejdz most": 15042 },
  "special_exit_locks": ["wejdz do jaskini"]
}

special_exit_locks is an array of command strings that are locked. Each value must exist as a key in special_exits.

10. Custom Lines

Custom lines are hand-drawn polylines on the map that replace the default straight-line exit connections. They are keyed by direction (for standard exits) or command string (for special exits).

"custom_lines": {
  "e": {
    "points": [[15.5, -3.0], [16.0, -2.5], [16.5, -3.0]],
    "color":  [255, 0, 0],
    "style":  "dash",
    "arrow":  true
  },
  "w": {
    "points": [],
    "color":  [255, 0, 0]
  }
}

Rendering

Custom lines are rendered as polylines starting from the room center (room.x, room.y), then through each waypoint in order. A custom line with 1 waypoint draws a single segment from room center to that point. The points array contains only waypoints — the room center is implicit and not stored in points.

Valid line styles

Empty Custom Lines

An empty custom line hides the default exit line that Mudlet would normally draw from this room in the given direction. It is needed when the opposite room has a custom line pointing here — without it, both lines would be drawn (a double line).

Example: Room A (id=100) has custom line e → Room B (id=101). Room B should have an empty custom line: "w": { "points": [], "color": [255,0,0] } to hide the default westward line.

Validation rule

Custom line keys must reference existing exits or special exits. The key must appear in either exits or special_exits of the same room.

Orphan style/arrow entries

Only custom line entries with a points array (including empty arrays, i.e. suppressors) are represented in .arkmap. Style/arrow/color entries for directions without a points entry — possible in .dat, where these are separate maps — are dropped on import (see §19).

11. Labels

Labels are text annotations or image overlays on the map, associated with an area.

{
  "id":          3,
  "x":           12.5,
  "y":           -4.2,
  "z":           0,
  "width":       8.0,
  "height":      1.5,
  "text":        "Wyspa Miłości",
  "fg_color":    [200, 200, 100],
  "bg_color":    [0, 0, 0, 50],
  "no_scaling":  false,
  "show_on_top": true,
  "pixmap":      null
}

12. Font Object

Represents a Qt QFont, serialized as JSON. Used for meta.symbol_font.

{
  "family":        "Bitstream Vera Sans Mono",
  "point_size":    -1,
  "pixel_size":    10,
  "style_hint":    7,
  "weight":        50,
  "style_setting": false,
  "underline":     false,
  "strike_out":    false,
  "fixed_pitch":   true
}

Optional font fields (omit when at defaults)

13. Color Type (RGB / RGBA)

Colors are represented as JSON arrays:

• RGB: [r, g, b] — 3 integers, each 0–255
• RGBA: [r, g, b, a] — 4 integers, each 0–255 (alpha: 0 = transparent, 255 = opaque)

Use RGB (3 elements) when alpha is 255 (fully opaque). Use RGBA (4 elements) only when alpha < 255. This keeps files compact.

[0, 128, 0]          // RGB green, alpha implied 255
[255, 0, 0, 128]     // RGBA semi-transparent red

14. user_data

A user_data field is a flat JSON object mapping string keys to string values. No nested objects, no arrays, no numeric values.

{ "version": "3.15.0", "revision": "abc123def456" }

Available at three levels: meta.user_data (map-level), area.user_data (area-level), and room.user_data (room-level).

14.1 Reserved keys

Although user_data is a generic string→string map, ArkMap Studio and the Arkadia toolchain assign meaning to a set of reserved keys. They remain ordinary string values — any conforming reader may ignore them — but editors that understand them should preserve their formats verbatim. Unless noted otherwise, these are room-level keys.

Arkadia game mechanics (room)

Edited through the Skrypty tab of the room panel. All survive .dat round-trips (stored as Mudlet user_data).

ArkMap Studio rendering (room)

Set through the room panel's Podstawowe tab. Stored as user_data, so they round-trip through .dat as opaque strings that Mudlet itself ignores.

Mudlet system (room)

Source pass-through (room)

These keys are injected by the source map (Arkadia mapping scripts / Mudlet) and are not written or interpreted by ArkMap Studio. They are preserved verbatim across both .arkmap and .dat round-trips.

Map-level keys (meta.user_data)

These keys commonly appear in meta.user_data and are written/read by ArkMap Studio:

15. Checksums (XXH3-64)

ArkMap Studio computes hierarchical XXH3-64 checksums on save and stores them in the top-level checksums object (moved out of meta in format version 2 — see §2). Every hashed value is first serialized with the canonical binary encoding — a deterministic, JSON-independent byte format whose normative reference is tests/checksums/CANONICAL_V4.md in the project repository. Checksums are optional — a file without checksums is valid.

"checksums": {
  "alg":   "v4",
  "file":  "a1b2c3d4e5f60718",
  "meta":  "f0e1d2c3b4a59687",
  "areas": { "7": "e5f6a7b8c9d0e1f2", "12": "c9d0e1f2a3b4c5d6" },
  "rooms": { "12847": "1a2b3c4d5e6f7a8b", "12848": "5e6f7a8b9c0d1e2f" },
  "transports": { "hash": "…", "lines": { "Wyzima - Novigrad": "…" } },  /* optional — transport line sums (see §21) */
  "sig":   "3f4a…"  /* optional — author signature, 128 lowercase hex (see §23) */
}

Computation algorithm (v4)

1. Room hash = XXH3-64 (seed 0) of the canonical binary encoding of the room, domain prefix "r4". Default values are omitted from the encoding (weight: 1, locked: false, hidden: false, empty strings and empty containers), internal fields (area) are excluded, and custom line defaults are normalized (style: "solid" → omit, arrow: false → omit). The upstream hash field (e.g. "45:28:0:Wyzima") is covered when present. This ensures hash stability regardless of in-memory representation.
2. Area hash = XXH3-64 of "a4" + the canonical encoding of the area attributes (id, name, the optional grid_mode/is_zone/zone_area_ref/pos fields when present, labels sorted by id — with full label color channels including alpha, count-prefixed —, user_data with keys in UTF-8 byte order) + the rollup of raw 8-byte little-endian room hashes sorted by room ID. Because the area's own fields and its id are part of the input, two empty areas are distinguishable.
3. File hash = XXH3-64 of "f4" + the canonical encoding of the map-level colors tables (env_colors, custom_env_colors; numeric keys in ascending numeric order) + the rollup of raw 8-byte little-endian area hashes sorted by area ID.
4. Meta hash (checksums.meta, added in format version 2) = XXH3-64 (seed 0) of the canonical binary encoding of the entire meta object, domain prefix "m4" (see the Meta object encoding section of CANONICAL_V4.md — keys in UTF-8 byte order, recursive). The two roles are deliberately separate: checksums.file is the map's identity — it excludes meta by design, so metadata edits (notes, acceptances, book-keeping) never change it; checksums.meta is the metadata's integrity — it detects external edits to meta without disturbing the identity hash. Keeping meta integrity separate is also what allows .arkdelta base matching (§4 of the .arkdelta spec) to rely on checksums.file alone.

All hash values are stored as 16-character lowercase hexadecimal strings. The canonical encoding fixes every cross-platform ambiguity: integers are little-endian i32, floats are little-endian f64 with -0 normalized to +0 and every NaN (or non-number) normalized to the canonical quiet-NaN 7ff8000000000000, strings are length-prefixed UTF-8, and map keys follow a fixed domain order (direction keys in n,ne,e,se,s,sw,w,nw,up,down,in,out order; other keys in UTF-8 byte order; numeric keys in ascending numeric order).

Unicode normalization: strings are hashed as their raw UTF-8 bytes exactly as they appear in the file — verifiers MUST NOT normalize before hashing. Producers SHOULD emit strings in Unicode Normalization Form C (NFC) so that semantically identical text hashes identically across tools.

Algorithm versioning (alg)

"v4" is the only algorithm ArkMap Studio writes (since v1.45.0) and the only one it verifies. The retired generations — legacy v1 (no alg field), "v2" ("a2:"/"f2:" prefixed rollups) and "v3" (canonical binary, v1.44.x) — are no longer produced or verified; the formulas are frozen history.

Verifiers MUST dispatch on alg: "v4" → v4 formulas; any other value (including absent) → report an algorithm mismatch (loud, never a silent skip — a silently skipped stale file would be indistinguishable from a file without checksums). Re-saving the file upgrades its checksums to v4.

Transport checksums (checksums.transports)

When the map embeds a transport document (map.transports), saving additionally signs it into checksums.transports = { hash, lines }: hash covers the whole document, lines holds one sum per line keyed by line name — so verification pinpoints exactly which line was modified (badLines), added unsigned (missingLines) or removed leaving an orphaned sum (extraLines). Unlike room/area/meta sums, transport sums use the canonical JSON encoding (deterministic stableStringify — keys sorted at every level, absent keys omitted), hashed as XXH3-64 of its UTF-8 bytes; the canonical document sorts lines by name (array order is not semantic) while preserving leg order (leg order is semantic). Transport integrity is an auxiliary, informational signal (same class as metaOk): it never affects file identity and is reported separately from map-data sums. Re-saving after removing transports clears the orphaned sums.

Verification

On load, recompute from bottom up — using the algorithm recorded in alg (see Algorithm versioning above) — and compare. Mismatches indicate the file was modified externally (hand-edited JSON, merge conflict resolution, etc.). Mismatches are warnings, not fatal errors. Verification never throws on malformed data (it reports a verification error and defers to structural validation), and it also reports dictionary inconsistencies: rooms or areas missing their checksum entry, and orphaned checksum entries without a matching object. Dictionary-inconsistency reporting applies to the areas and rooms dictionaries only; unrecognized top-level keys inside the checksums object itself (e.g. keys introduced by a newer spec) are ignored, not reported — verifiers must remain forward-compatible with the envelope.

16. Deterministic Serialization

For git-friendly output, .arkmap files use stable JSON serialization:

• Object keys are sorted alphabetically at every nesting level
• Indentation: 2 spaces per level
• Inline arrays of primitives (≤ 8 elements): written on a single line with , separator — e.g. [255, 0, 0], [32.7281, -7.9983]
• Arrays of objects: each element on its own line, standard JSON indentation
• undefined values are omitted (keys not present)
• Array sorting:
  • areas sorted by id ascending
  • rooms within each area sorted by id ascending
  • labels within each area sorted by id ascending
  • stubs, exit_locks, special_exit_locks sorted alphabetically
  • meta.accepted_dir_issues sorted lexicographically (UTF-8 byte order of the key strings)

17. Validation Rules

A conforming implementation should validate the following rules:

1. format must be "arkmap"
2. format_version must be 2
3. meta, colors, areas must be present
4. checksums, if present, must be an object; meta.checksums is not a recognized location (format version 1 layout — rejected by rule 2)
5. Unknown keys anywhere in the document (top level, meta, areas, rooms, labels, colors) must not cause rejection — readers preserve them verbatim and writers re-emit them (see §1); only the rules in this list may reject or warn. Unknown top-level keys are additionally reported at load (an informational note listing them) and are covered by the optional signature (§23)
6. meta.room_id_hash, if present, must be an object mapping contributor names (strings) to starting room IDs (integers)
7. All area IDs must be unique
8. All room IDs must be globally unique (across all areas)
9. Exit target room IDs must reference existing rooms
10. Special exit target room IDs must reference existing rooms and be integers
11. Special exit command keys must be non-empty strings
12. Special exit commands should not collide with standard direction names when a normal exit exists in the same direction (shared namespace for doors, exit_weights, custom_lines)
13. Exit weight keys must reference existing exits or special exits
14. Special exit lock commands must reference existing special exits
15. Door values must be one of: "open", "closed", "locked"
16. Custom line keys must reference existing exits or special exits
17. Custom line style must be one of: "solid", "dash", "dot", "dash_dot", "dash_dot_dot"
18. Custom line points must be arrays of [number, number] pairs (empty array = empty custom line)
19. Color arrays must have 3 or 4 integer elements, each 0–255
20. Room weight must be integer ≥ 1
21. Room coordinates (x, y, z) must be integers
22. Room name and symbol must be strings (if present)
23. Room locked must be boolean (if present)
24. user_data keys and values must be strings
25. Label IDs must be unique within their area
26. doors, exit_weights, custom_lines must be objects (not arrays) if present
27. special_exit_locks must be an array if present

18. Rendering Behavior

This section documents rendering conventions that implementations should follow for visual compatibility with Mudlet and Delwing.

Exit rendering

• Standard exits (n, ne, e, se, s, sw, w, nw): Rendered as lines between room edges. Both rooms must be on the same area and same Z level.
• One-way exits: When room A has an exit to room B, but B does not have the reciprocal exit back to A, the line is drawn with an arrowhead at the target end.
• Up/down/in/out: Never rendered as connecting lines. Instead, rendered as triangles inside the room: ▽ for down, △ for up. Triangle color is contrast-dependent on the room's background. For cross-Z targets, a ↑/↓ text symbol is also drawn.
• Cross-area exits: Rendered as directional arrows at the room edge with area name labels, regardless of whether source and target Z levels differ.

Custom line rendering

Custom lines are drawn as polylines starting from the room center, then through each waypoint in order. Arrowheads (when arrow: true) are rendered in both view and edit modes. Custom lines with an empty points array (empty custom lines) are not drawn but may be indicated with a ⊘ symbol at the room edge.

Color fallback

Rooms with envIds not resolved by any color layer render with the Mudlet default color rgb(114, 1, 0) (dark brownish-red). This applies to all visual contexts: canvas, minimap, room panel swatch, env color dialog, and palette chips. The legend and palette chips refresh dynamically after map load to reflect any custom_env_colors overrides.

19. Mudlet .dat Round-Trip

The .arkmap format is designed for lossless conversion to/from Mudlet's binary map.dat format. ArkMap Studio reads versions 17–22 and always writes version 20 (the Arkadia MUD standard). Round-trip conversion .dat → .arkmap → .dat produces byte-identical output for version 20 input files that are already in the canonical Qt layout — in practice, files previously written by ArkMap Studio (verified with SHA-256). Files written by external tools (e.g. Mudlet itself or Arkadia mapping scripts) are preserved semantically but not byte-identically: their content is normalized on import as listed below. Files in other versions (17–19, 21–22) are read correctly but re-written as version 20, so the output will differ structurally.

Normalizations on .dat import

ArkMap Studio always writes .dat files in the canonical layout (see §16). When importing a .dat file produced by external tools, the following normalizations are applied. They do not change the meaning of the map:

• Key ordering — QMap instances are re-serialized in canonical (sorted-key) Qt order, regardless of the source file's key order.
• Area bounds — per-area position/span values are recomputed from the area's rooms, even if the source file stores zeros (e.g. span = [0,0,0]).
• Custom line coordinates — rounded to 4 decimal places on import (sub-pixel difference; Mudlet rounds coordinates to whole pixels when rendering).
• Label colors — a label with an undefined QColor (spec=0, i.e. "default color") is normalized to black RGB. In Mudlet such a label renders in the default color; after a round-trip it may render black instead.
• Null vs empty strings — Qt distinguishes a null QString (0xFFFFFFFF length) from an empty QString (length 0); both are read as an empty string and written back as empty.
• Orphan custom line style/arrow/color entries — .dat stores custom line style, arrow and color in separate maps keyed by direction, so a file may contain such entries for directions that have no custom line points entry. They have no rendering effect and are dropped on import — matching Mudlet's own load-time audit (TRoom::audit), which removes them as well.

Known limitations

None currently known — as of spec v1.1, all previously identified data-loss cases (mRoomIdHash, exit weights equal to 1, orphan custom line attributes) have been addressed; the normalizations listed above are the only intentional differences from the source file.

Direction mapping (.arkmap → .dat)

.arkmap uses short strings; .dat uses 1-based indices (see §7 table). Convert using the direction table.

Door mapping

.arkmap uses strings; .dat uses integers: open=1, closed=2, locked=3.

Custom line style mapping

.arkmap uses strings; .dat uses integers: solid=1, dash=2, dot=3, dash_dot=4, dash_dot_dot=5.

Special exits encoding

.dat stores special exits as QMap<int targetRoomId, QList<QString>> where each string is prefixed with "0" (unlocked) or "1" (locked). .arkmap decomposes this into special_exits + special_exit_locks.

Y-axis convention

Important: Mudlet negates Y for per-area bounds: min_y = -max(room.y), max_y = -min(room.y). The .arkmap format stores Y as-is (positive = north). Implementations must negate Y when computing area bounds for .dat export.

Color conversion

Mudlet uses QColor (spec, r, g, b, alpha, pad). .arkmap uses [r, g, b] or [r, g, b, a]. When alpha is 255, omit it. When converting to QColor, set spec=1 (RGB), pad=0.

Font conversion

QFont bit flags are decomposed into boolean fields in .arkmap. See §12 for the mapping.

20. Extensions (.arkmap-only fields)

These fields are exclusive to the .arkmap format and are not preserved when exporting to Mudlet .dat:

Implementations that only handle .dat conversion can safely ignore these fields. When reading a .arkmap file for .dat export, these fields should be silently dropped.

21. Transport Lines (transports)

A map may embed a transport document describing named transport lines — ships, coaches, portals, anything that moves the player between non-adjacent rooms. The format is universal: it describes routing data for any map of any MUD; game-specific content is just data on top of the same schema. The document may also live as a standalone sidecar JSON (same schema) for tools that keep routing data out of the map file.

{
  "format":  "arkmap-transports",   // REQUIRED — magic string
  "version": 1,                    // REQUIRED — schema version
  "lines": [
    {
      "name":  "Wyzima - Novigrad ferry",  // REQUIRED, unique — lines are keyed by name
      "board": ["wsiadz na statek", "wejdz na statek"],  // REQUIRED — boarding commands (aliases)
      "exit":  "zejdz ze statku",          // REQUIRED — disembark command
      "legs": [                                // REQUIRED, ordered — the ride sequence
        { "from": 729, "to": 3760, "time": 23, "label": "Bialy Most" },
        { "from": 3760, "to": 729, "time": 18, "label": "Wyzima" }
      ]
    }
  ]
}

Semantics

• Leg order is semantic — it defines the ride (a line may chain stops A→B→C). Line order in the array is not semantic — canonical form sorts lines by name.
• Routing cost of a hop: Σ leg times · ratio + boarding penalty, one penalty per ride, so a direct crossing beats transfers. Reference cost model: normal ratio 0.5 / penalty 30, aggressive ratio 0.1 / penalty 10.
• Foreign maps: legs referencing rooms absent from the loaded map terminate the chain — a line segment is usable only where the map actually covers it.
• Validation: the core .arkmap validation (§17) does not inspect transports (unknown top-level keys are preserved untouched); the document is validated separately against the arkmap-transports v1 schema (validateTransports in the arkmap npm package).
• Integrity: per-line checksums in checksums.transports — see §15.
• Round-trip: transports has no .dat counterpart and is dropped on .dat export (see §20).

22. Complete Example

A minimal but valid .arkmap file with one area containing two rooms:

{
  "areas": [
    {
      "id": 1,
      "name": "Test Area",
      "rooms": [
        {
          "env": 272,
          "exits": {
            "e": 2
          },
          "id": 1,
          "name": "Start Room",
          "x": 0,
          "y": 0,
          "z": 0
        },
        {
          "env": 258,
          "exits": {
            "w": 1
          },
          "id": 2,
          "name": "Forest",
          "symbol": "T",
          "x": 1,
          "y": 0,
          "z": 0
        }
      ]
    }
  ],
  "checksums": {
    "alg": "v4",
    "areas": { "1": "202da9297d3fa8c6" },
    "file": "5d03008d88f80d3c",
    "meta": "81b665ced34bce7a",
    "rooms": { "1": "8e006383da3c0aa8", "2": "fa11ba21960714e5" }
  },
  "colors": {
    "custom_env_colors": {
      "258": [0, 179, 0],
      "272": [128, 128, 128]
    }
  },
  "format": "arkmap",
  "format_version": 2,
  "meta": {
    "map_name": "Test Map",
    "symbol_font": {
      "family": "Bitstream Vera Sans Mono",
      "fixed_pitch": true,
      "pixel_size": 10,
      "point_size": -1,
      "strike_out": false,
      "style_hint": 7,
      "style_setting": false,
      "underline": false,
      "weight": 50
    },
    "symbol_font_fudge_factor": 1.0,
    "use_only_map_font": false
  }
}

23. Optional Signatures

A map file exists in exactly one of two states: anonymous (no author fields, no signature) or signed (author fields plus a valid signature). There is no third state — see the anomaly rule below. The scheme mirrors the .arkdelta signature (§9 of the .arkdelta spec): the same field names, the same key type, the same payload construction — only the domain prefix differs (arkmap-v2: versus arkdelta-v3:).

What is signed

The signature is an Ed25519 signature over the UTF-8 byte string "arkmap-v2:" + canonicalSerialization(whole object minus checksums.sig) — the domain prefix followed by the deterministic serialization (§16) of the entire envelope, with only the sig key excluded from checksums. The payload therefore binds the content (areas/rooms), the colors tables, the metadata (including the author fields), every checksum entry, and any unknown top-level keys preserved under the forward-compatibility rule (§17). It is stored as checksums.sig — 128 lowercase hex characters (64 bytes). Storing the signature inside checksums keeps it outside every checksum input by construction — no circularity, and unsigned files are completely unaffected.

Producer rule

A producer that writes any author field (author, author_id, author_pubkey, created) MUST sign the file (write checksums.sig) and MUST recompute checksums.meta after writing the author fields, so the meta hash covers them. Author fields without a signature are an anomaly: readers report them as a declaration without proof and treat the authorship as unverified.

Reader policy

• The integrity signal remains the checksum hierarchy (§15) — unchanged, with or without a signature. A bad signature never substitutes for a checksum mismatch and never rescues one.
• If checksums.sig is present, readers that support signatures SHOULD verify it against meta.author_pubkey. An invalid signature over an intact checksum hierarchy is a loud warning, not a refusal: the file loads, authorship is treated as unverified.
• Signature states: unsigned (no author fields, no sig), claimed (author fields without sig — declaration without proof), valid (sig verifies; the reader additionally compares author_id against the fingerprint of author_pubkey and reports a mismatch), invalid (sig does not verify — loud warning).
• Readers unaware of signatures load signed files normally — unknown keys in checksums and meta are ignored (§17).
• Signatures are additive: they do not bump format_version.

Public registry

Signers MAY register their nick in the public ArkMap identity registry — one nick bound to exactly one key, with owner-initiated permanent revocation (tombstone). The registry, its gateway, and the registry-aware reader policy (match / missing / mismatch / revoked / offline) are specified once in §9 of the .arkdelta spec ("Public registry") and apply unchanged to map signatures — the registry binds identities, not file formats. Registry checks are never a load gate; an unreachable registry only marks the registry dimension unavailable.

24. Format Changelog

.arkmap Format Specification v2 · ArkMap Studio · Isithunzi · AGPL-3.0 License · 2026