The Problem

Simulating and visual‑rendering dynamic objects (aircraft, ships, spacecraft) on a planetary scale demands a tightly coupled 3D engine, physics, and geospatial data handling. Existing GIS stacks lack real‑time physics and high‑fidelity rendering, forcing teams to cobble together disparate libraries.

What This Does

Skybolt delivers a native C++ core (≈ 316 CPP + 414 headers) that wraps OpenSceneGraph, Bullet, and custom shaders to render planetary surfaces, atmospheres, oceans, and urban layouts. Python bindings (src/Skybolt/SkyboltPythonBindings/PythonBindings.cpp) let users script scenario creation and runtime control. The React‑based UI assets live under Assets/Globe and Assets/Core, exposing a browser‑like front‑end for scenario selection.

Key files:

  • src/Skybolt/MapFeaturesConverter/main.cpp – CLI that converts GeoJSON‑style feature files into the engine’s binary format.
  • src/Skybolt/TileMapGenerator/main.cpp – Generates tiled terrain/imagery caches used at runtime.
  • Assets/Core/Scripts/skybolt_util.py – Helper library imported by Python plug‑ins for entity spawning and replay handling.

How It Is Wired

Execution starts in one of the two main.cpp entry points. Both create a SkyboltEngine instance (defined in src/Skybolt/SkyboltEngine/SkyboltEngine.cpp), which:

  1. Initialises OpenSceneGraph – loads scene graph plugins, registers the BulletWorld (see src/Skybolt/SkyboltEnginePlugins/Bullet/BulletWorld.cpp).
  2. Loads configuration – reads JSON files such as Assets/Core/Entities/Camera.json and the scenario description passed on the command line.
  3. Registers Python bindings – PythonBindings.cpp exposes SkyboltEngine methods to the interpreter; the interpreter is started with the script path supplied to --script.
  4. Spawns the render loop – src/Skybolt/SkyboltVis/Renderer.cpp drives the OSG viewer, pulls shader programs from Assets/Core/Shaders/…, and steps the physics world each frame.

The most far‑reaching module is SkyboltEngine.cpp; any change to its plugin registration or the physics step propagates to all downstream renderers and Python scripts. No circular import cycles were detected, and the internal import graph consists of 20 isolated modules, indicating limited cross‑module coupling beyond the engine core.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/Skybolt
cd Skybolt

# Install Python helper deps (no lockfile – see health notes)
pip install -r Assets/Core/Scripts/requirements.txt

# Install UI deps (npm or pnpm based on package.json)
npm install --prefix Assets/Core
npm install --prefix Assets/Globe
npm install --prefix Assets/Movers

# Resolve C++ deps via Conan and configure CMake
mkdir build && cd build
conan install .. --build=missing
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release

Run the map‑feature converter (example):

./src/Skybolt/MapFeaturesConverter/MapFeaturesConverter \
    --input Assets/Globe/Entities/PlanetEarth.json \
    --output build/PlanetEarth.bin

Start the interactive viewer:

./src/Skybolt/SkyboltEngineQt/SkyboltViewer \
    --scenario build/PlanetEarth.bin

Configuration files (*.json) reside under Assets/Core/Entities and Assets/Globe/Entities. No environment variables are required out of the box.

Real‑World Use

A defense‑simulation team can generate a terrain cache with TileMapGenerator, then feed the binary to SkyboltViewer while a Python script (via skybolt_util.py) spawns live aircraft entities and streams telemetry to a separate analysis service. The C++ core guarantees deterministic physics; Python offers rapid scenario iteration.

Code Health & Issues

  • High – Pin GitHub Actions to commit SHAs (.github/workflows/*.yml).
  • High – Add a lockfile for Assets/Core/package.json.
  • Medium – Declare least‑privilege GITHUB_TOKEN permissions (.github/workflows/on_push.yml).
  • Medium – Enable Dependabot (.github/dependabot.yml).
  • Medium – Add a dependency‑vulnerability scan step to CI.
  • Medium – Set persist-credentials: false on the checkout action (build.yml).
  • Low – Define timeout-minutes on workflow jobs (build.yml).
  • Low – Files opened without context manager (Conan/Recipes/mufft/conanfile.py, Tools/BuildScripts/docs/serve_docs.py).
  • High – Deep nesting (up to 8 levels) in shader headers and physics code, making maintenance difficult.
  • High – Duplicated shader blocks across dozens of files; should be consolidated.
  • High – Oversized files (> 2 k lines) such as nanosvg.h and FeaturesConverter.cpp; recommend splitting by responsibility.

No secrets were found, a licence file is present, and CI runs via GitHub Actions.

The Bottom Line

Skybolt provides a full‑stack C++/Python engine for planetary‑scale simulation with a usable UI and clear entry points, but the codebase suffers from excessive file size, duplicated shader logic, and a few CI hygiene gaps. Teams comfortable with CMake/Conan and willing to refactor large files will find a solid foundation; otherwise, the maintenance overhead may outweigh the immediate capabilities.