orbiter-rs 0.2.0

Rust bindings for the Orbiter spaceflight simulator SDK
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

## Rust Bindings for Orbiter SDK

This project is a proof of concept for creating a spacecraft addon for the [Orbiter](https://github.com/orbitersim/orbiter) spaceflight simulator in Rust. It uses the [cxx](https://www.cxx.rs) crate creating Rust bindings for the Orbiter SDK. An addon built using these bindings can be found at: [https://github.com/thomasantony/surveyor](https://github.com/thomasantony/surveyor) which further on the included example to implement a landing guidance system.


### Goals

The initial goal of this project is to be able to re-create the core logic from this [tutorial](https://www.orbiterwiki.org/wiki/Vessel_Tutorial_1) in Rust. The source-code from the tutorial can be found in [examples/Surveyor/Surveyor.cpp](examples/Surveyor/Surveyor.cpp). This file exists purely as a reference and is not used during the build. Only the functions/classes required for this tutorial is currently implemented for Rust. This has been completed and it is possible to build a DLL file that can be loaded in Orbiter and re-creates the functionality of the Surveyor spacecraft to the extent shown in the aforementioned tutorial.

### Implementation

The crate can now be imported and used like a library. A demo implementation can be found in [`src/examples/Surveyor/surveyor.rs`](src/examples/Surveyor/surveyor.rs). An addon module must include a struct implementing the `OrbiterVessel` trait. Then it must use the `init_vessel!` macro to generate the code that links it to Orbiter SDK. For example:

```rust
init_vessel!(
    fn init(vessel) {
        Surveyor::new(vessel)
    }
    fn exit() {}
);
```

### Lifecycle of an Orbiter Rust Addon

TODO

### Building

1. Download/Install Orbiter
2. Install Visual Studio 2019
3. Install Rust using `rustup` (https://rustup.rs)
4. Install the win32 target by running `rustup target add i686-pc-windows-msvc`

This addon has been tested with Rust 1.57.0 and Visual Studio 2019 Commuity Edition on Windows 10. Running `cargo build` should build the project generate a DLL file.

### Installing and Testing the Addon

Once you build the addon, you should have a file called `Surveyor.dll` in ` target/i686-pc-windows-msvc/debug/examples/`. Copy this file to the `Modules` folder in your Orbiter installation. Also copy over the files in the `Config`, `Meshes` and `Scenarios` folders into the corresponding folders in your Orbiter installation. Launch the `SurveyorInOrbit` scenario in Orbiter and make sure that the spacecraft shows up. Pressing "L" should activate the retro thruster firing sequence.

### Future

Only a limited number of Orbiter functions are now available to Rust bindings. This list will expand in the future to hopefully include all of Orbiter SDK. Pull requests are welcome!

### Meshes

The meshes in the demo addon were adapted from the [Surveyor 1.0 Orbiter Addon](https://www.orbithangar.com/showAddon.php?id=e69853be-2dd6-4b37-a5df-fe6827c01cae). These were updated based on the tutorial at [https://www.orbiterwiki.org/wiki/Vessel_Tutorial_1](https://www.orbiterwiki.org/wiki/Vessel_Tutorial_1).

### MFDs

An older proof-of-concept for building MFDs can be found at [https://github.com/thomasantony/RustMFD](https://github.com/thomasantony/RustMFD). However, this uses an outdated and modified version of `cxx` and may not build at this time and exists just as a reference. The code in that repo will be moved over to this one at some point in the future.

### Notes
- Uses `.cargo/config` to force i686 as target