docs: establish official design documentation
This commit is contained in:
328
docs/EVENTS.md
Normal file
328
docs/EVENTS.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# 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`
|
||||
- `Station buy order for fuel opened`
|
||||
- `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
|
||||
Reference in New Issue
Block a user