# Events

This document defines the intended event model for the simulation.

Events are the explicit record of meaningful changes in the world.

They should support gameplay logic, debugging, UI presentation, replication, and future persistence.

## Design Goals

The event model should support:

- clear lifecycle visibility
- replayable and inspectable world changes
- useful observer replication
- commander and player feedback
- debugging without relying on implicit state diffs only

## Core Principles

- important world changes should emit explicit events
- events should reference stable entity IDs
- events should be typed, not only free-form text
- events should be useful for both machines and humans
- event detail should vary by space layer and relevance

## Event Structure

Every event should conceptually have:

- `eventId`
- `sequence`
- `occurredAt`
- `kind`
- `spaceLayer`
- `systemId?`
- `localspaceId?`
- `anchorId?`
- `primaryEntityKind`
- `primaryEntityId`
- `relatedEntityIds`
- `payload`
- `humanSummary`

This preserves both programmatic utility and debug readability.

## Event Scope

Events should naturally inherit spatial scope from the world model.

Examples:

- universe-scale events belong to `universe-space`
- strategic system events belong to `galaxy-space` or `system-space`
- local tactical events belong to `localspace`

This is important for interest management.

## Event Families

The major event families should be:

1. lifecycle events
2. movement events
3. market events
4. production events
5. construction events
6. population events
7. policy events
8. combat events
9. commander events
10. replication/system events

## Lifecycle Events

These describe entity creation, destruction, and state milestones.

Examples:

- `ship-created`
- `ship-destroyed`
- `station-founded`
- `station-destroyed`
- `claim-placed`
- `claim-destroyed`
- `construction-started`
- `construction-completed`
- `commander-created`
- `commander-killed`

These are especially important because entity lifecycles should not be inferred only from snapshots.

## Movement Events

These describe meaningful transitions in movement regime or location context.

Examples:

- `entered-localspace`
- `left-localspace`
- `warp-spooling-started`
- `warp-started`
- `warp-arrived`
- `stargate-transit-started`
- `ftl-transit-started`
- `dock-requested`
- `dock-granted`
- `dock-denied`
- `docked`
- `undocked`

Movement events should capture transitions, not every tiny positional change.

## Market Events

These describe market intent and fulfillment.

Examples:

- `buy-order-opened`
- `buy-order-updated`
- `buy-order-filled`
- `buy-order-cancelled`
- `sell-order-opened`
- `sell-order-updated`
- `sell-order-filled`
- `sell-order-cancelled`
- `trade-delivered`
- `trade-rejected`

These events are useful for:

- economic debugging
- UI history
- future analytics

## Production Events

These describe recipe and processing state.

Examples:

- `recipe-started`
- `recipe-blocked-no-input`
- `recipe-blocked-no-power`
- `recipe-completed`
- `production-stalled-output-full`

Production events should explain why stations are or are not producing.

## Construction Events

These describe founding, module expansion, and build progress.

Examples:

- `claim-activation-started`
- `claim-activated`
- `construction-storage-created`
- `construction-material-delivered`
- `construction-progressed`
- `module-construction-started`
- `module-construction-completed`
- `station-construction-completed`

Construction events are especially important because claims and building are contestable.

## Population Events

These describe demographic and workforce changes.

Examples:

- `population-grew`
- `population-transferred`
- `population-arrived`
- `population-loss-food`
- `population-loss-water`
- `population-loss-energy`
- `commander-generated`

These help explain why a station's efficiency is changing.

## Policy Events

These describe access and restriction changes.

Examples:

- `trade-policy-changed`
- `docking-policy-changed`
- `construction-policy-changed`
- `range-policy-changed`

These are useful because policy changes alter behavior without directly changing physical state.

## Combat Events

These describe tactical engagement and destruction.

Examples:

- `combat-started`
- `target-acquired`
- `under-attack`
- `claim-attacked`
- `construction-site-attacked`
- `ship-damaged`
- `ship-destroyed`
- `station-damaged`
- `station-defense-engaged`
- `pirate-raid-detected`
- `retreat-started`

Combat events should favor meaningful state changes over weapon-by-weapon spam.

## Commander Events

These describe decision-level changes by AI authority.

Examples:

- `commander-created`
- `commander-assigned`
- `commander-killed`
- `goal-changed`
- `doctrine-changed`
- `priority-changed`
- `support-requested`

These make it easier to understand why entities changed behavior.

Task and order transition events should also exist as a first-class part of the event model.

Examples:

- `order-accepted`
- `order-cancelled`
- `task-started`
- `task-blocked`
- `task-completed`
- `task-failed`
- `behavior-changed`

See [TASKS.md](/home/jbourdon/repos/space-game/docs/TASKS.md) for the planner and execution model behind these transitions.

## Replication And System Events

These describe transport-level or observer-level system changes.

Examples:

- `snapshot-issued`
- `delta-issued`
- `observer-scope-changed`
- `requires-refresh`

These may remain more internal than gameplay-facing, but they still benefit from consistent typing.

## Event Visibility

Not every observer needs every event.

The intended rule should be:

- high-layer events are broad and low-detail
- low-layer events are narrow and high-detail

Examples:

- a local viewer should see nearby combat and docking events
- a system viewer should see claim and station progress events
- a galaxy viewer may only need summarized strategic events

## Event Retention

The runtime may not keep full history forever, but events should still be designed as if they are useful beyond one frame.

Useful retention targets:

- short-term debug history
- player-facing notifications
- recent replication catch-up
- future persistence or replay systems

## Human Summary

Every event should be capable of producing a concise human-readable summary.

Example style:

- `Claim at Helios IV L4 destroyed by pirates`
- `Miner completed warp to refinery node`

This helps reuse the same event model for:

- logs
- notifications
- debug panels
- event history UI

## Minimum Rules

The following rules should remain true unless deliberately revised:

- important world changes emit typed events
- events reference stable entity IDs
- events carry enough scope for interest management
- events should support both machine use and human summaries
- lifecycle events should not rely only on snapshot inference
- local combat and construction conflict should be explicitly represented

## Relationship To Other Documents

- [DATA-MODEL.md](/home/jbourdon/repos/space-game/docs/DATA-MODEL.md)
  - defines the entities referenced by events

- [UNIVERSE-MODEL.md](/home/jbourdon/repos/space-game/docs/UNIVERSE-MODEL.md)
  - defines event scope by space layer

- [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md)
  - defines market and trade-related event domains

- [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md)
  - defines recipe and production event domains

- [COMBAT.md](/home/jbourdon/repos/space-game/docs/COMBAT.md)
  - defines combat and claim-related event domains