millimeters-of-aluminum/GAME_DESIGN_DOCUMENT.md

Game Design Document: Project Millimeters of Aluminum (Working Title)

1. Game Vision & Concept

Project Millimeters of Aluminum is a third-person 3D spaceship simulation game that emphasizes realistic physics, deep ship management, and cooperative crew gameplay. Players take on roles as members of a multi-species crew aboard a modular, physically simulated spaceship.

The game's aesthetic is inspired by the functional, industrial look of real-world space hardware and sci-fi like The Expanse, focusing on diegetic interfaces and detailed, functional components. The core experience is about planning and executing complex maneuvers in a hazardous, procedurally generated star system, where understanding the ship's systems is as important as piloting skill.

The game's aesthetic is inspired by the technical, gritty, and high-contrast 2D style of games like Barotrauma, focusing on diegetic interfaces and detailed, functional components. The core experience is about planning and executing complex maneuvers in a hazardous, procedurally generated star system, where understanding the ship's systems is as important as piloting skill.

2. Core Gameplay Loop

The gameplay is centered around a Plan -> Execute -> Manage loop:

1. Plan: The crew uses the Navigation Computer to analyze their orbit and plan complex maneuvers, such as a Hohmann transfer to another planet. They must account for launch windows, fuel costs, and travel time.

2. Execute: The crew engages the autopilot or manually pilots the ship. The Helm executes the planned burns, performing precise, fuel-optimal rotations and main engine thrusts to alter the ship's trajectory.

3. Manage: While underway, the crew moves about the ship's 3D interior, manages modular systems, monitors resources, and responds to emergent events like hull breaches or system failures.

3. Key Features

1. Procedural Star System

The game world is a procedurally generated star system created by the StarSystemGenerator. Each system features a central star, a variable number of planets, moons, and asteroid belts, creating a unique environment for each playthrough.

2. N-Body Physics Simulation

Major bodies in orbit (CelestialBody class) are governed by a 3D n-body gravity simulation, managed by the OrbitalMechanics library. Objects inherit from a base OrbitalBody3D class, ensuring consistent physics. The simulation allows for complex and emergent orbital behaviors.

3. Modular Spaceship

The player's ship is not a monolithic entity but a collection of distinct, physically simulated components attached to a root Module node.

The Module class extends OrbitalBody3D and aggregates mass and inertia from all child Component and StructuralPiece nodes.

Ship logic is decentralized into data-driven "databanks," such as the HelmLogicShard and AutopilotShard.

Hardware, like a Thruster, is a 3D Component that applies force to the root Module.

4. Advanced Navigation Computer

This is the primary crew interface for long-range travel, presented as a diegetic 2D screen (SensorPanel) within the 3D world.

Maneuver Planning: The computer can calculate various orbital transfers, each with strategic trade-offs:

    Hohmann Transfer

    Brachistochrone (Torchship) Trajectory

Tactical Map: A fully interactive UI map featuring:

    Zoom-to-cursor and click-and-drag panning.

    Predictive orbital path drawing.

    Icon culling and detailed tooltips.

5. Physics-Based 3D Character Control

Character control is built on a robust, physics-based 3D system designed for complex zero-G environments.

Pawn/Controller Architecture: Player control is split between a PlayerController3D (which gathers hardware input and sends it via RPC) and a CharacterPawn3D (a CharacterBody3D that acts as the physics integrator).

Modular Movement: The pawn's movement logic is handled by component "brains." The ZeroGMovementComponent manages all zero-G interaction, while the EVAMovementComponent acts as a "dumb tool" providing thruster forces.

Physics-Based Gripping: Players can grab onto designated GripArea3D nodes. This is not an animation lock; a PD controller applies forces to the player's body to move them to the grip point and align them with its orientation.

Zero-G Traversal: The ZeroGMovementComponent features a state machine for IDLE (coasting), CLIMBING (moving between grips), REACHING (pending implementation), and CHARGING_LAUNCH (pushing off surfaces).

6. Runtime Component Design & Engineering

(This future-facing concept remains valid from the original design)

