About Plugins

What is a Plugin?

A plugin is a Basilisk-compatible C++/SWIG module compiled outside of the Basilisk source tree. It links against the same Basilisk runtime your simulation uses, so it behaves identically to any built-in module.

Basilisk ships a curated set of simulation modules covering common astrodynamics tasks. Plugins let you extend Basilisk with your own C++ modules—new dynamics models, custom environment models, proprietary algorithms, or research prototypes—without modifying or recompiling Basilisk itself.

Plugins vs. External Modules

Plugins are the recommended way to write custom Basilisk modules. Basilisk also supports an older Building Custom Modules mechanism that folds modules into a from-source Basilisk build, but it requires cloning and recompiling all of Basilisk every time you make a change.

Feature	Plugin ✓ recommended	External module
Requires cloning BSK source	No	Yes
Requires recompiling all of Basilisk	No — builds in seconds	Yes — full rebuild
Distributable via pip install	Yes	No
Works with pip install bsk	Yes	No
Portable across machines/environments	Yes — just install the wheel	No — tied to a local build
Can be kept in a private repo	Yes	Yes
Supports custom messages	Yes	Yes

Only use external modules if you specifically need your code compiled into the same build as Basilisk (i.e. available as Basilisk.ExternalModules.myModule).

Why Write a Plugin?

Tip

pip install bsk + pip install bsk-sdk is all you need. No cloning. No building Basilisk from source. Ever.

• No Basilisk source checkout required. Install Basilisk and the SDK from PyPI and start writing your module immediately. Upgrading Basilisk is a single pip install --upgrade bsk.

• Compile only your code. Plugin builds take seconds, not minutes. You never wait on a full Basilisk recompile to test a one-line change.

• Fully portable. A plugin is a standard Python wheel. Check it into your own repo, build it in CI, and install it anywhere with pip install. No build environment setup required on the target machine.

• Share with the community. Publish to PyPI and anyone can install your module with pip install my-plugin alongside their existing Basilisk installation.

• Keep proprietary code private. Your module lives in its own repository. Nothing about the Basilisk source is exposed or required.

How Plugins Work

Basilisk plugins are built with bsk-sdk, a companion Python package that ships the headers, SWIG interface files, and CMake helpers needed to compile out-of-tree modules.

┌─────────────────────────────────────┐
│  Your plugin (separate repo/wheel)  │
│                                     │
│   myModule.cpp / myModule.h         │
│   myModule.i                        │
│   CMakeLists.txt                    │
└──────────────┬──────────────────────┘
               │ links against
┌──────────────▼──────────────────────┐
│  bsk-sdk wheel                      │
│  (vendored BSK headers + cmake)     │
└──────────────┬──────────────────────┘
               │ compatible with
┌──────────────▼──────────────────────┐
│  Basilisk (pip install bsk)         │
└─────────────────────────────────────┘

The plugin compiles against the same BSK headers and SWIG runtime that Basilisk uses, so message types, base classes, and the module API are all fully compatible.

Quick Start

1. Install the SDK

pip install bsk-sdk

2. Create your plugin layout (following BSK module conventions)

my-plugin/
├── pyproject.toml
├── CMakeLists.txt
└── myModule/
    ├── myModule.h
    ├── myModule.cpp
    ├── myModule.i
    └── _UnitTest/
        └── test_myModule.py

3. Wire up CMakeLists.txt

cmake_minimum_required(VERSION 3.26)
project(my_plugin LANGUAGES C CXX)

find_package(Python3 REQUIRED COMPONENTS Interpreter Development.Module NumPy)

execute_process(
  COMMAND "${Python3_EXECUTABLE}" -c
    "import bsk_sdk; print(bsk_sdk.cmake_config_dir(), end='')"
  OUTPUT_VARIABLE bsk_sdk_dir
)
set(bsk-sdk_DIR "${bsk_sdk_dir}")
find_package(bsk-sdk CONFIG REQUIRED)

bsk_add_swig_module(
  TARGET myModule
  INTERFACE myModule/myModule.i
  SOURCES   myModule/myModule.cpp
  LINK_LIBS bsk::plugin
  OUTPUT_DIR "${SKBUILD_PLATLIB_DIR}/my_plugin"
)

4. Build and install

pip install scikit-build-core build
python -m build --wheel
pip install dist/*.whl

5. Use it in a simulation

from my_plugin import myModule
from Basilisk.utilities import SimulationBaseClass

sim = SimulationBaseClass.SimBaseClass()
mod = myModule.MyModule()
sim.AddModelToTask("task", mod)

A complete working example is provided in the bsk-sdk repository.

Version Compatibility

A plugin wheel is compiled against a specific version of the BSK headers. bsk-sdk version numbers track Basilisk: bsk-sdk==2.9.1 contains headers from Basilisk v2.9.1. If the installed Basilisk version does not match, CMake will error at configure time with a clear message.

Always install matching versions:

pip install "bsk==2.9.1" "bsk-sdk==2.9.1"