How mumech/mechjeb2 works
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 Plugin modules · MechJebLib MechJebLib · MechJebLibBindings Bindings · MechJebCore.cs MechJebCore
Components 19
Game plugin
Runtime KSP/Unity assemblies that run inside the game.
- MechJebCore · Main runtime entry point and vessel-attached controller inside KSP.
MechJeb2/MechJebCore.cs - Plugin modules · Mission modules, menus, and vessel-facing controllers that implement gameplay behavior.
MechJeb2 - Attitude control · Low-level attitude, thrust, RCS, and direction tracking controllers.
MechJeb2/AttitudeControllers - Landing stack · Deorbit, deceleration, final descent, and landing guidance modules.
MechJeb2/LandingAutopilot - Maneuver planner · Orbital operation builders, porkchop planning, and node execution helpers.
MechJeb2/Maneuver - Flight sims · Reentry, flying, hoverslam, and landing prediction simulators used by guidance.
MechJeb2/FlyingSim - Runtime settings · Installation/version checks, part gating, and module settings/state.
MechJeb2/CompatibilityChecker.cs
Core library
Pure computation and algorithmic modules isolated from Unity/KSP.
- MechJebLib · Pure numerical and guidance algorithms separated from the game runtime.
MechJebLib - Control math · PID, LQR, filtering, interpolation, and throttle modulation primitives.
MechJebLib/Control - Fuel model · Deterministic fuel-flow, decoupling, part, and vessel simulation models.
MechJebLib/FuelFlowSimulation - PSG ascent · Multi-phase ascent problem, solver, phases, terminals, and solution building.
MechJebLib/PSG - Orbit math · Two-body propagation, Lambert solvers, maneuver functions, and transfer logic.
MechJebLib/Functions
Adapters
Translation layers between KSP state and the pure simulation models.
- Bindings · Adapters that convert KSP vessels and parts into library-friendly simulation inputs.
MechJebLibBindings
Content
Distributable part, localization, icon, and shader assets.
- AR202 part · The in-game MechJeb control pod that enables the mod's functionality.
Parts/MechJeb2_AR202 - Localization · Language strings and user-facing text resources.
Localization - Shaders/bundles · Unity shader sources and built asset bundles for in-game rendering.
Bundles - Unity project · Unity editor project used to build shader asset bundles and related assets.
MechJeb2-Unity
Tests
Verification projects for the reusable library.
- Lib tests · Unit and scenario tests covering primitives, solvers, maneuvers, ascent, and control math.
MechJebLibTest
Vendored deps
Third-party numerical library included in source form.
- alglib · Bundled numerical optimization and analysis library used by the solution.
alglib
Connections 23
- 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.