Forem: Rodney Lab

Godot Rust CI: Handy GDScript & Rust GitHub Actions

Rodney Lab — Thu, 15 Aug 2024 07:19:50 +0000

🎬 Godot Rust GitHub Actions

In this Godot Rust CI post, we take a quick look at some GitHub action you might want to add to your project for linting GDScript and Rust code on each commit.

The config, below, is based on the Knights to See You game. I ran through that project and some resources for getting going with Godot Rust bindings in a recent post. You might want to start there if you are new to Rust in Godot.

GitHub actions let you run continuous integration processes on each commit, usually by adding a YAML config file in a .github/workflows directory for your project. They can take a little trial-and-error to get right, but are worth the effort for keeping code consistent, running unit tests, finding outdated packages and even spotting potential security vulnerabilities.

There is a link further down to the full project code.

🤖 GDScript Linting and Formatting

The project uses a mix of Rust and GDScript, and for linting the GDScript code in GitHub actions, I use godot-gdscript-toolkit.

name: Rust
on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main
permissions: read-all
# TRUNCATED...
  static-checks:
    name: 'GDScript Static checks'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - uses: Scony/godot-gdscript-toolkit@9c4fa1cd596149d71e9d867416f3bb7b3a2fed3e # 4.2.2
      - run: gdformat --check godot/
      - run: gdlint godot/

Setting default read-only permissions in a line 10 is a good idea, to limit access actions have to your repo. You can override this for any actions which require repo write access.

I use commit hashes to identify the exact action I want to run, though you can just use tag, instead.

The project is structured with godot and rust folders at the root level, and I set gdformat and gdlint only to run on the godot directory. gdformat provides opinionated GDScript formatting, while gdlint includes checks for unnecessary else statements, unused arguments and that your naming is consistent with the GDScript style guide (snake case function names, Pascal Case classes etc) among other checks.

🦀 Rust Linting and Formatting

Rust is well-known for having integrated formatting, linting, testing through cargo utilities, and you can set these up to run in GitHub actions by dtolnay:

name: Rust
on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main
permissions: read-all
env:
  CARGO_TERM_COLOR: always
  RUSTFLAGS: "-Dwarnings -Cinstrument-coverage"
  LLVM_PROFILE_FILE: "project-%p-%m.profraw"
jobs:
  test:
    name: Test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - uses: dtolnay/rust-toolchain@4f366e621dc8fa63f557ca04b8f4361824a35a45 # stable
      - name: Run tests
        run: cargo test
  fmt:
    name: Rustfmt
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - uses: dtolnay/rust-toolchain@4f366e621dc8fa63f557ca04b8f4361824a35a45 # stable
        with:
          components: rustfmt
      - name: Enforce formatting
        run: cargo fmt --check
  clippy:
    name: Clippy
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - uses: dtolnay/rust-toolchain@4f366e621dc8fa63f557ca04b8f4361824a35a45 # stable
        with:
          components: clippy
      - name: Linting
        run: cargo clippy -- -D warnings

You are probably already familiar with these tools, but let me know if the GitHub action side of things needs more explanation.

🧐 Other Handy Rust Actions

Jon Gjengset has a fantastic video, in which he takes you through setting up CI on a Rust GitHub repo. You can clone his setup into any new Rust projects. Essentially, that is the process I followed for Knights to See You. Besides the Rust actions above, I have:

msrv check - a check that the project successfully builds using the Minimum Supported Rust version I give in Cargo.toml. This is worth checking in CI, since locally you will, likely, be running a newer Rust version.
cargo deny check - this checks the licences of any crates you use in your project and dependencies of those crates. You create your own allow list of licences, and the tool highlights any projects without matching licences. This helps avoid surprises further down the line.
audit-check - finds crates with security vulnerabilities.

Rust MSRV Check Action

name: Rust
on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened]
    branches:
      - main
permissions: read-all
# TRUNCATED...
  msrv:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        msrv: ["1.78.0"]
    name: ubuntu / ${{ matrix.msrv }}
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - name: Install Linux Dependencies
        run: sudo apt-get update
      - name: Install ${{ matrix.msrv }}
        uses: dtolnay/rust-toolchain@4f366e621dc8fa63f557ca04b8f4361824a35a45 # stable
        with:
          toolchain: ${{ matrix.msrv }}
      - name: cargo +${{ matrix.msrv }} check
        run: cargo check

Cargo Deny Licence Check Action

name: Cargo Deny
on: [push, pull_request]
permissions:
  contents: read
jobs:
  cargo-deny:
    runs-on: ubuntu-22.04
    strategy:
      matrix:
        checks:
          - advisories
          - bans licenses sources
    # Prevent sudden announcement of a new advisory from failing ci:
    continue-on-error: ${{ matrix.checks == 'advisories' }}
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - uses: EmbarkStudios/cargo-deny-action@3f4a782664881cf5725d0ffd23969fcce89fd868 # v1.6.3
        with:
          command: check ${{ matrix.checks }}

See cargo-deny-action repo for configuration details.

Rust Security Audit Action

name: Security audit
permissions:
  contents: read
on:
  push:
    paths:
      - 'Cargo.toml'
      - 'Cargo.lock'
jobs:
  security_audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7
      - uses: rustsec/audit-check@dd51754d4e59da7395a4cd9b593f0ff2d61a9b95 # v1.4.1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

See audit-check repo for configuration details.

There are more checks you might want to include, depending on your project, and I have only highlighted a few here. See Jon Gjengset’s rust-ci-config repo for more.

🙌🏽 Godot Rust CI: Wrapping Up

In this Godot Rust CI, we took a quick look through some GitHub actions you might want to add to your Godot Rust game. In particular, we looked at:

actions for linting and formatting GDScript;
running familiar cargo tooling in GitHub actions; and
also how to run security audit and licence checks on your Rust crates in CI.

I hope you found this useful. As promised, you can get the full project code on the Rodney Lab GitHub repo. I would love to hear from you, if you are also new to Godot video game development. Were there other resources you found useful? Also, let me know what kind of game you are working on!

🙏🏽 Godot Rust CI: Feedback

If you have found this post useful, see links below for further related content on this site. Let me know if there are any ways I can improve on it. I hope you will use the code or starter in your own projects. Be sure to share your work on X, giving me a mention, so I can see what you did. Finally, be sure to let me know ideas for other short videos you would like to see. Read on to find ways to get in touch, further below. If you have found this post useful, even though you can only afford even a tiny contribution, please consider supporting me through Buy me a Coffee.

Finally, feel free to share the post on your social media accounts for all your followers who will find it useful. As well as leaving a comment below, you can get in touch via @askRodney on X (previously Twitter) and also, join the #rodney Element Matrix room. Also, see further ways to get in touch with Rodney Lab. I post regularly on Game Dev as well as Rust and C++ (among other topics). Also, subscribe to the newsletter to keep up-to-date with our latest projects.

Godot Rust gdext: GDExtension Rust Game Dev Bindings

Rodney Lab — Wed, 07 Aug 2024 17:05:20 +0000

🕹️ Godot Rust

Following on from the recent, trying Godot 4 post, here, we look at Godot Rust gdext. In that previous post, I mentioned how Godot not only lets you code in officially supported GDScript, but also lets you create dynamic libraries for your Godot games written in Rust, Swift, and Zig among other languages.

In this post, I run through some resources for getting started with Godot Rust gdext and also highlight some tips that I benefited from.

🧑🏽‍🎓 gdext Learning Resources

gdext provides GDExtension bindings for Godot 4. If you are working with Godot 4, skip over gdnative resources, which relate to the older Godot 3 API.

The best starting point is probably the godot-rust book, which starts by setting up with gdext and runs through a basic code example. The book then move on to more advanced topics, these are really helpful, and you will probably want to keep the book open even if you jump to working on your own game after working through the initial chapters.

The official, online Rust godot docs document APIs. If you have to work offline, cargo lets you open these from a local source in a browser:

cargo doc --open --package godot

Since the gdext APIs mirror GDScript APIs, you will often want to check the GDScript API docs for additional background.

Another fantastic resource is the example game code in the gdext GitHub repo for a Dodge the Creeps game (which will sound familiar if you have followed the official Godot, GDScript-based, tutorial). You can try building it or just dip into for help to unblock if you get stuck working on your own game.

🧱 What I Built

After working though the gdext Hello World, I thought a good way to learn more APIs would be to start converting a game I already had from GDScript to Godot Rust gdext. For this, I picked the Knights to See You game I made by following the How to make a Video Game - Godot Beginner Tutorial.

I followed the guidelines in the godot-rust book, but made a small change, in the project file structure. This made it slightly more convenient to work in the Terminal from the project root folder, and also simplified the project CI configuration.

📂 Folder Structure

The change I made from the godot-rust book, which I alluded to before was to set the project up using Cargo Workspaces. The rust folder is exactly as the book recommends, and contains a Cargo.toml file.

├── Cargo.toml
├── godot
│   ├── assets
│   │   ├── fonts
│   │   ├── music
│   │   ├── sounds
│   │   └── sprites
│   ├── export_presets.cfg
│   ├── knights-to-see-you.gdextension
│   ├── project.godot
│   ├── scenes
│   └── scripts
└── rust
    ├── Cargo.toml
    └── src
        ├── lib.rs
        └── player.rs

I, just, added another Cargo.toml file to the root directory, where I created a new workspace, adding that rust directory:

[workspace]
members = ["rust"]
resolver = "2"

This changes the Rust output target directory, moving it up a level, so I had to update the paths listed in my godot/<PROJECT>.gdextension file:

[configuration]
entry_symbol = "gdext_rust_init"
compatibility_minimum = 4.2
reloadable = true

[libraries]
linux.debug.x86_64 = "res://../target/debug/librust.so"
linux.release.x86_64 = "res://../target/release/librust.so"
windows.debug.x86_64 = "res://../target/debug/librust.dll"
windows.release.x86_64 = "res://../target/release/librust.dll"
macos.debug = "res://../target/debug/librust.dylib"
macos.release = "res://../target/release/librust.dylib"
macos.debeg.arm64 = "res://../target/debug/librust.dylib"
macos.release.arm64 = "res://../target/release/librust.dylib"

