wsc-world-state

Initialize and manage WSC world state. Use when creating a new world, loading world state, advancing simulation ticks, or checking world status.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

When & Why to Use This Skill

The wsc-world-state skill is a specialized infrastructure tool designed to initialize and manage complex simulation environments. It provides a robust framework for separating read-only scenario templates from mutable runtime world instances, allowing for persistent state tracking, time-based progression (ticks), and detailed entity management. This skill is essential for developers and researchers building agentic systems that require a consistent, evolving, and queryable 'world' context.

Use Cases

  • Game Development and Narrative Design: Create and manage multiple persistent game worlds with distinct genres (e.g., sci-fi, fantasy), allowing for complex story progression and state saving.
  • Agent Environment Orchestration: Provide a structured environment for AI agents to interact with, where the world state evolves based on agent actions and automated time ticks.
  • Simulation Branching and Testing: Initialize multiple world instances from the same scenario template to test different AI behaviors or event outcomes in parallel.
  • Temporal State Tracking: Advance simulation time using a flexible 'tick' system to model long-term consequences in continental, galactic, or scene-level simulations.
  • World Status Monitoring: Retrieve real-time snapshots of the active world, including entity counts, recent event chronicles, and location-specific metadata.
namewsc-world-state
descriptionInitialize and manage WSC world state. Use when creating a new world, loading world state, advancing simulation ticks, or checking world status.
allowed-toolsRead, Write, Bash, Glob

WSC World State Management

Manage world instances including creation, switching, tick advancement, and status checking.

Architecture

WSC separates scenarios (templates) from worlds (runtime instances):

src/
├── scenarios/              # Scenario TEMPLATES (read-only)
│   ├── scenarios.json      # Available scenarios
│   ├── vega_conflict/      # Sci-fi scenario
│   │   ├── scenario.json
│   │   ├── entities/
│   │   ├── locations/
│   │   └── rules/
│   └── shattered_realms/   # Fantasy scenario
│       └── ...
└── worlds/                 # RUNTIME instances (mutable)
    ├── worlds.json         # Registry of world instances
    ├── vega_conflict_001/  # First Vega playthrough
    │   ├── state.json
    │   ├── chronicle.ndjson
    │   ├── entities/
    │   └── locations/
    └── shattered_realms_001/
        └── ...

Commands

Create New World

# Create from default scenario
npx tsx .claude/skills/wsc-world-state/scripts/init.ts

# Create from specific scenario
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --scenario shattered_realms

# Create with custom name
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --scenario vega_conflict --name "My Campaign"

# Create with specific ID
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --scenario vega_conflict --id my_vega_game

# Create empty world
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --empty

List Available

# List scenarios (templates)
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --list

# List world instances (saves)
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --list-worlds

Switch Worlds

# Switch to a different world instance
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --switch vega_conflict_002

Delete World

# Delete a world instance
npx tsx .claude/skills/wsc-world-state/scripts/init.ts --delete vega_conflict_001

Check World Status

npx tsx .claude/skills/wsc-world-state/scripts/status.ts

Shows:

  • Active world ID
  • Current tick
  • Entity counts by type
  • Recent events
  • World settings

Advance Tick

# Advance by 1 tick
npx tsx .claude/skills/wsc-world-state/scripts/tick.ts

# Advance by N ticks
npx tsx .claude/skills/wsc-world-state/scripts/tick.ts --count 5

# Advance to specific tick
npx tsx .claude/skills/wsc-world-state/scripts/tick.ts --to 1050

World Instance Structure

Each world instance contains:

worlds/{world_id}/
├── state.json          # World metadata (tick, settings)
├── chronicle.ndjson    # Append-only event log
├── entities/           # Current entity states
│   ├── polity.*.json
│   ├── agent.*.json
│   └── ...
└── locations/          # Location map files
    ├── world.*.json
    ├── region.*.json
    └── locale.*.json

State File Format

{
  "tick": 1000,
  "last_event_id": 10500,
  "active_scenario": "vega_conflict",
  "drill_down_opportunities": [],
  "active_conflicts": [],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T12:30:00Z",
  "settings": {
    "name": "The Vega Conflict",
    "genre": "sci-fi"
  }
}

Worlds Registry Format

The worlds/worlds.json file tracks all instances:

{
  "active_world": "vega_conflict_001",
  "worlds": {
    "vega_conflict_001": {
      "scenario": "vega_conflict",
      "name": "The Vega Conflict",
      "created_at": "2024-01-15T10:00:00Z",
      "last_played": "2024-01-15T12:30:00Z"
    },
    "shattered_realms_001": {
      "scenario": "shattered_realms",
      "name": "The Shattered Realms",
      "created_at": "2024-01-16T08:00:00Z",
      "last_played": "2024-01-16T09:00:00Z"
    }
  }
}

Tick Semantics

The tick value represents world time. Its meaning depends on the genre:

Genre Tick Unit Example
Galactic Days tick 1000 = Day 1000
Continental Seasons tick 100 = 25th year
City Weeks tick 52 = 1 year
Scene Minutes tick 60 = 1 hour

Integration with Agents

Agents read world state to understand context and emit events that modify it:

  1. Orchestrator reads state.json to get current tick and active world
  2. Orchestrator queries entities relevant to current lens
  3. Agent simulates and emits events
  4. Events are applied via wsc-effects skill
  5. Tick advances

File Locations

All paths automatically resolve to the active world:

  • Active world: src/worlds/{active_world}/
  • World state: src/worlds/{active_world}/state.json
  • Entities: src/worlds/{active_world}/entities/
  • Locations: src/worlds/{active_world}/locations/
  • Chronicle: src/worlds/{active_world}/chronicle.ndjson
  • Scenarios: src/scenarios/