How not-fl3/macroquad works
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.