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.
--- 3md: 1.0 # the magic marker axis: time # you name the Z axis title: My week --- @plane z=0 label="Monday" # Monday - [ ] Standup at 9 @plane z=1 label="Tuesday" # Tuesday - [ ] Ship the release
Start with an example
Paint a sculpture ↗
Open in Cubes, then try Slice.
Read layered notes ↗
Choose Preview and step through planes.
Open a binary file ↗
The same canopy as portable .3mdb.
Explore a composition ↗
Read its root. Open the file locally for Inside entries.
Browse a GitHub folder ↗
Open the public example files.
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 →
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 = timedays, a week, a timeline
- axis = layerssource · plain-English · review
- axis = framesanimation, step by step
- axis = spacex / y / z stage positions
- axis = slidesa deck you step through
- axis = floorsa building, by elevator
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).
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.
--- 3md: 1.0 # required version axis: layer # time · layer · frame · space… title: Annotated clause --- @plane z=0 label="source" Deliver within thirty (30) days. @plane z=1 label="plain english" You have 30 days from signing.
- 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
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 compactApp-specific LZFSE .3mdb. Not the portable format. Sparse volumes shrink a lot. Mixed data does not.
- Portable 2.0Uncompressed envelope, magic 3mdbin. Same composition as the text file, plus 40 bytes.
- Kind 2Structured 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.
| 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.
| 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 |
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.
| 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 |
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.
| 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 |
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.
| Sample | Kind-2 bytes | Size ratio |
|---|---|---|
| synthetic-2000 | 3,998,362 | 0.990311 |
| sculpt-4096 | 2,934,090 | 0.967917 |
| Check | Swift | Bun 1.4.0 | Rust |
|---|---|---|---|
| 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.
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 disclosureThe agent loads only the skill it needs, not all of them.
- flat at scaleKeep the skill index out of the prompt and query it as a tool, and per turn context stays roughly flat as the agent grows.
- portableThe same file loads in TypeScript, Rust, and Swift.
- mcp-readyRun it as an MCP server and any agent can call its skills as tools.
--- 3md: 1.0 axis: skill # plane 0 is the agent agent: atlas model: claude-opus-4-8 --- @plane z=0 label="Atlas" Route each task to the skill that matches. @plane z=1 label="web-research" triggers="search, find, latest" Find current info, then cite sources.
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.