space-game/docs/MODULES.md

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.

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 for the item-side vocabulary. See 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

  • station growth and services

• SHIPS.md

  • ship capabilities and specialization

• ITEMS.md

  • goods consumed or enabled by modules

• WORKFORCE.md

  • workforce and habitat interaction

• ECONOMY.md

  • market demand created by module construction and operation

• PRODUCTION.md

  • recipes executed by production-capable modules