Macroquad

https://docs.rs/crate/macroquad/latest
Admin
Macroquad is a simple and easy-to-use graphics library for the Rust programming language, heavily...
Tokens:10,914
Snippets:23
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### Setup Macroquad Project and Run

Source: https://docs.rs/crate/macroquad/latest/source/README

These Bash commands illustrate the initial steps to set up a new Rust project for macroquad, add the dependency, and run the application natively.

```Bash
# Create empty cargo project
cargo init --bin

# Add macroquad as a dependency to Cargo.toml:
# [dependencies]
# macroquad = "0.4"

# Put some macroquad code in src/main.rs:
# 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
#     }
# }

# And to run it natively:
cargo run
```

--------------------------------

### Setting Up a Macroquad Project

Source: https://docs.rs/crate/macroquad/latest/index

Steps to initialize a new Rust project, add Macroquad as a dependency, and a basic example of drawing shapes and text in a Macroquad application.

```shell
cargo init --bin
```

```toml
[dependencies]
macroquad = "0.4"
```

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

```shell
cargo run
```

--------------------------------

### Macroquad Crate Configuration (Cargo.toml)

Source: https://docs.rs/crate/macroquad/latest/source/Cargo

This snippet details the dependencies and example configurations for the macroquad Rust crate. It lists external libraries like `glam`, `image`, and `miniquad`, and specifies available examples such as '3d', 'arkanoid', and 'audio'. It also outlines feature flags and build configurations.

```TOML
[dependencies.backtrace]
optional = true
version = "0.3.60"

[dependencies.fontdue]
version = "0.9"

[dependencies.glam]
features = ["scalar-math"]
version = "0.27"

[dependencies.image]
default-features = false
features = ["png", "tga"]
version = "0.24"

[dependencies.log]
optional = true
version = "0.4"

[dependencies.macroquad_macro]
version = "0.1.8"

[dependencies.miniquad]
features = ["log-impl"]
version = "=0.4.8"

[dependencies.quad-rand]
version = "0.2.3"

[dependencies.quad-snd]
optional = true
version = "0.2"

[dev-dependencies]

[[example]]
name = "3d"
path = "examples/3d.rs"

[[example]]
name = "arkanoid"
path = "examples/arkanoid.rs"

[[example]]
name = "asteroids"
path = "examples/asteroids.rs"

[[example]]
name = "audio"
path = "examples/audio.rs"

[[example]]
name = "basic_shapes"
path = "examples/basic_shapes.rs"

[[example]]
name = "camera"
path = "examples/camera.rs"

[[example]]
name = "camera_transformations"
path = "examples/camera_transformations.rs"

[[example]]
name = "custom_material"
path = "examples/custom_material.rs"

[[example]]
name = "events"
path = "examples/events.rs"

[[example]]
name = "exit_dialog"
path = "examples/exit_dialog.rs"

[[example]]
name = "first_person"
path = "examples/first_person.rs"

[[example]]
name = "input_keys"
path = "examples/input_keys.rs"

[[example]]
name = "input_touch"
path = "examples/input_touch.rs"

[[example]]
name = "letterbox"
path = "examples/letterbox.rs"

[[example]]
name = "life"
path = "examples/life.rs"

[[example]]
name = "logs"
path = "examples/logs.rs"

[[example]]
name = "particles_example"
path = "examples/particles_example.rs"

[[example]]
name = "particles_single_emitter"
path = "examples/particles_single_emitter.rs"

[[example]]
name = "platformer"
path = "examples/platformer.rs"

[[example]]
name = "post_processing"
path = "examples/post_processing.rs"

[[example]]
name = "raw_miniquad"
path = "examples/raw_miniquad.rs"

[[example]]
name = "rustaceanmark"
path = "examples/rustaceanmark.rs"

[[example]]
name = "screen_texture"
path = "examples/screen_texture.rs"

[[example]]
name = "shadertoy"
path = "examples/shadertoy.rs"

[[example]]
name = "snake"
path = "examples/snake.rs"

[[example]]
name = "text"
path = "examples/text.rs"

[[example]]
name = "text_measures"
path = "examples/text_measures.rs"

[[example]]
name = "texture"
path = "examples/texture.rs"

[[example]]
name = "tree"
path = "examples/tree.rs"

[[example]]
name = "ui"
path = "examples/ui.rs"

[[example]]
name = "ui_skins"
path = "examples/ui_skins.rs"

[[example]]
name = "window_conf"
path = "examples/window_conf.rs"

[features]
audio = ["quad-snd"]
default = []
glam-serde = ["glam/serde"]
log-rs = ["log"]

[lib]
name = "macroquad"
path = "src/lib.rs"

[package]
authors = ["not-fl3 <not.fl3@gmail.com>"]
autobenches = false
autobins = false
autoexamples = false
autolib = false
autotests = false
build = false
description = """
Simple and easy to use graphics library
"""
edition = "2021"
homepage = "https://github.com/not-fl3/macroquad"
license = "MIT OR Apache-2.0"
name = "macroquad"
readme = "README.md"
repository = "https://github.com/not-fl3/macroquad"
version = "0.4.14"

[package.metadata.android]
assets = "examples/"

[package.metadata.docs.rs]
all-features = true

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

[[test]]
name = "back_to_the_future"
path = "tests/back_to_the_future.rs"

[[test]]
name = "back_to_the_future_coroutines"
path = "tests/back_to_the_future_coroutines.rs"

[[test]]
name = "coroutine_pause"

```

