Skip to content

The .3md format

3md.

Markdown, but with a third axis you name yourself.

A plain-text format for documents with depth: time, layers, frames, space. Open, MIT. Four libraries: Swift, TypeScript, Rust, and GDScript. Swift, TypeScript, and Rust stay in the hosted conformance lane. Open a document, rotate its cubes, paint a slice, or share it with a link.

Published at 2.2.1. GitHub release v2.2.1, 2026-10-09. Includes the Godot 4.7 addon. Text grammar 1.0 stays frozen. npm and the Swift tag are 2.2.1. crates.io serves threemd 2.2.1. The Rust manifest in the GitHub repo reads 2.2.1. The binary save writes kind 2.

Start with an example

The editor opens local files and folders too. Use Preview for prose, Cubes to orbit, and Slice to draw, erase or fill a compatible grid. See supported files and controls →

01

You decide what Z means.

Markdown is flat. Real things have depth. In 3md the third axis is yours to name, so the same plain-text file becomes a week, a stack of overlays, an animation, or a stage, just by what you call the axis.

  • axis = time
    days, a week, a timeline
  • axis = layers
    source · plain-English · review
  • axis = frames
    animation, step by step
  • axis = space
    x / y / z stage positions
  • axis = slides
    a deck you step through
  • axis = floors
    a building, by elevator
02

Try the web component.

Edit the source on the left; the live viewer on the right is the real <three-md> component people embed. Switch the layout (split · editor · viewer), then copy a share link or an embed snippet (both carry the whole document).

source.3md
live viewer<three-md>
03

Know Markdown? You know 3md.

A version line is the magic marker. An axis names what depth means. @plane directives slice the document along Z, and everything between them is ordinary Markdown. That's the format.

The viewer above is the text component. The shared text contract is green in Swift, TypeScript, and Rust. GDScript is additional and checked locally on Godot 4.7.2. Hosted CI does not install Godot. The demo here reads text. The full viewer and editor also opens uncompressed standard .3mdb and self-contained compositions.

1
free axis
you name what depth means
4
libraries
Swift, TypeScript, Rust, and GDScript
43
conformance vectors
shared text contract, green in Swift, TypeScript, and Rust
1.0
text grammar
frozen. Release 2.2.1
+40
portable bytes
the 2.0 file beside its text
2.2.1
released
npm and Swift. crates.io serves 2.2.1
04

Binary and text are not one result.

Three saves show up in this work, and they do not behave alike. Sculpt's compact file can be a small fraction of the readable text. The portable binary from 2.0.0 is 40 bytes larger than its text. Kind 2 is the structured payload. It is only a little smaller than its text, and faster to decode. npm and the Swift tag are 2.2.1. crates.io serves threemd 2.2.1.

  • Sculpt compact
    App-specific LZFSE .3mdb. Not the portable format. Sparse volumes shrink a lot. Mixed data does not.
  • Portable 2.0
    Uncompressed envelope, magic 3mdbin. Same composition as the text file, plus 40 bytes.
  • Kind 2
    Structured payload inside the version-1 container. Kind 1 binary is deprecated for new files. Older kind 1 files stay readable. Storage has no fixed size stop.

Sculpt's compact save

These five volumes are the app's own compact file beside the readable text. Each figure is the median of five samples in an optimized Swift build, CPU time only. File I/O and rendering are excluded. A sparse result does not predict an arbitrary model. Compact encode is often slower, because the save spends time compressing. Empty and dense match on disk because each volume is uniform. The mixed volume is the one that stays large. The Sculpt.3md page shows the sculptures.

Compact bytes as a share of the readable file. A full bar would mean no saving. Shares under one percent are a hairline on purpose. Grand solar system is 99.64% smaller (185,400 occupied cells) and about 23 times faster to decode, at 19.34 ms against 444.33 ms. Its compact encode is slower: 82.83 ms against 10.82 ms.
Volume Occupied Readable Compact Share Text decode Compact decode Text encode Compact encode
Orb, 16 cubed 608 5,126 505
9.9%
0.55 ms 0.013 ms 0.065 ms 0.042 ms
Grand solar system 185,400 16,854,166 60,313
0.36%
444.33 ms 19.34 ms 10.82 ms 82.83 ms
Empty 256 cubed 0 16,854,157 10,127
0.06%
439.70 ms 18.17 ms 11.06 ms 82.76 ms
Dense 256 cubed 16,777,216 16,854,157 10,127
0.06%
453.14 ms 28.85 ms 10.47 ms 82.82 ms
Mixed 256 cubed 15,098,128 16,854,157 8,163,571
48.4%
574.84 ms 170.94 ms 10.48 ms 287.70 ms