👀 Rust Hot Reloading and Watching Files

GDExtension for Godot 4.2 supports hot reloading out of the box. To speed up your coding feedback cycle, use cargo watch to recompile your Rust code automatically when you save a Rust source file. Install cargo watch (if you need to):

cargo install cargo-watch --locked

Then, you can run:

cargo watch -cx check -x clippy -x build

which will clear the window, run cargo check, cargo clippy then, cargo build each time you save the Rust source. Now you can hit save then jump straight to Godot Engine to test play the game.

🦀 gdext API Snippets

I started the switch from GDScript to Godot Rust gdext with the Player scene. In the original game, the Player Scene was a CharacterBody2D.

Rust does not easily handle Object-oriented Programming inheritance, and gdext opts for a composition approach. Following the book, you will see the recommended pattern, here, is to create a Player struct in Rust with a base field of type Base<ICharacterBody2D>. That base field then provides access to the character properties that you are familiar with from GDScript.

Here are some API snippets (with equivalent GDScript) to give you a feel for gdext.

Updating Character Velocity

Using GDScript:

velocity.x = 100.0
velocity.y = 0.0

Using gdext:

  self.base_mut().set_velocity(Vector2::new(100.0, 0.0));

base_mut(), here, returns a mutable reference to the base field on Player, mentioned above. You set and get CharacterBody2D properties using self.base() and self.base_mut().

Gravity and Project Settings

To get project default gravity value with GDScript, you can use:

var gravity = ProjectSettings.get_setting("physics/2d/default_gravity")

The equivalent in gdext is:

let gravity = ProjectSettings::singleton()
    .get_setting("physics/2d/default_gravity".into())
    .try_to::<f64>()
    .unwrap();

Setting Animations

The Player scene has an AnimatedSprite2D node. Typically, you can reference that node in GDScript with something like this:

@onready var animated_sprite = $AnimatedSprite2D


# TRUNCATED...


animated_sprite.play("idle")

In gdext, you can set the sprite like so:

let mut animated_sprite = self
    .base()
    .get_node_as::<AnimatedSprite2D>("AnimatedSprite2D");

// Play animation
animated_sprite.play_ex().name("idle".into()).done();

Full Comparison

For reference, here is the full code for the Rust Player class (rust/src/player.rs):

use godot::{
    builtin::Vector2,
    classes::{AnimatedSprite2D, CharacterBody2D, ICharacterBody2D, Input, ProjectSettings},
    global::{godot_print, move_toward},
    obj::{Base, WithBaseField},
    prelude::{godot_api, GodotClass},
};

#[derive(GodotClass)]
#[class(base=CharacterBody2D)]
struct Player {
    speed: f64,
    jump_velocity: f64,

    base: Base<CharacterBody2D>,
}

enum MovementDirection {
    Left,
    Neutral,
    Right,
}

#[godot_api]
impl ICharacterBody2D for Player {
    fn init(base: Base<CharacterBody2D>) -> Self {
        godot_print!("Initialise player Rust class");
        Self {
            speed: 130.0,
            jump_velocity: -300.0,

            base,
        }
    }

    fn physics_process(&mut self, delta: f64) {
        let Vector2 {
            x: velocity_x,
            y: velocity_y,
        } = self.base().get_velocity();

        let input = Input::singleton();

        // handle jump and gravity
        let new_velocity_y = if self.base().is_on_floor() {
            if input.is_action_pressed("jump".into()) {
                #[allow(clippy::cast_possible_truncation)]
                {
                    self.jump_velocity as f32
                }
            } else {
                velocity_y
            }
        } else {
            let gravity = ProjectSettings::singleton()
                .get_setting("physics/2d/default_gravity".into())
                .try_to::<f64>()
                .expect("Should be able to represent default gravity as a 32-bit float");
            #[allow(clippy::cast_possible_truncation)]
            {
                velocity_y + (gravity * delta) as f32
            }
        };

        // Get input direction
        let direction = input.get_axis("move_left".into(), "move_right".into());
        let movement_direction = match direction {
            val if val < -f32::EPSILON => MovementDirection::Left,
            val if (-f32::EPSILON..f32::EPSILON).contains(&val) => MovementDirection::Neutral,
            val if val >= f32::EPSILON => MovementDirection::Right,
            _ => unreachable!(),
        };

        let mut animated_sprite = self
            .base()
            .get_node_as::<AnimatedSprite2D>("AnimatedSprite2D");

        // Flip the sprite to match movement direction
        match movement_direction {
            MovementDirection::Left => animated_sprite.set_flip_h(true),
            MovementDirection::Neutral => {}
            MovementDirection::Right => animated_sprite.set_flip_h(false),
        }

        // Play animation
        let animation = if self.base().is_on_floor() {
            match movement_direction {
                MovementDirection::Neutral => "idle",
                MovementDirection::Left | MovementDirection::Right => "run",
            }
        } else {
            "jump"
        };
        animated_sprite.play_ex().name(animation.into()).done();

        // Apply movement
        #[allow(clippy::cast_possible_truncation)]
        let new_velocity_x = match movement_direction {
            MovementDirection::Neutral => {
                move_toward(f64::from(velocity_x), 0.0, self.speed) as f32
            }
            MovementDirection::Left | MovementDirection::Right => direction * (self.speed) as f32,
        };

        self.base_mut().set_velocity(Vector2 {
            x: new_velocity_x,
            y: new_velocity_y,
        });

        self.base_mut().move_and_slide();
    }
}

See the link further down for the full project code.

Again, for reference, here is the previous GDScript code for the Player:

extends CharacterBody2D

const SPEED := 130.0
const JUMP_VELOCITY := -300.0

# Get the gravity from the project settings to be synced with RigidBody nodes.
var gravity = ProjectSettings.get_setting("physics/2d/default_gravity")

@onready var animated_sprite = $AnimatedSprite2D


func _physics_process(delta):
    # Add the gravity.
    if not is_on_floor():
        velocity.y += gravity * delta

    # Handle jump.
    if Input.is_action_just_pressed("jump") and is_on_floor():
        velocity.y = JUMP_VELOCITY

    # Get the input direction: -1, 0 or 1
    var direction := Input.get_axis("move_left", "move_right")

    # Flip the sprite
    if direction > 0:
        animated_sprite.flip_h = false
    elif direction < 0:
        animated_sprite.flip_h = true

    # Play animation
    if is_on_floor():
        if direction == 0:
            animated_sprite.play("idle")
        else:
            animated_sprite.play("run")
    else:
        animated_sprite.play("jump")

    # Apply movement
    if direction:
        velocity.x = direction * SPEED
    else:
        velocity.x = move_toward(velocity.x, 0, SPEED)

    move_and_slide()

🤖 Adding Rust Library in Godot Engine

Once you have coded and compiled the player (or other GDExtension class) to use it in your game, you just need to change the type of its Godot Scene.

Do this by right-clicking on the scene in Godot Engine (Player scene in this case) and selecting Change Type….

Then, you need to search for the name you gave your class in the Rust code. My Rust struct was also called Player, and I can see it in the view as a child of CharacterBody2D. I select this and I am done!

Godot Engine now links to the dynamic shared library I created in Rust.

🙌🏽 Godot Rust gdext: Wrapping Up

In this post on Godot Rust gdext, we took a look through some resources for getting started with GDExtension for Godot 4. In particular, we looked at:

resources for getting started with GDExtension and Godot Rust;
a tip for speeding up the coding feedback cycles; and
how to use your GDExtension dynamic library in Godot Engine.

🙏🏽 Godot Rust gdext: Feedback

Trying Godot 4: Free & Open-source Video GameDev

Rodney Lab — Wed, 17 Jul 2024 16:47:42 +0000

🤖 Trying Godot 4

I have been hearing a lot of good things about Godot for game development, and thought it would be a good time to try it out and write a post on trying Godot 4. Godot is a full-featured game engine like Unity or Unreal. The biggest difference it that it is free and open-source software (FOSS). You need to look no further than the 3D modelling and editing Blender toolset to see how community driven development creates software on a par with proprietary alternatives.

FOSS advancements can track user needs. Studios adopting Godot, instead of building and maintaining their own in-house engine, leverage on community contributions. Further, they provide Godot improvements, useful for their own games, and then share those improvements back to the community.

There are already successful Godot games available on Steam, such as Brotato, Ex-Zodiac (in early access at time of writing), and Halls of Torment.

In the rest of this post, we take a closer look at why you might choose Godot and also see some video and website resources for starting out with Godot.

🤔 Why Godot?

In short:

Godot has batteries included; it is a full-featured and intuitive game engine helping you churn out your game quicker,
it is FOSS, so you do not have to pay to use Godot or pay royalties on games you create with it; and
it is popular - it keeps improving with community contributions, and you can find quality learning resources.

My first impression was that Godot is lightweight. I loved that you could download, install and start coding far quicker than other engines which have gigantic downloads. Despite that, Godot is still powerful. Not only is Godot powerful, but the user interface, is snappy and intuitive.

Finally, here, I would say the flexibility in code language for the game logic is another strength. The easiest way to code, is to use GDScript, which looks like Python. However, if you need performance, you can use GDExtension which lets you code in C, C++ or, thanks to a donation from Microsoft, C#. Language support does not end there though; community projects also add support for Rust, Swift, Zig and Go as well as other languages.

🏅 Official Godot Getting Started Guide

The official tutorial is well-written and provides a direct route for getting you up-to-speed on the Godot engine. If you want to get a feel for Godot before diving in though, first try the Brackeys How to make a Video Game video tutorial (mentioned further down). You can then loop back and learn more fundamentals once you have a better idea of whether it is something that will suit you.

The official guide starts with an Introduction, giving you an overview of Godot’s capabilities.
You then jump onto some Godot concepts, before moving onto the Instancing Tutorial, which provides a first look at Godot Code.
The guide wraps up with creating a 2D and then, 3D Godot game, before you are let loose to build that game idea you have had running through your mind for months!