--------------------------------

### Windows Cross-Compilation Setup

Source: https://docs.rs/crate/macroquad/latest/index

Configures Rust for cross-compiling to the Windows GNU target from Linux and demonstrates how to run the project.

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

--------------------------------

### Serve WASM Files Locally

Source: https://docs.rs/crate/macroquad/latest/source/README

Instructions to install and run a basic HTTP server for serving static files, commonly used to test WASM applications locally.

```sh
cargo install basic-http-server
basic-http-server .
```

--------------------------------

### Install Linux System Dependencies for Macroquad

Source: https://docs.rs/crate/macroquad/latest/source/README

This section provides Bash commands for installing necessary system dependencies on different Linux distributions (Ubuntu, Fedora, Arch Linux) required for building and running macroquad applications.

```Bash
# 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 libgl mesa-libgl alsa-lib
```

--------------------------------

### Linux System Dependencies

Source: https://docs.rs/crate/macroquad/latest/index

Installs necessary system packages for Macroquad development on Ubuntu, Fedora, and Arch Linux distributions.

```shell
# ubuntu system dependencies
apt install pkg-config libx11-dev libxi-dev libgl1-mesa-dev libasound2-dev
```

```shell
# fedora system dependencies
dnf install libX11-devel libXi-devel mesa-libGL-devel alsa-lib-devel
```

```shell
# arch linux system dependencies
 pacman -S pkg-config libx11 libxi libgl mesa-libgl alsa-lib
```

--------------------------------

### iOS Simulator Deployment

Source: https://docs.rs/crate/macroquad/latest/source/README

Steps to build, package, and deploy a macroquad application to the iOS simulator. This includes creating an app bundle, copying the executable and assets, generating an Info.plist, and using `xcrun` commands for installation and launching.

```sh
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
```

--------------------------------

### Rust Macroquad Basic Shapes Example

Source: https://docs.rs/crate/macroquad/latest/source/README

This Rust code snippet demonstrates how to use the macroquad library to draw basic shapes like lines, rectangles, and circles on the screen. It includes clearing the background, drawing elements, and handling frame updates within an asynchronous main loop.

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

--------------------------------

### WASM HTML Structure

Source: https://docs.rs/crate/macroquad/latest/source/README

A basic HTML file structure required to load and run a compiled WebAssembly module using macroquad. It includes canvas setup and script tags for the macroquad JS bundle and the WASM file.

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

--------------------------------

### IOS Simulator Build and Deployment

Source: https://docs.rs/crate/macroquad/latest/index

Instructions for building a Macroquad project for the iOS simulator, packaging it, and deploying it using `xcrun` commands. Includes a basic Info.plist structure.

```shell
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
```

--------------------------------

### WASM Build and Deployment

Source: https://docs.rs/crate/macroquad/latest/index

Builds a Rust project for the WebAssembly target and provides an HTML template to load and run the compiled WASM file, along with a command to serve static files.

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

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

```shell
cargo install basic-http-server
basic-http-server .
```

--------------------------------

### Rust Build Profile Configuration

Source: https://docs.rs/crate/macroquad/latest/index

Configures the Rust build profile for development packages to use optimization level 3, ensuring faster execution even in debug builds.

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

--------------------------------

### Cargo.toml Configuration for Macroquad

Source: https://docs.rs/crate/macroquad/latest/source/Cargo.toml

This file defines the project's metadata, version, authors, license, and dependencies for the macroquad Rust crate. It also specifies feature flags that enable optional functionalities like audio or logging.