Portable uncompressed binary

This is the 2.0.0 container, not Sculpt's compact save. A 1,024 by 1,024 by 1,024 address domain holds 1,073,741,824 cells. The retained run is an Apple M1 Ultra on macOS 26.5.2. Editable models stay at 256 cells on each axis. Native text is the app's readable world file. Portable text is a ThreeMD composition. Portable binary is that same composition in the uncompressed envelope, exactly 40 bytes larger in both worlds. The native Skyreach save matches its catalog file byte for byte. These world files are under 20 MiB. 2.2.1 no longer stops at a fixed document size. A document is parsed and saved when the process can hold it. A caller can still pass a lower limit.

Stored bytes for the two reusable worlds. The binary column is larger than the portable text column by 40 bytes. Native text is a different file.
World Native text Portable text Portable binary Placements Models Unique voxels Occupied Native encode Native decode
Solid 608,772 671,771 671,811 4,096 2 262,144 1,073,741,824 10.9 ms 80.0 ms
Skyreach 2,249,314 2,229,495 2,229,535 280 9 2,097,152 28,057,022 16.3 ms 251.6 ms
Log-scale bar chart of stored bytes for one 1,024 cubed address domain. Dense raw bytes are 1,073,741,824. The dense LZFSE payload is 53,965,390. Skyreach and Solid text and portable binary files sit near one hundred thousand to a few million bytes. The solid world repeats one 64 cubed model 4,096 times and does not store a billion bytes.
Log scale, so the small files stay visible. The longest bar is the raw 1 GiB probe. The next bar is that probe compressed to 53,965,390 bytes. Neither is a 3md file. The shorter bars are the world files. Solid portable binary is 671,811 bytes. Solid portable text is 671,771.

The 1 GiB probe is not a 3md file

The probe allocates one buffer of 1,073,741,824 bytes, writes every byte, hashes it, streams Apple LZFSE, then decodes and compares every byte. The compressed payload is 53,965,390 bytes. It is not in the repository, and it is not a .3md or .3mdb. Times below are the final run, one clock sample each, not an average. Encode includes the compressed hash, the file write, and sync. The final decode added 3,768,344 bytes of physical footprint. The first decode grew the process by 56,541,232 bytes.

Final dense probe on an Apple M1 Ultra. Not a document decode.
Phase Final run
Fill every byte 0.389 s
Hash the buffer 0.487 s
LZFSE encode 6.076 s
Decode and compare 0.804 s
Bar chart of the dense 1 GiB probe, final run, on an Apple M1 Ultra. Fill, hash, LZFSE encode at 6.076 seconds, and decode and compare at 0.804 seconds. Encode includes hash, write, and sync.
Phase times for the raw probe. LZFSE encode dominates, at 6.076 seconds.

What those worlds draw

Ten cases, 120 camera submissions, and 12 frames each, at 800 by 600. The median includes SceneKit flush, GPU sync, and readback. It is not an on-screen frame rate. The renderer does not draw a billion individual cubes. Visible instances stay at or below 512. The solid mesh is one shared 24,576-face model. Skyreach prepares 146,918 faces across eight leaves and reuses them. Wide solid cases omit 3,584 placements.

Bar chart of offscreen Metal frame medians, 12 frames each, including GPU sync and readback. Solid cases sit between 2.641 and 3.153 milliseconds. Skyreach cases sit between 1.626 and 2.546 milliseconds. Not an on-screen frame rate.
Median of 12 offscreen frames. The upper five cases are the solid world. The lower five are Skyreach. The table lists every median.
Detail chunks, wireframe proxies, placements omitted by the instance budget, and distance-culled placements.
Case Detail Proxy Omitted Culled Median frame
Solid, center, narrow 20 188 0 3,888 3.057 ms
Solid, center, wide 20 492 3,584 0 3.153 ms
Solid, shifted 20 124 0 3,952 2.641 ms
Solid, ground 20 119 0 3,957 2.661 ms
Solid, wide budget 20 492 3,584 0 3.092 ms
Skyreach, center, narrow 1 1 0 278 1.770 ms
Skyreach, center, wide 4 276 0 0 2.300 ms
Skyreach, shifted 1 0 0 279 1.626 ms
Skyreach, ground 20 22 0 238 2.187 ms
Skyreach, wide budget 33 247 0 0 2.546 ms
Offscreen frame of the solid world from the center at wide distance: a small pale lattice cube in a dark field.
Solid, center, wide. 20 detail, 492 proxies, 3,584 omitted. Median 3.153 ms.
Offscreen frame of Skyreach from the center at wide distance: a flat lattice ground and a loose field of floating cube outlines.
Skyreach, center, wide. 4 detail and 276 proxies. Median 2.300 ms.
Offscreen frame of Skyreach from the ground at narrow distance: a tiled landscape with trees and roofs, surrounded by cube outlines.
Skyreach from the ground, narrow. 20 detail and 22 proxies. Median 2.187 ms.