🏞️ Godot Design: Scenes, Nodes and Signals

Godot promotes an Object-oriented Programming (OOP) approach to games architecture, which contrasts to the Entity Component System (ECS) used by Bevy, for example.

Godot Scenes are game elements, such as collectable coins, a moving platform or even a player.

Scenes might be composed of multiple Godot built-in Nodes. Nodes are OOP objects providing some logic or behaviour. For example, the collectable coin scenes have:

a 2D collider node (used to detect that the player character has walked into the coin),
an AudioStreamPlayer node to play a sound effect when the coin is picked up; and
one each of an AnimationSprite and AnimationPlayer node.

Scenes are combined into a Scene Trees: the game scene includes collectable coin and player scenes in its scene tree.

Signals: Communicating between Remote Scenes

Signals provide a convenient interface communicating between scenes at different levels of the game. There are built-in signals, triggered when a button is pressed, but you can also create your own. For example, you could create a lava scene with an on_body_entered signal, emitted when the player falls into the lava. Now, the score readout, life count and other independent components just need to listen for that signal to update themselves. No need to poll on every game tick to check if they need to update.

🧩 Composition is Still Possible

ECS designs favour composition over inheritance, making certain common relationships easier to code. Godot allows for composition, adding custom components to a class. This is a little beyond the scope of this post, though the How You Can Easily Make Your Code Simpler in Godot 4 video provides an excellent explanation with great examples.

🖥️ Coding your Godot Game

I mentioned above, that GDScript is a good choice if you want to get going quickly and other languages, available via GDExtension can provide more performant alternatives where that is most important.

Trying Godot 4: GDScript

GDScript looks a lot like Python. In fact, earlier versions of Godot supported coding in Python, though Python was replaced by GDScript to address Python for game development shortcomings. GDScript is quite intuitive and supports static types. Here is an example, in case you are curious to see some code:



extends Node2D

const SPEED := 60

var direction: int = 1

@onready var ray_cast_right = $RayCastRight
@onready var ray_cast_left = $RayCastLeft


# Called every frame. 'delta' is the elapsed time since the previous frame.
func _process(delta):
    if ray_cast_right.is_colliding():
        direction = -1
    if ray_cast_left.is_colliding():
        direction = 1
    position.x += direction * SPEED * delta

This code moves a monster back and forth between two walls. Here:

_process is the in-built function run on every frame for our scene. Engine function names begin with an underscore.
const SPEED := 60 creates the constant property, inferring its type to be integer from the value provided. The typing is optional, and the statement could be written const SPEED = 60 for dynamic typing.
var direction: int = 1 uses an explicit static type. Godot would throw up an error if we later tried to assign a string, for example, to direction.

Learning GDScript

The Brackeys have a broad-strokes overview of GDScript, in a one-hour video. This is a different video to the Godot introduction from the same creator, mentioned further down. Some, older, content on YouTube covers GDScript for Godot 3. Godot 4 was released over a year ago now, and is stable, so you will probably want to focus on Godot 4 for any new games you create.

Trying Godot 4: GDExtension for Rust, Swift, C++, C#, Zig and more…

When you need performance, GDExtension will probably be your best bet. GDExtension lets you compile a shared library using third-party C bindings. Shared libraries are compiled independently of the game, but still can be called from your game code. Because GDExtension creates shared libraries, you can use the same library in different games, or distribute it, without having to compile with the engine’s source code.

You target a particular Godot engine version when you write GDExtension. If you target 4.2 (latest version at time of writing), you get to use the latest Godot features and your code will be compatible with future Godot Engine versions. That said, your Godot 4.2 targeted GDExtension library might not work with Godot Engine 4.1 and earlier versions.

Watch the 6 Programming Languages in 1 Godot Game! Trying out GDExtension! video to get a better fell for how this works.

GDExtension Tutorials

For tutorials see:

Godot’s official Godot C++ GDExtension tutorial;
the godot-rust book, which takes you through setting up your first Rust GDExtension game; or
the SwiftGodot tutorial.

📼 Free Video Tutorials

Here are some free tutorials you can access on YouTube to get going with Godot. The first two, shorter ones assume a little previous programming knowledge.

The Brackeys (known for Unity content) have recently started putting out Godot 4 content. Create a 2D platform game in the How to make a Video Game - Godot Beginner Tutorial. Around 80 minutes.
Create a rogue-like shoot-em-up in the same vein as Brotato and Halls of Torrent in the Your First 2D GAME From Zero with GODOT 4! video from GDQuest. Just over two hours.
Build a 3D Godot 4 Platformer in the 3D for coding beginners series. Creator has a background in eduction and targets all levels including coding novices. 11 videos, 5 hours in total.

If plan to work offline, remember to check the video descriptions for game asset downloads needed to complete the tutorials.

🏁 Where Next?

If you are looking for a roadmap for getting going on Godot my two cents it to try these steps in this order:

the Brackeys How to make a Video Game - Godot Beginner Tutorial video, for an overview of Godot building your own game in under two hours without having to get too concerned with the details;
the official Godot tutorial to learn some fundamentals in more detail; and
the Brackeys GDScript tutorial.

From there, you can explore a path taking in Godot aspects best suited for the game you want to work on, including the other resources listed above.

🙌🏽 Trying Godot 4: Wrapping Up

In this trying Godot 4 post, we took a look through some resources for getting started with Godot. In particular, I talked about:

why you might choose Godot;
Godot options for coding language, including GDScript, C++, C#, Rust and Swift; and
some Godot 4 tutorials.

I hope you found this useful. I would love to hear from you, if you are also new to Godot video game development. Were there other resources you found useful? Also, let me know what kind of game you are working on!

🙏🏽 Trying Godot 4: Feedback

Ratatui Audio with Rodio: Sound FX for Rust Text-based UI

Rodney Lab — Wed, 26 Jun 2024 17:47:13 +0000

🔊 Adding Sound FX to a Ratatui Game

In this post, we look at Ratatui audio with Rodio. I have been building a text-based User Interface (TUI) game in Ratatui. Ratatui is Rust tooling for Terminal apps. This is the third post in the series. I wrote the initial post once I had put together a minimal viable product, and outlined some next steps in that post. In the last post, I added fireworks to the victory screen by painting in a Ratatui canvas widget.

As well as fireworks, another enhancement that I identified (in the first post) was sound effects. I have built Rust games with sound before, but relied on the game’s tooling to add manage loading the audio assets and playing them (Macroquad and Bevy, for example, make this seamless). So, the first step was going to be finding a crate to play MP3 audio. I discovered Rodio, which worked well, and was quick to get going with.

In the rest of this post, I talk about the Rodio integration, and some next steps for the game. There is a link to the latest project repo, with full code further down.

🧱 Ratatui Audio with Rodio: What I Built

I didn’t really want background music, just sound effects to play when the player starts the challenge, and then to provide audio feedback if their latest solution attempt was good or perfect. Finally, I wanted to play some audio when each firework on the victory screen ignited. I found some quite small wave files for each of these, and converted them to MP3s.

About Rodio

Rodio uses a number of lower level crates under the hood, simplifying adding audio via their single higher level API. These, lower-level, crates include:

cpal for playback;
symphonia for MP4 and AAC playback;
hound for WAV playback;
lewton for Vorbis playback; and
claxon for FLAC playback.

I just needed MP3s, so disabled default features, and only added symphonia-mp3 back in the project Cargo.toml, to keep the binary size in check:



[package]
name = "countdown-numbers"
version = "0.1.0"
edition = "2021"
license = "BSD-3-Clause"
repository = "https://github.com/rodneylab/countdown-numbers"
# ratatui v0.26.3 requires 1.74.0 or newer
rust-version = "1.74"
description = "Trying Ratatui TUI 🧑🏽‍🍳 building a text-based UI number game in the Terminal 🖥️ in Rust with Ratatui immediate mode rendering."

[dependencies]
num_parser = "1.0.2"
rand = "0.8.5"
ratatui = "0.27.0"
rodio = { version = "0.18.1", default-features = false, features = ["symphonia-mp3"] }

🐎 Adding Rodio

The Rodio docs give a couple of examples for getting going. Those examples read and decode an ogg file from a local folder within the project. This makes uses of the Rodio decoder struct, either appending it to a Rodio sink, or playing decoder output directly on an output stream. Either way, the audio is decoded and played straight away.

That setup works well for longer files, played once. For the game, I have a few sound effects that might be played dozens of times. It seemed a little extravagant to read from a file and decode each time I needed to play the same sound effect. Luckily, I found a Stack Overflow post with an alternative approach, letting you buffer the decoder output. Since the audio files were no bigger that 10 KB, I was happy to buffer them as the app starts up and keep them in memory.

Rust Code

I created a SoundEffects struct for holding all the sound effects, as there are only five of them. For an app with more, I would attempt a cleaner solution, but this approach keeps things simple for what I have.



use std::{fs::File, path::Path};

use rodio::{
    source::{Buffered, Source},
    Decoder,
};

pub struct SoundEffects {
    pub start: Buffered<Decoder<File>>,
    pub end: Buffered<Decoder<File>>,
    pub perfect: Buffered<Decoder<File>>,
    pub valid: Buffered<Decoder<File>>,
    pub firework: Buffered<Decoder<File>>,
}

fn buffer_sound_effect<P: AsRef<Path>>(path: P) -> Buffered<Decoder<File>> {
    let sound_file = File::open(&path)
        .unwrap_or_else(|_| panic!("Should be able to load `{}`", path.as_ref().display()));
    let source = Decoder::new(sound_file).unwrap_or_else(|_| {
        panic!(
            "Should be able to decode audio file `{}`",
            path.as_ref().display()
        )
    });

    source.buffered()
}

