# mumech/mechjeb2 architecture

> Architecture diagram of the GitHub repository mumech/mechjeb2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mumech/mechjeb2
- Repository: https://github.com/mumech/mechjeb2

## Overview

1. **Overall shape**
   MechJeb2 is a Kerbal Space Program mod built as a multi-assembly Unity/C# solution. The repo splits cleanly into a game-facing plugin layer, a reusable math/flight-computation library, bindings/adapters between them, and test projects. It also includes the distributable game assets: part config/model, icons, localization, and shader bundles.

2. **Game integration boundary**
   The `MechJeb2` assembly is the runtime entry point inside KSP/Unity. It contains the MonoBehaviour-style modules that attach to vessels or UI, such as `MechJebCore`, `ComputerModule`, `AutopilotModule`, `DisplayModule`, and the many `MechJebModule*` feature controllers. This is the layer that talks to KSP’s vessel, part, and flight APIs and turns library computations into in-game control actions.

3. **Autopilot and guidance subsystem**
   The plugin layer is organized around mission-specific autopilots: ascent, landing, rendezvous, docking, maneuver planning, rover control, hoverslam, staging, warp, thrust, RCS balancing, and attitude control. These modules represent the “decision layer” of the mod: they read vessel state, choose a mode or target, then command pitch/yaw/roll, throttle, staging, warp, and node execution.

4. **Control-loop subsystem**
   The `AttitudeControllers` folder plus modules like `MechJebModuleSmartASS`, `MechJebModuleAttitudeController`, `MechJebModuleRCSController`, and `MechJebModuleThrustController` form the low-level control boundary. This is where guidance commands are translated into actuator-level outputs. The repository includes multiple controller strategies: PID-based loops, LQR variants, torque PI, and hybrid/better controllers, indicating the mod supports different control laws depending on situation and vessel dynamics.

5. **Simulation and prediction layer**
   Several plugin-side simulators estimate future behavior without fully flying the vessel: `FlyingSim`, `ReentrySimulation`, `MechJebModuleLandingPredictions`, `MechJebModuleHoverslamSimulation`, and `MechJebStageStatsHelper`. These components feed landing, ascent, and maneuver planning with predicted trajectories, deceleration burns, stage performance, and reentry outcomes. They are the main source of “what if” data used by autopilots.

6. **Orbital mechanics and maneuver planning**
   Maneuver construction lives in the `Maneuver` folder and related modules. The code covers standard orbital operations such as circularization, inclination changes, transfers, plane changes, station-keeping, and Lambert-based transfers. This subsystem is the bridge from desired orbital targets to concrete maneuver nodes and burn vectors.

7. **Reusable computation library**
   `MechJebLib` is the algorithmic core and is deliberately separated from the Unity/KSP runtime. It contains pure computational modules for control theory, ODE integration, root finding, interpolation, two-body orbit math, Lambert solvers, maneuver equations, ascent optimization, and hoverslam modeling. This separation makes the core logic testable and reusable outside the game engine.

8. **Bindings/adapters between game state and pure math**
   `MechJebLibBindings` is the translation layer from KSP objects to library-friendly simulation models. Its fuel-flow and vessel builder/updater types adapt parts, resources, and modules into simulated parts/vessels used by `MechJebLib`. This boundary is important: game objects are mutable and Unity-owned, while the library expects deterministic model inputs.

9. **Part, UI, and content packaging**
   The mod ships with an actual in-game part (`Parts/MechJeb2_AR202`) that acts as the control pod enabling MechJeb functionality. UI assets are split across `Icons`, `Bundles`, and `MechJeb2-Unity`, where shaders and asset bundles are built in Unity and then loaded by the plugin. `Localization/*.cfg` provides multilingual text for the interface and messages.

10. **Feature gating and compatibility**
   Files like `CompatibilityChecker`, `InstallChecker`, `MechJebAR202`, and `MechJebEdu.cfg` indicate the mod checks KSP version, installation state, and part availability before enabling functions. Some behavior is also gated by career/science progress and vessel configuration, matching KSP’s progression model.

11. **External libraries and numerical engine**
   `alglib` is vendored in the repo and likely used for numerical optimization and related math routines. The README also lists xUnit and NSubstitute for testing and mocking. These dependencies matter because much of MechJeb’s functionality depends on stable numerical methods rather than simple gameplay scripting.

