Crate voxel_engine

This repository contains the public modding API for the Octo voxel game engine. The modding API can be used to develop new games for the engine, in the form of WASM plugins. The following functionality is available:

• Adjusting the camera position
• Drawing in-game GUIs using egui
• Reading user input, including mouse movements, key presses, and controller inputs

This crate is early in development, and breaking changes may occur at any time. This crate is not guaranteed to follow semantic versioning.

Getting started

The following is an abridged tutorial demonstrating how to compile/load a WASM plugin into the voxel engine. A complete example plugin can be found in the example_mod directory.

First, initialize a Rust project:

cargo new my_mod --lib

Next, add the following lines to the Cargo.toml:

[lib]
crate-type = [ "cdylib" ]  # Indicate that cargo should generate a .wasm file

[dependencies]
voxel_engine = { version = "0.1" }  # Provides access to engine APIs
wings = { version = "0.1" }  # Allows for creating WASM plugins

Then, create an example WingsSystem and export it. This will cause the engine to load the system:

use voxel_engine::*;
use voxel_engine::timing::*;
use wings::*;

// The game client will load all systems listed in brackets.
instantiate_systems!(Client, [HelloClient]);

/// A system that will print out the frame
/// time each frame.
struct HelloClient {
    /// The context handle.
    ctx: WingsContextHandle<Self>
}

impl HelloClient {
    /// Event that executes once per frame
    fn print_frame_time(&mut self, _: &voxel_engine::timing::on::Frame) {
        println!("Frame time: {}", self.ctx.get::<dyn FrameTiming>().frame_duration().as_secs_f32());
    }
}

impl WingsSystem for HelloClient {
    const DEPENDENCIES: Dependencies = dependencies()
        .with::<dyn FrameTiming>();

    const EVENT_HANDLERS: EventHandlers<Self> = event_handlers()
        .with(Self::print_frame_time);

    fn new(ctx: WingsContextHandle<Self>) -> Self {
        println!("Hello client!");
        Self
    }
}

Next, build the WASM mod with Cargo:

cargo build --target wasm32-wasip1

The resultant WASM binary will be located under target/wasm32-wasip1/release. This file can be selected and loaded into the voxel engine.

Modules

asset

Manages access to wasset-embedded data.

egui

Allows for drawing user interfaces with egui.

input

Allows for accessing user input.

math

Provides abstractions/functions for working with vectors and other math.

physics

Provides access to raycasting and physics functionality.

player

Allows for manipulating the camera and player.

timing

Facilitates access to frame and tick timing data.

Macros

include_assets

Includes all of the assets contained in the specified folder (and its subfolders). A set of modules is generated containing the IDs of each asset.

Structs

Client

Marks systems that will be instantiated on the game client.

Server

Marks systems that will be instantiated on the game server.