impl Default for SoundEffects {
    fn default() -> Self {
        SoundEffects {
            start: buffer_sound_effect("./assets/start.mp3"),
            end: buffer_sound_effect("./assets/end.mp3"),
            perfect: buffer_sound_effect("./assets/perfect.mp3"),
            valid: buffer_sound_effect("./assets/valid.mp3"),
            firework: buffer_sound_effect("./assets/firework.mp3"),
        }
    }
}

The default initializer for the SoundEffects struct just creates a buffered decoding for each of the effects, which can be called later from the app code.

In app code, I can then clone one of these buffers and add it to a sink to play it. For example in the main game loop:



fn run_app<B: Backend>(terminal: &mut Terminal<B>, app: &mut App) -> io::Result<()> {
    // ...TRUNCATED   

    let (_stream, stream_handle) = OutputStream::try_default().unwrap();
    let sink = Sink::try_new(&stream_handle).unwrap();
    let sound_effects = SoundEffects::default();

    loop {
        if event::poll(timeout)? {
            if let Event::Key(key) = event::read()? {
              // ...TRUNCATED

                match app.current_screen {
                  // ...TRUNCATED
                    CurrentScreen::PickingNumbers => match key.code {
                        KeyCode::Enter => {
                            if app.is_number_selection_complete() {
                                app.current_screen = CurrentScreen::Playing;
                                sink.append(sound_effects.start.clone());
                            }
                        }
                    }
                }
            }
        }
        // TRUNCATED...
    }
}

We initialize the sink ahead of the main loop, then play the buffered sound from within it (line 19), by calling sink.append(). sink.append() pushes the buffer into a queue and plays it immediately (if nothing is already playing), or waits until the last sound has finished before starting. That setup works here, and if you need to play sounds simultaneously, you can create multiple sinks. This setup also avoids borrow checker issues with consuming the File struct, which might arise when decoding the File within the main loop.

🙌🏽 Ratatui Audio with Rodio: Wrapping Up

In this Ratatui audio with Rodio post, I briefly ran through how I added audio to the Ratatui Countdown game. In particular, I talked about:

why I added Rodio;
why you might buffer Rodio to avoid borrow checker issues in a game loop; and
how I buffered MP3 sound FX with Rodio.

I hope you found this useful. As promised, you can get the full project code on the Rodney Lab GitHub repo. I would love to hear from you, if you are also new to Rust game development. Do you have alternative resources you found useful? How will you use this code in your own projects?

🙏🏽 Ratatui Audio with Rodio: Feedback

Ratatui for Terminal Fireworks: using Rust TUI Canvas

Rodney Lab — Wed, 19 Jun 2024 17:00:01 +0000

🧨 Adding Fireworks to the Ratatui Game

In this Ratatui for Terminal Fireworks post, I talk about how I added fireworks to the Text-based User Interface (TUI) game I created in a recent post. The game is based on the arithmetic challenge from the UK TV quiz, Countdown. The Ratatui game worked already, but was little more than a minimal viable product.

I mentioned some rough corners worth focussing on in that previous post. One of those rough corners was adding some confetti or fireworks to the results screen when the player achieves a perfect score. In this post, I take a quick look at how I added fireworks using the Ratatui canvas. There is a link to the latest project repo, with full code further down.

🧱 Ratatui for Terminal Fireworks: What I Built

The game stayed mostly as it was, and only the victory screen changed, adding a fireworks animation using a Ratatui canvas widget if the player got a perfect score.

🧑🏽‍🎓 Ratatui Examples

In the post on Trying Ratatui TUI, I listed some resources for getting started with Ratatui, including three official tutorials. Those tutorials focus on text-content, and the Ratatui Canvas widget is a better match for the fireworks animation, as I would want to draw shapes to the window at arbitrary locations.

Luckily, there is another invaluable resource for getting started with Ratatui: the examples in Ratatui’s GitHub repo.

The canvas examples within the repo and more specifically, the Pong frame, within that collection was super helpful in getting going here, as it included example code on timing in Ratatui.

🎆 Fireworks Alternative

There is an alternative for adding fireworks, worth a mention. That combines Ratatui with the Bevy Rust game engine, calling Ratatui from within a Bevy app. This alternative approach uses bevy_ratatui. This lets you take advantage of Bevy features, such as its Entity Component System (ECS) and plugin ecosystem, while still rendering to the Terminal.

At the time of writing, bevy_ratatui is still experimental. Also, I already have a Ratatui app, and wanted to avoid re-writing it with Bevy, so decided to stick with Ratatui’s canvas widget for the firework animation. bevy_ratatui does look promising though, and I will probably try it in another project soon. Let me know if you have already tried it and have some feedback!

🖥️ My Approach using Ratatui Canvas

Creating and drawing to the canvas widget was not too complicated. I created a Rust Vec of firework Sparks structs. Each Spark struct had a colour (selected randomly at initialization) and current position and velocity values. I just needed to loop over that Spark Vec to display each of them on each render.



fn create_result_block_canvas<'a>(app: &'a App, sparks: &'a [Spark]) -> impl Widget + 'a {
    match app.check_solution() {
        Some(0) => Canvas::default()
            .block(Block::default())
            .marker(symbols::Marker::Dot)
            .paint(move |ctx| {
                for Spark {
                    x_position,
                    y_position,
                    colour,
                    ..
                } in sparks
                {
                    ctx.draw(&Circle {
                        x: *x_position,
                        y: *y_position,
                        radius: 1.0,
                        color: *colour,
                    });
                }
            })
            .x_bounds([-100.0, 100.0])
            .y_bounds([-50.0, 50.0]),
        None | Some(_) => Canvas::default(),
    }
}

Ratatui uses immediate mode, so you have to redraw every element for each frame. I updated the position elements for each spark in an on_tick method, which also runs each frames, creating the appearance of moving sparks.

🙌🏽 Ratatui for Terminal Fireworks: Wrapping Up

In this Ratatui for Terminal fireworks post, I briefly ran through how I added fireworks to the Ratatui Countdown game. In particular, we saw:

a link to code examples for getting started with Ratatui;
the bevy_ratatui app as an alternative route to rendering in the Terminal; and
some code snippets and design choices for my own Ratatui game.

🙏🏽 Ratatui for Terminal Fireworks: Feedback

Trying Ratatui TUI: Rust Text-based User Interface Apps

Rodney Lab — Wed, 12 Jun 2024 16:42:23 +0000

Ratatui and Text-based User Interfaces

I have been trying Ratatui TUI, a Rust crate for building Text-based User Interface (TUI) apps, which typically run in the Terminal. Ratatui, along with Go-based Bubble Tea might be responsible for the recent growth in TUIs. Some examples of TUI apps are Lazygit, glow, Soft Serve, ATAC and rlt. C++ programmers are not left out — FTXUI is a modern C++ library for building TUIs.

You use the Ratatui crate to build command line apps in Rust, though it is a little different to other Rust libraries like clap and inquire. clap focusses on managing and parsing command line flags (its name is an acronym: Command Line Argument Parser). inquire, is designed for interacting with the user, prompting them for information via the command line. Ratatui is different to both, and gives you more control over the text-based app’s user interface layout and handling interaction.

🧑🏽‍🎓 Ratatui Learning Resources

Ratatui is a powerful library, so there is a little to learn, and the project provides three beginner tutorials to help flatten the learning curve. These are:

Ratatui Hello World Tutorial, which is a good starting point if you are quite new to the Rust ecosystem;
Counter App, which takes things up a level and introduces immediate mode rendering; and
JSON Editor, which introduces more sophisticated layouts.

If this is your first Rust app, you might want to start with either Command line app in Rust, or probably The Rust Programming Language, both free web books.

🧱 What I Built

After following the tutorials, a nice extension was to create a basic numbers game, inspired by the UK TV Countdown quiz. For this arithmetic challenge, the player randomly picks six numbers, then using +, -, * and / operators, tries to arrive at a target.

This little game provided a natural extension to the JSON editor tutorial, mentioned above.

⚙️ Project setup

Beyond the ratatui and crossbeam crates used in the JSON tutorial, I added num_parser and rand. Naturally, rand was useful for generating the target and helping select the six, initial numbers.

[package]
name = "countdown-numbers"
version = "0.1.0"
edition = "2021"
license = "BSD-3-Clause"
repository = "https://github.com/rodneylab/countdown-numbers"
rust-version = "1.74"
description = "Trying Ratatui TUI 🧑🏽‍🍳 building a text-based UI number game in the Terminal 🖥️ in Rust with Ratatui immediate mode rendering."

[dependencies]
crossterm = "0.27.0"
num_parser = "1.0.2"
rand = "0.8.5"
ratatui = "0.26.3"

I set the game up, so the player typed in their solution attempt, with their chosen numbers, using familiar algebraic notation. For example, let’s say the target is 326 and the six numbers are 1, 2, 2, 75, 50 and 25. Here, it is possible to reach the target exactly, and the player could enter their solution into the Ratatui app as:

(2 * 2 * 75) + 25 + 1

The num_parser crate can parse that expression and yield the result (326), significantly reducing the number of lines of code I had to write.

That was all I needed for dependencies: crossterm, num_parser, rand and ratatui.

🧑🏽‍🍳 What I Liked about Ratatui

📚 Fantastic Docs

The three tutorials are very well written, and provide a great introduction to using Ratatui, including unit testing your app. Beyond the tutorials, I found the official Ratatui API docs were detailed enough to solve all the queries I had as I built the app.

📦 Leveraging crates.io

Being able to leverage the Rust crate ecosystem was a huge help. I mentioned num_parser did a lot of heavy-lifting. This was quick to find num_parser using crates.io. Although a similar C++ library might exist, I don’t think I could have found it so easily. I am not familiar enough with the Go ecosystem to comment on how that would have worked out for me, drop a comment below if you are familiar, or if you are a C++ aficionado, and know an easy way to find C++ libraries.

🖥️ Trying Ratatui TUI: Immediate Mode

I kept the app structure from the JSON tutorial, that is, with three main source files:

src/main.rs: contains the main loop, draws the UI and listens for UI events, immediately calling app methods;
src/app.rs: manages app state and provides helper functions the app calls on user event; and
src/ui.rs: generates the UI based on the current app state.

