328 lines
7.4 KiB
Markdown
328 lines
7.4 KiB
Markdown
# 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?`
|
|
- `bubbleId?`
|
|
- `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`
|
|
- combat, docking, and claims belong to `local-space`
|
|
|
|
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-local-bubble`
|
|
- `left-local-bubble`
|
|
- `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
|
|
|
|
- [SPACES.md](/home/jbourdon/repos/space-game/docs/SPACES.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
|