Snowplay

Idiomatic Rust interface to the WebAssembly API of Snowplay, the game engine used in Stormgate, a real-time strategy game by Frost Giant Studios.

WebAssembly and the Standard Library

Snowplay provides an API that mods can call in order to affect the game. This API is exposed via WebAssembly (WASM). For the uninitiated, WASM is a platform-agnostic binary code format, which is ideal for third-party mods and plugins as it allows a variety of tools to be used for modding (like Rust!) while maintaining decent performance and ensuring security (for instance, ensuring that mods can only do what they are allowed to do and aren't used for viruses or other kind of malware).

Usually when you compile Rust code, you compile it into native code for your CPU architecture. When building a mod for Snowplay, you need to instead compile it into WebAssembly. This WebAssembly code can then be imported into the Snowplay engine. However, because you're compiling to WebAssembly and running inside Snowplay, you don't have access to the Standard Library -- most crucially, you can't allocate heap memory, so no Vec or String, only statically-sized arrays (like [u8; 10]) and string slices (&str).

Quick Start

In order to compile for WASM and set your code up to not link with the Standard Library, you need to do the following things:

1. Setup a new Cargo project with cargo new --lib <crate_name_here>
2. Create the file .cargo/config.toml in your Cargo project and fill it with this configuration, which will make your crate compile to WASM:

   [build]
   target = "wasm32-unknown-unknown"
   

3. At the top of your lib.rs file, use the no_std attribute to disable the standard library and use the panic handler provided by this crate (see more details on panic handling below):

   #![no_std]
   
   // Don't use the panic handler during tests since tests will have access to std.
   #[cfg(not(test))]
   #[panic_handler]
   fn panic_handler(panic_info: &core::panic::PanicInfo) -> ! {
       snowplay::panic_handler(panic_info)
   }
   

4. Finally, in your Cargo.toml, set your crate type to be cdylib to produce a .wasm library once built:

   [lib]
   crate_type = ["cdylib"]
   

5. Now, once you run cargo build, you should see a my_crate.wasm file in the my_crate/target/wasm32-unknown-unknown/debug folder!

Panic Handling

The Standard Library comes with a "panic handler", a function that is called when a panic occurs in your code. Since we aren't using the Standard Library, we don't get this panic handler for free. Fortunately for you, the snowplay crate defines a panic handler for you which will print out an error message in-game when a panic occurs. You are free to use your own panic handler if you wish.

snowplay_sys

This crate uses a lower-level crate, snowplay_sys, to call Snowplay's API. You'll most likely want to use this crate for an easy-to-use higher-level interface, but should you want to customize your API usage, you can use snowplay_sys directly instead.

Status of this crate

Snowplay is not released at this time. Therefore, this crate is empty for now. This crate will become what it promises once Stormgate releases with a public API to consume. If you're interested in this too, please reach out!

Disclaimer

This project is not affiliated with or officially supported by Frost Giant Studios in any way.