Crate orbiter_rs

Rust bindings for Orbiter SDK

This crate allows the development of addon modules for the Orbiter spaceflight simulator in Rust. At present, this crate is still under development and only a limited subset of the VESSEL API is supported.

Minimal Example

The following example shows a very basic addon that uses the existing textures supplied with Orbiter to create a minimal vessel addon.

use orbiter_rs::{
   debug_string, OrbiterVessel, init_vessel, SDKVessel
};
pub struct MinimalPB{
    ctx: SDKVessel
}
impl MinimalPB {
    pub fn new(vessel: SDKVessel) -> Self {
        Self {
            ctx: vessel
        }
    }
}
impl OrbiterVessel for MinimalPB {
    fn set_class_caps(&mut self, _cfg: FileHandle) {
        self.ctx.SetSize(1.0);
        self.ctx.AddMesh("ShuttlePB");
    }
    fn on_pre_step(&mut self, sim_t: f64, _sim_dt: f64, _mjd: f64)
    {
        debug_string!("Hello world! sim_t: {:.2}", sim_t);
    }
}

init_vessel!(
    fn init(vessel) {
        MinimalPB::new(vessel)
    }
    fn exit() {}
);

The Cargo.toml for the addon must specify crate-type = [cdylib]. It may also be beneficiant to create a .cargo/confg file with the following contents:

[build]
target = "i686-pc-windows-msvc"

This will ensure that the build always targets 32-bit windows (which is the only platform supported by Orbiter at the time of writing). The ORBITER_DIR environment variable must be set to the path to a working Orbiter installation before building.

Building and Installing Examples

The examples in the examples directory can be built by running cargo build --example MinimalPB and cargo build --example Surveyor. To install these, copy the resulting DLL from target/i686-pc-windows-msvc/debug/examples/MinimalPB.dll to the Modules folder in your Orbiter installation. The contents of examples/MinimalPB/Config and examples/MinimalPB/Scenarios should also be copied into your Orbiter installation direction under the respective folders.

For the Surveyor example, the Meshes, Textures folders also needs to have their contents copied to the respective folders under the Orbiter installation

The addons can then be tested by opening the newly installed scenarios in Orbiter.

Logging

orbiter-rs uses the log crate to facilitate logging directly to the Orbiter log. Any addons seeking to use this must call init_logging somewhere in their code, preferably in their OrbiterVessel::set_class_caps implementation. After the system is initialized, the macros log::error, log::warn, log::info, log::debug and log::trace can be used. All of the filtering features of the log crate may be used as well.

Macros

V

Helper macro for defining Vector3 objects

ctype_wrapper

Macro for defining ctype wrappers

debug_string

Displays a string in the lower left corner of the viewport.

init_vessel

Helper macro for defining entry point into a Vessel addon

Structs

DWORD

Newtype wrapper for DWORD as a u32

KeyStates

Keyboard key states

OBJHANDLE

Newtype wrapper for OBJHANDLE as a usize

OrbiterLogger

PROPELLANT_HANDLE

Newtype wrapper for PROPELLANT_HANDLE as a usize

ReferenceFrame

Reference Frame

THGROUP_HANDLE

Newtype wrapper for THGROUP_HANDLE as a usize

THRUSTER_HANDLE

Newtype wrapper for THRUSTER_HANDLE as a usize

ThrusterGroupType

Type alias for [THGROUP_TYPE] Thruster Group Type

VESSELSTATUS

Binding for OrbiterSDK’s VESSELSTATUS struct

Vector3

VesselContext

Rust interface to the VESSELx abstract classes in Orbiter SDK

Enums

Key

Keyboard keys

Traits

OrbiterVessel

Trait to be implemented by a spacecraft addon module

Functions

ODebug

Print message to lower-left corner of screen. For debugging purposes only!

init_logging

Initialize orbiter logger with given minimum log level

oapi_create_vessel

Create new vessel using Orbiter SDK

Type Aliases

FILEHANDLE

PropellantHandle

Type alias for PROPELLANT_HANDLE

SDKVessel

A wrapper over the FFI interface to the Orbiter SDK This is passed to the init() function in the [init_vessel!] macro

ThrustGroupHandle

Type alias for THGROUP_HANDLE

ThrusterHandle

Type alias for THRUSTER_HANDLE

VECTOR3

Type alias for VECTOR3

VesselStatus

Type alias for VESSELSTATUS