Reference

cruxIR Schema

The Intermediate Representation format for deterministic world definitions.

Overview

cruxIR (Intermediate Representation) is the JSON format used to define worlds in cruxOS. It's the compiled output from cruxLang and the input to cruxVM.

cruxLang .crux

→

cruxIR .cxir / .json

→

cruxVM runtime

You can write cruxIR directly in JSON or compile from cruxLang. The schema is validated using Zod for type safety.

CruxIR

The root object containing the complete world definition.

TypeScript Definition

interface CruxIR {
  $schema: "cruxir/1.0";    // Schema version
  metadata: Metadata;       // World configuration
  initialState: WorldState; // Starting state
  rules: Rule[];            // Simulation logic
}

JSON Example

{
  "$schema": "cruxir/1.0",
  "metadata": {
    "name": "my-world",
    "version": "1.0.0",
    "seed": 42
  },
  "initialState": {
    "tick": 0,
    "agents": [],
    "zones": [],
    "fields": [],
    "events": [],
    "globals": {}
  },
  "rules": []
}

Metadata

World configuration and identity.

TypeScript Definition

interface Metadata {
  name: string;              // World name
  version: string;           // Semantic version
  description?: string;      // Optional description
  author?: string;           // Optional author
  seed: number;              // RNG seed (default: 0)
  tickRate: number;          // Ticks per second (default: 1)
  maxTicks?: number;         // Maximum simulation length
  createdAt?: number;        // Unix timestamp (ms)
  identity?: VisualIdentity; // Visual DNA
}

Visual Identity

Each world can have a deterministic visual identity generated from its seed. This ensures worlds have consistent visual branding.

VisualIdentity

interface VisualIdentity {
  hue: number;        // 0-360, primary color
  saturation: number; // 0-100, color intensity
  lightness: number;  // 0-100, brightness
  cornerStyle: "flourish" | "tech" | "geometric" | "minimal";
  patternSeed: number; // For generating sigils
}

WorldState

Complete snapshot of the world at a point in time.

TypeScript Definition

interface WorldState {
  tick: number;                      // Current tick
  agents: Agent[];                   // All agents
  zones: Zone[];                     // Spatial zones
  fields: Field[];                   // Scalar/vector fields
  events: Event[];                   // Events this tick
  globals: Record<string, unknown>; // Global variables
}

Agent

An entity that exists and acts within the world.

TypeScript Definition

interface Agent {
  id: string;                        // Unique identifier
  type: string;                      // Agent type
  position: Position;                // Spatial location
  state: Record<string, unknown>;   // Custom state
  tags: string[];                    // Classification tags
  inbox: Message[];                  // Received messages
  outbox: Message[];                 // Pending messages
  inboxLimit: number;                // Max inbox size (default: 100)
}

interface Position {
  x: number;
  y: number;
  z?: number; // Default: 0
}

JSON Example

{
  "id": "visitor_1",
  "type": "visitor",
  "position": { "x": 10, "y": 20 },
  "state": {
    "mood": "happy",
    "energy": 100
  },
  "tags": ["human", "adult"]
}

Messages

Agents communicate via typed messages.

Message

interface Message {
  from: string;                      // Sender ID
  to: string;                        // Recipient ID
  type: string;                      // Message type
  payload: Record<string, unknown>; // Message data
  tick: number;                      // Tick sent
}

Zone

A spatial region with properties.

TypeScript Definition

interface Zone {
  id: string;
  type: string;
  bounds: {
    x: number;
    y: number;
    z?: number;
    width: number;
    height: number;
  };
  properties: Record<string, unknown>;
}

JSON Example

{
  "id": "spawn_area",
  "type": "spawn",
  "bounds": {
    "x": 0, "y": 0,
    "width": 100, "height": 100
  },
  "properties": {
    "maxAgents": 10,
    "spawnRate": 0.1
  }
}

Rule

Logic that executes each tick against selected agents.

TypeScript Definition

interface Rule {
  id: string;                       // Unique identifier
  name: string;                     // Human-readable name
  priority: number;                 // Execution order (higher first)
  selector?: Selector;              // Which agents
  condition?: string;               // When to execute
  action: string;                   // What to do
  params: Record<string, unknown>; // Action parameters
}

interface Selector {
  type?: string;      // Match by type
  tags?: string[];    // Match by tags (all must match)
  ids?: string[];     // Match by specific IDs
}

JSON Example

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

Built-in Actions

Action	Description	Parameters
`wander`	Random movement	`speed`
`move_toward`	Move to target	`target`, `speed`
`set_state`	Update agent state	Any key-value pairs
`deplete_energy`	Reduce energy	`amount`
`rest`	Recover energy	`recovery`
`fly_random`	Random flight	`speed`, `maxX`, `maxY`

Event

Record of something that happened in the world.

TypeScript Definition

interface Event {
  id: string;                        // Unique identifier
  type: string;                      // Event type
  tick: number;                      // When it happened
  source?: string;                   // Originating agent
  target?: string;                   // Target agent
  data: Record<string, unknown>;    // Event data
}

Event Lifecycle

Events are cleared at the start of each tick. They represent what happened during a tick and are available for inspection immediately after.

Next Steps

⚙️

cruxVM Runtime

Learn how the runtime executes worlds

→ 🔧

@cruxos/ir API

Full API reference for the IR package

→