Skip to main content

Moonlander Architecture

System Overview

Moonlander is structured as a modular spacecraft simulation platform with clearly separated frontend, backend, configuration, control, physics, propulsion, and telemetry layers. The architecture is designed to support ongoing development from the current three-dimensional translational simulation toward future 6-DOF spacecraft dynamics.

The system separates user interaction, command generation, propulsion modeling, numerical state propagation, and telemetry output. This allows individual components to be extended or replaced without restructuring the complete simulation framework.

Moonlander system architecture and data flow diagram

Component Descriptions

  • Frontend / Cockpit: Qt-based user interface for telemetry display, spacecraft selection, cockpit visualization, and manual operator interaction.
  • InputMapper: Frontend-side input processing component that maps keyboard input, and later controller input, into structured flight commands for main engine and RCS control.
  • SimulationWorker: Dedicated worker-thread component that executes simulation steps outside the UI thread and provides safe data exchange between frontend and backend.
  • SimControl: Central simulation coordinator responsible for simulation flow, command forwarding, parameter validation, and interaction with the spacecraft object.
  • Backend / Simulation Core: C++ simulation layer for physics, propulsion, control, state propagation, telemetry generation, and future research-oriented model extensions.
  • Spacecraft: Owns the physical spacecraft state, including position, velocity, mass properties, propulsion state, and dynamic quantities required for force-based simulation.
  • Physics and Integrators: Modular interfaces and implementations for force modeling and numerical propagation, including IPhysicsModel, BasicMoonGravity, Physics, IIntegrator, and EulerIntegrator.
  • Control and Automation: Includes manual command arbitration, controller interfaces, PD-based velocity control, and the Adaptive Descent Controller for automated landing guidance.
  • Propulsion: Multi-engine propulsion architecture based on a central Thrust Orchestrator, engine-specific models, thrust states, fuel tanks, and vectorized thrust aggregation.
  • Configuration / JSON: External spacecraft and simulation configuration layer for mass properties, tanks, engines, initial states, and simulation parameters.
  • Backend Structs: Standardized data containers for state vectors, spacecraft state, simulation output, engine states, fuel tanks, and environment configuration.
  • Logger: Backend logging component that captures diagnostic output independently of the user interface.

Physics Architecture

The physics architecture is centered around a modular Physics orchestrator. This component coordinates physics models, integrators, controller outputs, autopilot logic, and sensor feedback without embedding all physical models directly into a single monolithic class.

The current model scope focuses on three-dimensional translational spacecraft dynamics. Rotational dynamics and full rigid-body 6-DOF propagation are planned future extensions.

Moonlander physics architecture diagram

Key Components and Relationships

  • Physics Orchestrator: Central coordination layer for physics-related simulation tasks. It delegates computations to the active physics model, integrator, control modules, and sensor components.
  • IPhysicsModel: Abstract interface for physical force models. Concrete implementations can be exchanged to represent different environmental or force-model assumptions.
  • BasicMoonGravity: Current lunar gravity model used to compute gravitational acceleration acting on the spacecraft.
  • IIntegrator: Abstract numerical integration interface used to propagate the spacecraft state over time.
  • EulerIntegrator: Current integration implementation for discrete-time propagation of the translational spacecraft state.
  • IController: Interface for feedback control modules that compute control commands from the current spacecraft state.
  • PD Controller: Velocity-control component used to track target velocities with gravity compensation and thrust-limit handling.
  • IAutopilot: Interface for automated guidance and control logic.
  • Adaptive Descent Controller: Energy-based landing controller using brake-ratio-guided mode switching for phase-dependent descent behavior.
  • BasicRCSControlModel: Planned RCS control model responsible for translating RCS-related flight commands into suitable thruster commands. This component is currently under construction and will provide the control connection between commanded translational inputs and RCS engine behavior.
  • ISensor / SensorModel: Sensor abstraction and implementation used to compute telemetry quantities such as g-load and provide feedback to higher-level control logic.

Flow Summary

  • The Physics orchestrator receives the current spacecraft state and active commands.
  • Physics models compute environmental forces such as lunar gravity.
  • Controllers and automation modules compute guidance or control commands.
  • The BasicRCSControlModel will map RCS commands to thruster-level behavior once completed.
  • The propulsion layer provides thrust forces to the dynamics model.
  • The integrator advances the spacecraft state in discrete simulation steps.
  • Sensors compute feedback and telemetry for control and visualization.

