Difference between revisions of "SDK 6.3/Rust"

From WowWiki
Jump to navigation Jump to search
(Full Rust spec: module wrappers + application layer + source availability (WowBot))
(Rust API rewritten for CubiOS Rust SDK; EXPERIMENTAL marked everywhere (WowBot))
Line 1: Line 1:
−
{{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.}}
+
{{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 nav}}
Line 5: Line 5:
 
''← [[SDK 6.3]] · Rust''
 
''← [[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].
+
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.
  
−
== Crate layout ==
+
== The CubiOS Rust SDK ==
  
−
[package]
+
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):
−
name = "wowcube_sdk"
 
−
version = "0.1.0"
 
−
edition = "2021"
 
  
−
[dependencies]
+
* '''<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>.
−
cty = "0.2.2"
+
* '''<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).
  
−
* <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>.
+
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>.
−
* <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 ==
 
== Application trait ==
  
−
A cubeapp implements the <code>Application</code> trait; all callbacks have default no-op implementations, so you override only what you need:
+
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>.
  
−
pub trait Application {
+
{| class="wikitable"
−
    fn app_context_mut(&mut self) -> &mut ApplicationContext;
+
! 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
 +
|}
  
−
    fn on_init(&mut self)  -> Result<(), AppErr> { Ok(()) }
+
Timer helpers (<code>set_timer / start_timer / stop_timer / kill_timer</code>) come with the trait via <code>ApplicationContext</code>.
−
    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 { … }
+
== 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(())
 
  }
 
  }
−
 
+
   
−
Errors are reported through the <code>AppErr</code> enum (<code>AssetNotFound</code>, <code>InvalidModule</code>, <code>InvalidTwist</code>, <code>SceneNotFound</code>, …).
+
  static mut APPLICATION: Option<HelloCube> = None;
−
 
+
−
== 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]
 
  #[no_mangle]
 
  pub extern "C" fn on_init(cid: u32) {
 
  pub extern "C" fn on_init(cid: u32) {
−
     let mut application = cubeapp::HelloWOWCube::new();
+
     let mut app = HelloCube { ctx: ApplicationContext::new() };
−
     wowcube_sdk::application::application_init(&mut application, cid);
+
     application_init(&mut app, cid);
−
     unsafe { APPLICATION = Some(application); }
+
     unsafe { *core::ptr::addr_of_mut!(APPLICATION) = Some(app) }
 
  }
 
  }
−
 
+
 
  #[no_mangle]
 
  #[no_mangle]
 
  pub extern "C" fn run() {
 
  pub extern "C" fn run() {
−
     let application = unsafe { APPLICATION.as_mut().unwrap() };
+
     let app = unsafe { (*core::ptr::addr_of_mut!(APPLICATION)).as_mut().unwrap() };
−
     wowcube_sdk::application::application_run(application);
+
     application_run(app);
 
  }
 
  }
  
−
<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>.
+
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].
−
 
 
−
== 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&lt;T: Packable&gt;</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&lt;T&gt;</code> / <code>enum RotationDir</code> / <code>enum AppPkt</code> / <code>enum AppErr</code>
 
  
−
: Animation value helper, rotation directions, standard packet kinds, error type.
+
== Conventions ==
  
−
== Source availability ==
+
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>.
  
−
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.)
+
== Availability ==
  
−
== Examples ==
+
* '''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.
  
−
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.
+
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:SDK 6.3]]
 
[[Category:Rust API]]
 
[[Category:Rust API]]

Revision as of 10:33, 26 July 2026

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

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

← SDK 6.3 · Rust

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

The CubiOS Rust SDK

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

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

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

Application trait

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

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

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

Quick start

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

struct HelloCube { ctx: ApplicationContext }

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

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

static mut APPLICATION: Option<HelloCube> = None;

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

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

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

Conventions

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

Availability

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

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

Retrieved from "https://wiki.wowcube.com/index.php?title=SDK_6.3/Rust&oldid=16972"