SDK 6.3/Rust

Official WOWCube SDK documentation. SDK 6.3, Rust API. Based on the wowcube_sdk crate shipped with the WOWCube Development Kit; the crate sources remain authoritative.

SDK 6.3 · PAWN API: Core · Graphics · Topology · Sound · Motion Sensor · Leaderboard · Splash Screen · Physics · Network · Save · Scramble · Logging
C++: Native API · Application · GFX Engine  ·  Rust: Rust API (experimental)  ·  Changelog

← SDK 6.3 · Rust

Rust cubeapps are built to WebAssembly and use the same engine ABI as the C++ native API. The Development Kit ships the wowcube_sdk crate (v0.1.0) together with buildable Rust example projects (Basics 1–3, with assets). Projects are created and built with the WOWCube SDK extension for VS Code.

Crate layout

[package]
name = "wowcube_sdk"
version = "0.1.0"
edition = "2021"

[dependencies]
cty = "0.2.2"

• wowcube_sdk::application — the Application trait, ApplicationContext, timers, animation helper (Anim), error type AppErr, and the entry helpers application_init() / application_run().
• wowcube_sdk::cubios — FFI bindings to the engine ABI and the typed submodules comm, gfx, topology.

Application trait

A cubeapp implements the Application trait; all callbacks have default no-op implementations, so you override only what you need:

pub trait Application {
    fn app_context_mut(&mut self) -> &mut ApplicationContext;

    fn on_init(&mut self)  -> Result<(), AppErr> { Ok(()) }
    fn on_tick(&mut self)  -> Result<(), AppErr> { Ok(()) }
    fn on_render(&self)    -> Result<(), AppErr> { Ok(()) }
    fn on_timer(&mut self, _timer_id: u8) -> Result<(), AppErr> { Ok(()) }

    fn set_timer(&mut self, id: u8, delay: u32, suspended: bool) -> bool { … }
}

Errors are reported through the AppErr enum (AssetNotFound, InvalidModule, InvalidTwist, SceneNotFound, …).

Entry points

The module exports two extern "C" functions which the runtime calls (from the shipped HelloWOWCube example):

#![no_main]
mod cubeapp;
use wowcube_sdk;

static mut APPLICATION: Option<cubeapp::HelloWOWCube> = None;

#[no_mangle]
pub extern "C" fn on_init(cid: u32) {
    let mut application = cubeapp::HelloWOWCube::new();
    wowcube_sdk::application::application_init(&mut application, cid);
    unsafe { APPLICATION = Some(application); }
}

#[no_mangle]
pub extern "C" fn run() {
    let application = unsafe { APPLICATION.as_mut().unwrap() };
    wowcube_sdk::application::application_run(application);
}

cid is the index of the module (0–7) the instance runs on — the same value as cubeN in C++ and SELF_ID in PAWN; it is also available as cubios::CUBE_N.

FFI types

wowcube_sdk::cubios mirrors the native types with Rust naming:

pub struct TopologyFaceletInfo { pub module: i32, pub screen: i32, pub connected: i32 }
pub struct TopologyPlace       { pub face: i32, pub position: i32 }
pub struct TopologyTwistInfo   { pub screen: i32, pub count: i32, pub direction: i32 }
pub struct LbInfo              { pub board_count: i32, pub self_position: i32,
                                 pub self_achivement: i32, pub whole_user_list_count: i32 }
pub struct GfxParticle         { ttl, vx, vy, ax, ay, explosion, velocity,
                                 duration, frequency, max, loop, time }

Enumerations: TopologyNeighbour (None/Left/Diagonal/Top/Right/Bottom), TopologyOrientation (Menu/Gravity/Splash), TopologyLocation (Up/Down/Front/Back/Left/Right), TextAlign (9 values), LogLevel, UartId; constant NET_BROADCAST = 0xFF; type aliases SoundId, SpriteId.

For the semantics of the underlying engine functions (graphics, sound, topology, sensors, leaderboard) see the native API reference — names and behavior match one-to-one.

Examples

The Development Kit ships three buildable Rust projects under examples/…/rust/Basics, each with a project/src/main.rs, cubeapp.rs, an assets/ folder and a wowcubeapp-build.json build manifest.