An open-source ecosystem for small-arms exterior ballistics
One physics core — point-mass (3‑DoF) trajectory model plus spin drift — implemented once in C/C++ and exposed natively to Python, TypeScript, Dart, and MicroPython.
Ballistic trajectory math doesn’t change between platforms — only the deployment target does. Instead of re-deriving the physics for every language, this organization keeps a single C++/C99 core (bclibc / tiny_bclibc) and builds thin, idiomatic bindings around it for desktop, mobile, web, and embedded targets. One engine, one set of bugs to fix, many places it runs.
Every wrapper that can drive a py-ballisticcalc engine is checked against the same, well-covered
test suite from py-ballisticcalc. This keeps the bindings numerically consistent with each other
and with the C++ core, so the bindings stay numerically consistent with each other and with the C++ core.
js-ballistics cannot load a Python engine, so it keeps its own port of the same suite.
flowchart TD
A["bclibc<br><i>C++17 core</i><br>RK4/Euler/Verlet + adaptive RK45<br>(Cash-Karp, Dormand-Prince, Tsitouras)<br>C FFI: BCLIBCFFI_*"]
A2["tiny_bclibc<br><i>C99 subset for embedding</i><br>(Tsitouras)"]
A -->|"subset"| A2
A --> X["py-ballisticcalc.exts<br><i>(Cython)</i>"]
A --> D["dart-bclibc<br><i>(Dart FFI)</i>"]
A --> J["js-ballistics<br><i>(bare WASM, zig/wasi-sdk)</i>"]
A2 -.->|"git submodule<br>C99 subset only"| T["tiny-bclibc-wasm-py<br><i>(WebAssembly: CPython, PyPy, Pythonista)</i>"]
A2 -.->|"git submodule<br>C99 subset only"| E["micropython-bclibc<br><i>(natmod/usermod for MCUs)</i>"]
API{{"py-ballisticcalc<br>compatible engine API"}}
X --> API
D -->|"Python bridge"| API
T -->|"engine plugin<br>(entry points)"| API
API --> P["py-ballisticcalc<br><i>+ pure Python and SciPy engines</i>"]
API -.-> O["shared test suite"]
E -.-|"same Python API"| T
D --> F["ebalistyka<br><i>(Flutter app)</i>"]
Pure C++ ballistic solver: RK4, Euler, Cash-Karp, Dormand-Prince and Tsitouras integration, Ridder’s method for zero-finding, and a stable,
versioned C FFI surface (BCLIBCFFI_*) consumable from Dart, Python, Rust, WASM or anything with a C ABI.
Builds to a static core (libbclibc_core) and a shared FFI lib (libbclibc_ffi) for Linux, macOS, and Windows, and also as bare wasm32-wasi module.
The repo also bundles a C99 subset (tiny_bclibc) of the same engine, used as-is by micropython-bclibc via git submodule.
MicroPython bindings around the tiny_bclibc C99 subset bundled in the bclibc repo (pulled in as a git submodule),
with three deployment modes: native .mpy module (x64/x86, Cortex‑M, Xtensa, RISC‑V),
usermod baked directly into firmware (RP2040, ESP32, STM32…), or FFI against libtiny_bclibc.so on any Unix port.
Includes a streaming/callback trajectory API for boards with as little as ~200 KB free RAM, plus a float32-vs-float64 precision comparison harness.
Experimental — APIs may change.
Python library for ballistic trajectory calculation, with pluggable engines (pure-Python RK4/Euler/Verlet, Cython-accelerated, or SciPy-backed)
and full unit-conversion support across angular, distance, energy, pressure, temperature, velocity and weight dimensions. pip install py-ballisticcalc.
Ballistic solver (tiny_bclibc) as WebAssembly for CPython, PyPy and Pythonista, with a py-ballisticcalc engine
TypeScript/JavaScript library powered by the C++ core compiled to bare-WebAssembly — runs in Node.js or directly in the browser (CDN-ready, no build step). Supports wind layers, multi-BC drag models, Coriolis effect, danger-space, and powder-temperature sensitivity. npm install js-ballistics.
Thin, zero-copy Dart FFI/WASM wrapper around libbclibc_ffi, bundling the bclibc C++ source as a git submodule (no pre-built binaries required).
Covers the full solver surface — trajectory integration, zero-angle/apex/max-range solving, sight corrections, energy/OGW — plus a typed
unit system (Distance, Velocity, Temperature, …). Supports Linux, Windows, macOS, Android, iOS and Web.
Cross-platform ballistic calculator app (Linux, Windows, Android — macOS/iOS in progress) built with Flutter, consuming bclibc through the
dart_bclibc wrapper. Shooting profiles, trajectory tables, an SVG mil-reticle with live
drop/windage indication, and profile import/export. Alpha software.
- One physics model. Atmosphere density, Coriolis effect, drag-curve interpolation (PCHIP), and cant correction are implemented once in C++/C99; every binding just marshals data in and out.
- Precision tiers. Where it matters for embedded targets, both
float32andfloat64builds are validated against each other (seemicropython-bclibc’s precision-comparison suite).
Warning
These libraries perform approximate simulations of complex physical processes. Calculation results must not be considered a complete or fully reliable reflection of actual projectile behavior. Use for educational purposes only — results must not be relied upon in any context where an incorrect calculation could cause financial harm or put a human life at risk. Code is provided “AS IS”, without warranty of any kind. See each repository’s README for the full notice.