This structure supports systematic model development by separating physical assumptions, numerical propagation, control logic, and sensor feedback into independent components.

Propulsion Architecture

The propulsion subsystem has been refactored into a modular Thrust Orchestrator architecture. Instead of treating propulsion as a single scalar output, the system now supports multiple engines, multiple tanks, engine-specific state handling, and vectorized thrust representation.

This design allows the main engine and RCS thrusters to be modeled separately, while still exposing a unified thrust interface to the spacecraft dynamics.

Moonlander propulsion and thrust architecture diagram

Key Components and Relationships

  • Thrust Orchestrator: Central propulsion manager of the spacecraft. It coordinates registered engine models, forwards commands, updates engine states, manages fuel usage, and aggregates individual engine outputs into a resulting thrust vector.
  • IThrustModel: Abstract interface for propulsion models. It defines common behavior such as command handling, thrust-state update, fuel-consumption calculation, and thrust-output access.
  • BasicMainEngineModel: Concrete main engine implementation. It models scalar thrust magnitude, target tracking, response dynamics, and fuel consumption based on the configured engine parameters.
  • BasicRCSModel: Planned RCS thruster model for discrete, vector-based translational control. The model will represent RCS behavior separately from the main engine and is intended to support future extensions toward attitude and 6-DOF modeling.
  • EngineConfig: Static configuration data for each engine, including identifier, name, type, controlled axis, tank assignment, maximum thrust, specific impulse, response parameters, thrust direction, and mounting position.
  • EngineType: Type-safe selector used to query either the total propulsion output or a specific subsystem such as the main engine or RCS.
  • ME_ThrustState: Dynamic main engine state. The primary thrust quantity is represented as a scalar magnitude, while the engine direction is handled separately to derive a physical thrust vector.
  • RCS_ThrustState: Dynamic RCS state. RCS commands and thrust quantities are represented as Vector3 values because translational RCS control acts along multiple axes.
  • FuelTank: Static and dynamic tank representation used to assign fuel resources to propulsion models and track remaining fuel mass.
  • FuelState: Runtime fuel data used to calculate and apply engine-specific mass flow during simulation.

Flow Summary

  • The JSON spacecraft configuration defines engines, tanks, directions, positions, and engine-to-tank assignments.
  • The Thrust Orchestrator initializes propulsion models from the provided EngineConfig objects.
  • Main engine and RCS commands are received through separate command paths.
  • The main engine model updates scalar thrust magnitude using its response model.
  • The RCS model receives vector-based commands for translational control.
  • Each engine model computes thrust output and fuel consumption according to its own state and configuration.
  • The Thrust Orchestrator aggregates individual thrust contributions into a total thrust vector.
  • The resulting propulsion force is passed to the spacecraft dynamics model.

The propulsion layer explicitly separates configuration, command input, dynamic state, actuator behavior, and physical thrust output. This makes the subsystem extensible, testable, and suitable for future research-oriented propulsion and control experiments.

Command and Input Flow

Manual control input is processed separately from the physical propulsion models. The frontend InputMapper converts operator input into structured flight commands, while backend components decide how those commands affect engine states and spacecraft dynamics.

Current Command Path

  • Keyboard input is captured in the cockpit frontend.
  • The InputMapper converts key states into main engine or RCS flight commands.
  • Commands are forwarded through the Qt signal-slot interface to the simulation backend.
  • SimControl and the spacecraft backend forward propulsion-related commands to the Thrust Orchestrator.
  • The Thrust Orchestrator updates the corresponding engine model or thrust state.
  • The resulting thrust vector is used by the dynamics layer during the next simulation step.

This separation is important because user input does not directly modify physical forces. Instead, input is transformed into commands, commands update actuator states, and actuator states generate physical thrust. This distinction supports realistic modeling and future extension to controller input, autopilot commands, and actuator dynamics.

Architectural Design Principles

  • Separation of Concerns: User input, command processing, propulsion modeling, physics propagation, and visualization are handled by distinct components.
  • Explicit State Representation: Runtime states such as ME_ThrustState and RCS_ThrustState distinguish commanded values from actual actuator output.
  • Vector-Based Dynamics: Forces are represented as Vector3 quantities, enabling three-dimensional translational dynamics and future 6-DOF extensions.
  • Configuration-Driven Setup: Spacecraft engines, tanks, and initial properties are loaded from external JSON definitions.
  • Interface-Based Extensibility: Physics, control, sensor, and propulsion models are accessed through abstract interfaces where possible.