# Modules This document defines the intended module model for ships and stations. Modules are the primary way ships and stations gain capability. They determine what an entity can do, what goods it can handle, what services it can provide, and how much workforce or support it requires. ## Design Goals The module system should support: - X4-style composable stations - role-defined ships without excessive hardcoding - meaningful logistics and infrastructure requirements - clear capability gating - future expansion without changing the basic architecture ## Core Principles - ships and stations gain most capabilities through modules - modules should define function, not just stats - modules should have real operational requirements - modules should interact with workforce, items, and command logic - a hull or station frame without the right modules should be meaningfully limited ## Module Ownership Modules belong to either: - ships - stations Some module categories conceptually exist on both, but their use may differ. Examples: - storage - habitat - power-related modules ## Capability Gating Modules should gate real gameplay abilities. Examples: - no docking module means no docking service - no habitat module means no population growth or human transport - no refinery module means no refining - no fuel-processing module means no gas-to-fuel conversion - no storage module means reduced or absent inventory capability - no shipyard-related module means no ship production This should remain a core rule of the simulation. ## Ship Modules Ship modules define what a ship can do. Likely ship-side categories include: - reactor or power generation - capacitor or energy buffer - thruster package later if separated - warp-capable propulsion support later if needed - FTL capability where applicable - cargo storage - habitat for human transport - livestock transport - mining equipment - gas harvesting equipment - weapons - support or utility systems later Ship identity should be influenced by: - hull class - fitted modules - commander behavior Not every industrial role needs a distinct hardcoded hull if modules can express the difference clearly enough. ## Station Modules Station modules define what a station can do. Likely station-side categories include: - power generation - docking - storage - habitat - refinery - fuel processing - manufacturing - shipyard or construction support - defense - trade or logistics support later - livestock or food-chain support later Station identity should largely come from module composition. This is especially important because your station model is configuration-based rather than having every station type be a wholly separate structure class. ## Structural Rule Stations are built at one Lagrange point and expanded by adding modules. That means modules are the main axis of station growth. A station does not sprawl across multiple sites. ## Module Categories For design purposes, modules can be grouped into a few major classes: 1. structural modules 2. operational modules 3. production modules 4. logistics modules 5. population modules 6. military modules ### Structural Modules These define physical expansion and attachment capacity. Examples: - core station body - structural extensions - future hardpoint or attachment frames ### Operational Modules These keep the entity functioning. Examples: - reactor - capacitor - station power core - fuel systems ### Production Modules These convert goods into other goods or into built output. Examples: - refinery - fuel processor - factory - shipyard support ### Logistics Modules These let an entity store, receive, and move goods or people. Examples: - cargo storage - docking bay - transfer systems later - habitat transport support - livestock handling ### Population Modules These support humans and long-term station staffing. Examples: - habitat - civilian support modules later Population modules are especially important because they connect stations to [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md). ### Military Modules These allow defense and force projection. Examples: - turrets - missile systems later - shield or defensive utility later - station defense platforms as module sets ## Module Requirements Modules should not be treated as free magic unlocks. They may require: - construction materials - build time - power - workforce - fuel or energy inputs - docking or logistics support This should let stations and ships fail in believable ways when underbuilt or undersupplied. ## Workforce Interaction Modules should interact with workforce through a simple rule at first: - every module contributes to the station's workforce requirement - workforce satisfaction scales module effectiveness equally That keeps the first model simple while preserving the idea that bigger stations need more people. ## Item Interaction Modules should define which item flows an entity can participate in. Examples: - a habitat module enables population support - a fuel-processing module consumes gas and produces fuel - a refinery consumes raw resources and produces processed goods - a storage module determines what volume or class of goods can be held - a livestock module participates in the food chain See [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) for the item-side vocabulary. See [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) for the recipe-side model. ## Construction And Module Demand Module construction should use the same economic logic as station construction more broadly. That means: - module builds consume real goods - construction storage can publish demand - expansion creates burst economic pressure This keeps station growth tied to the market rather than detached from it. ## Operational Failure Modules should help determine failure modes. Examples: - no power means operational modules fail - no docking module means the station cannot offer docking service - no habitat means no local population growth - no storage means goods handling becomes impossible or severely constrained This helps capability loss emerge from the world state instead of from arbitrary toggles. ## Fitting Philosophy The intended philosophy should be: - hulls and station frames define limits - modules define capabilities That means the simulation should avoid making every role a unique special-case entity if a module composition can express it more cleanly. ## Minimum Rules The following rules should remain true unless deliberately revised: - modules gate real capabilities - stations grow by module addition at one location - ships depend on fitted modules for specialized roles - modules consume real construction goods - modules interact with workforce and power - habitat modules are required for population support or human transport - storage and logistics modules matter for market participation ## Relationship To Other Documents - [STATIONS.md](/home/jbourdon/repos/space-game/docs/STATIONS.md) - station growth and services - [SHIPS.md](/home/jbourdon/repos/space-game/docs/SHIPS.md) - ship capabilities and specialization - [ITEMS.md](/home/jbourdon/repos/space-game/docs/ITEMS.md) - goods consumed or enabled by modules - [WORKFORCE.md](/home/jbourdon/repos/space-game/docs/WORKFORCE.md) - workforce and habitat interaction - [ECONOMY.md](/home/jbourdon/repos/space-game/docs/ECONOMY.md) - market demand created by module construction and operation - [PRODUCTION.md](/home/jbourdon/repos/space-game/docs/PRODUCTION.md) - recipes executed by production-capable modules