macroquad

Macroquad is a standard Rust dependency. To start a new project, initialize a cargo binary project and add macroquad to your Cargo.toml dependencies.

To improve performance (especially image loading) while keeping compile times low, add the following snippet to your Cargo.toml to ensure dependencies compile with high optimization even in debug mode:

[profile.dev.package.'*']
opt-level = 3

# Create empty cargo project
cargo init --bin

[dependencies]
macroquad = "0.4"

To target WebAssembly, add the wasm32-unknown-unknown target and build using cargo build. The resulting .wasm file will be located in target/wasm32-unknown-unknown/ (debug or release). To serve the files, you can use basic-http-server.

rustup target add wasm32-unknown-unknown
cargo build --target wasm32-unknown-unknown

# To serve static files
cargo install basic-http-server
basic-http-server .

Depending on your Linux distribution, install the following system packages to support graphics and audio:

Ubuntu/Debian: apt install pkg-config libx11-dev libxi-dev libgl1-mesa-dev libasound2-dev

Fedora: dnf install libX11-devel libXi-devel mesa-libGL-devel alsa-lib-devel

Arch Linux: pacman -S pkg-config libx11 libxi mesa-libgl alsa-lib

# ubuntu system dependencies
apt install pkg-config libx11-dev libxi-dev libgl1-mesa-dev libasound2-dev

# fedora system dependencies
dnf install libX11-devel libXi-devel mesa-libGL-devel alsa-lib-devel

# arch linux system dependencies
pacman -S pkg-config libx11 libxi mesa-libgl alsa-lib

Macroquad supports both MSVC and GNU targets on Windows without additional dependencies. You can also cross-compile to Windows from Linux using the x86_64-pc-windows-gnu target.

# Cross-compiling to windows from linux
rustup target add x86_64-pc-windows-gnu

cargo run --target x86_64-pc-windows-gnu

To customize window settings, batching capacities, or update triggers, create a function that returns a macroquad::conf::Conf object and pass it to the #[macroquad::main] macro.

use macroquad::prelude::*;

fn window_conf() -> Conf {
    Conf {
        miniquad_conf: miniquad::conf::Conf {
            window_title: "Window name".to_owned(),
            fullscreen: true,
            ..Default::default()
        },
        ..Default::default()
    }
}

#[macroquad::main(window_conf)]
async fn main() {
    // ...
}

Use the #[macroquad::main] attribute to define the entry point of your application. The main function must be async. You can pass a string for the window title or a configuration function that returns a Conf object for more advanced settings.

use macroquad::prelude::*;

#[macroquad::main("BasicShapes")]
async fn main() {
    loop {
        clear_background(RED);

        draw_line(40.0, 40.0, 100.0, 200.0, 15.0, BLUE);
        draw_rectangle(screen_width() / 2.0 - 60.0, 100.0, 120.0, 60.0, GREEN);
        draw_circle(screen_width() - 30.0, screen_height() - 30.0, 15.0, YELLOW);
        draw_text("HELLO", 20.0, 20.0, 20.0, DARKGRAY);

        next_frame().await
    }
}

Use the #[macroquad::main] attribute on an async fn main() to define your entry point. The main loop should use next_frame().await to yield control and allow the engine to process the next frame. This pattern is required for cross-platform compatibility, especially for WASM and Android.

use macroquad::prelude::*;

#[macroquad::main("BasicShapes")]
async fn main() {
    loop {
        clear_background(RED);

        draw_line(40.0, 40.0, 100.0, 200.0, 15.0, BLUE);
        draw_rectangle(screen_width() / 2.0 - 60.0, 100.0, 120.0, 60.0, GREEN);
        draw_circle(screen_width() - 30.0, screen_height() - 30.0, 15.0, YELLOW);

        draw_text("IT WORKS!", 20.0, 20.0, 30.0, DARKGRAY);

        next_frame().await
    }
}