Skip to content
Cairn

Cairn — Minecraft Build DSL Specification 2026.06 (draft)

Cairn (a cairn is a deliberately stacked pile of stones that marks a place) is the normative specification of an intermediate language for AI to read and write Minecraft builds. It avoids the inefficiency of NBT/SNBT (binary, one-record-per-block) and aligns architectural knowledge (walls, roofs, symmetry) with the voxel world. The approach is generation-first (lossy).

Reading order

Section titled “Reading order”
# Chapter Contents
1 Purpose and Scope Purpose, scope, non-goals
2 Design Principles Design principles P1–P5
3 Architecture Three-layer IR + block-array universal pivot
4 Compilation Model Phase evaluation, target axes
5 Syntax Lexical, key=value, selectors, headers
6 Blockstate Model Derivation + override, intent/resolved, waterlogged
7 Materials and Themes Slots, canonical vocabulary, themes
8 Entities Two-tier entity model, anchor conventions
9 Components, Editing, and Multi-building def, editing, multi-building
10 Versioning and Editions Version/edition strategy, lock
11 Lint Lint and constraint validation
12 Ecosystem Interop Ecosystem interop, reverse conversion
13 Evaluation Framework Evaluation framework
14 Redstone Redstone (logic circuits)
15 Open Issues Open issues
— Compatibility Tiers Stable / Evolving / Internal contract for every public surface
— Glossary Cross-chapter glossary of defined terms

Terminology and conventions

Section titled “Terminology and conventions”
  • Requirement-level words: MUST / SHOULD / MUST NOT / OPTIONAL (RFC 2119 sense).
  • The language name is Cairn, the CLI tool is cairn, and source files use the .crn extension.
  • Design principles are referenced as P1–P5 (see Design Principles).

Versioning

Section titled “Versioning”

Cairn’s own releases use date-based versioning (CalVer) YYYY.M[.PATCH].

  • Examples: 2026.7 (monthly release), 2026.7.1 (in-month patch). Sorts chronologically as a string.
  • This document is 2026.6 (draft), superseding the former v0.2 label.
  • A release bundles “language spec + reference compiler + standard library + (edition,version) registry/constraint catalogs”. It appears in cairn --version and the lock’s cairn_version (see Versioning and Editions).

Separate axis from the Minecraft target version (do not conflate):

  • Cairn version 2026.06 — the release of the Cairn tool itself.
  • MC target — the output Minecraft (--edition java --target <version>; see Versioning and Editions).

Minecraft itself moved to date-based versions from its latest release, so the two cannot be told apart by format. Versions are ALWAYS distinguished by field/flag/keyword:

  • lock: cairn_version vs mc_version
  • headers: @cairn vs @requires / @intended_targets
  • CLI: cairn --version (Cairn itself) vs --target (MC)

When ambiguous in prose, use a prefix: cairn:2026.06 / mc:<version>.

A .crn file MAY declare @cairn 2026.06 (the Cairn language version it was written against). This is a separate axis from the MC-version headers @requires / @intended_targets, and exists as provenance so a future compiler can parse/warn correctly (see Syntax).