defocus

World substrate for interactive narrative, IF, and stateful simulations.

defocus is a protocol-level world model where everything is an object, all interaction is message passing, and rules are structured data (ASTs, not text). The same world file runs on multiple runtimes: Rust (server/CLI), TypeScript (browser/Node), with WASM and Lua via Crescent planned. It replaces the ad-hoc state management that every IF/narrative tool reinvents.

import { WorldBuilder } from "defocus-core";

const world = new WorldBuilder()
  .object("local:room")
    .state("description", "A dusty room with a heavy door.")
    .ref("door", "local:door")
    .handler("look", ["perform", "reply", ["get-in", ["get", "state"], "description"]])
    .done()
  .object("local:door")
    .state("open", false)
    .handler("open", [
      "do",
      ["perform", "set", "open", true],
      ["perform", "reply", "The door creaks open."],
    ])
    .done()
  .build();

world.send("local:room", { verb: "look", payload: null });
let replies = world.drain(100);
// => ["A dusty room with a heavy door."]

world.send("local:door", { verb: "open", payload: null });
replies = world.drain(100);
// => ["The door creaks open."]

use defocus_core::world::{Object, World, Message};
use defocus_core::value::Value;

let mut world = World::new();

world.add(
    Object::new("local:room")
        .with_state("description", "A dusty room with a heavy door.")
        .with_ref("door", "local:door")
        .with_handler("look", serde_json::from_value(serde_json::json!(
            ["perform", "reply", ["get-in", ["get", "state"], "description"]]
        )).unwrap())
);

world.add(
    Object::new("local:door")
        .with_state("open", Value::Bool(false))
        .with_handler("open", serde_json::from_value(serde_json::json!([
            "do",
            ["perform", "set", "open", true],
            ["perform", "reply", "The door creaks open."]
        ])).unwrap())
);

world.send("local:room".into(), Message { verb: "look".into(), payload: Value::Null });
let replies = world.drain(100);
// => [Value::String("A dusty room with a heavy door.")]

• Object-message architecture -- everything is an object, all interaction is message passing
• Rules as data -- handlers are JSON ASTs, not source text; diffable, serializable, visually editable
• Prototype inheritance -- objects delegate to prototypes; handler resolution walks the chain
• Capability-based refs -- $ref values with optional $verbs for attenuated access
• Fluent builder DSL (TypeScript) -- WorldBuilder / ObjectBuilder for ergonomic world construction
• Expression evaluator -- Marinada subset: arithmetic, logic, control flow, closures, pattern matching
• Algebraic effects -- perform expressions produce effects (set state, send messages, reply, spawn, remove, schedule)
• World queries -- query op filters objects by state, interface, prototype, children, has-state
• LLM integration -- llm op calls a pluggable provider from within handlers; outputs logged for deterministic replay
• Event logging -- optional event log records every message dispatch and reply
• Branching / fork -- fork world state at any point in the event log
• Replay -- re-dispatch a log against a world for deterministic reconstruction
• Persistence -- SaveBackend trait with MemoryBackend, Tee, Rolling; browser backends for localStorage and IndexedDB
• World diffing -- structural diff between world snapshots
• Scheduled messages -- schedule effect delivers messages at future ticks
• JSON serialization -- worlds round-trip through a versioned JSON format
• Interconnect adapter (defocus-interconnect crate) -- expose a world as an Interconnect authority

A defocus world consists of:

• Values -- null, bool, number, string, array, record, ref. Refs ({ $ref: id }) are capabilities pointing to other objects, optionally attenuated with $verbs.
• Objects -- identified by string IDs. Each has state (key-value), handlers (verb -> expression), an interface (list of verbs), children, and an optional prototype.
• Messages -- a verb string + a payload value, sent to an object ID.
• Evaluator -- walks expression ASTs, producing effects. Handlers receive self, sender, payload, and state bindings.
• Effects -- set state, send message, reply, spawn object, remove object, schedule future message.
• Event log -- append-only record of dispatched messages and their replies.
• Persistence -- composable backends: memory, tee (fan-out), rolling (N most recent snapshots), localStorage, IndexedDB.

Expressions are JSON values. An array with a string first element is a function call.

Effects are produced by ["perform", tag, ...] expressions.

• LambdaMOO -- the original object-message MUD substrate; defocus modernizes this model with structured rules, JSON serialization, and capability-based security.
• Lotus/Viwo -- the direct ancestor within this ecosystem; a persistent multiplayer MOO engine that was decomposed into ecosystem primitives, with defocus inheriting the world model.
• existence -- independently invented the text-as-rendering-layer architecture and observation-source/prose-compositor pattern that defocus adopts for its text output model.

TBD