Kind 2, the structured payload

Text grammar stays 1.0. The libraries on npm are 2.2.1: @corvidlabs/threemd and @corvidlabs/three-md-element. The Swift tag is v2.2.1. The threemd crate on crates.io is 2.2.1. The Rust manifest in the GitHub repo reads 2.2.1. .binary writes payload kind 2, the same document as length-prefixed records, inside the version-1 container. Kind 1 binary is deprecated for new files. Kind-1 files from 2.0 stay readable. Kind 3 is reserved. The same kind-2 sizes came out of Swift, TypeScript, and Rust. The checksum detects corruption. It does not authenticate the file. Optional LZFSE stays Apple-only. TypeScript and Rust return an unsupported-backend error. GDScript refuses LZFSE. Uncompressed storage is the portable contract.

The viewer on this page, and the published web component, stay text renderers. The full editor opens uncompressed standard binary and embedded composition entries. Sculpt compact saves and LZFSE need a readable or uncompressed export; see the viewer guide for limits and current loading gaps. The element bundle that ships with the library work is 48,840 bytes and contains no storage codec. The command line convert and inspect commands stay text-only.

Kind-2 bytes divided by canonical text bytes. A full bar would mean the same size as text. synthetic-2000 ceiling is 0.995. sculpt-4096 ceiling is 0.98. Both samples are under their ceiling, and only by a few percent.
Sample Kind-2 bytes Size ratio
synthetic-2000 3,998,362
0.990311
sculpt-4096 2,934,090
0.967917
Local library check, not the performance gate. One process per language, warmup 1 second, median of 9 samples. The gate warms for 3 seconds and uses the median of 3 processes. Bun was 1.4.0, not the gate pin 1.4.2. Node was not measured. G1 is kind-2 decode divided by bounded text decode. G2 divides by the legacy parser. K1 is kind-1 decode divided by bounded text decode. Synthetic G1 ceilings are 0.07 for Swift and 0.25 for Bun and Rust. Rust synthetic G1 is 0.233, under 0.25 and close to it. Swift's 0.037 is a ratio against a slow text baseline of about 0.264 seconds. Rust's text baseline on that input was about 0.023 seconds, and Bun's was about 0.071 seconds. The kind-2 decode row is the absolute time.
Check SwiftBun 1.4.0Rust
Synthetic G1 0.037 0.121 0.233
Sculpt G1 0.023 0.116 0.125
Synthetic G2 0.079 0.244 0.378
Sculpt G2 0.047 0.206 0.151
Synthetic K1 1.009 0.995 1.043
Sculpt K1 1.016 1.056 1.026
Synthetic kind-2 decode 9.8 ms 8.5 ms 5.4 ms
Synthetic encode / decode 0.40 1.57 0.94
Sculpt encode / decode 0.85 1.64 0.68

Encode divided by decode, synthetic then sculpt: Swift 0.40 and 0.85, Bun 1.57 and 1.64, Rust 0.94 and 0.68. Those ceilings are 2.0 for Swift and Rust and 3.5 for TypeScript. A ratio above 1 means encode took longer than decode.

05

agent.3md builds on the format.

Put an agent in a single .3md file: plane 0 is the agent, every other plane is a skill. That project has its own page because the agent layer adds routing, CLI bindings, loaders, and MCP on top of the base 3md format.

  • progressive disclosure
    The agent loads only the skill it needs, not all of them.
  • flat at scale
    Keep the skill index out of the prompt and query it as a tool, and per turn context stays roughly flat as the agent grows.
  • portable
    The same file loads in TypeScript, Rust, and Swift.
  • mcp-ready
    Run it as an MCP server and any agent can call its skills as tools.

Markdown, with depth.

One free axis, four libraries, and text grammar 1.0. The shared text contract is green in Swift, TypeScript, and Rust. GDScript is additional and local. The component on this page reads text. The 2.0.0 portable file is the text plus 40 bytes. The binary save writes kind 2. npm and the Swift tag are 2.2.1. crates.io serves threemd 2.2.1.