67次发布

0.4.12	2024年8月10日
0.4.11	2024年7月9日
0.4.10	~~2024年6月25日~~
0.4.5	2024年2月21日
0.1.3	2020年3月7日

#11 在图形API 中

24,828 每月下载量
用于 70 个包（直接使用68个）

MIT/Apache

1MB
12K SLoC

macroquad

macroquad 是一个简单易用的 Rust 编程语言的图形库，深受 raylib 启发。

特性

所有支持平台的代码相同，无需平台相关的定义。
高效的2D渲染，带有自动几何批处理。
依赖项最少：在x230（大约6年前的笔记本电脑）上，使用 cargo clean 构建，只需16秒。
包含即时模式UI库。
一次命令即可部署WASM和Android。

支持的平台

PC：Windows/Linux/macOS；
HTML5；
Android；
IOS。

构建说明

设置Macroquad项目

Macroquad 是一个普通的Rust依赖项，因此可以使用以下命令创建一个空的 Macroquad 项目：

# Create empty cargo project
cargo init --bin

将 macroquad 添加到 Cargo.toml 作为依赖项


[dependencies]
macroquad = "0.4"

在 src/main.rs 中添加一些 macroquad 代码

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

然后以原生方式运行它

cargo run

更多示例请参阅 Macroquad 示例文件夹

Linux

# 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

Windows

在 Windows 上，支持 MSVC 和 GNU 目标，无需额外的依赖项。

还支持从 Linux 向 Windows 的交叉编译

rustup target add x86_64-pc-windows-gnu

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

WASM

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

这将生成 target/debug/wasm32-unknown-unknown/CRATENAME.wasm 或在构建时使用 --release 生成 target/release/wasm32-unknown-unknown/CRATENAME.wasm 中的 .wasm 文件。

然后使用以下 .html 来加载它

index.html

<html lang="en">

<head>
    <meta charset="utf-8">
    <title>TITLE</title>
    <style>
        html,
        body,
        canvas {
            margin: 0px;
            padding: 0px;
            width: 100%;
            height: 100%;
            overflow: hidden;
            position: absolute;
            background: black;
            z-index: 0;
        }
    </style>
</head>

<body>
    <canvas id="glcanvas" tabindex='1'></canvas>
    <!-- Minified and statically hosted version of https://github.com/not-fl3/macroquad/blob/master/js/mq_js_bundle.js -->
    <script src="https://not-fl3.github.io/miniquad-samples/mq_js_bundle.js"></script>
    <script>load("CRATENAME.wasm");</script> <!-- Your compiled wasm file -->
</body>

</html>

提供静态 .wasm 和 .html 文件的一种方法

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

IOS

在模拟器上运行

mkdir MyGame.app
cargo build --target x86_64-apple-ios --release
cp target/release/mygame MyGame.app
# only if the game have any assets
cp -r assets MyGame.app
cat > MyGame.app/Info.plist << EOF
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleExecutable</key>
<string>mygame</string>
<key>CFBundleIdentifier</key>
<string>com.mygame</string>
<key>CFBundleName</key>
<string>mygame</string>
<key>CFBundleVersion</key>
<string>1</string>
<key>CFBundleShortVersionString</key>
<string>1.0</string>
</dict>
</plist>
EOF

xcrun simctl install booted MyGame.app/
xcrun simctl launch booted com.mygame

有关为真 iPhone 提供详细说明和指南，请查看 https://macroquad.rs/articles/ios/

技巧

将以下片段添加到您的 Cargo.toml 中，确保所有依赖项在发布模式下即使是在调试模式下也能编译。在 macroquad 中，这会使图像加载速度快几倍，并且应用程序性能更佳，同时将编译时间保持在奇迹般的低水平。

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

async/await

虽然 macroquad 尽量使用尽可能少的 Rust 特有概念，但在所有示例中的 .await 看起来有些可怕。Rust 的 async/await 用于解决一个问题——跨平台主循环组织。

详情

问题：在 WASM 和 Android 上很难以这种方式组织主循环

fn main() {
    // do some initialization

    // start main loop
    loop {
        // handle input

        // update logic

        // draw frame
    }
}

在 Android 上可以通过线程修复这个问题，但在网络上没有方法“暂停”和“恢复”WASM 执行，因此WASM代码永远不应该阻塞。而循环阻塞整个游戏执行！C++ 解决此问题的解决方案：[https://kripken.github.io/blog/wasm/2019/07/16/asyncify.html](https://kripken.github.io/blog/wasm/2019/07/16/asyncify.html)

但在 Rust 中我们有了 async/await。Rust 的 futures 基本上是延续——future 的堆栈可以存储到变量中以在稍后某个时间点暂停/恢复 future 代码的执行。

macroquad 中的 async/await 支持不需要任何外部依赖——没有运行时，没有执行器，也没有 futures-rs 参与。这只是保留 main 堆栈在 WASM 上，并保持代码跨平台而无需任何 WASM 特定的主循环。

社区

Quads Discord 服务器 - 与库的开发人员和社区成员聊天的地方。
Awesome Quads - 一个精心挑选的链接列表，包含 miniquad/macroquad 相关的代码和资源。

金牌赞助商

Macroquad 由以下公司支持

SourceGear

依赖项

~11MB
~252K SLoC