# not-fl3/macroquad architecture

> Architecture diagram of the GitHub repository not-fl3/macroquad, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/not-fl3/macroquad
- Repository: https://github.com/not-fl3/macroquad

## Overview

##### Project type and purpose
- Macroquad is a Rust-based, cross-platform game development library (engine).
- It provides high-level APIs for 2D rendering, immediate-mode UI, input handling, audio, math utilities, and async main-loop support on PC (Windows/Linux/macOS), HTML5 (WASM), Android, and iOS.

##### File structure
Top-level directories and crates:
- macroquad_macro/ → Procedural macro crate providing `#[macroquad::main]` to bootstrap the async main loop.
- js/              → JavaScript loader/bundle (`mq_js_bundle.js`) to host WASM builds in browsers.
- examples/        → Sample applications showcasing engine features.
- particles/, physics-platformer/, profiler/, tiled/
→ Optional extension crates (plugins/libraries) that depend on the core engine.
- Cargo.toml, build scripts, GitHub Actions workflow.

##### README for additional insights
- The README highlights the supported platforms, feature set (automatic batching, immediate-mode UI), and build/deploy instructions for native, WASM, Android, iOS.
- It mentions that async/await is used internally to unify the main loop across all targets.

##### Main components & interactions
a. Core Engine (Rust crate “macroquad” – src/)
- Rendering sub-system
- UI sub-system
- Input handling
- Audio
- Asset loading & file I/O
- Async main loop
b. Procedural Macro (“macroquad_macro”)
- Generates the platform-agnostic entrypoint and ties into the async main loop.
c. Backend Abstraction (miniquad)
- Low-level platform/graphics abstraction layer (GL/Vulkan/DX) – not visible in file tree but a dependency.
d. Platform Adaptors
- Desktop: X11/Win32/Quartz + OpenGL
- WASM: JavaScript loader (js/mq_js_bundle.js) + WebGL context
- Android: JNI bindings, native activity
- iOS: Simulator & device packaging (Info.plist, .app folder)
e. Extension Crates
- particles, physics-platformer, profiler, tiled – each plugs into the core engine via public APIs.
f. Examples & Tests
- Usage patterns and validate subsystems (input, coroutines).

Data flow & relationships:
1) Game application (user code / examples) invokes macroquad APIs.
2) Macroquad public API (prelude) routes calls to subsystems (render, input, audio).
4) Backend interacts with platform OS/graphics stack or JS/WebGL.
5) Async main loop orchestrates per-frame updates (input → logic → render → next_frame()).
6) Procedural macro transforms user’s async `main` into the correct entrypoint on each target.

