WSC Effects System

WSC Effects System

The effects system applies chronicle events to world state. When an event is emitted, its effects are applied deterministically to modify entity attributes.

How It Works

Event Emitted → Effects Handler → Entity Updates
     ↓              ↓                   ↓
  battle.resolved → applyBattleEffects → force.strength reduced

Commands

Apply Effects for an Event

# Apply effects for a specific event
npx tsx .claude/​skills/​wsc-effects/​scripts/​apply.ts evt_10492

# Apply effects for all pending events
npx tsx .claude/​skills/​wsc-effects/​scripts/​apply.ts --pending

# Dry run (show what would change)
npx tsx .claude/​skills/​wsc-effects/​scripts/​apply.ts evt_10492 --dry-run

List Effect Handlers

npx tsx .claude/​skills/​wsc-effects/​scripts/​apply.ts --list-handlers

Effect Handlers

Each event type has a handler that knows how to apply its effects:

Conflict Events

Influence Events

Agent Events

Governance Events

Settlement Events

Effect Application Rules

1. Idempotency: Effects are designed to be safely re-applied
2. Validation: Effects check entity exists before modifying
3. Bounds: Numeric values are clamped to valid ranges (0-1 for normalized)
4. Logging: All changes are logged for debugging

Example: Battle Effects

For event battle.resolved:

{
  "id": "evt_10492",
  "type": "battle.resolved",
  "who": ["force.7th_fleet", "force.raiders"],
  "data": {
    "outcome": "raider_victory",
    "losses": {
      "7th_fleet": { "strength_before": 0.75, "strength_after": 0.50 },
      "raiders": { "strength_before": 0.25, "strength_after": 0.20 }
    }
  }
}

Effects applied:

• force.7th_fleet.attrs.strength → 0.50
• force.raiders.attrs.strength → 0.20

Adding New Handlers

Handlers are defined in scripts/​handlers.ts. To add a new handler:

export const handlers: EffectHandlers = {
  'my_event.type': (event, world) => {
    // Find relevant entities
    const entity = world.getEntity(event.who[0]);

    // Apply changes
    entity.attrs.value = event.data.newValue;

    // Save
    world.saveEntity(entity);

    return { modified: [entity.id] };
  },
};

Integration

The effects system is typically called automatically by the orchestrator after events are emitted:

1. Agent emits event via wsc-chronicle
2. Orchestrator calls wsc-effects to apply
3. Entities are updated
4. Next tick proceeds