A dependency-free toolkit for trustworthy BYOND map work, shared by people and agents: inspection, a native type tree, static and in-game rendering, safe copy-on-write edits, diffs, prefabs, generator-aware inspection, spatial contracts, an agent API/MCP server and native compile/playtest capture, plus a VS Code map editor. Every layer says what it was checked against (see verification).
- VS Code: install BYOND Map Editor
from the Marketplace (search "BYOND Map Editor", formerly "BYOND Map Preview", in the Extensions panel), then set
byondDevtools.byondBinto your BYONDbinfolder. The.vsixis also attached to each GitHub release. - CLI: clone this repository and run
node src/cli.jswith Node.js 22+. There is nothing to install.
Current release: v0.4.0: the VS Code editor compares a map
with a git revision (changed tiles outlined, Next change) and opens a tile's definition in the text;
the MCP server gains dump_render (live views such as Civ13's character_view, with screen
objects, snapshots over time and a list of clickable atoms that draw nothing), icon_diff,
resources and prompts, and the CLI gains icon-diff for sprite review. v0.3.0 added kind toggles, type
highlighting, animated states, icon renders, animated PNGs, image comparison and in-game renders
(see Agent API (MCP)).
v0.5.0 added map resize in the CLI (resize), MCP (map_resize) and VS Code
(BYOND: Resize map). v0.5.1 widens the dictionary keys when resize needs a key on a full map,
and is published to Open VSX too. Next, v0.5.2 (on main, not yet tagged): edits (CLI, MCP and
the map editor) widen the keys on a full map as well.
- Dependency-free ECMAScript modules on Node.js 22+.
- Bounded DMM/TGM syntax parsing: dictionary, ordered atom stacks, opaque variable override text, one-based coordinates, multiple/offset blocks, multiple z levels.
- Source-preserving inspection: original input text is retained; no serialization, normalization, evaluation, mutation, network access or game process control.
- JSON summaries, exact-cell inspection and paginated type/subtype search.
- Snapshot objects/arrays are frozen, and internal lookup maps are private.
- Project-relative, realpath-contained UTF-8 file reads, SHA-256 provenance, and a deliberately lexical DME include inventory.
- Synthetic tests, a TGM fixture, and a CI corpus job over every Civ13 map. No game assets are vendored.
No npm install is necessary. Run:
npm test
npm run check
node src/cli.js summary --root . --map fixtures/tiny.dmm
node src/cli.js cell --root . --map fixtures/tiny.dmm --x 1 --y 2 --z 1
node src/cli.js find --root . --map fixtures/tiny.dmm --type /obj --subtypes --limit 10For an existing Civ13 checkout (paths with spaces must be quoted):
node src/cli.js summary --root /path/to/Civ13 --map maps/nomads/nomads_gaia.dmm --dme civ13.dme
node src/cli.js project --root /path/to/Civ13 --dme civ13.dmeThe same commands work on Windows with the checkout's Windows path. CI runs the
tests on Ubuntu and Windows with Node 22 and 24, and parses every map in a
shallow Civ13 checkout on both (npm run corpus -- --root PATH). Output is JSON; errors use stderr and
exit status 1. Only edit --apply writes a map (see below).
Passing the parser is not full-game compilation or playability validation. Overrides
remain raw DM expressions, never evaluated. No inheritance, active conditional
includes, lighting, smoothing, runtime overlays, pathfinding, runtime state or
persistent saves are resolved by the parser; the static preview shows authored source plus type defaults, and the ingame render (below) is the view after runtime changes and lighting. The --dme option binds the file hash but does not
resolve its type environment. Unknown paths are retained, not silently removed.
Sparse/offset blocks are placed the way BYOND 516 places them (header y counts down
from the map top, see architecture); missing cells are holes
that BYOND fills with /turf in /area. Source spans use JavaScript UTF-16 code-unit offsets, not byte offsets.
Files must be valid UTF-8. CLI hashes describe exact disk bytes; parser source
is decoded text. Neither is a native binary .sav representation.
The conservative syntax profile accepts ASCII identifier paths and alphabetic keys of uniform width (1–8 characters). The default 65,534-definition cap is a protective implementation limit, not a promise of native compatibility. It rejects unsupported constructs instead of repairing them. Comments inside opaque override expressions are balanced but not interpreted; comments between an atom's prefix and type path are currently rejected. See architecture.
All phases are merged; v0.1.0 released them, v0.2.0 added map editing, v0.3.0 render options and v0.4.0 map compare, live views and sprite review:
- Strict read-only inspection, provenance and source-preserving observation fixtures (done).
- Native type tree, DMI decoding and coordinate-linked static rendering (done).
- VS Code custom editor, tested in Stable and Insiders on Linux and Windows (done,
vscode/; editing since v0.2.0). - One copy-on-write edit transaction with old-value preconditions, bounded edits, inverse patch and verified unchanged regions, plus a semantic and visual diff (done).
- Prefabs, generator-aware tools, spatial contracts and a local agent API/MCP server (done; icon, animated, comparison and in-game render tools in v0.3.0).
- Authorized native compiler, runtime-error and profiler capture, and local playtests, distinct from static validation; no live-server or persistence actions (done).
types and lint read the project's real compiled type tree from your own installed
DreamMaker (-o). The compiler runs on a one-line probe .dme in a temporary directory
that includes the project's .dme, so its .rsc lands there, not in your checkout.
A saved tree (DreamMaker -o civ13.dme > tree.xml) can be passed with --tree.
node src/cli.js types --root /path/to/Civ13 --dme civ13.dme --byond /path/to/byond/bin
node src/cli.js types --root /path/to/Civ13 --dme civ13.dme --byond BIN --type /obj/structure/closet
node src/cli.js lint --root /path/to/Civ13 --dme civ13.dme --byond BIN --map maps/1943/berlin.dmmDreamMaker's printed values are not evaluated (operators are dropped: 2 + 0.1 prints
20.1, 4|1 prints 41). Each value is therefore resolved from its declaring source
line: a plain literal, a #define for one, or + - * / arithmetic over those in 32-bit
floats. Anything else (NORTH|EAST, \improper text, proc calls) is reported as
unresolved with its source text. Fixture values are checked against instances created
in DreamDaemon. On Civ13 every icon, icon_state, layer and plane of all 11,289
atom types resolves. lint exits 3 when it finds unknown types or overrides of undeclared
vars. It complements Civ13's scripts/maplint.py, which checks tile structure.
src/png.js and src/dmi.js are an original, dependency-free PNG and DMI decoder: all
non-interlaced colour types and bit depths, tRNS transparency, every row filter, and
the Description metadata (states, dirs, frames, delays, movement states). Interlaced
PNGs and malformed metadata are rejected with an error.
node src/cli.js icon --root /path/to/Civ13 --dmi icons/obj/closet.dmiPixels are checked against DreamDaemon's icon.GetPixel: every pixel of 15 fixtures
(one per colour type and depth), and a 24,660-pixel sample over all 384 Civ13 icons, with
zero differences. Recorded lookup rules: a duplicated state name uses the first state; a
movement lookup with no movement state, a direction the state lacks, or a frame past
its count returns nothing. The renderer's display fallback ({display: true}) is not yet
checked natively.
render draws a bounded region of a map as a PNG from the authored map and the native
type tree, with icons decoded from the checkout. It is a preview of authored source plus
compiled type defaults, not a client screenshot.
node src/cli.js render --root /path/to/Civ13 --dme civ13.dme --byond BIN \
--map maps/nomads/nomads_gaia.dmm --z 2 --x1 400 --y1 160 --x2 463 --y2 223 --grid 16 --out gaia.png- Writes only the
--outPNG, refuses to overwrite it without--force, and renders at most 128x128 tiles and 16 Mpx. Icon files are read inside--rootonly. - Draw order: plane, layer, then south rows over north rows, then the tile's native
contents order (turfs, objs, mobs). Icons anchor at the tile's bottom-left and use
icon_state,dir,pixel_x/y/w/z, hexcolorandalpha(frame 1). - Map overrides apply when they are plain values; type defaults use the same resolver as
types. Fixture defaults are checked against DreamDaemon instance values. - Not modelled:
New()/Initialize()changes, runtime overlays and smoothing, lighting, animation past frame 1, filters, transforms, colour matrices,see_invisible. - Everything not drawn exactly is counted in the JSON report:
unknown-typeandmissing-icondraw a magenta/black placeholder,missing-statedraws nothing (as in game),invisible-skipped(--show-invisibledraws them), andapproximate-varwhen a render var is an expression the resolver cannot prove.--areasalso draws area icons.
ingame shows what the map looks like after the game has run: icons changed in
New()/Initialize(), smoothing, runtime overlays and underlays, colour matrices,
transforms, planes, plane masters and lighting. It runs game code: it compiles the
project's .dme with a probe appended (in a temp folder; the checkout is not written),
boots it in DreamDaemon with -safe on 127.0.0.1 with no saves and only config/
copied in, waits until the round is playing and lighting has settled, records the final
appearance of every atom in the region, and shuts down. Never point it at a live server.
node src/cli.js ingame --root /path/to/Civ13 --dme civ13.dme --byond BIN --profile civ13 \
--z 2 --x1 400 --y1 160 --x2 431 --y2 191 --time-of-day Midday --save-dump gaia.json --out gaia-ingame.png
node src/cli.js ingame --root . --dump gaia.json --out again.png --force # re-render without booting- Profiles say when a game is ready:
default(plain worlds) andciv13(starts the round like an admin's start-now, waits for lighting creation and its update queue, builds the HUD's plane masters, turns webhooks and Tor checks off).--mapswaps another map into the.dme'sBEGIN/END_SELECTED_MAPblock. - The game runs in a temp folder with a copy of
config/only. Files it reads at run time go in with--data PATH[,PATH...](project-relative, for example--data maps/heightsfor Civ13's hills). - The image is composed by byond-devtools from the recorded appearances, not taken from a
client: planes in order, plane masters (colour matrix over the whole plane surface,
then their blend mode), layers, south over north, underlays/self/overlays with
inherited dir, colour, alpha, offsets and transform, blend modes, and
see_invisibleof a living player. - Not modelled, counted in the report: filters (including the client's ambient-occlusion
shadow), maptext,
vis_contentson movables (turfvis_contentsare drawn), animation past frame 1,KEEP_TOGETHERgroups,client.colorand screen objects on secondary maps. - A dump may carry
screen([appearance, screen_loc]pairs fromclient.screen) withview(client.view) andcenter: screen objects are placed byscreen_loc(numbers, WEST/EAST/NORTH/ SOUTH/CENTER with offsets,:pixeloffsets,a to branges) and sorted into the same planes. - The result lists
undrawn: visible, clickable movables (mouse_opacitynot 0) whose whole appearance tree put no pixel on the map, so an object a player can interact with but cannot see shows up as a finding.
vscode/ is a custom editor for .dmm files: rendered views with the static renderer,
tile inspection and diagnostics, and editing (place, erase, stamp and move objects, edit a
tile's stack and var overrides, undo/redo). Every change is a whole-stack edit planned by
src/edit.js, and Save writes one patch through src/edit-project.js (base sha256,
expected stacks, verification, atomic replace), so a map changed on disk is never overwritten. CI runs its integration suite inside real VS Code
Stable and Insiders on Linux and Windows. It is published on the
Visual Studio Marketplace
as civ13.byond-devtools-vscode. See vscode/README.md.
Releasing: bump vscode/package.json's version, merge, then push a matching tag vX.Y.Z.
The Release workflow runs the tests, publishes a GitHub release with the .vsix, and
publishes to the Marketplace and Open VSX when they are set up:
- Marketplace: Microsoft Entra sign-in with no stored token. Repository variables
AZURE_CLIENT_IDandAZURE_TENANT_IDname an app registration with a federated credential for this repository'sreleaseenvironment (subjectrepo:Civ13@41390861/byond-devtools@1449711083:environment:release, GitHub's ID form). - Open VSX: secret
OVSX_PAT(an access token from open-vsx.org). The first release creates theciv13namespace.
edit replaces whole tile stacks at given coordinates. It is a dry run unless --apply is
passed. A patch is JSON:
{ "base": "<sha256 of the map file>",
"bounds": { "x1": 10, "y1": 10, "x2": 20, "y2": 20, "z": 1 },
"edits": [ { "x": 12, "y": 14, "z": 1,
"expect": ["/turf/floor/dirt", "/area/caribbean/nomads/forest"],
"set": ["/obj/structure/table{dir = 4}", "/turf/floor/dirt", "/area/caribbean/nomads/forest"] } ] }node src/cli.js edit --root /path/to/Civ13 --map maps/x.dmm --patch patch.json # dry run
node src/cli.js edit --root /path/to/Civ13 --map maps/x.dmm --patch patch.json --apply --inverse-out undo.json- Preconditions: the file's sha256 must equal
base, and each cell's current stack must equalexpect(whitespace outside quotes is ignored). Otherwise nothing is written. - Only the edited grid keys change, plus new dictionary entries for new stacks. New entries
take the lowest free key and go in key order, in the file's own DMM or TGM style and line
endings; an existing identical stack is reused. Unused entries are kept and reported as
orphanedKeys. When every key of the current width is taken, the map is first re-keyed one character wider, asresizedoes (widenedKeys: {from, to}in the result); that rewrites every key, so the diff is large, and every tile is still verified. - Overrides must be
name = valuepairs. A tile with two areas is refused (DreamMaker rejects it). Cells outside the existing blocks cannot be added; useresizefor that. - The output is re-parsed: the world size, every old dictionary entry and every untouched cell must be identical, and edited cells must hold the new stacks.
--applywrites a temp file beside the map, flushes and re-hashes it, re-hashes the original to catch concurrent changes, then renames it over the map. A UTF-8 BOM is kept.- The inverse patch (
base= the new hash) restores every cell. It is not byte-for-byte: the new dictionary entries stay, unused.
resize changes a map's size, adds or removes levels, and fills holes between grid blocks.
It is a dry run unless --apply is passed.
node src/cli.js resize --root /path/to/Civ13 --map maps/x.dmm --max-x 120 --max-y 100 --fill "/turf/floor/dirt,/area/caribbean/nomads"
node src/cli.js resize --root /path/to/Civ13 --map maps/x.dmm --max-x 120 --offset-x 20 --fill "..." --base <sha256> --apply- Unset axes keep their size.
--offset-x/--offset-ymove the existing tiles, so a positive offset grows the map west or south. New space and holes get the--fillstack (one turf and exactly one area); tiles moved past the new edge are cropped. - The dictionary is kept byte for byte. The fill reuses an identical existing entry, or takes the lowest free key in key order. The grid is rewritten as complete blocks in the map's own style (one block per level, or one column per block for TGM) with its line endings, so a resize to the same size is byte-identical. Unused entries are kept and reported.
- When every key of the map's width is taken (52 one-letter keys, for example), the fill
first widens all keys by one character: each key keeps its order and gains a leading
a(bbecomesab), the widened map is checked tile by tile, and the report sayswidenedKeys: {from, to}. This rewrites every dictionary line, so the diff is large. - The output is re-parsed and every tile is checked: kept tiles hold their old stacks at the
moved coordinates, all others hold the fill.
--applywrites atomically aseditdoes, and--baserefuses a map that changed since the dry run. Each axis is at most 1000.
diff compares a map with another file, a git revision, or the result of a patch dry run.
Cells are compared by atom stack, not dictionary key, so a map that mapmerge2 re-keyed has no
changes. Each changed cell lists the atoms removed and added (as multisets); reordered means
the same atoms in a new order, and added/removed mean a hole on the other side.
node src/cli.js diff --root /path/to/Civ13 --map maps/x.dmm --git-ref HEAD
node src/cli.js diff --root /path/to/Civ13 --map maps/x.dmm --patch patch.json \
--dme civ13.dme --byond BIN --out diff.png # before | after | changed tiles- Counts, per-level bounds and per-type totals are complete; the cell list stops at
--limit(default 10,000) and saystruncated. --outrenders the changed area (bounding box plus--padtiles, at most 64 a side, or an explicit--x1..--y2 --z) twice with the static renderer and writes three panels: before, after, and after with unchanged tiles dimmed and changed tiles outlined (yellow modified, blue reordered, green added, red removed).--git-refrunsgit show REF:pathwithout a shell; revisions with..or a leading-are refused. A patch diff never writes the map.
A prefab is a rectangle of tile stacks lifted from a map as JSON, with atom text kept as
authored. Placing one never writes the map: it makes an ordinary edit patch whose expect
stacks are the target's current tiles, so it gets the same base-hash and stale-stack checks,
and can be previewed with diff --patch first.
node src/cli.js prefab-extract --root R --map maps/a.dmm --x1 8 --y1 260 --x2 19 --y2 270 --z 1 \
--layers movable,turf --out house.json
node src/cli.js prefab-place --root R --map maps/b.dmm --prefab house.json --x 410 --y 170 --z 2 --out patch.json
node src/cli.js diff --root R --map maps/b.dmm --patch patch.json --dme civ13.dme --byond BIN --out preview.png
node src/cli.js edit --root R --map maps/b.dmm --patch patch.json --apply --inverse-out undo.json--layerspicks what each tile keeps:movable(objs and mobs),turf,area.replace(default) puts the prefab's stack on each tile, keeping the tile's own turf or area where the prefab cell has none.overlayadds the prefab's movables on top of what is there; a prefab turf or area still replaces the tile's.- Tiles whose result is unchanged are skipped, so placing a prefab twice is a no-op. Missing
prefab cells leave the tile alone. The prefab lists its
types; runlintafter applying when it came from another project. Rotation is not offered:dirvalues would need per-type knowledge to turn correctly.
generators lists the map atoms that make other content when the world starts: spawners,
loot drops, landmarks and (profile civ13) vehicle auto-assemblers. The static preview only
shows their markers, so the report says what each one will produce, read from its vars:
node src/cli.js generators --root R --map maps/nomads/nomads_gaia.dmm --dme civ13.dme --byond BIN --profile civ13
node src/cli.js generators ... --out gens.png --x1 420 --y1 300 --x2 470 --y2 340 --z 2 # markers outlined- An atom is a generator when its type is a subtype of a profile root (
--rootsoverrides). - For each generator type: instance count,
spawns(each var whose source line or map override is a type path or alist(...)of type paths, with pickweight weights and whether each type exists), literalsettingssuch asmax_numberormax_range,unresolvedexpressions, and the init procs (New,Initialize, ...) its type chain defines. - Multi-line
list(values are read across lines. Spawn targets come from source text, not from running code, so whether the generator really uses a var is not proven. --outrenders the region with invisible atoms shown and outlines generator tiles in cyan.
A contract is a JSON list of checks a map region must pass. check runs it and exits 3 on any
failure; edit --contract runs it on the edited text and refuses --apply when it would fail,
so an agent's edit cannot quietly wall off a spawn or leak a sealed room.
{ "kind": "byond-devtools-contract", "schemaVersion": 1,
"actors": { "human": { "dense": true, "blocking": { "paths": ["/turf/floor/beach/water/deep"] },
"passable": { "paths": ["/obj/structure/simple_door"] } } },
"rules": [
{ "id": "spawn", "type": "require", "region": { "x1": 10, "y1": 10, "x2": 20, "y2": 20, "z": 1 },
"match": { "paths": ["/obj/effect/landmark"] }, "min": 1, "max": 4 },
{ "id": "road", "type": "reachable", "from": { "x": 443, "y": 326, "z": 2 }, "to": { "x": 225, "y": 326, "z": 2 }, "actor": "human" },
{ "id": "vault", "type": "enclosed", "seed": { "x": 15, "y": 15, "z": 1 }, "region": { "x1": 12, "y1": 12, "x2": 18, "y2": 18, "z": 1 }, "actor": "human" } ] }node src/cli.js check --root R --map maps/x.dmm --contract c.json --dme civ13.dme --byond BIN
node src/cli.js edit --root R --map maps/x.dmm --patch p.json --contract c.json --dme civ13.dme --byond BIN --apply- Rules:
require(count of matching atoms in[min, max]),forbid,area(every tile's area matches),reachable,unreachable,enclosed(a walk fromseednever leaves the region).matchis{paths, subtypes}; subtypes count by default. - Actors make route assumptions explicit:
blockingpaths,dense: true(type default or map overridedensity, from the native type tree; unprovable densities block and are listed),passablepaths that win over both (doors the actor opens),diagonal(corners cannot be cut, as with BYOND steps),maxSteps. Holes block. Routes stay on one z level. - Failures carry evidence: counts and up to 20 example tiles, the route found (or that an endpoint is blocked and by what), and for a leaking room the first tile outside and the way out.
- A static walk over authored tiles:
Bump(),CanPass(), door locks, runtime spawns and stairs are not modelled. On Gaia a 242-step walk across z2 checks in under 2 s.
src/mcp.js serves the same core as tools over the Model Context Protocol (stdio), for one
project root, so an agent can inspect, render, diff, place prefabs, check contracts and edit
maps without shelling out to the CLI.
node src/mcp.js --root /path/to/Civ13 --dme civ13.dme --byond /path/to/byond/bin # read-only
node src/mcp.js --root /path/to/Civ13 --dme civ13.dme --byond /path/to/byond/bin --allow-write
node src/mcp.js --root /path/to/Civ13 --dme civ13.dme --byond /path/to/byond/bin --allow-game # adds ingame_render
claude mcp add byond-map -- node /path/to/byond-devtools/src/mcp.js --root /path/to/Civ13 --dme civ13.dme --byond BINOr in a project's .mcp.json:
{ "mcpServers": { "byond-map": { "command": "node",
"args": ["D:/GitHub/byond-devtools/src/mcp.js", "--root", "D:/GitHub/Civ13", "--dme", "civ13.dme",
"--byond", "C:/Program Files (x86)/BYOND/bin"] } } }- Tools:
map_summary,map_cell,map_find,map_render(PNG image, at most 64x64 tiles),map_lint,type_info,map_diff(optionally rendered),map_edit,prefab_extract,map_resize,prefab_place,map_generators,map_check,project_compile,icon_info,icon_render,icon_diff,image_compare,ingame_renderanddump_render. Inputs are validated against each tool's schema; unknown arguments are refused. Failures come back as tool errors the model can read. - Every PNG tool takes
scale(1-8, nearest neighbour),background(#rrggbb[aa]ortransparent),inline(false leaves the image out of the reply) andfile(true writes it to abyond-devtools-mcpfolder under the OS temp folder and returns the path, never into the project).map_renderalso filters atoms bykinds/exclude_kindsandtypes/exclude_types(a type and its subtypes), hiding or dimming the rest (filter_mode), and outlines tiles withboxes: [{x, y, width?, height?, color?}]. icon_renderdraws one state, dir and frame of a.dmi(or a type's default icon), or withsheet: trueevery dir (rows) by frame (columns).image_comparecompares a reference PNG (project-relative, or afile: trueoutput) with another PNG or a fresh static render and returns the differing pixel count, bounds and max/mean delta over athreshold, with a reference | candidate | heatmap image.icon_diffcompares a.dmiwith its version at a git revision (defaultHEAD) or with another.dmi, state by state (added, removed, changed size, dirs, frames, delays or pixels), with one before | after | heatmap row per changed state. It is theicon-diffCLI for agents.- Animated PNGs (APNG; viewers without APNG show frame 1):
icon_renderwithanimate: trueplays one state in one dir with its own delays,rewindandloopcount;map_renderwithanimate: {frames: 2-60, interval_ms}renders the region at each interval, every animated state starting together and stepping by its own delays.ingame_renderstays a single frame. ingame_renderis the CLI'singamerender over MCP: it compiles and boots the game headless in a temp folder (-safe, 127.0.0.1, no saves) and composes the initialized world. It runs game code, so it is refused unless the server was started with--allow-game.dump_renderdraws an appearance dump in the same format without booting anything, such as a live Civ13 character's view (character_view). Its icons are inline base64 (runtime icons) or project-relativesourcepaths read from--root; a missing one is amissing-icondiagnostic. Withdumps(snapshots over time) instead ofdumpit returns an animated PNG, one frame per dump everyinterval_ms. The CLI does the same withingame --dump FILE.json[,FILE2.json...] --out FILE.png [--interval-ms N].- Read-only by default.
map_editwithapply: trueneeds--allow-write, and then still requires the patch's base sha256 and expected stacks, verifies the result, and refuses the write if an optionalcontractfails. Read-only tools are annotatedreadOnlyHint. - Map paths are project-relative with realpath containment, as in the CLI. The type tree is
built once per server (restart it after changing DM code). Only
ingame_renderruns game code. - Resources:
byond://guide(a short how-to), every project map asbyond://map/{path}(its summary), and templates forbyond://icon/{path}(states) andbyond://type/{path}(vars). Prompts:render_area,review_map_changeandinspect_iconset up those jobs for the model. - The transport-free API is
createAgentApi()insrc/agent-api.js.
node src/cli.js icon-diff --before old.dmi --after new.dmi --out review.png compares two versions
of a DMI state by state: added, removed and changed states (size, dirs, frames, delays, pixels).
The PNG has one row per changed state: before | after | heatmap. It exits 3 when anything changed
(none stands for a missing side). Civ13 runs it on pull requests that touch icons/.
These run your installed BYOND, distinct from the static checks above. Both work in a fresh
temporary folder from a probe .dme that includes the checkout by absolute path, so nothing is
written to the checkout.
node src/cli.js compile --root /path/to/Civ13 --dme civ13.dme --byond BIN [--map maps/x.dmm]
node src/cli.js playtest --root /path/to/Civ13 --dme civ13.dme --byond BIN --minutes 20 --profile-procs --followcompileruns DreamMaker only (no game code) and reports every error and warning with a project-relativefile:line, the warning code (unused_var, ...) and the.dmbsize; exit 3 on errors.--mapselects another map. Civ13 builds in about 10 s on a cloud runner.playtestruns the game: DreamDaemon-safe, bound to 127.0.0.1,-invisible, with onlyconfig/copied in and no save data, so it cannot reach a live server or its persistence. It printsbyond://127.0.0.1:PORTto join with Dream Seeker and stops--minutes(default 30) after the world finishes loading, on Ctrl+C, or when the world shuts down.- The playtest probe compiles with
DEBUG, so runtime errors carry their source line. They come back grouped by message and location with counts,src,usrand the call stack.--profile-procsadds BYOND's proc profiler (top procs by total time); a heartbeat records CPU, map CPU and player count every 30 s. - There is no step debugger: BYOND has no debugger protocol to attach to, so the integration is compiler diagnostics, runtime-error capture and the proc profiler.
- The VS Code extension has BYOND: Compile project and BYOND: Start local playtest,
which put compile errors and runtime errors in the Problems panel. The MCP server offers
project_compile; it never starts a playtest.
scripts/native.js compiles a map against generated stub types with a separately
installed DreamMaker, boots it headless in DreamDaemon (-safe), and compares every cell
(turf, area, underlay count, contents order and literal override values) with the
parser. Recorded rules: the last turf wins and earlier turfs become underlays, objs enter
contents before mobs, six-digit hex colors are stored lower case and white becomes null,
and a tile with two areas fails to compile (reported as a multiple-areas diagnostic).
node scripts/native.js check --byond /path/to/byond/bin fixtures/native/*.dmm
node scripts/native.js corpus --byond /path/to/byond/bin --root /path/to/Civ13This is map-load agreement only. It runs no game code, so it does not prove that a map works with Civ13's real types.
Licensed under AGPL-3.0 (see LICENSE), matching Civ13. The implementation and fixtures are original. No SpacemanDMM, StrongDMM, FastDMM2, mapmerge2 source, Civ13 map, or BYOND binary is bundled; CI downloads the pinned BYOND build separately and checks its sha256.