Getting Started

So you want to make games for the DreamBox! Excellent choice!
DreamBox games are built on WASM, so you can any language of your choice as long as it compiles to WASM and links to the DreamBox API.
However, for the sake of simplicity, this guide will cover how to set up a new Rust project.

Setting Up

In order to build your first DreamBox game, you will need Rust installed. Installation is pretty easy - just follow the Getting Started instructions to install Rustup and fetch the latest version of the Rust compiler and the Cargo package manager.
Once that's done, you can install the CLI helper used to create and build DreamBox projects:

cargo install dbsdk-cli

Creating a new project

Pick a folder for your project to go in and open a new terminal there. Next, run command:

dbsdk-cli new hello-dreambox

This command will create several new files: a Cargo.toml, a .cargo/config.toml, and a src/lib.rs file - basically all the components of a Rust project. To build this project, just execute another command:

dbsdk-cli build .

This command builds the project in the current location, and then produces an output build/debug.iso file. This file is actually ready to run in DreamBox! However, it won't do anything interesting - in fact, it won't do anything at all, DreamBox will just sit on a black screen.
Let's make it do something. First, add a new crate dependency:

cargo add dbsdk-rs

And next, edit src/lib.rs:

extern crate dbsdk_rs;
use dbsdk_rs::{vdp::{self, Color32}, db};

fn tick() {
    vdp::clear_color(Color32::new(128, 128, 255, 255));
}

#[no_mangle]
pub fn main(_: i32, _: i32) -> i32 {
    db::register_panic();
    db::log(format!("Hello, DreamBox!").as_str());
    vdp::set_vsync_handler(Some(tick));
    return 0;
}

Assuming everything was set up correctly, running this ISO in DreamBox should produce the following:


Congratulations! You've created your first DreamBox game!

Where is my log output?

You might be wondering what's up with that db::log line. This prints a message to the console, but if you just opened DreamBox from your desktop environment, you probably won't see any console output.
Not to worry - you just need to install a Dev build to see your console output. On Itch.IO, download any build with "dev" in its name and launch that instead.

Now when you run your game, you should now see that message in the output:

[DBG] Hello, world!