Crate openworldformat 

openworldformat (Rust)

The Open World Format’s Rust reference, extracted from LocalGPT’s world-types, world-sync and world-physics crates — the same code that implemented the format since its origin, now in the format’s own home. The document (types + edits), the session fold (log, branches, state), and the extensions’ executable halves (ext-physics, ext-cinematography), in one serde-only crate: no Bevy, no async, no sockets.

use openworldformat::{WorldManifest, OpLogEntry};
let manifest: WorldManifest = serde_json::from_str(
    std::fs::read_to_string("world/manifest.json")?.as_str(),
)?;
let entries: Vec<OpLogEntry> = std::fs::read_to_string("world/ops.jsonl")?
    .lines()
    .filter(|l| !l.trim().is_empty())
    .map(serde_json::from_str)
    .collect::<Result<_, _>>()?;
let doc = openworldformat::fold_log(&manifest.as_base()?, &entries)?;
println!("{} entities at head", doc.len());

Provenance and plan: LocalGPT remains the app-side consumer; its crates flip to depend on this one (a re-export shim) when they’re quiet, ending the dual maintenance. Until then, both sides generate the same world.schema.json — the schema snapshot test on each side is the drift guard.

Re-exports

pub use asset::MeshAssetRef;

pub use asset::NodeOverride;

pub use audio::AudioDef;

pub use audio::AudioKind;

pub use audio::AudioSource;

pub use audio::FilterType;

pub use audio::Rolloff;

pub use audio::WaveformType;

pub use authoring::Ingested;

pub use authoring::Refused;

pub use authoring::ingest;

pub use authoring::merge_patch;

pub use avatar::AvatarDef;

pub use avatar::PointOfView;

pub use behavior::BehaviorDef;

pub use behavior::PathMode;

pub use creation::CreationDef;

pub use creation::SemanticCategory;

pub use doc::ApplyError;

pub use doc::WorldDoc;

pub use entity::EntityPatch;

pub use entity::WorldEntity;

pub use entity::WorldTransform;

pub use entity::values_close;

pub use entity_refs::ENTITY_REFS;

pub use entity_refs::EntityRefField;

pub use entity_refs::EntityRefKind;

pub use entity_refs::EntityRefScope;

pub use ext_h3::EXT_H3_KEY;

pub use ext_h3::ExtH3Frame;

pub use ext_h3::ExtH3Placement;

pub use ext_h3::LatLng;

pub use ext_provenance::EXT_PROVENANCE_FIELDS;

pub use ext_provenance::EXT_PROVENANCE_KEY;

pub use ext_provenance::ExtProvenance;

pub use hash::sha256;

pub use hash::sha256_hex;

pub use history::AmbienceLayerDef;

pub use history::EditHistory;

pub use history::EditOp;

pub use history::WorldEdit;

pub use identity::CreationId;

pub use identity::EntityId;

pub use identity::EntityName;

pub use identity::EntityRef;

pub use identity::MAX_ENTITY_ID;

pub use instance::InstanceOf;

pub use instance::PartLink;

pub use instance::PartOverride;

pub use instance::expand_instances;

pub use instance::part_links;

pub use instance::validate_instances;

pub use light::LightDef;

pub use light::LightType;

pub use material::AlphaModeDef;

pub use material::MaterialDef;

pub use material::TextureSlot;

pub use modulation::ModulationDef;

pub use modulation::ModulationTarget;

pub use modulation::SignalSource;

pub use modulation::StemKind;

pub use oplog::OpLogEntry;

pub use oplog::canonical_json;

pub use oplog::compute_entry_id;

pub use oplog::decode_line;

pub use oplog::encode_line;

pub use package::BASE_SNAPSHOT;

pub use package::PACKAGE_FORMAT_VERSION;

pub use package::compact_plan;

pub use package::manifest_text;

pub use package::manifest_text_of;

pub use package::snapshot_filename;

pub use session::MergedBranch;

pub use session::fold_log;

pub use session::fold_path;

pub use session::main_tip;

pub use session::merge_branch;

pub use shape::PrimitiveShapeKind;

pub use shape::Shape;

pub use soundtrack::SoundtrackDef;

pub use soundtrack::StemCurves;

pub use soundtrack::curve_at;

pub use spatial::ChunkCoord;

pub use state::StateDoc;

pub use state::StateField;

pub use state::fold_state;

pub use strict::REGISTERED_EXTENSIONS;

pub use strict::StrictError;

pub use strict::decode_line_strict;

pub use strict::parse_manifest_strict;