```toml
[package]
name = "macroquad"
version = "0.4.14"
authors = ["not-fl3 <not.fl3@gmail.com>"]
edition = "2021"
homepage = "https://github.com/not-fl3/macroquad"
repository = "https://github.com/not-fl3/macroquad"
description = """
Simple and easy to use graphics library
"""
readme="README.md"
license = "MIT OR Apache-2.0"

[features]
audio = ["quad-snd"]
log-rs = ["log"]
glam-serde = ["glam/serde"]
default = []

[package.metadata.android]
assets = "examples/"

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

[package.metadata.docs.rs]
all-features = true

[dependencies]
miniquad = { version = "=0.4.8", features = ["log-impl"] }
quad-rand = "0.2.3"
glam = { version = "0.27", features = ["scalar-math"] }
image = { version = "0.24", default-features = false, features = ["png", "tga"] }
macroquad_macro = { version = "0.1.8", path = "macroquad_macro" }
fontdue = "0.9"
backtrace = { version = "0.3.60", optional = true }
log = { version = "0.4", optional = true }
quad-snd = { version = "0.2", optional = true }

[dev-dependencies]
macroquad-particles = { path = "./particles" }
macroquad-tiled = { path = "./tiled" }
macroquad-profiler = { path = "./profiler" }
macroquad-platformer = { path = "./physics-platformer" }

# workaround to fix the examples
# this allows to use macroquad-particles in examples without two versions of macroquad
[patch.crates-io]
macroquad = { path = './' }

#quad-snd = {path = '../quad-snd'}
#miniquad = { path = '../miniquad' }
#miniquad = { git = "https://github.com/not-fl3/miniquad", branch = "msaa_render_texture" }
#quad-gl = {path = './quad-gl'}

```

--------------------------------

### Cross-Compile to Windows

Source: https://docs.rs/crate/macroquad/latest/source/README

Instructions for cross-compiling Rust projects to Windows targets using the GNU toolchain. No additional dependencies are required on Windows itself.

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

--------------------------------

### Macroquad Sandbox Limits

Source: https://docs.rs/crate/macroquad/latest/builds

Details the resource limitations imposed on builds executed within the docs.rs sandbox environment for the macroquad crate. These limits include RAM, execution time, log size, network access, and build targets.

```APIDOC
Macroquad Sandbox Limits:
  - Available RAM: 6.44 GB
  - Maximum rustdoc execution time: 15 minutes
  - Maximum size of a build log: 102.4 kB
  - Network access: blocked
  - Maximum number of build targets: 10

If a build fails due to hitting these limits, users are advised to open an issue on the docs.rs GitHub repository.
```

--------------------------------

### Cross-Compile to WASM

Source: https://docs.rs/crate/macroquad/latest/source/README

Steps to add the WASM target and compile a Rust project for WebAssembly. The output .wasm file is located in the target directory.

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

--------------------------------

### Macroquad Feature Flags

Source: https://docs.rs/crate/macroquad/latest/features

Lists and describes the available feature flags for the macroquad crate. Each feature flag may enable additional functionalities or depend on other crates.

```APIDOC
Macroquad Features:

- default: This feature flag does not enable additional features.

- audio: Enables audio support, likely integrating with the 'quad-snd' crate.
  - Dependency: quad-snd

- backtrace: Enables backtrace functionality for error reporting.
  - Dependency: backtrace

- glam-serde: Integrates 'glam' with 'serde' for serialization/deserialization.
  - Dependency: glam, serde

- log: Integrates with the 'log' crate for logging.
  - Dependency: log

- log-rs: Integrates with the 'log' crate for logging (alternative naming).
  - Dependency: log

- quad-snd: Integrates with the 'quad-snd' crate for audio functionalities.
  - Dependency: quad-snd
```

--------------------------------

### Gitignore Patterns

Source: https://docs.rs/crate/macroquad/latest/source/.gitignore

Common patterns used to ignore files and directories in a Git repository, such as build artifacts and temporary files.

```gitignore
/target
**/*.rs.bk
Cargo.lock
```

--------------------------------

### Cargo.toml Debug Profile Optimization

Source: https://docs.rs/crate/macroquad/latest/source/README

A Cargo configuration snippet to ensure all dependencies compile in release mode even during debug builds. This can significantly improve performance for macroquad applications.

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

--------------------------------

### MIT License for macroquad

Source: https://docs.rs/crate/macroquad/latest/source/LICENSE-MIT

This snippet contains the full MIT License text, detailing the terms under which the macroquad software can be used, copied, modified, distributed, and sold.

```text
MIT License

@ 2019-2021 Fedor Logachev <not.fl3@gmail.com>

Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.

```

--------------------------------

### macroquad 0.4.14 - Rust Graphics Library

Source: https://docs.rs/crate/macroquad/latest/source/LICENSE-MIT

This snippet provides the core information about the macroquad library, its version, and its purpose as a simple and easy-to-use graphics library for Rust.

```rust
Project: /context7/rs-crate-macroquad

# macroquad 0.4.14

Simple and easy to use graphics library
```

--------------------------------

### Add Macroquad Dependency to Cargo.toml

Source: https://docs.rs/crate/macroquad/latest/source/README

This TOML snippet shows how to add the macroquad library as a dependency in your Rust project's Cargo.toml file, specifying the version.

```TOML
[dependencies]
macroquad = "0.4"
```
Tokens:
Raw