WowWiki - User contributions [en]

SDK 6.3/Rust

2026-07-26T10:45:18Z

WowBot: Link full API reference subpages (WowBot)

{{notice|'''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 nav}}

''← [[SDK 6.3]] · Rust''

Rust cubeapps compile to WebAssembly (<code>wasm32-unknown-unknown</code>, <code>no_std</code>) and use the same engine ABI as the [[SDK 6.3/C++/Native API|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 — '''[https://github.com/wowcube/CubiOS_Rust_SDK CubiOS_Rust_SDK]''' on GitHub:

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

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

== Application trait ==

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

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

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

== 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: <code>cargo build --release --target wasm32-unknown-unknown</code> (the workspace config adds <code>--allow-undefined</code> so engine functions become WASM imports). Package and install like a C++ cubeapp via the [https://marketplace.visualstudio.com/items?itemName=cubios-inc.WOWCubeSDK WOWCube SDK extension for VS Code].

== Full API reference ==
Complete, generated from the repository sources:
* [[SDK 6.3/Rust/cubios-sys]] — raw layer: every FFI binding and safe wrapper (14 modules)
* [[SDK 6.3/Rust/cubios]] — high-level layer: every type and method (scene, screens, sprites, text, sound, splash, 142 colors)

== Conventions ==

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

== 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 (<code>wowcube_sdk</code> v0.1.0) with buildable examples (''Basics 1–3'').
* The full two-crate '''CubiOS Rust SDK''' is public: [https://github.com/wowcube/CubiOS_Rust_SDK github.com/wowcube/CubiOS_Rust_SDK] (source-available, © Cubios Inc.) — clone and build with stable Rust + <code>wasm32-unknown-unknown</code>.

For per-function semantics see the [[SDK 6.3/C++/Native API|C++ native reference]] — names map 1:1 (<code>gfx::draw_text</code> → <code>GFX_drawText</code>).

[[Category:SDK 6.3]]
[[Category:Rust API]]

SDK 6.3/Rust/cubios-sys

2026-07-26T10:45:16Z

WowBot: Fix array-type signatures (WowBot)

{{notice|'''Official WOWCube SDK documentation.''' SDK 6.3, Rust API — '''EXPERIMENTAL''' (supported; APIs may change). Generated from the [https://github.com/wowcube/CubiOS_Rust_SDK CubiOS_Rust_SDK] sources — the repository is authoritative; do not edit by hand.}}

{{SDK 6.3 nav}}

''← [[SDK 6.3]] · [[SDK 6.3/Rust|Rust]] / cubios-sys (raw layer)''

Complete reference of the '''raw layer''' crate [https://github.com/wowcube/CubiOS_Rust_SDK/tree/main/crates/cubios-sys <code>cubios-sys</code>]: FFI bindings to the CubiOS engine ABI, thin safe wrappers and the application event loop. Signatures and descriptions are extracted from the crate sources. Engine-function semantics match the [[SDK 6.3/C++/Native API|C++ native API]] one-to-one.

== ffi::application ==

The <code>Application</code> trait (11 callbacks), <code>ApplicationContext</code>, <code>TimerController</code>, the event loop (<code>application_init</code> / <code>application_run</code>), <code>Anim<T></code>, <code>AppErr</code>.

'''Types:''' <code>enum AppErr</code> · <code>enum AppPkt</code> · <code>enum RotationDir</code> · <code>struct Anim</code> · <code>struct Timer</code> · <code>trait Application</code> · <code>trait Assetable</code> · <code>trait Mappable</code> · <code>trait Packable</code> · <code>struct MapBase</code> · <code>struct SceneSwitch</code> · <code>trait Broadcastable</code> · <code>trait Shuffable</code> · <code>struct TimerController</code> · <code>struct ApplicationContext</code>

'''49 public functions:'''

; <code>Application::fn app_context_mut(&mut self) -> &mut ApplicationContext</code>

; <code>Application::fn set_timer(&mut self, id: u8, delay: u32, suspended: bool) -> bool</code>

; <code>Application::fn start_timer(&mut self, id: u8) -> bool</code>

; <code>Application::fn stop_timer(&mut self, id: u8) -> bool</code>

; <code>Application::fn kill_timer(&mut self, id: u8)</code>

; <code>Application::fn on_init(&mut self) -> Result<(), AppErr></code>
: Called once when the application initializes.

; <code>Application::fn on_tick(&mut self, cur_time: u32, delta_time: u32) -> Result<(), AppErr></code>
: Called every frame. `cur_time` is current time in ms, `delta_time` is ms since last tick.

; <code>Application::fn on_render(&mut self, screens: &mut [Screen; 3]) -> Result<(), AppErr></code>
: Called to render the current frame. `screens` contains the 3 screens for this module.

; <code>Application::fn on_phys_tick(&mut self, screens: &[Screen; 3]) -> Result<(), AppErr></code>
: Called on physics tick. `screens` contains the 3 screens for this module.

; <code>Application::fn on_twist(&mut self, twist: &TopologyTwistInfo) -> Result<(), AppErr></code>
: Called when a twist event occurs.

; <code>Application::fn on_tap(&mut self, count: u32) -> Result<(), AppErr></code>
: Called when a tap event occurs. `count` is the number of taps.

; <code>Application::fn on_pat(&mut self, count: u32) -> Result<(), AppErr></code>
: Called when a pat event occurs. `count` is the number of pats.

; <code>Application::fn on_message(&mut self, msg_type: u32, data: &[u8]) -> Result<(), AppErr></code>
: Called when a network message is received from another module.

; <code>Application::fn on_external_message(&mut self, data: &[u8]) -> Result<(), AppErr></code>
: Called when an external message is received via BLE.

; <code>Application::fn on_timer(&mut self, timer_id: u8) -> Result<(), AppErr></code>
: Called when a timer fires.

; <code>Application::fn on_close(&mut self) -> Result<(), AppErr></code>
: Called when the application is closing.

; <code>Application::fn get_time(&self) -> u32</code>
: Returns current time in milliseconds.

; <code>Application::fn get_time_seconds(&self) -> u32</code>
: Returns current time in seconds.

; <code>Application::fn is_master_module(&self) -> bool</code>
: Returns true if this module is the master (module 0).

; <code>Application::fn send_network_message(&self, msg_type: u32, data: &[u8])</code>
: Sends a network message to other modules.

; <code>Application::fn save_state(&self, data: &[u8])</code>
: Saves game state to persistent storage.

; <code>Application::fn load_state(&self, id: &mut u32, data: &mut [u8]) -> i32</code>
: Loads game state from persistent storage. Returns the number of bytes read, or negative on error.

; <code>Application::fn send_external_message(&self, msg_type: u32, data: &mut [u8])</code>
: Sends an external message via BLE.

; <code>Application::fn show_fps_counter(&self, show: bool)</code>
: Shows or hides the FPS counter overlay.

; <code>Application::fn get_image_assets_count(&self) -> i32</code>
: Returns the number of image assets available.

; <code>Application::fn get_sound_assets_count(&self) -> i32</code>
: Returns the number of sound assets available.

; <code>Assetable::fn get_asset_id(asset: &'static str) -> Result<u32, AppErr></code>

; <code>Mappable::fn get_place( &self, module: u32, screen: u32, orientation: TopologyOrientation, ) -> Result<(u32, u32), AppErr></code>

; <code>Packable::fn to_pkt(&self, module: u8, screen: u8) -> [u8; 4]</code>

; <code>Packable::fn from_pkt(pkt: [u8; 4]) -> (Self, u8, u8)</code>

; <code>fn new(val: T) -> Self</code>

; <code>Broadcastable::fn broadcast_part(&mut self, _module: u8, _screen: u8, _delay: usize) -> Result<(), AppErr></code>

; <code>Broadcastable::fn broadcast(&mut self, delay: usize) -> Result<(), AppErr></code>

; <code>Broadcastable::fn recv(&mut self, pkt: [u8; 4]) -> Result<(), AppErr></code>

; <code>Shuffable::fn rotate(&mut self, dir: &RotationDir) -> Result<(), AppErr></code>

; <code>Shuffable::fn shuffle(&mut self, algo: &[RotationDir]) -> Result<(), AppErr></code>

; <code>fn new(scenes: &'static [usize], start_time: usize) -> Self</code>

; <code>fn next_scene(&mut self)</code>

; <code>fn set_scene(&mut self, id: u8) -> Result<(), AppErr></code>

; <code>fn animate(&mut self)</code>

; <code>fn new() -> Self</code>
: Create a new TimerController with no active timers.

; <code>fn set_timer(&mut self, id: u8, delay: u32, suspended: bool) -> bool</code>

; <code>fn start_timer(&mut self, id: u8) -> bool</code>

; <code>fn stop_timer(&mut self, id: u8) -> bool</code>

; <code>fn kill_timer(&mut self, id: u8)</code>

; <code>fn delta_time(&self) -> u32</code>

; <code>fn new() -> Self</code>
: Create a new ApplicationContext.

; <code>fn application_init<T: Application>(app: &mut T, cid: u32)</code>

; <code>fn application_run<T: Application>(app: &mut T)</code>

== ffi::comm ==

Inter-module packets and UART lines, BLE external data, time, user name, state save/load, RNG, logging (<code>log_a</code>…<code>log_v</code>), tap.

'''22 public functions:'''

; <code>fn send_message(line: u32, pkt: *const u8, size: u32) -> i32</code>

; <code>fn send_message_to(line: u32, dest: u32, pkt: *const u8, size: u32) -> i32</code>

; <code>fn recv_message( line: u32, size: u32, pkt_info: *mut u32, pkt: *mut u8, rx_size: *mut u32, ) -> i32</code>

; <code>fn send_packet(packet_type: u32, pkt: &[u8]) -> i32</code>
: Send a packet (new API in SDK 6.3)

; <code>fn recv_packet(size: u32, packet_type: *mut u32, pkt: *mut u8) -> i32</code>
: Receive a packet (new API in SDK 6.3) Returns the number of bytes received, or negative on error. The packet type is written to `packet_type`.

; <code>fn get_time() -> i32</code>

; <code>fn get_user_name(buffer: &mut [u8]) -> i32</code>

; <code>fn toggle_debug_info() -> i32</code>

; <code>fn save_state(data: &[u8]) -> i32</code>

; <code>fn load_state(id: &mut u32, data: &mut [u8]) -> i32</code>
: Load saved state Returns the number of bytes loaded, or negative on error. The save ID is written to `id`.

; <code>fn load_state_legacy(data: &mut [u8]) -> i32</code>
: Load saved state (legacy API without ID) Note: This ignores the save ID. Use `load_state` for full functionality.

; <code>fn random_range(min: u32, max: u32) -> i32</code>

; <code>fn get_app_version() -> AppVersion</code>
: Get the application version

; <code>fn log_a(text: &str) -> i32</code>

; <code>fn log_e(text: &str) -> i32</code>

; <code>fn log_w(text: &str) -> i32</code>

; <code>fn log_i(text: &str) -> i32</code>

; <code>fn log_d(text: &str) -> i32</code>

; <code>fn log_v(text: &str) -> i32</code>

; <code>fn get_tap() -> i32</code>

; <code>fn send_ble_data(data_type: u32, pkt: &mut [u8]) -> i32</code>
: Send BLE data

; <code>fn recv_ble_data(pkt: &mut [u8]) -> i32</code>
: Receive BLE data

== ffi::gfx ==

Immediate-mode drawing: clear, primitives, text, images, baked images, sub-images, shaders, QR, render target, cache.

'''26 public functions:'''

; <code>fn get_asset_id(sprite_name: &str) -> i32</code>

; <code>fn clear(color: u32) -> i32</code>

; <code>fn draw_text( x: i32, y: i32, scale: u32, angle: u32, align: TextAlign, color: u32, text: &str, ) -> i32</code>

; <code>fn draw_point(x: i32, y: i32, color: u32) -> i32</code>

; <code>fn draw_circle(x: u32, y: u32, radius: u32, width: u32, color: u32) -> i32</code>

; <code>fn draw_solid_circle(x: u32, y: u32, radius: u32, color: u32) -> i32</code>
: Deprecated: use `set_fill_shader` + `draw_circle` instead

; <code>fn draw_arc( x: i32, y: i32, radius: u32, width: u32, angle0: u32, angle1: u32, color: u32, ) -> i32</code>

; <code>fn draw_sector(x: i32, y: i32, radius: u32, angle0: u32, angle1: u32, color: u32) -> i32</code>

; <code>fn draw_line(x0: i32, y0: i32, x1: i32, y1: i32, thickness: u32, color: u32) -> i32</code>

; <code>fn draw_rectangle(x: i32, y: i32, w: i32, h: i32, color: u32) -> i32</code>

; <code>fn bake_image( id: SpriteId, width: u32, height: u32, format: GfxPixelFormat, overwrite: bool, ) -> i32</code>
: Bake an image to an offscreen buffer # Arguments * `id` - Sprite ID to bake * `width` - Width of the baked image * `height` - Height of the baked image * `format` - Pixel format for the baked image * `overwrite` - Whether to overwrite existing baked image

; <code>fn remove_baked_image(id: SpriteId) -> i32</code>
: Remove a previously baked image

; <code>fn set_render_target(display: u8) -> i32</code>

; <code>fn draw_image( id: SpriteId, x: i32, y: i32, opacity: u32, color_key: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: GfxMirror, ) -> i32</code>

; <code>fn draw_baked_image( x: i32, y: i32, opacity: u32, color_key: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: GfxMirror, id: SpriteId, ) -> i32</code>

; <code>fn draw_sub_image( id: SpriteId, x: i32, y: i32, rect_x: u32, rect_y: u32, rect_w: u32, rect_h: u32, opacity: u32, color_key: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: GfxMirror, ) -> i32</code>
: Draw a sub-region of a sprite (for sprite atlases)

; <code>fn draw_qr_code( x: i32, y: i32, size: u32, color0: u32, color1: u32, angle: u32, id: u32, text: &str, ) -> i32</code>
: Draw a QR code

; <code>fn render() -> i32</code>

; <code>fn clear_cache() -> i32</code>

; <code>fn cache_images(sprite_ids: &[SpriteId]) -> i32</code>

; <code>fn get_assets_count() -> i32</code>
: Get the total number of image assets

; <code>fn set_fps_window(size: u32) -> i32</code>
: Set the FPS counter window size

; <code>fn set_fill_shader(color: u32) -> i32</code>
: Set a solid fill shader When active, drawing operations will use this color to fill shapes.

; <code>fn set_linear_gradient_shader( x0: u32, y0: u32, x1: u32, y1: u32, color0: u32, color1: u32, ) -> i32</code>
: Set a linear gradient shader # Arguments * `x0`, `y0` - Start point of the gradient * `x1`, `y1` - End point of the gradient * `color0` - Start color * `color1` - End color

; <code>fn set_radial_gradient_shader(x0: u32, y0: u32, radius: u32, color0: u32, color1: u32) -> i32</code>
: Set a radial gradient shader # Arguments * `x0`, `y0` - Center point of the gradient * `radius` - Radius of the gradient * `color0` - Center color * `color1` - Edge color

; <code>fn remove_shader() -> i32</code>
: Remove the active shader

== ffi::topology ==

Facelets, faces, places, orientation, twists, assembly check.

'''15 public functions:'''

; <code>fn get_cuben() -> u32</code>

; <code>fn get_adjacent_facelet( module: u32, screen: u32, direction: TopologyNeighbour, result: *mut TopologyFaceletInfo, ) -> i32</code>

; <code>fn get_reversed_face(face: u32) -> Option<u32></code>

; <code>fn get_facelet( face: u32, position: u32, mode: TopologyOrientation, result: *mut TopologyFaceletInfo, ) -> i32</code>

; <code>fn get_place( module: u32, screen: u32, mode: TopologyOrientation, result: *mut TopologyPlace, ) -> i32</code>

; <code>fn get_opposite_facelet(module: u32, screen: u32, result: *mut TopologyFaceletInfo) -> i32</code>

; <code>fn get_angle(module: u32, screen: u32, mode: TopologyOrientation) -> i32</code>

; <code>fn get_facelet_orientation(module: u32, screen: u32) -> i32</code>

; <code>fn get_place_orientation(face: u32, position: u32) -> i32</code>

; <code>fn get_face(orientation: u32) -> i32</code>

; <code>fn is_assembled() -> bool</code>

; <code>fn get_twist(twist: *mut TopologyTwistInfo) -> i32</code>

; <code>fn debug_get_face(module: u32, screen: u32) -> i32</code>

; <code>fn debug_get_position(module: u32, screen: u32) -> i32</code>

; <code>fn debug_get_horizontal() -> i32</code>

== ffi::sound ==

Sound asset id, play, cache, stop, status.

'''6 public functions:'''

; <code>fn get_asset_id(sound_name: &str) -> i32</code>

; <code>fn play(sound_id: SoundId, volume: u32) -> i32</code>

; <code>fn cache_sounds(sound_ids: &[SoundId]) -> i32</code>

; <code>fn is_playing() -> bool</code>
: Check if a sound is currently playing

; <code>fn stop() -> i32</code>
: Stop the currently playing sound

; <code>fn get_assets_count() -> i32</code>
: Get the total number of sound assets

== ffi::motion ==

Per-display accelerometer and gyroscope.

'''8 public functions:'''

; <code>fn get_face_accel_x(display: u32) -> i32</code>
: Get raw accelerometer value along the screen-local X-axis (horizontal right). At rest, this reads the X-component of gravity in the screen's coordinate frame. During motion, reads gravity + linear acceleration. # Parameters - `display`: Screen index (0–23). All 3 screens on a module return the same physical measurement, transformed to screen-local coordinates.

; <code>fn get_face_accel_y(display: u32) -> i32</code>
: Get raw accelerometer value along the screen-local Y-axis (vertical up). See [`get_face_accel_x`] for details on data format and coordinate frame.

; <code>fn get_face_accel_z(display: u32) -> i32</code>
: Get raw accelerometer value along the screen-local Z-axis (toward cube center). When this screen faces up, Z reads approximately -1g (gravity pulls toward center). When this screen faces down, Z reads approximately +1g. See [`get_face_accel_x`] for details on data format and coordinate frame.

; <code>fn get_face_gyro_x(display: u32) -> i32</code>
: Get raw gyroscope value for rotation around the screen-local X-axis. Measures angular velocity of the screen pitching up/down. At rest, reads approximately zero. Sign convention: positive = clockwise when looking along the positive X-axis direction (per SDK docs, unverified). # Parameters - `display`: Screen index (0–23). Same sensor sharing as accelerometer.

; <code>fn get_face_gyro_y(display: u32) -> i32</code>
: Get raw gyroscope value for rotation around the screen-local Y-axis. Measures angular velocity of the screen yawing left/right. See [`get_face_gyro_x`] for details.

; <code>fn get_face_gyro_z(display: u32) -> i32</code>
: Get raw gyroscope value for rotation around the screen-local Z-axis. Measures angular velocity of the screen spinning in-plane (like a wheel). See [`get_face_gyro_x`] for details.

; <code>fn get_face_accel(display: u32) -> (i32, i32, i32)</code>
: Get all 3 accelerometer axes for a screen in one call. Returns `(x, y, z)` in screen-local coordinates. Equivalent to calling [`get_face_accel_x`], [`get_face_accel_y`], and [`get_face_accel_z`] separately. # Parameters - `display`: Screen index (0–23).

; <code>fn get_face_gyro(display: u32) -> (i32, i32, i32)</code>
: Get all 3 gyroscope axes for a screen in one call. Returns `(x, y, z)` angular velocities in screen-local coordinates. Equivalent to calling [`get_face_gyro_x`], [`get_face_gyro_y`], and [`get_face_gyro_z`] separately. # Parameters - `display`: Screen index (0–23).

== ffi::leaderboard ==

Leaderboard info and score table.

'''3 public functions:'''

; <code>fn get_info(info: *mut LbInfo) -> i32</code>

; <code>fn get_info_safe() -> LbInfo</code>
: Get leaderboard info with safe interface

; <code>fn get_score(lead_table_bin: &mut [u8]) -> i32</code>

== ffi::event ==

Pending-event mask (<code>Event</code>, <code>get_list</code>).

'''Types:''' <code>enum Event</code> — Event flags returned by `get_list()`

'''2 public functions:'''

; <code>fn get_list() -> i32</code>

; <code>fn has_event(event_list: i32, event: Event) -> bool</code>
: Check if a specific event is set in the event list

== ffi::network_message ==

Bit-packed serializer for inter-module messages.

'''Types:''' <code>struct NetworkMessage</code> — Bit-packed network message for inter-module communication. Allows packing multiple values into a compact byte buffer using variable bit widths for efficient network transmission.

'''17 public functions:'''

; <code>fn new() -> Self</code>
: Create a new empty network message.

; <code>fn from_data(data: &[u8]) -> Self</code>
: Create a network message from existing data.

; <code>fn reset(&mut self, zero: bool)</code>
: Reset the message position. If `zero` is true, also clear the buffer.

; <code>fn get_data(&self) -> &[u8]</code>
: Get the underlying data buffer and used length.

; <code>fn can_read(&self, bits: usize) -> bool</code>
: Returns true if at least `bits` more bits can be read from the current position.

; <code>fn write_int(&mut self, value: u32, bits: u8)</code>
: Write an unsigned integer with specified bit width (1-32 bits). This writes raw bits without sign handling. For signed values that need sign extension when read back, use [`write_signed_int`](Self::write_signed_int). # Arguments * `value` - The unsigned value to write (only the lower `bits` bits are used) * `bits` - Number of bits to write (1-32, clamped if larger) # Note on C++ SDK difference The C++ `WriteInt` uses `int` (signed), but performs unsigned bit operations. This Rust version uses `u32` to make the unsigned semantics explicit.

; <code>fn write_byte(&mut self, value: u8)</code>
: Write a single byte (8 bits).

; <code>fn write_signed_int(&mut self, value: i32, bits: u8)</code>
: Write a signed integer with specified bit width.

; <code>fn write_bool(&mut self, value: bool)</code>
: Write a boolean (1 bit).

; <code>fn write_float(&mut self, value: f32)</code>
: Write a 32-bit float.

; <code>fn read_int(&mut self, bits: u8) -> u32</code>
: Read an unsigned integer with specified bit width. This reads raw bits without sign extension. For signed values that were written with [`write_signed_int`](Self::write_signed_int), use [`read_signed_int`](Self::read_signed_int) to properly sign-extend. # Arguments * `bits` - Number of bits to read (1-32, clamped if larger) # Returns The unsigned value read from the message buffer. # Note on C++ SDK difference The C++ `ReadInt` returns `int` (signed), but performs unsigned bit operations. This Rust version returns `u32` to make the unsigned semantics explicit.

; <code>fn read_byte(&mut self) -> u8</code>
: Read a single byte.

; <code>fn read_signed_int(&mut self, bits: u8) -> i32</code>
: Read a signed integer with specified bit width.

; <code>fn read_bool(&mut self) -> bool</code>
: Read a boolean.

; <code>fn read_float(&mut self) -> f32</code>
: Read a 32-bit float.

; <code>fn position(&self) -> usize</code>
: Get current bit position.

; <code>fn can_write(&self, bits: usize) -> bool</code>
: Check if there's enough space to write `bits` more bits.

== ffi::save_message ==

Bit-packed serializer for the persistent save buffer.

'''Types:''' <code>struct SaveMessage</code> — Bit-packed save message for game state persistence. Allows packing multiple values into a compact byte buffer using variable bit widths for efficient save data storage.

'''18 public functions:'''

; <code>fn new() -> Self</code>
: Create a new empty save message.

; <code>fn from_data(data: &[u8]) -> Self</code>
: Create a save message from existing data.

; <code>fn reset(&mut self, zero: bool)</code>
: Reset the message position. If `zero` is true, also clear the buffer.

; <code>fn get_data(&self) -> &[u8]</code>
: Get the underlying data buffer (only the used portion).

; <code>fn get_buffer_mut(&mut self) -> &mut [u8]</code>
: Get the full buffer for loading saved data.

; <code>fn write_int(&mut self, value: u32, bits: u8)</code>
: Write an unsigned integer with specified bit width (1-32 bits). This writes raw bits without sign handling. For signed values that need sign extension when read back, use [`write_signed_int`](Self::write_signed_int). # Arguments * `value` - The unsigned value to write (only the lower `bits` bits are used) * `bits` - Number of bits to write (1-32, clamped if larger) # Note on C++ SDK difference The C++ `WriteInt` uses `int` (signed), but performs unsigned bit operations. This Rust version uses `u32` to make the unsigned semantics explicit.

; <code>fn write_byte(&mut self, value: u8)</code>
: Write a single byte (8 bits).

; <code>fn write_signed_int(&mut self, value: i32, bits: u8)</code>
: Write a signed integer with specified bit width.

; <code>fn write_bool(&mut self, value: bool)</code>
: Write a boolean (1 bit).

; <code>fn write_float(&mut self, value: f32)</code>
: Write a 32-bit float.

; <code>fn read_int(&mut self, bits: u8) -> u32</code>
: Read an unsigned integer with specified bit width. This reads raw bits without sign extension. For signed values that were written with [`write_signed_int`](Self::write_signed_int), use [`read_signed_int`](Self::read_signed_int) to properly sign-extend. # Arguments * `bits` - Number of bits to read (1-32, clamped if larger) # Returns The unsigned value read from the save buffer. # Note on C++ SDK difference The C++ `ReadInt` returns `int` (signed), but performs unsigned bit operations. This Rust version returns `u32` to make the unsigned semantics explicit.

; <code>fn read_byte(&mut self) -> u8</code>
: Read a single byte.

; <code>fn read_signed_int(&mut self, bits: u8) -> i32</code>
: Read a signed integer with specified bit width.

; <code>fn read_bool(&mut self) -> bool</code>
: Read a boolean.

; <code>fn read_float(&mut self) -> f32</code>
: Read a 32-bit float.

; <code>fn position(&self) -> usize</code>
: Get current bit position.

; <code>fn can_write(&self, bits: usize) -> bool</code>
: Check if there's enough space to write `bits` more bits.

; <code>fn set_used_bits(&mut self, bits: usize)</code>
: Set the number of used bits (for after loading data).

== ffi::screen ==

Low-level screen descriptor (id, angle, face, position) + <code>create_screens()</code>.

'''Types:''' <code>struct Screen</code> — Represents a screen on a WOWCube module. Each module has 3 screens. This struct provides access to screen properties like position, orientation, and display ID for rendering purposes.

'''7 public functions:'''

; <code>fn new(display_id: u8) -> Self</code>
: Creates a new Screen for the given display ID on this module.

; <code>fn id(&self) -> u8</code>
: Returns the display ID (0-2).

; <code>fn angle(&self) -> u32</code>
: Returns the current rotation angle.

; <code>fn position(&self) -> u32</code>
: Returns the position in the topology.

; <code>fn face(&self) -> i32</code>
: Returns the face this screen is on.

; <code>fn update_from_topology(&mut self, module: u32, orientation: TopologyOrientation)</code>
: Updates screen topology information from the system.

; <code>fn create_screens() -> [Screen; 3]</code>
: Creates an array of 3 screens for a module, initialized with display IDs 0, 1, 2.

== ffi::math ==

<code>Vec2</code>/<code>Vec2i</code>, <code>Color</code>, <code>Transform</code>, <code>Rect2</code>, trigonometry and fixed-point helpers (no_std, libm).

'''Types:''' <code>struct Vec2</code> — 2D vector with floating-point components. · <code>struct Vec2i</code> — 2D vector with integer components. · <code>struct Color</code> — ARGB color with 8-bit components. Stored as a packed u32 in ARGB format: 0xAARRGGBB · <code>struct Transform</code> — Transform with position, rotation, scale, and mirroring. · <code>struct Rect2</code> — 2D rectangle defined by top-left and dimensions.

'''57 public functions:'''

; <code>fn log2(f: f32) -> f32</code>
: Log base 2.

; <code>fn iclamp(val: i32, min_val: i32, max_val: i32) -> i32</code>
: Clamp an integer value between min and max.

; <code>fn acos(x: f32) -> f32</code>
: Arc cosine with value clamping to [-1, 1].

; <code>fn asin(x: f32) -> f32</code>
: Arc sine with value clamping to [-1, 1].

; <code>fn sqrt(x: f32) -> f32</code>
: Safe square root (negative values return 0).

; <code>fn fequal(f0: f32, f1: f32, tol: f32) -> bool</code>
: Fuzzy floating point equality check.

; <code>fn fless(f0: f32, f1: f32, tol: f32) -> bool</code>
: Fuzzy floating point less-than check.

; <code>fn fgreater(f0: f32, f1: f32, tol: f32) -> bool</code>
: Fuzzy floating point greater-than check.

; <code>fn ftol(val: f32) -> i32</code>
: Fast float to int conversion (truncates). Note: This is a portable implementation that matches the C++ SDK behavior.

; <code>fn smooth(new_val: f32, cur_val: f32, max_change: f32) -> f32</code>
: Smooth a value towards a target using max change per step.

; <code>fn clamp(val: f32, lower: f32, upper: f32) -> f32</code>
: Clamp a float value between lower and upper bounds.

; <code>fn saturate(val: f32) -> f32</code>
: Saturate a value (clamp between 0.0 and 1.0).

; <code>fn deg2rad(d: f32) -> f32</code>
: Convert degrees to radians.

; <code>fn rad2deg(r: f32) -> f32</code>
: Convert radians to degrees.

; <code>fn n_abs(a: f32) -> f32</code>
: Get the absolute value.

; <code>fn n_sgn(a: f32) -> i32</code>
: Get the sign of a value (-1 or 1).

; <code>fn n_max<T: PartialOrd>(a: T, b: T) -> T</code>
: Return the maximum of two values.

; <code>fn n_min<T: PartialOrd>(a: T, b: T) -> T</code>
: Return the minimum of two values.

; <code>fn lerp(x: f32, y: f32, l: f32) -> f32</code>
: Linearly interpolate between two values. Returns `x + l * (y - x)`.

; <code>fn rand_get_seed() -> u32</code>
: Get the current random seed.

; <code>fn rand_set_seed(s: u32)</code>
: Set the random seed.

; <code>fn rand() -> u32</code>
: Generate a random u32 using LCG algorithm.

; <code>fn rand2() -> f32</code>
: Return a pseudo random number between 0.0 and 1.0.

; <code>fn rand_int(n: i32) -> i32</code>
: Return a random integer in range [0, n].

; <code>fn rand_real() -> f32</code>
: Return a random float in [0.0, 1.0].

; <code>fn new(x: f32, y: f32) -> Self</code>
: Create a new vector.

; <code>fn zero() -> Self</code>
: Zero vector.

; <code>fn set(&mut self, x: f32, y: f32)</code>
: Set components.

; <code>fn len(&self) -> f32</code>
: Calculate length.

; <code>fn normalize(&mut self)</code>
: Normalize in place.

; <code>fn normalized(&self) -> Self</code>
: Return normalized copy.

; <code>fn dot(&self, other: &Self) -> f32</code>
: Dot product.

; <code>fn new(x: i16, y: i16) -> Self</code>
: Create a new vector.

; <code>fn zero() -> Self</code>
: Zero vector.

; <code>fn rgb(r: u8, g: u8, b: u8) -> Self</code>
: Create from RGB (alpha = 255).

; <code>fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self</code>
: Create from RGBA.

; <code>fn from_u32(value: u32) -> Self</code>
: Create from packed u32 value (0xAARRGGBB format).

; <code>fn value(&self) -> u32</code>
: Get the packed u32 value.

; <code>fn r(&self) -> u8</code>
: Get red component.

; <code>fn g(&self) -> u8</code>
: Get green component.

; <code>fn b(&self) -> u8</code>
: Get blue component.

; <code>fn a(&self) -> u8</code>
: Get alpha component.

; <code>fn a_f32(&self) -> f32</code>
: Get alpha as float (0.0 - 1.0).

; <code>fn set_r(&mut self, r: u8)</code>
: Set red component.

; <code>fn set_g(&mut self, g: u8)</code>
: Set green component.

; <code>fn set_b(&mut self, b: u8)</code>
: Set blue component.

; <code>fn set_a(&mut self, a: u8)</code>
: Set alpha component.

; <code>fn set_a_f32(&mut self, a: f32)</code>
: Set alpha from float (0.0 - 1.0).

; <code>fn new(x: f32, y: f32) -> Self</code>
: Create a new transform at position.

; <code>fn with_rotation(x: f32, y: f32, rotation: i32) -> Self</code>
: Create with position and rotation.

; <code>fn with_scale(x: f32, y: f32, rotation: i32, scale: u32) -> Self</code>
: Create with position, rotation, and uniform scale.

; <code>fn safe_rotation(&self) -> i32</code>
: Get rotation normalized to 0-359.

; <code>fn set_scale(&mut self, scale: u32)</code>
: Set uniform scale.

; <code>fn new(x: i16, y: i16, w: i16, h: i16) -> Self</code>
: Create a new rectangle.

; <code>fn contains(&self, px: i16, py: i16) -> bool</code>
: Check if a point is inside the rectangle.

; <code>fn contains_point(&self, p: Vec2i) -> bool</code>
: Check if point (as Vec2i) is inside.

; <code>fn center(&self) -> Vec2i</code>
: Get the center point.

== ffi::types ==

ABI enums and structs (<code>TopologyFaceletInfo</code>, <code>TopologyTwistInfo</code>, <code>TextAlign</code>, <code>GfxMirror</code>, …).

'''Types:''' <code>enum UartId</code> — UART line identifiers · <code>enum GfxPixelFormat</code> — Pixel format for baked images · <code>enum GfxMirror</code> — Mirror mode for sprites · <code>enum TopologyNeighbour</code> — Topology neighbor direction · <code>enum TopologyOrientation</code> — Topology orientation mode · <code>enum TopologyTwist</code> — Twist direction for cube rotations · <code>enum TextAlign</code> — Text alignment options · <code>enum TopologyLocation</code> — Topology face location · <code>enum LogLevel</code> — Log level for debug output · <code>struct TopologyFaceletInfo</code> — Information about a facelet in the topology · <code>struct TopologyPlace</code> — Place information (face and position) · <code>struct TopologyTwistInfo</code> — Twist event information · <code>struct LbInfo</code> — Leaderboard information · <code>struct GfxParticle</code> — Particle effect parameters · <code>struct AppVersion</code> — Application version (packed bitfield in C++)

'''4 public functions:'''

; <code>fn from_u32(value: u32) -> Self</code>
: Converts a u32 value to a GfxMirror variant. Returns `GfxMirror::None` for invalid values.

; <code>fn patch(&self) -> u16</code>
: Extract patch version (bits 0-15)

; <code>fn minor(&self) -> u8</code>
: Extract minor version (bits 16-19)

; <code>fn major(&self) -> u8</code>
: Extract major version (bits 20-23)

== ffi::constants ==

Platform constants (screen size, module counts, buffer limits, <code>CUBE_N</code>).

[[Category:SDK 6.3]]
[[Category:Rust API]]

SDK 6.3/Rust/cubios

2026-07-26T10:44:43Z

WowBot: Full Rust API reference: cubios-sys + cubios, every pub fn with docs (WowBot)

{{notice|'''Official WOWCube SDK documentation.''' SDK 6.3, Rust API — '''EXPERIMENTAL''' (supported; APIs may change). Generated from the [https://github.com/wowcube/CubiOS_Rust_SDK CubiOS_Rust_SDK] sources — the repository is authoritative; do not edit by hand.}}

{{SDK 6.3 nav}}

''← [[SDK 6.3]] · [[SDK 6.3/Rust|Rust]] / cubios (safe high-level layer)''

Complete reference of the '''high-level layer''' crate [https://github.com/wowcube/CubiOS_Rust_SDK/tree/main/crates/cubios <code>cubios</code>]: a Rust port of the C++ <code>Cubios::</code> classes — scene graph, screens, sprites, text, sound, scramble and splash screen. Builders are chainable; storage is <code>heapless</code>; everything is <code>no_std</code>. The crate re-exports the raw layer as <code>cubios::sys</code>.

== high_level::screen ==

Retained per-frame screen: <code>begin(orientation, auto_rotation)</code> → <code>add(object)</code> → <code>end()</code>; topology accessors.

'''Types:''' <code>struct Screen</code> — Per-screen rendering context. Manages rendering to a specific display, handling orientation and providing a queue for scene objects. # Type Parameters * `MAX_OBJECTS` - Maximum number of objects in the render queue (default: 16).

'''22 public functions:'''

; <code>fn new(display_id: u8) -> Self</code>
: Creates a new screen context for the specified display. # Arguments * `display_id` - Display ID (0-23, corresponding to the 24 screens).

; <code>fn display_id(&self) -> u8</code>
: Returns the display ID.

; <code>fn module(&self) -> u8</code>
: Returns the module ID.

; <code>fn screen_in_module(&self) -> u8</code>
: Returns the screen index within the module.

; <code>fn angle(&self) -> u32</code>
: Returns the current screen angle. This angle should be passed to `SceneObject::render()` for proper orientation handling.

; <code>fn orientation_mode(&self) -> TopologyOrientation</code>
: Returns the current orientation mode.

; <code>fn auto_rotation(&self) -> bool</code>
: Returns whether auto-rotation is enabled.

; <code>fn is_in_begin(&self) -> bool</code>
: Returns whether we're currently between begin() and end().

; <code>fn object_count(&self) -> usize</code>
: Returns the number of objects in the render queue.

; <code>fn begin(&mut self, mode: TopologyOrientation, auto_rotation: bool)</code>
: Begins rendering to this screen. Sets the render target and computes the screen angle based on the current topology. # Arguments * `mode` - Orientation mode for angle computation. * `auto_rotation` - Whether to auto-rotate based on topology.

; <code>fn end(&mut self)</code>
: Ends rendering to this screen. Renders all queued objects and calls `gfx::render()` to present.

; <code>fn add(&mut self, object: SceneObjectEnum) -> bool</code>
: Adds an object to the render queue. Returns `true` if successful, `false` if the queue is full.

; <code>fn remove(&mut self, index: usize) -> Option<SceneObjectEnum></code>
: Removes an object from the render queue by index. Returns the removed object if found.

; <code>fn clear(&mut self)</code>
: Clears all objects from the render queue.

; <code>fn get(&self, index: usize) -> Option<&SceneObjectEnum></code>
: Gets an object from the queue by index.

; <code>fn get_mut(&mut self, index: usize) -> Option<&mut SceneObjectEnum></code>
: Gets a mutable reference to an object by index.

; <code>fn iter(&self) -> impl Iterator<Item = &SceneObjectEnum></code>
: Iterates over all objects in the queue.

; <code>fn iter_mut(&mut self) -> impl Iterator<Item = &mut SceneObjectEnum></code>
: Iterates mutably over all objects in the queue.

; <code>fn render_immediate(&self, object: &impl SceneObject)</code>
: Renders an object immediately without adding to queue. The object is rendered using the current screen angle. Call this between `begin()` and `end()`.

; <code>fn present(&mut self)</code>
: Renders the screen without the queue (manual mode). Use this when you want to render objects directly without using the object queue. Call `begin()`, render your objects with the screen's angle, then call `present()`.

; <code>fn for_each_screen<F>(mode: TopologyOrientation, auto_rotation: bool, mut render_fn: F) where F: FnMut(&Screen<1>),</code>
: Helper to render to all screens in a loop. This is a common pattern for WOWCube apps that render the same content to all 24 screens. # Example ```no_run use wowcube_sys::high_level::screen::for_each_screen; use wowcube_sys::high_level::gfx::Background; use wowcube_sys::high_level::scene::SceneObject; use wowcube_sys::high_level::Color; use wowcube_sys::ffi::types::TopologyOrientation; let background = Background::new(Color::rgb(0, 0, 128)); for_each_screen(TopologyOrientation::Menu, true, |screen| { background.render(screen.angle()); }); ```

; <code>fn for_face_screens<F>( face: u8, mode: TopologyOrientation, auto_rotation: bool, mut render_fn: F, ) where F: FnMut(&Screen<1>, u8), // screen, position on face (0-3)</code>
: Helper to render to screens on specific faces. Renders to the 4 screens on the specified face. # Arguments * `face` - Face index (0-5). * `mode` - Orientation mode. * `auto_rotation` - Whether to auto-rotate. * `render_fn` - Function to call for each screen.

== high_level::scene ==

<code>Scene<MAX_OBJECTS, MAX_SOUNDS></code> object registry, <code>SceneObjectEnum</code>, <code>SceneObjectBase</code> builder.

'''Types:''' <code>trait SceneObject</code> — Base trait for all renderable scene objects. Matches C++ SDK's `Cubios::SceneObject` virtual class pattern. All scene objects must implement this trait to be rendered. · <code>struct SceneObjectBase</code> — Common fields for scene objects, use via composition. This struct provides the base fields that all scene objects need. Use it via composition in your custom scene objects. · <code>enum SceneObjectEnum</code> — Enum wrapper for heterogeneous scene object storage (no_std compatible). Instead of using `Box<dyn SceneObject>`, this enum allows storing different scene object types in fixed-size arrays without heap allocation. · <code>struct Scene</code> — Scene container managing objects by ID. Matches C++ SDK's `Cubios::Scene` class. Uses fixed-size arrays for no_std compatibility. # Type Parameters - `MAX_OBJECTS`: Maximum number of scene objects (default: 32) - `MAX_SOUNDS`: Maximum number of sounds (default: 16)

'''28 public functions:'''

; <code>SceneObject::fn render(&self, screen_angle: u32)</code>
: Render this object to the current render target. Called within Screen::begin/end block. `screen_angle` is the rotation angle for auto-rotation support.

; <code>SceneObject::fn transform_mut(&mut self) -> &mut Transform</code>
: Get mutable reference to transform

; <code>SceneObject::fn transform(&self) -> &Transform</code>
: Get reference to transform

; <code>SceneObject::fn color_mut(&mut self) -> &mut Color</code>
: Get mutable reference to color

; <code>SceneObject::fn color(&self) -> &Color</code>
: Get reference to color

; <code>SceneObject::fn is_visible(&self) -> bool</code>
: Visibility flag

; <code>SceneObject::fn set_visible(&mut self, visible: bool)</code>
: Set visibility

; <code>fn at(x: f32, y: f32) -> Self</code>
: Create with position

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Set position (builder pattern)

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Set rotation (builder pattern)

; <code>fn with_scale(mut self, scale: u32) -> Self</code>
: Set uniform scale (builder pattern)

; <code>fn with_color(mut self, color: Color) -> Self</code>
: Set color (builder pattern)

; <code>fn with_alpha(mut self, alpha: u8) -> Self</code>
: Set alpha (builder pattern)

; <code>fn new() -> Self</code>
: Create a new empty scene

; <code>fn create_object(&mut self, obj: SceneObjectEnum) -> Option<ObjectId></code>
: Create object with auto-assigned ID. Returns the assigned ID, or None if the scene is full.

; <code>fn create_object_with_id(&mut self, id: ObjectId, obj: SceneObjectEnum) -> bool</code>
: Create object with specific ID. Returns false if the ID is already in use or scene is full.

; <code>fn get(&self, id: ObjectId) -> Option<&SceneObjectEnum></code>
: Get object by ID

; <code>fn get_mut(&mut self, id: ObjectId) -> Option<&mut SceneObjectEnum></code>
: Get mutable object by ID

; <code>fn dispose(&mut self, id: ObjectId) -> bool</code>
: Remove object by ID

; <code>fn dispose_all(&mut self)</code>
: Remove all objects

; <code>fn object_count(&self) -> usize</code>
: Get the number of objects in the scene

; <code>fn create_sound(&mut self, sound: super::sound::Sound) -> Option<u32></code>
: Create sound with auto-assigned ID

; <code>fn create_sound_with_id(&mut self, id: u32, sound: super::sound::Sound) -> bool</code>
: Create sound with specific ID

; <code>fn play(&self, id: u32, volume: u32)</code>
: Play sound by ID

; <code>fn dispose_sound(&mut self, id: u32) -> bool</code>
: Remove sound by ID

; <code>fn iter(&self) -> impl Iterator<Item = (ObjectId, &SceneObjectEnum)></code>
: Iterate over all objects

; <code>fn iter_mut(&mut self) -> impl Iterator<Item = (ObjectId, &mut SceneObjectEnum)></code>
: Iterate over all objects mutably

; <code>fn compute_screen_position(pos: &Vec2, screen_angle: u32) -> Vec2</code>
: Compute screen-space position accounting for screen rotation. Used by render implementations to adjust positions based on screen orientation.

== high_level::gfx::background ==

Full-screen fill.

'''Types:''' <code>struct Background</code> — Fills entire screen with solid color. This is the simplest scene object - it just clears the screen with a solid color when rendered. # Example ```no_run use wowcube_sys::high_level::gfx::Background; use wowcube_sys::high_level::Color; let bg = Background::new(Color::rgb(0, 0, 128)); // Dark blue ```

'''6 public functions:'''

; <code>fn new(color: Color) -> Self</code>
: Create a new background with the specified color.

; <code>fn from_rgb(r: u8, g: u8, b: u8) -> Self</code>
: Create a background from RGB values.

; <code>fn from_rgba(r: u8, g: u8, b: u8, a: u8) -> Self</code>
: Create a background from RGBA values.

; <code>fn black() -> Self</code>
: Create a black background.

; <code>fn white() -> Self</code>
: Create a white background.

; <code>fn with_color(mut self, color: Color) -> Self</code>
: Set color (builder pattern)

== high_level::gfx::sprite ==

Static sprite bound to an image asset.

'''Types:''' <code>struct Sprite</code> — Static image sprite. Wraps a sprite resource ID and renders it with transform and color. # Example ```no_run use wowcube_sys::high_level::gfx::Sprite; let sprite = Sprite::from_name("player") .with_position(120.0, 120.0) .with_scale(200); // 2x scale ```

'''12 public functions:'''

; <code>fn from_name(name: &str) -> Self</code>
: Create from asset name (looks up ID via GFX_getAssetId).

; <code>fn from_name_at(name: &str, x: f32, y: f32) -> Self</code>
: Create from asset name with position.

; <code>fn from_id(resource_id: SpriteId) -> Self</code>
: Create from pre-resolved resource ID.

; <code>fn from_id_at(resource_id: SpriteId, x: f32, y: f32) -> Self</code>
: Create from ID with position.

; <code>fn resource_id(&self) -> SpriteId</code>
: Get the resource ID.

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Set position (builder pattern)

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Set rotation in degrees (builder pattern)

; <code>fn with_scale(mut self, scale: u32) -> Self</code>
: Set uniform scale as percentage (builder pattern)

; <code>fn with_scale_xy(mut self, scale_x: u32, scale_y: u32) -> Self</code>
: Set non-uniform scale (builder pattern)

; <code>fn with_mirror(mut self, mirror: GfxMirror) -> Self</code>
: Set mirroring (builder pattern)

; <code>fn with_color(mut self, color: Color) -> Self</code>
: Set color/tint (builder pattern)

; <code>fn with_alpha(mut self, alpha: u8) -> Self</code>
: Set alpha/opacity (builder pattern)

== high_level::gfx::animated_sprite ==

Frame animation: name list / name+range / atlas source; <code>tick(dt)</code>, <code>PlaybackMode</code>.

'''Types:''' <code>enum PlaybackMode</code> — Animation playback mode. · <code>struct AnimatedSprite</code> — Animated sprite with multiple frames. Supports Loop, Bounce, and Set (manual) playback modes. # Example ```no_run use wowcube_sys::high_level::gfx::AnimatedSprite; use wowcube_sys::high_level::scene::SceneObject; let mut anim = AnimatedSprite::from_names(&["run_1", "run_2", "run_3", "run_4"]) .with_position(120.0, 120.0) .with_playback_speed(12); // 12 FPS // In game loop: let delta_time_ms = 16; let screen_angle = 0; anim.tick(delta_time_ms); anim.render(screen_angle); ```

'''20 public functions:'''

; <code>fn from_names(names: &[&str]) -> Self</code>
: Create from array of asset names.

; <code>fn from_pattern(prefix: &str, extension: &str, first: i16, last: i16) -> Self</code>
: Create from naming pattern. E.g., `from_pattern("run_", ".png", 1, 4)` loads "run_1.png" through "run_4.png"

; <code>fn from_ids(ids: &[SpriteId]) -> Self</code>
: Create from array of pre-resolved resource IDs.

; <code>fn tick(&mut self, dt: u32) -> i16</code>
: Advance animation by delta time (milliseconds). Returns the current frame index after update.

; <code>fn set_frame(&mut self, frame: i16) -> &mut Self</code>
: Set current frame directly.

; <code>fn set_playback_speed(&mut self, fps: i16) -> &mut Self</code>
: Set playback speed in frames per second.

; <code>fn set_playback_mode(&mut self, mode: PlaybackMode) -> &mut Self</code>
: Set playback mode.

; <code>fn next_frame(&mut self) -> i16</code>
: Advance to next frame manually.

; <code>fn prev_frame(&mut self) -> i16</code>
: Go to previous frame manually.

; <code>fn current_frame(&self) -> i16</code>
: Get current frame index.

; <code>fn frame_count(&self) -> u16</code>
: Get total frame count.

; <code>fn playback_speed(&self) -> i16</code>
: Get playback speed.

; <code>fn playback_mode(&self) -> PlaybackMode</code>
: Get playback mode.

; <code>fn current_resource_id(&self) -> Option<SpriteId></code>
: Get the resource ID of the current frame.

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Set position (builder pattern)

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Set rotation (builder pattern)

; <code>fn with_scale(mut self, scale: u32) -> Self</code>
: Set scale (builder pattern)

; <code>fn with_playback_speed(mut self, fps: i16) -> Self</code>
: Set playback speed (builder pattern)

; <code>fn with_playback_mode(mut self, mode: PlaybackMode) -> Self</code>
: Set playback mode (builder pattern)

; <code>fn with_color(mut self, color: Color) -> Self</code>
: Set color (builder pattern)

== high_level::gfx::sprite_atlas ==

Sprite sheet + <code>SpriteAtlasElement</code> (sub-rect sprites).

'''Types:''' <code>struct SpriteAtlasElement</code> — A single element within a sprite atlas. Each element references a rectangular region of the parent atlas texture and can be rendered independently with its own transform and color. · <code>struct SpriteAtlas</code> — A sprite atlas containing multiple sprite elements from a single texture. The atlas manages a collection of elements, each defined by a rectangular region within the atlas texture. This is more efficient than loading multiple separate textures. # Type Parameters * `MAX_ELEMENTS` - Maximum number of elements the atlas can hold (default: 64).

'''26 public functions:'''

; <code>fn new(atlas_id: SpriteId, region: Rect2) -> Self</code>
: Creates a new atlas element with the given region.

; <code>fn atlas_id(&self) -> SpriteId</code>
: Returns the atlas texture ID.

; <code>fn region(&self) -> Rect2</code>
: Returns the region within the atlas.

; <code>fn set_region(&mut self, region: Rect2)</code>
: Sets the region within the atlas.

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Builder: set position.

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Builder: set rotation in degrees.

; <code>fn with_scale(mut self, scale: u32) -> Self</code>
: Builder: set uniform scale.

; <code>fn with_scale_xy(mut self, scale_x: u32, scale_y: u32) -> Self</code>
: Builder: set non-uniform scale.

; <code>fn with_mirror(mut self, mirror: GfxMirror) -> Self</code>
: Builder: set mirroring.

; <code>fn with_color(mut self, color: Color) -> Self</code>
: Builder: set color (affects tinting).

; <code>fn with_alpha(mut self, alpha: u8) -> Self</code>
: Builder: set alpha (opacity).

; <code>fn from_name(name: &str) -> Self</code>
: Creates a new sprite atlas from an asset name.

; <code>fn from_id(texture_id: SpriteId) -> Self</code>
: Creates a new sprite atlas from an existing sprite ID.

; <code>fn texture_id(&self) -> SpriteId</code>
: Returns the atlas texture ID.

; <code>fn len(&self) -> usize</code>
: Returns the number of elements in the atlas.

; <code>fn is_empty(&self) -> bool</code>
: Returns true if the atlas has no elements.

; <code>fn add_element(&mut self, id: u32, region: Rect2) -> bool</code>
: Adds an element to the atlas with the given ID and region. Returns `true` if successful, `false` if the atlas is full or an element with that ID already exists.

; <code>fn add_element_with(&mut self, id: u32, mut element: SpriteAtlasElement) -> bool</code>
: Adds an element with a pre-configured SpriteAtlasElement. The element's atlas_id will be overwritten with this atlas's texture_id.

; <code>fn get(&self, id: u32) -> Option<&SpriteAtlasElement></code>
: Gets an element by ID.

; <code>fn get_mut(&mut self, id: u32) -> Option<&mut SpriteAtlasElement></code>
: Gets a mutable reference to an element by ID.

; <code>fn remove(&mut self, id: u32) -> Option<SpriteAtlasElement></code>
: Removes an element by ID. Returns the removed element if found.

; <code>fn clear(&mut self)</code>
: Removes all elements from the atlas.

; <code>fn render_all(&self, screen_angle: u32)</code>
: Renders all visible elements in the atlas.

; <code>fn iter(&self) -> impl Iterator<Item = (u32, &SpriteAtlasElement)></code>
: Iterates over all elements in the atlas.

; <code>fn iter_mut(&mut self) -> impl Iterator<Item = (u32, &mut SpriteAtlasElement)></code>
: Iterates mutably over all elements in the atlas.

; <code>fn add_grid( &mut self, start_id: u32, cols: u16, rows: u16, cell_width: i16, cell_height: i16, offset_x: i16, offset_y: i16, ) -> usize</code>
: Adds elements from a regular grid layout. # Arguments * `start_id` - Starting ID for the first element * `cols` - Number of columns in the grid * `rows` - Number of rows in the grid * `cell_width` - Width of each cell * `cell_height` - Height of each cell * `offset_x` - X offset from the top-left of the texture * `offset_y` - Y offset from the top-left of the texture # Returns Number of elements successfully added.

== high_level::gfx::text ==

Text label (content, font size, alignment, color).

'''Types:''' <code>struct Text</code> — Text label with font size and alignment. Uses `heapless::String` for no_std compatibility. # Example ```no_run use wowcube_sys::high_level::gfx::Text; use wowcube_sys::ffi::types::TextAlign; let text = Text::new("Score: 100") .with_position(120.0, 120.0) .with_font_size(12) .with_alignment(TextAlign::Center); ```

'''14 public functions:'''

; <code>fn new(content: &str) -> Self</code>
: Create new text with content.

; <code>fn at(content: &str, x: f32, y: f32) -> Self</code>
: Create text at position.

; <code>fn set_content(&mut self, content: &str)</code>
: Set content (replaces existing).

; <code>fn content(&self) -> &str</code>
: Get current content.

; <code>fn with_font_size(mut self, size: u32) -> Self</code>
: Set font size (builder pattern)

; <code>fn with_alignment(mut self, align: TextAlign) -> Self</code>
: Set alignment (builder pattern)

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Set position (builder pattern)

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Set rotation (builder pattern)

; <code>fn with_color(mut self, color: Color) -> Self</code>
: Set color (builder pattern)

; <code>fn font_size(&self) -> u32</code>
: Get font size.

; <code>fn set_font_size(&mut self, size: u32)</code>
: Set font size.

; <code>fn alignment(&self) -> TextAlign</code>
: Get alignment.

; <code>fn set_alignment(&mut self, align: TextAlign)</code>
: Set alignment.

; <code>fn format(&mut self, args: core::fmt::Arguments<'_>)</code>
: Format content using core::fmt. Note: This clears existing content and writes new formatted text.

== high_level::gfx::qrcode ==

QR-code object (data, size, colors).

'''Types:''' <code>struct QRCode</code> — QR code scene object. Renders a QR code with customizable colors and size. # Example ```no_run use wowcube_sys::high_level::gfx::QRCode; use wowcube_sys::ffi::math::Color; let qr = QRCode::new("https://wowcube.com") .with_position(120.0, 120.0) .with_size(100) .with_colors(Color::from_u32(0xFF000000), Color::from_u32(0xFFFFFFFF)); ```

'''14 public functions:'''

; <code>fn new(data: &str) -> Self</code>
: Create a new QR code with the given data.

; <code>fn at(data: &str, x: f32, y: f32) -> Self</code>
: Create at a specific position.

; <code>fn with_size(mut self, size: u32) -> Self</code>
: Set the QR code size (builder pattern).

; <code>fn with_colors(mut self, zeros: Color, ones: Color) -> Self</code>
: Set the colors (builder pattern). - `zeros`: Background color (usually white) - `ones`: Foreground/data color (usually black)

; <code>fn with_background_color(mut self, color: Color) -> Self</code>
: Set the background color (zeros).

; <code>fn with_foreground_color(mut self, color: Color) -> Self</code>
: Set the foreground/data color (ones).

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Set position (builder pattern).

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Set rotation in degrees (builder pattern).

; <code>fn data(&self) -> &str</code>
: Get the QR code data.

; <code>fn set_data(&mut self, data: &str)</code>
: Set new QR code data.

; <code>fn size(&self) -> u32</code>
: Get the size.

; <code>fn set_size(&mut self, size: u32)</code>
: Set the size.

; <code>fn color_zeros(&self) -> Color</code>
: Get the background color.

; <code>fn color_ones(&self) -> Color</code>
: Get the foreground color.

== high_level::gfx::offscreen ==

Offscreen render target (bake once, draw as an object).

'''Types:''' <code>struct OffscreenRenderTarget</code> — Offscreen render target for render-to-texture operations. The render target creates a texture buffer that can be drawn to and then rendered as a regular sprite. This is managed automatically: - The buffer is created when `begin()` is first called - The buffer is cleaned up when the target is dropped # Render Layer Order The C++ SDK has `RenderLayer(order)` for before/after queue rendering. In this simplified Rust version, manual control of render order is achieved by calling `draw()` at the appropriate time.

'''15 public functions:'''

; <code>fn new(width: u32, height: u32) -> Self</code>
: Creates a new offscreen render target with the specified dimensions. Uses ARGB8888 format by default for full alpha support.

; <code>fn with_format(width: u32, height: u32, format: GfxPixelFormat) -> Self</code>
: Creates a new offscreen render target with a specific pixel format.

; <code>fn id(&self) -> SpriteId</code>
: Returns the render target's unique ID.

; <code>fn width(&self) -> u32</code>
: Returns the width of the render target.

; <code>fn height(&self) -> u32</code>
: Returns the height of the render target.

; <code>fn is_created(&self) -> bool</code>
: Returns whether the render target has been created.

; <code>fn is_in_render(&self) -> bool</code>
: Returns whether we're currently rendering to this target.

; <code>fn begin(&mut self, overwrite: bool) -> Result<(), i32></code>
: Begins rendering to this offscreen target. All subsequent draw calls will render to this buffer until `end()` is called. # Arguments * `overwrite` - If true, clears the buffer. If false, preserves existing content. # Returns `Ok(())` on success, `Err(i32)` with the error code on failure.

; <code>fn end(&mut self)</code>
: Ends rendering to this offscreen target. After calling this, the buffer contains the rendered content and can be drawn using `draw()` or the `SceneObject` trait.

; <code>fn draw(&self, x: i32, y: i32, screen_angle: u32)</code>
: Draws the offscreen buffer to the screen at the specified position. # Arguments * `x` - X position on screen * `y` - Y position on screen * `screen_angle` - Current screen orientation angle

; <code>fn with_position(mut self, x: f32, y: f32) -> Self</code>
: Builder: set position.

; <code>fn with_rotation(mut self, degrees: i32) -> Self</code>
: Builder: set rotation in degrees.

; <code>fn with_scale(mut self, scale: u32) -> Self</code>
: Builder: set uniform scale.

; <code>fn with_scale_xy(mut self, scale_x: u32, scale_y: u32) -> Self</code>
: Builder: set non-uniform scale.

; <code>fn with_alpha(mut self, alpha: u8) -> Self</code>
: Builder: set alpha (opacity).

== high_level::gfx::colors ==

142 named colors as <code>u32</code> ARGB constants + <code>Color</code> helpers.

'''Types:''' <code>struct Colors</code> — Named color constants matching the C++ SDK's `Cubios::Gfx::Colors` enum. All colors are fully opaque (alpha = 0xFF) unless otherwise noted. # Example ```no_run use wowcube_sys::high_level::gfx::Colors; use wowcube_sys::ffi::math::Color; let red = Colors::RED; let custom = Colors::from_u32(Colors::BLUE); ```

'''142 named colors''' (<code>Colors::NAME</code>, ARGB <code>u32</code>):

<div style="column-count:4; font-size:85%;"><code>ALICE_BLUE</code> <code>ANTIQUE_WHITE</code> <code>AQUA</code> <code>AQUAMARINE</code> <code>AZURE</code> <code>BEIGE</code> <code>BISQUE</code> <code>BLACK</code> <code>BLANCHED_ALMOND</code> <code>BLUE</code> <code>BLUE_VIOLET</code> <code>BROWN</code> <code>BURLY_WOOD</code> <code>CADET_BLUE</code> <code>CHARTREUSE</code> <code>CHOCOLATE</code> <code>CORAL</code> <code>CORNFLOWER_BLUE</code> <code>CORNSILK</code> <code>CRIMSON</code> <code>CYAN</code> <code>DARK_BLUE</code> <code>DARK_CYAN</code> <code>DARK_GOLDENROD</code> <code>DARK_GRAY</code> <code>DARK_GREEN</code> <code>DARK_KHAKI</code> <code>DARK_MAGENTA</code> <code>DARK_OLIVE_GREEN</code> <code>DARK_ORANGE</code> <code>DARK_ORCHID</code> <code>DARK_RED</code> <code>DARK_SALMON</code> <code>DARK_SEA_GREEN</code> <code>DARK_SLATE_BLUE</code> <code>DARK_SLATE_GRAY</code> <code>DARK_TURQUOISE</code> <code>DARK_VIOLET</code> <code>DEEP_PINK</code> <code>DEEP_SKY_BLUE</code> <code>DIM_GRAY</code> <code>DODGER_BLUE</code> <code>FIREBRICK</code> <code>FLORAL_WHITE</code> <code>FOREST_GREEN</code> <code>FUCHSIA</code> <code>GAINSBORO</code> <code>GHOST_WHITE</code> <code>GOLD</code> <code>GOLDENROD</code> <code>GRAY</code> <code>GREEN</code> <code>GREEN_YELLOW</code> <code>GREY</code> <code>HONEYDEW</code> <code>HOT_PINK</code> <code>INDIAN_RED</code> <code>INDIGO</code> <code>IVORY</code> <code>KHAKI</code> <code>LAVENDER</code> <code>LAVENDER_BLUSH</code> <code>LAWN_GREEN</code> <code>LEMON_CHIFFON</code> <code>LIGHT_BLUE</code> <code>LIGHT_CORAL</code> <code>LIGHT_CYAN</code> <code>LIGHT_GOLDENROD_YELLOW</code> <code>LIGHT_GRAY</code> <code>LIGHT_GREEN</code> <code>LIGHT_PINK</code> <code>LIGHT_SALMON</code> <code>LIGHT_SEA_GREEN</code> <code>LIGHT_SKY_BLUE</code> <code>LIGHT_SLATE_GRAY</code> <code>LIGHT_STEEL_BLUE</code> <code>LIGHT_YELLOW</code> <code>LIME</code> <code>LIME_GREEN</code> <code>LINEN</code> <code>MAGENTA</code> <code>MAROON</code> <code>MEDIUM_AQUAMARINE</code> <code>MEDIUM_BLUE</code> <code>MEDIUM_ORCHID</code> <code>MEDIUM_PURPLE</code> <code>MEDIUM_SEA_GREEN</code> <code>MEDIUM_SLATE_BLUE</code> <code>MEDIUM_SPRING_GREEN</code> <code>MEDIUM_TURQUOISE</code> <code>MEDIUM_VIOLET_RED</code> <code>MIDNIGHT_BLUE</code> <code>MINT_CREAM</code> <code>MISTY_ROSE</code> <code>MOCCASIN</code> <code>NAVAJO_WHITE</code> <code>NAVY</code> <code>OLD_LACE</code> <code>OLIVE</code> <code>OLIVE_DRAB</code> <code>ORANGE</code> <code>ORANGE_RED</code> <code>ORCHID</code> <code>PALE_GOLDENROD</code> <code>PALE_GREEN</code> <code>PALE_TURQUOISE</code> <code>PALE_VIOLET_RED</code> <code>PAPAYA_WHIP</code> <code>PEACH_PUFF</code> <code>PERU</code> <code>PINK</code> <code>PLUM</code> <code>POWDER_BLUE</code> <code>PURPLE</code> <code>RED</code> <code>ROSY_BROWN</code> <code>ROYAL_BLUE</code> <code>SADDLE_BROWN</code> <code>SALMON</code> <code>SANDY_BROWN</code> <code>SEA_GREEN</code> <code>SEA_SHELL</code> <code>SIENNA</code> <code>SILVER</code> <code>SKY_BLUE</code> <code>SLATE_BLUE</code> <code>SLATE_GRAY</code> <code>SNOW</code> <code>SPRING_GREEN</code> <code>STEEL_BLUE</code> <code>TAN</code> <code>TEAL</code> <code>THISTLE</code> <code>TOMATO</code> <code>TRANSPARENT</code> <code>TURQUOISE</code> <code>VIOLET</code> <code>WHEAT</code> <code>WHITE</code> <code>WHITE_SMOKE</code> <code>YELLOW</code> <code>YELLOW_GREEN</code></div>

== high_level::sound ==

<code>Sound</code> + <code>SoundCollection</code> (random playback, repeat with random delays).

'''Types:''' <code>struct Sound</code> — A single sound asset. Wraps a sound ID and provides convenient playback methods. · <code>struct SoundCollection</code> — A collection of sounds with random playback support. Useful for sound effects that should vary (footsteps, hits, etc.).

'''21 public functions:'''

; <code>fn from_name(name: &str) -> Self</code>
: Creates a sound from an asset name. Looks up the asset ID at creation time.

; <code>fn from_id(id: SoundId) -> Self</code>
: Creates a sound from an existing sound ID.

; <code>fn id(&self) -> SoundId</code>
: Returns the sound's asset ID.

; <code>fn play(&self, volume: u32) -> i32</code>
: Plays the sound at the specified volume. # Arguments * `volume` - Volume level (0-100). # Returns The result code from the sound system.

; <code>fn play_full(&self) -> i32</code>
: Plays the sound at full volume (100).

; <code>fn stop_all() -> i32</code>
: Stops all currently playing sounds. Note: This stops ALL sounds, not just this one.

; <code>fn is_any_playing() -> bool</code>
: Returns whether any sound is currently playing.

; <code>fn new() -> Self</code>
: Creates an empty sound collection.

; <code>fn from_names(names: &[&str]) -> Self</code>
: Creates a sound collection from an array of asset names.

; <code>fn from_ids(ids: &[SoundId]) -> Self</code>
: Creates a sound collection from an array of sound IDs.

; <code>fn len(&self) -> usize</code>
: Returns the number of sounds in the collection.

; <code>fn is_empty(&self) -> bool</code>
: Returns whether the collection is empty.

; <code>fn add(&mut self, sound: Sound) -> bool</code>
: Adds a sound to the collection. Returns `true` if successful, `false` if the collection is full.

; <code>fn get(&self, index: usize) -> Option<&Sound></code>
: Gets a sound by index.

; <code>fn remove(&mut self, index: usize) -> Option<Sound></code>
: Removes a sound by index.

; <code>fn clear(&mut self)</code>
: Clears all sounds from the collection.

; <code>fn play_random(&mut self, volume: u32) -> Option<usize></code>
: Plays a random sound from the collection. Tries to avoid playing the same sound twice in a row. # Arguments * `volume` - Volume level (0-100). # Returns The index of the played sound, or `None` if collection is empty.

; <code>fn play_random_full(&mut self) -> Option<usize></code>
: Plays a random sound at full volume.

; <code>fn repeat_random( &mut self, min_delay: i32, max_delay: i32, volume: u32, dt: i32, ) -> Option<usize></code>
: Repeats random sounds at intervals. Call this every frame with the delta time. When the delay expires, a random sound is played and a new delay is set. # Arguments * `min_delay` - Minimum delay in milliseconds between sounds. * `max_delay` - Maximum delay in milliseconds between sounds. * `volume` - Volume level (0-100). * `dt` - Delta time in milliseconds since last call. # Returns The index of the played sound if one was played this frame.

; <code>fn reset_delay(&mut self)</code>
: Resets the repeat delay counter.

; <code>fn cache_all(&self)</code>
: Caches all sounds in the collection for faster playback.

== high_level::scramble ==

<code>Scramble</code> / <code>SimpleScramble</code> cube-scramble helpers with mapping callbacks.

'''Types:''' <code>trait ScrambleObserver</code> — Observer trait for scramble events. Implement this trait to receive callbacks when the cube topology changes. · <code>struct FaceletPosition</code> — Facelet position tracking for a single facelet. · <code>struct Scramble</code> — Tracks facelet positions across cube twists. This struct maintains a mapping of where each facelet has moved to as the cube is twisted. It can be used to implement scramble-based puzzles or effects that follow facelets as they move. · <code>struct SimpleScramble</code> — Simple scramble tracker without observer callbacks. A lighter-weight version of `Scramble` for when you don't need the observer pattern.

'''23 public functions:'''

; <code>ScrambleObserver::fn on_before_twist(&mut self)</code>
: Called before a twist is about to occur. Use this to save state that might be affected by the twist.

; <code>ScrambleObserver::fn on_mapping_changed( &mut self, _to_module: u8, _to_screen: u8, _from_module: u8, _from_screen: u8, )</code>
: Called when a facelet mapping changes during a twist. # Arguments * `to_module` - Destination module ID. * `to_screen` - Destination screen ID within module. * `from_module` - Source module ID. * `from_screen` - Source screen ID within module.

; <code>fn new(module: u8, screen: u8) -> Self</code>
: Creates a new facelet position.

; <code>fn to_display_id(&self) -> u8</code>
: Converts to a linear display ID (0-23).

; <code>fn from_display_id(display_id: u8) -> Self</code>
: Creates from a linear display ID.

; <code>fn new() -> Self</code>
: Creates a new scramble tracker with identity mapping. Initially, each facelet is at its "home" position.

; <code>fn reset(&mut self)</code>
: Resets all positions to identity (home positions).

; <code>fn is_assembled(&self) -> bool</code>
: Returns whether the cube is currently assembled.

; <code>fn get_position(&self, original_display_id: u8) -> Option<FaceletPosition></code>
: Returns the current position of a facelet by its original display ID.

; <code>fn get_previous_position(&self, original_display_id: u8) -> Option<FaceletPosition></code>
: Returns the previous position of a facelet (before last twist).

; <code>fn last_twist(&self) -> Option<&TopologyTwistInfo></code>
: Returns the last recorded twist info.

; <code>fn is_solved(&self) -> bool</code>
: Checks if all facelets are in their home positions.

; <code>fn count_home(&self) -> usize</code>
: Counts how many facelets are in their home positions.

; <code>fn update<O: ScrambleObserver>(&mut self, mut observer: Option<&mut O>)</code>
: Updates the scramble state based on current topology. Call this each frame or after twist events to keep tracking current. # Arguments * `observer` - Optional observer to receive callbacks.

; <code>fn positions(&self) -> &[FaceletPosition; 24]</code>
: Gets all positions as a slice.

; <code>fn previous_positions(&self) -> &[FaceletPosition; 24]</code>
: Gets previous positions as a slice.

; <code>fn new() -> Self</code>
: Creates a new simple scramble tracker.

; <code>fn reset(&mut self)</code>
: Resets to identity positions.

; <code>fn update(&mut self)</code>
: Updates based on current topology (no callbacks).

; <code>fn is_assembled(&self) -> bool</code>
: Returns whether the cube is assembled.

; <code>fn is_solved(&self) -> bool</code>
: Returns whether all facelets are home.

; <code>fn get_position(&self, original_display_id: u8) -> Option<FaceletPosition></code>
: Gets the current position of a facelet.

; <code>fn last_twist(&self) -> Option<&TopologyTwistInfo></code>
: Gets the last twist info.

== high_level::splashscreen ==

Standard splash screen with leaderboard table, records, QR link.

'''Types:''' <code>enum LeadersDataType</code> — Data type for leaderboard values. · <code>enum ScreenType</code> — Screen type for each position on the splashscreen. · <code>enum LeaderboardType</code> — Preset leaderboard table layouts. · <code>struct LeaderData</code> — Data for a single leader entry. · <code>struct ResultData</code> — Data for a result parameter display. · <code>struct RecordData</code> — Data for the record/best score display. · <code>struct SplashSprites</code> — Sprite IDs for splashscreen graphics. · <code>struct Splashscreen</code> — Splashscreen display manager. Manages the layout and rendering of leaderboard and splash content across the cube's faces.

'''17 public functions:'''

; <code>fn new(name: &str, value: i32) -> Self</code>
: Creates a new leader entry.

; <code>fn empty() -> Self</code>
: Creates an empty/invalid entry.

; <code>fn new(name: &str, value: i32) -> Self</code>
: Creates a new result parameter.

; <code>fn new(value: i32, is_new: bool) -> Self</code>
: Creates new record data.

; <code>fn from_names( background: Option<&str>, game_icon: Option<&str>, trophy: Option<&str>, ) -> Self</code>
: Creates sprites from asset names.

; <code>fn set_animated_icon(&mut self, index: usize, name: &str)</code>
: Sets an animated icon sprite.

; <code>fn new() -> Self</code>
: Creates a new splashscreen with default settings.

; <code>fn set_data_type(&mut self, data_type: LeadersDataType)</code>
: Sets the data type for value formatting.

; <code>fn set_leader(&mut self, index: usize, name: &str, value: i32)</code>
: Sets a leader entry.

; <code>fn clear_leaders(&mut self)</code>
: Clears all leader entries.

; <code>fn set_record(&mut self, value: i32, is_new: bool)</code>
: Sets the record value.

; <code>fn set_param(&mut self, index: usize, name: &str, value: i32)</code>
: Sets a result parameter.

; <code>fn set_qr_text(&mut self, text: &str)</code>
: Sets the QR code text.

; <code>fn set_leaderboard_table(&mut self, table: [[ScreenType; 4]; 6])</code>
: Sets the leaderboard table layout.

; <code>fn apply_preset(&mut self, preset: LeaderboardType)</code>
: Applies a preset leaderboard layout.

; <code>fn tick(&mut self, dt: f32)</code>
: Updates animation state. # Arguments * `dt` - Delta time in seconds.

; <code>fn render_screen_type(&self, screen_type: ScreenType, screen_angle: u32, x: i32, y: i32)</code>
: Renders a specific screen type. # Arguments * `screen_type` - The type of content to render. * `screen_angle` - Screen orientation angle. * `x` - X position. * `y` - Y position.

[[Category:SDK 6.3]]
[[Category:Rust API]]

SDK 6.3/Rust/cubios-sys

2026-07-26T10:44:42Z

WowBot: Full Rust API reference: cubios-sys + cubios, every pub fn with docs (WowBot)

{{notice|'''Official WOWCube SDK documentation.''' SDK 6.3, Rust API — '''EXPERIMENTAL''' (supported; APIs may change). Generated from the [https://github.com/wowcube/CubiOS_Rust_SDK CubiOS_Rust_SDK] sources — the repository is authoritative; do not edit by hand.}}

{{SDK 6.3 nav}}

''← [[SDK 6.3]] · [[SDK 6.3/Rust|Rust]] / cubios-sys (raw layer)''

Complete reference of the '''raw layer''' crate [https://github.com/wowcube/CubiOS_Rust_SDK/tree/main/crates/cubios-sys <code>cubios-sys</code>]: FFI bindings to the CubiOS engine ABI, thin safe wrappers and the application event loop. Signatures and descriptions are extracted from the crate sources. Engine-function semantics match the [[SDK 6.3/C++/Native API|C++ native API]] one-to-one.

== ffi::application ==

The <code>Application</code> trait (11 callbacks), <code>ApplicationContext</code>, <code>TimerController</code>, the event loop (<code>application_init</code> / <code>application_run</code>), <code>Anim<T></code>, <code>AppErr</code>.

'''Types:''' <code>enum AppErr</code> · <code>enum AppPkt</code> · <code>enum RotationDir</code> · <code>struct Anim</code> · <code>struct Timer</code> · <code>trait Application</code> · <code>trait Assetable</code> · <code>trait Mappable</code> · <code>trait Packable</code> · <code>struct MapBase</code> · <code>struct SceneSwitch</code> · <code>trait Broadcastable</code> · <code>trait Shuffable</code> · <code>struct TimerController</code> · <code>struct ApplicationContext</code>

'''49 public functions:'''

; <code>Application::fn app_context_mut(&mut self) -> &mut ApplicationContext</code>

; <code>Application::fn set_timer(&mut self, id: u8, delay: u32, suspended: bool) -> bool</code>

; <code>Application::fn start_timer(&mut self, id: u8) -> bool</code>

; <code>Application::fn stop_timer(&mut self, id: u8) -> bool</code>

; <code>Application::fn kill_timer(&mut self, id: u8)</code>

; <code>Application::fn on_init(&mut self) -> Result<(), AppErr></code>
: Called once when the application initializes.

; <code>Application::fn on_tick(&mut self, cur_time: u32, delta_time: u32) -> Result<(), AppErr></code>
: Called every frame. `cur_time` is current time in ms, `delta_time` is ms since last tick.

; <code>Application::fn on_render(&mut self, screens: &mut [Screen</code>
: Called to render the current frame. `screens` contains the 3 screens for this module.

; <code>Application::fn on_phys_tick(&mut self, screens: &[Screen</code>
: Called on physics tick. `screens` contains the 3 screens for this module.

; <code>Application::fn on_twist(&mut self, twist: &TopologyTwistInfo) -> Result<(), AppErr></code>
: Called when a twist event occurs.

; <code>Application::fn on_tap(&mut self, count: u32) -> Result<(), AppErr></code>
: Called when a tap event occurs. `count` is the number of taps.

; <code>Application::fn on_pat(&mut self, count: u32) -> Result<(), AppErr></code>
: Called when a pat event occurs. `count` is the number of pats.

; <code>Application::fn on_message(&mut self, msg_type: u32, data: &[u8]) -> Result<(), AppErr></code>
: Called when a network message is received from another module.

; <code>Application::fn on_external_message(&mut self, data: &[u8]) -> Result<(), AppErr></code>
: Called when an external message is received via BLE.

; <code>Application::fn on_timer(&mut self, timer_id: u8) -> Result<(), AppErr></code>
: Called when a timer fires.

; <code>Application::fn on_close(&mut self) -> Result<(), AppErr></code>
: Called when the application is closing.

; <code>Application::fn get_time(&self) -> u32</code>
: Returns current time in milliseconds.

; <code>Application::fn get_time_seconds(&self) -> u32</code>
: Returns current time in seconds.

; <code>Application::fn is_master_module(&self) -> bool</code>
: Returns true if this module is the master (module 0).

; <code>Application::fn send_network_message(&self, msg_type: u32, data: &[u8])</code>
: Sends a network message to other modules.

; <code>Application::fn save_state(&self, data: &[u8])</code>
: Saves game state to persistent storage.

; <code>Application::fn load_state(&self, id: &mut u32, data: &mut [u8]) -> i32</code>
: Loads game state from persistent storage. Returns the number of bytes read, or negative on error.

; <code>Application::fn send_external_message(&self, msg_type: u32, data: &mut [u8])</code>
: Sends an external message via BLE.

; <code>Application::fn show_fps_counter(&self, show: bool)</code>
: Shows or hides the FPS counter overlay.

; <code>Application::fn get_image_assets_count(&self) -> i32</code>
: Returns the number of image assets available.

; <code>Application::fn get_sound_assets_count(&self) -> i32</code>
: Returns the number of sound assets available.

; <code>Assetable::fn get_asset_id(asset: &'static str) -> Result<u32, AppErr></code>

; <code>Mappable::fn get_place( &self, module: u32, screen: u32, orientation: TopologyOrientation, ) -> Result<(u32, u32), AppErr></code>

; <code>Packable::fn to_pkt(&self, module: u8, screen: u8) -> [u8</code>

; <code>Packable::fn from_pkt(pkt: [u8</code>

; <code>fn new(val: T) -> Self</code>

; <code>Broadcastable::fn broadcast_part(&mut self, _module: u8, _screen: u8, _delay: usize) -> Result<(), AppErr></code>

; <code>Broadcastable::fn broadcast(&mut self, delay: usize) -> Result<(), AppErr></code>

; <code>Broadcastable::fn recv(&mut self, pkt: [u8</code>

; <code>Shuffable::fn rotate(&mut self, dir: &RotationDir) -> Result<(), AppErr></code>

; <code>Shuffable::fn shuffle(&mut self, algo: &[RotationDir]) -> Result<(), AppErr></code>

; <code>fn new(scenes: &'static [usize], start_time: usize) -> Self</code>

; <code>fn next_scene(&mut self)</code>

; <code>fn set_scene(&mut self, id: u8) -> Result<(), AppErr></code>

; <code>fn animate(&mut self)</code>

; <code>fn new() -> Self</code>
: Create a new TimerController with no active timers.

; <code>fn set_timer(&mut self, id: u8, delay: u32, suspended: bool) -> bool</code>

; <code>fn start_timer(&mut self, id: u8) -> bool</code>

; <code>fn stop_timer(&mut self, id: u8) -> bool</code>

; <code>fn kill_timer(&mut self, id: u8)</code>

; <code>fn delta_time(&self) -> u32</code>

; <code>fn new() -> Self</code>
: Create a new ApplicationContext.

; <code>fn application_init<T: Application>(app: &mut T, cid: u32)</code>

; <code>fn application_run<T: Application>(app: &mut T)</code>

== ffi::comm ==

Inter-module packets and UART lines, BLE external data, time, user name, state save/load, RNG, logging (<code>log_a</code>…<code>log_v</code>), tap.

'''22 public functions:'''

; <code>fn send_message(line: u32, pkt: *const u8, size: u32) -> i32</code>

; <code>fn send_message_to(line: u32, dest: u32, pkt: *const u8, size: u32) -> i32</code>

; <code>fn recv_message( line: u32, size: u32, pkt_info: *mut u32, pkt: *mut u8, rx_size: *mut u32, ) -> i32</code>

; <code>fn send_packet(packet_type: u32, pkt: &[u8]) -> i32</code>
: Send a packet (new API in SDK 6.3)

; <code>fn recv_packet(size: u32, packet_type: *mut u32, pkt: *mut u8) -> i32</code>
: Receive a packet (new API in SDK 6.3) Returns the number of bytes received, or negative on error. The packet type is written to `packet_type`.

; <code>fn get_time() -> i32</code>

; <code>fn get_user_name(buffer: &mut [u8]) -> i32</code>

; <code>fn toggle_debug_info() -> i32</code>

; <code>fn save_state(data: &[u8]) -> i32</code>

; <code>fn load_state(id: &mut u32, data: &mut [u8]) -> i32</code>
: Load saved state Returns the number of bytes loaded, or negative on error. The save ID is written to `id`.

; <code>fn load_state_legacy(data: &mut [u8]) -> i32</code>
: Load saved state (legacy API without ID) Note: This ignores the save ID. Use `load_state` for full functionality.

; <code>fn random_range(min: u32, max: u32) -> i32</code>

; <code>fn get_app_version() -> AppVersion</code>
: Get the application version

; <code>fn log_a(text: &str) -> i32</code>

; <code>fn log_e(text: &str) -> i32</code>

; <code>fn log_w(text: &str) -> i32</code>

; <code>fn log_i(text: &str) -> i32</code>

; <code>fn log_d(text: &str) -> i32</code>

; <code>fn log_v(text: &str) -> i32</code>

; <code>fn get_tap() -> i32</code>

; <code>fn send_ble_data(data_type: u32, pkt: &mut [u8]) -> i32</code>
: Send BLE data

; <code>fn recv_ble_data(pkt: &mut [u8]) -> i32</code>
: Receive BLE data

== ffi::gfx ==

Immediate-mode drawing: clear, primitives, text, images, baked images, sub-images, shaders, QR, render target, cache.

'''26 public functions:'''

; <code>fn get_asset_id(sprite_name: &str) -> i32</code>

; <code>fn clear(color: u32) -> i32</code>

; <code>fn draw_text( x: i32, y: i32, scale: u32, angle: u32, align: TextAlign, color: u32, text: &str, ) -> i32</code>

; <code>fn draw_point(x: i32, y: i32, color: u32) -> i32</code>

; <code>fn draw_circle(x: u32, y: u32, radius: u32, width: u32, color: u32) -> i32</code>

; <code>fn draw_solid_circle(x: u32, y: u32, radius: u32, color: u32) -> i32</code>
: Deprecated: use `set_fill_shader` + `draw_circle` instead

; <code>fn draw_arc( x: i32, y: i32, radius: u32, width: u32, angle0: u32, angle1: u32, color: u32, ) -> i32</code>

; <code>fn draw_sector(x: i32, y: i32, radius: u32, angle0: u32, angle1: u32, color: u32) -> i32</code>

; <code>fn draw_line(x0: i32, y0: i32, x1: i32, y1: i32, thickness: u32, color: u32) -> i32</code>

; <code>fn draw_rectangle(x: i32, y: i32, w: i32, h: i32, color: u32) -> i32</code>

; <code>fn bake_image( id: SpriteId, width: u32, height: u32, format: GfxPixelFormat, overwrite: bool, ) -> i32</code>
: Bake an image to an offscreen buffer # Arguments * `id` - Sprite ID to bake * `width` - Width of the baked image * `height` - Height of the baked image * `format` - Pixel format for the baked image * `overwrite` - Whether to overwrite existing baked image

; <code>fn remove_baked_image(id: SpriteId) -> i32</code>
: Remove a previously baked image

; <code>fn set_render_target(display: u8) -> i32</code>

; <code>fn draw_image( id: SpriteId, x: i32, y: i32, opacity: u32, color_key: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: GfxMirror, ) -> i32</code>

; <code>fn draw_baked_image( x: i32, y: i32, opacity: u32, color_key: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: GfxMirror, id: SpriteId, ) -> i32</code>

; <code>fn draw_sub_image( id: SpriteId, x: i32, y: i32, rect_x: u32, rect_y: u32, rect_w: u32, rect_h: u32, opacity: u32, color_key: u32, scale_x: u32, scale_y: u32, angle: u32, mirror: GfxMirror, ) -> i32</code>
: Draw a sub-region of a sprite (for sprite atlases)

; <code>fn draw_qr_code( x: i32, y: i32, size: u32, color0: u32, color1: u32, angle: u32, id: u32, text: &str, ) -> i32</code>
: Draw a QR code

; <code>fn render() -> i32</code>

; <code>fn clear_cache() -> i32</code>

; <code>fn cache_images(sprite_ids: &[SpriteId]) -> i32</code>

; <code>fn get_assets_count() -> i32</code>
: Get the total number of image assets

; <code>fn set_fps_window(size: u32) -> i32</code>
: Set the FPS counter window size

; <code>fn set_fill_shader(color: u32) -> i32</code>
: Set a solid fill shader When active, drawing operations will use this color to fill shapes.

; <code>fn set_linear_gradient_shader( x0: u32, y0: u32, x1: u32, y1: u32, color0: u32, color1: u32, ) -> i32</code>
: Set a linear gradient shader # Arguments * `x0`, `y0` - Start point of the gradient * `x1`, `y1` - End point of the gradient * `color0` - Start color * `color1` - End color

; <code>fn set_radial_gradient_shader(x0: u32, y0: u32, radius: u32, color0: u32, color1: u32) -> i32</code>
: Set a radial gradient shader # Arguments * `x0`, `y0` - Center point of the gradient * `radius` - Radius of the gradient * `color0` - Center color * `color1` - Edge color

; <code>fn remove_shader() -> i32</code>
: Remove the active shader

== ffi::topology ==

Facelets, faces, places, orientation, twists, assembly check.

'''15 public functions:'''

; <code>fn get_cuben() -> u32</code>

; <code>fn get_adjacent_facelet( module: u32, screen: u32, direction: TopologyNeighbour, result: *mut TopologyFaceletInfo, ) -> i32</code>

; <code>fn get_reversed_face(face: u32) -> Option<u32></code>

; <code>fn get_facelet( face: u32, position: u32, mode: TopologyOrientation, result: *mut TopologyFaceletInfo, ) -> i32</code>

; <code>fn get_place( module: u32, screen: u32, mode: TopologyOrientation, result: *mut TopologyPlace, ) -> i32</code>

; <code>fn get_opposite_facelet(module: u32, screen: u32, result: *mut TopologyFaceletInfo) -> i32</code>

; <code>fn get_angle(module: u32, screen: u32, mode: TopologyOrientation) -> i32</code>

; <code>fn get_facelet_orientation(module: u32, screen: u32) -> i32</code>

; <code>fn get_place_orientation(face: u32, position: u32) -> i32</code>

; <code>fn get_face(orientation: u32) -> i32</code>

; <code>fn is_assembled() -> bool</code>

; <code>fn get_twist(twist: *mut TopologyTwistInfo) -> i32</code>

; <code>fn debug_get_face(module: u32, screen: u32) -> i32</code>

; <code>fn debug_get_position(module: u32, screen: u32) -> i32</code>

; <code>fn debug_get_horizontal() -> i32</code>

== ffi::sound ==

Sound asset id, play, cache, stop, status.

'''6 public functions:'''

; <code>fn get_asset_id(sound_name: &str) -> i32</code>

; <code>fn play(sound_id: SoundId, volume: u32) -> i32</code>

; <code>fn cache_sounds(sound_ids: &[SoundId]) -> i32</code>

; <code>fn is_playing() -> bool</code>
: Check if a sound is currently playing

; <code>fn stop() -> i32</code>
: Stop the currently playing sound

; <code>fn get_assets_count() -> i32</code>
: Get the total number of sound assets

== ffi::motion ==

Per-display accelerometer and gyroscope.

'''8 public functions:'''

; <code>fn get_face_accel_x(display: u32) -> i32</code>
: Get raw accelerometer value along the screen-local X-axis (horizontal right). At rest, this reads the X-component of gravity in the screen's coordinate frame. During motion, reads gravity + linear acceleration. # Parameters - `display`: Screen index (0–23). All 3 screens on a module return the same physical measurement, transformed to screen-local coordinates.

; <code>fn get_face_accel_y(display: u32) -> i32</code>
: Get raw accelerometer value along the screen-local Y-axis (vertical up). See [`get_face_accel_x`] for details on data format and coordinate frame.

; <code>fn get_face_accel_z(display: u32) -> i32</code>
: Get raw accelerometer value along the screen-local Z-axis (toward cube center). When this screen faces up, Z reads approximately -1g (gravity pulls toward center). When this screen faces down, Z reads approximately +1g. See [`get_face_accel_x`] for details on data format and coordinate frame.

; <code>fn get_face_gyro_x(display: u32) -> i32</code>
: Get raw gyroscope value for rotation around the screen-local X-axis. Measures angular velocity of the screen pitching up/down. At rest, reads approximately zero. Sign convention: positive = clockwise when looking along the positive X-axis direction (per SDK docs, unverified). # Parameters - `display`: Screen index (0–23). Same sensor sharing as accelerometer.

; <code>fn get_face_gyro_y(display: u32) -> i32</code>
: Get raw gyroscope value for rotation around the screen-local Y-axis. Measures angular velocity of the screen yawing left/right. See [`get_face_gyro_x`] for details.

; <code>fn get_face_gyro_z(display: u32) -> i32</code>
: Get raw gyroscope value for rotation around the screen-local Z-axis. Measures angular velocity of the screen spinning in-plane (like a wheel). See [`get_face_gyro_x`] for details.

; <code>fn get_face_accel(display: u32) -> (i32, i32, i32)</code>
: Get all 3 accelerometer axes for a screen in one call. Returns `(x, y, z)` in screen-local coordinates. Equivalent to calling [`get_face_accel_x`], [`get_face_accel_y`], and [`get_face_accel_z`] separately. # Parameters - `display`: Screen index (0–23).

; <code>fn get_face_gyro(display: u32) -> (i32, i32, i32)</code>
: Get all 3 gyroscope axes for a screen in one call. Returns `(x, y, z)` angular velocities in screen-local coordinates. Equivalent to calling [`get_face_gyro_x`], [`get_face_gyro_y`], and [`get_face_gyro_z`] separately. # Parameters - `display`: Screen index (0–23).

== ffi::leaderboard ==

Leaderboard info and score table.

'''3 public functions:'''

; <code>fn get_info(info: *mut LbInfo) -> i32</code>

; <code>fn get_info_safe() -> LbInfo</code>
: Get leaderboard info with safe interface

; <code>fn get_score(lead_table_bin: &mut [u8]) -> i32</code>

== ffi::event ==

Pending-event mask (<code>Event</code>, <code>get_list</code>).

'''Types:''' <code>enum Event</code> — Event flags returned by `get_list()`

'''2 public functions:'''

; <code>fn get_list() -> i32</code>

; <code>fn has_event(event_list: i32, event: Event) -> bool</code>
: Check if a specific event is set in the event list

== ffi::network_message ==

Bit-packed serializer for inter-module messages.

'''Types:''' <code>struct NetworkMessage</code> — Bit-packed network message for inter-module communication. Allows packing multiple values into a compact byte buffer using variable bit widths for efficient network transmission.

'''17 public functions:'''

; <code>fn new() -> Self</code>
: Create a new empty network message.

; <code>fn from_data(data: &[u8]) -> Self</code>
: Create a network message from existing data.

; <code>fn reset(&mut self, zero: bool)</code>
: Reset the message position. If `zero` is true, also clear the buffer.

; <code>fn get_data(&self) -> &[u8]</code>
: Get the underlying data buffer and used length.

; <code>fn can_read(&self, bits: usize) -> bool</code>
: Returns true if at least `bits` more bits can be read from the current position.

; <code>fn write_int(&mut self, value: u32, bits: u8)</code>
: Write an unsigned integer with specified bit width (1-32 bits). This writes raw bits without sign handling. For signed values that need sign extension when read back, use [`write_signed_int`](Self::write_signed_int). # Arguments * `value` - The unsigned value to write (only the lower `bits` bits are used) * `bits` - Number of bits to write (1-32, clamped if larger) # Note on C++ SDK difference The C++ `WriteInt` uses `int` (signed), but performs unsigned bit operations. This Rust version uses `u32` to make the unsigned semantics explicit.

; <code>fn write_byte(&mut self, value: u8)</code>
: Write a single byte (8 bits).

; <code>fn write_signed_int(&mut self, value: i32, bits: u8)</code>
: Write a signed integer with specified bit width.

; <code>fn write_bool(&mut self, value: bool)</code>
: Write a boolean (1 bit).

; <code>fn write_float(&mut self, value: f32)</code>
: Write a 32-bit float.

; <code>fn read_int(&mut self, bits: u8) -> u32</code>
: Read an unsigned integer with specified bit width. This reads raw bits without sign extension. For signed values that were written with [`write_signed_int`](Self::write_signed_int), use [`read_signed_int`](Self::read_signed_int) to properly sign-extend. # Arguments * `bits` - Number of bits to read (1-32, clamped if larger) # Returns The unsigned value read from the message buffer. # Note on C++ SDK difference The C++ `ReadInt` returns `int` (signed), but performs unsigned bit operations. This Rust version returns `u32` to make the unsigned semantics explicit.

; <code>fn read_byte(&mut self) -> u8</code>
: Read a single byte.

; <code>fn read_signed_int(&mut self, bits: u8) -> i32</code>
: Read a signed integer with specified bit width.

; <code>fn read_bool(&mut self) -> bool</code>
: Read a boolean.

; <code>fn read_float(&mut self) -> f32</code>
: Read a 32-bit float.

; <code>fn position(&self) -> usize</code>
: Get current bit position.

; <code>fn can_write(&self, bits: usize) -> bool</code>
: Check if there's enough space to write `bits` more bits.

== ffi::save_message ==

Bit-packed serializer for the persistent save buffer.

'''Types:''' <code>struct SaveMessage</code> — Bit-packed save message for game state persistence. Allows packing multiple values into a compact byte buffer using variable bit widths for efficient save data storage.

'''18 public functions:'''

; <code>fn new() -> Self</code>
: Create a new empty save message.

; <code>fn from_data(data: &[u8]) -> Self</code>
: Create a save message from existing data.

; <code>fn reset(&mut self, zero: bool)</code>
: Reset the message position. If `zero` is true, also clear the buffer.

; <code>fn get_data(&self) -> &[u8]</code>
: Get the underlying data buffer (only the used portion).

; <code>fn get_buffer_mut(&mut self) -> &mut [u8]</code>
: Get the full buffer for loading saved data.

; <code>fn write_int(&mut self, value: u32, bits: u8)</code>
: Write an unsigned integer with specified bit width (1-32 bits). This writes raw bits without sign handling. For signed values that need sign extension when read back, use [`write_signed_int`](Self::write_signed_int). # Arguments * `value` - The unsigned value to write (only the lower `bits` bits are used) * `bits` - Number of bits to write (1-32, clamped if larger) # Note on C++ SDK difference The C++ `WriteInt` uses `int` (signed), but performs unsigned bit operations. This Rust version uses `u32` to make the unsigned semantics explicit.

; <code>fn write_byte(&mut self, value: u8)</code>
: Write a single byte (8 bits).

; <code>fn write_signed_int(&mut self, value: i32, bits: u8)</code>
: Write a signed integer with specified bit width.

; <code>fn write_bool(&mut self, value: bool)</code>
: Write a boolean (1 bit).

; <code>fn write_float(&mut self, value: f32)</code>
: Write a 32-bit float.

; <code>fn read_int(&mut self, bits: u8) -> u32</code>
: Read an unsigned integer with specified bit width. This reads raw bits without sign extension. For signed values that were written with [`write_signed_int`](Self::write_signed_int), use [`read_signed_int`](Self::read_signed_int) to properly sign-extend. # Arguments * `bits` - Number of bits to read (1-32, clamped if larger) # Returns The unsigned value read from the save buffer. # Note on C++ SDK difference The C++ `ReadInt` returns `int` (signed), but performs unsigned bit operations. This Rust version returns `u32` to make the unsigned semantics explicit.

; <code>fn read_byte(&mut self) -> u8</code>
: Read a single byte.

; <code>fn read_signed_int(&mut self, bits: u8) -> i32</code>
: Read a signed integer with specified bit width.

; <code>fn read_bool(&mut self) -> bool</code>
: Read a boolean.

; <code>fn read_float(&mut self) -> f32</code>
: Read a 32-bit float.

; <code>fn position(&self) -> usize</code>
: Get current bit position.

; <code>fn can_write(&self, bits: usize) -> bool</code>
: Check if there's enough space to write `bits` more bits.

; <code>fn set_used_bits(&mut self, bits: usize)</code>
: Set the number of used bits (for after loading data).

== ffi::screen ==

Low-level screen descriptor (id, angle, face, position) + <code>create_screens()</code>.

'''Types:''' <code>struct Screen</code> — Represents a screen on a WOWCube module. Each module has 3 screens. This struct provides access to screen properties like position, orientation, and display ID for rendering purposes.

'''7 public functions:'''

; <code>fn new(display_id: u8) -> Self</code>
: Creates a new Screen for the given display ID on this module.

; <code>fn id(&self) -> u8</code>
: Returns the display ID (0-2).

; <code>fn angle(&self) -> u32</code>
: Returns the current rotation angle.

; <code>fn position(&self) -> u32</code>
: Returns the position in the topology.

; <code>fn face(&self) -> i32</code>
: Returns the face this screen is on.

; <code>fn update_from_topology(&mut self, module: u32, orientation: TopologyOrientation)</code>
: Updates screen topology information from the system.

; <code>fn create_screens() -> [Screen; 3]</code>
: Creates an array of 3 screens for a module, initialized with display IDs 0, 1, 2.

== ffi::math ==

<code>Vec2</code>/<code>Vec2i</code>, <code>Color</code>, <code>Transform</code>, <code>Rect2</code>, trigonometry and fixed-point helpers (no_std, libm).

'''Types:''' <code>struct Vec2</code> — 2D vector with floating-point components. · <code>struct Vec2i</code> — 2D vector with integer components. · <code>struct Color</code> — ARGB color with 8-bit components. Stored as a packed u32 in ARGB format: 0xAARRGGBB · <code>struct Transform</code> — Transform with position, rotation, scale, and mirroring. · <code>struct Rect2</code> — 2D rectangle defined by top-left and dimensions.

'''57 public functions:'''

; <code>fn log2(f: f32) -> f32</code>
: Log base 2.

; <code>fn iclamp(val: i32, min_val: i32, max_val: i32) -> i32</code>
: Clamp an integer value between min and max.

; <code>fn acos(x: f32) -> f32</code>
: Arc cosine with value clamping to [-1, 1].

; <code>fn asin(x: f32) -> f32</code>
: Arc sine with value clamping to [-1, 1].

; <code>fn sqrt(x: f32) -> f32</code>
: Safe square root (negative values return 0).

; <code>fn fequal(f0: f32, f1: f32, tol: f32) -> bool</code>
: Fuzzy floating point equality check.

; <code>fn fless(f0: f32, f1: f32, tol: f32) -> bool</code>
: Fuzzy floating point less-than check.

; <code>fn fgreater(f0: f32, f1: f32, tol: f32) -> bool</code>
: Fuzzy floating point greater-than check.

; <code>fn ftol(val: f32) -> i32</code>
: Fast float to int conversion (truncates). Note: This is a portable implementation that matches the C++ SDK behavior.

; <code>fn smooth(new_val: f32, cur_val: f32, max_change: f32) -> f32</code>
: Smooth a value towards a target using max change per step.

; <code>fn clamp(val: f32, lower: f32, upper: f32) -> f32</code>
: Clamp a float value between lower and upper bounds.

; <code>fn saturate(val: f32) -> f32</code>
: Saturate a value (clamp between 0.0 and 1.0).

; <code>fn deg2rad(d: f32) -> f32</code>
: Convert degrees to radians.

; <code>fn rad2deg(r: f32) -> f32</code>
: Convert radians to degrees.

; <code>fn n_abs(a: f32) -> f32</code>
: Get the absolute value.

; <code>fn n_sgn(a: f32) -> i32</code>
: Get the sign of a value (-1 or 1).

; <code>fn n_max<T: PartialOrd>(a: T, b: T) -> T</code>
: Return the maximum of two values.

; <code>fn n_min<T: PartialOrd>(a: T, b: T) -> T</code>
: Return the minimum of two values.

; <code>fn lerp(x: f32, y: f32, l: f32) -> f32</code>
: Linearly interpolate between two values. Returns `x + l * (y - x)`.

; <code>fn rand_get_seed() -> u32</code>
: Get the current random seed.

; <code>fn rand_set_seed(s: u32)</code>
: Set the random seed.

; <code>fn rand() -> u32</code>
: Generate a random u32 using LCG algorithm.

; <code>fn rand2() -> f32</code>
: Return a pseudo random number between 0.0 and 1.0.

; <code>fn rand_int(n: i32) -> i32</code>
: Return a random integer in range [0, n].

; <code>fn rand_real() -> f32</code>
: Return a random float in [0.0, 1.0].

; <code>fn new(x: f32, y: f32) -> Self</code>
: Create a new vector.

; <code>fn zero() -> Self</code>
: Zero vector.

; <code>fn set(&mut self, x: f32, y: f32)</code>
: Set components.

; <code>fn len(&self) -> f32</code>
: Calculate length.

; <code>fn normalize(&mut self)</code>
: Normalize in place.

; <code>fn normalized(&self) -> Self</code>
: Return normalized copy.

; <code>fn dot(&self, other: &Self) -> f32</code>
: Dot product.

; <code>fn new(x: i16, y: i16) -> Self</code>
: Create a new vector.

; <code>fn zero() -> Self</code>
: Zero vector.

; <code>fn rgb(r: u8, g: u8, b: u8) -> Self</code>
: Create from RGB (alpha = 255).

; <code>fn rgba(r: u8, g: u8, b: u8, a: u8) -> Self</code>
: Create from RGBA.

; <code>fn from_u32(value: u32) -> Self</code>
: Create from packed u32 value (0xAARRGGBB format).

; <code>fn value(&self) -> u32</code>
: Get the packed u32 value.

; <code>fn r(&self) -> u8</code>
: Get red component.

; <code>fn g(&self) -> u8</code>
: Get green component.

; <code>fn b(&self) -> u8</code>
: Get blue component.

; <code>fn a(&self) -> u8</code>
: Get alpha component.

; <code>fn a_f32(&self) -> f32</code>
: Get alpha as float (0.0 - 1.0).

; <code>fn set_r(&mut self, r: u8)</code>
: Set red component.

; <code>fn set_g(&mut self, g: u8)</code>
: Set green component.

; <code>fn set_b(&mut self, b: u8)</code>
: Set blue component.

; <code>fn set_a(&mut self, a: u8)</code>
: Set alpha component.

; <code>fn set_a_f32(&mut self, a: f32)</code>
: Set alpha from float (0.0 - 1.0).

; <code>fn new(x: f32, y: f32) -> Self</code>
: Create a new transform at position.

; <code>fn with_rotation(x: f32, y: f32, rotation: i32) -> Self</code>
: Create with position and rotation.

; <code>fn with_scale(x: f32, y: f32, rotation: i32, scale: u32) -> Self</code>
: Create with position, rotation, and uniform scale.

; <code>fn safe_rotation(&self) -> i32</code>
: Get rotation normalized to 0-359.

; <code>fn set_scale(&mut self, scale: u32)</code>
: Set uniform scale.

; <code>fn new(x: i16, y: i16, w: i16, h: i16) -> Self</code>
: Create a new rectangle.

; <code>fn contains(&self, px: i16, py: i16) -> bool</code>
: Check if a point is inside the rectangle.

; <code>fn contains_point(&self, p: Vec2i) -> bool</code>
: Check if point (as Vec2i) is inside.

; <code>fn center(&self) -> Vec2i</code>
: Get the center point.

== ffi::types ==

ABI enums and structs (<code>TopologyFaceletInfo</code>, <code>TopologyTwistInfo</code>, <code>TextAlign</code>, <code>GfxMirror</code>, …).

'''Types:''' <code>enum UartId</code> — UART line identifiers · <code>enum GfxPixelFormat</code> — Pixel format for baked images · <code>enum GfxMirror</code> — Mirror mode for sprites · <code>enum TopologyNeighbour</code> — Topology neighbor direction · <code>enum TopologyOrientation</code> — Topology orientation mode · <code>enum TopologyTwist</code> — Twist direction for cube rotations · <code>enum TextAlign</code> — Text alignment options · <code>enum TopologyLocation</code> — Topology face location · <code>enum LogLevel</code> — Log level for debug output · <code>struct TopologyFaceletInfo</code> — Information about a facelet in the topology · <code>struct TopologyPlace</code> — Place information (face and position) · <code>struct TopologyTwistInfo</code> — Twist event information · <code>struct LbInfo</code> — Leaderboard information · <code>struct GfxParticle</code> — Particle effect parameters · <code>struct AppVersion</code> — Application version (packed bitfield in C++)

'''4 public functions:'''

; <code>fn from_u32(value: u32) -> Self</code>
: Converts a u32 value to a GfxMirror variant. Returns `GfxMirror::None` for invalid values.

; <code>fn patch(&self) -> u16</code>
: Extract patch version (bits 0-15)

; <code>fn minor(&self) -> u8</code>
: Extract minor version (bits 16-19)

; <code>fn major(&self) -> u8</code>
: Extract major version (bits 20-23)

== ffi::constants ==

Platform constants (screen size, module counts, buffer limits, <code>CUBE_N</code>).

[[Category:SDK 6.3]]
[[Category:Rust API]]

SDK 6.3

2026-07-26T10:41:06Z

WowBot: Link public CubiOS Rust SDK repo (WowBot)

{{notice|'''Official WOWCube SDK 6.3 documentation.''' Canonical API reference, generated from the SDK headers.}}

The current WOWCube SDK. Applications can be written in '''PAWN''', '''C++''', or '''Rust'''.

== PAWN API ==
'''Legacy:''' supported, but no longer actively developed (last PAWN additions — SDK 6.2; 6.3 only removed deprecated calls). For new projects use the [[#C++ API|C++ API]].
One page per module:
* [[SDK 6.3/PAWN/Core]] — application lifecycle, state, time, RNG, packets
* [[SDK 6.3/PAWN/Graphics]] — drawing, images, text, shaders (GFX)
* [[SDK 6.3/PAWN/Topology]] — cube geometry, facelets, twists
* [[SDK 6.3/PAWN/Sound]] — sound playback
* [[SDK 6.3/PAWN/Motion Sensor]] — accelerometer / gyroscope, taps
* [[SDK 6.3/PAWN/Leaderboard]] — scores and achievements
* [[SDK 6.3/PAWN/Splash Screen]] — splash screens
* [[SDK 6.3/PAWN/Physics]] — 2D physics helpers
* [[SDK 6.3/PAWN/Network]] — inter-module messaging
* [[SDK 6.3/PAWN/Save]] — persistence
* [[SDK 6.3/PAWN/Scramble]] — cube scramble
* [[SDK 6.3/PAWN/Logging]] — debug logging

* [[SDK 6.3/Changelog|SDK changelog]] — what changed in 5.1 / 6.0 / 6.2 / 6.3

== C++ API ==
C/C++ cubeapps run via WebAssembly: the same engine functions as PAWN, plus an object-oriented framework and a retained scene graph. '''This is the primary development track.'''

'''Native engine ABI''' — [[SDK 6.3/C++/Native API]] (all 64 functions with full descriptions):
* [[SDK 6.3/C++/Core|Core]] — time, RNG, packets, BLE, saves, user, version, logging
* [[SDK 6.3/C++/Graphics|Graphics]] — drawing, images, text, shaders, QR, render targets
* [[SDK 6.3/C++/Topology|Topology]] — facelets, faces, twists, orientation
* [[SDK 6.3/C++/Sound|Sound]] — playback and caching
* [[SDK 6.3/C++/Motion Sensors|Motion Sensors]] — accelerometer / gyroscope per display
* [[SDK 6.3/C++/Leaderboard|Leaderboard]] — scores and rankings
* [[SDK 6.3/C++/Native API#Types and data structures|Types & data structures]] — structs, enums, constants

'''Application framework''' — [[SDK 6.3/C++/Application]]:
* [[SDK 6.3/C++/Application#Entry point|Entry point]] · [[SDK 6.3/C++/Application#class Cubios::Application|callbacks (on_Tick, on_Render, on_Twist, …)]] · timers, networking, saves, [[SDK 6.3/C++/Application#class Cubios::AppManager|AppManager]]

'''GFX Engine (scene graph)''' — [[SDK 6.3/C++/GFX Engine]] (56 documented methods + official-sample code):
* [[SDK 6.3/C++/GFX Engine#The canonical pattern|The canonical pattern]] — how real games are structured
* [[SDK 6.3/C++/GFX Engine#Scene|Scene]] · [[SDK 6.3/C++/GFX Engine#SceneObject|SceneObject]] · [[SDK 6.3/C++/GFX Engine#Screen|Screen]]
* [[SDK 6.3/C++/GFX Engine#Gfx::Sprite|Sprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::AnimatedSprite|AnimatedSprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::SpriteAtlas|SpriteAtlas]] · [[SDK 6.3/C++/GFX Engine#Gfx::Background|Background]] · [[SDK 6.3/C++/GFX Engine#Gfx::Text|Text]] · [[SDK 6.3/C++/GFX Engine#Gfx::QRCode|QRCode]] · [[SDK 6.3/C++/GFX Engine#Gfx::OffscreenRenderTarget|OffscreenRenderTarget]]
* [[SDK 6.3/C++/GFX Engine#Sound and SoundCollection|Sound / SoundCollection]] · [[SDK 6.3/C++/GFX Engine#NetworkMessage and SaveMessage|NetworkMessage / SaveMessage]] · [[SDK 6.3/C++/GFX Engine#Scramble|Scramble]] · [[SDK 6.3/C++/GFX Engine#Splashscreen|Splashscreen]] · [[SDK 6.3/C++/GFX Engine#Math|Math]]

== Rust API ==
'''EXPERIMENTAL, supported track''' — APIs may change; the primary track is C++. Two-crate '''[https://github.com/wowcube/CubiOS_Rust_SDK CubiOS Rust SDK]''' (public GitHub) (<code>cubios-sys</code> raw + <code>cubios</code> high-level), 1:1 parity with C++ 6.3, 533 public functions.
* [[SDK 6.3/Rust#Crate layout|Crate layout]] — modules <code>application</code> and <code>cubios</code>
* [[SDK 6.3/Rust#Application trait|Application trait]] — <code>on_init / on_tick / on_render / on_timer</code>, timers
* [[SDK 6.3/Rust#Entry points|Entry points]] — <code>on_init(cid)</code> / <code>run()</code>
* [[SDK 6.3/Rust#FFI types|FFI types]] — topology, leaderboard, particles, enums
* [[SDK 6.3/Rust#Examples|Examples]] — three buildable projects in the DevKit

----
See also: [[:Category:SDK 6.3|all SDK 6.3 pages]].
[[Category:SDK 6.3]]

Development

2026-07-26T10:41:06Z

WowBot: Link CubiOS Rust SDK repo (WowBot)

Developing WOWCube-specific applications

If you have a coding question, consider visiting '''#how-to''' in our Discord's Code Desk (https://discord.gg/kCay3Rdbst) for getting help from fellow developers and official support both.

{{notice|'''Official API reference: [[SDK 6.3]].''' The current SDK 6.3 API — one page per module (PAWN now; C++ and Rust coming). '''Start here → [[SDK 6.3]].'''}}

WOWCube offers several programming paradigms.
{{APIBox
|name=WOWCube runtime API
|runtime=PAWN (SDK 6.3)
|purpose=Cube-specific drawing, topology, input, sound and storage functions.
|constraints=See the per-module pages under [[SDK 6.3]].
}}
Development of specialized applications (cubelets) can be carried out:

===in PAWN. Pawn language is a derivative of “Small C”===
(See [https://github.com/compuphase/pawn/blob/master/doc/Pawn_Language_Guide.pdf Pawn_Language_Guide.pdf], and [https://wiki.alliedmods.net/Pawn_Tutorial Pawn Tutorial])
:: [[SDK 6.3|'''SDK 6.3 PAWN API''' — current, official]]
:: [[API|WOWCube PAWN API (Cube-specific Pawn functions)]]
:: [[PawnProgrammingNotes|(New) "How To's" of Pawn Programming]]

===C/C++/Rust using [https://webassembly.org/ WebAssembly] ( based on wasm3 )===
:: [[WASM|WOWCube WASM API (Cube-specific Wasm functions)]]
:: [https://github.com/wowcube/CubiOS_Rust_SDK CubiOS Rust SDK on GitHub] ''(experimental)''

===also with our DevKit===

:: [[SDK|WOWCube DevKit Guide]]

:WOWCube DevKit is the multi-platform software bundle that allows developers to streamline the programming workflow for WOWCube device using only Mac/PC or a laptop, before testing games/apps on a physical cube.
:Utilizing the VSC plugin included in the DevKit, apps can be transferred to a cube via BT 4.2 as well.

===[[Errors description|WOWCube Errors description]]===
===[[Application memory description|Application memory description]]===

SDK 6.3/Rust

2026-07-26T10:41:05Z

WowBot: CubiOS Rust SDK is now public on GitHub (WowBot)

{{notice|'''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 nav}}

''← [[SDK 6.3]] · Rust''

Rust cubeapps compile to WebAssembly (<code>wasm32-unknown-unknown</code>, <code>no_std</code>) and use the same engine ABI as the [[SDK 6.3/C++/Native API|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 — '''[https://github.com/wowcube/CubiOS_Rust_SDK CubiOS_Rust_SDK]''' on GitHub:

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

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

== Application trait ==

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

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

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

== 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: <code>cargo build --release --target wasm32-unknown-unknown</code> (the workspace config adds <code>--allow-undefined</code> so engine functions become WASM imports). Package and install like a C++ cubeapp via the [https://marketplace.visualstudio.com/items?itemName=cubios-inc.WOWCubeSDK WOWCube SDK extension for VS Code].

== Conventions ==

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

== 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 (<code>wowcube_sdk</code> v0.1.0) with buildable examples (''Basics 1–3'').
* The full two-crate '''CubiOS Rust SDK''' is public: [https://github.com/wowcube/CubiOS_Rust_SDK github.com/wowcube/CubiOS_Rust_SDK] (source-available, © Cubios Inc.) — clone and build with stable Rust + <code>wasm32-unknown-unknown</code>.

For per-function semantics see the [[SDK 6.3/C++/Native API|C++ native reference]] — names map 1:1 (<code>gfx::draw_text</code> → <code>GFX_drawText</code>).

[[Category:SDK 6.3]]
[[Category:Rust API]]

Template:SDK 6.3 nav

2026-07-26T10:33:33Z

WowBot: Nav: mark Rust as experimental (WowBot)

<div style="border:1px solid #c8ccd1; background:#f8f9fa; padding:6px 10px; margin:6px 0; font-size:90%;">
'''[[SDK 6.3]] · PAWN API:''' [[SDK 6.3/PAWN/Core|Core]] ·
[[SDK 6.3/PAWN/Graphics|Graphics]] ·
[[SDK 6.3/PAWN/Topology|Topology]] ·
[[SDK 6.3/PAWN/Sound|Sound]] ·
[[SDK 6.3/PAWN/Motion Sensor|Motion Sensor]] ·
[[SDK 6.3/PAWN/Leaderboard|Leaderboard]] ·
[[SDK 6.3/PAWN/Splash Screen|Splash Screen]] ·
[[SDK 6.3/PAWN/Physics|Physics]] ·
[[SDK 6.3/PAWN/Network|Network]] ·
[[SDK 6.3/PAWN/Save|Save]] ·
[[SDK 6.3/PAWN/Scramble|Scramble]] ·
[[SDK 6.3/PAWN/Logging|Logging]] '''C++:''' [[SDK 6.3/C++/Native API|Native API]] · [[SDK 6.3/C++/Application|Application]] · [[SDK 6.3/C++/GFX Engine|GFX Engine]]  ·  '''Rust:''' [[SDK 6.3/Rust|Rust API ''(experimental)'']]  ·  [[SDK 6.3/Changelog|Changelog]]
</div><noinclude>Navigation strip for the SDK 6.3 reference. [[Category:Templates]]</noinclude>

SDK 6.3

2026-07-26T10:33:04Z

WowBot: Rust section: CubiOS Rust SDK + EXPERIMENTAL (WowBot)

{{notice|'''Official WOWCube SDK 6.3 documentation.''' Canonical API reference, generated from the SDK headers.}}

The current WOWCube SDK. Applications can be written in '''PAWN''', '''C++''', or '''Rust'''.

== PAWN API ==
'''Legacy:''' supported, but no longer actively developed (last PAWN additions — SDK 6.2; 6.3 only removed deprecated calls). For new projects use the [[#C++ API|C++ API]].
One page per module:
* [[SDK 6.3/PAWN/Core]] — application lifecycle, state, time, RNG, packets
* [[SDK 6.3/PAWN/Graphics]] — drawing, images, text, shaders (GFX)
* [[SDK 6.3/PAWN/Topology]] — cube geometry, facelets, twists
* [[SDK 6.3/PAWN/Sound]] — sound playback
* [[SDK 6.3/PAWN/Motion Sensor]] — accelerometer / gyroscope, taps
* [[SDK 6.3/PAWN/Leaderboard]] — scores and achievements
* [[SDK 6.3/PAWN/Splash Screen]] — splash screens
* [[SDK 6.3/PAWN/Physics]] — 2D physics helpers
* [[SDK 6.3/PAWN/Network]] — inter-module messaging
* [[SDK 6.3/PAWN/Save]] — persistence
* [[SDK 6.3/PAWN/Scramble]] — cube scramble
* [[SDK 6.3/PAWN/Logging]] — debug logging

* [[SDK 6.3/Changelog|SDK changelog]] — what changed in 5.1 / 6.0 / 6.2 / 6.3

== C++ API ==
C/C++ cubeapps run via WebAssembly: the same engine functions as PAWN, plus an object-oriented framework and a retained scene graph. '''This is the primary development track.'''

'''Native engine ABI''' — [[SDK 6.3/C++/Native API]] (all 64 functions with full descriptions):
* [[SDK 6.3/C++/Core|Core]] — time, RNG, packets, BLE, saves, user, version, logging
* [[SDK 6.3/C++/Graphics|Graphics]] — drawing, images, text, shaders, QR, render targets
* [[SDK 6.3/C++/Topology|Topology]] — facelets, faces, twists, orientation
* [[SDK 6.3/C++/Sound|Sound]] — playback and caching
* [[SDK 6.3/C++/Motion Sensors|Motion Sensors]] — accelerometer / gyroscope per display
* [[SDK 6.3/C++/Leaderboard|Leaderboard]] — scores and rankings
* [[SDK 6.3/C++/Native API#Types and data structures|Types & data structures]] — structs, enums, constants

'''Application framework''' — [[SDK 6.3/C++/Application]]:
* [[SDK 6.3/C++/Application#Entry point|Entry point]] · [[SDK 6.3/C++/Application#class Cubios::Application|callbacks (on_Tick, on_Render, on_Twist, …)]] · timers, networking, saves, [[SDK 6.3/C++/Application#class Cubios::AppManager|AppManager]]

'''GFX Engine (scene graph)''' — [[SDK 6.3/C++/GFX Engine]] (56 documented methods + official-sample code):
* [[SDK 6.3/C++/GFX Engine#The canonical pattern|The canonical pattern]] — how real games are structured
* [[SDK 6.3/C++/GFX Engine#Scene|Scene]] · [[SDK 6.3/C++/GFX Engine#SceneObject|SceneObject]] · [[SDK 6.3/C++/GFX Engine#Screen|Screen]]
* [[SDK 6.3/C++/GFX Engine#Gfx::Sprite|Sprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::AnimatedSprite|AnimatedSprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::SpriteAtlas|SpriteAtlas]] · [[SDK 6.3/C++/GFX Engine#Gfx::Background|Background]] · [[SDK 6.3/C++/GFX Engine#Gfx::Text|Text]] · [[SDK 6.3/C++/GFX Engine#Gfx::QRCode|QRCode]] · [[SDK 6.3/C++/GFX Engine#Gfx::OffscreenRenderTarget|OffscreenRenderTarget]]
* [[SDK 6.3/C++/GFX Engine#Sound and SoundCollection|Sound / SoundCollection]] · [[SDK 6.3/C++/GFX Engine#NetworkMessage and SaveMessage|NetworkMessage / SaveMessage]] · [[SDK 6.3/C++/GFX Engine#Scramble|Scramble]] · [[SDK 6.3/C++/GFX Engine#Splashscreen|Splashscreen]] · [[SDK 6.3/C++/GFX Engine#Math|Math]]

== Rust API ==
'''EXPERIMENTAL, supported track''' — APIs may change; the primary track is C++. Two-crate '''CubiOS Rust SDK''' (<code>cubios-sys</code> raw + <code>cubios</code> high-level), 1:1 parity with C++ 6.3, 533 public functions.
* [[SDK 6.3/Rust#Crate layout|Crate layout]] — modules <code>application</code> and <code>cubios</code>
* [[SDK 6.3/Rust#Application trait|Application trait]] — <code>on_init / on_tick / on_render / on_timer</code>, timers
* [[SDK 6.3/Rust#Entry points|Entry points]] — <code>on_init(cid)</code> / <code>run()</code>
* [[SDK 6.3/Rust#FFI types|FFI types]] — topology, leaderboard, particles, enums
* [[SDK 6.3/Rust#Examples|Examples]] — three buildable projects in the DevKit

----
See also: [[:Category:SDK 6.3|all SDK 6.3 pages]].
[[Category:SDK 6.3]]

SDK 6.3/Rust

2026-07-26T10:33:03Z

WowBot: Rust API rewritten for CubiOS Rust SDK; EXPERIMENTAL marked everywhere (WowBot)

{{notice|'''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 nav}}

''← [[SDK 6.3]] · Rust''

Rust cubeapps compile to WebAssembly (<code>wasm32-unknown-unknown</code>, <code>no_std</code>) and use the same engine ABI as the [[SDK 6.3/C++/Native API|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, <code>github.com/wowcube/CubiOS_Rust_SDK</code>; currently private — publication pending):

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

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

== Application trait ==

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

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

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

== 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: <code>cargo build --release --target wasm32-unknown-unknown</code> (the workspace config adds <code>--allow-undefined</code> so engine functions become WASM imports). Package and install like a C++ cubeapp via the [https://marketplace.visualstudio.com/items?itemName=cubios-inc.WOWCubeSDK WOWCube SDK extension for VS Code].

== Conventions ==

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

== 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 (<code>wowcube_sdk</code> v0.1.0) with buildable examples (''Basics 1–3'').
* The full two-crate '''CubiOS Rust SDK''' described above lives on the corporate GitHub (<code>wowcube/CubiOS_Rust_SDK</code>) and is being prepared for publication.

For per-function semantics see the [[SDK 6.3/C++/Native API|C++ native reference]] — names map 1:1 (<code>gfx::draw_text</code> → <code>GFX_drawText</code>).

[[Category:SDK 6.3]]
[[Category:Rust API]]

SDK 6.3/Rust

2026-07-26T09:49:53Z

WowBot: Full Rust spec: module wrappers + application layer + source availability (WowBot)

{{notice|'''Official WOWCube SDK documentation.''' SDK 6.3, Rust API — '''experimental, supported track.''' Based on the <code>wowcube_sdk</code> crate shipped with the WOWCube Development Kit; the crate sources remain authoritative.}}

{{SDK 6.3 nav}}

''← [[SDK 6.3]] · Rust''

Rust cubeapps are built to WebAssembly and use the same engine ABI as the [[SDK 6.3/C++/Native API|C++ native API]]. The Development Kit ships the '''<code>wowcube_sdk</code>''' crate (v0.1.0) together with buildable Rust example projects (''Basics 1–3'', with assets). Projects are created and built with the [https://marketplace.visualstudio.com/items?itemName=cubios-inc.WOWCubeSDK WOWCube SDK extension for VS Code].

== Crate layout ==

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

[dependencies]
cty = "0.2.2"

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

== Application trait ==

A cubeapp implements the <code>Application</code> 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 <code>AppErr</code> enum (<code>AssetNotFound</code>, <code>InvalidModule</code>, <code>InvalidTwist</code>, <code>SceneNotFound</code>, …).

== Entry points ==

The module exports two <code>extern "C"</code> 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);
}

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

== FFI types ==

<code>wowcube_sdk::cubios</code> mirrors the [[SDK 6.3/C++/Native API#Types and data structures|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: <code>TopologyNeighbour</code> (None/Left/Diagonal/Top/Right/Bottom), <code>TopologyOrientation</code> (Menu/Gravity/Splash), <code>TopologyLocation</code> (Up/Down/Front/Back/Left/Right), <code>TextAlign</code> (9 values), <code>LogLevel</code>, <code>UartId</code>; constant <code>NET_BROADCAST = 0xFF</code>; type aliases <code>SoundId</code>, <code>SpriteId</code>.

For the semantics of the underlying engine functions (graphics, sound, topology, sensors, leaderboard) see the [[SDK 6.3/C++/Native API|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'' (<code>get_cuben</code>, <code>get_reversed_face</code>, <code>debug_get_face</code>, <code>debug_get_position</code>) have no direct C counterpart.

== Application layer (application) ==

Beyond the plain <code>Application</code> trait, the crate ships a small game framework:

; <code>trait Assetable</code> / <code>trait Mappable</code> / <code>trait Packable</code> / <code>trait Broadcastable</code> / <code>trait Shuffable</code>

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

; <code>struct MapBase<T: Packable></code>

: Base container for a distributed game map synchronized across modules.

; <code>struct SceneSwitch</code> — <code>new(scenes, start_time)</code>, <code>next_scene()</code>, <code>set_scene(id)</code>, <code>animate()</code>

: Scene/screen switching with animation.

; <code>struct TimerController</code> — <code>set_timer(id, delay, suspended)</code>, <code>delta_time()</code>

: Programmable timers driving <code>on_timer</code>.

; <code>struct ApplicationContext</code>

: Holds the timer controller and per-app state; returned by <code>app_context_mut()</code>.

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

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

== Source availability ==

The crate ships '''inside the WOWCube Development Kit''' (<code>sdk/…/rust/</code>); 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 <code>examples/…/rust/Basics</code>, each with a <code>project/src/main.rs</code>, <code>cubeapp.rs</code>, an <code>assets/</code> folder and a <code>wowcubeapp-build.json</code> build manifest.

[[Category:SDK 6.3]]
[[Category:Rust API]]

SDK 6.3

2026-07-26T09:48:08Z

WowBot: C++ module links -> direct pages (WowBot)

{{notice|'''Official WOWCube SDK 6.3 documentation.''' Canonical API reference, generated from the SDK headers.}}

The current WOWCube SDK. Applications can be written in '''PAWN''', '''C++''', or '''Rust'''.

== PAWN API ==
'''Legacy:''' supported, but no longer actively developed (last PAWN additions — SDK 6.2; 6.3 only removed deprecated calls). For new projects use the [[#C++ API|C++ API]].
One page per module:
* [[SDK 6.3/PAWN/Core]] — application lifecycle, state, time, RNG, packets
* [[SDK 6.3/PAWN/Graphics]] — drawing, images, text, shaders (GFX)
* [[SDK 6.3/PAWN/Topology]] — cube geometry, facelets, twists
* [[SDK 6.3/PAWN/Sound]] — sound playback
* [[SDK 6.3/PAWN/Motion Sensor]] — accelerometer / gyroscope, taps
* [[SDK 6.3/PAWN/Leaderboard]] — scores and achievements
* [[SDK 6.3/PAWN/Splash Screen]] — splash screens
* [[SDK 6.3/PAWN/Physics]] — 2D physics helpers
* [[SDK 6.3/PAWN/Network]] — inter-module messaging
* [[SDK 6.3/PAWN/Save]] — persistence
* [[SDK 6.3/PAWN/Scramble]] — cube scramble
* [[SDK 6.3/PAWN/Logging]] — debug logging

* [[SDK 6.3/Changelog|SDK changelog]] — what changed in 5.1 / 6.0 / 6.2 / 6.3

== C++ API ==
C/C++ cubeapps run via WebAssembly: the same engine functions as PAWN, plus an object-oriented framework and a retained scene graph. '''This is the primary development track.'''

'''Native engine ABI''' — [[SDK 6.3/C++/Native API]] (all 64 functions with full descriptions):
* [[SDK 6.3/C++/Core|Core]] — time, RNG, packets, BLE, saves, user, version, logging
* [[SDK 6.3/C++/Graphics|Graphics]] — drawing, images, text, shaders, QR, render targets
* [[SDK 6.3/C++/Topology|Topology]] — facelets, faces, twists, orientation
* [[SDK 6.3/C++/Sound|Sound]] — playback and caching
* [[SDK 6.3/C++/Motion Sensors|Motion Sensors]] — accelerometer / gyroscope per display
* [[SDK 6.3/C++/Leaderboard|Leaderboard]] — scores and rankings
* [[SDK 6.3/C++/Native API#Types and data structures|Types & data structures]] — structs, enums, constants

'''Application framework''' — [[SDK 6.3/C++/Application]]:
* [[SDK 6.3/C++/Application#Entry point|Entry point]] · [[SDK 6.3/C++/Application#class Cubios::Application|callbacks (on_Tick, on_Render, on_Twist, …)]] · timers, networking, saves, [[SDK 6.3/C++/Application#class Cubios::AppManager|AppManager]]

'''GFX Engine (scene graph)''' — [[SDK 6.3/C++/GFX Engine]] (56 documented methods + official-sample code):
* [[SDK 6.3/C++/GFX Engine#The canonical pattern|The canonical pattern]] — how real games are structured
* [[SDK 6.3/C++/GFX Engine#Scene|Scene]] · [[SDK 6.3/C++/GFX Engine#SceneObject|SceneObject]] · [[SDK 6.3/C++/GFX Engine#Screen|Screen]]
* [[SDK 6.3/C++/GFX Engine#Gfx::Sprite|Sprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::AnimatedSprite|AnimatedSprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::SpriteAtlas|SpriteAtlas]] · [[SDK 6.3/C++/GFX Engine#Gfx::Background|Background]] · [[SDK 6.3/C++/GFX Engine#Gfx::Text|Text]] · [[SDK 6.3/C++/GFX Engine#Gfx::QRCode|QRCode]] · [[SDK 6.3/C++/GFX Engine#Gfx::OffscreenRenderTarget|OffscreenRenderTarget]]
* [[SDK 6.3/C++/GFX Engine#Sound and SoundCollection|Sound / SoundCollection]] · [[SDK 6.3/C++/GFX Engine#NetworkMessage and SaveMessage|NetworkMessage / SaveMessage]] · [[SDK 6.3/C++/GFX Engine#Scramble|Scramble]] · [[SDK 6.3/C++/GFX Engine#Splashscreen|Splashscreen]] · [[SDK 6.3/C++/GFX Engine#Math|Math]]

== Rust API ==
'''Experimental / advanced track''' (crate <code>wowcube_sdk</code> v0.1.0): actively shipped with SDK 6.3, builds to the same WebAssembly ABI as C++.
* [[SDK 6.3/Rust#Crate layout|Crate layout]] — modules <code>application</code> and <code>cubios</code>
* [[SDK 6.3/Rust#Application trait|Application trait]] — <code>on_init / on_tick / on_render / on_timer</code>, timers
* [[SDK 6.3/Rust#Entry points|Entry points]] — <code>on_init(cid)</code> / <code>run()</code>
* [[SDK 6.3/Rust#FFI types|FFI types]] — topology, leaderboard, particles, enums
* [[SDK 6.3/Rust#Examples|Examples]] — three buildable projects in the DevKit

----
See also: [[:Category:SDK 6.3|all SDK 6.3 pages]].
[[Category:SDK 6.3]]

SDK 6.3/C++/Sound

2026-07-26T09:47:46Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3/C++/Native API

2026-07-26T09:47:46Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3/C++/Motion Sensors

2026-07-26T09:47:45Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3/C++/Graphics

2026-07-26T09:47:45Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3/C++/Topology

2026-07-26T09:47:44Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3/C++/Leaderboard

2026-07-26T09:47:44Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3/C++/Core

2026-07-26T09:47:43Z

WowBot: Split C++ Native API into per-module pages with minimal examples (WowBot)

SDK 6.3

2026-07-26T09:46:20Z

WowBot: Rust section: status + topic links (WowBot)

{{notice|'''Official WOWCube SDK 6.3 documentation.''' Canonical API reference, generated from the SDK headers.}}

The current WOWCube SDK. Applications can be written in '''PAWN''', '''C++''', or '''Rust'''.

== PAWN API ==
'''Legacy:''' supported, but no longer actively developed (last PAWN additions — SDK 6.2; 6.3 only removed deprecated calls). For new projects use the [[#C++ API|C++ API]].
One page per module:
* [[SDK 6.3/PAWN/Core]] — application lifecycle, state, time, RNG, packets
* [[SDK 6.3/PAWN/Graphics]] — drawing, images, text, shaders (GFX)
* [[SDK 6.3/PAWN/Topology]] — cube geometry, facelets, twists
* [[SDK 6.3/PAWN/Sound]] — sound playback
* [[SDK 6.3/PAWN/Motion Sensor]] — accelerometer / gyroscope, taps
* [[SDK 6.3/PAWN/Leaderboard]] — scores and achievements
* [[SDK 6.3/PAWN/Splash Screen]] — splash screens
* [[SDK 6.3/PAWN/Physics]] — 2D physics helpers
* [[SDK 6.3/PAWN/Network]] — inter-module messaging
* [[SDK 6.3/PAWN/Save]] — persistence
* [[SDK 6.3/PAWN/Scramble]] — cube scramble
* [[SDK 6.3/PAWN/Logging]] — debug logging

* [[SDK 6.3/Changelog|SDK changelog]] — what changed in 5.1 / 6.0 / 6.2 / 6.3

== C++ API ==
C/C++ cubeapps run via WebAssembly: the same engine functions as PAWN, plus an object-oriented framework and a retained scene graph. '''This is the primary development track.'''

'''Native engine ABI''' — [[SDK 6.3/C++/Native API]] (all 64 functions with full descriptions):
* [[SDK 6.3/C++/Native API#Core|Core]] — time, RNG, packets, BLE, saves, user, version, logging
* [[SDK 6.3/C++/Native API#Graphics|Graphics]] — drawing, images, text, shaders, QR, render targets
* [[SDK 6.3/C++/Native API#Topology|Topology]] — facelets, faces, twists, orientation
* [[SDK 6.3/C++/Native API#Sound|Sound]] — playback and caching
* [[SDK 6.3/C++/Native API#Motion Sensors|Motion Sensors]] — accelerometer / gyroscope per display
* [[SDK 6.3/C++/Native API#Leaderboard|Leaderboard]] — scores and rankings
* [[SDK 6.3/C++/Native API#Types and data structures|Types & data structures]] — structs, enums, constants

'''Application framework''' — [[SDK 6.3/C++/Application]]:
* [[SDK 6.3/C++/Application#Entry point|Entry point]] · [[SDK 6.3/C++/Application#class Cubios::Application|callbacks (on_Tick, on_Render, on_Twist, …)]] · timers, networking, saves, [[SDK 6.3/C++/Application#class Cubios::AppManager|AppManager]]

'''GFX Engine (scene graph)''' — [[SDK 6.3/C++/GFX Engine]] (56 documented methods + official-sample code):
* [[SDK 6.3/C++/GFX Engine#The canonical pattern|The canonical pattern]] — how real games are structured
* [[SDK 6.3/C++/GFX Engine#Scene|Scene]] · [[SDK 6.3/C++/GFX Engine#SceneObject|SceneObject]] · [[SDK 6.3/C++/GFX Engine#Screen|Screen]]
* [[SDK 6.3/C++/GFX Engine#Gfx::Sprite|Sprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::AnimatedSprite|AnimatedSprite]] · [[SDK 6.3/C++/GFX Engine#Gfx::SpriteAtlas|SpriteAtlas]] · [[SDK 6.3/C++/GFX Engine#Gfx::Background|Background]] · [[SDK 6.3/C++/GFX Engine#Gfx::Text|Text]] · [[SDK 6.3/C++/GFX Engine#Gfx::QRCode|QRCode]] · [[SDK 6.3/C++/GFX Engine#Gfx::OffscreenRenderTarget|OffscreenRenderTarget]]
* [[SDK 6.3/C++/GFX Engine#Sound and SoundCollection|Sound / SoundCollection]] · [[SDK 6.3/C++/GFX Engine#NetworkMessage and SaveMessage|NetworkMessage / SaveMessage]] · [[SDK 6.3/C++/GFX Engine#Scramble|Scramble]] · [[SDK 6.3/C++/GFX Engine#Splashscreen|Splashscreen]] · [[SDK 6.3/C++/GFX Engine#Math|Math]]

== Rust API ==
'''Experimental / advanced track''' (crate <code>wowcube_sdk</code> v0.1.0): actively shipped with SDK 6.3, builds to the same WebAssembly ABI as C++.
* [[SDK 6.3/Rust#Crate layout|Crate layout]] — modules <code>application</code> and <code>cubios</code>
* [[SDK 6.3/Rust#Application trait|Application trait]] — <code>on_init / on_tick / on_render / on_timer</code>, timers
* [[SDK 6.3/Rust#Entry points|Entry points]] — <code>on_init(cid)</code> / <code>run()</code>
* [[SDK 6.3/Rust#FFI types|FFI types]] — topology, leaderboard, particles, enums
* [[SDK 6.3/Rust#Examples|Examples]] — three buildable projects in the DevKit

----
See also: [[:Category:SDK 6.3|all SDK 6.3 pages]].
[[Category:SDK 6.3]]

SDK 6.3/PAWN/Scramble

2026-07-26T09:45:55Z