# Macroquad — Cross-Platform Game Engine in Rust

> A simple and easy-to-use Rust game library inspired by raylib, targeting web, desktop, and mobile from a single codebase.

## Install

Save in your project root:

# Macroquad — Cross-Platform Game Engine in Rust

## Quick Use
```toml
# Cargo.toml
[dependencies]
macroquad = "0.4"
```
```rust
use macroquad::prelude::*;

#[macroquad::main("MyGame")]
async fn main() {
    loop {
        clear_background(LIGHTGRAY);
        draw_circle(screen_width() / 2.0, screen_height() / 2.0, 50.0, RED);
        draw_text("Hello, Macroquad!", 20.0, 20.0, 30.0, DARKGRAY);
        next_frame().await
    }
}
```

## Introduction
Macroquad is a Rust game library that prioritizes simplicity and cross-platform reach. It compiles to native desktop targets, WebAssembly for browsers, and mobile platforms (Android/iOS), all without requiring platform-specific build steps beyond standard Rust toolchains.

## What Macroquad Does
- Renders 2D graphics including shapes, sprites, text, and tilemaps with a simple immediate-mode API
- Handles keyboard, mouse, touch, and gamepad input through straightforward polling functions
- Compiles to WASM for browser deployment with a single cargo build command
- Provides built-in audio playback for sound effects and music
- Includes a basic UI system (megaui) for in-game menus, debug panels, and tool interfaces

## Architecture Overview
Macroquad wraps a minimal OpenGL abstraction layer (miniquad) that provides a rendering context on each platform. The main game loop is an async function that yields at next_frame().await, letting the runtime handle platform event pumping and frame synchronization. Drawing commands are issued in immediate mode during each frame and batched into draw calls. This design avoids the entity-component-system complexity of larger engines and keeps the API surface small enough to learn in an afternoon.

## Self-Hosting & Configuration
- Install the Rust toolchain via rustup and add macroquad to your Cargo.toml dependencies
- For WASM builds, install the wasm32-unknown-unknown target and use cargo build --target wasm32-unknown-unknown
- For Android, use the cargo-quad-apk tool to package and sign APKs
- Configure window size, title, and fullscreen mode through the Conf struct passed to the main attribute macro
- Assets (textures, sounds, fonts) are loaded asynchronously via load_texture, load_sound, and load_ttf_font

## Key Features
- Minimal API inspired by raylib that fits in a single use macroquad::prelude::* import
- First-class WebAssembly support with no JavaScript glue code required
- No external C dependencies on most platforms, simplifying cross-compilation
- Async/await-based game loop that works identically on native and web targets
- Companion crates for physics (macroquad-platformer), particles, and tiled map loading

## Comparison with Similar Tools
- **Bevy** — full ECS game engine with a plugin ecosystem; more powerful but significantly more complex
- **ggez** — Rust 2D game framework similar in scope; uses a more traditional game loop without async
- **raylib (Rust bindings)** — C library with Rust FFI; similar API philosophy but requires C toolchain
- **Fyrox** — 3D-capable Rust game engine with a scene editor; heavier for 2D-only projects
- **Piston** — modular Rust game engine; older project with less active maintenance

## FAQ
**Q: Can Macroquad handle 3D rendering?**
A: Macroquad has basic 3D support (meshes, cameras, shaders), but it is primarily designed for 2D games. For complex 3D projects, Bevy or Fyrox are better suited.

**Q: How does Macroquad compare to raylib?**
A: Macroquad is directly inspired by raylib's API design but is written in pure Rust. It adds async/await and native WASM support that raylib's C implementation does not provide out of the box.

**Q: Does Macroquad support ECS (Entity Component System)?**
A: No. Macroquad is intentionally simple and does not include an ECS. You can add one (like hecs or legion) as a separate dependency if needed.

**Q: Is Macroquad suitable for game jams?**
A: Yes. Its minimal setup and immediate-mode API make it well suited for rapid prototyping and time-constrained game jams.

## Sources
- https://github.com/not-fl3/macroquad
- https://macroquad.rs/

---
Source: https://tokrepo.com/en/workflows/asset-94415847
Author: AI Open Source