macroquad: A Cross-Platform Rust Game Library with Fast Build Times and Single-Command Deploys

What macroquad Is and Who It Targets

macroquad is a Rust game library described as "simple and easy to use," heavily inspired by raylib. It targets Rust developers who want to write games or interactive applications without first learning a large engine framework. The library provides 2D rendering, an immediate mode UI, audio support (as an optional feature), and cross-platform deployment in a package that builds from clean in 16 seconds on a six-year-old laptop.

The core design principle is uniformity. The README states: "Same code for all supported platforms, no platform dependent defines required." A program written against macroquad's API compiles for Windows, Linux, macOS, HTML5 (via WebAssembly), Android, and iOS without conditional compilation blocks. This matters practically: a desktop prototype becomes a browser demo with one additional build command.

The library is dual-licensed under MIT and Apache-2.0, as noted in Cargo.toml: `license = "MIT OR Apache-2.0"`. Users may choose either license. The current version is 0.4.16.

Platform Support and the async/await Design Choice

macroquad supports six platforms: Windows (both MSVC and GNU targets), Linux, macOS, HTML5 via WebAssembly, Android, and iOS. The README confirms no platform-specific defines are required in application code.

All example programs use `.await` in the main loop, which is unusual for a game library. The README explains this directly: "async/await support in macroquad comes without any external dependencies - no runtime, no executors and futures-rs is not involved. It's just a way to preserve main's stack on WASM and keep the code cross platform without any WASM-specific main loop."

The problem async solves is specific to WebAssembly. A traditional blocking loop cannot run in the browser because WASM execution must not block the JavaScript thread. macroquad uses Rust's native `Future` machinery to checkpoint the main loop at each `next_frame().await`, which allows the browser's event system to resume it on the next animation frame. On native platforms the same code runs without any executor overhead.

This design means macroquad avoids the common pattern of writing a separate HTML5 main loop. The tradeoff is that every macroquad program must be async, including programs that will never target WASM.

Creating a First Project: Setup Through First Frame

macroquad is a normal Cargo dependency. Start with an empty binary project:

cargo init --bin

Add macroquad to Cargo.toml:

[dependencies]
macroquad = "0.4"

Replace the contents of src/main.rs with a minimal example:

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
    }
}

Run it natively:

cargo run

On Linux, system libraries are required before the first build. For Ubuntu:

apt install pkg-config libx11-dev libxi-dev libgl1-mesa-dev libasound2-dev

For Fedora: `dnf install libX11-devel libXi-devel mesa-libGL-devel alsa-lib-devel`. For Arch: `pacman -S pkg-config libx11 libxi mesa-libgl alsa-lib`. On Windows and macOS no additional system libraries are needed.

Building for WebAssembly and HTML5

WebAssembly deployment requires adding the target and building with it:

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

This produces a .wasm file in `target/wasm32-unknown-unknown/debug/CRATENAME.wasm` (or the release path with `--release`). The README provides an index.html template that loads the .wasm file via macroquad's JavaScript bundle.

To serve the files locally, the README recommends a lightweight HTTP server:

cargo install basic-http-server
basic-http-server .

Cross-compilation from Linux to Windows is also supported:

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

For Android and iOS, the README provides separate instructions. iOS deployment to the simulator requires building with `cargo build --target x86_64-apple-ios --release`, copying the binary and assets into a .app bundle, and creating an Info.plist. The README links to an article at macroquad.rs/articles/ios/ for real device provisioning.

Single-command deploy for WASM and Android, which the feature list mentions, refers to the target add and cargo build steps being the full deployment pipeline for those platforms.

Optional Audio and the Dev Build Optimization

Audio support is an optional feature in macroquad. It is not enabled by default. To add audio, enable the feature in Cargo.toml:

[dependencies]
macroquad = { version = "0.4", features = ["audio"] }

The audio feature pulls in the quad-snd crate. The README does not state which audio formats quad-snd supports; refer to quad-snd's own documentation for codec coverage.

The README also documents a Cargo.toml snippet that meaningfully improves debug build performance:

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

This sets release-level optimization for all dependencies in debug builds while keeping your own code in debug mode. The README states this makes images load "several times faster" and applications "much more performant, while keeping compile times miraculously low." Image decoding in debug mode without this setting is the main cause of slow load times in macroquad prototypes.

macroquad vs miniquad: The Dependency Relationship

macroquad depends on miniquad, which is listed in Cargo.toml as `miniquad = { version = "=0.4.11" }` with an exact version pin. miniquad is the lower-level graphics and windowing layer; macroquad builds higher-level 2D drawing, UI, and audio on top of it.

Users who need only a minimal rendering surface with explicit GPU control might choose miniquad directly. Users who want ready-made 2D primitives (draw_circle, draw_text, draw_rectangle), a built-in UI system, and the full platform support with less code would choose macroquad. The two are separate crates from the same ecosystem; both are referenced in Awesome Quads at github.com/ozkriff/awesome-quads.

The common alternative at a higher architectural level is Bevy. Bevy uses an entity-component-system (ECS) architecture suited for games with complex entity lifecycles and data-driven behavior. macroquad takes a procedural approach without ECS, which is simpler for small games but less suited to large projects where ECS helps manage state.

The README notes that macroquad is "heavily inspired by raylib," which is a C library with a similar philosophy of simplicity and cross-platform support. Engineers comfortable with raylib in other languages will find macroquad's API familiar.

Limitations to Consider Before Committing

macroquad has no GitHub releases for version tracking. The library is versioned through crates.io (current 0.4.16 per Cargo.toml), but there are no GitHub release tags. Teams that want to pin to a GitHub-tagged release must reference specific commits instead.

The library's simplicity comes at the cost of missing features that a full game engine provides. macroquad does not include a scene graph, an entity-component-system, built-in 2D physics, asset management with hot reloading, or a visual editor. Projects that outgrow the procedural loop-based style require refactoring or switching to a more structured framework. This is a deliberate trade-off: the README calls it "simple and easy to use," not comprehensive. Projects that need to manage hundreds of distinct entity types with varied behaviors will find that an ECS-based framework like Bevy provides structural advantages macroquad does not attempt to offer.

Audio is not enabled by default. Any macroquad project that omits the audio feature flag will have no sound, which is easy to overlook when starting a prototype and adding audio later.

The community Discord is at discord.gg/WfEp6ut. SourceGear is listed as the platinum sponsor. The repository has no formal governance document beyond the README and the examples folder, which contains about 25 example programs covering shapes, audio, camera, platformer physics, particles, and 3D.

The last push to the repository was on 2026-08-18.

Editorial conclusion

macroquad is the right choice for Rust developers who want to write a small game or interactive demo and deploy it across platforms without spending hours on engine configuration. It is not a good fit for projects that need an entity-component-system architecture, a scene editor, or built-in 3D physics. The last push was on 2026-08-18. Check whether the current version (0.4.16 per Cargo.toml) covers the specific platform features you need before building a large project on it.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. not-fl3/macroquad on GitHub
4. README