To move beyond pre-defined ship parts, the game will feature an in-game system for players to design, prototype, and manufacture their own components. This is achieved through a "Component Blueprint" architecture that separates a component's data definition from its physical form.

Component Blueprints: A ComponentBlueprint is a Resource file (.tres) that acts as a schematic.

Generic Template Scenes: The game will use a small number of generic, unconfigured "template" scenes (e.g., generic_thruster.tscn).

The Design Lab: Players will use a dedicated SystemStation to create and modify blueprints.

Networked Construction: A global ComponentFactory on the server will instantiate and configure components based on player-chosen blueprints, which are then replicated by the MultiplayerSpawner.

3. Modular Spaceship

The player's ship is not a monolithic entity but a collection of distinct, physically simulated components attached by joints. Key modules include:

• Spaceship: The main RigidBody3D hull that tracks overall mass, inertia, and health.
• Thruster: Self-contained RigidBody3D components that apply their own force. Their role (main engine, RCS, etc.) is an emergent property of their placement on the hull.
• ThrusterController: The "brains" of the ship's movement, featuring a sophisticated autopilot that can execute fuel-optimal "bang-coast-bang" rotational maneuvers and a PD controller for stable attitude hold.
• FuelSystem & LifeSupport: Centralized managers for resources and internal ship environment. Hull breaches can create thrust vectors from escaping atmosphere.
• On-board Sensors: Diegetic components like Accelerometers allow the crew to calibrate ship performance by test-firing thrusters and measuring the true physical output.

4. Advanced Navigation Computer

This is the primary crew interface for long-range travel.

• Maneuver Planning: The computer can calculate various orbital transfers, each with strategic trade-offs:
  • Hohmann Transfer: The most fuel-efficient route.
  • Fast Transfer: A quicker but more fuel-intensive option.
  • Brachistochrone (Torchship) Trajectory: For ships with high-efficiency engines like Ion Drives, enabling constant-thrust travel.
  • Gravity Assist: Planned for future implementation.
• Tactical Map: A fully interactive UI map that replaces custom drawing with instanced, clickable icons for all bodies. It features:
  • Zoom-to-cursor and click-and-drag panning.
  • Predictive orbital path drawing for all objects.
  • Icon culling at a distance to reduce clutter.
  • Custom hover effects and detailed tooltips with "sensor data."
  • A "picture-in-picture" SubViewport showing the ship's main camera view.

5. Multi-Species Crew (Player Classes)

Character progression is based on distinct species with physical advantages and disadvantages, rather than a point-based system.

• Humanoid: A generalist base class.

• Multi-armed Heavy: Can perform more tasks simultaneously but has higher mass, requiring more fuel for EVAs and special considerations during high-G burns.

• Hard Vacuum Monster: An EVA specialist that can cling to the hull but is vulnerable in pressurized environments.

• Ship AI: A non-physical class that interacts directly with ship systems at the cost of high power and heat generation.

6. Runtime Component Design & Engineering

To move beyond pre-defined ship parts, the game will feature an in-game system for players to design, prototype, and manufacture their own components. This is achieved through a "Component Blueprint" architecture that separates a component's data definition from its physical form.

• Component Blueprints: A ComponentBlueprint is a Resource file (.tres) that acts as a schematic. It contains metadata (name, description), a reference to a generic base scene (e.g., a "thruster chassis"), and a dictionary of overridden properties (e.g., {"thrust_force": 7500, "mass": 120}).

• Generic Template Scenes: Instead of dozens of unique component scenes, the game will use a small number of generic, unconfigured "template" scenes (e.g., generic_thruster.tscn, generic_power_plant.tscn). These scenes have scripts with exported variables that define their performance characteristics.

• The Design Lab: Players will use a dedicated SystemStation (the "Design Lab") to create and modify blueprints. This UI will dynamically generate controls (sliders, input fields) based on the exported variables of the selected template scene. Players can tweak parameters, balancing trade-offs like performance vs. resource cost, and save the result as a new blueprint resource in their personal data folder.

