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
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
It models planks as rigid blocks resting on each other, with friction
(rigid-block equilibrium, solved as a linear program). It is conservative:
planks pressed side by side get no help from friction. Its findings are
reported as information (I-unstable, I-fragile), never as errors: they
are not part of the format. In the player, tick Check balance to run the
same check in the background. It is off by default, as it keeps a processor
core busy: the verdict (stands, or falls from plank N) comes within a second
or two even on 200 planks, then the tilt of each step follows, step by step,
in up to half a minute.
A physics engine gives a second opinion, and shows the fall: Drop test
drops the planks shown all at once, Replay build puts them down one by
one in building order and stops on the first placement that makes the
construction move. Both run in the player, in slow motion, and on the command
line (node bin/plankmd.js drop <file>). The balance check and the engine are
validated against each other on test/cases/.
Use it as a library.
const PlankMD = require('./src/plankmd.js'); // or window.PlankMD in a browser
const { valid, planks, steps, diagnostics } = PlankMD.validate(text);
Print a booklet, make a video. The player links to an A4 building
booklet and to a building video of the model shown. From the command line,
with Chrome and ffmpeg installed:
npm run booklet -- gallery/castle.plank.md # castle.pdf
npm run video -- gallery/castle.plank.md # castle.mp4, ready for YouTube
Generate models with an LLM. Give the model
docs/llm-instructions.md as its system prompt,
ask for a construction, run the validator on the result, and send the
diagnostics back until it is clean.
Run the tests. npm test (Node 18 or later). Without npm install, the
balance and drop tests are skipped and the rest runs with no dependency.
Compatibility
Compatible with KAPLA® planks: the default plank size (plank: [15, 3, 1],
unit_mm: 7.8) matches them. Any other planks work too: declare their
proportions in the frontmatter.
KAPLA® is a registered trademark of its owner. PlankMD is an independent
project; it is not affiliated with, sponsored or endorsed by any plank
manufacturer.
Design
PlankMD follows the design principles of LearnSpec,
an open suite of Markdown formats for learning: Markdown-first, file-native,
progressive levels (Level 0 is one block of four numbers per line), and built
to be generated and consumed by AI systems.
License
MIT for the specification, the code, the website and the logo.
The models (samples/, gallery/, test/cases/) are released under CC0.
The optional solvers keep their own licenses: HiGHS is MIT, Rapier is
Apache-2.0.