12. **Testing boundary**
   `MechJebLibTest` focuses on the pure library, with coverage for primitives, root finding, ODE solvers, Lambert solvers, hoverslam, maneuvers, ascent planning, and control loops. This strongly reinforces the repository architecture: the game plugin is comparatively thin, while the core orbital/control logic is isolated and verified independently.

13. **Build and packaging pipeline**
   The repo is organized as a ship-ready mod package rather than a single executable. The solution builds multiple assemblies, then copies runtime outputs into a KSP-compatible folder layout. Unity project files under `MechJeb2-Unity` are used to generate shader asset bundles, and the final distributable is assembled from DLLs plus the content folders the game expects.

14. **Primary data flow**
   The central runtime flow is: KSP vessel/part state enters the plugin layer, adapters build a simulation model, `MechJebLib` computes guidance or predictions, autopilot modules convert those results into control commands, and the UI displays state/settings to the player. The mod’s architecture is therefore a classic split between game integration, deterministic computation, and presentation/content assets.

Main entry points: [`MechJeb2`](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2) (Plugin modules), [`MechJebLib`](https://github.com/mumech/mechjeb2/tree/dev/MechJebLib) (MechJebLib), [`MechJebLibBindings`](https://github.com/mumech/mechjeb2/tree/dev/MechJebLibBindings) (Bindings), [`MechJeb2/MechJebCore.cs`](https://github.com/mumech/mechjeb2/blob/dev/MechJeb2/MechJebCore.cs) (MechJebCore)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_plugin["Game plugin"]
  node_n_core["MechJebCore<br/>runtime entry<br/>[MechJebCore.cs]"]
  node_n_modules["Plugin modules<br/>autopilot/UI"]
  node_n_att_ctrl["Attitude control<br/>control loop"]
  node_n_landing["Landing stack<br/>descent autopilot"]
  node_n_maneuver["Maneuver planner<br/>node planning"]
  node_n_sim["Flight sims<br/>prediction"]
  node_n_settings["Runtime settings<br/>compatibility"]
end

subgraph group_grp_lib["Core library"]
  node_n_lib["MechJebLib<br/>math core"]
  node_n_control["Control math<br/>control theory"]
  node_n_fuel["Fuel model<br/>vehicle simulation"]
  node_n_psg["PSG ascent<br/>ascent optimizer"]
  node_n_orbit["Orbit math<br/>astrodynamics"]
end

subgraph group_grp_bindings["Adapters"]
  node_n_bind["Bindings<br/>adapter layer"]
end

subgraph group_grp_content["Content"]
  node_n_part["AR202 part<br/>game part"]
  node_n_locale["Localization<br/>content"]
  node_n_shaders["Shaders/bundles<br/>ui assets"]
  node_n_unity["Unity project<br/>asset build"]
end

subgraph group_grp_tests["Tests"]
  node_n_tests["Lib tests<br/>test suite"]
end

subgraph group_grp_vendor["Vendored deps"]
  node_n_alglib["alglib<br/>vendored numeric lib"]
end

node_n_core -->|"hosts"| node_n_modules
node_n_modules -->|"uses"| node_n_att_ctrl
node_n_modules -->|"drives"| node_n_landing
node_n_modules -->|"plans"| node_n_maneuver
node_n_modules -->|"predicts"| node_n_sim
node_n_modules -->|"guards"| node_n_settings
node_n_att_ctrl -->|"maps to"| node_n_control
node_n_landing -->|"consults"| node_n_sim
node_n_maneuver -->|"computes"| node_n_orbit
node_n_sim -->|"models via"| node_n_bind
node_n_core -->|"adapts through"| node_n_bind
node_n_bind -->|"builds"| node_n_fuel
node_n_bind -->|"supports"| node_n_control
node_n_lib -->|"contains"| node_n_control
node_n_lib -->|"contains"| node_n_fuel
node_n_lib -->|"contains"| node_n_psg
node_n_lib -->|"contains"| node_n_orbit
node_n_tests -->|"verifies"| node_n_lib
node_n_unity -->|"builds"| node_n_shaders
node_n_shaders -->|"loaded by"| node_n_modules
node_n_locale -->|"localizes"| node_n_modules
node_n_part -->|"enables"| node_n_core
node_n_alglib -->|"supports"| node_n_lib

click node_n_core "https://github.com/mumech/mechjeb2/blob/dev/MechJeb2/MechJebCore.cs"
click node_n_modules "https://github.com/mumech/mechjeb2/tree/dev/MechJeb2"
click node_n_att_ctrl "https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/AttitudeControllers"
click node_n_landing "https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/LandingAutopilot"
click node_n_maneuver "https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/Maneuver"
click node_n_sim "https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/FlyingSim"
click node_n_settings "https://github.com/mumech/mechjeb2/blob/dev/MechJeb2/CompatibilityChecker.cs"
click node_n_lib "https://github.com/mumech/mechjeb2/tree/dev/MechJebLib"
click node_n_control "https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/Control"
click node_n_fuel "https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/FuelFlowSimulation"
click node_n_psg "https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/PSG"
click node_n_orbit "https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/Functions"
click node_n_bind "https://github.com/mumech/mechjeb2/tree/dev/MechJebLibBindings"
click node_n_part "https://github.com/mumech/mechjeb2/tree/dev/Parts/MechJeb2_AR202"
click node_n_locale "https://github.com/mumech/mechjeb2/tree/dev/Localization"
click node_n_shaders "https://github.com/mumech/mechjeb2/tree/dev/Bundles"
click node_n_unity "https://github.com/mumech/mechjeb2/tree/dev/MechJeb2-Unity"
click node_n_tests "https://github.com/mumech/mechjeb2/tree/dev/MechJebLibTest"
click node_n_alglib "https://github.com/mumech/mechjeb2/tree/dev/alglib"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_core,node_n_modules,node_n_att_ctrl,node_n_landing,node_n_maneuver,node_n_sim,node_n_settings toneBlue
class node_n_lib,node_n_control,node_n_fuel,node_n_psg,node_n_orbit toneAmber
class node_n_bind toneMint
class node_n_part,node_n_locale,node_n_shaders,node_n_unity toneRose
class node_n_tests toneIndigo
class node_n_alglib toneTeal
```

## Components

### Game plugin

Runtime KSP/Unity assemblies that run inside the game.

- [MechJebCore](https://github.com/mumech/mechjeb2/blob/dev/MechJeb2/MechJebCore.cs): runtime entry · Main runtime entry point and vessel-attached controller inside KSP. · `MechJeb2/MechJebCore.cs`
- [Plugin modules](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2): autopilot/UI · Mission modules, menus, and vessel-facing controllers that implement gameplay behavior. · `MechJeb2`
- [Attitude control](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/AttitudeControllers): control loop · Low-level attitude, thrust, RCS, and direction tracking controllers. · `MechJeb2/AttitudeControllers`
- [Landing stack](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/LandingAutopilot): descent autopilot · Deorbit, deceleration, final descent, and landing guidance modules. · `MechJeb2/LandingAutopilot`
- [Maneuver planner](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/Maneuver): node planning · Orbital operation builders, porkchop planning, and node execution helpers. · `MechJeb2/Maneuver`
- [Flight sims](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2/FlyingSim): prediction · Reentry, flying, hoverslam, and landing prediction simulators used by guidance. · `MechJeb2/FlyingSim`
- [Runtime settings](https://github.com/mumech/mechjeb2/blob/dev/MechJeb2/CompatibilityChecker.cs): compatibility · Installation/version checks, part gating, and module settings/state. · `MechJeb2/CompatibilityChecker.cs`

### Core library

Pure computation and algorithmic modules isolated from Unity/KSP.

- [MechJebLib](https://github.com/mumech/mechjeb2/tree/dev/MechJebLib): math core · Pure numerical and guidance algorithms separated from the game runtime. · `MechJebLib`
- [Control math](https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/Control): control theory · PID, LQR, filtering, interpolation, and throttle modulation primitives. · `MechJebLib/Control`
- [Fuel model](https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/FuelFlowSimulation): vehicle simulation · Deterministic fuel-flow, decoupling, part, and vessel simulation models. · `MechJebLib/FuelFlowSimulation`
- [PSG ascent](https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/PSG): ascent optimizer · Multi-phase ascent problem, solver, phases, terminals, and solution building. · `MechJebLib/PSG`
- [Orbit math](https://github.com/mumech/mechjeb2/tree/dev/MechJebLib/Functions): astrodynamics · Two-body propagation, Lambert solvers, maneuver functions, and transfer logic. · `MechJebLib/Functions`

### Adapters

Translation layers between KSP state and the pure simulation models.

- [Bindings](https://github.com/mumech/mechjeb2/tree/dev/MechJebLibBindings): adapter layer · Adapters that convert KSP vessels and parts into library-friendly simulation inputs. · `MechJebLibBindings`

### Content

Distributable part, localization, icon, and shader assets.

- [AR202 part](https://github.com/mumech/mechjeb2/tree/dev/Parts/MechJeb2_AR202): game part · The in-game MechJeb control pod that enables the mod's functionality. · `Parts/MechJeb2_AR202`
- [Localization](https://github.com/mumech/mechjeb2/tree/dev/Localization): content · Language strings and user-facing text resources. · `Localization`
- [Shaders/bundles](https://github.com/mumech/mechjeb2/tree/dev/Bundles): ui assets · Unity shader sources and built asset bundles for in-game rendering. · `Bundles`
- [Unity project](https://github.com/mumech/mechjeb2/tree/dev/MechJeb2-Unity): asset build · Unity editor project used to build shader asset bundles and related assets. · `MechJeb2-Unity`

### Tests

Verification projects for the reusable library.

- [Lib tests](https://github.com/mumech/mechjeb2/tree/dev/MechJebLibTest): test suite · Unit and scenario tests covering primitives, solvers, maneuvers, ascent, and control math. · `MechJebLibTest`

### Vendored deps

Third-party numerical library included in source form.

- [alglib](https://github.com/mumech/mechjeb2/tree/dev/alglib): vendored numeric lib · Bundled numerical optimization and analysis library used by the solution. · `alglib`

## Connections

- MechJebCore → Plugin modules: hosts · Core singleton coordinates runtime modules and UI controllers.
- Plugin modules → Attitude control: uses · Autopilots delegate low-level actuator control to attitude and thrust controllers.
- Plugin modules → Landing stack: drives · Landing-related modules consume descent guidance and simulation outputs.
- Plugin modules → Maneuver planner: plans · Mission modules create and execute maneuver nodes and transfer operations.
- Plugin modules → Flight sims: predicts · Gameplay guidance uses local simulation and prediction subsystems.
- Plugin modules → Runtime settings: guards · Feature availability is gated by installation and compatibility checks.
- Attitude control → Control math: maps to · Plugin controllers mirror the reusable control-loop implementations.
- Landing stack → Flight sims: consults · Landing autopilot relies on trajectory and deceleration prediction.
- Maneuver planner → Orbit math: computes · Maneuver planning is built on orbital mechanics and transfer math.
- Flight sims → Bindings: models via · Simulation layers are fed through deterministic vessel and part adapters.
- MechJebCore → Bindings: adapts through · Runtime state is translated into library inputs via bindings.
- Bindings → Fuel model: builds · Adapters construct simulated vessels, parts, and fuel-flow state.
- Bindings → Control math: supports · Bindings supply math-friendly state for controllers and optimizers.
- MechJebLib → Control math: contains · Core library includes the reusable control primitives.
- MechJebLib → Fuel model: contains · Core library includes the vessel and fuel-flow simulation models.
- MechJebLib → PSG ascent: contains · Core library includes the ascent optimization system.
- MechJebLib → Orbit math: contains · Core library includes orbital mechanics and maneuver formulas.
- Lib tests → MechJebLib: verifies · Tests cover the deterministic library instead of the game plugin.
- Unity project → Shaders/bundles: builds · Unity project produces the shader bundles shipped with the mod.
- Shaders/bundles → Plugin modules: loaded by · Built assets are consumed by the runtime plugin for UI rendering.
- Localization → Plugin modules: localizes · Localization files provide user-visible text for modules and windows.
- AR202 part → MechJebCore: enables · The control pod is the physical in-game entry point for the core module.
- alglib → MechJebLib: supports · Vendored numerical routines back parts of the reusable algorithm layer.
