SDK 6.3/Rust

Official WOWCube SDK documentation. SDK 6.3, Rust API — EXPERIMENTAL. Rust support is an experimental, supported track: APIs may change between releases. The C++ (WebAssembly) API remains the primary development track.

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 compile to WebAssembly (wasm32-unknown-unknown, no_std) and use the same engine ABI as the C++ native API — with 1:1 feature parity with C++ SDK 6.3 (all graphics, topology, communication, motion, sound, leaderboard, 140+ named colors, math). One WASM module runs on all eight cube modules; each instance drives the module's three 240×240 screens.

The CubiOS Rust SDK

The SDK is a two-crate Cargo workspace (CubiOS_Rust_SDK on the corporate GitHub, github.com/wowcube/CubiOS_Rust_SDK; currently private — publication pending):

• cubios-sys — raw layer. FFI bindings to the CubiOS engine ABI plus thin safe wrappers and the application event loop. Modules: application (the Application trait, timers, event loop), comm (packets, BLE, time, saves, RNG, logging), gfx (immediate-mode drawing), topology, sound, motion, leaderboard, event, network_message / save_message (bit-packed serializers), screen, math (Vec2, Color, Transform, Rect2), types, constants.
• cubios — safe / high-level layer. A Rust port of the C++ Cubios:: classes: retained per-screen rendering (begin → add → end), Scene registry, Sprite / AnimatedSprite / SpriteAtlas / Background / Text / QRCode / OffscreenRenderTarget, Sound / SoundCollection, Scramble, Splashscreen, and 142 named colors (Colors::*). Builders are chainable; storage is heapless (no allocator).

Public API surface: 533 functions across 27 modules. Everything is no_std; the bundled minimal example builds to a ~3 KB .wasm.

Application trait

A cubeapp implements Application (from cubios_sys::ffi::application) and exports two entry points the runtime calls: on_init(cid) (module index 0–7) and run.

Callback	When
on_init()	once, after construction
on_tick(cur_time, delta_time)	every frame (ms)
on_render(&mut [Screen; 3])	module is about to draw
on_phys_tick(&[Screen; 3])	fixed-cadence physics tick
on_twist(&TopologyTwistInfo)	cube twisted
on_tap(count) / on_pat(count)	tap on a screen / opposite side
on_message(msg_type, data)	packet from another module
on_external_message(data)	BLE data from the companion app
on_timer(timer_id)	programmable timer fired
on_close()	app is closing

Timer helpers (set_timer / start_timer / stop_timer / kill_timer) come with the trait via ApplicationContext.

Quick start

#![no_std]
use cubios::high_level::gfx::{Background, Text};
use cubios::high_level::scene::SceneObjectEnum;
use cubios::high_level::screen::Screen;
use cubios::sys::ffi::application::{application_init, application_run,
                                    AppErr, Application, ApplicationContext};
use cubios::sys::ffi::screen::Screen as SysScreen;
use cubios::sys::ffi::types::{TopologyOrientation, TopologyTwistInfo};

struct HelloCube { ctx: ApplicationContext }

impl Application for HelloCube {
    fn app_context_mut(&mut self) -> &mut ApplicationContext { &mut self.ctx }
    fn on_init(&mut self) -> Result<(), AppErr> { Ok(()) }
    fn on_tick(&mut self, _t: u32, _dt: u32) -> Result<(), AppErr> { Ok(()) }

    fn on_render(&mut self, screens: &mut [SysScreen; 3]) -> Result<(), AppErr> {
        for s in screens.iter() {
            let mut screen: Screen = Screen::new(s.id());
            screen.begin(TopologyOrientation::Menu, false);
            screen.add(SceneObjectEnum::Background(Background::from_rgb(0, 0, 0)));
            screen.add(SceneObjectEnum::Text(Text::at("HELLO", 120.0, 100.0).with_font_size(24)));
            screen.add(SceneObjectEnum::Text(Text::at("WOWCUBE", 120.0, 140.0).with_font_size(24)));
            screen.end();
        }
        Ok(())
    }
    // ... remaining callbacks return Ok(())
}

static mut APPLICATION: Option<HelloCube> = None;

#[no_mangle]
pub extern "C" fn on_init(cid: u32) {
    let mut app = HelloCube { ctx: ApplicationContext::new() };
    application_init(&mut app, cid);
    unsafe { *core::ptr::addr_of_mut!(APPLICATION) = Some(app) }
}

#[no_mangle]
pub extern "C" fn run() {
    let app = unsafe { (*core::ptr::addr_of_mut!(APPLICATION)).as_mut().unwrap() };
    application_run(app);
}

Build: cargo build --release --target wasm32-unknown-unknown (the workspace config adds --allow-undefined so engine functions become WASM imports). Package and install like a C++ cubeapp via the WOWCube SDK extension for VS Code.

Conventions

Identical to the C++ SDK: colors 0xAARRGGBB (142 named Colors::*); rotation in degrees; scale in percent (100 = 1:1); inter-module packets bit-packed via NetworkMessage (≤ MESSAGE_SIZE_MAX bytes); persistent state via SaveMessage (≤ GAME_SAVE_SIZE bytes); NET_BROADCAST = 0xFF; the module index is CUBE_N.

Availability

• Experimental status: Rust support is supported but experimental — API may change; the C++ track is primary.
• The Development Kit currently ships a thin bindings crate (wowcube_sdk v0.1.0) with buildable examples (Basics 1–3).
• The full two-crate CubiOS Rust SDK described above lives on the corporate GitHub (wowcube/CubiOS_Rust_SDK) and is being prepared for publication.

For per-function semantics see the C++ native reference — names map 1:1 (gfx::draw_text → GFX_drawText).