• Networked Construction: When a player builds an object in-game, they are selecting one of their saved blueprints.

  1. The client sends an RPC to the server with the path to the chosen ComponentBlueprint resource.
  2. The server validates the request and loads the blueprint. (This requires a system for syncing player-created blueprints to the server upon connection).
  3. A global ComponentFactory singleton on the server takes the blueprint, instantiates the correct generic template scene, and applies the blueprint's property overrides to the new instance.
  4. This fully-configured node is then passed to the MultiplayerSpawner, which replicates the object across the network, ensuring all clients see the correctly customized component.

4. Technical Overview

• Architecture: The project uses a decoupled, modular architecture. A GameManager handles global state, while ship systems are managed by ControlPanel and Databank resources loaded by a SystemStation.

• Key Scripts: -OrbitalBody3D.gd: The base class for all physical objects.

  • Module.gd: The central hub for a player ship, aggregating mass, inertia, and components.
  • HelmLogicShard.gd / AutopilotShard.gd: Databanks that contain the advanced autopilot and manual control logic.
  • SensorPanel.gd: A Control node that manages the interactive map UI.
  • CharacterPawn3D.gd / ZeroGMovementComponent.gd: Manages all third-person 3D physics-based character movement.

• Art Style: Aims for a functional, industrial 3D aesthetic. Character movement is physics-based using CharacterBody3D and Area3D grip detection. Ship interiors will be built from 3D modules and viewed from an over-the-shoulder camera.

5. Game Progression & Economy

This is the biggest area for potential expansion. A new section could detail how the player engages with the world and improves their situation over time.

1. The Core Objective:

What is the player's primary motivation? Is it pure sandbox exploration, or is there an overarching goal (e.g., paying off a debt, reaching a distant star, uncovering a mystery)? Defining this will help shape the rest of the progression systems.

2. Mission & Contract System: How do players get tasks?

1. Types:

Detail potential mission types (e.g., Cargo Hauling, Passenger Transport, Asteroid Surveying, Salvage Operations, Scientific Data Collection).

2. Sources:

Where do players find missions? (e.g., Station bulletin boards, faction representatives, distress signals).

3. Economy & Resources: How does the in-game economy function?

• Currency: What is the primary currency?
• Resource Management: Beyond fuel, what other resources are critical? (e.g., Spare Parts for repairs, Life Support supplies, Power Cells).
• Markets: Will there be dynamic markets at stations where players can buy low and sell high?

6. Emergent Events & Hazards

You mention "emergent events" in the gameplay loop. It would be beneficial to detail what these could be. This helps in planning the systems needed to trigger and manage them.

1. System Failures:

• Component Wear & Tear: Do ship modules degrade over time or from stress (e.g., high-G burns)? This would create a need for maintenance and repair gameplay.
• Power Grid Management: Could overloading the ship's reactor cause brownouts or damage to modules?

2. Environmental Hazards:

• Micrometeoroid Showers: Random events that can cause minor hull damage.
• Radiation Belts: Areas around planets that could interfere with sensors or harm the crew if the ship isn't properly shielded.
• Derelict Ships/Stations: Opportunities for exploration and salvage, but with potential dangers.

7. Crew Interaction & Ship Interior

Since co-op and crew management are central, detailing this aspect is crucial.

1. Ship Interior Management:

• Diegetic Interfaces: The crew will interact with systems from a third-person, over-the-shoulder perspective. They must be at a specific SystemStation to use its panels. Repairs will require a character to physically be at the damaged module.
• Atmospherics & Life Support: How is the ship's interior environment simulated? This will tie into the LifeSupport system.

2. Character States:

• Health & Injury: How are characters affected by hazards? Can they be injured in high-G maneuvers or from system failures?
• EVA (Extra-Vehicular Activity): This is a core feature. The EVAMovementComponent provides force-based thruster control for linear movement and roll torque. The ZeroGMovementComponent manages gripping, climbing, and launching from the ship's exterior and interior surfaces.
• Movement for the "Hard Vacuum Monster" species can be refined from a version of the reaching component where it can grab any nearby surface and can generate enough suction strength to remain attached to a moving object.