space-game/docs/EVENTS.md

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?
• 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 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

  • defines the entities referenced by events

• UNIVERSE-MODEL.md

  • defines event scope by space layer

• ECONOMY.md

  • defines market and trade-related event domains

• PRODUCTION.md

  • defines recipe and production event domains

• COMBAT.md

  • defines combat and claim-related event domains