SDK 6.3/Rust

Official WOWCube SDK documentation. SDK 6.3, Rust API — experimental, supported track. 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.

Module wrappers (cubios)

Safe snake_case wrappers over the engine ABI, one Rust module per subsystem. Semantics are identical to the C ABI — follow the links for full per-function descriptions.

cubios::gfx

Semantics: see SDK 6.3/C++/Graphics.

pub fn get_asset_id(sprite_name: &str) -> i32   // -> GFX_getAssetId
pub fn clear(color: u32) -> i32   // -> GFX_Clear
pub fn draw_text(x: u32, y: u32, scale: u32, angle: u32, align: super::TextAlign, color: u32, text: &str) -> i32   // -> GFX_DrawText
pub fn draw_point(x: i32, y: i32, color: u32) -> i32   // -> GFX_DrawPoint
pub fn draw_circle(x: i32, y: i32, radius: u32, width: u32, color: u32) -> i32   // -> GFX_DrawCircle
pub fn draw_solid_circle(x: i32, y: i32, radius: u32, color: u32) -> i32   // -> GFX_DrawSolidCircle
pub fn draw_arc(x: i32, y: i32, radius: u32, width: u32, angle0: u32, angle1: u32, color: u32) -> i32   // -> GFX_DrawArc
pub fn draw_sector(x: i32, y: i32, radius: u32, angle0: u32, angle1: u32, color: u32) -> i32   // -> GFX_DrawSector
pub fn draw_line(x0: i32, y0: i32, x1: i32, y1: i32, thickness: u32, color: u32) -> i32   // -> GFX_DrawLine
pub fn draw_rectangle(x: i32, y: i32, w: i32, h: i32, color: u32) -> i32   // -> GFX_DrawRectangle
pub fn bake_image(id: super::SpriteId, width: u32 , height: u32, replace: u32, overwrite: u32) -> i32   // -> GFX_BakeImage
pub fn set_render_target(display: u8) -> i32   // -> GFX_SetRenderTarget
pub fn draw_image(id: super::SpriteId, x: i32, y: i32, color: u32, alpha: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: u32) -> i32   // -> GFX_DrawImage
pub fn draw_baked_image(x: i32, y: i32, color: u32, alpha: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: u32, id: super::SpriteId) -> i32   // -> GFX_DrawBakedImage
pub fn render() -> i32   // -> GFX_Render
pub fn clear_cache() -> i32   // -> GFX_ClearCache
pub fn cache_images(sprite_ids: &[super::SpriteId]) -> i32   // -> GFX_CacheImages

cubios::topology

Semantics: see SDK 6.3/C++/Topology.

pub fn get_cuben() -> u32 // Rust-only helper
pub fn get_adjacent_facelet(module: u32, screen: u32, direction: super::TopologyNeighbour, result: *mut super::TopologyFaceletInfo) -> i32   // -> TOPOLOGY_GetAdjacentFacelet
pub fn get_reversed_face(face: u32) -> Option<u32> // Rust-only helper
pub fn get_facelet(face: u32, position: u32, mode: super::TopologyOrientation, result: *mut super::TopologyFaceletInfo) -> i32   // -> TOPOLOGY_GetFacelet
pub fn get_place(module: u32, screen: u32, mode: super::TopologyOrientation, result: *mut super::TopologyPlace) -> i32   // -> TOPOLOGY_GetPlace
pub fn get_opposite_facelet(module: u32, screen: u32, result: *mut super::TopologyFaceletInfo) -> i32   // -> TOPOLOGY_GetOppositeFacelet
pub fn get_angle(module: u32, screen: u32, mode: super::TopologyOrientation) -> i32   // -> TOPOLOGY_GetAngle
pub fn get_facelet_orientation(module: u32, screen: u32) -> i32   // -> TOPOLOGY_GetFaceletOrientation
pub fn get_place_orientation(face: u32, position: u32) -> i32   // -> TOPOLOGY_GetPlaceOrientation
pub fn get_face(orientation: u32) -> i32   // -> TOPOLOGY_GetFace
pub fn is_assembled() -> i32   // -> TOPOLOGY_IsAssembled
pub fn get_twist(twist: *mut super::TopologyTwistInfo) -> i32   // -> TOPOLOGY_GetTwist
pub fn debug_get_face(module: u32, screen: u32) -> i32 // Rust-only helper
pub fn debug_get_position(module: u32, screen: u32) -> i32 // Rust-only helper

