PlankMD
Status: Draft (v0.3), not yet stable.
Website: plankmd.org, with the spec, the
player and the gallery.
PlankMD is an open, Markdown-based format for constructions made of
identical wooden building planks, and for the steps to build them.
A .plank.md file is a 3D model and an instruction booklet at the same time:
one plank per line, one fenced block per building step, and plain Markdown
prose in between for the instructions. It is readable in any text editor,
diffs cleanly in Git, and is short and regular enough for a language model to
write and check.
## Step 1: the first layer
Lay two planks flat and parallel, then two across them, on their ends.
```plank
flat-x 0 0 0
flat-x 0 12 0
flat-y 0 0 1
flat-y 12 0 1
```
## Step 2: build up the walls
```plank
flat-x 0 0 2 repeat=4 offset=0,0,2
flat-x 0 12 2 repeat=4 offset=0,0,2
flat-y 0 0 3 repeat=4 offset=0,0,2
flat-y 12 0 3 repeat=4 offset=0,0,2
```
Positions are counted in plank thicknesses (a plank is 15 × 3 × 1), so most
models only use small integers. The order of the lines is the order in which
the builder places the planks, and the validator checks every plank at the
moment it is placed: nothing goes through anything, and nothing floats.
Gaps are measured the way builders measure them, with planks used as rulers:
a guide line is a ghost plank shown during its step only. It tells the
builder how much space to leave, and the validator checks that the space is
right.
guide flat-x 0 3 0 repeat=3 offset=0,3,0 # leave three plank widths between the walls
flat-x 0 0 0
flat-x 0 12 0
Planks can lean (lean=-x:20, a ramp) or tilt around a common axis
(tilt=x:-90 tilt-step=5 tilt-pivot=0,0.5, the fan of a true arch); a ring of
planks around a centre is one line (rot-step=60 pivot=0,0 order=whole); and
a scaffold line is a temporary support that holds up what cannot stand yet,
removed at the end of its step.
A step can say where to look at it from (```plank view=back-left,20), and
the frontmatter of a shared model says who made it, where it lives and what
it looks like built (author, url, image, tags…).
Gallery
gallery/ holds twelve larger models (CC0): a castle, a lighthouse,
a pagoda, a sailing ship, a windmill, an amphitheatre, five landmarks
(an Eiffel-style tower, a step pyramid, a Greek temple, a triumphal arch,
the Pantheon under its ring dome), and Notre-Dame de Paris, 1392 planks in
29 steps.
Each one stands at every placement in the balance check and in the drop
test (npm run check:gallery). Open player/gallery.html to browse them.
What is in this repository
| Path | What it is |
|---|
SPEC.md | The format specification |
docs/llm-instructions.md | A ready-to-use system prompt for writing PlankMD with an LLM |
src/plankmd.js | Reference implementation: parse, expand, validate. No dependencies, Node and browser |
bin/plankmd.js | Command-line validator |
src/physics.js | Balance check: does it stand at every placement, and how much tilt does it withstand? Optional, needs HiGHS |
src/drop.js | Drop test: a physics engine (Rapier) lets gravity act on the model |
gallery/ | Twelve larger models, checked for balance |
site/ | Source of plankmd.org (VitePress) |
player/ | A 3D player: steps, plank-by-plank replay, live editing, diagnostics, balance check and drop test; a printable booklet (booklet.html) and a building video (video.html) of any model |
samples/ | Example models (CC0): square tower, twisted tower, corbel bridge, a ring dome, and three models that fall on purpose: a diving board (at step 3), a leaning tower (when its flag goes on top) and a fan arch (when its centring comes out) |
Quick start
See a model. Open player/index.html in a browser, pick a sample, or drop
your own .plank.md file on the scene. Edit the source on the left, and the
model and the diagnostics update as you type. player/index.html?src=<url>
loads a model from the web, and
plankmd.org/p?repo=<GitHub address>
opens every model of a GitHub repository, in the browser only. The player
speaks English and French (EN/FR switch, or ?lang=fr).
Validate a model. With the npm package,
npx plankmd validate model.plank.md; in a clone of this repository:
node bin/plankmd.js validate samples/*.plank.md
✓ samples/corbel-bridge.plank.md: 45 planks, 3 steps, 0 errors, 0 warnings
Each diagnostic names its line and its plank number, for example
model.plank.md:31: W-floating plank 12 ("flat-y 0 0 3") rests on nothing when it is placed. Add --json for machine-readable output and --strict
to fail on warnings. node bin/plankmd.js expand <file> lists every plank in
placement order.
Check that it stands. --physics adds a balance check: after every
plank placed, can the construction stand? And at the end of every step, how
much can the table tilt before it falls?
npm install # installs the optional solver, HiGHS
node bin/plankmd.js validate samples/corbel-bridge.plank.md --physics
samples/corbel-bridge.plank.md: step 3 stands, withstands a 9.7° tilt (towards +x)
✓ samples/corbel-bridge.plank.md: 69 planks, 3 steps, 0 errors, 0 warnings, stands
This is the beginning of the README. Read the rest at the original. Read the full README ↗
