Core Concepts

Determinism

Determinism is the core principle of cruxOS. Given the same inputs, a world will always evolve in exactly the same way.

Why Determinism Matters

• Reproducibility — Run simulations again and get identical results
• Debugging — Replay exact scenarios to find bugs
• Verification — Prove outcomes are legitimate
• Sharing — Exchange seeds instead of entire state histories

Seeded Randomness

cruxOS uses a deterministic pseudo-random number generator (PRNG). The seed in your world metadata initializes this PRNG, ensuring "random" events are actually predictable given the seed.

// ❌ Non-deterministic
const value = Math.random();

// ✅ Deterministic
const value = vm.getRNG().next();

Worlds

A World is a self-contained simulation environment. It holds all state and rules needed to evolve over time.

World Components

metadata

Name, version, seed, tick rate, and configuration

initialState

Starting snapshot: agents, zones, fields, events, globals

rules

Logic that transforms state each tick

Agents

Agents are the primary entities in a world. They have positions, internal state, and respond to rules.

interface Agent {
  id: string;          // Unique identifier
  type: string;        // Agent type (e.g., "visitor", "bird")
  position: {         // Spatial location
    x: number;
    y: number;
    z?: number;
  };
  state: Record;       // Custom state (mood, energy, etc.)
  tags: string[];      // Classification tags
  inbox: Message[];    // Received messages
  outbox: Message[];   // Messages to send
}

Agent Communication

Agents communicate through messages. Each tick, the VM:

1. Processes rules (agents can add to outbox)
2. Delivers all outbox messages to recipients' inbox
3. Clears outboxes

Rules

Rules define how the world evolves. Each tick, rules are evaluated and actions are executed.

{
  "id": "rule_wander",
  "name": "Visitors wander around",
  "priority": 10,
  "selector": { "type": "visitor" },
  "condition": "energy >= 30",
  "action": "wander",
  "params": { "speed": 3 }
}

Rule Execution Flow

Selectors

Selectors determine which agents a rule applies to:

• type — Match by agent type
• tags — Match by tags (agent must have ALL specified)
• ids — Match by specific IDs

Conditions

Conditions are expressions evaluated against agent state. Supported operators: ==, !=, >, <, >=, <=, &&, ||

Ticks & Time

A tick is the smallest unit of simulation time. Each tick:

1. Clear previous tick's events
2. Execute all rules (sorted by priority)
3. Deliver messages (outbox → inbox)
4. Increment tick counter

Time Units

Gas (crx)

Every simulation consumes compute gas (crx). Gas measures computational work and prevents infinite loops.