cubios::comm

Semantics: see SDK 6.3/C++/Core.

pub fn send_message(line: u32, pkt: *const u8, size: u32) -> i32   // -> sendPacket
pub fn recv_message(line: u32, size: u32, pkt_info: *mut u32, pkt: *mut u8, rx_size: *mut u32) -> i32   // -> recvPacket
pub fn get_time() -> i32   // -> getTime
pub fn get_user_name(buffer: &mut [u8]) -> i32   // -> getUserName
pub fn toggle_debug_info() -> i32   // -> toggleDebugInfo
pub fn save_state(data: &[u8]) -> i32   // -> saveState
pub fn load_state(data: &mut [u8]) -> i32   // -> loadState
pub fn random(min: u32, max: u32) -> i32   // -> random
pub fn log_a(text: &str) -> i32   // -> log_a
pub fn log_e(text: &str) -> i32   // -> log_e
pub fn log_w(text: &str) -> i32   // -> log_w
pub fn log_i(text: &str) -> i32   // -> log_i
pub fn log_d(text: &str) -> i32   // -> log_d
pub fn log_v(text: &str) -> i32   // -> log_v
pub fn get_tap() -> i32   // -> getTap

cubios::snd

Semantics: see SDK 6.3/C++/Sound.

pub fn get_asset_id(sound_name: &str) -> i32   // -> SND_getAssetId
pub fn play(sound_id: super::SoundId, volume: u32) -> i32   // -> SND_Play
pub fn cache_sounds(sound_ids: &[super::SoundId]) -> i32   // -> SND_CacheSounds

cubios::ms

Semantics: see SDK 6.3/C++/Motion Sensors.

pub fn get_face_accel_x(display: u32) -> i32   // -> MS_GetFaceAccelX
pub fn get_face_accel_y(display: u32) -> i32   // -> MS_GetFaceAccelY
pub fn get_face_accel_z(display: u32) -> i32   // -> MS_GetFaceAccelZ
pub fn get_face_gyro_x(display: u32) -> i32   // -> MS_GetFaceGyroX
pub fn get_face_gyro_y(display: u32) -> i32   // -> MS_GetFaceGyroY
pub fn get_face_gyro_z(display: u32) -> i32   // -> MS_GetFaceGyroZ

cubios::lb

Semantics: see SDK 6.3/C++/Leaderboard.

pub fn get_info(info: *mut super::LbInfo) -> i32   // -> LB_GetInfo
pub fn get_score(lead_table_bin: &mut [u8]) -> i32   // -> LB_GetScore

cubios::event

Semantics: see SDK 6.3/C++/Core.

pub fn get_list() -> cty::int32_t   // -> EVENT_getList

Rust-only helpers (get_cuben, get_reversed_face, debug_get_face, debug_get_position) have no direct C counterpart.

Application layer (application)

Beyond the plain Application trait, the crate ships a small game framework:

trait Assetable / trait Mappable / trait Packable / trait Broadcastable / trait Shuffable

Composable capabilities: asset lookup, facelet mapping, bit-packing game state into packets, broadcasting it between modules, and shuffling.

struct MapBase<T: Packable>

Base container for a distributed game map synchronized across modules.

struct SceneSwitch — new(scenes, start_time), next_scene(), set_scene(id), animate()

Scene/screen switching with animation.

struct TimerController — set_timer(id, delay, suspended), delta_time()

Programmable timers driving on_timer.

struct ApplicationContext

Holds the timer controller and per-app state; returned by app_context_mut().

struct Anim<T> / enum RotationDir / enum AppPkt / enum AppErr

Animation value helper, rotation directions, standard packet kinds, error type.

Source availability

The crate ships inside the WOWCube Development Kit (sdk/…/rust/); there is currently no official standalone GitHub repository for it. (A third-party wowcube-sdk-unofficial exists on GitHub but is not maintained by Cubios.)

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.