# 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:
    ```toml
    [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):
    ```rust ,ignore
    #![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:
    ```toml
    [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.