An open format for worlds

A .world is a folder (a zip is its transport form) holding a world document, a typed state document, an append-only session log, and content-addressed assets. State at any revision is a pure fold of the log over the base — which makes rendering, editing, multiplayer, undo, save games, replays and mods all reads over one history.

It is the layer above glTF, not a competitor: meshes stay glTF leaves, referenced by content hash. glTF owns transport; .world owns composition, parametric authoring, behavior, audio, game state and sessions.

Read the spec

1. The world document — what a world is
2. The package — the folder, assets by hash, integrity
3. The session log — the ops that build a world, and the history around them
4. Profiles and extensions — must, may, must-ignore
5. Versioning policy — the compatibility contract

The JSON Schema is normative; the conformance worlds define correct rendering — and you can watch them draw: open the live viewer, the reference three.js renderer running the whole suite in this tab. The same page opens any manifest: world.html?src=….

Try it in a minute

npm install openworldformat

import { parseManifest, parseLogLine, foldLog, toManifest } from "openworldformat";

// manifest.json is the world now — a viewer needs nothing else.
const world = parseManifest(await fs.readFile("world/manifest.json", "utf8"));

// The history folds over snapshots/base.json back to the same world.
const base = parseManifest(await fs.readFile("world/snapshots/base.json", "utf8"));
const entries = (await fs.readFile("world/ops.jsonl", "utf8"))
  .split("\n").filter(Boolean).map(parseLogLine);
const head = toManifest(foldLog(base, entries)); // the same world

Or in Python, where the same fold is pure standard library:

from pathlib import Path
from openworldformat import read_package, fold_log

base, entries, head, package = read_package(Path("world"))
state = fold_log(base, entries)   # the world at head revision
state["entities"], state["applied_edits"]

Agents change a world from outside the app that shows it: they send batches of edit ops to the package’s one authority, which binds names, merges partial patches, reads strictly and commits all or nothing (the session log, “Authoring”).

Get it

Five references parse and fold a .world. Each runs the same conformance worlds and the same authoring outcome suite, so a fold — and a receipt — reads the same in every one.

• JavaScript — npm install openworldformat (npm). The reference three.js renderer ships in the package as openworldformat/render; it is what the viewer runs.
• Python — pip install openworldformat (PyPI). Pure standard library and deliberately no renderer: the research surface, for benchmarks, dataset tooling over session logs, and notebooks.
• Rust — cargo add openworldformat (crates.io, docs.rs). The types, the fold and the branches, game state, and the ext-physics and ext-cinematography extensions' executable halves; serde only, no engine.
• Swift — .package(url: "https://github.com/openworldformat/openworldformat", from: "0.3.5"), product OpenWorldFormat. macOS, iOS, iPadOS and visionOS; released on bare vX.Y.Z tags of the repository.
• Kotlin — kotlin/, JVM and Android (minSdk 26), built from source as a Gradle composite build until it reaches Maven Central.

Tools that use it

Packages are written and read outside this repository, each tool riding one of the references above.

• worldprobe — the desktop inspector (source): drop a package folder and see the fold, the validation verdict, the branches, a diff between any two points of the history, the state and the physics. Over the Rust crate, adding no format semantics of its own.
• worldwalk — a viewer for macOS, iOS, iPadOS and visionOS (SwiftUI and RealityKit, over the Swift package) and Android (Compose, over the Kotlin package) (source): open a package, pick a branch tip, walk the world it folds to. It draws what the fold says and nothing more.
• LocalGPT — local apps that write packages from a prompt, a Markdown document or a song, and open any package as a live canvas that agents edit from outside (localgpt.app, over the Rust crate). localgpt.md drafts a screenplay into one package per scene in the browser, and localgpt.world plays worlds in the reference renderer.

Status

Draft 0.3, describing manifest schema version 3 and package format 2 (head-first). The schema, the conformance suite and the five reference implementations above are in the repository, tested in CI. Expect churn until 1.0; the versioning policy is the contract.

Since draft 0.3, within schema version 3 — every addition optional, so a reader that predates it stays conforming by ignoring it:

• Receipts for agents. A batch may name the revision it read, the authority’s reply is a receipt, and every reference runs one authoring outcome suite (the session log).
• The geometry of every shape, stated here rather than inherited from an engine, and pinned by landmark points any renderer can check (the world document).
• Prism, a prism with a side count, 3 to 8 — experimental (see it).
• Exports from other systems. author.source says how each batch came to be — hand, library or ai — and a producer that keeps its own live truth can export a world with the history that built it (the package).
• Extensions. ext-cinematography is experimental at 0.3 — cameras with a filmback and a lens, shots aimed and focused by entity — in four references; ext-h3, a geo frame for worlds that live on a globe, is proposed.