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 top-down 2D spaceship simulation game that emphasizes realistic orbital mechanics, 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 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 Thruster Controller 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 manages the ship's modular systems, monitors resources like fuel and power, 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 goveerened by a simplified n-body gravity simulation. Physical objects with player interaction (ships, crew characters, detached components, and eventually stations) are governed by a realistic N-body gravitational simulation, managed by the OrbitalMechanics library. - Objects inherit from a base OrbitalBody2D class, ensuring consistent physics. - This allows for complex and emergent orbital behaviors, such as tidal forces and stable elliptical orbits.

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 RigidBody2D hull that tracks overall mass, inertia, and health.
• Thruster: Self-contained RigidBody2D 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.

4. Technical Overview

• Architecture: The project uses a decoupled, modular architecture heavily reliant on a global SignalBus for inter-scene communication and a GameManager for global state. Ships feature their own local ShipSignalBus for internal component communication.

• Key Scripts:

  • OrbitalBody2D.gd: The base class for all physical objects.
  • Spaceship.gd: The central hub for a player ship.
  • Thruster.gd: A self-contained, physically simulated thruster component.
  • ThrusterController.gd: Contains advanced autopilot and manual control logic (PD controller, bang-coast-bang maneuvers).
  • NavigationComputer.gd: Manages the UI and high-level maneuver planning.
  • MapDrawer.gd: A Control node that manages the interactive map UI.
  • MapIcon.gd: The reusable UI component for map objects.

• Art Style: Aims for a Barotraumainspired aesthetic using 2D ragdolls (Skeleton2D, PinJoint2D), detailed sprites with normal maps, and high-contrast dynamic lighting (PointLight2D, LightOccluder2D).

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: You mention this in the vision. It's worth specifying how the crew will interact with systems. Will they need to be at a specific console (like the Navigation Computer) to use it? Do repairs require a character to physically be at the damaged module?
• Atmospherics & Life Support: How is the ship's interior environment simulated? Will fires or toxic gas leaks be a possibility? This ties directly into your 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): Detail the mechanics for EVAs. What equipment is needed? How is movement handled in zero-G? This would be a perfect role for the "Hard Vacuum Monster" species.