The immediate mode pattern worked well, writing how the app UI should look for any given state, with Rust pattern matching helping me get going quicker, making sure I covered all possible states, with no surprises.

As an example of how this worked, we might look at the initial number picking. The player presses [ to pick a small number and ] for a large one. These key presses are captured in event listener code in src/main.rs:

match app.current_screen {
    CurrentScreen::Introduction => {
        if key.code == KeyCode::Enter {
            app.current_screen = CurrentScreen::PickingNumbers;
        }
    }
    CurrentScreen::PickingNumbers => match key.code {
        KeyCode::Enter => {
            if app.is_number_selection_complete() {
                app.current_screen = CurrentScreen::Playing;
            }
        }
        KeyCode::Char(']') => {
            app.pick_random_large_number();
        }
        KeyCode::Char('[') => {
            app.pick_random_small_number();
        }
        _ => {}
    },
    // TRUNCATED...
}

So pressing those square bracket keys triggers an app state update (src/app.rs):

pub fn pick_random_large_number(&mut self) {
    if let Some(index_value) = self.random_available_large_number_index() {
        let result = self.available_large_numbers[index_value];
        let picked_index = self.selected_numbers.iter().position(|&val| val.is_none());
        if let Some(picked_index_value) = picked_index {
            if result.is_some() {
                self.selected_numbers[picked_index_value] = result;
                self.available_large_numbers[index_value] = None;
            };
        }
    }
}

Then the UI model is updated (src/ui.rs):

fn create_selected_numbers_block(app: &App) -> Paragraph {
    let mut selected_numbers_text = app.selected_numbers.into_iter().fold(
        vec![Span::styled("Numbers: ", Style::default())],
        |mut accum, val| {
            if let Some(value) = val {
                accum.push(Span::styled(
                    format!("{value} "),
                    Style::default().fg(Color::Green),
                ));
            } else {
                accum.push(Span::styled("_ ", Style::default().fg(Color::Green)));
            };
            accum
        },
    );
    // TRUNCATED...
}

Hence, the current app state gets reflected on the next enumeration of the event loop.

There is a link further down to the complete code for the project.

🏁 Trying Ratatui TUI: What Next?

So far, I have a minimal proof of concept. I would like to remove some rough edges. In particular:

add some fireworks to make the victory screen feel a little more of a celebration;
add sound feedback when the user hits keys; and
improve gameplay.

For improving gameplay, there are already different messages depending on how close to the target you got. However, I would like to take this to the next level, adding a game timer and putting best times on a high-score board. This definitely provides motivation for me playing Sudoku Pi (also written in Rust), and I hope it will translate to this game.

🙌🏽 Trying Ratatui TUI: Wrapping Up

In this post on trying Ratatui TUI, we looked got an introduction to immediate mode user interfaces in Rust. In particular, we saw:

TUI alternatives to Rust’s Ratatui in Go and C++;
other Rust Terminal app tooling and how Ratatui is different; and
some learning resources for getting started with Ratatui.

🙏🏽 Trying Ratatui TUI: Feedback

Using egui for Bevy ECS Introspection with Macroquad Rendering

Rodney Lab — Wed, 05 Jun 2024 17:19:46 +0000

👀 Using egui for Bevy ECS Introspection

In this post, we look at using egui for Bevy Introspection with Macroquad rendering. This continues the series of recent posts, which started with adding egui DevTools to Macroquad, then added Rapier physics, units of measurement and an Entity Component system (ECS).

Here, we bring everything together, adding DevTools-like introspection to the Bevy ECS demo from the previous post. As before, the complete project code is on GitHub (link further down).

🧱 What are we Building Here?

The demo simulation, built in Rust, shows a series of coloured, floating bubbles release and float to top of the window. The bubbles subsequently get trapped at the top of the screen; filling the window, from the top down.

I employed the following tools to build the demo:

Macroquad — a fast, quick-to-get going on Rust tool built with game prototyping in mind;
Rapier — mature, pure Rust physics engine for game dev;
uom — a crate with applications in Aerospace for maintaining consistency in physical quantity units and helping to avoid unit errors;
Bevy ECS — ECS implementation from the Bevy game engine, added to this project as the stand-alone bevy_ecs crate; and
egui — an immediate Graphics User Interface (GUI) library for Rust (inspired, in fact, by the C++ Dear ImGui library).

I focus on the egui integration in this post, so feel free to jump back through the series to learn more about how I put the other elements together.

⚙️ Crate Setup

You might need to use slightly older (than the latest) versions of some crates to get everything working together. Here is my Cargo.toml, which you can use as a starting point for finding compatible versions of egui, egui-macroquad and macroquad:

[package]
name = "macroquad-bevy-ecs-introspection"
version = "0.1.0"
edition = "2021"
license = "BSD-3-Clause"
repository = "https://github.com/rapier-example"
# bevy_ecs 0.13 requires MSRV 1.76
rust-version = "1.76"
description = "Macroquad Rapier ECS 🦀 Rust game dev — using bevy's 🧩 Entity Component System in a Macroquad game with Rapier physics."

[dependencies]
bevy_ecs = "0.13.2"
crossbeam = "0.8.4"
egui = "0.21.0"
egui-macroquad = "0.15"
macroquad = { version = "0.3.26", default-features = false }
rand = "0.8.5"
rand_distr = "0.4.3"
rapier2d = { version = "0.19.0", features = ["simd-stable"] }
uom = "0.36.0"

🔄 Update egui Introspection System

I introduced Bevy ECS to the project in a previous Macroquad Rapier ECS post. Continuing, we need to add a couple of ECS systems for updating and rendering the egui DevTools. First up is the update_dev_tools_system in src/systems.rs:

pub fn update_dev_tools_system(query: Query<(Entity, &Position, &Velocity, &CircleMesh)>) {
    egui_macroquad::ui(|egui_ctx| {
        egui_ctx.set_pixels_per_point(4.0);
        egui::Window::new("Developer Tools").show(egui_ctx, |ui| {
            ScrollArea::vertical().show(ui, |ui| {
                CollapsingHeader::new("Bubbles")
                    .default_open(false)
                    .show(ui, |ui| {
                        for (entity, position, bubble_velocity, circle_mesh) in &query {
                            draw_ball_ui_data(ui, entity, position, bubble_velocity, circle_mesh);
                        }
                    });
            });
        });
    });
}

Bevy ECS Queries

Typically, for Bevy ECS, this function takes a query over ECS components as its argument (line 107). Here, the query generates a collection of all ECS entities that have Position, Velocity and CircleMesh components (essentially the bubbles). Additionally:

In line 109, I call set_pixels_per_point this scales up the UI. 4.0 worked for screen captures, though for general use, you will probably want something a touch lower.
We need a ScrollArea in the UI (line 111) to make viewing data for the dozens of balls in the simulation more practical.
You can iterate over the ECS entities satisfying the initial query, with a simple for loop (line 115).

Next, we look at the draw_ball_ui_data function called within that last loop.

🫧 Individual Bubble Updates

Another advantage of using the uom crate for handling physical quantities is formatting of those values for output, which we use in the draw_ball_ui_data function (src/systems):

fn draw_ball_ui_data(
    ui: &mut Ui,
    entity: Entity,
    position: &Position,
    bubble_velocity: &Velocity,
    circle_mesh: &CircleMesh,
) {
    let m = Length::format_args(length::meter, Abbreviation);
    let m_s = VelocityUnit::format_args(velocity::meter_per_second, Abbreviation);
    CollapsingHeader::new(format!(
        "Entity Generation:ID {}:{}",
        entity.generation(),
        entity.index()
    ))
    .default_open(false)
    .show(ui, |ui| {
        ui.horizontal(|ui| {
            ui.label("Position");
            ui.label(format!(
                "x: {:.2}, y: {:.2}",
                m.with(position.0.x),
                m.with(position.0.y)
            ))
        });
        // TRUNCATED...
    });
}

Quantity Formatting

To select preferred formatting, in lines 55 and 56, we add unit formatting for metre and metre per second quantities. These uom format args incorporate type checking, so you would get a compile-time error if you tried to format a length quantity using metres per second, for example.

Notice, in for example, in lines 67-70 that we can use standard Rust formatting arguments with the uom format arg to specify the precision we want position output data with. Here, the {:.2} format specifiers indicates we want to round the position values to two decimal places.

ECS Entity Generations and IDs

ECS entities are not a lot more than an integer ID and a generation. The generation provides a mechanism for reusing IDs. For example, the first bubble spawned might have ID 0 and generation 1. If we then despawned that bubble from the ECS, the next bubble can re-use ID 0, which is now free. However, the ECS would give it a generation of 2, so it can be distinguished from the earlier one.

We access, both generation an id from the Bevy ECS Entity struct calling .generation() and .index() in lines 59 and 60.

✍🏽 Draw UI System

The system for actually drawing the DevTools panel, using egui is a little simpler — we just need to call egui_macroquad::draw:

pub fn draw_dev_tools_system() {
    egui_macroquad::draw();
}

📆 Bringing it all together: ECS Schedule

I added the two new systems to the Bevy ECS schedule, to give us some control over the order Bevy ECS runs them in (src/main.rs):

let mut playing_schedule = Schedule::default();
playing_schedule
        .configure_sets(
                (
                        ScheduleSet::BeforeSimulation,
                        ScheduleSet::Simulation,
                        ScheduleSet::AfterSimulation,
                )
                        .chain(),
        )
        .add_systems(
                (
                        create_ball_physics_system,
                        (
                                update_dev_tools_system,
                                draw_balls_system,
                                draw_dev_tools_system,
                        )
                                .chain(),
                )
                        .chain()
                        .in_set(ScheduleSet::BeforeSimulation),
        )
        .add_systems(step_physics_engine_system.in_set(ScheduleSet::Simulation))
        .add_systems(
                (
                        update_balls_system,
                        spawn_new_ball_system,
                        end_simulation_system,
                )
                        .in_set(ScheduleSet::AfterSimulation),
        );