pub use strict::registered_extensions;

pub use tour::TourDef;

pub use tour::TourMode;

pub use tour::TourWaypoint;

pub use trigger::TriggerActionDef;

pub use trigger::TriggerDef;

pub use trigger::TriggerEvent;

pub use trigger::TriggerVolume;

pub use validation::Severity;

pub use validation::ValidationIssue;

pub use validation::WorldLimits;

pub use validation::validate_entities;

pub use validation::validate_manifest;

pub use world::CameraDef;

pub use world::ComplianceMeta;

pub use world::EnvironmentDef;

pub use world::IdCeilingError;

pub use world::WorldManifest;

pub use world::WorldMeta;

pub use world_patch::WORLD_PATCH_KEYS;

pub use world_patch::WorldPatch;

Modules

asset

Asset references — for imported meshes, textures, and audio files.

audio

Unified audio definitions — merges ambient and emitter sound systems.

author

Who or what wrote a log entry — a person, a model, a visitor, a host. Authorship is what makes the log an audit trail: “what did the model do here, versus the people?” is a filter on one field.

authoring

Authoring: what an authority does with a batch of ops an author sends (spec/session.md, “Authoring”). The fold reads committed ops; this is the step before — turning what an agent, a script or a person wrote into ops worth committing, or refusing them with reasons.

avatar

Avatar definition — user/explorer presence in a world.

behavior

Declarative behavior definitions — data-driven entity animations.

cinematography

openworldformat::cinematography

creation

Creation definitions — compound objects made of multiple entities.

doc

The shared document: a world’s entities by id plus its scene-wide settings, changed only by applying world-types EditOps.

entity

WorldEntity — the composable entity definition.

entity_refs

The one list of entity-reference fields (spec/world.md “Identity”, schema/entity-refs.json) — the crate’s embedded copy. The canonical list is generated from world.schema.json’s x-entity-ref markers by schema/generate-entity-refs.mjs, but a published crate can’t read the repo’s schema/ at runtime, so the passes read this table instead, and tests/entity_refs.rs fails when it drifts from the canonical file.

ext_h3

The geo frame extension — ext-h3 (spec/extensions/h3.md), version 0.1: where an entity sits on a globe, as an H3 cell plus an integer-only transform in that cell’s frame, beside the core transform that a reader without the extension draws.

ext_provenance

LLM provenance — the ext-provenance extension (spec/extensions/provenance.md).

hash

SHA-256, hand-rolled — the one hash the format’s entry identity needs, kept in-crate so “serde-only, no engine required” stays literally true on every target (spec/session.md’s canonical-hash rule names the algorithm; it doesn’t get to name a dependency).

history

Undo/redo history — edit operations and their inverses.

identity

Entity identity — dual ID + name system.

instance

Instances of reusable creations — one definition, many placements.

light

Light definitions — directional, point, and spot lights.

material

PBR material definition.

modulation

Signal-driven modulation — the reactive layer of a world.

oplog

The op log: one JSON object per line, ops.jsonl — the room’s durable, replayable history (spec phase 5; the session package’s one log — see docs/rfcs/multiplayer/session-package-format.md).

package

The package’s derived parts: snapshot naming and compaction (spec/package.md, spec/session.md “Snapshots”). The file moves themselves stay with the host app — this crate is the format’s serde-only core — so what lives here are the decisions a host could get wrong: which name a snapshot goes under, and what compaction changes on paper.

physics

openworldformat::physics

session

The session log’s op vocabulary — what a line in ops.jsonl can hold.

shape

Parametric shape definitions — type-safe, never loses dimension info.

soundtrack

The song a world performs to.

spatial

Spatial indexing — chunk coordinates for large world streaming.

state

The state document and its fold: where the game is, not what the scene is (spec/state.md). A save game is base + state declaration + a player’s session log — the fold below is the arithmetic.

strict

Strict mode — must-ignore’s off switch (spec/profiles.md).

tour

Tour definitions — guided camera/avatar paths through the world.

trigger

Triggers — what happens when a visitor clicks, comes near, or waits.

validation

World validation — budget limits and constraint checking.

world

World manifest — the top-level world definition.

world_patch

ModifyWorld’s patch: the document’s scene-wide fields, changed the way ModifyEntity changes an entity (spec/session.md, “The op kinds”) — an absent key leaves its field alone, null clears it, a value sets it. With it every field of a manifest is reachable by an edit, so the fold’s state is always a whole manifest.

Constants

WORLD_SCHEMA_VERSION

The manifest schema version this crate reads (spec: schema v3).