##### Architectural patterns & design principles
- Modular decomposition: each concern (rendering, input, audio, UI, math) lives in its own module.
- Immediate-mode UI: UI elements called every frame.
- Async main loop: single-threaded, cross-platform entrypoint.
- Proc-macro bootstrap: separates user code from platform initialization.
- Plugin/extension crates: leverage core engine abstractions without modifying core code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    User["User Game App (Examples)"]:::user
    click User "https://github.com/not-fl3/macroquad/tree/master/examples/"

    ProcMacro["Procedural Macro\n(macroquad_macro)"]:::code
    click ProcMacro "https://github.com/not-fl3/macroquad/blob/master/macroquad_macro/src/lib.rs"

    User -->|"uses API"| CoreEngineAPI
    ProcMacro -->|"codegen entrypoint"| CoreEngineAPI

    subgraph "Core Engine\n(macroquad crate)"
        direction TB
        CoreEngineAPI["Public API (Prelude)"]:::core
        AsyncLoop["Async Main Loop"]:::core
        Rendering["Rendering\n(src/quad_gl.rs, src/material.rs)"]:::core
        UI["Immediate-mode UI\n(src/ui.rs & src/ui/)"]:::core
        Input["Input Handling\n(src/input.rs)"]:::core
        Audio["Audio\n(src/audio.rs)"]:::core
        Math["Math & Shapes\n(src/math.rs & src/math/, src/shapes.rs)"]:::core
        AssetIO["Asset Loading & File I/O\n(src/file.rs & src/texture.rs)"]:::core
        Telemetry["Telemetry & Error Handling\n(src/telemetry.rs & src/error.rs)"]:::core
        Exec["Exec Module\n(src/exec.rs)"]:::core

        CoreEngineAPI --> AsyncLoop
        AsyncLoop --> Rendering
        AsyncLoop --> UI
        AsyncLoop --> Input
        AsyncLoop --> Audio
        AsyncLoop --> Math
        AsyncLoop --> AssetIO
        AsyncLoop --> Telemetry
        AsyncLoop --> Exec
    end

    click CoreEngineAPI "https://github.com/not-fl3/macroquad/blob/master/src/lib.rs"
    click AsyncLoop "https://github.com/not-fl3/macroquad/blob/master/src/exec.rs"
    click Rendering "https://github.com/not-fl3/macroquad/blob/master/src/quad_gl.rs"
    click Rendering "https://github.com/not-fl3/macroquad/blob/master/src/material.rs"
    click UI "https://github.com/not-fl3/macroquad/blob/master/src/ui.rs"
    click UI "https://github.com/not-fl3/macroquad/tree/master/src/ui/"
    click Input "https://github.com/not-fl3/macroquad/blob/master/src/input.rs"
    click Audio "https://github.com/not-fl3/macroquad/blob/master/src/audio.rs"
    click Math "https://github.com/not-fl3/macroquad/blob/master/src/math.rs"
    click Math "https://github.com/not-fl3/macroquad/tree/master/src/math/"
    click Math "https://github.com/not-fl3/macroquad/blob/master/src/shapes.rs"
    click AssetIO "https://github.com/not-fl3/macroquad/blob/master/src/file.rs"
    click AssetIO "https://github.com/not-fl3/macroquad/blob/master/src/texture.rs"
    click Telemetry "https://github.com/not-fl3/macroquad/blob/master/src/telemetry.rs"
    click Telemetry "https://github.com/not-fl3/macroquad/blob/master/src/error.rs"

    CoreEngineAPI -->|"calls"| Backend
    Rendering -->|"draw calls"| Backend
    Input -->|"event polling"| Backend

    Backend["Backend Abstraction\n(miniquad)"]:::backend

    Backend -->|"platform calls"| Desktop
    Backend -->|"WebGL"| WASMAdaptor
    Backend -->|"JNI/OpenGL ES"| Android
    Backend -->|"Metal/OpenGL ES"| iOS

    subgraph "Platform Adaptors"
        direction TB
        Desktop["Desktop\n(X11/Win32/Quartz + OpenGL)"]:::platform
        WASMAdaptor["WASM/JS\n(WebGL)"]:::platform
        Android["Android\n(JNI bindings)"]:::platform
        iOS["iOS\n(.app packaging)"]:::platform
        WASMAdaptor --> JSLoader
        JSLoader["JS Loader\n(js/mq_js_bundle.js)"]:::platform
        click JSLoader "https://github.com/not-fl3/macroquad/blob/master/js/mq_js_bundle.js"
    end

    subgraph "Extension Crates"
        direction TB
        Particles["particles"]:::ext
        Phys["physics-platformer"]:::ext
        Profiler["profiler"]:::ext
        Tiled["tiled"]:::ext
        click Particles "https://github.com/not-fl3/macroquad/blob/master/particles/src/lib.rs"
        click Phys "https://github.com/not-fl3/macroquad/blob/master/physics-platformer/src/lib.rs"
        click Profiler "https://github.com/not-fl3/macroquad/blob/master/profiler/src/lib.rs"
        click Tiled "https://github.com/not-fl3/macroquad/blob/master/tiled/src/lib.rs"
        Particles -.-> CoreEngineAPI
        Phys -.-> CoreEngineAPI
        Profiler -.-> CoreEngineAPI
        Tiled -.-> CoreEngineAPI
    end

    subgraph Legend
        direction LR
        U["User Code"]:::user
        C["Core Engine"]:::core
        B["Backend"]:::backend
        P["Platform"]:::platform
        E["Extensions"]:::ext
    end

    classDef user fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef core fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef platform fill:#98FB98,stroke:#333,stroke-width:1px
    classDef ext fill:#FFA500,stroke:#333,stroke-width:1px
    classDef code fill:#FFE4B5,stroke:#333,stroke-width:1px
```