With Bevy ECS, schedule systems grouped into a tuple will run in parallel. Tacking .chain() onto the end of the tuple tells the ECS that you want the systems to run in series, in the order of appearance.

🏁 What Next?

I have the basic, minimal DevTools panel working now. In terms of extensions and where to go next, I am considering:

adding a wireframe view mode, with toggle, to show/hide the Rapier colliders;
buttons for pausing, stepping and restarting the simulation from the dev panel tool; and
adding the collider properties to the panel.

Interested to know if you have some ideas on and also, what else might be a good direction to take this in. Drop a comment below, or reach out on other channels.

🙌🏽 Using egui for Bevy ECS Introspection: Wrapping Up

In this post on using egui for Bevy ECS introspection, we looked at displaying Rapier physical properties with egui and Macroquad rendering. In particular, we saw:

code for adding egui update and draw ECS systems;
how you can add an egui ScrollArea to display large data collections; and
how you can format uom quantities for display, including rounding to a fixed number of decimal places.

🙏🏽 Using egui for Bevy ECS Introspection: Feedback

Macroquad Rapier ECS: Using Bevy ECS in Macroquad Game

Rodney Lab — Thu, 30 May 2024 08:03:14 +0000

🐣 Using Bevy Entity Component System outside of Bevy

Not every game needs an Entity Component System (ECS), but for this Macroquad Rapier ECS post, I was keen to see how you might add an ECS to a Macroquad game with Rapier physics.

In a previous post, I used the Shipyard ECS with Macroquad. I have been working through a build-your-own physics engine tutorial, which used the Bevy game engine. I loved the ergonomics of the embedded ECS, so thought, I would take it for a spin here. Rapier the Rust physics engine used here has a Bevy plugin, but I wanted to try using both Rapier and the stand-alone Bevy ECS outside of Bevy, just for the challenge.

🧱 Macroquad Rapier ECS: What I Built

I continued with the bubble simulation, used for a few recent posts. It had no ECS, dozens of entities and a few other features that made it interesting to try with an ECS data model. So that was my starting point.

The simulation releases bubbles which float to the top of the screen, where they are trapped by a Rapier height field. Once all existing bubbles are settled, the simulation spawns a fresh one.

The simulation uses a random number generator to decide on the initial velocity of spawned balls, and has running and paused states. The simulation triggers the paused state when the bubbles almost completely fill the window. Both the random number generator and the simulation state are singletons, and fit well into the ECS resource model. I also put the physics engine itself into an ECS resource. The C/C++ flecs ECS library, for example, calls resources singletons.

The Simulation within the ECS Model

As you would expect, each bubble is an entity. If you are new to ECSs you might imagine the ECS entities as rows of a database table. In this database world, the table columns are components. In my case, the balls all have the same components:

a circle static mesh (which encodes colour and size data needed for rendering);
a circle collider (for handling physical collisions with Rapier); and
position and velocity components (used for updating the simulation physics).

Systems mutate the component properties, for example, there is a ball update system, which uses Rapier, to work out what the current velocity of the bubble is, at each step, then update the velocity component.

In the following sections, we look at some code snippets to help illuminate the points here, and hopefully give you an idea of how I put the simulation together, adding an ECS to Macroquad. The full code is on GitHub, and there is a link to it further down.

🧩 Components

I just mentioned that bubble entities each have a few components. Here is some example code for spawning a new ball using the simulation ECS:

let _ball_entity = world.spawn((
    Position(new_ball_position),
    CircleMesh {
        colour: BALL_COLOURS[macroquad_rand::gen_range(0, BALL_COLOURS.len())],
        radius: Length::new::<length::meter>(BALL_RADIUS),
    },
    CircleCollider {
        radius: Length::new::<length::meter>(BALL_RADIUS),
        physics_handle: None,
    },
    Velocity(new_ball_velocity),
));

The new entity gets a Position, CircleMesh, CircleCollider and Velocity. The number of components here is arbitrary, and not fixed (as it might be when calling a constructor using an object-oriented approach). This grants flexibility as you develop the simulation or game.

Also note, I follow a Rust convention in naming the _ball_entity identifier. The initial underscore (_) indicates the identifier is not used anywhere else in the scope. We do not need it later, since the systems used to query and mutate the component properties, operate on entities with specific sets of components (properties). We will see this more clearly later.

In an ECS model, the entity is not much more than an integer, which Bevy ECS can use as an ID.

Units of Measurement

In a previous post on adding units of measurement to a Rapier game, I introduced the length units used in the snippet above. This pattern of using units leveraging Rusts type system, sense-checking calculations and helping to avoid unit conversion errors.

🏷️ Macroquad Rapier ECS: Tags

The Position and Velocity components, mentioned before, are structs with associated data. You can also have ECS tags, which are akin to components without data. Rapier has a type of collider that just detects a collision, and beyond that does not interact with the physics system, these are sensors.

I used a Sensor tag in the ECS for colliders that are sensors, which helps to separate them out when running systems. The only sensor in the simulation runs along the bottom of the window. Towards the end of the simulation, when the window is almost full, a newly spawned bubble will inevitably bounce off an existing one and collide with the floor sensor. I added a system to pause the simulation when this occurs, effectively ending the simulation.

#[derive(Component, Debug)]
pub struct CuboidCollider {
    pub half_extents: Vector2<f32>,
    pub position: Isometry<f32, Unit<Complex<f32>>, 2>,
    pub translation: Vector2<f32>,
}

#[derive(Component, Debug)]
pub struct Sensor;

This, above, code snippet shows a CuboidCollider (used for the floor sensor), which is a regular component and then the Sensor tag. The code snippet, below, initializes the floor sensor:

pub fn spawn_ground_sensor_system(mut commands: Commands) {
    let collider_half_thickness = Length::new::<length::meter>(0.05);
    let window_width = Length::new::<pixel>(WINDOW_WIDTH);
    let window_height = Length::new::<pixel>(WINDOW_HEIGHT);
    commands.spawn((
        CuboidCollider {
            half_extents: vector![
                0.5 * window_width.get::<length::meter>(),
                collider_half_thickness.value
            ],
            translation: vector![
                0.0,
                (-window_height - collider_half_thickness).get::<length::meter>()
            ],
            position: Isometry2::identity(),
        },
        Sensor,
    ));
}

Note, the Sensor tag is included. To spawn the wall colliders on either side of the window, a very similar block is used, only omitting the Sensor tag. We will see how this can be used with systems next.

🎺 Systems

Systems are code blocks, which are only run on components belonging to a specified component set. As an example, here is the system for updating bubble position and velocity within the game loop:

pub fn update_balls_system(
    mut query: Query<(&mut Position, &mut Velocity, &CircleCollider)>,
    physics_engine: Res<PhysicsEngine>,
) {
    for (mut position, mut velocity, circle_collider) in &mut query {
        if let Some(handle) = circle_collider.physics_handle {
            let ball_body = &physics_engine.rigid_body_set[handle];
            position.0 = vector![
                Length::new::<length::meter>(ball_body.translation().x),
                Length::new::<length::meter>(ball_body.translation().y)
            ];
            velocity.0 = vector![
                VelocityUnit::new::<velocity::meter_per_second>(ball_body.linvel().x),
                VelocityUnit::new::<velocity::meter_per_second>(ball_body.linvel().y)
            ];
        }
    }
}

This system runs on any entity that satisfies the query of having Position, Velocity and CircleCollider components. We can be more prescriptive, choosing entities that have a set of components, and also, either do, or do not have some other component or tag. We use With when creating the floor sensor during the simulation initialization:

pub fn create_cuboid_sensors_system(
    query: Query<&CuboidCollider, With<Sensor>>,
    mut physics_engine: ResMut<PhysicsEngine>,
) {
    for collider in query.iter() {
        let new_collider =
            ColliderBuilder::cuboid(collider.half_extents.x, collider.half_extents.y)
                .position(collider.position)
                .translation(collider.translation)
                .sensor(true)
                .build();
        physics_engine.collider_set.insert(new_collider);
    }
}

As you might expect, the equivalent code for creating the side wall colliders uses Without in its query, and omits .sensor(true) in its Rapier setup code.

📆 Schedules

We use ECS schedules to determine when systems run. The simulation has:

a setup schedule, run once during simulation setup,
a running schedule, executed on every run through the game loop in simulate/running mode; and
a paused schedule, runs when we have paused the simulation.

Bevy ECS organizes the systems above into these schedules, which can include constraints to ensure systems run in the right order.

Here is the paused schedule code:

    let mut paused_schedule = Schedule::default();
    paused_schedule.add_systems(draw_balls_system);

This just needs to draw the balls (the screen is cleared in each game loop iteration, even while the simulation is paused). The running schedule features more systems.

That code above is triggered in the game loop, while the simulation state is set to paused:

    loop {
        // TRUNCATED...
        clear_background(GUNMETAL);

        let simulation_state = world
            .get_resource::<SimulationState>()
            .expect("Expected simulation state to have been initialised");

        match &simulation_state.mode {
            SimulationMode::Running => {
                playing_schedule.run(&mut world);
            }
            SimulationMode::Paused => paused_schedule.run(&mut world),
        }

        next_frame().await;
    }

That’s it! We covered all the major constituents of an ECS!

🙌🏽 Macroquad Rapier ECS: Wrapping Up

In this post on Macroquad Rapier ECS, we got an introduction to working with an ECS in Macroquad. In particular, we saw:

the main constituents of an ECS including resources, schedules and tags, as well as entities, components, and systems;
why you might want to add tags, and how you can use them in Bevy ECS system queries along with With and Without; and
ECS schedules for different game or simulation states.

🙏🏽 Macroquad Rapier ECS: Feedback

Unreal Engine 5 macOS: UE5 C++ Game Dev

Rodney Lab — Wed, 22 May 2024 16:40:00 +0000

🧑🏽‍💻 Working with UE 5.4 on macOS

