Guide

Getting Started

Build your first deterministic world in 5 minutes. No prior experience required.

What is cruxOS?

cruxOS is a Deterministic Simulation Operating System (DSIMOS). It allows you to create worlds with agents that follow rules, producing perfectly reproducible outcomes.

The Determinism Contract

same IR + same seed = same world evolution

This is the foundation of cruxOS. Every world is reproducible. Every outcome is traceable.

Core Concepts

Worlds — Simulation containers with agents, zones, and rules
Agents — Entities that exist and act within worlds
Rules — Logic that executes each tick
Ticks — The smallest unit of simulation time
IR — Intermediate Representation, the JSON format for worlds

Installation

Install the cruxOS CLI globally using npm or pnpm:

Terminal

# Using npm
npm install -g @cruxos/cli

# Using pnpm
pnpm add -g @cruxos/cli

# Verify installation
cruxos --version

You can also use cruxOS packages directly in your project:

Terminal

# Core packages
pnpm add @cruxos/ir @cruxos/vm

# Optional: Language compiler
pnpm add @cruxos/lang

Your First World

Let's create a simple world called "cloud-park" — a small park where visitors wander around and birds fly overhead.

Create the world file

Create a new file called world.json:

world.json

{
  "$schema": "cruxir/1.0",
  "metadata": {
    "name": "cloud-park",
    "version": "0.0.1",
    "description": "A small park in the clouds",
    "seed": 42,
    "tickRate": 1,
    "maxTicks": 100
  },
  "initialState": {
    "tick": 0,
    "agents": [
      {
        "id": "visitor_1",
        "type": "visitor",
        "position": { "x": 10, "y": 10 },
        "state": { "mood": "happy", "energy": 100 },
        "tags": ["human"]
      },
      {
        "id": "bird_1",
        "type": "bird",
        "position": { "x": 25, "y": 45 },
        "state": { "flying": true },
        "tags": ["animal", "flying"]
      }
    ],
    "zones": [
      {
        "id": "main_lawn",
        "type": "grass",
        "bounds": { "x": 0, "y": 0, "width": 100, "height": 60 },
        "properties": { "walkable": true }
      }
    ],
    "fields": [],
    "events": [],
    "globals": {
      "weather": "sunny",
      "time_of_day": "afternoon"
    }
  },
  "rules": [
    {
      "id": "rule_wander",
      "name": "Visitors wander",
      "priority": 10,
      "selector": { "type": "visitor" },
      "condition": "energy >= 30",
      "action": "wander",
      "params": { "speed": 3 }
    },
    {
      "id": "rule_bird_fly",
      "name": "Birds fly around",
      "priority": 5,
      "selector": { "type": "bird" },
      "action": "fly_random",
      "params": { "speed": 5, "maxX": 100, "maxY": 60 }
    }
  ]
}

Understanding the Structure

metadata: World configuration including name, seed (for determinism), and tick settings
initialState: Starting state with agents, zones, fields, events, and global variables
rules: Logic that executes each tick — selectors choose agents, conditions filter them, actions change state

Running the Simulation

Run your world using the CLI:

Terminal

# Run for 100 ticks (default)
cruxos run world.json

# Run for specific number of ticks
cruxos run world.json --ticks 50

Or programmatically with the VM package:

run.ts

import { readFileSync } from 'fs';
import { validate } from '@cruxos/ir';
import { CruxVM } from '@cruxos/vm';

// Load and validate
const ir = JSON.parse(readFileSync('world.json', 'utf-8'));
const { data } = validate(ir);

// Create VM and run
const vm = new CruxVM(data);
const result = vm.run(100);

console.log(`Ticks: ${result.ticksExecuted}`);
console.log(`Events: ${result.events.length}`);
console.log(`Agents:`, vm.getState().agents);

Understanding the Output

When you run a simulation, you'll see output like this:

Output

Loading world.json...

Running simulation for 100 ticks...

══════════════════════════════════════════════════
  Simulation Complete
══════════════════════════════════════════════════
  Ticks executed: 100
  Time: 12ms
  Ticks/sec: 8333.3

  Final State:
    Agents: 2
    Events this tick: 0

  Agent Positions:
    visitor_1: (45, 32)
    bird_1: (78, 15)

Determinism in Action

Run the same simulation again with the same seed — you'll get identical results. Change the seed, and the world evolves differently. This is the power of determinism.

Next Steps

📐

Core Concepts

Understand determinism, agents, and rules

→ 📝

cruxLang

Learn the world definition language

→ 🧬

cruxIR Schema

Deep dive into the IR specification

→