In this post, we see how you can work in Unreal Engine 5 on macOS. When using C++ with Unreal Editor, the official UE5 editor for macOS is Xcode, though we see how you can set up VS Code to work with UE5. This is a common developer editor choice and worth considering for UE5, if you are already familiar with it. We also see how you can make sure you have the right version of Xcode installed on your Mac, to work with UE 5.4.

🛠️ Installing UE5

To get going in Unreal Editor, you will first need to download the Epic Games Launcher. This manages your Unreal Engine install, letting you download Unreal Editor and flip between different installed versions.

You can install the Epic Games Launcher with Homebrew, from the Terminal:

brew install --cask epic-games

Once you have that, the actual Unreal Engine install can be quite large and take a while. To get started, open the Epic Games Launcher and create an account, if you do not already have one. Once you are set up, select Unreal Engine from the sidebar on the left, then Library from the toolbar, which run along the top of the window. You should see an icon showing the latest Unreal Engine version, which you can click to start the download. You can jump ahead to the next section, while you wait for the download.

⚙️ Installing Xcode for Unreal Engine on macOS

Even though we do not use Xcode as the editor here, you will need Xcode installed on your system for compiling under the hood. The officially supported Xcode version, may not be the latest Xcode version (even though you are using the latest version of Unreal). As an example, at the time of writing, you should opt for Xcode 14.3.1 for use with the current Unreal release (5.4.1).

You can check the Unreal Engine Xcode requirements for your Unreal Engine version in the official UE docs. It is important to use a supported version. As an example, I was able to compile code successfully using Xcode 15 (and UE5), but when I tried to re-open the project in Unreal Engine, I got a “The following modules are missing or built with a different engine version” error below (even after rebuilding).

However, by downgrading to Xcode 14.3.1, I got everything to run smoothly. You can download the latest version of Xcode from the macOS App Store, using a shortcut already on your dock or Launchpad. However, if you require an older version, you will need to use the Apple Developer site to download Xcode, logging in and completing any two-factor authorization requests. I would recommend using Safari for the download; the file will be quite big and Safari supports resuming your download, in case the connection drops.

You can have Unreal Engine generate the necessary VS Code project configuration by setting VS Code as your editor, then opening VS Code from the menu in Unreal Engine.

🧱 Running Unreal Engine builds in VS Code

With Xcode and Unreal Engine set up, let’s have a look at how to run builds from VS Code. To build your Unreal project using VS Code, install the C/C++ VS Code extension from Microsoft.

Now we are ready to roll. To run a development build, go to the Terminal menu and select Run build Task…. From the options, choose [YourProjectName]Editor Mac Development Build. This will build your project, and you will be able to see any changes you made with the Unreal Engine Editor UI. Run a quick rebuild, from within Unreal Engine Editor, by clicking the “Recompile on the fly” button in the status bar at the bottom right of the screen.

🙌🏽 Unreal Engine 5 macOS: Wrapping Up

In this Unreal Engine 5 macOS post, we saw how you can get going with game development in Unreal Engine using macOS. More specifically, we saw:

how to install Epic Games Launcher and Unreal Engine 5 on macOS;
checking you have the right Xcode version for your UE5 install; and
how to set up VS Code as an Unreal Engine C++ editor.

I hope you found this useful. Do let me know if you found this content useful and would like to see more similar content. Also reach out if there is anything I could improve to provide a better experience for you.

🙏🏽 Unreal Engine 5 macOS: Feedback

Rapier Physics with Units of Measurement: Utilize Rust Types

Rodney Lab — Wed, 15 May 2024 17:14:45 +0000

Unit of Measurement in Game Dev

In this post, we will take a quick look at Rapier physics with units of measurement (UOM). In a recent post, trying out the Rust Rapier physics engine with Macroquad, we noted that Rapier recommends using full-scale measurements for more realistic simulations. We opted for SI units (metres for distance and metres per second for velocities). There was necessary conversion from these physical units to pixels, for rendering.

This got me thinking about leveraging Rust’s types for conversion between the physics and graphics units. I discovered the Rust uom crate, which has applications in Aerospace. In his Rust Nation UK talk, Lachezar Lechev mentioned how confusion over units might have been behind a costly financial loss in a real-world Aerospace project.

If professional teams working full-time on a project with such high financial stakes can make mistakes, then, probably, anyone is prone to making similar mistakes. So, I considered adding UOM to my Rust game stack and talk about how I set it up in this post.

📏 `uom`

The uom crate, has applications in Aerospace and Aeronautical Engineering. By defining quantities with a unit of measurement, it can catch basic errors at compile time. As an example, you might define the speed of a ball in metres-per-second, and its mass in kilograms. Now, if you try (erroneously) to add the mass to the velocity, in your Rust code — something that doesn’t make sense physically — you will get a compile-time error, potentially saving you debugging an error, which might be hard to catch.

uom also helps with conversions, so you can safely add a displacement in kilometres to a diameter in metres.

⚙️ Adding `uom` to your Project

You can just add uom to your Cargo.toml:

[dependencies]
# ...TRUNCATED
rapier2d = { version = "0.19.0", features = ["simd-stable"] }
uom = "0.36.0"

For my use case, this worked just fine (with default features), though you might need to tweak the uom features, depending on your use case.

To define a custom pixel unit for conversion between the physics and rendering systems (using the uom unit macro), I also needed to add this snippet to my Rust source (last two lines):

use uom::{
    si::{
        f32::{Length, Velocity},
        length, velocity,
    },
    unit,
};

#[macro_use]
extern crate uom;

We come to the full definition of the custom unit later.

In this post, we use the example from the earlier Rapier Physics with Macroquad floating bubble post. In the following section, we see some snippets where I added units to that code. Find a link to the full code repo further down.

Domain Units of Measurement

The demo features floating bubbles or balls. For the demo domain, I use uom to define the ball with typed values in SI units. For rendering, I will need to convert these to pixels, and for use with Rapier, I will need a raw float value.

Here is the ball struct Rust code:

#[derive(Debug)]
struct Ball {
    radius: Length,
    position: Vector2<Length>,
    physics_handle: Option<RigidBodyHandle>,
    colour: Color,
}

uom has a predefined Length type alias using standard SI units for length quantities (metres). I use it here to set the type for the ball radius and current displacement within the simulation world.

🗡️ Rapier Physics Units

I kept things simple, and used SI units (with uom) within my own code, and converted the values to f32s whenever I needed to pass the value to Rapier. You could go a step further and use type-driven development, where (by design) only validated quantities can get passed to the Rapier physics engine.

Here is a code snippet, defining a new ball’s velocity and initializing it with Rapier:

let x_velocity: Velocity =
        Velocity::new::<velocity::meter_per_second>(pseudo_random_value);
let y_velocity: Velocity = Velocity::new::<velocity::meter_per_second>(1.0);

let linear_velocity = vector![x_velocity.value, y_velocity.value];

let rigid_body = RigidBodyBuilder::dynamic()
        .translation(vector![ball.position.x.value, ball.position.y.value])
        .linvel(linear_velocity)
        .build();

Velocity is a predefined uom type aliases (like Length).

In the first line, above, I defined x_velocity to be some random float, and associated metres per second as units, using the uom types.
For rapier2d, I need to pass the velocity components as f32 values, so extract the raw value from the two, typed velocities via the .value field.
Finally, in the last line we pass the linear_velocity, as an nalgebra Vector2 of 32-bit floats (expected by Rapier).

The example might seem a little contrived, as I convert a 32-bit float to a uom velocity, and then immediately convert it back to a float for consumption by Rapier. We shall see in a later section, though, that you can tweak this slightly to define a value in one unit, and then extract a converted value in another unit for passing to Macroquad for rendering.

🖥️ Macroquad Render Units of Measurement

For rendering, I am using Macroquad, which works with pixels. In the previous post, I set a scale of 50 pixels per metre. I formalized that here using a uom custom unit.

Custom Pixel Unit

uom provides the unit macro for defining custom units, needed in your domain. I used that macro to define a new pixel unit as a length measurement:

unit! {
    system: uom::si;
    quantity: uom::si::length;

    // 1 metre is 50 px
    @pixel: 0.02; "px", "pixel", "pixels";
}

Remember to include the snippet mentioned above if you use this macro.

Here:

system adds the new unit to the uom in-built SI units;
quantity defines the unit as a length; and
@pixel, in the final line, gives the abbreviation, singular and plural names for the unit.

Now, we can define variables using this new unit as a type, and convert between other units. As an example, the get_max_balls function uses quantities in both pixels and metres to determine the maximum number of balls that can fit across the app window, given the window has a pre-determined width:

fn get_max_balls() -> u32 {
    let window_width = Length::new::<pixel>(WINDOW_WIDTH);
    let ball_radius = Length::new::<length::meter>(BALL_RADIUS);

    (window_width / (2.0 * ball_radius)).value.floor() as u32
}

Here, window_width is defined in pixels and ball_radius, in metres. Notice, we use .value (as in the previous example) to extract the raw float value. WINDOW_WIDTH and BALL_RADIUS are raw f32 constants.

To convert a length between different length quantities (for example metres to pixels), we can call the get method on the quantity. For example, here is a snippet for rendering the ball where we need to convert the internal metre lengths to pixels:

fn draw_balls(balls: &[Ball]) {
    for ball in balls {
        let Ball {
            colour,
            position,
            radius,
            ..
        } = ball;
        draw_circle(
            position.x.get::<pixel>(),
            -position.y.get::<pixel>(),
            radius.get::<pixel>(),
            *colour,
        );
    }
}

The position and radius are all stored in metre values internally, yet there is no need to make sure we have the right conversion factor to get pixels out; the custom uom does that for us. Although the calculations are relatively simple to perform manually, converting automatically can save you making a simple mistake when revisiting code you haven’t seen in a while.

🙌🏽 Rapier Physics with Units of Measurement: Wrapping Up

In this post on Rapier Physics with Units of Measurement, we got an introduction to working with units of measurement with Rapier. In particular, we saw:

how you can use the uom Rust crate to add SI units of measurement to game physics;
how you can define custom quantities and convert between units; and
interface with code that does not expect units.

🙏🏽 Rapier Physics with Units of Measurement: Feedback

Rapier Physics with Macroquad: Rust Game Physics

Rodney Lab — Wed, 08 May 2024 16:41:07 +0000

Unit of Measurement in Game Dev

📏 `uom`

uom also helps with conversions, so you can safely add a displacement in kilometres to a diameter in metres.

⚙️ Adding `uom` to your Project

You can just add uom to your Cargo.toml:

[dependencies]
# ...TRUNCATED
rapier2d = { version = "0.18.0", features = ["simd-stable"] }
uom = "0.36.0"

For my use case, this worked just fine (with default features), though you might need to tweak the uom features, depending on your use case.

To define a custom pixel unit for conversion between the physics and rendering systems (using the uom unit macro), I also needed to add this snippet to my Rust source (last two lines):

use uom::{
    si::{
        f32::{Length, Velocity},
        length, velocity,
    },
    unit,
};

#[macro_use]
extern crate uom;

We come to the full definition of the custom unit later.

Domain Units of Measurement

Here is the ball struct Rust code:

#[derive(Debug)]
struct Ball {
    radius: Length,
    position: Vector2<Length>,
    physics_handle: Option<RigidBodyHandle>,
    colour: Color,
}

🗡️ Rapier Physics Units

Here is a code snippet, defining a new ball’s velocity and initializing it with Rapier:

let x_velocity: Velocity =
        Velocity::new::<velocity::meter_per_second>(pseudo_random_value);
let y_velocity: Velocity = Velocity::new::<velocity::meter_per_second>(1.0);

let linear_velocity = vector![x_velocity.value, y_velocity.value];

let rigid_body = RigidBodyBuilder::dynamic()
        .translation(vector![ball.position.x.value, ball.position.y.value])
        .linvel(linear_velocity)
        .build();

Velocity is a predefined uom type aliases (like Length).

In the first line, above, I defined x_velocity to be some random float, and associated metres per second as units, using the uom types.
For rapier2d, I need to pass the velocity components as f32 values, so extract the raw value from the two, typed velocities via the .value field.
Finally, in the last line we pass the linear_velocity, as an nalgebra Vector2 of 32-bit floats (expected by Rapier).

🖥️ Macroquad Render Units of Measurement

For rendering, I am using Macroquad, which works with pixels. In the previous post, I set a scale of 50 pixels per metre. I formalized that here using a uom custom unit.

Custom Pixel Unit

uom provides the unit macro for defining custom units, needed in your domain. I used that macro to define a new pixel unit as a length measurement:

unit! {
    system: uom::si;
    quantity: uom::si::length;

    // 1 metre is 50 px
    @pixel: 0.02; "px", "pixel", "pixels";
}

Remember to include the snippet mentioned above if you use this macro.

Here:

system adds the new unit to the uom in-built SI units;
quantity defines the unit as a length; and
@pixel, in the final line, gives the abbreviation, singular and plural names for the unit.

fn get_max_balls() -> u32 {
    let window_width = Length::new::<pixel>(WINDOW_WIDTH);
    let ball_radius = Length::new::<length::meter>(BALL_RADIUS);

    (window_width / (2.0 * ball_radius)).value.floor() as u32
}

fn draw_balls(balls: &[Ball]) {
    for ball in balls {
        let Ball {
            colour,
            position,
            radius,
            ..
        } = ball;
        draw_circle(
            position.x.get::<pixel>(),
            -position.y.get::<pixel>(),
            radius.get::<pixel>(),
            *colour,
        );
    }
}

🙌🏽 Rapier Physics with Units of Measurement: Wrapping Up

In this post on Rapier Physics with Units of Measurement, we got an introduction to working with units of measurement with Rapier. In particular, we saw:

how you can use the uom Rust crate to add SI units of measurement to game physics;
how you can define custom quantities and convert between units; and
interface with code that does not expect units.

🙏🏽 Rapier Physics with Units of Measurement: Feedback

Macroquad egui DevTools: Rust Game Debugging UI

Rodney Lab — Thu, 02 May 2024 11:01:03 +0000

🎮 Macroquad egui DevTools

In this post on Macroquad egui DevTools, I talk about a demo project I put together to add a developer-focussed debugging view to a Macroquad game. Macroquad is a Rust game development library built for fast prototyping and egui is a Rust immediate mode GUI. Interestingly, both were inspired by libraries from the C/C++ world. Macroquad was inspired by the C, raylib library, while Dear ImGui inspired the creation of egui.

We shall see the idea of the DevTools is to create a debugging interface, rather than something intended for end-user access. The inspiration here is the DevTools found in web browsers like Chrome and Firefox to help web developers debug sites they are working on. Using egui we shall see how you can both display data on the current Macroquad game state and also mutate the state. The latter could be handy for tweaking gameplay or even just the game aesthetic, working on real-world project.

Macroquad does have its own UI, though I preferred to use egui here partly because it allows more flexibility. It saves me having to learn another UI interface, and also make the UI more portable if I later want to port the game to Bevy, Godot or Tauri for example. egui enjoys wide support in the Rust Game Dev ecosystem.

Anyway, if this all sounds interesting to you, then let’s press on, starting by taking a look at what I created.

🧱 What I Built

I built a minimal proof-of-concept “game” using Macroquad and egui. The Macroquad base code renders a carrot coloured ball, which bounces off the window edges. Using egui widgets, I then added a dev panel which has readouts of the ball current position and velocity. Taking things a step further, another widget lets the developer change the size of the ball in real-time, just by using an egui UI slider.

🤔 A Little more about egui

I mentioned egui is an immediate mode GUI. Immediate mode is a design pattern where code for handling user interface side effects appears alongside the code for the UI itself. For example, there is no callback function attached to our slider for adjusting the ball radius. We just pass a mutable reference to the ball radius into the slider widget UI method, and let the UI widget update the radius directly.

That immediate mode pattern makes coding an interface far simpler. It is not all milk and honey, though! Re-rendering unchanged elements on every loop might be inefficient. Another drawback is that precise layout can be tricky with immediate mode. Because the library draws widgets as it encounters them, centring a widget horizontally, as an example, can be tricky. This is because we might not know how wide the widget or container are until we have drawn them. That said, for a game debugging tool, immediate mode is a pretty good match.

If you want to see a more general introduction to egui or immediate mode in Rust, see a recent post where we looked at creating a Cistercian clock using Rust with egui.

⚙️ Project Setup

The macroquad-egui crate is probably the easiest way to get egui working with Macroquad. At the time of writing, macroquad-egui was not working well with the latest version of Macroquad, though I found these versions do work well together:

[package]
name = "macroquad-egui"
version = "0.1.0"
edition = "2021"

[dependencies]
egui = "0.21.0"
egui-macroquad = "0.15"
macroquad = { version="0.3.26", default-features=false }

You can find some skeleton code in the egui-macroquad repo to test your setup:

// Source: https://github.com/optozorax/egui-macroquad#usage
use macroquad::prelude::*;

#[macroquad::main("egui with macroquad")]
async fn main() {
    loop {
        clear_background(WHITE);

        // Process keys, mouse etc.

        egui_macroquad::ui(|egui_ctx| {
            egui::Window::new("egui ❤ macroquad")
                .show(egui_ctx, |ui| {
                    ui.label("Test");
                });
        });

        // Draw things before egui

        egui_macroquad::draw();

        // Draw things after egui

        next_frame().await;
    }
}

🖱️ Adding egui to Macroquad

Probably the hardest part, if you are new to egui, is to work out how to display the widgets you want. The egui demo site is quite handy in this regard. It features the egui widgets, and has GitHub links to the Rust code used to make each widget. This will help you replicate them in your own project.

I include the egui code I wrote here, in case it is useful for you as a starting point:

egui_macroquad::ui(|egui_ctx| {
    egui_ctx.set_pixels_per_point(4.0);
    egui::Window::new("Developer Tools").show(egui_ctx, |ui| {
        CollapsingHeader::new("Ball Physics")
            .default_open(false)
            .show(ui, |ui| {
                ui.horizontal(|ui| {
                    ui.label("Position");
                    ui.label(format!(
                        "x: {:.2} y: {:.2}",
                        ball.position.x, ball.position.y
                    ));
                });
                ui.horizontal(|ui| {
                    ui.label("Velocity");
                    ui.label(format!("x: {} y: {}", ball.velocity.x, ball.velocity.y));
                });
            });
        CollapsingHeader::new("Ball Shape")
            .default_open(false)
            .show(ui, |ui| {
                ui.horizontal(|ui| {
                    ui.label("Radius");
                    ui.add(egui::Slider::new(&mut ball.radius, 1.0..=100.0));
                });
            });
    });
});

Some interesting points;

set_pixels_per_point in line 128 scales the whole user interface. I set 4.0 so the elements were large enough for capturing screenshots, and this might be a little high for general use.
The CollapsingHeader element in lines 130-144 creates the folding tree structure you see in the demo.
Notice in line 150, we just pass in a mutable reference to ball.radius to the slider. No need for callbacks; it directly updates the same variable which Macroquad uses for rendering.

Hopefully the other parts of the code will make sense, probably more so if you have already used Dear ImGui. That said, please let me know if some lines would benefit from further clarification. I have added a link, further down, to the entire project code.

🏁 What Next for the Macroquad egui DevTools Interface?

I mentioned this is just a basic proof-of-concept. I have tried a similar game debugging interface in C++ using raylib and Dear ImGui and would like to bring some features across such as:

adding game state and pausing play in the Dev Tools;
having separate regular and debugging DevTools modes; and
the ability to move the dev tool tab so it does not overlap the main window.

🙌🏽 Macroquad egui DevTools: Wrapping Up

In this Macroquad egui DevTools post, we got an introduction to working with Macroquad and egui. In particular, we saw:

which versions of Macroquad and egui work with egui-macroquad;
how you might use egui to update game state from a debugging panel; and
some resources for getting started with egui.