Introduction

Rusteal lets you write Unreal Engine 5.8 games in Rust. Your gameplay code is a Rust crate, compiled into a library that a small Unreal plugin loads. The classes you declare in it are real Unreal classes: they show up in the editor, they can be placed in a level, Blueprints can derive from them, and they are saved, cooked and packaged like classes written in C++.

This book is for the game developer. It shows how to use Rusteal to make a game: how to create a project, how to write actors, characters and systems in Rust, how to work with the editor and Blueprints, how to iterate without restarting the editor, and how to ship. It does not explain how Rusteal itself is built.

What stays in the editor, what goes in Rust

Rusteal does not replace the editor. A Rusteal game is an Unreal project like any other, and the work is split the way a C++ project splits it:

A Rust class declares a property, and a Blueprint child of that class picks the mesh, the sound or the input action that goes into it. That is how Epic’s own C++ templates work, and Rusteal’s templates are those same templates with the C++ replaced by Rust.

How the book is organized

• Getting started installs the tools and creates a first project.
• The rusteal CLI covers every command you run while making the game.
• The iteration loop covers hot reload, rusteal watch, the console commands and testing.
• Classes covers what you write: classes, properties, components, functions, events, interfaces and structs.
• The engine API covers how Rust code talks to the engine: object references, spawning, assets, timers, traces and delegates.
• Gameplay recipes are complete use cases taken from the templates: movement, cameras, combat, AI, UI and more.
• Systems covers subsystems, settings, data assets, console commands and background work.
• Plugins covers gameplay and editor plugins written in Rust.
• Shipping covers packaging the game.
• Reference collects the attributes, the types, the event names, the known limits and the common problems.

Status

Rusteal is in early development. Its API changes between versions, and many engine features are not covered yet. Each chapter says what works today, and Known limits lists what does not.

How to read this book

Most pages are written as use cases. Each one starts from something you want to do in a game and shows how to do it with Rusteal:

• The goal: what the use case achieves in the game.
• The code: the Rust you write, complete enough to compile in a project made by rusteal new.
• In the editor: what you do in Unreal Editor, step by step, with the names the editor shows.
• Notes: limits, alternatives and what to watch for.

Code conventions

The examples import from two places:

• rusteal_runtime, the runtime crate: the attributes (uclass, uclass_impl, ustruct), the logging macro and the types every project uses (UObjectRef, RustealResult, OwnedStruct…).
• bindings, the crate Rusteal generates from your engine: one Rust type per engine class, struct and enum, grouped by engine module (bindings::engine, bindings::enhanced_input, bindings::ai…). bindings::prelude brings the common ones and the helper functions (bind_action, create_widget_of_class, FVector::from_dvec3…).

Engine names become Rust names in a fixed way. Classes lose their C++ prefix (AActor is Actor, UCharacterMovementComponent is CharacterMovementComponent); structs and enums keep it (FVector, ETriggerEvent); functions and properties are in snake_case (K2_GetActorLocation is k2_get_actor_location). A class’s functions come from a trait named after it with Ext at the end (ActorExt, CharacterMovementComponentExt), which you import with the class.

Optional parameters of engine functions, the ones with a default value in C++, are Options in Rust: Some(value) passes a value, None keeps the default.

Screenshots

Some steps are easier to follow with a picture of the editor. Where a picture belongs, the page has a placeholder like this one:

Screenshot: what the picture shows. (images/example.png)

The file name in parentheses is where the image goes, under src/images/.

Prerequisites

Rusteal needs three things on the machine: Unreal Engine 5.8, Rust 1.88 or newer, and the C++ toolchain the engine builds with. The versions below come from the engine’s own requirements.

Linux (x64)

The engine brings the rest: the clang toolchain the Unreal Build Tool compiles with and the .NET SDK that runs it.

Windows (x64)

Install Visual Studio before Rust: rustup uses its build tools for the MSVC toolchain.

Visual Studio workloads

In the Visual Studio Installer (Modify on an existing install), the Workloads tab needs two workloads:

Screenshot: the Workloads tab of the Visual Studio Installer with both workloads checked. (images/getting_started/vs_workloads.png)

Then, in the Individual components tab, check that these are selected:

• MSVC v143 x64/x86 build tools 14.44 for Visual Studio 2022, or MSVC x64/x86 build tools 14.50 for Visual Studio 2026. The engine refuses 14.39 to 14.43, 14.44 before 14.44.35211 and 14.50 before 14.50.35723;
• Windows 11 SDK 10.0.22621 (10.0.19041 at least);
• .NET Framework 4.6.2 targeting pack.

Screenshot: the Individual components tab with the MSVC build tools, the Windows SDK and the .NET Framework targeting pack selected. (images/getting_started/vs_components.png)

The Rust host

Rust must use the MSVC host. rustup show prints:

Default host: x86_64-pc-windows-msvc

If your default toolchain is a -windows-gnu one, for another project, it can stay. Set the default host and install the MSVC toolchain:

rustup set default-host x86_64-pc-windows-msvc
rustup toolchain install stable-x86_64-pc-windows-msvc

Then pin it in your game project with a rust-toolchain.toml, or for the directory that holds your projects:

rustup override set stable-x86_64-pc-windows-msvc --path <dir>

macOS

Rusteal has not been tested on macOS yet.

Installing the CLI

Everything you do with Rusteal goes through one command, rusteal. Install it from crates.io:

cargo install rusteal

The binary carries the Unreal plugins and the project templates inside it: there is nothing else to download.

Telling Rusteal where the engine is

The first command that needs the engine asks where it is installed:

Unreal Engine root (the directory with Engine/ and Templates/):

Answer with the directory that holds Engine/, for example the engine’s install directory from the Epic Games Launcher on Windows, or the directory you extracted or built the engine in on Linux. Rusteal checks that the directory has Engine/Build/BatchFiles and asks again if it does not.

The answer is saved in the CLI’s configuration file, ~/.config/rusteal/config.toml on Linux (the platform’s configuration directory elsewhere), under [engine].path. It is the only setting Rusteal keeps per machine: everything else lives in the project. To point Rusteal at another engine, edit that file.

Checking the version

rusteal --version

A project is tied to the Rusteal version that created it. See Versions and upgrades.

Your first project

The goal: a new Unreal project with a Rust actor that writes to the log when the game starts.

Creating the project

rusteal new MyGame --dir ~/Projects

rusteal new does everything a first build needs:

1. creates the Unreal project in ~/Projects/MyGame, from the engine’s Blank template;
2. installs the Rusteal plugins into its Plugins/;
3. writes the Rust workspace in Rust/, with your game crate and a HelloActor;
4. runs the whole build pipeline: it builds the project with the Unreal Build Tool, generates the Rust bindings for your engine, builds the game crate and deploys the library.

The first build takes a while: it compiles the engine module and generates bindings for the whole engine API. The builds after it only compile your crate.

rusteal new does not run git init, but it writes a .gitignore that covers Unreal’s and Cargo’s build output, so the right files are picked up when you do.

The Rust code

The game crate is in Rust/my-game/. Its src/lib.rs declares the library and its modules:

#![allow(unused)]
fn main() {
rusteal_runtime::entry!();

mod hello;
}

entry!() is required once per library: it is the function the Unreal plugin calls when it loads the library. Every other file is a normal Rust module.

src/hello.rs declares the actor:

#![allow(unused)]
fn main() {
use bindings::prelude::*;
use rusteal_runtime::{uclass, uclass_impl};

#[uclass(parent = Actor)]
pub struct HelloActor {}

#[uclass_impl]
impl HelloActor {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        log::info!("[MyGame] Hello from Rust");
    }
}
}

• #[uclass(parent = Actor)] makes HelloActor an Unreal class whose parent is AActor.
• #[uclass_impl] marks the block where its Unreal functions are.
• #[ufunction(Override)] on receive_begin_play implements the engine’s ReceiveBeginPlay event, the one a Blueprint’s Event BeginPlay node implements.
• log::info! writes to the Output Log (see Logging).

In the editor

1. Open MyGame.uproject.
2. In the main menu, open Window > Place Actors.
3. In the Place Actors panel, type HelloActor in the search box.
4. Drag HelloActor from the panel into the level viewport.
5. Press Play in the toolbar.
6. Open the Output Log tab (Window > Output Log if it is not open).

The log shows:

LogRusteal: [MyGame] Hello from Rust

Screenshot: the Place Actors panel with HelloActor found by the search, and the Output Log showing the message. (images/getting_started/hello_actor.png)

Changing the code

Change the message in hello.rs, then build the crate again:

cd ~/Projects/MyGame
rusteal build

The editor reloads the library as soon as the build deploys it, without a restart, and shows a notification. Press Play again to see the new message. The iteration loop explains what a reload changes, and how rusteal watch builds on every save.

The flags of rusteal new

Project layout

A Rusteal project is an Unreal project with a Cargo workspace inside it. Everything it needs lives in its directory; the only thing outside is the engine path in the CLI’s configuration.

MyGame/
├── MyGame.uproject
├── rusteal.toml                # Rusteal's project configuration
├── Source/MyGame/              # the C++ module the Unreal Build Tool needs
├── Content/                    # the project's assets
├── Config/                     # the project's ini files
├── Plugins/Rusteal/            # the runtime plugin and the generated C++ wrappers
├── Plugins/RustealGenerator/   # the plugin that exports the engine's reflection
├── Intermediate/Rusteal/uht/   # the exported reflection (build output)
└── Rust/
    ├── Cargo.toml              # the workspace
    ├── my-game/                # your game crate
    └── bindings/               # the generated bindings crate

What to version

Version everything except the build output, which the .gitignore written by rusteal new already leaves out. That includes Rust/bindings/ and the generated C++ wrappers in Plugins/Rusteal/: they are generated, but a clone of the project builds without generating them again.

The workspace

Rust/Cargo.toml lists the crates and pins the Rusteal crates to the version that created the project:

[workspace]
members = ["my-game", "bindings"]
resolver = "3"

[workspace.dependencies]
rusteal-runtime = "=x.y.z"
rusteal-core = "=x.y.z"
rusteal-ffi = "=x.y.z"
glam = "0.34"
log = "0.4"

It also holds the build profiles, which only a workspace’s Cargo.toml can set. See Development and release builds.

The game crate

Rust/my-game/Cargo.toml makes the crate a dynamic library and depends on the runtime and the bindings:

[package]
name = "my-game"
version = "0.1.0"
edition = "2024"
publish = false

[lib]
crate-type = ["cdylib"]

[dependencies]
rusteal-runtime = { workspace = true }
bindings = { path = "../bindings" }
glam = { workspace = true }
log = { workspace = true }

Add any crate from crates.io to [dependencies] as in any Rust project: serde, rand, rayon, a physics or a pathfinding library. They are compiled into your game’s library.

Your code goes in Rust/my-game/src/. lib.rs starts with #![deny(unsafe_code)], calls rusteal_runtime::entry!() once and declares the modules:

#![allow(unused)]
#![deny(unsafe_code)]

fn main() {
rusteal_runtime::entry!();

mod hello;
}

A game written with Rusteal never needs unsafe. Everything a game does, Rusteal’s API does in safe Rust, and the code its macros generate is accepted by #![deny(unsafe_code)]; the line makes the compiler refuse an unsafe that slips in, so keep it. If something seems to need unsafe, look for the safe call in this handbook; if there is none, it is a gap in Rusteal to report, not something to work around.

How you split the rest into modules is up to you; how you split the rest into modules is up to you. The templates keep each class in its own file, and the rules that do not touch the engine in a model.rs next to it, where cargo test can test them (see Testing without the engine).

The bindings crate

Rust/bindings/ is generated from the engine you build with, and only for the engine modules rusteal.toml lists. Do not edit it: the next generation overwrites it. To bind more of the engine (AI, Niagara, StateTree, Gameplay Tags…), see Binding more of the engine.

Where the library goes

rusteal build deploys the library to Plugins/Rusteal/Binaries/<Platform>/: librusteal.so on Linux, rusteal.dll on Windows. The plugin loads it from there when the editor or the game starts.

Starting from a template

The goal: a playable project in a genre, with its gameplay already written in Rust, to build your game on.

rusteal new MyGame --template third-person
rusteal new MyGame --template third-person --variant combat

A template is one of the engine’s templates with its gameplay written in Rust. The C++ classes are gone, the Rust crate in Rust/ takes their place, and their Blueprint children, with the same names, have Rust parents. The engine’s Blueprint-only templates (vr, ar, intro) keep their Blueprints, reparented to Rust classes and holding only data: meshes, materials, effects, input assets, widget layouts and Anim Blueprint graphs. Open the project and press Play: it plays like the engine’s template.

The engine’s templates come with variants, genre starting points that the C++ version puts all in one project. In Rusteal each variant is its own project: --variant picks one, and without it the project is the template alone. A variant project opens on the variant’s level.

Names are matched loosely (side-scrolling or SideScrolling), and rusteal new with an unknown template or variant lists them all, with the features any template can take (see Adding features).

Each template has a page of its own, linked from the table: how to play it, its Rust classes and its variants.

Reading a template

The templates are the largest body of Rusteal code there is, and the Gameplay recipes in this book are taken from them. In a template project:

• the Rust classes are in Rust/<crate>/src/, one per file, with a variant’s classes in a module named after it (src/combat/, src/shooter/);
• the tunable numbers and the rules that do not call the engine are in the model.rs files, with their tests;
• the Blueprint children that assign meshes, animations, input actions and widgets are in Content/, under the same names as in the engine’s template (BP_ThirdPersonCharacter, BP_ThirdPersonPlayerController…).

To see where a Rust class is used, open its Blueprint child in the editor: Class Settings shows the Rust class as the Parent Class, and the Details panel shows the properties the Rust class declares.

Screenshot: BP_ThirdPersonCharacter open in the Blueprint editor, with Class Settings showing ThirdPersonCharacter as the Parent Class. (images/getting_started/bp_parent_class.png)

blank

The engine’s Blank template and one Rust class, HelloActor, to see the whole loop work before anything else. It is the default: rusteal new MyGame makes it.

rusteal new MyGame --template blank

From TP_Blank, the engine template it is made of.

Playing it

Open <Name>.uproject, drag a HelloActor from the Place Actors panel into the level and press Play: the Output Log shows [<Name>] Hello from Rust.

Screenshot: the blank template’s HelloActor message in the Output Log. (images/templates/blank.png)

Its classes

The class is in Rust/<crate>/src/hello.rs, the place to start writing your own.

first-person

The engine’s First Person template, playable as it comes with keyboard and mouse, gamepad or touch: its character with first person arms and camera, camera manager, game mode and player controller are Rust classes, and their Blueprint children keep the meshes, animations and input assets.

rusteal new MyGame --template first-person

From TP_FirstPerson, the engine template it is made of.

Playing it

Open the project and press Play: WASD / left stick move, mouse / right stick look, Space / A jump.

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

Variants

Each variant is a project of its own: the template plus the variant, opening on the variant’s level.

horror

A dark level explored with a flashlight, and a sprint that runs on stamina, its meter on screen.

rusteal new MyGame --template first-person --variant horror

It opens /Game/Variant_Horror/Lvl_Horror. To play: WASD / left stick move, mouse / right stick look, Space / A jump, hold Shift / LB sprint.

Its own classes, next to the template’s, in a module named after it:

shooter

An arena shooter: weapon pickups described by a data table, projectiles and grenades, team scores, and NPCs run by a StateTree that sense their enemies, snipe and shoot.

rusteal new MyGame --template first-person --variant shooter

It opens /Game/Variant_Shooter/Lvl_Shooter. To play: WASD / left stick move, mouse / right stick look, Space / A jump, left click / RT shoot, Left Shift / Y switch weapons.

Its own classes, next to the template’s, in a module named after it:

Recipes taken from it: Character movement and input, Cameras, Projectiles and weapons.

third-person

The engine’s Third Person template, playable as it comes with keyboard and mouse, gamepad or touch: its character with its spring arm camera, game mode and player controller are Rust classes.

rusteal new MyGame --template third-person

From TP_ThirdPerson, the engine template it is made of.

Playing it

Open the project and press Play: WASD / left stick move, mouse / right stick look, Space / A jump.

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

Variants

Each variant is a project of its own: the template plus the variant, opening on the variant’s level.

combat

Melee combat: combo and charged attacks driven by animation notifies, enemies run by a StateTree, enemy spawners, checkpoints and respawn, damageable props and a lava floor.

rusteal new MyGame --template third-person --variant combat

It opens /Game/Variant_Combat/Lvl_Combat. To play: WASD / left stick move, mouse / right stick look, left click / RB combo attack, hold right click / RT charged attack, R / D-pad down switch the camera side.

Its own classes, next to the template’s, in a module named after it:

platforming

Double jump, wall jump, coyote time, a dash, local multiplayer and respawn.

rusteal new MyGame --template third-person --variant platforming

It opens /Game/Variant_Platforming/Lvl_Platforming. To play: WASD / left stick move, mouse / right stick look, Space / A jump (again in the air: double jump, against a wall: wall jump), Shift / B dash.

Its own classes, next to the template’s, in a module named after it:

side-scrolling

A side view platformer: soft platforms to drop through, jump pads, moving platforms, pickups with a counter, interactables and an NPC run by a StateTree.

rusteal new MyGame --template third-person --variant side-scrolling

It opens /Game/Variant_SideScrolling/Lvl_SideScrolling. To play: A/D / left stick move, Space / A jump (again in the air: double jump, against a wall: wall jump), S / stick down + Space drop through a platform, F / X interact.

Its own classes, next to the template’s, in a module named after it:

Recipes taken from it: Character movement and input, Health, damage and death, Platforming, AI.

top-down

The engine’s Top Down template, point and click with the mouse or touch: its character, game mode and player controller are Rust classes. The engine’s own version is Blueprint-only at its base; here its Blueprints are children of the Rust classes.

rusteal new MyGame --template top-down

From TP_TopDown, the engine template it is made of.

Playing it

Open the project and press Play: click (or hold) / tap where the character should go.

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

Variants

Each variant is a project of its own: the template plus the variant, opening on the variant’s level.

strategy

A real-time strategy start: units selected with clicks, boxes and touches, sent along the navigation mesh by EnvQueries, and interacting with the units they reach.

rusteal new MyGame --template top-down --variant strategy

It opens /Game/Variant_Strategy/LVL_Strategy. To play: left click / drag selects units (Shift adds, double click selects all), right click sends them, WASD / right drag pans, wheel / Q E zoom.

Its own classes, next to the template’s, in a module named after it:

twin-stick

A twin stick shooter: projectiles, dashes and area attacks against waves of enemies run by a StateTree, pickups and a combo score.

rusteal new MyGame --template top-down --variant twin-stick

It opens /Game/Variant_TwinStick/LVL_TwinStick. To play: WASD / left stick move, mouse / right stick aim, left click / RT shoot, Left Shift / LB dash, right click / LT area attack.

Its own classes, next to the template’s, in a module named after it:

Recipes taken from it: Point and click, AI, Projectiles and weapons.

vehicle

The engine’s Vehicle template on Chaos Vehicles: a sports car and an offroad car, with their wheels, the game mode, the player controller and the speed and gear HUD in Rust. It plays with keyboard, gamepad, steering wheel or touch.

rusteal new MyGame --template vehicle

From TP_VehicleAdv, the engine template it is made of.

Playing it

Open the project and press Play: W / right trigger throttle, S / left trigger brake and reverse, A D / left stick steer, Space / left shoulder handbrake, mouse / right stick look around, Tab toggles the camera, Backspace resets the car.

Screenshot: the vehicle template’s sports car on the track. (images/templates/vehicle.png)

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

Variants

Each variant is a project of its own: the template plus the variant, opening on the variant’s level.

offroad

The offroad car on an offroad level, its game mode ready for local split screen players.

rusteal new MyGame --template vehicle --variant offroad

It opens /Game/Variant_OffRoad/Maps/Lvl_Offroad. To play: W / right trigger throttle, S / left trigger brake and reverse, A D / left stick steer, Space / left shoulder handbrake, mouse / right stick look around, Tab toggles the camera, Backspace resets the car.

Screenshot: the vehicle template’s offroad variant in play. (images/templates/vehicle-offroad.png)

Its own classes, next to the template’s, in a module named after it:

time-trial

A race track with a start countdown, gates to pass in order, laps and the best lap time.

rusteal new MyGame --template vehicle --variant time-trial

It opens /Game/Variant_TimeTrial/Maps/Lvl_Timetrial. To play: W / right trigger throttle, S / left trigger brake and reverse, A D / left stick steer, Space / left shoulder handbrake, mouse / right stick look around, Tab toggles the camera, Backspace resets the car.

Screenshot: the vehicle template’s time-trial variant in play. (images/templates/vehicle-time-trial.png)

Its own classes, next to the template’s, in a module named after it:

Recipes taken from it: Vehicles.

intro

The engine’s Intro To Unreal template: a guided tour level whose stations show the editor and the engine at work. The stations are the four features any template can take, mannequin, checkpoints, interactables and tour, which rusteal new adds by itself; the level’s Blueprints are children of their Rust classes. The first person character is the first-person template’s, with IntroGameMode as the level’s game mode; the checkpoints’ subsystem brings the player back to the last spawn point.

rusteal new MyGame --template intro

From TP_UEIntro_BP, the engine template it is made of.

Playing it

Open the project and press Play: WASD / left stick move, mouse / right stick look, Space / A jump; follow the tour from the first station.

Screenshot: the intro template’s tour level, at its first station. (images/templates/intro.png)

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

ar

The engine’s Handheld AR template on ARCore and ARKit: its pawn reads touch gestures to pick a detected plane, place the object on it, then move, rotate and scale it, and applies the light estimation; the plane and placeable actors and the styled menus are Rust classes. It runs in the editor; Rusteal does not build for Android or iOS yet (see Known limits).

rusteal new MyGame --template ar

From TP_HandheldARBP, the engine template it is made of.

Playing it

Open the project and press Play: tap Begin Scan, tap a plane, tap it again to place the object, drag with one finger to move it, twist or pinch with two to rotate or scale it.

Screenshot: the ar template’s start menu in the editor. (images/templates/ar.png)

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

vr

The engine’s Virtual Reality template on OpenXR: its pawn teleports along the navigation mesh, snap turns and poses the hands; grabbable objects, a pistol and its projectiles, a 3D menu, passthrough and a spectator camera are Rust classes. Play it with Play > VR Preview and an OpenXR headset.

rusteal new MyGame --template vr

From TP_VirtualRealityBP, the engine template it is made of.

Playing it

Open the project and press Play: right thumbstick forward aims a teleport, left thumbstick snaps the view, grips grab, triggers shoot the pistol, the menu button opens the menu.

Screenshot: the vr template’s hands and teleport arc in VR Preview. (images/templates/vr.png)

Its classes

The Rust classes are in Rust/<crate>/src/; their Blueprint children, under the engine template’s names, are in Content/.

Adding features

A feature is a piece of gameplay any template can take: a Rusteal plugin with its Rust classes, and the engine content they need. --feature adds it when the project is created, as many times as wanted:

rusteal new MyGame --template third-person --feature mannequin

Each feature becomes a plugin in Plugins/<Plugin>/, enabled in the .uproject and built with the project: its Rust classes are in Plugins/<Plugin>/Rust/, and rusteal build builds them with the game’s. When the project lacks the engine content the feature uses, it is copied in: mannequin brings the Characters pack (Content/Characters/Mannequins), which the third person and first person templates already have, and interactables and tour the LevelPrototyping pack. Each feature’s Blueprints are in its plugin’s content: in the Content Browser, click Settings and check Show Plugin Content, then open the plugin’s folder, Plugins > Mannequin Content for the mannequin feature.

The intro template is made of all four: rusteal new MyTour --template intro adds them by itself, and the Blueprints of its tour level are children of their Rust classes.

An existing project takes a feature as a plugin:

rusteal plugin new Mannequin --template mannequin

A feature whose plugin carries assets keeps its plugin name, since its assets live under /<Plugin>/.

Features that add files

Some features add files to the project instead of a plugin: the setup of a tool around it.

mannequin

Mannequins that move like a character: CopycatAnimInstance is a parent for Animation Blueprints that copies a character’s movement (ground speed, direction, moving, falling), the player’s unless told which, and BP_CopycatMannequin is the Intro To Unreal template’s mannequin that walks, runs and jumps with the player. ReachingMannequin reaches for a ReachTarget placed in the level with its right hand, a two-bone IK solved in Rust.

rusteal new MyGame --template third-person --feature mannequin
rusteal plugin new Mannequin --template mannequin   # in an existing project

It becomes the Mannequin plugin, in Plugins/Mannequin/. It brings the engine’s Characters pack (Content/Characters/Mannequins) when the project lacks it; the third person and first person templates already have it.

Trying it

Place a BP_CopycatMannequin, and a ReachingMannequin with a ReachTarget as its Target (Plugins > Mannequin Content, Place Actors), then press Play.

Screenshot: the mannequin feature in play. (images/features/mannequin.png)

Its classes

The Rust classes are in Plugins/Mannequin/Rust/mannequin/src/:

Its Blueprints, ABP_Copycat and BP_CopycatMannequin, children of those classes holding the meshes, materials and widget layouts, are in the plugin’s content: in the Content Browser, click Settings and check Show Plugin Content, then open Plugins > Mannequin Content.

A mannequin that copies the player

1. Create a project with --feature mannequin, or add the plugin to an existing one.
2. In the Content Browser, right-click and choose Animation > Animation Blueprint; pick the SK_Mannequin skeleton and, as the Parent Class, CopycatAnimInstance.
3. Open it. In the My Blueprint panel, click the gear icon and check Show Inherited Variables: Ground Speed, Direction, Should Move, Is Falling, Velocity and Character appear under Copycat.
4. In its AnimGraph, blend the idle, walk and run animations by Ground Speed and Direction, and switch to a jump loop when Is Falling is set.
5. Drag SKM_Manny_Simple from Content/Characters/Mannequins/Meshes into the level.
6. In its Details panel, set Animation Mode to Use Animation Blueprint.
7. Set Anim Class to the new Animation Blueprint.
8. Press Play and walk: the mannequin walks, runs and jumps with you.

Screenshot: a copycat mannequin running beside the player in the third person level. (images/getting_started/feature_copycat.png)

The copying is plain Rust in Plugins/Mannequin/Rust/mannequin/src/copycat.rs: the speed ignores the vertical axis, the mannequin moves only when the speed is above 0.01 and the character accelerates, and the direction is kept within 45 degrees when the character turns toward its movement.

Recipes that use it: Animation.

checkpoints

Spawn points that save the player’s progress: walking past a BP_SpawnPoint writes it to a save (CheckpointSaveData), and a world subsystem, CheckpointSubsystem, brings the player back to the last one when the level starts, or when RespawnPlayer is called.

rusteal new MyGame --template third-person --feature checkpoints
rusteal plugin new Checkpoints --template checkpoints   # in an existing project

It becomes the Checkpoints plugin, in Plugins/Checkpoints/. It needs no engine content of its own.

Trying it

Place BP_SpawnPoint actors (Plugins > Checkpoints Content) along the level, press Play, walk past one, stop and play again: you start there.

Screenshot: the checkpoints feature in play. (images/features/checkpoints.png)

Its classes

The Rust classes are in Plugins/Checkpoints/Rust/checkpoints/src/:

Its Blueprint, BP_SpawnPoint, a child of those classes holding the meshes and materials, is in the plugin’s content: in the Content Browser, click Settings and check Show Plugin Content, then open Plugins > Checkpoints Content.

Recipes that use it: Saving the game.

interactables

A trigger and what it drives: BP_DoorTrigger is a switch that broadcasts its Trigger event, which toggles BP_Lights and unlocks a BP_DoorFrame_Unlockable. Around them: BP_ConfettiTrigger, a Niagara burst; BP_SequenceTrigger, which plays a level sequence; BP_Metasound, a MetaSound with a seed parameter; BP_DangleBlocks, cubes hanging from physics constraints.

rusteal new MyGame --template third-person --feature interactables
rusteal plugin new Interactables --template interactables   # in an existing project

It becomes the Interactables plugin, in Plugins/Interactables/. It brings the engine’s LevelPrototyping pack (door meshes, cubes) when the project lacks it.

Trying it

Place a BP_DoorTrigger and a BP_DoorFrame_Unlockable (Plugins > Interactables Content), set the door’s Trigger to the trigger, press Play and step on it.

Screenshot: the interactables feature in play. (images/features/interactables.png)

Its classes

The Rust classes are in Plugins/Interactables/Rust/interactables/src/:

Its Blueprints, BP_ConfettiTrigger, BP_DangleBlocks, BP_DoorFrame_Unlockable, BP_DoorTrigger, BP_Light, BP_Metasound and BP_SequenceTrigger, children of those classes holding the meshes, materials and widget layouts, are in the plugin’s content: in the Content Browser, click Settings and check Show Plugin Content, then open Plugins > Interactables Content.

Recipes that use it: Game flow, Physics, Effects and sound.

tour

The pieces of the Intro To Unreal tour: BP_TextSwitcher, text that changes in game; BP_Titles, the station numbers; animated BP_KeyboardKeys and BP_MouseKeys; BP_GizmoDemo, the move, rotate and scale gizmos at work; BP_TemplateCube; BP_SplinePath, decal arrows along a spline; and BP_UI_Update, editor panels shown in game.

rusteal new MyGame --template third-person --feature tour
rusteal plugin new Tour --template tour   # in an existing project

It becomes the Tour plugin, in Plugins/Tour/. It brings the engine’s LevelPrototyping pack when the project lacks it.

Trying it

Place a BP_KeyboardKey (Plugins > Tour Content), set its Key, and a BP_GizmoDemo with a Selection, then press Play.

Screenshot: the tour feature in play. (images/features/tour.png)

Its classes

The Rust classes are in Plugins/Tour/Rust/tour/src/:

Its Blueprints, BP_GizmoDemo, BP_KeyboardKey, BP_MouseKey, BP_SplinePath, BP_TemplateCube, BP_TextSwitcher, BP_Titles and BP_UI_Update, children of those classes holding the meshes, materials and widget layouts, are in the plugin’s content: in the Content Browser, click Settings and check Show Plugin Content, then open Plugins > Tour Content.

Recipes that use it: UI.

rustrover

The goal: a new project that opens in RustRover with its run configurations ready, the same on Linux and Windows.

rustrover is a feature that adds files to the project instead of a plugin: two RustRover run configurations, stored as project files in Rust/.run/:

rusteal new MyGame --template third-person --feature rustrover

1. In RustRover, choose File > Open and open the project’s Rust folder.
2. Pick Rusteal Watch or Rusteal Test in the run configurations next to the Run button, and click Run.

They are files of the project, so they go into version control with it and the rest of the team gets them too.

Screenshot: RustRover’s run configurations list with Rusteal Watch and Rusteal Test. (images/getting_started/rustrover_features.png)

Adding Rusteal to an existing project

The goal: Rust gameplay in a project that already exists, made from the editor or with C++.

rusteal setup /path/to/YourProject

rusteal setup installs the Rusteal plugins into the project’s Plugins/ and writes a starter rusteal.toml. If the project already has a rusteal.toml, it keeps it.

It does not write the Rust workspace. Create it as rusteal new does (see Project layout):

1. Rust/Cargo.toml, the workspace, listing your crate and bindings, and pinning the Rusteal crates to the CLI’s version (rusteal --version);
2. Rust/<crate>/Cargo.toml, a cdylib depending on rusteal-runtime, bindings and glam;
3. Rust/<crate>/src/lib.rs, with rusteal_runtime::entry!();;
4. in rusteal.toml, [project] crate = "<crate>", the package name of your crate.

The quickest way is to create a blank project with rusteal new next to it and copy its Rust/ directory and the profiles of its Rust/Cargo.toml.

Then build everything once:

cd /path/to/YourProject
rusteal build --all

The project needs a C++ module (Source/<Project>/) for the Unreal Build Tool to build it. A project made from the editor’s Blueprint templates has none: add one from the editor (Tools > New C++ Class, any class) before running the build.

Your existing C++ and Blueprint classes stay as they are, and work next to the Rust ones: Blueprints derive from Rust classes, call their functions and bind their delegates the way they do with C++ classes.

Versions and upgrades

A project is tied to one Rusteal version: Rust/Cargo.toml pins rusteal-runtime, rusteal-core and rusteal-ffi to it ("=x.y.z"), and the plugins in Plugins/ carry it.

Before doing anything, rusteal build, rusteal generate and rusteal setup compare it with the CLI’s own version:

• The CLI is newer. Upgrade the project:

  rusteal upgrade
  

  It moves the pins, replaces Plugins/Rusteal and Plugins/RustealGenerator with the CLI’s, and runs a full build.

• The project is newer. Install the CLI version the project uses:

  cargo install rusteal@x.y.z
  

The plugin checks the library as well: a library built against another Rusteal version is refused when it loads, and the Output Log shows both versions.

Before upgrading

Rusteal is in early development, and its API changes between versions. Commit your project before running rusteal upgrade, so the changes it makes, and the compile errors your code may get from a changed API, can be reviewed in a diff.

Changing the engine version

The bindings are generated from the engine you build with. After installing another engine version, point the CLI at it (see Installing the CLI) and regenerate everything:

rusteal build --all

The rusteal CLI

Every Rusteal task is a rusteal command. Commands that act on a project take its directory as an argument, or find it by walking up from the current directory, so inside a project you can leave the path out.

rusteal help <command> and rusteal <command> --help list the flags of each command.

A day with the CLI

A typical session, once the project exists:

cd ~/Projects/MyGame
rusteal watch

Open the editor, change Rust code, save: rusteal watch builds, the editor reloads the library, and you press Play. When you change rusteal.toml or the engine version, stop the watch and run rusteal build --all once. When the game is ready to be tried outside the editor, run rusteal package.

Use case: running the CLI from the IDE

The goal: start rusteal watch from the IDE, with one run configuration that works on Linux and on Windows.

Every command is also a Cargo subcommand: cargo rusteal watch is rusteal watch (cargo install rusteal installs both). In RustRover:

1. Open Run > Edit Configurations….
2. Click + and choose Cargo.
3. Name it rusteal watch, and set Command to rusteal watch.
4. Set Working directory to the project’s Rust directory: the command finds the project by walking up from it.
5. Tick Store as project file to share it with the rest of the team, then click OK.

Screenshot: RustRover’s Run/Debug Configurations with a Cargo configuration whose command is rusteal watch. (images/cli/rustrover_watch.png)

Building

A Rusteal build has five steps:

Which build to run

rusteal build runs steps 4 and 5: that is all a change to Rust code needs, and it takes seconds. rusteal build --all runs the five, and takes as long as the engine build and the bindings generation take.

Flags

rusteal build
rusteal build --all
rusteal build --from 2
rusteal build --step 3
rusteal build --release
rusteal build --plugin Inventory
rusteal build /path/to/MyGame

--all cannot be combined with --from or --step.

Generating the bindings alone

rusteal generate

Regenerates the bindings crate and the C++ wrappers from the reflection already exported, without building anything.

When the build fails

The build prints the output of the tool that failed: Cargo’s errors for your code, the Unreal Build Tool’s for the engine steps. A Rust compile error leaves the library the editor runs as it was: fix the code and build again.

The Unreal Build Tool runs one build at a time per engine. If another build is running, from the editor or from another project, wait for it to finish.

If rusteal build says the bindings are missing, the project has never been built on this machine, or Rust/bindings/ was deleted: run rusteal build --all.

Binding more of the engine

The goal: use an engine module the project does not bind yet, such as AI, Niagara, StateTree or Gameplay Tags.

The bindings crate only has the engine modules rusteal.toml asks for. A new project binds the core of the engine, input, UMG and Enhanced Input. The other modules are listed in rusteal.toml, each behind a feature, and a feature is turned on by adding it to features.

The file

[project]
crate = "my-game"

[codegen]
features = ["core", "engine", "input", "slate", "umg", "enhanced-input"]

[codegen.modules]
CoreUObject = { module = "core_ue", feature = "core" }
Engine = { module = "engine", feature = "engine" }
AIModule = { module = "ai", feature = "ai" }
GameplayTasks = { module = "gameplay_tasks", feature = "ai" }
NavigationSystem = { module = "navigation", feature = "ai" }
StateTreeModule = { module = "state_tree", feature = "state-tree", plugin = "StateTree" }
GameplayStateTreeModule = { module = "gameplay_state_tree", feature = "state-tree", plugin = "GameplayStateTree" }
Niagara = { module = "niagara", feature = "niagara", plugin = "Niagara" }

Turning a module on

1. Add the feature to features:

   features = ["core", "engine", "input", "slate", "umg", "enhanced-input", "ai", "state-tree"]
   

2. Run the whole pipeline:

   rusteal build --all
   

3. Use the module from bindings:

   #![allow(unused)]
   fn main() {
   use bindings::ai::{AIController, AIControllerExt};
   use bindings::navigation::NavigationSystemV1;
   }

When a module comes from an engine plugin (plugin = "StateTree"), the build enables that plugin for Rusteal, so the engine loads it with your game.

The modules a new project lists

engine needs input, slate and umg, because the Rusteal plugin links them: keep them in the list.

Binding another module

Any reflected engine module can be added to [codegen.modules] the same way, with a feature of your choice:

DeveloperSettings = { module = "developer_settings", feature = "engine" }

The blocklist

A few engine functions are reflected but not exported by the engine, so their wrapper compiles but does not link. The blocklist a new project gets already lists the ones known for the engine version Rusteal targets. If a rusteal build --all fails at link time on a wrapper of a new module, add the function to [codegen.blocklist] functions as "Class.Function" and build again.

Bigger bindings, longer builds

Every module added makes the bindings crate larger, and its first build longer. The bindings are compiled once and kept, so a change to your own code does not rebuild them. Bind what the game uses.

Development and release builds

The game library is built with Cargo’s dev profile by default, and with the release profile when --release is given. The two want opposite things, and the projects Rusteal creates set them up for that in Rust/Cargo.toml, the only place Cargo reads profiles from (in the game crate’s own Cargo.toml they are ignored with a warning).

dev: iterating

rusteal build

Rebuilding after a change must be fast, and the game must still run well in the editor:

• your game crate, the one that changes, is barely optimized, so it compiles in about a second;
• the Rusteal crates and the generated bindings, which compile once, are fully optimized;
• your crate has full debug info, for the debugger; the dependencies and the bindings keep only file and line, enough for backtraces, so the library stays small enough to reload quickly.

release: shipping

rusteal build --release

The fastest library possible, however long it takes to build: one codegen unit per crate and link-time optimization across crates, which also drops the parts of the bindings the game does not use. rusteal package always builds this profile.

Tuning

The profiles are yours to change, in Rust/Cargo.toml. The optimization levels follow Bevy’s recommendations for game projects:

[profile.dev]
opt-level = 1

[profile.dev.package."*"]
opt-level = 3
debug = "line-tables-only"

[profile.dev.package.bindings]
opt-level = 3
debug = "line-tables-only"

[profile.release]
codegen-units = 1
lto = "thin"

Every crates.io dependency you add is covered by "*": optimized, with file and line only. To step into one of them in the debugger, give it full debug info alone:

[profile.dev.package.rapier3d]
debug = true

Keep the bindings at line-tables-only: with full debug info, the library grows past a hundred megabytes, and every hot reload loads it again.

Platform optimizations

The goal: engine settings that one platform needs, applied on that platform only, on every machine you work on and in the game you ship, without you having to remember them.

Some engine settings fix or tune one platform and have no business on the others. Rusteal keeps them in rusteal.toml, per platform, and writes them into the engine’s own per-platform config files for you.

What every project gets

The templates ship one Linux setting:

[optimizations.linux.Engine.ConsoleVariables]
"r.Vulkan.CpuWaitForFence" = 0

On Linux the engine renders with Vulkan. Whenever the swapchain goes out of date (a window is resized or closed, PIE stops, the game switches to fullscreen, alt-tab), the engine recreates it and, by default, waits for the next image with a CPU fence. NVIDIA’s Linux driver can crash inside vkWaitForFences right then: the editor closes with a segfault in the driver a second or two after AcquireNextImage() failed due to the outdated swapchain in the log. With 0, the wait is done on the GPU with a semaphore, which never calls the crashing function. It costs nothing measurable, and Epic ships the same value on Android.

The crash is not the editor’s alone: a packaged game runs the same Vulkan code, so a player on Linux with an NVIDIA card can hit it when resizing or alt-tabbing. That is why the setting ships with the game too. On Windows the engine uses DirectX 12, and the setting is never written there.

Where it goes

The table’s path names the platform, the config file and its section: [optimizations.<platform>.<File>.<Section>]. The platforms are linux, windows and mac. Rusteal writes the table of the platform it runs on into Config/<Platform>/<Platform><File>.ini of your project, here Config/Linux/LinuxEngine.ini, between two comment lines of its own:

; Rusteal optimizations, written by rusteal from rusteal.toml [optimizations]: begin
[ConsoleVariables]
r.Vulkan.CpuWaitForFence=0
; Rusteal optimizations: end

That file is the engine’s: it reads it on Linux only, for the editor and for the packaged game alike. Rusteal only rewrites what is between its two lines:

• what you write elsewhere in the file stays as it is;
• a key you set yourself in that file, outside the Rusteal lines, keeps your value, and Rusteal leaves it out of its block.

Commit the file with the project: every Linux machine writes the same block, so it does not change from one developer to the next.

While you develop

rusteal watch

rusteal new writes the optimizations into the new project, and rusteal watch writes them again each time it starts. You may work on several machines, Linux and Windows, or a teammate on another one: whoever starts rusteal watch on Linux has the settings, and nobody has to copy anything. The Rusteal CLI built for Windows has no Linux settings in it at all; it is compiled per platform.

The editor reads config files when it starts: after the first rusteal watch of a new setting, restart the editor once. Check that it took in Saved/Logs/<Project>.log:

LogConfig: Set CVar [[r.Vulkan.CpuWaitForFence:0]]

To work without them, for instance to see whether a problem comes from one of them:

rusteal watch --optimizations off

That removes the block, and the file too if Rusteal had created it; the next rusteal watch writes it back. --optimizations 0 is the same. Do not commit the file in that state.

When you ship

rusteal package --shipping

rusteal package writes the optimizations of the platform it packages for, so the game carries them, then puts the project’s config files back exactly as they were before the package. Packaging on Windows for Windows, nothing of Linux goes in: the engine stages Config/Linux for Linux builds only, and the Windows CLI does not write it anyway.

To ship a game without them:

rusteal package --shipping --optimizations off

Your own

Add keys and tables to rusteal.toml, in the same shape. If the Vulkan crash still showed up, the next console variable to try is the one that recreates the swapchain from scratch instead of reusing the old one:

[optimizations.linux.Engine.ConsoleVariables]
"r.Vulkan.CpuWaitForFence" = 0
"r.Vulkan.KeepSwapChain" = 0

Any config file and section works: [optimizations.windows.Game.<Section>] goes into Config/Windows/WindowsGame.ini, [optimizations.mac.Engine.<Section>] into Config/Mac/MacEngine.ini. Keys with dots, and section names with dots or slashes such as "/Script/Engine.RendererSettings", go in quotes. Values are strings, numbers or booleans (true is written True). The next rusteal watch or rusteal package writes them; removing a line from rusteal.toml removes it from the .ini the same way.

• A project with no [optimizations] table, one made before Rusteal had them, gets the defaults above.
• An empty table turns them all off for good:

[optimizations]

In the engine itself

Some crashes happen before any project is open: the Project Browser runs the same Vulkan code, and a project’s config does not apply there. For those, the setting can go into the engine install, in the [ConsoleVariables] section that Engine/Config/Linux/LinuxEngine.ini already has:

[ConsoleVariables]
; larger timeout since drivers may take longer time
g.TimeoutForBlockOnRenderFence=60000
memory.MemoryPressureCriticalThresholdPercent=10
; Use semaphores instead of fences for swapchain image wait (avoids NVIDIA driver crash in vkWaitForFences after an out-of-date swapchain)
r.Vulkan.CpuWaitForFence=0

Know what that means before doing it:

The project’s file is the one that travels with the game: keep it even when the engine has the line. Use Engine/Config/ConsoleVariables.ini only for the editor’s own debugging settings; its [Startup] section is ignored by Shipping builds, so a fix that the game needs does not belong there.

Hot reload

The goal: change Rust code and see it in the running editor, without restarting it.

rusteal build

When the build deploys the library, the editor reloads it on its own, and a notification says so. Press Play and the new code runs. Nothing else is needed: no button in the editor, no restart.

Screenshot: the editor notification shown after a reload. (images/iteration/reload_notification.png)

What a reload keeps and what it changes

When a class is created again, every object of it moves to the new class: the actors placed in the level, the Blueprint children of the class, and the Rust classes that derive from it. Their property values are kept.

Blueprints that use a changed class

A Blueprint that calls a function you removed, or reads a property you removed, gets a compile error on that node after the reload, as it would after the same change to a C++ class. Open the Blueprint, and either fix the node or put the function back and build again: the error clears.

Screenshot: a Blueprint graph with a node in error after its Rust function was removed. (images/iteration/blueprint_node_error.png)

Rust-only fields start over

A field with no attribute is Rust’s alone, kept outside the Unreal object, and a reload drops it. Keep what must survive a reload in #[uproperty] fields: they live in the object’s memory, and the reload keeps them. A Rust-only field is for state that can be rebuilt (a cache, a path, a timer you set again in receive_begin_play).

When a restart is needed

• A changed #[ustruct]: the editor keeps the old struct until it restarts.
• A change to rusteal.toml, or a new engine version: run rusteal build --all, then restart the editor.
• A new Rusteal version after rusteal upgrade: restart the editor.
• Outside the editor (a game started with -game), a changed class or interface cannot be replaced: it keeps its old shape, and the log asks for a restart. Function bodies still update.

Reloading by hand

The editor also reloads on request, from its console. See Console commands.

A reload during Play

The safest moment to reload is between Play sessions. A reload during Play drops the Rust-only fields of the objects in the game, and moves the objects of a class that is created again to the new class in the middle of the game.

How long it takes

A reload that only changes code takes a few milliseconds. A reload that creates classes again takes longer, around a tenth of a second for a few classes, which is the engine moving the objects to the new classes. The Output Log ends each reload with how long it took.

rusteal watch

The goal: save a Rust file and have the change in the editor, with nothing else to run.

cd ~/Projects/MyGame
rusteal watch

rusteal watch builds the Rust libraries every time a source file changes, the same build as rusteal build. With the editor reloading each library when it is deployed, saving is the whole loop: save, build, deploy, reload.

rusteal watch: watching
  /home/me/Projects/MyGame/Rust
Each change builds and deploys the libraries (rusteal build); Ctrl+C stops.

Leave it running in a terminal next to the editor. Ctrl+C stops it.

What it watches

The .rs and .toml files of the project’s Rust workspace, and of each Rust plugin’s workspace. It does not watch target/ or the generated bindings/.

It waits until the files have settled before building, so saving several files at once, or a formatter rewriting them, makes one build.

When the build fails

The build’s errors are printed, and the watch goes on:

rusteal watch: the build failed (above), waiting for changes

The editor keeps running the last library that built. Fix the error and save: the next build deploys and reloads.

One plugin

rusteal watch --plugin Inventory

Watches and builds only that plugin’s library, which is what working on a plugin needs.

What it does not do

rusteal watch runs steps 4 and 5 of the build. A change to rusteal.toml or to the engine version needs rusteal build --all: stop the watch, run it, and start the watch again.

Console commands

Rusteal adds two commands to the editor’s console.

Opening the console

Either of these works:

• press the ` key (the one under Esc) with the mouse over the level viewport;
• type in the Cmd box at the bottom of the Output Log tab.

Screenshot: the Cmd box at the bottom of the Output Log tab with Rusteal.Reload typed in. (images/iteration/output_log_cmd.png)

The commands

Use case: reloading when you choose

The goal: build several times without the editor reloading after each build, for example while a Play session must not be interrupted.

1. In the console, run Rusteal.AutoReload 0.
2. Build as many times as you want with rusteal build.
3. When you are ready, run Rusteal.Reload.
4. Run Rusteal.AutoReload 1 to go back to reloading on every build.

Use case: reloading one plugin

The goal: reload a plugin’s library and leave the game’s alone.

Rusteal.Reload Inventory

Your own commands

A game can add its own console commands and variables from Rust. See Console commands and variables.

Logging

The goal: print messages from Rust code to the Output Log.

#![allow(unused)]
fn main() {
log::info!("[MyGame] wave {wave} started");
log::warn!("[MyGame] no spawn points in the level");
log::error!("[MyGame] could not load the save: {e}");
}

Rusteal logs through the log crate, the logging facade of the Rust ecosystem: the projects Rusteal creates depend on it (log = { workspace = true } in the game crate), and the library routes it to the Output Log when it loads. Its messages go under the LogRusteal category, with the level’s color: plain for info!, yellow for warn!, red for error!.

LogRusteal: [MyGame] wave 3 started
LogRusteal: Warning: [MyGame] no spawn points in the level

debug! and trace! are off by default. Turn them on, for the whole library, where it starts:

#![allow(unused)]
fn main() {
fn verbose_logs() {
    log::set_max_level(log::LevelFilter::Debug);
}

rusteal_runtime::on_load!(verbose_logs);
}

They show at the display level, like info!. The crates your game depends on that log through log (most do) show in the Output Log the same way.

A project made before Rusteal routed log has no log dependency: add log = "0.4" to [workspace.dependencies] in Rust/Cargo.toml and log = { workspace = true } to the game crate’s [dependencies]. Its ulog! calls keep working.

Filtering

In the Output Log tab, Filters > Categories can show LogRusteal alone. A prefix of your own at the start of each message ([MyGame], [Inventory]) makes them easy to find with the search box as well.

Screenshot: the Output Log filtered to the LogRusteal category. (images/iteration/output_log_filter.png)

Errors that reach the log by themselves

Some failures are logged without any code of yours:

• A panic in your code is caught where the engine called into Rust, and logged as an error. The editor keeps running; the function that panicked stops there.
• A function bound by name (an input action, a delegate, a timer) that does not exist is logged with its name.
• A library built against another Rusteal version is refused, with both versions in the log.

Logging a RustealResult

Engine calls that can fail return a RustealResult. A common pattern is to put the work in a method that returns one, and log the error in the event that calls it:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_begin_play(&mut self) {
    if let Err(e) = self.setup() {
        log::warn!("[MyGame] setup failed: {e}");
    }
}
}

See Errors.

Testing without the engine

The goal: test gameplay rules with cargo test, without opening Unreal.

Code that calls the engine needs the engine to run. Code that only computes does not: damage formulas, combo windows, stamina, inventories, wave schedules, movement math. Keep that code in plain Rust functions and types, apart from the classes, and test it like any Rust code.

The templates do this with a model.rs file next to each class: the tunable numbers and the rules live there, and the class calls them.

Example

src/character/model.rs:

#![allow(unused)]
fn main() {
use glam::DVec3;

pub const MAX_WALK_SPEED: f32 = 500.0;
pub const CAMERA_BOOM_LENGTH: f32 = 400.0;

pub fn ground_axes(yaw_degrees: f64) -> (DVec3, DVec3) {
    let (sin, cos) = yaw_degrees.to_radians().sin_cos();
    (DVec3::new(cos, sin, 0.0), DVec3::new(-sin, cos, 0.0))
}

#[cfg(test)]
mod tests {
    use super::*;

    fn close(a: DVec3, b: DVec3) -> bool {
        (a - b).length() < 1e-9
    }

    #[test]
    fn ground_axes_follow_control_yaw() {
        let (forward, right) = ground_axes(90.0);
        assert!(close(forward, DVec3::Y));
        assert!(close(right, -DVec3::X));
    }
}
}

The class uses it:

#![allow(unused)]
fn main() {
let yaw = controller.checked()?.get_control_rotation().to_rotator().yaw;
let (forward, right) = model::ground_axes(yaw);
}

Running the tests

From Rust/:

cargo test -p my-game

The tests compile your crate as a normal Rust program, without the engine. A test that calls an engine function cannot run this way: keep the engine calls in the classes and the rules in the model.

What else works

Everything Rust offers for testing works here: property tests (proptest), benchmarks (criterion), snapshot tests. A rules crate of its own, with no Rusteal dependency at all, can be shared with a dedicated server, a balancing tool or a web page.

Declaring a class

The goal: a new Unreal class, written in Rust, that the editor and Blueprints treat like any other.

#![allow(unused)]
fn main() {
use bindings::engine::{StaticMeshComponent, SceneComponent};
use bindings::prelude::*;
use rusteal_runtime::{uclass, uclass_impl};

#[uclass(parent = Actor)]
pub struct Barrel {
    #[component(root)]
    root: SceneComponent,

    #[component(attach = "root")]
    mesh: StaticMeshComponent,

    #[uproperty(EditAnywhere, default = 50)]
    health: i32,
}

#[uclass_impl]
impl Barrel {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        log::info!("[MyGame] crate with {} health", self.health());
    }
}
}

A class is two parts:

• The struct, marked #[uclass(parent = ...)]: its fields are the class’s properties (#[uproperty]), its components (#[component]) and fields only Rust sees (no attribute).
• The impl block, marked #[uclass_impl]: its methods marked #[ufunction] are the class’s Unreal functions and events, and #[class_defaults] sets its default values. A class can split them over several #[uclass_impl] blocks, in several files. Plain impl blocks next to them hold the methods only Rust calls.

When the library loads, Rusteal creates the class in the engine under the struct’s name: Barrel above. It can be placed in a level, used as a Blueprint’s parent and picked in any class field of the editor.

Choosing a parent

The parent is an engine class from the bindings, or another Rust class. What the class is follows from it:

The engine classes keep their C++ names without the prefix (AActor is Actor), and come from the module they belong to (bindings::engine::Character, bindings::ai::AIController, bindings::umg::UserWidget).

Reaching the object

Inside the class, self is the Rust side of the object. Three methods connect it to the engine:

#![allow(unused)]
fn main() {
let me = self.as_ref().checked()?;
let location = me.k2_get_actor_location().to_dvec3();
}

#![allow(unused)]
fn main() {
if let Ok(mut barrel) = Barrel::from_obj(other_actor) {
    barrel.set_health(barrel.health() - 10);
}
}

from_obj is how one Rust class reaches another: an overlap gives an UObjectRef<Actor>, and from_obj turns it into the Rust class, with its getters, setters and methods, when that is what it is. See Object references.

Where the class lives

The game’s classes are in the /Script/Rusteal package: /Script/Rusteal.Barrel is the class path of Barrel, the path an ini file, a redirect or editor Python uses. A plugin’s classes are in its own package (see Plugins).

What a class cannot do yet

• Replicate properties or call RPCs over the network: Replicated and the RPC specifiers are not accepted yet.

See Known limits.

Properties

The goal: values that designers tune in the editor, that Blueprints read and write, and that the engine saves with the object.

#![allow(unused)]
fn main() {
use bindings::engine::{AnimMontage, SoundBase};
use bindings::prelude::*;
use rusteal_runtime::runtime::{FName, SubclassOf, UObjectRef, UeArray};
use rusteal_runtime::{uclass, uclass_impl};

#[uclass(parent = Actor)]
pub struct Turret {
    #[uproperty(EditAnywhere, category = "Combat", default = 25.0)]
    damage: f32,

    #[uproperty(EditAnywhere, category = "Combat", default = 3)]
    burst_size: i32,

    #[uproperty(EditAnywhere, BlueprintReadWrite, default = true)]
    b_active: bool,

    #[uproperty(EditAnywhere, category = "Effects")]
    fire_sound: UObjectRef<SoundBase>,

    #[uproperty(EditAnywhere, category = "Effects")]
    fire_montage: UObjectRef<AnimMontage>,

    #[uproperty(EditAnywhere, category = "Combat")]
    projectile_class: SubclassOf<Actor>,

    #[uproperty(EditAnywhere)]
    target_tags: UeArray<FName>,

    #[uproperty]
    current_target: UObjectRef<Actor>,

    shots_fired: u32,
}

#[uclass_impl]
impl Turret {}
}

A field marked #[uproperty] is a real Unreal property. It lives in the object’s memory, the editor shows it according to its specifiers, Blueprints reach it, it is saved with the level or the Blueprint, and object references in it keep the object alive for the garbage collector.

Getters and setters

Each property gets a getter named after the field and a setter with set_:

#![allow(unused)]
fn main() {
let damage = self.damage();
self.set_burst_size(5);
self.set_current_target(target);
}

The getter of a scalar, an object, a class or a name returns a copy. The getter of a UeArray returns a view of the array inside the object, changed in place:

#![allow(unused)]
fn main() {
let tags = self.target_tags();
tags.push(&FName::new("Player"))?;
let all: Vec<_> = tags.to_vec()?;
}

The getter of a struct property (OwnedStruct<FVector>) returns a copy; change it and set it back.

Specifiers

Several specifiers can be combined. A property with none (#[uproperty]) is hidden from the editor and from Blueprints, but is still a real property: use it for object references the class holds, so the garbage collector sees them.

Any other argument is a compile error.

Named arguments

default is for scalars and enums. Objects, classes, arrays and structs get their defaults in Class defaults or in a Blueprint child.

Names

The Unreal name is the field’s name in PascalCase: burst_size is BurstSize. A bool whose field starts with b_ follows Unreal’s b convention: b_active is bActive. When PascalCase gets it wrong, name fixes it:

#![allow(unused)]
fn main() {
#[uproperty(EditAnywhere, name = "MaxHP", default = 100.0)]
max_hp: f32,

#[uproperty(EditAnywhere, name = "NPCClass")]
npc_class: SubclassOf<Actor>,
}

The Unreal name is what Blueprints, ini files, data tables and editor Python see. Changing it on a class that already has Blueprint children or placed instances loses the values they saved under the old name.

Types

Maps and sets (TMap, TSet) cannot be declared yet; two arrays side by side, or a Rust-only HashMap, do the job meanwhile.

Fields only Rust sees

A field without an attribute is Rust’s alone: any Rust type, kept outside the Unreal object. It gets the same getter and setter, plus a <field>_mut() that changes it in place:

#![allow(unused)]
fn main() {
self.set_shots_fired(self.shots_fired() + 1);
self.cooldowns_mut().insert(weapon, 2.0);
}

The getter of a Rust-only field returns a clone. Use these fields for state the editor does not need: caches, timers, a state machine, a HashMap. Two things to keep in mind:

• They start over from Default on every hot reload.
• An UObjectRef kept only there does not keep its object alive: the garbage collector does not see it. Hold the objects you need to keep in a #[uproperty], or check them with checked() before use (see Object references).

The templates keep a class’s transient state in one plain struct field, read, changed and written back:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, Default)]
pub struct MoveState {
    pub has_double_jumped: bool,
    pub last_fall_time: f64,
}

let mut state = self.state();
state.has_double_jumped = true;
self.set_state(state);
}

In the editor

Open the class’s Blueprint child, click Class Defaults in the toolbar, and the Details panel lists the EditAnywhere and EditDefaultsOnly properties under their categories. Select an instance in the level to see the EditAnywhere ones per instance.

Screenshot: the Details panel of a Blueprint child showing the Combat and Effects categories of a Rust class. (images/classes/details_categories.png)

Components

The goal: an actor made of components, a mesh, a collision shape, a camera on a spring arm, created with every instance, as a C++ constructor’s CreateDefaultSubobject creates them.

#![allow(unused)]
fn main() {
use bindings::engine::{
    BoxComponent, CameraComponent, ProjectileMovementComponent, SceneComponent,
    SpringArmComponent, StaticMeshComponent
};
use rusteal_runtime::{uclass, uclass_impl};

#[uclass(parent = Actor)]
pub struct Door {
    #[component(root)]
    root: SceneComponent,

    #[component(attach = "root")]
    frame: StaticMeshComponent,

    #[component(attach = "frame", socket = "Hinge")]
    panel: StaticMeshComponent,

    #[component(attach = "root", name = "Trigger Box")]
    trigger: BoxComponent,
}

#[uclass_impl]
impl Door {}
}

A component that is not a scene component (a movement component, a perception component, a StateTree component) has no transform: it takes neither root nor attach.

#![allow(unused)]
fn main() {
#[component(name = "Projectile Movement")]
projectile_movement: ProjectileMovementComponent,
}

Attaching to inherited components

A Character already has a capsule (its root), a skeletal mesh and a movement component. Attach to them by their field-style names:

#![allow(unused)]
fn main() {
#[uclass(parent = Character)]
pub struct Hero {
    #[component(attach = "root_component")]
    camera_boom: SpringArmComponent,

    #[component(attach = "camera_boom", socket = "SpringEndpoint")]
    follow_camera: CameraComponent,
}
}

Reaching a component

Each component gets a getter that returns a reference to it:

#![allow(unused)]
fn main() {
let boom = self.camera_boom()?.checked()?;
boom.set_target_arm_length(400.0);
}

The getter returns a RustealResult, because the component may not exist on the object at that moment (an object being destroyed). Inherited engine components come from the engine getters: me.get_mesh(), me.get_capsule_component(), me.get_character_movement().

Names and Blueprints

A component’s name is its field’s name, or name. A Blueprint child’s changes to an inherited component, a mesh assigned to it, a collision preset, are saved under that name. Keep it stable once Blueprints use the class: renaming the field without name loses those changes. When you port a C++ class, give each component the name the C++ CreateDefaultSubobject used, and the Blueprint children keep their data.

Configuring components

The values a component starts with go in Class defaults:

#![allow(unused)]
fn main() {
use bindings::engine::{BoxComponentExt, PrimitiveComponentExt};

#[class_defaults]
fn class_defaults(&mut self) -> RustealResult<()> {
    let trigger = self.trigger()?.checked()?;
    trigger.set_box_extent(&FVector::from_dvec3(DVec3::new(100.0, 100.0, 120.0)), Some(false));
    trigger.set_collision_profile_name(FName::new("OverlapAllDynamic").handle(), Some(true));
    Ok(())
}
}

Adding a component at runtime

A component created during the game, for example on an actor the class does not own, is added through the engine:

#![allow(unused)]
fn main() {
let class = SubclassOf::<InventoryComponent>::base().upcast_to::<ActorComponent>();
let identity = FTransform::from_transform(Transform::IDENTITY);
let component = actor.checked()?.add_component_by_class(class, false, &identity, false);
}

See the inventory recipe.

In the editor

The Blueprint child’s Components panel lists the Rust components as inherited components: select one to change its mesh, material or collision in the Details panel.

Screenshot: the Components panel of a Blueprint child listing the components of a Rust class. (images/classes/components_panel.png)

Class defaults

The goal: set what a C++ constructor sets: inherited properties, component settings, object defaults, classes to use.

#![allow(unused)]
fn main() {
#[uclass_impl]
impl Hero {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        me.set_use_controller_rotation_yaw(false);

        let movement = me.get_character_movement().checked()?;
        movement.set_orient_rotation_to_movement(true);
        movement.set_max_walk_speed(500.0);
        movement.set_jump_z_velocity(700.0);

        let boom = self.camera_boom()?.checked()?;
        boom.set_target_arm_length(400.0);
        boom.set_use_pawn_control_rotation(true);

        Ok(())
    }
}
}

A method marked #[class_defaults] in the #[uclass_impl] block runs once, on the class default object, when the class is created. Every instance and every Blueprint child starts from that object, so what it sets is the class’s default. It returns RustealResult<()>, so ? works, or nothing.

What goes there

An actor needs nothing to tick: overriding receive_tick turns its tick on.

What does not go there

Class defaults run on the class default object, not on an instance in a level, and before any game starts. Do not spawn actors, look for other actors or read the world there: do that in receive_begin_play.

Blueprint children win

A Blueprint child that changes a value in its Class Defaults keeps its value: class defaults set the starting point, and the Blueprint’s changes are saved on top of it. When a change in class_defaults does not show on a Blueprint child, check whether that Blueprint overrides the same value (a value changed from its default shows a Reset to Default arrow next to it in the Details panel).

A Rust parent’s defaults

A class whose parent is a Rust class starts from the parent’s defaults: the parent’s class_defaults runs first, then the child’s.

Engine events

The goal: run Rust code when the engine says something happened: the game started, a frame passed, the actor was hit, a controller possessed the pawn.

#![allow(unused)]
fn main() {
#[uclass_impl]
impl Hero {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
    }

    #[ufunction(Override)]
    fn receive_tick(&mut self, delta_seconds: f32) {
    }

    #[ufunction(Override)]
    fn receive_end_play(&mut self, end_play_reason: u8) {
    }

    #[ufunction(Override)]
    fn on_landed(&mut self, hit: UStructRef<FHitResult>) {
    }
}
}

#[ufunction(Override)] implements an event of the parent class: one of the functions a Blueprint implements as an Event node (Event BeginPlay, Event Tick, Event Hit). The method is named after the event in snake_case and takes the event’s parameters, in order.

C++ virtuals are events

A C++ class overrides virtual functions (BeginPlay, Tick, NotifyHit). A Rust class, like a Blueprint, overrides the events the engine raises for them:

Overriding receive_tick turns the actor’s tick on: nothing else is needed.

Parameter types

An event that returns a value returns it from the method:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn choose_player_start(&mut self, _player: UObjectRef<Controller>) -> UObjectRef<Actor> {
    let starts = GameplayStatics::get_all_actors_of_class(
        self.as_ref().upcast_to(),
        SubclassOf::<PlayerStart>::base().upcast_to(),
    );

    starts.first().copied().unwrap_or_default()
}
}

Events whose name is not the method’s

When the event’s name is not the method’s name in PascalCase, name gives it:

#![allow(unused)]
fn main() {
const MOVE_FALLING: u8 = 3;

#[ufunction(Override, name = "K2_OnMovementModeChanged")]
fn on_movement_mode_changed(
    &mut self,
    _prev_movement_mode: u8,
    new_movement_mode: u8,
    _prev_custom_mode: u8,
    _new_custom_mode: u8,
) {
    if new_movement_mode == MOVE_FALLING {
    }
}
}

Finding an event’s name and parameters

An event is any function the parent class lets Blueprints implement. To find one:

• in a Blueprint child of the parent class, right-click the Event Graph and look under Add Event: the node’s title is the event, and hovering it shows its name;
• in the engine’s C++ headers, events are the UFUNCTION(BlueprintImplementableEvent) and UFUNCTION(BlueprintNativeEvent) declarations of the class, many named Receive... or K2_...;
• in the generated bindings (Rust/bindings/src/), the class’s module lists them with their parameters.

A Blueprint child must not implement the same event

A Blueprint child that implements the same event in its graph replaces the Rust one: the engine runs the Blueprint’s graph instead. Keep the Blueprint children of Rust classes for data (meshes, sounds, input actions), and if a Blueprint needs to react too, give it an event of its own (see Functions, BlueprintImplementableEvent).

Functions

The goal: functions Blueprints can call, events Blueprints implement, and functions the engine calls by name (input, timers, delegates).

#![allow(unused)]
fn main() {
#[uclass_impl]
impl Turret {
    #[ufunction(BlueprintCallable)]
    fn fire(&mut self, target: UObjectRef<Actor>) {
    }

    #[ufunction(BlueprintPure)]
    fn is_reloading(&self) -> bool {
        self.reload_left() > 0.0
    }

    #[ufunction(BlueprintImplementableEvent)]
    fn on_fired(&self, muzzle_location: &OwnedStruct<FVector>) {}
}
}

A method marked #[ufunction] is a real Unreal function of the class. It is BlueprintCallable unless it says otherwise:

name = "..." gives the Unreal name when the method’s name in PascalCase is not it. Any other argument is a compile error.

Parameters and return values

A function takes scalars (bool, u8, i32, i64, f32, f64), enums (engine enums and #[uenum]s), objects (UObjectRef<T>), classes (SubclassOf<T>) and structs (UStructRef<T>, a reference into the call’s parameters; to_owned() keeps a copy), and returns a scalar, an enum, an object or a class. A BlueprintImplementableEvent takes structs as &OwnedStruct<T>. An Override of an engine event that returns a struct, such as an input modifier’s ModifyRaw, returns an OwnedStruct<T>.

Strings and arrays are not function parameters yet. A Blueprint that needs to pass text to Rust can set a String property and call a function that reads it.

Names

The Unreal name is the method’s name in PascalCase: fire is Fire, do_jump_start is DoJumpStart. A method named after a Rust keyword uses a raw identifier: fn r#move is Move, fn r#use is Use. When PascalCase gets it wrong, name fixes it:

#![allow(unused)]
fn main() {
#[ufunction(name = "SpawnNPC")]
fn spawn_npc(&mut self) {
}
}

Functions the engine calls by name

Several engine features call a function by its Unreal name: an input action bound with bind_action, a timer set with k2_set_timer, a delegate bound with add_ufunction. Any #[ufunction] works for them:

#![allow(unused)]
fn main() {
#[ufunction]
fn respawn(&mut self) {
}

KismetSystemLibrary::k2_set_timer(self.as_ref().upcast_to(), "Respawn", 3.0, false, None, None, None);
}

A name that matches no function is logged with that name. See Timers and Delegates.

Use case: letting the Blueprint play the effects

The goal: Rust decides when something happens; the Blueprint child decides how it looks and sounds.

#![allow(unused)]
fn main() {
#[uclass(parent = Actor)]
pub struct Pickup {
    #[component(root)]
    root: SceneComponent,
}

#[uclass_impl]
impl Pickup {
    #[ufunction(BlueprintImplementableEvent, name = "BP_OnPickedUp")]
    fn bp_on_picked_up(&self) {}

    #[ufunction(Override)]
    fn receive_actor_begin_overlap(&mut self, other_actor: UObjectRef<Actor>) {
        if other_actor.cast::<Character>().is_err() {
            return;
        }

        if let Ok(me) = self.as_ref().checked() {
            me.set_actor_enable_collision(false);
        }

        self.bp_on_picked_up();
    }
}
}

In the editor:

1. Open the Blueprint child of Pickup (see Blueprint children).
2. Right-click the Event Graph and search for BP On Picked Up.
3. Add the Event BP On Picked Up node, and from it play a sound, spawn a Niagara system, hide the mesh.
4. Click Compile, then Save.

Screenshot: the Event Graph of BP_Pickup with the Event BP On Picked Up node playing a sound. (images/classes/implementable_event.png)

The templates name these events BP_... so they are easy to tell apart from the engine’s, and use them for every effect: hit sparks, death animations, UI updates.

Use case: a getter for an Animation Blueprint

The goal: an Animation Blueprint reads gameplay state from the Rust character.

#![allow(unused)]
fn main() {
#[ufunction(BlueprintPure)]
fn has_double_jumped(&self) -> bool {
    self.state().has_double_jumped
}
}

In the Animation Blueprint’s Event Graph, cast Try Get Pawn Owner to the character’s class, and call Has Double Jumped on it. The pure function has no execution pins, so it can feed a variable directly.

Blueprint children

The goal: a Blueprint whose parent is a Rust class, to assign the assets the class needs (meshes, sounds, input actions, widget classes) and to tune its values, without touching Rust.

This is how every Rusteal template works: the Rust class declares the properties, and a Blueprint child named BP_<Class> fills them in. The game then uses the Blueprint, not the Rust class directly.

Creating the Blueprint

1. In the Content Browser, open the folder the Blueprint goes in.
2. Right-click an empty area and choose Blueprint Class.
3. In the Pick Parent Class window, expand All Classes.
4. Type the Rust class’s name in the search box (Turret).
5. Select the class in the list and click Select.
6. Name the new asset BP_Turret and press Enter.

Screenshot: the Pick Parent Class window with All Classes expanded and the Rust class found by the search. (images/classes/pick_parent_class.png)

Filling in the properties

1. Double-click BP_Turret to open it.
2. Click Class Defaults in the toolbar.
3. In the Details panel, find the Rust class’s properties under their categories, and set them: pick the sound in Fire Sound, the projectile Blueprint in Projectile Class.
4. Click Compile, then Save.

Screenshot: the Class Defaults of BP_Turret with Fire Sound and Projectile Class assigned. (images/classes/class_defaults_assigned.png)

The components the Rust class declares are in the Components panel: select one to give it a mesh or a material.

Using the Blueprint

Place BP_Turret in the level by dragging it from the Content Browser into the viewport, or spawn it from Rust through a SubclassOf<T> property that holds it (see Spawning actors).

Game mode, pawn and controller

A game mode names the pawn and the controller the game uses. With all three in Rust:

1. Create a Blueprint child of each: BP_MyGameMode, BP_MyCharacter, BP_MyPlayerController.
2. Open BP_MyGameMode, click Class Defaults, and in the Details panel, under Classes, set Default Pawn Class to BP_MyCharacter and Player Controller Class to BP_MyPlayerController. Compile and Save.
3. Open the level, and in the World Settings tab (Window > World Settings), set GameMode Override to BP_MyGameMode.

Or, for every level of the project: Edit > Project Settings, Maps & Modes, Default GameMode.

Screenshot: the World Settings tab with GameMode Override set to the game mode Blueprint. (images/classes/world_settings_game_mode.png)

Rules for Blueprint children

• Data, not logic, for what Rust does. A Blueprint child that implements an event the Rust class implements replaces the Rust code for it. Keep the Blueprint’s graph for the BlueprintImplementableEvents the Rust class declares for it.
• Values changed in the Blueprint win. A value set in the Blueprint’s Class Defaults overrides the Rust default. The arrow next to a changed value resets it.
• Hot reload keeps them. When the Rust class changes shape, its Blueprint children move to the new class with their values. See Hot reload.

Rust classes deriving from Rust classes

The goal: a class that extends another Rust class: a horror character built on the first-person character, an elite enemy built on the enemy.

#![allow(unused)]
fn main() {
use crate::character::FirstPersonCharacter;

#[uclass(parent = FirstPersonCharacter)]
pub struct HorrorCharacter {
    #[component(attach = "first_person_camera_component", name = "SpotLight")]
    spot_light: SpotLightComponent,

    #[uproperty(EditAnywhere, category = "Sprint", default = 600.0)]
    sprint_speed: f32,
}
}

The child has the parent’s properties, components and functions, and adds its own:

• its components can attach to the parent’s by their field names;
• its class defaults start from the parent’s: the parent’s class_defaults runs first;
• Blueprints see one class with everything.

Calling the parent

An event both classes override runs the child’s code. To run the parent’s too, as C++ calls Super::, reach the parent class with from_obj and call it:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_begin_play(&mut self) {
    if let Ok(mut parent) = FirstPersonCharacter::from_obj(self.as_ref()) {
        parent.receive_begin_play();
    }
}
}

The parent’s methods must be visible to the child’s module: declare the ones the child calls pub(crate).

#![allow(unused)]
fn main() {
#[ufunction(Override)]
pub(crate) fn receive_begin_play(&mut self) {
}
}

The same reaches the parent’s components and Rust methods. The templates keep a helper for it:

#![allow(unused)]
fn main() {
fn base(&self) -> RustealResult<FirstPersonCharacter> {
    FirstPersonCharacter::from_obj(self.as_ref())
}

let camera = self.base()?.first_person_camera_component()?.checked()?;
}

Replacing a parent’s function

A function the child declares again with the same name replaces the parent’s, for Blueprints and for the engine:

#![allow(unused)]
fn main() {
#[ufunction(BlueprintCallable)]
fn do_move(&mut self, right: f32, forward: f32) {
    if !self.is_dead()
        && let Ok(mut parent) = FirstPersonCharacter::from_obj(self.as_ref())
    {
        parent.do_move(right, forward);
    }
}
}

Hot reload

When a parent class changes shape, its Rust children are created again with it, and their objects move to the new classes. See Hot reload.

Interfaces

Two different tools answer “different classes that respond to the same call”: Unreal interfaces, which Blueprints understand, and Rust traits, which only Rust code sees. A #[uinterface] trait is both.

Use case: an interface declared in Rust

Not released yet. #[uinterface] is in development and comes in a release after 0.7.0. Until then, a Rust class implements the interfaces declared in C++ or as Blueprint Interface assets, by class path: see implementing a Blueprint Interface.

The goal: doors, chests and levers the player interacts with, some written in Rust and some in Blueprints, and one call that reaches any of them.

In Rust

#![allow(unused)]
fn main() {
use rusteal_runtime::{uclass, uclass_impl, uinterface};

#[uinterface]
pub trait Interactable {
    fn interact(&mut self, instigator: UObjectRef<Actor>) -> bool;
    fn highlight(&mut self, on: bool);
}
}

#[uinterface] makes the trait an Unreal interface, Interactable, whose functions are Blueprint events: Interact returns a Boolean, Highlight returns nothing. Its functions take &self or &mut self, then what a #[ufunction] takes (see Functions), and return what it returns. They have no body: each class implementing the interface writes its own.

A Rust class implements it with #[uclass_impl] on the trait’s implementation. Its methods are the interface’s functions, with no #[ufunction]:

#![allow(unused)]
fn main() {
#[uclass(parent = Actor)]
pub struct Door {
    #[uproperty(EditAnywhere)]
    b_locked: bool,
    #[uproperty(VisibleAnywhere)]
    b_open: bool,
}

#[uclass_impl]
impl Interactable for Door {
    fn interact(&mut self, _instigator: UObjectRef<Actor>) -> bool {
        if self.b_locked() {
            return false;
        }

        self.set_b_open(!self.b_open());
        true
    }

    fn highlight(&mut self, on: bool) {
        log::info!("Door highlighted: {on}");
    }
}
}

The class keeps its other #[uclass_impl] block for its own functions and events.

In the editor

A Blueprint implements it as it implements a Blueprint Interface:

1. Open the Blueprint (a chest, say), and click Class Settings in the toolbar.
2. In the Details panel, under Interfaces, click Add next to Implemented Interfaces and pick Interactable.
3. In the My Blueprint panel, under Interfaces, double-click Interact: a function graph opens, since it returns a value. Connect its logic to the Return Node.
4. Right-click the Event Graph, search for Event Highlight, and place it: functions with no return value are events.
5. Click Compile, then Save.

Screenshot: a chest Blueprint’s Class Settings, with Interactable under Implemented Interfaces and the Interact function in My Blueprint. (images/classes/uinterface_bp.png)

A Blueprint child of Door has the interface too: double-clicking Interact in its My Blueprint panel overrides Door’s, as a C++ BlueprintNativeEvent is overridden, and Add call to parent function in the graph’s context menu runs the Rust one.

A Rust class that leaves the functions to its Blueprint children lists the interface instead of implementing it:

#![allow(unused)]
fn main() {
#[uclass(parent = Actor, implements = [Interactable])]
pub struct Lever {}
}

Calling it

From Rust, on any object, whichever language implements it:

#![allow(unused)]
fn main() {
if let Ok(mut target) = hit_actor.interface::<dyn Interactable>() {
    target.interact(self.as_ref().upcast_to());
}
}

interface::<dyn Interactable>() turns an object into the interface, as C++’s Cast<IInteractable>: an error when its class does not implement it. implements::<dyn Interactable>() only tells. The ScriptInterface<dyn Interactable> it gives (C++’s TScriptInterface) calls the object’s own implementation, Rust or Blueprint; a function the object’s class does not implement returns the default value (false, 0, a null reference), as a Blueprint’s interface message does.

From a Blueprint: the Interact (Message) node on any actor, or Interact on an Interactable reference; Does Implement Interface with Interactable finds out whether an actor has it.

Screenshot: a Blueprint graph calling Interact (Message) on a line trace’s Hit Actor. (images/classes/uinterface_message.png)

Notes

• The interface is /Script/Rusteal.Interactable, a plugin’s /Script/<Plugin>.Interactable. The classes of another library (the game, for a plugin’s interface) implement it by that path, as below.
• Changing it during a hot reload keeps the interface and gives it the new functions; the Blueprints implementing or calling it are recompiled, as when a Blueprint Interface changes. See Hot reload.

Use case: implementing a Blueprint Interface

The goal: a Rust door that a Blueprint can Use through a Blueprint Interface, like any Blueprint door.

In the editor

1. In the Content Browser, right-click an empty area and choose Blueprint > Blueprint Interface.
2. Name it BPI_Usable and open it.
3. In the My Blueprint panel, rename the first function to Use.
4. With Use selected, in the Details panel, add an Input named Instigator of type Actor (Object Reference), and an Output named ReturnValue of type Boolean.
5. Click Compile, then Save.

Screenshot: BPI_Usable open, with the Use function’s Instigator input and ReturnValue output in the Details panel. (images/classes/bpi_usable.png)

In Rust

#![allow(unused)]
fn main() {
#[uclass(parent = Actor, implements = ["/Game/Interaction/BPI_Usable.BPI_Usable_C"])]
pub struct Door {
    #[uproperty(EditAnywhere)]
    b_locked: bool,
}

#[uclass_impl]
impl Door {
    #[ufunction]
    fn r#use(&mut self, _instigator: UObjectRef<Actor>) -> bool {
        !self.b_locked()
    }
}
}

implements lists interfaces by class path:

• a Blueprint Interface asset: its path with _C after the asset name, /Game/Interaction/BPI_Usable.BPI_Usable_C for BPI_Usable in Content/Interaction/;
• a C++ interface: /Script/<Module>.<Interface> without the U, /Script/Engine.NavAgentInterface.

Each interface function is a #[ufunction] named as the interface’s function (in snake_case, or with name), taking the same parameters in the same order and returning its return value.

Calling it

A Blueprint calls it with the Use (Message) node on any actor, and Does Implement Interface finds out whether an actor has it. C++ calls it with IUsable::Execute_Use. They reach the Rust class as they reach a Blueprint that implements the interface.

Notes

• The interface loads once the engine is initialized, so the class implements it from then on.
• An interface whose functions are not Blueprint events (one marked CannotImplementInterfaceInBlueprint) can only be implemented in C++, and is refused, as Blueprints refuse it.
• To declare the interface in Rust instead, see the first use case.

Use case: Rust traits between Rust classes

The goal: several Rust classes take damage, and the code that deals it does not care which one it hit.

When only Rust code calls it, a Rust trait is the lighter tool. The templates declare the trait, implement it on each class, and turn an actor into the trait with from_obj:

#![allow(unused)]
fn main() {
pub trait Damageable {
    fn apply_damage(&mut self, damage: f32, causer: UObjectRef<Actor>);
}

impl Damageable for Enemy {
    fn apply_damage(&mut self, damage: f32, _causer: UObjectRef<Actor>) {
        self.set_current_hp(self.current_hp() - damage);
    }
}

impl Damageable for DamageableBox {
    fn apply_damage(&mut self, damage: f32, _causer: UObjectRef<Actor>) {
    }
}

pub fn damageable(actor: UObjectRef<Actor>) -> Option<Box<dyn Damageable>> {
    if let Ok(enemy) = Enemy::from_obj(actor) {
        Some(Box::new(enemy))
    } else if let Ok(damageable_box) = DamageableBox::from_obj(actor) {
        Some(Box::new(damageable_box))
    } else {
        None
    }
}
}

The caller:

#![allow(unused)]
fn main() {
if let Some(mut target) = damageable(other_actor) {
    target.apply_damage(self.damage(), self.as_ref().upcast_to());
}
}

A trait is invisible to Blueprints: a Blueprint class cannot implement it, and a Blueprint cannot call it. When a Blueprint must take part, put #[uinterface] on the trait: the classes implement it with #[uclass_impl], and interface::<dyn Damageable>() replaces the damageable function.

Structs and data tables

The goal: a struct declared in Rust that Unreal understands: the row of a data table, or a group of values a class’s property holds.

#![allow(unused)]
fn main() {
use bindings::engine::StaticMesh;
use rusteal_runtime::runtime::{SoftObjectRef, SubclassOf};
use rusteal_runtime::ustruct;

#[ustruct]
pub struct WeaponTableRow {
    #[uproperty(EditAnywhere)]
    static_mesh: SoftObjectRef<StaticMesh>,

    #[uproperty(EditAnywhere)]
    weapon_to_spawn: SubclassOf<Weapon>,

    #[uproperty(EditAnywhere)]
    damage: f32,
}
}

A #[ustruct] is Unreal’s USTRUCT(). Every field is a #[uproperty], of the kinds a class’s properties are, without default: a struct starts zeroed. Its memory belongs to Unreal (a data table’s row, a property of an object, an OwnedStruct), so the Rust type itself is a marker, and the fields are read and written through a trait generated next to it, WeaponTableRowExt, on UStructRef<WeaponTableRow> and OwnedStruct<WeaponTableRow>:

#![allow(unused)]
fn main() {
use super::pickup::WeaponTableRowExt;

let damage = row.damage();
row.set_damage(30.0);
}

Use case: a data table of weapons

The goal: designers list the weapons in a table, and a pickup shows and grants the one it is set to.

In the editor

1. In the Content Browser, right-click an empty area and choose Miscellaneous > Data Table.
2. In the Pick Row Structure window, choose WeaponTableRow and click OK.
3. Name it DT_WeaponData and open it.
4. Click Add to add a row, name it (Pistol), and fill in Static Mesh, Weapon To Spawn and Damage in the Row Editor.
5. Click Save.

Screenshot: DT_WeaponData open, with a Pistol row filled in the Row Editor. (images/classes/data_table_rows.png)

In Rust

The pickup holds a row handle, which the editor shows as a table and a row name:

#![allow(unused)]
fn main() {
use bindings::engine::{FDataTableRowHandle, StaticMeshComponent, StaticMeshComponentExt};
use bindings::prelude::*;

#[uclass(parent = Actor)]
pub struct WeaponPickup {
    #[component(root)]
    mesh: StaticMeshComponent,

    #[uproperty(EditAnywhere, category = "Pickup")]
    weapon_type: OwnedStruct<FDataTableRowHandle>,

    #[uproperty]
    weapon_class: SubclassOf<Weapon>,
}

#[uclass_impl]
impl WeaponPickup {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        let weapon_type = self.weapon_type();

        let Some(row) = weapon_type.get_row::<WeaponTableRow>() else {
            log::warn!("[MyGame] pickup without a weapon type");
            return;
        };

        if let Ok(static_mesh) = row.static_mesh().load_synchronous()
            && let Ok(mesh) = self.mesh().and_then(|m| m.checked())
        {
            mesh.set_static_mesh(static_mesh);
        }

        self.set_weapon_class(row.weapon_to_spawn());
    }
}
}

get_row::<T>() is C++’s FindRow<T>: it returns None when the handle points to no table, to a missing row, or to a table of another row struct. A row can also be found by table and name:

#![allow(unused)]
fn main() {
let row = find_data_table_row::<WeaponTableRow>(table, FName::new("Pistol"));
}

Then, on each WeaponPickup in the level (or on its Blueprint child), set Weapon Type: the Data Table to DT_WeaponData and the Row Name to Pistol.

Screenshot: the Details panel of a WeaponPickup with Weapon Type set to DT_WeaponData and the Pistol row. (images/classes/row_handle.png)

Use case: a struct property

A class can hold your struct as a property:

#![allow(unused)]
fn main() {
#[uproperty(EditAnywhere)]
stats: OwnedStruct<WeaponTableRow>,
}

The getter returns a copy: change it and set it back.

#![allow(unused)]
fn main() {
let stats = self.stats();
stats.as_ref().set_damage(stats.as_ref().damage() * 2.0);
self.set_stats(&stats);
}

An array inside a struct, such as a gearbox’s gear ratios, is a UeArray view into the struct it belongs to: change it on the copy, then set the copy back.

#![allow(unused)]
fn main() {
let transmission = movement.get_transmission_setup();
transmission.as_ref().forward_gear_ratios().set_all(&[4.25, 2.52, 1.66, 1.22, 1.0])?;
movement.set_transmission_setup(&transmission);
}

Hot reload

A changed #[ustruct] keeps its old fields until the editor restarts: the Output Log says so when it happens. Classes reload without a restart; structs do not, yet.

Enums

The goal: an enum declared in Rust that Unreal understands: a property a designer picks from a dropdown, a function parameter a Blueprint passes, a value Blueprints switch on.

#![allow(unused)]
fn main() {
use rusteal_runtime::uenum;

#[uenum]
pub enum EGrabType {
    None,
    Snap,
    Custom = 3,
    Free,
}
}

A #[uenum] is Unreal’s UENUM(BlueprintType). Its variants carry no data, and their values go up to 254, as a Blueprint enum’s uint8 does (Unreal adds the _MAX entry after the last). Values follow Rust’s rules: the first is 0, each next one adds 1, and = 3 sets one. The macro sets the representation, u8, and derives Clone, Copy, PartialEq, Eq, Hash and Debug, so the enum is a plain Rust value too:

#![allow(unused)]
fn main() {
match self.grab_type() {
    EGrabType::Free | EGrabType::Snap => self.attach_to(controller),
    EGrabType::Custom => self.set_b_is_held(true),
    EGrabType::None => {}
}
}

Use case: a grab type designers choose

The goal: a grab component whose kind of grab each object sets in its Blueprint, from a dropdown.

#![allow(unused)]
fn main() {
#[uclass(parent = SceneComponent)]
pub struct GrabComponent {
    #[uproperty(EditAnywhere, BlueprintReadWrite, category = "Grab", default = EGrabType::Free)]
    grab_type: EGrabType,
}
}

default takes a variant, as it does for engine enums. A Rust class that places the component can choose it in its class defaults:

#![allow(unused)]
fn main() {
#[class_defaults]
fn class_defaults(&mut self) -> RustealResult<()> {
    GrabComponent::from_obj(self.grab_component_snap()?)?.set_grab_type(EGrabType::Snap);
    Ok(())
}
}

In the editor

1. Open the Blueprint that has the component (a BP_Pistol child of the Rust pistol).
2. In the Components panel, select GrabComponentSnap.
3. In the Details panel, under Grab, Grab Type lists None, Snap, Custom and Free.

Screenshot: the Details panel of a grab component, with the Grab Type dropdown open. (images/classes/uenum_dropdown.png)

In a Blueprint graph, the enum has the usual nodes: Switch on EGrabType, == (Equal), Literal enum EGrabType.

Enums in functions

#[uenum]s and engine enums are #[ufunction] parameters and return values:

#![allow(unused)]
fn main() {
#[ufunction(BlueprintPure)]
pub fn get_held_by_hand(&self) -> EControllerHand {
    match model::hand_of_motion_source(&self.motion_source_name()) {
        model::Hand::Left => EControllerHand::Left,
        model::Hand::Right => EControllerHand::Right,
    }
}

#[ufunction(BlueprintCallable)]
pub fn set_vr_spectator_mode(&mut self, new_vr_spectator_mode: EVRSpectatorMode) {
    self.set_spectator_mode(new_vr_spectator_mode);
}
}

The enum must be a one-byte one, as every Blueprint enum is; an engine enum stored on more bytes is refused when the crate compiles.

Notes

• The enum’s Unreal name is the Rust name. Its entries are EGrabType::Snap to C++ and ini files, Snap in the editor.
• An enum created by a hot reload keeps its first values: adding a variant takes an editor restart, as changing a #[ustruct] does.
• An enum asset made in the editor (Blueprint > Enumeration) is not a Rust type. To use one from Rust, declare it again with #[uenum] and point the Blueprints at the Rust one.

Object references

Every Unreal object Rust code touches, an actor, a component, an asset, a class’s default object, is reached through a reference. Unreal owns the objects and destroys them when its garbage collector decides; Rust code holds references to them and checks them before use.

UObjectRef

#![allow(unused)]
fn main() {
let target: UObjectRef<Actor> = self.current_target();
}

UObjectRef<T> is a handle to an object of class T: eight bytes, Copy, cheap to pass around and to store. It does not keep the object alive, and the object may be destroyed while you hold it.

Calling functions: checked

Engine functions are called on a checked reference:

#![allow(unused)]
fn main() {
let me = self.as_ref().checked()?;
let location = me.k2_get_actor_location().to_dvec3();
me.k2_destroy_actor();
}

checked() verifies the object is still alive once, and the calls after it go straight to the engine. A call on a destroyed object would crash the engine in C++; in Rust, checked() returns an error first, and the code decides what to do:

#![allow(unused)]
fn main() {
let Ok(target) = self.current_target().checked() else {
    return;
};
}

Casting

#![allow(unused)]
fn main() {
if let Ok(character) = other_actor.cast::<Character>() {
}

let as_object: UObjectRef<Object> = actor.upcast_to::<Object>();
}

cast is C++’s Cast<T>: a runtime check. upcast_to is free and cannot fail, because the compiler knows Character is an Actor. The engine functions that take a world context or a base class (UObject* WorldContextObject, AActor*) take the upcast:

#![allow(unused)]
fn main() {
let world_context = self.as_ref().upcast_to();
let player = GameplayStatics::get_player_pawn(world_context, 0);
}

An object’s class and outer come typed as well: actor.class()? is a SubclassOf<T> of the reference’s own type, and component.outer::<Actor>()? is the outer, checked to be an actor.

For your own Rust classes, MyClass::from_obj(reference) does the cast and gives the Rust class with its getters and methods. See Declaring a class.

Keeping an object alive

The garbage collector keeps an object alive while something it knows about references it. A UObjectRef in a Rust-only field or a local variable is invisible to it. To keep an object:

• Hold it in a #[uproperty]. The usual way, and what C++ does with UPROPERTY() pointers.

  #![allow(unused)]
  fn main() {
  #[uproperty]
  spawned_weapon: UObjectRef<Weapon>,
  }

• Pin it. Pinned<T> is a garbage collection root: the object lives until the Pinned is dropped. For objects Rust code alone keeps, outside any class.

  #![allow(unused)]
  fn main() {
  let pinned: Pinned<Actor> = actor.pin()?;
  let location = pinned.k2_get_actor_location();
  }

• Watch it. TWeakObjectPtr<T> does not keep the object, and tells you when it is gone:

  #![allow(unused)]
  fn main() {
  let weak = TWeakObjectPtr::from_ref(&actor);
  if let Some(actor) = weak.get() {
  }
  }

Classes: SubclassOf

A class is not an object reference. SubclassOf<T> is Unreal’s TSubclassOf<T>, a class that is T or derives from it:

#![allow(unused)]
fn main() {
#[uproperty(EditAnywhere)]
projectile_class: SubclassOf<Projectile>,
}

Engine functions that take a class filter (get_all_actors_of_class, get_overlapping_actors) take a SubclassOf:

#![allow(unused)]
fn main() {
let units = GameplayStatics::get_all_actors_of_class(
    self.as_ref().upcast_to(),
    SubclassOf::<Unit>::base().upcast_to(),
);
}

Threads

References are Send, so a background thread can carry them, but Unreal objects belong to the game thread: call the engine only from there. See Work off the game thread.

Calling the engine

The bindings give Rust every function Blueprints can call, for the engine modules the project binds. This page covers how they look from Rust.

Finding a function

A Blueprint node is a function of some class. Its Rust name is its C++ name in snake_case, on the class’s Ext trait:

The C++ name is in the node’s tooltip in the Blueprint editor, and in the engine’s headers. Many Blueprint nodes are K2_ functions in C++ (K2_GetActorLocation, K2_SetTimer, K2_DestroyActor).

Import the class and its Ext trait from its module:

#![allow(unused)]
fn main() {
use bindings::engine::{Character, CharacterExt, CharacterMovementComponentExt};
}

rust-analyzer completes the methods on a checked reference, which is the quickest way to browse what a class offers.

Static functions

Function libraries (UGameplayStatics, UKismetSystemLibrary, UKismetMathLibrary) are called on the class, as in C++:

#![allow(unused)]
fn main() {
let now = GameplayStatics::get_time_seconds(self.as_ref().upcast_to());
let roll = KismetMathLibrary::random_integer_in_range(0, 100);
}

Properties of engine classes

The properties Blueprints can read have a getter, get_<name>(), and the ones they can write a setter, set_<name>(): get_max_walk_speed(), set_max_walk_speed(600.0). An array property’s getter is the property’s name alone (tags()). Private engine properties that Blueprints can read (ACharacter’s Mesh, CharacterMovement and CapsuleComponent) have getters, without setters when they are read-only:

#![allow(unused)]
fn main() {
let mesh = me.get_mesh().checked()?;
let movement = me.get_character_movement().checked()?;
let tags = me.tags();
}

An array property returns a view of the array inside the object (UeArray), changed in place:

#![allow(unused)]
fn main() {
me.tags().push(&FName::new("Dead").handle())?;
}

Optional parameters

A parameter with a default value in C++ is an Option in Rust. None keeps the default:

#![allow(unused)]
fn main() {
anim_instance.montage_play(montage, Some(1.0), None, Some(0.0), Some(true));
capsule.set_capsule_size(42.0, 96.0, Some(false));
}

Out parameters

A function with out parameters returns them in a tuple, after its return value:

#![allow(unused)]
fn main() {
let (hit, out_hit) = KismetSystemLibrary::line_trace_single(...);
let (projected, screen_position) = controller.project_world_location_to_screen(&location, Some(true));
let (found, x, y) = controller.get_mouse_position();
}

Names, strings and text

#![allow(unused)]
fn main() {
let socket = FName::new("HandGrip_R");
let location = mesh.get_socket_location(socket.handle()).to_dvec3();
}

Math

Engine structs (FVector, FRotator, FTransform, FQuat, FLinearColor) are Unreal’s memory, held in an OwnedStruct. Rust math uses glam (DVec3, DQuat, DVec2) and Rusteal’s own Rotator, Transform and LinearColor. Convert at the boundary:

#![allow(unused)]
fn main() {
let me = self.as_ref().checked()?;
let forward = me.get_actor_forward_vector().to_dvec3();
let target = me.k2_get_actor_location().to_dvec3() + forward * 500.0;
me.k2_set_actor_location(&FVector::from_dvec3(target), false, true);
}

The conversions and FVector, FRotator, FTransform come with use bindings::prelude::*. Unreal’s units are kept: centimeters, degrees for rotators, Z up.

Structs: reading and writing fields

An engine struct has a getter and a setter per field, on its Ext trait (FHitResultExt, FVectorExt):

#![allow(unused)]
fn main() {
use bindings::engine::{ActorComponentExt, FHitResultExt};

let hit = out_hit.as_ref();
let impact = hit.get_impact_point().to_dvec3();
let normal = hit.get_impact_normal().to_dvec3();
let other = hit.get_component().checked()?.get_owner();
}

OwnedStruct<T> is a struct Rust owns; as_ref() gives the UStructRef<T> the field accessors work on. OwnedStruct::new() is a struct with Unreal’s default values, the usual way to pass “no options”:

#![allow(unused)]
fn main() {
subsystem.add_mapping_context(context, 0, &OwnedStruct::new());
}

To change a struct an engine object holds, read it, change the copy and write it back:

#![allow(unused)]
fn main() {
let nav = movement.get_nav_agent_props();
nav.as_ref().set_agent_radius(42.0);
movement.set_nav_agent_props(&nav);
}

Enums

Engine enums are Rust enums with the C++ names: ECollisionChannel::ECC_Pawn, ETriggerEvent::Triggered, EAttachmentRule::SnapToTarget. Events receive some enums as their u8 value (receive_end_play(&mut self, end_play_reason: u8)). Your own enums are declared with #[uenum]; see Enums.

Functions that are not in the bindings

A function that reflection exposes but the bindings leave out (a Blueprint’s own function, a module the project does not bind) can still be called by name. See Dynamic calls.

Spawning actors

The goal: put actors into the level from code: projectiles, enemies, pickups, effects.

Spawning a Blueprint chosen in the editor

The usual case: the class to spawn is a Blueprint child (BP_Projectile), picked in a SubclassOf property.

#![allow(unused)]
fn main() {
use bindings::engine::{ESpawnActorCollisionHandlingMethod, GameplayStatics, KismetMathLibrary};
use bindings::prelude::*;

#[uclass(parent = Character)]
pub struct Shooter {
    #[uproperty(EditAnywhere, category = "Projectile")]
    projectile_class: SubclassOf<Projectile>,
}

impl Shooter {
    fn spawn_projectile(&self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        let location = me.k2_get_actor_location().to_dvec3()
            + me.get_actor_forward_vector().to_dvec3() * 100.0;

        let transform = KismetMathLibrary::make_transform(
            &FVector::from_dvec3(location),
            &me.k2_get_actor_rotation(),
            &FVector::from_dvec3(DVec3::ONE),
        );

        let world = self.as_ref().get_world()?;
        world.spawn_actor_of_class(self.projectile_class(), &transform)?;

        Ok(())
    }
}
}

get_world() gives the world an object lives in, and spawn_actor_of_class spawns an actor of a class held in a SubclassOf. It returns an UObjectRef<T> to the new actor, or an error if the class is not set or the spawn failed.

Deferred spawn: setting values before BeginPlay

To set an actor up before its BeginPlay runs (an owner, an instigator, a team), spawn it deferred and finish the spawn after:

#![allow(unused)]
fn main() {
let spawned = GameplayStatics::begin_deferred_actor_spawn_from_class(
    me.as_ref().upcast_to(),
    self.projectile_class().upcast_to(),
    &transform,
    Some(ESpawnActorCollisionHandlingMethod::AlwaysSpawn),
    Some(me.as_ref().upcast_to()),
    None,
);

if let Ok(projectile) = spawned.checked() {
    projectile.set_instigator(me.as_ref().upcast_to());
}

let spawned = GameplayStatics::finish_spawning_actor(spawned, &transform, None);

if let Ok(projectile) = Projectile::from_obj(spawned) {
    projectile.set_damage(self.damage());
}
}

The fifth argument is the owner. The same, with the world and typed parameters:

#![allow(unused)]
fn main() {
let params = SpawnParams {
    owner: Some(me.as_ref().upcast_to()),
    instigator: Some(pawn),
    collision: SpawnCollisionMethod::AlwaysSpawn,
};

let projectile = world.spawn_actor_deferred_of_class(self.projectile_class(), &transform, params)?;
Projectile::from_obj(projectile)?.set_damage(self.damage());
world.finish_spawning(&projectile.upcast_to(), &transform)?;
}

spawn_actor_deferred_of_class returns the actor already typed as the class’s T; SpawnParams::default() has no owner, no instigator and the class’s own collision handling. The collision handling method decides what happens when the spawn point is blocked:

Spawning a Rust class directly

A Rust class with no Blueprint child, or an engine class, is spawned by type:

#![allow(unused)]
fn main() {
let transform = FTransform::from_transform(Transform::new(DQuat::IDENTITY, location, DVec3::ONE));
let gem: UObjectRef<Gem> = world.spawn_actor(&transform)?;
}

Without a Blueprint child, no assets are assigned: give the actor its mesh in code, or prefer a SubclassOf property and a Blueprint.

An actor class without a root component ignores the spawn transform; Rusteal logs a warning when that happens.

Destroying

#![allow(unused)]
fn main() {
me.k2_destroy_actor();
me.set_life_span(5.0);
}

k2_destroy_actor destroys the actor at the end of the frame. set_life_span destroys it after that many seconds.

Finding actors

#![allow(unused)]
fn main() {
let world_context = self.as_ref().upcast_to();

let enemies = GameplayStatics::get_all_actors_of_class(
    world_context,
    SubclassOf::<Enemy>::base().upcast_to(),
);

let starts = GameplayStatics::get_all_actors_of_class_with_tag(
    world_context,
    SubclassOf::<PlayerStart>::base().upcast_to(),
    FName::new("Player1").handle(),
);

let player_pawn = GameplayStatics::get_player_pawn(world_context, 0);
let player_controller = GameplayStatics::get_player_controller(world_context, 0);
let game_mode = GameplayStatics::get_game_mode(world_context);
}

get_all_actors_of_class walks every actor of the level: fine on a key press or at the start of a level, too slow every frame for a big level. Keep the actors you need in a property, or let them register themselves with a subsystem.

Your Rust game mode, from any actor:

#![allow(unused)]
fn main() {
if let Ok(mut game_mode) = MyGameMode::from_obj(GameplayStatics::get_game_mode(world_context)) {
    game_mode.add_score(10);
}
}

Assets and objects

Assets assigned in the editor

Most assets reach Rust code through properties a Blueprint child fills: a UObjectRef<StaticMesh>, a UObjectRef<SoundBase>, a SubclassOf<Actor>. That is the recommended way: the cooker sees the reference and packages the asset.

#![allow(unused)]
fn main() {
#[uproperty(EditAnywhere)]
explosion_sound: UObjectRef<SoundBase>,
}

Loading an asset by path

#![allow(unused)]
fn main() {
let mesh: UObjectRef<StaticMesh> = load_object("/Game/Props/SM_Crate.SM_Crate")?;
let cube: UObjectRef<StaticMesh> = load_object("/Engine/BasicShapes/Cube")?;
}

A class, a Blueprint’s included, loads with load_class, checked against the class it must derive from:

#![allow(unused)]
fn main() {
let class: SubclassOf<AnimInstance> = load_class("/Game/Characters/ABP_Hero.ABP_Hero_C")?;
mesh.set_anim_instance_class(class.upcast_to());
}

A Blueprint’s class path ends in _C. load_object loads the asset if it is not loaded yet, and returns an error if there is none at that path. find_object finds it only if it is already loaded. The path is the asset’s object path, which Copy Reference in the Content Browser’s right-click menu puts on the clipboard.

An asset that only load_object uses is not found by the cooker, because nothing references it: list its directory in Project Settings > Packaging > Additional Asset Directories to Cook, or the packaged game will not have it. See Packaging a game.

Soft references: loading on demand

#![allow(unused)]
fn main() {
#[uproperty(EditAnywhere)]
boss_music: SoftObjectRef<SoundBase>,
}

SoftObjectRef<T> is Unreal’s TSoftObjectPtr<T>: an asset picked in the editor but not loaded with the object. It keeps big or rarely used assets out of memory until needed:

#![allow(unused)]
fn main() {
let music = self.boss_music().load_synchronous()?;
let loaded_already = self.boss_music().get();
}

load_synchronous loads it now (a hitch for a large asset); get returns it only if it is already loaded, or a null reference.

Creating objects

#![allow(unused)]
fn main() {
use bindings::manual::world_ext::new_object;

let entry = new_object::<MenuEntry>(&self.as_ref())?;
}

new_object::<T>(outer) creates an object of class T inside outer, as C++’s NewObject<T>(Outer). For actors, spawn instead (see Spawning actors); for widgets, see UI.

Keep the new object in a #[uproperty], or the garbage collector may collect it.

Timers

The goal: run something later, once or repeatedly: a respawn in three seconds, a weapon’s refire, a stamina tick.

#![allow(unused)]
fn main() {
use bindings::engine::KismetSystemLibrary;

#[uclass_impl]
impl Enemy {
    #[ufunction]
    fn remove_from_level(&mut self) {
        if let Ok(me) = self.as_ref().checked() {
            me.k2_destroy_actor();
        }
    }

    #[ufunction(Override)]
    fn receive_end_play(&mut self, _end_play_reason: u8) {
        KismetSystemLibrary::k2_clear_timer(self.as_ref().upcast_to(), "RemoveFromLevel");
    }
}

impl Enemy {
    fn die(&mut self) {
        KismetSystemLibrary::k2_set_timer(
            self.as_ref().upcast_to(),
            "RemoveFromLevel",
            5.0,
            false,
            None,
            None,
            None,
        );
    }
}
}

k2_set_timer is the Blueprint node Set Timer by Function Name: it calls a function of the object, by its Unreal name, after the given seconds. The function is any #[ufunction] of the class: remove_from_level is RemoveFromLevel.

k2_clear_timer stops a timer by the same object and name. Clear the timers of an object in its receive_end_play, so none fires on an object being destroyed. Setting a timer that is already running restarts it.

Use case: a looping timer at a fixed rate

The goal: update stamina thirty times a second, whatever the frame rate.

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_begin_play(&mut self) {
    KismetSystemLibrary::k2_set_timer(
        self.as_ref().upcast_to(),
        "SprintFixedTick",
        1.0 / 30.0,
        true,
        None,
        None,
        None,
    );
}

#[ufunction]
fn sprint_fixed_tick(&mut self) {
}
}

Use case: refire with a cooldown

The goal: an automatic weapon fires every refire_rate seconds while the trigger is held; a semi-automatic one fires once and waits.

#![allow(unused)]
fn main() {
#[ufunction]
fn fire(&mut self) {
    if !self.is_firing() {
        return;
    }

    let next = if self.b_full_auto() { "Fire" } else { "FireCooldownExpired" };

    KismetSystemLibrary::k2_set_timer(
        self.as_ref().upcast_to(),
        next,
        self.refire_rate(),
        false,
        None,
        None,
        None,
    );
}
}

Timers and the game’s time

Timers follow the game: they pause when the game is paused, and slow down with time dilation. To know the current game time:

#![allow(unused)]
fn main() {
let now = GameplayStatics::get_time_seconds(self.as_ref().upcast_to());
}

Comparing it with a stored time is the other way to handle cooldowns, without a timer:

#![allow(unused)]
fn main() {
if now - self.last_attack_time() > f64::from(self.cooldown()) {
    self.set_last_attack_time(now);
}
}

Every frame without an actor

receive_tick runs every frame on an actor. Code that is not an actor, or that must also run in the editor outside Play, can register a frame callback. See Work off the game thread, task::on_tick.

Traces and overlaps

The goal: ask the world what is in a line, a sphere or an area: what the player aims at, what a sword swing hits, what is caught in an explosion.

All of them are functions of KismetSystemLibrary, the Blueprint nodes Line Trace By Channel, Sphere Trace For Objects, Sphere Overlap Actors and the others.

Line trace: what the player aims at

#![allow(unused)]
fn main() {
use bindings::engine::{EDrawDebugTrace, ETraceTypeQuery, FHitResultExt, KismetSystemLibrary};

fn aim_point(&self, start: DVec3, direction: DVec3) -> DVec3 {
    let end = start + direction * 10_000.0;
    let me = self.as_ref().upcast_to::<Actor>();

    let (hit, out_hit) = KismetSystemLibrary::line_trace_single(
        me.upcast_to(),
        &FVector::from_dvec3(start),
        &FVector::from_dvec3(end),
        ETraceTypeQuery::TraceTypeQuery1,
        false,
        &[me],
        EDrawDebugTrace::None,
        true,
        &OwnedStruct::new(),
        &OwnedStruct::new(),
        None,
    );

    if hit {
        out_hit.as_ref().get_impact_point().to_dvec3()
    } else {
        end
    }
}
}

It returns whether something was hit and the FHitResult. Read the hit with as_ref(): get_impact_point(), get_impact_normal(), get_location(), get_component(), get_blocking_hit().

#![allow(unused)]
fn main() {
use bindings::engine::ActorComponentExt;

let hit_actor = out_hit.as_ref().get_component().checked()?.get_owner();
}

Sphere trace for objects: a sword swing

The goal: everything a swing touches between two points, pawns and movable props, not the floor.

#![allow(unused)]
fn main() {
use bindings::engine::{ECollisionChannel, EDrawDebugTrace, KismetSystemLibrary};

fn sweep(&self, start: DVec3, end: DVec3, radius: f32) -> Vec<OwnedStruct<FHitResult>> {
    let object_types: Vec<_> = [ECollisionChannel::ECC_Pawn, ECollisionChannel::ECC_WorldDynamic]
        .into_iter()
        .filter_map(object_type_query)
        .collect();

    let (_, hits) = KismetSystemLibrary::sphere_trace_multi_for_objects(
        self.as_ref().upcast_to(),
        &FVector::from_dvec3(start),
        &FVector::from_dvec3(end),
        radius,
        &object_types,
        false,
        &[],
        EDrawDebugTrace::None,
        true,
        &OwnedStruct::new(),
        &OwnedStruct::new(),
        None,
    );

    hits
}
}

“For objects” traces filter by object type, the Object Type of a collision preset, instead of a trace channel. object_type_query (from the prelude) turns a collision channel into the object type the function takes.

The single, multi, line, sphere, box and capsule variants (line_trace_multi, sphere_trace_single, box_trace_single_for_objects, capsule_trace_single…) follow the same pattern.

Overlap: an explosion

The goal: every actor within a radius.

#![allow(unused)]
fn main() {
let object_types: Vec<_> = [ECollisionChannel::ECC_Pawn, ECollisionChannel::ECC_PhysicsBody]
    .into_iter()
    .filter_map(object_type_query)
    .collect();

let ignored = [self.as_ref().upcast_to::<Actor>()];

let (_, actors) = KismetSystemLibrary::sphere_overlap_actors(
    self.as_ref().upcast_to(),
    &FVector::from_dvec3(center),
    500.0,
    &object_types,
    SubclassOf::<Actor>::base().upcast_to(),
    &ignored,
);

for actor in actors {
}
}

sphere_overlap_components returns the components instead, useful to push the physics bodies hit.

Overlaps of a component

A component with overlap events lists what overlaps it now:

#![allow(unused)]
fn main() {
let sphere = self.collision_sphere()?.checked()?;

for actor in sphere.get_overlapping_actors(Some(SubclassOf::<Enemy>::base().upcast_to())) {
}
}

To react when something starts overlapping, bind the component’s delegate. See Delegates.

What is under the mouse

#![allow(unused)]
fn main() {
let controller = self.as_ref().checked()?;
let (hit, out_hit) = controller.get_hit_result_under_cursor_by_channel(ETraceTypeQuery::TraceTypeQuery1, true);

if hit {
    let point = out_hit.as_ref().get_location().to_dvec3();
}
}

get_hit_result_under_finger_by_channel(ETouchIndex::Touch1, ...) is the same for touch.

Delegates

Delegates are how the engine says “this happened” to whoever is listening: an actor overlapped, a component was hit, a montage ended, a pawn was destroyed. Rust code listens with a closure or with a function of its class, and Rust classes declare their own delegates for Blueprints and other Rust code to listen to.

Use case: reacting to an overlap with a function

The goal: a jump pad launches any character that steps on it.

#![allow(unused)]
fn main() {
use bindings::engine::{
    BoxComponent, Character, CharacterExt, ECollisionChannel, ECollisionEnabled,
    ECollisionResponse, PrimitiveComponentExt, SceneComponent
};

#[uclass(parent = Actor)]
pub struct JumpPad {
    #[component(root)]
    root: SceneComponent,

    #[component(attach = "root")]
    r#box: BoxComponent,

    #[uproperty(EditAnywhere, default = 1000.0)]
    z_strength: f32,
}

#[uclass_impl]
impl JumpPad {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let r#box = self.r#box()?.checked()?;
        r#box.set_collision_enabled(ECollisionEnabled::QueryOnly);
        r#box.set_collision_response_to_all_channels(ECollisionResponse::ECR_Ignore);
        r#box.set_collision_response_to_channel(ECollisionChannel::ECC_Pawn, ECollisionResponse::ECR_Overlap);
        Ok(())
    }

    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        let me = self.as_ref();

        if let Err(e) = me
            .checked()
            .and_then(|actor| actor.on_actor_begin_overlap().add_ufunction(&me, "BeginOverlap"))
        {
            log::warn!("[MyGame] jump pad overlap: {e}");
        }
    }

    #[ufunction]
    fn begin_overlap(&mut self, _overlapped_actor: UObjectRef<Actor>, other_actor: UObjectRef<Actor>) {
        let Ok(character) = other_actor.cast::<Character>().and_then(|c| c.checked()) else {
            return;
        };

        let launch = DVec3::Z * f64::from(self.z_strength());
        character.launch_character(&FVector::from_dvec3(launch), false, true);
    }
}
}

add_ufunction(&target, "Function") binds a #[ufunction] of target by its Unreal name, as C++’s AddDynamic does. The function takes the delegate’s parameters, in order. Binding the same function again does nothing, so it is safe in receive_begin_play.

For an actor’s own overlaps, overriding receive_actor_begin_overlap is simpler still (see Engine events); delegates are for a component’s overlaps and for another object’s events.

Use case: a component’s overlap

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_begin_play(&mut self) {
    let me = self.as_ref();

    let bound = self.trigger().and_then(|trigger| {
        trigger.checked()?.on_component_begin_overlap().add_ufunction(&me, "OnTriggerOverlap")
    });

    if let Err(e) = bound {
        log::warn!("[MyGame] trigger overlap: {e}");
    }
}

#[ufunction]
#[allow(clippy::too_many_arguments)]
fn on_trigger_overlap(
    &mut self,
    _overlapped_component: UObjectRef<PrimitiveComponent>,
    other_actor: UObjectRef<Actor>,
    _other_comp: UObjectRef<PrimitiveComponent>,
    _other_body_index: i32,
    _from_sweep: bool,
    _sweep_result: UStructRef<FHitResult>,
) {
}
}

The common component delegates and their parameters:

Use case: listening with a closure

The goal: the player controller respawns the player when its pawn is destroyed.

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_possess(&mut self, possessed_pawn: UObjectRef<Pawn>) {
    let controller: UObjectRef<PlayerController> = self.as_ref();

    let bound = possessed_pawn.checked().and_then(|pawn| {
        pawn.on_destroyed().add(move |_destroyed_actor| {
            if let Ok(mut me) = MyPlayerController::from_obj(controller) {
                me.respawn();
            }
        })
    });

    match bound {
        Ok(binding) => binding.detach(),
        Err(e) => log::warn!("[MyGame] cannot watch the pawn: {e}"),
    }
}
}

add(closure) binds a Rust closure, which receives the delegate’s parameters. It returns a binding:

• dropping the binding unbinds the closure;
• detach() keeps the closure bound for as long as the object that raises the delegate lives.

The closure captures UObjectRefs, which are Copy, and turns them back into Rust classes with from_obj when it runs: by then the object may be gone, and from_obj says so.

Closures and add_ufunction both work on any delegate the engine exposes to Blueprints: animation (on_montage_ended), AI perception (on_target_perception_updated), movement (on_projectile_stop), AI moves (receive_move_completed), EQS (on_query_finished_event). See the Gameplay recipes.

Use case: a delegate of your own

The goal: a health component announces every change, and a UMG widget, a Blueprint or other Rust code updates itself.

#![allow(unused)]
fn main() {
#[uclass(parent = ActorComponent)]
pub struct Health {
    #[uproperty(EditAnywhere, default = 100.0)]
    max_health: f32,

    #[uproperty(VisibleAnywhere)]
    current: f32,
}

#[uclass_impl]
impl Health {
    #[udelegate]
    pub fn on_health_changed(&self, current: f32, max: f32) {}

    #[ufunction]
    pub fn take_damage(&mut self, amount: f32) {
        self.set_current((self.current() - amount).max(0.0));
        self.on_health_changed(self.current(), self.max_health());
    }
}
}

#[udelegate] declares a multicast delegate, C++’s DECLARE_DYNAMIC_MULTICAST_DELEGATE with a BlueprintAssignable property. The method’s body stays empty; calling it broadcasts to every listener. The macro adds two methods for Rust listeners:

#![allow(unused)]
fn main() {
health.on_health_changed_add(|current, max| {
})?.detach();

health.on_health_changed_add_ufunction(&hud.as_ref(), "RefreshHealth")?;
}

Its parameters are scalars, objects, classes and structs (as &OwnedStruct<T>; a closure receives an OwnedStruct<T>). #[udelegate(name = "...")] gives the Unreal name when PascalCase is not it.

In the editor

In a Blueprint that holds the component, select the component in the Components panel; in the Details panel, the Events section lists On Health Changed with a + button that adds the bound event to the graph. Or, from any reference to the component, drag a wire and search for Bind Event to On Health Changed.

Screenshot: the Events section of the Details panel listing On Health Changed for a Rust component. (images/engine_api/udelegate_events.png)

Delegates that cannot be bound

Only delegates exposed to Blueprints can be bound. Some engine delegates exist only in C++ (UPathFollowingComponent::OnRequestFinished, for one); for those, look for a Blueprint-exposed delegate raised for the same thing (the AI controller’s ReceiveMoveCompleted).

Dynamic calls

The goal: call a function the bindings do not have: one a Blueprint declares, one of a module the project does not bind, one of a plugin’s Rust class.

#![allow(unused)]
fn main() {
use rusteal_runtime::runtime::DynamicCall;

let mut call = DynamicCall::new(&door, "OpenDoor")?;
call.set("Speed", 2.0f32)?;
let result = call.call()?;
let opened: bool = result.get("ReturnValue")?;
}

DynamicCall calls any reflected function by name, with the engine’s reflection, as a Blueprint node does:

Values are passed as they are in memory: bool, numbers, f32 for float, f64 for double, an object’s handle (object.raw()), an FName’s handle.

Use case: a function of a Blueprint

The goal: Rust code calls a function a designer wrote in a Blueprint.

#![allow(unused)]
fn main() {
let mut call = DynamicCall::new(&actor, "PlayIntro")?;
call.set("Delay", 0.5f32)?;
call.call()?;
}

The function name and the parameter names are the ones the Blueprint shows. A Blueprint function renamed in the editor breaks the call at runtime, with a FunctionNotFound error, not at compile time.

When to prefer something else

Dynamic calls skip the compiler’s checks: a wrong name or a wrong type is found when the game runs. Prefer:

• the bindings, for engine functions (bind the module in rusteal.toml if it is missing; see Binding more of the engine);
• a BlueprintImplementableEvent, when Rust calls into a Blueprint child of a Rust class (see Functions);
• an interface, when the object may be one of several classes (see Interfaces).

Errors

The engine fails in ways C++ code tends to crash on: an object destroyed while something still points to it, a cast to the wrong class, a function that is not there. In Rusteal those failures are values: RustealResult<T>, an alias of Result<T, RustealError>.

What an error says

A RustealError says what went wrong, on which Unreal object, why Unreal refused when it says, and where in your Rust code:

invalid cast: expected Pawn (object StaticMeshActor_0 of class StaticMeshActor)
    at my-game/src/turret.rs:42:23
while aiming at the target
    at my-game/src/turret.rs:30:14

• What: its kind, and the name involved (the property, the function, the class a cast expected).
• On what: the object’s name and its class, when the error came from an object.
• Why, says Unreal: when the engine side knows more than the kind, its reason, after Unreal:: type mismatch: Unreal: Ammo (IntProperty of Turret) is not a BoolProperty, index out of range: Unreal: index 5 past the 3 elements of Targets (ArrayProperty of Turret).
• Where: the file and line of the call that failed in your code, not inside Rusteal: the functions that return a RustealResult pass their caller’s location along.
• While doing what: the contexts your code added on the way up (below).
• Caused by: the error underneath, when it came from another library (a file that did not open, a number that did not parse).

It prints three ways:

e.log(LOG_WARNING) reports it (see In the editor).

In the editor

A reported error goes to two places:

• the Output Log, as the report above, followed by the Blueprint call stack when a Blueprint was running;
• the Rusteal tab of the Message Log (Window > Message Log, then Rusteal in its list), one line per error. Its object is a link that selects it; an object of Play In Editor, once Play has stopped, selects the same actor in the level. Its Rust file and line are a link that opens the file at that line in the IDE set in Editor Preferences > General > Source Code. An error also shows a notification, at most once every few seconds.

Screenshot: the Message Log’s Rusteal tab with an invalid cast error, its object link and its errors.rs:42 link. (images/engine_api/message_log.png)

Panics are reported the same way, with the file and line of the panic!, the unwrap() or the index out of bounds.

Use case: a function that can fail

The goal: a Blueprint calls a Rust function that can fail, and the failure is a Blueprint runtime error on the node that called it, not a silent default.

A #[ufunction] (or an Override) returns a RustealResult<T> when it can fail. Unreal sees a function returning T (nothing for RustealResult<()>):

#![allow(unused)]
fn main() {
#[ufunction]
fn reload(&mut self) -> RustealResult<i32> {
    let magazine = self.magazine().checked()?;
    Ok(magazine.rounds())
}

#[ufunction(Override)]
fn receive_begin_play(&mut self) -> RustealResult<()> {
    self.setup()
}
}

An Err is reported with the function’s name (Turret::Reload failed: ...) and the function returns the default value (0, false, a null reference). Called from a Blueprint, it is also a Blueprint runtime error: in Play In Editor the Message Log opens on it with a link to the node, as for an Accessed None, and with Blueprint Exceptions breakpoints on, the debugger stops there.

Screenshot: a Blueprint runtime error raised by a Rust function, with the link to the calling node in the Message Log. (images/engine_api/blueprint_error.png)

The same panic, unwrap or ? inside a function that does not return a RustealResult is still caught: a panic is reported as above, and the function returns the default value.

Use case: Result inside, log at the edge

The goal: a turret’s setup can fail in several ways, and the log says which, where and on what.

Events and functions the engine calls cannot return an error to anyone. Put the work in a method that returns RustealResult, use ? in it, and log the error in the event:

#![allow(unused)]
fn main() {
use rusteal_runtime::runtime::{ErrorContext, LOG_WARNING, RustealResult};

#[ufunction(Override)]
fn receive_begin_play(&mut self) {
    if let Err(e) = self.setup() {
        e.log(LOG_WARNING);
    }
}

impl Turret {
    fn setup(&mut self) -> RustealResult<()> {
        let mesh = self.mesh()?.checked()?;
        let target = self.target().cast::<Pawn>().context("aiming at the target")?;
        let range: f32 = self.range_text().parse().context("reading the range")?;
        Ok(())
    }
}
}

.context("...") adds what the code was doing to the error, with its own line; contexts read outermost first in {e}. It works on any Result whose error is a Rust error (a RustealError, an std::io::Error, a serde_json::Error…), and on Option, where None becomes an error with that message:

#![allow(unused)]
fn main() {
let spawn = self.find_spawn_point().context("no spawn point in the level")?;
}

Errors from other libraries

? turns the standard library’s errors (std::io::Error, ParseIntError, ParseFloatError, Utf8Error…) into a RustealError by itself, keeping them as the cause and recording the line of the ?. Another crate’s error goes through .context("..."), or .map_err(RustealError::other) with no context.

RustealError implements std::error::Error, so it goes the other way too: into anyhow::Error, a Box<dyn Error>, or a thiserror enum of your own.

Telling errors apart

kind() gives an ErrorKind to match on:

#![allow(unused)]
fn main() {
match other_actor.cast::<Character>() {
    Ok(character) => self.hit(character),
    Err(e) if e.is(ErrorKind::InvalidCast) => {}
    Err(e) => return Err(e),
}
}

Where a failure is a normal case (no target, the player is not a character), let else or if let say it without an error:

#![allow(unused)]
fn main() {
let Ok(character) = other_actor.cast::<Character>() else {
    return;
};
}

Your own errors

#![allow(unused)]
fn main() {
use rusteal_runtime::runtime::{ErrorKind, RustealResult, bail, ensure};

fn spend(&mut self, cost: i32) -> RustealResult<()> {
    ensure!(cost >= 0, "a cost of {cost}");

    if cost > self.gold() {
        bail!(ErrorKind::InvalidOperation, "{cost} gold, {} in the purse", self.gold());
    }

    self.set_gold(self.gold() - cost);
    Ok(())
}
}

bail! returns an error with a message, of the kind given first or Other without one; ensure! does when its condition is false. RustealError::msg("..."), RustealError::with_message(kind, "...") and the constructors named after each kind (RustealError::null_argument(), RustealError::invalid_operation("...")) make one to return yourself, and .on(&actor) names the object it concerns.

Panics

A panic in your code does not crash the editor: it is caught where the engine called into Rust, reported as an error with its file and line (see In the editor), and the call returns. The object may be left half updated, so a panic is a bug to fix, not a way to handle errors. unwrap() on a RustealResult is a panic waiting for an object to be destroyed at the wrong moment: prefer ?, let else or unwrap_or_default().

Gameplay recipes

Complete use cases, each one taken from a Rusteal template, where it runs as part of a playable game. To see one working, create the template it comes from and play it:

rusteal new CombatLab --template third-person --variant combat

The code in these recipes is trimmed to what the use case needs. The template’s source, in Rust/<crate>/src/, has the rest.

Character movement and input

The goal: a character that walks, looks around and jumps with the keyboard and mouse, a gamepad or touch, with Enhanced Input.

Input in Rusteal works as in the engine’s C++ templates:

1. the player controller adds the Input Mapping Contexts when the game starts;
2. the pawn binds each Input Action to one of its functions once its input component exists;
3. a Blueprint child of each assigns the assets.

The player controller

#![allow(unused)]
fn main() {
use bindings::engine::{ControllerExt, PlayerController};
use bindings::enhanced_input::{EnhancedInputLocalPlayerSubsystemExt, InputMappingContext};
use bindings::prelude::*;
use rusteal_runtime::runtime::{OwnedStruct, RustealResult, UObjectRef, UeArray };
use rusteal_runtime::{uclass, uclass_impl};

#[uclass(parent = PlayerController)]
pub struct MyPlayerController {
    #[uproperty(EditAnywhere)]
    default_mapping_contexts: UeArray<UObjectRef<InputMappingContext>>,
}

#[uclass_impl]
impl MyPlayerController {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        if let Err(e) = self.add_mapping_contexts() {
            log::warn!("[MyGame] input mapping contexts failed: {e}");
        }
    }
}

impl MyPlayerController {
    fn add_mapping_contexts(&self) -> RustealResult<()> {
        let me: UObjectRef<PlayerController> = self.as_ref();

        if !me.checked()?.is_local_controller() {
            return Ok(());
        }

        let subsystem = enhanced_input_subsystem(me)?.checked()?;

        for context in self.default_mapping_contexts().to_vec()? {
            subsystem.add_mapping_context(context, 0, &OwnedStruct::new());
        }

        Ok(())
    }
}
}

enhanced_input_subsystem(controller) is the controller’s Enhanced Input Local Player Subsystem, where mapping contexts are added. A player controller binds its own actions in receive_begin_play too, which is where C++ does it (SetupInputComponent).

The character

#![allow(unused)]
fn main() {
use bindings::engine::{
    Character, CharacterExt, CharacterMovementComponentExt, ControllerExt, PawnExt
};
use bindings::enhanced_input::{ETriggerEvent, FInputActionValue, InputAction};
use bindings::prelude::*;
use rusteal_runtime::runtime::{RustealResult, UObjectRef, UStructRef };
use rusteal_runtime::{uclass, uclass_impl};

#[uclass(parent = Character)]
pub struct MyCharacter {
    #[uproperty(EditAnywhere, category = "Input")]
    jump_action: UObjectRef<InputAction>,

    #[uproperty(EditAnywhere, category = "Input")]
    move_action: UObjectRef<InputAction>,

    #[uproperty(EditAnywhere, category = "Input")]
    look_action: UObjectRef<InputAction>,
}

#[uclass_impl]
impl MyCharacter {
    #[ufunction(Override)]
    fn receive_restarted(&mut self) {
        if let Err(e) = self.bind_input() {
            log::warn!("[MyGame] input binding failed: {e}");
        }
    }

    #[ufunction]
    fn r#move(&mut self, value: UStructRef<FInputActionValue>) {
        let axis = value.axis2d();

        let Ok(me) = self.as_ref().checked() else {
            return;
        };

        let Ok(controller) = me.get_controller().checked() else {
            return;
        };

        let yaw = controller.get_control_rotation().to_rotator().yaw.to_radians();
        let forward = DVec3::new(yaw.cos(), yaw.sin(), 0.0);
        let right = DVec3::new(-yaw.sin(), yaw.cos(), 0.0);

        me.add_movement_input(&FVector::from_dvec3(forward), Some(axis.y as f32), Some(false));
        me.add_movement_input(&FVector::from_dvec3(right), Some(axis.x as f32), Some(false));
    }

    #[ufunction]
    fn look(&mut self, value: UStructRef<FInputActionValue>) {
        let axis = value.axis2d();

        if let Ok(me) = self.as_ref().checked() {
            me.add_controller_yaw_input(axis.x as f32);
            me.add_controller_pitch_input(axis.y as f32);
        }
    }
}

impl MyCharacter {
    fn bind_input(&self) -> RustealResult<()> {
        let me = self.as_ref();
        let pawn = me.checked()?;

        if !pawn.is_player_controlled() || !pawn.is_locally_controlled() {
            return Ok(());
        }

        bind_action(&me, self.jump_action(), ETriggerEvent::Started, "Jump")?;
        bind_action(&me, self.jump_action(), ETriggerEvent::Completed, "StopJumping")?;
        bind_action(&me, self.move_action(), ETriggerEvent::Triggered, "Move")?;
        bind_action(&me, self.look_action(), ETriggerEvent::Triggered, "Look")?;

        Ok(())
    }
}
}

• receive_restarted is where a pawn binds input: it runs when a controller possesses the pawn, once the input component exists. It replaces C++’s SetupPlayerInputComponent.
• bind_action(&pawn, action, trigger, "Function") binds an action’s trigger event to a function by its Unreal name. Engine functions work as well: "Jump" and "StopJumping" are ACharacter’s.
• The value of an action reads as get_bool(), axis1d(), axis2d() or axis3d(), by its Value Type.

What a bound function can take

The function takes nothing, or a leading part of these, in order:

#![allow(unused)]
fn main() {
#[ufunction]
fn charge(&mut self, _value: UStructRef<FInputActionValue>, elapsed_seconds: f32) {
    let charged = elapsed_seconds >= 1.5;
}
}

In the editor

The engine templates already have the input actions (IA_Move, IA_Look, IA_Jump) and a mapping context (IMC_Default). For a project without them:

1. In the Content Browser, right-click and choose Input > Input Action. Create IA_Move and, in its Details, set Value Type to Axis2D (Vector2D). Do the same for IA_Look, and create IA_Jump with Digital (bool).
2. Right-click and choose Input > Input Mapping Context. Name it IMC_Default, open it, and add a mapping for each action with the + next to Mappings: IA_Jump to Space Bar, IA_Look to Mouse XY 2D-Axis, IA_Move to W, S, A and D with the Swizzle Input Axis Values and Negate modifiers as the engine templates do.
3. Create a Blueprint child of MyPlayerController (see Blueprint children), and in its Class Defaults add IMC_Default to Default Mapping Contexts.
4. Create a Blueprint child of MyCharacter, and in its Class Defaults, under Input, set Jump Action, Move Action and Look Action.
5. Set both Blueprints in the game mode (see Game flow).

Screenshot: the Class Defaults of the character Blueprint with the three input actions assigned. (images/recipes/input_actions_assigned.png)

Screenshot: IMC_Default with the W, A, S, D mappings and their modifiers. (images/recipes/imc_default.png)

If nothing moves, the Output Log usually says why: no mapping contexts added, or a function name that does not exist.

Touch controls

The templates add a virtual joystick widget on touch screens:

#![allow(unused)]
fn main() {
use rusteal_runtime::runtime::input::should_display_touch_interface;

if should_display_touch_interface() {
    let widget = create_widget_of_class(&me, self.mobile_controls_widget_class())?;
    widget.checked()?.add_to_player_screen(Some(0));
}
}

should_display_touch_interface() is the engine’s own check for a touch screen. The widget class is a SubclassOf<UserWidget> property, which the template’s player controller Blueprint sets to the engine template’s mobile controls widget.

Movement settings

The movement itself is the character movement component’s, tuned in Class defaults:

#![allow(unused)]
fn main() {
let movement = me.get_character_movement().checked()?;
movement.set_orient_rotation_to_movement(true);
movement.set_max_walk_speed(500.0);
movement.set_jump_z_velocity(500.0);
movement.set_air_control(0.35);
}

Cameras

Use case: a third person camera on a spring arm

The goal: a camera behind the character that orbits with the mouse and pulls in when a wall is in the way.

#![allow(unused)]
fn main() {
use bindings::engine::{CameraComponent, CameraComponentExt, SpringArmComponent, SpringArmComponentExt};

#[uclass(parent = Character)]
pub struct Hero {
    #[component(attach = "root_component")]
    camera_boom: SpringArmComponent,

    #[component(attach = "camera_boom", socket = "SpringEndpoint")]
    follow_camera: CameraComponent,
}

#[uclass_impl]
impl Hero {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        me.set_use_controller_rotation_pitch(false);
        me.set_use_controller_rotation_yaw(false);
        me.set_use_controller_rotation_roll(false);

        let boom = self.camera_boom()?.checked()?;
        boom.set_target_arm_length(400.0);
        boom.set_use_pawn_control_rotation(true);

        self.follow_camera()?.checked()?.set_use_pawn_control_rotation(false);

        Ok(())
    }
}
}

The spring arm follows the controller’s rotation, which the look input changes; the character does not turn with it, and the movement component turns it toward where it walks (set_orient_rotation_to_movement(true)).

A smoother camera adds lag: boom.set_enable_camera_lag(true) and boom.set_camera_lag_speed(10.0).

Use case: a first person camera

The goal: a camera at the head, with arms only the player sees and a body only others see.

#![allow(unused)]
fn main() {
use bindings::engine::{
    CameraComponent, CameraComponentExt, EFirstPersonPrimitiveType, PrimitiveComponentExt,
    SceneComponentExt, SkeletalMeshComponent
};

#[uclass(parent = Character)]
pub struct FirstPersonHero {
    #[component(attach = "mesh", name = "First Person Mesh")]
    first_person_mesh: SkeletalMeshComponent,

    #[component(attach = "first_person_mesh", socket = "head", name = "First Person Camera")]
    first_person_camera: CameraComponent,
}

#[uclass_impl]
impl FirstPersonHero {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let arms = self.first_person_mesh()?.checked()?;
        arms.set_only_owner_see(true);
        arms.set_first_person_primitive_type(EFirstPersonPrimitiveType::FirstPerson);
        arms.set_collision_profile_name(FName::new("NoCollision").handle(), Some(true));

        let camera = self.first_person_camera()?.checked()?;
        camera.set_use_pawn_control_rotation(true);
        camera.set_enable_first_person_field_of_view(true);
        camera.set_first_person_field_of_view(70.0);

        let body = self.as_ref().checked()?.get_mesh().checked()?;
        body.set_owner_no_see(true);
        body.set_first_person_primitive_type(EFirstPersonPrimitiveType::WorldSpaceRepresentation);

        Ok(())
    }
}
}

The Blueprint child assigns the arms’ and the body’s skeletal meshes and Animation Blueprints.

Use case: limiting how far the player looks up and down

The goal: a camera manager that clamps the pitch.

#![allow(unused)]
fn main() {
use bindings::engine::{PlayerCameraManager, PlayerCameraManagerExt};

#[uclass(parent = PlayerCameraManager)]
pub struct MyCameraManager {}

#[uclass_impl]
impl MyCameraManager {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        me.set_view_pitch_min(-70.0);
        me.set_view_pitch_max(80.0);
        Ok(())
    }
}
}

The player controller uses it, set in its own class defaults:

#![allow(unused)]
fn main() {
self.as_ref().checked()?.set_player_camera_manager_class(
    SubclassOf::<MyCameraManager>::base().upcast_to(),
);
}

Use case: a side scroller camera computed every frame

The goal: a camera that follows the character along X, stays within the level’s bounds, and moves up and down smoothly.

A camera manager decides the camera’s location, rotation and field of view every frame in BlueprintUpdateCamera:

#![allow(unused)]
fn main() {
#[uclass(parent = PlayerCameraManager)]
pub struct SideCameraManager {
    #[uproperty(EditAnywhere, default = 400.0)]
    current_zoom: f32,

    #[uproperty(EditAnywhere, default = -1000.0)]
    camera_x_min_bounds: f32,

    #[uproperty(EditAnywhere, default = 1000.0)]
    camera_x_max_bounds: f32,
}

#[uclass_impl]
impl SideCameraManager {
    #[ufunction(Override)]
    fn blueprint_update_camera(
        &mut self,
        camera_target: UObjectRef<Actor>,
        new_camera_location: UStructRef<FVector>,
        new_camera_rotation: UStructRef<FRotator>,
        new_camera_fov: OutRef<f32>,
    ) -> bool {
        let Ok(target) = camera_target.checked() else {
            return false;
        };

        let location = target.k2_get_actor_location().to_dvec3();
        let x = location.x.clamp(f64::from(self.camera_x_min_bounds()), f64::from(self.camera_x_max_bounds()));

        new_camera_location.set_x(x);
        new_camera_location.set_y(location.y + f64::from(self.current_zoom()));
        new_camera_location.set_z(location.z);

        new_camera_rotation.set_pitch(0.0);
        new_camera_rotation.set_yaw(-90.0);
        new_camera_rotation.set_roll(0.0);

        new_camera_fov.set(65.0);

        true
    }
}
}

The event writes the camera into the structs it receives (UStructRef, written in place) and the field of view into an OutRef, and returns true to use them. The side-scrolling template adds smoothing with the engine’s interpolation formulas, written as plain Rust in its model.rs and tested there.

Animation

Use case: playing a montage and knowing when it ends

The goal: an attack plays its animation montage, and the character can attack again once it ends.

#![allow(unused)]
fn main() {
use bindings::engine::{AnimInstance, AnimInstanceExt, AnimMontage, Character, CharacterExt, SkeletalMeshComponentExt};

#[uclass(parent = Character)]
pub struct Fighter {
    #[uproperty(EditAnywhere, category = "Combat")]
    attack_montage: UObjectRef<AnimMontage>,

    is_attacking: bool,
    montage_end_bound: bool,
}

impl Fighter {
    fn attack(&mut self) -> RustealResult<()> {
        if self.is_attacking() {
            return Ok(());
        }

        let anim_instance = self.as_ref().checked()?.get_mesh().checked()?.get_anim_instance();
        self.bind_montage_end(anim_instance)?;

        anim_instance.checked()?.montage_play(self.attack_montage(), Some(1.0), None, Some(0.0), Some(true));
        self.set_is_attacking(true);

        Ok(())
    }

    fn bind_montage_end(&mut self, anim_instance: UObjectRef<AnimInstance>) -> RustealResult<()> {
        if self.montage_end_bound() {
            return Ok(());
        }

        let character: UObjectRef<Character> = self.as_ref();

        anim_instance
            .checked()?
            .on_montage_ended()
            .add(move |montage, _interrupted| {
                if let Ok(mut me) = Fighter::from_obj(character)
                    && montage == me.attack_montage()
                {
                    me.set_is_attacking(false);
                }
            })?
            .detach();

        self.set_montage_end_bound(true);

        Ok(())
    }
}
}

• montage_play(montage, play_rate, return_value_type, time_to_start, stop_all_montages) plays it; None keeps a default.
• on_montage_ended is the anim instance’s delegate for every montage that ends, interrupted or not: the closure checks which one ended.
• A Rust-only flag keeps the closure from being bound twice.

Other montage controls on the anim instance:

#![allow(unused)]
fn main() {
anim_instance.montage_jump_to_section(FName::new("Attack2").handle(), Some(montage));
anim_instance.montage_stop(0.1, Some(montage));
}

Use case: code at a frame of an animation

The goal: the sword’s damage trace runs at the exact frame of the swing, set by an animator in the montage.

#![allow(unused)]
fn main() {
use bindings::engine::{ActorComponentExt, AnimNotify, AnimSequenceBase, FAnimNotifyEventReference, SkeletalMeshComponent};

#[uclass(parent = AnimNotify)]
pub struct AnimNotifyAttackTrace {
    #[uproperty(EditAnywhere)]
    attack_bone_name: FName,
}

#[uclass_impl]
impl AnimNotifyAttackTrace {
    #[ufunction(Override, name = "Received_Notify")]
    fn notify(
        &self,
        mesh_comp: UObjectRef<SkeletalMeshComponent>,
        _animation: UObjectRef<AnimSequenceBase>,
        _event_reference: UStructRef<FAnimNotifyEventReference>,
    ) -> bool {
        let Ok(owner) = mesh_comp.checked().map(|mesh| mesh.get_owner()) else {
            return false;
        };

        if let Ok(mut fighter) = Fighter::from_obj(owner) {
            fighter.do_attack_trace(&self.attack_bone_name().to_string_lossy());
        }

        true
    }
}
}

A class whose parent is AnimNotify is a notify animators place on a timeline. It receives the skeletal mesh component that plays the animation; its owner is the character.

In the editor

1. Open the montage (AM_Attack).
2. In the Notifies track, right-click at the frame of the hit and choose Add Notify > Anim Notify Attack Trace.
3. Select the notify, and in the Details panel set Attack Bone Name (hand_r).
4. Save.

Screenshot: a montage’s Notifies track with the Rust notify placed at the hit frame, and its Attack Bone Name in the Details panel. (images/recipes/anim_notify.png)

Use case: gameplay state for the Animation Blueprint

An Animation Blueprint reads the character’s state through BlueprintPure functions:

#![allow(unused)]
fn main() {
#[ufunction(BlueprintPure)]
fn has_double_jumped(&self) -> bool {
    self.state().has_double_jumped
}
}

In the Animation Blueprint’s Event Graph, cast Try Get Pawn Owner to the character’s class, call Has Double Jumped on it, and store the result in a variable the AnimGraph uses.

Use case: the Animation Blueprint’s logic in Rust

The goal: the logic of an Animation Blueprint’s Event Graph (reading the owner, easing values toward their targets) in Rust, and the AnimGraph left to the Animation Blueprint, which reads the values the Rust class keeps.

The Rust class is the Animation Blueprint’s parent, an AnimInstance:

#![allow(unused)]
fn main() {
use bindings::engine::{AnimInstance, AnimInstanceExt, SkeletalMeshComponent};

#[uclass(parent = SkeletalMeshComponent)]
pub struct MannequinsXR {
    #[uproperty(EditAnywhere, BlueprintReadWrite, category = "Hand", default = false)]
    b_mirror: bool,
}

#[uclass(parent = AnimInstance)]
pub struct HandAnimInstance {
    #[uproperty(BlueprintReadWrite, category = "Pose", default = 0.0)]
    pose_alpha_point: f32,

    #[uproperty(BlueprintReadOnly, category = "Pose", default = 0.0)]
    current_pose_alpha_point: f64,

    #[uproperty(BlueprintReadOnly, category = "Pose", default = false)]
    b_mirror: bool,
}

#[uclass_impl]
impl HandAnimInstance {
    #[ufunction(Override)]
    fn blueprint_initialize_animation(&mut self) {
        let mirror = self
            .as_ref()
            .checked()
            .ok()
            .and_then(|anim| MannequinsXR::from_obj(anim.get_owning_component()).ok())
            .is_some_and(|hand| hand.b_mirror());

        self.set_b_mirror(mirror);
    }

    #[ufunction(Override)]
    fn blueprint_update_animation(&mut self, delta_time_x: f32) {
        self.set_current_pose_alpha_point(model::f_interp_to(
            self.current_pose_alpha_point(),
            f64::from(self.pose_alpha_point()),
            f64::from(delta_time_x),
            13.0,
        ));
    }
}
}

blueprint_initialize_animation runs once, when the mesh creates the instance; blueprint_update_animation every animation update, on the game thread, with the frame’s time. What the AnimGraph reads are the Rust properties, BlueprintReadOnly or BlueprintReadWrite. The pawn sets the targets on the instance its hand mesh has:

#![allow(unused)]
fn main() {
let anim = hand.checked()?.get_anim_instance();

if let Ok(mut hand_anim) = HandAnimInstance::from_obj(anim) {
    hand_anim.set_pose_alpha_point(1.0);
}
}

In the editor

1. Open the Animation Blueprint (ABP_MannequinsXR), and in the toolbar click Class Settings.
2. In the Details panel, set Parent Class to HandAnimInstance.
3. In the My Blueprint panel, Variables lists the Rust properties under Pose; drag Current Pose Alpha Point into the AnimGraph and connect it where the old variable was.
4. Delete the old variables and the Event Graph nodes the Rust class replaces, then click Compile.

Screenshot: the AnimGraph of ABP_MannequinsXR, with Current Pose Alpha Point coming from the Rust parent. (images/recipes/anim_rust_parent.png)

The variable types follow the Blueprint’s: a Blueprint Float that is double precision is f64, one stored in single precision is f32. When they match, the AnimGraph’s nodes take the Rust property in place of a variable of the same name.

Template: vr.

Use case: a mannequin that copies the player

The goal: a mannequin in the level that walks, runs, jumps and lands when the player does, as the Intro To Unreal template’s copycat.

The mannequin feature’s CopycatAnimInstance reads player 0’s character every animation update and keeps what an AnimGraph needs:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn blueprint_update_animation(&mut self, _delta_time_x: f32) {
    if !self.character().is_valid() || !self.movement_component().is_valid() {
        self.find_character();
    }

    let (Ok(anim), Ok(character), Ok(movement)) = (
        self.as_ref().checked(),
        self.character().checked(),
        self.movement_component().checked(),
    ) else {
        return;
    };

    let velocity = movement.get_velocity();
    let ground_speed = ground_speed(velocity.to_dvec3());
    let direction = f64::from(anim.calculate_direction(&velocity, &character.k2_get_actor_rotation()));

    self.set_ground_speed(ground_speed);
    self.set_direction(clamp_direction(direction, movement.get_orient_rotation_to_movement()));
    self.set_should_move(should_move(ground_speed, movement.get_current_acceleration().to_dvec3()));
    self.set_is_falling(movement.is_falling());
}
}

ground_speed, should_move and clamp_direction are plain functions, tested with cargo test: the speed ignores the vertical axis, the mannequin moves only above 0.01 cm/s and while the character accelerates, and the direction stays within 45 degrees when the character turns toward its movement. ABP_Copycat is a child of CopycatAnimInstance whose AnimGraph blends idle, walk and run by Ground Speed and switches to a jump on Is Falling. Setting the instance’s Source Character copies another character than the player.

Any skeletal mesh of the SK_Mannequin skeleton takes it: Manny, Quinn, or a mannequin of your own on that skeleton.

Use case: a hand that reaches for a target

The goal: a mannequin plays its idle and, when a target comes within arm’s length, its right hand goes to it.

The animation plays on a hidden skeletal mesh; every tick, a poseable mesh copies that pose and bends the arm with a two-bone IK solved in Rust:

#![allow(unused)]
fn main() {
let pose = self.pose()?.checked()?;
pose.copy_pose_from_skeletal_component(self.body()?);

let chain = Chain {
    root: location("upperarm_r"),
    joint: location("lowerarm_r"),
    end: location("hand_r"),
};

let solved = ik::reach(chain, target, down);

for (bone, rotation, location) in [
    ("upperarm_r", solved.root_delta * rotation("upperarm_r"), chain.root),
    ("lowerarm_r", solved.joint_delta * solved.root_delta * rotation("lowerarm_r"), solved.joint),
    ("hand_r", rotation("hand_r"), solved.end),
] {
    pose.set_bone_transform_by_name(
        FName::new(bone).handle(),
        &FTransform::from_transform(Transform::new(rotation, location, DVec3::ONE)),
        EBoneSpaces::WorldSpace,
    );
}
}

ik::reach keeps both bone lengths, places the elbow in the plane of its current bend (nudged by a pole, here down), and returns the rotations that carry each bone onto the solution. Each bone gets its whole world transform: set_bone_rotation_by_name would read the bone’s location from before its parent moved, and pull the elbow off the arm.

The hidden mesh keeps animating with Visibility Based Anim Tick Option set to Always Tick Pose and Refresh Bones, and plays an animation asset without an Animation Blueprint:

#![allow(unused)]
fn main() {
body.play_animation(self.idle_animation().upcast_to(), true);
}

In the editor: place a ReachingMannequin and a ReachTarget from the Place Actors panel, select the mannequin and set its Target to the target, then move the target around it while playing.

Screenshot: the reaching mannequin with its right hand on the target sphere. (images/recipes/reach_target.png)

Health, damage and death

Use case: health with the engine’s damage system

The goal: a character that loses health when anything damages it, through the engine’s ApplyDamage, which Blueprints and other systems also use.

The dealer applies damage:

#![allow(unused)]
fn main() {
use bindings::engine::{DamageType, GameplayStatics, PawnExt};

let instigator_controller = me.get_instigator().checked().map(|pawn| pawn.get_controller()).unwrap_or_default();

GameplayStatics::apply_damage(
    hit_actor,
    25.0,
    instigator_controller,
    me.as_ref().upcast_to(),
    SubclassOf::<DamageType>::base(),
);
}

The damaged character overrides ReceiveAnyDamage, the event the engine raises for it:

#![allow(unused)]
fn main() {
use bindings::engine::{Controller, DamageType};

#[uclass(parent = Character)]
pub struct Soldier {
    #[uproperty(EditAnywhere, name = "MaxHP", category = "Health", default = 100.0)]
    max_hp: f32,

    #[uproperty(name = "CurrentHP")]
    current_hp: f32,
}

#[uclass_impl]
impl Soldier {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        self.set_current_hp(self.max_hp());
    }

    #[ufunction(Override)]
    fn receive_any_damage(
        &mut self,
        damage: f32,
        _damage_type: UObjectRef<DamageType>,
        _instigated_by: UObjectRef<Controller>,
        _damage_causer: UObjectRef<Actor>,
    ) {
        if self.current_hp() <= 0.0 {
            return;
        }

        self.set_current_hp(self.current_hp() - damage);

        if self.current_hp() <= 0.0 {
            self.die();
        }
    }

    #[ufunction(BlueprintImplementableEvent, name = "BP_OnDeath")]
    fn bp_on_death(&self) {}
}
}

For damage in an area, GameplayStatics::apply_radial_damage damages every actor in a radius that is not blocked by a wall. The shooter template does it by hand instead, with an overlap and apply_damage per actor, to push physics bodies too (see Projectiles).

Use case: dying as a ragdoll

The goal: on death the character stops, falls as a ragdoll, and is removed a few seconds later.

#![allow(unused)]
fn main() {
use bindings::engine::{
    CharacterExt, CharacterMovementComponentExt, ECollisionEnabled, KismetSystemLibrary,
    MovementComponentExt, PrimitiveComponentExt
};

impl Soldier {
    fn die(&mut self) {
        let Ok(me) = self.as_ref().checked() else {
            return;
        };

        let _ = me.tags().push(&FName::new("Dead").handle());

        if let Ok(movement) = me.get_character_movement().checked() {
            movement.stop_movement_immediately();
            movement.disable_movement();
        }

        if let Ok(capsule) = me.get_capsule_component().checked() {
            capsule.set_collision_enabled(ECollisionEnabled::NoCollision);
        }

        if let Ok(mesh) = me.get_mesh().checked() {
            mesh.set_collision_profile_name(FName::new("Ragdoll").handle(), Some(true));
            mesh.set_simulate_physics(true);
        }

        self.bp_on_death();

        KismetSystemLibrary::k2_set_timer(me.as_ref().upcast_to(), "RemoveBody", 5.0, false, None, None, None);
    }
}
}

RemoveBody is a #[ufunction] that calls k2_destroy_actor. The Blueprint child implements BP On Death for the sound and the effects.

Use case: respawning the player

The goal: when the player’s character is destroyed, a new one spawns at a player start and the controller possesses it.

#![allow(unused)]
fn main() {
use bindings::engine::{ControllerExt, Pawn, PlayerController, PlayerStart};

#[uclass(parent = PlayerController)]
pub struct SoldierController {
    #[uproperty(EditAnywhere)]
    character_class: SubclassOf<Soldier>,
}

#[uclass_impl]
impl SoldierController {
    #[ufunction(Override)]
    fn receive_possess(&mut self, possessed_pawn: UObjectRef<Pawn>) {
        let controller: UObjectRef<PlayerController> = self.as_ref();

        let bound = possessed_pawn.checked().and_then(|pawn| {
            pawn.on_destroyed().add(move |_destroyed| {
                if let Ok(mut me) = SoldierController::from_obj(controller)
                    && let Err(e) = me.respawn()
                {
                    log::warn!("[MyGame] respawn failed: {e}");
                }
            })
        });

        match bound {
            Ok(binding) => binding.detach(),
            Err(e) => log::warn!("[MyGame] cannot watch the pawn: {e}"),
        }
    }
}

impl SoldierController {
    fn respawn(&mut self) -> RustealResult<()> {
        let me = self.as_ref();

        let starts = GameplayStatics::get_all_actors_of_class(
            me.upcast_to(),
            SubclassOf::<PlayerStart>::base().upcast_to(),
        );

        let Some(start) = starts.first() else {
            return Ok(());
        };

        let transform = start.checked()?.get_transform();
        let character = me.get_world()?.spawn_actor_of_class(self.character_class(), &transform)?;
        me.checked()?.possess(character.upcast_to());

        Ok(())
    }
}
}

The Blueprint child of the controller sets Character Class to the character’s Blueprint.

Use case: damage between your own classes

When only Rust classes deal and take the damage, and they need more than a number (a hit location, a knockback impulse), a Rust trait is simpler than the engine’s damage system. See Interfaces, “Rust traits between Rust classes”, and the combat variant of third-person, whose interfaces.rs does exactly this.

Projectiles and weapons

Use case: a projectile

The goal: a bullet that flies, bounces, damages what it hits, and is removed after a while.

#![allow(unused)]
fn main() {
use bindings::engine::{
    Character, DamageType, ECollisionEnabled, ECollisionResponse, FHitResult, FHitResultExt,
    GameplayStatics, PawnExt, PrimitiveComponent, PrimitiveComponentExt,
    ProjectileMovementComponent, ProjectileMovementComponentExt, SphereComponent,
    SphereComponentExt
};

#[uclass(parent = Actor)]
pub struct Bullet {
    #[component(root, name = "Collision Component")]
    collision: SphereComponent,

    #[component(name = "Projectile Movement")]
    movement: ProjectileMovementComponent,

    #[uproperty(EditAnywhere, category = "Hit", default = 25.0)]
    hit_damage: f32,

    #[uproperty(EditAnywhere, category = "Hit", default = 100.0)]
    physics_force: f32,

    hit: bool,
}

#[uclass_impl]
impl Bullet {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let collision = self.collision()?.checked()?;
        collision.set_sphere_radius(16.0, Some(true));
        collision.set_collision_enabled(ECollisionEnabled::QueryAndPhysics);
        collision.set_collision_response_to_all_channels(ECollisionResponse::ECR_Block);

        let movement = self.movement()?.checked()?;
        movement.set_initial_speed(3000.0);
        movement.set_max_speed(3000.0);
        movement.set_should_bounce(true);

        self.as_ref().checked()?.set_initial_life_span(5.0);

        Ok(())
    }

    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        if let (Ok(collision), Ok(me)) = (self.collision().and_then(|c| c.checked()), self.as_ref().checked()) {
            collision.ignore_actor_when_moving(me.get_instigator().upcast_to(), true);
        }
    }

    #[ufunction(Override)]
    #[allow(clippy::too_many_arguments)]
    fn receive_hit(
        &mut self,
        _my_comp: UObjectRef<PrimitiveComponent>,
        other: UObjectRef<Actor>,
        other_comp: UObjectRef<PrimitiveComponent>,
        _self_moved: bool,
        _hit_location: UStructRef<FVector>,
        _hit_normal: UStructRef<FVector>,
        _normal_impulse: UStructRef<FVector>,
        hit: UStructRef<FHitResult>,
    ) {
        if self.hit() {
            return;
        }

        self.set_hit(true);

        let Ok(me) = self.as_ref().checked() else {
            return;
        };

        if other.cast::<Character>().is_ok() {
            let instigator = me.get_instigator().checked().map(|pawn| pawn.get_controller()).unwrap_or_default();
            GameplayStatics::apply_damage(other, self.hit_damage(), instigator, me.as_ref().upcast_to(), SubclassOf::<DamageType>::base());
        }

        if let Ok(component) = other_comp.checked()
            && component.is_simulating_physics(None)
        {
            let direction = -hit.get_impact_normal().to_dvec3();
            component.add_impulse_at_location(
                &FVector::from_dvec3(direction * f64::from(self.physics_force())),
                &FVector::from_dvec3(hit.get_impact_point().to_dvec3()),
                None,
            );
        }

        self.bp_on_hit(&hit.to_owned());
        me.k2_destroy_actor();
    }

    #[ufunction(BlueprintImplementableEvent, name = "BP_OnProjectileHit")]
    fn bp_on_hit(&self, hit: &OwnedStruct<FHitResult>) {}
}
}

• The ProjectileMovementComponent moves it; the root sphere collides.
• set_initial_life_span removes it after five seconds if it hits nothing.
• The Blueprint child gives it a mesh, and implements BP On Projectile Hit for the impact effect and sound.

The weapon spawns it deferred, so the instigator is set before BeginPlay runs (see Spawning actors).

Use case: a weapon with a magazine and a refire rate

The goal: a weapon that fires while the trigger is held (or once per press), counts its bullets, and tells the HUD.

The shooter template splits it in two: the rules in model.rs, tested without the engine, and the weapon class that applies them.

#![allow(unused)]
fn main() {
pub enum TriggerPull {
    FireNow,
    FireIn(f32),
    Wait,
}

pub fn pull_trigger(time_since_last_shot: f32, refire_rate: f32, full_auto: bool) -> TriggerPull {
    if time_since_last_shot > refire_rate {
        TriggerPull::FireNow
    } else if full_auto {
        TriggerPull::FireIn(refire_rate - time_since_last_shot)
    } else {
        TriggerPull::Wait
    }
}

pub fn bullets_after_shot(bullets: i32, magazine_size: i32) -> i32 {
    let left = bullets - 1;
    if left <= 0 { magazine_size } else { left }
}
}

#![allow(unused)]
fn main() {
pub fn start_firing(&mut self) {
    self.set_is_firing(true);

    let now = GameplayStatics::get_time_seconds(self.as_ref().upcast_to()) as f32;

    match model::pull_trigger(now - self.time_of_last_shot(), self.refire_rate(), self.b_full_auto()) {
        TriggerPull::FireNow => self.fire(),
        TriggerPull::FireIn(delay) => self.set_refire_timer("Fire", delay),
        TriggerPull::Wait => {}
    }
}

pub fn stop_firing(&mut self) {
    self.set_is_firing(false);
    KismetSystemLibrary::k2_clear_timer(self.as_ref().upcast_to(), "Fire");
}
}

fire spawns the projectile, plays the firing montage on the holder, adds recoil (add_controller_pitch_input), updates the bullet count and sets the timer for the next shot. See shooter/weapon.rs in a first-person --variant shooter project.

Use case: attaching a weapon to a hand

The goal: the weapon actor follows the character’s hand.

#![allow(unused)]
fn main() {
use bindings::engine::{EAttachmentRule, SceneComponentExt};

let snap = EAttachmentRule::SnapToTarget;

weapon.checked()?.k2_attach_to_actor(me.as_ref().upcast_to(), FName::NONE.handle(), snap, snap, snap, false);

weapon_mesh.checked()?.k2_attach_to_component(
    character_mesh.upcast_to(),
    FName::new("HandGrip_R").handle(),
    snap,
    snap,
    snap,
    false,
);
}

The weapon is spawned with the character as its owner, and destroys itself with it:

#![allow(unused)]
fn main() {
let weapon = self.as_ref();

me.get_owner()
    .checked()?
    .on_destroyed()
    .add(move |_destroyed| {
        if let Ok(weapon) = weapon.checked() {
            weapon.k2_destroy_actor();
        }
    })?
    .detach();
}

Use case: telling the AI a shot was heard

#![allow(unused)]
fn main() {
me.make_noise(
    Some(1.0),
    Some(pawn_owner),
    &pawn.k2_get_actor_location(),
    Some(3000.0),
    Some(FName::new("Shot").handle()),
);
}

make_noise is heard by AI perception’s hearing sense, with the tag the AI filters on. See AI.

Pickups

Use case: a coin that counts

The goal: the player walks into a coin, the game mode counts it, the UI shows the count, and the Blueprint plays the effect.

#![allow(unused)]
fn main() {
use bindings::engine::{
    ECollisionChannel, ECollisionEnabled, ECollisionResponse, GameplayStatics,
    PrimitiveComponentExt, SceneComponent, SphereComponent, SphereComponentExt
};

#[uclass(parent = Actor)]
pub struct Coin {
    #[component(root)]
    root: SceneComponent,

    #[component(attach = "root", name = "Collision")]
    sphere: SphereComponent,
}

#[uclass_impl]
impl Coin {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let sphere = self.sphere()?.checked()?;
        sphere.set_sphere_radius(60.0, Some(false));
        sphere.set_collision_enabled(ECollisionEnabled::QueryOnly);
        sphere.set_collision_response_to_all_channels(ECollisionResponse::ECR_Ignore);
        sphere.set_collision_response_to_channel(ECollisionChannel::ECC_Pawn, ECollisionResponse::ECR_Overlap);
        Ok(())
    }

    #[ufunction(Override)]
    fn receive_actor_begin_overlap(&mut self, other_actor: UObjectRef<Actor>) {
        if let Err(e) = self.pick_up(other_actor) {
            log::warn!("[MyGame] pickup failed: {e}");
        }
    }

    #[ufunction(BlueprintImplementableEvent, name = "BP_OnPickedUp")]
    fn bp_on_picked_up(&self) {}
}

impl Coin {
    fn pick_up(&mut self, other_actor: UObjectRef<Actor>) -> RustealResult<()> {
        let Ok(character) = other_actor.cast::<Character>() else {
            return Ok(());
        };

        if !character.checked()?.is_player_controlled() {
            return Ok(());
        }

        let game_mode = GameplayStatics::get_game_mode(self.as_ref().upcast_to());

        if let Ok(mut game_mode) = CoinGameMode::from_obj(game_mode) {
            game_mode.add_coin()?;
        }

        self.as_ref().checked()?.set_actor_enable_collision(false);
        self.bp_on_picked_up();

        Ok(())
    }
}
}

The collision only overlaps pawns, so the coin does not block anything. The Blueprint child gives it a mesh, and its BP On Picked Up graph plays a sound and hides or destroys it. The game mode keeps the count and updates the UI: see UI, “A counter on screen”.

Use case: a weapon pickup that respawns

The goal: a pickup gives its weapon to whoever walks in, hides, and comes back after a few seconds.

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_actor_begin_overlap(&mut self, other_actor: UObjectRef<Actor>) {
    let Some(mut holder) = weapon_holder(other_actor) else {
        return;
    };

    holder.add_weapon_class(self.weapon_class());

    let Ok(me) = self.as_ref().checked() else {
        return;
    };

    me.set_actor_hidden_in_game(true);
    me.set_actor_enable_collision(false);

    KismetSystemLibrary::k2_set_timer(me.as_ref().upcast_to(), "RespawnPickup", self.respawn_time(), false, None, None, None);
}

#[ufunction]
fn respawn_pickup(&mut self) {
    if let Ok(me) = self.as_ref().checked() {
        me.set_actor_hidden_in_game(false);
        me.set_actor_enable_collision(true);
    }
}

#[ufunction(Override)]
fn receive_end_play(&mut self, _end_play_reason: u8) {
    KismetSystemLibrary::k2_clear_timer(self.as_ref().upcast_to(), "RespawnPickup");
}
}

weapon_holder turns the actor into a Rust trait that both the player and the NPCs implement (see Interfaces). Which weapon the pickup gives comes from a data table row: see Structs and data tables.

Platforming

The platforming and side-scrolling variants of third-person are full platformer controllers. Their rules are in model.rs, tested without the engine, and their classes apply them.

Use case: double jump and coyote time

The goal: a second jump in the air, and a jump that still works a moment after walking off a ledge.

The rules, plain Rust:

#![allow(unused)]
fn main() {
#[derive(Clone, Copy, Default)]
pub struct MoveState {
    pub has_double_jumped: bool,
    pub last_fall_time: f64,
}

pub enum AirJump {
    Coyote,
    Double,
    None,
}

pub fn air_jump(state: &MoveState, now: f64, max_coyote_time: f32) -> AirJump {
    if now - state.last_fall_time < f64::from(max_coyote_time) {
        AirJump::Coyote
    } else if !state.has_double_jumped {
        AirJump::Double
    } else {
        AirJump::None
    }
}
}

The character records when it starts falling, applies the rules on the jump press, and resets them on landing:

#![allow(unused)]
fn main() {
use bindings::engine::{CharacterExt, GameplayStatics, NavMovementComponentExt};

const MOVE_FALLING: u8 = 3;

#[uclass(parent = Character)]
pub struct Platformer {
    #[uproperty(EditAnywhere, category = "Jump", default = 0.16)]
    max_coyote_time: f32,

    state: MoveState,
}

#[uclass_impl]
impl Platformer {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        me.set_jump_max_hold_time(0.4);
        me.set_jump_max_count(3);
        Ok(())
    }

    #[ufunction(Override, name = "K2_OnMovementModeChanged")]
    fn on_movement_mode_changed(&mut self, _prev_mode: u8, new_mode: u8, _prev_custom: u8, _new_custom: u8) {
        if new_mode == MOVE_FALLING {
            let mut state = self.state();
            state.last_fall_time = GameplayStatics::get_time_seconds(self.as_ref().upcast_to());
            self.set_state(state);
        }
    }

    #[ufunction]
    fn jump_pressed(&mut self) {
        let Ok(me) = self.as_ref().checked() else {
            return;
        };

        let Ok(movement) = me.get_character_movement().checked() else {
            return;
        };

        if !movement.is_falling() {
            me.jump();
            return;
        }

        let mut state = self.state();
        let now = GameplayStatics::get_time_seconds(self.as_ref().upcast_to());

        match air_jump(&state, now, self.max_coyote_time()) {
            AirJump::Coyote => me.jump(),
            AirJump::Double => {
                state.has_double_jumped = true;
                me.jump();
            }
            AirJump::None => {}
        }

        self.set_state(state);
    }

    #[ufunction(Override)]
    fn on_landed(&mut self, _hit: UStructRef<FHitResult>) {
        let mut state = self.state();
        state.has_double_jumped = false;
        self.set_state(state);
    }
}
}

The movement mode arrives as its u8 value: 3 is MOVE_Falling in the engine’s EMovementMode.

Use case: a wall jump

The goal: jumping while touching a wall bounces off it.

#![allow(unused)]
fn main() {
let me = self.as_ref().checked()?;
let start = me.k2_get_actor_location().to_dvec3();
let end = start + me.get_actor_forward_vector().to_dvec3() * 100.0;

let (hit, out_hit) = KismetSystemLibrary::sphere_trace_single(
    self.as_ref().upcast_to(),
    &FVector::from_dvec3(start),
    &FVector::from_dvec3(end),
    40.0,
    ETraceTypeQuery::TraceTypeQuery1,
    false,
    &[],
    EDrawDebugTrace::None,
    true,
    &OwnedStruct::new(),
    &OwnedStruct::new(),
    None,
);

if hit {
    let normal = out_hit.as_ref().get_impact_normal().to_dvec3();
    let impulse = normal * 800.0 + DVec3::Z * 900.0;
    me.launch_character(&FVector::from_dvec3(impulse), true, true);
}
}

launch_character(velocity, xy_override, z_override) replaces the character’s velocity with the launch: the bounce does not depend on how fast it was falling.

Use case: a dash

The goal: a quick dash in the air, driven by a montage with root motion, with gravity off while it lasts.

#![allow(unused)]
fn main() {
use bindings::engine::{AnimInstanceExt, MovementComponentExt, SkeletalMeshComponentExt};

fn start_dash(&mut self) -> RustealResult<()> {
    let me = self.as_ref().checked()?;
    let movement = me.get_character_movement().checked()?;
    movement.set_gravity_scale(0.0);
    movement.set_velocity(&FVector::from_dvec3(DVec3::ZERO));

    let anim_instance = me.get_mesh().checked()?.get_anim_instance();
    anim_instance.checked()?.montage_play(self.dash_montage(), Some(1.0), None, Some(0.0), Some(true));

    Ok(())
}

pub fn end_dash(&mut self) {
    if let Ok(movement) = self.as_ref().checked().and_then(|me| me.get_character_movement().checked()) {
        movement.set_gravity_scale(1.0);
    }
}
}

end_dash runs from an anim notify at the end of the dash montage (see Animation), and from the montage’s end as a fallback.

Use case: a jump pad

See Delegates: a box that overlaps pawns and calls launch_character on whoever steps on it.

Use case: a platform you can drop through

The goal: a platform the character lands on, and drops through when pressing down and jump.

The platform’s mesh blocks a custom object channel; the character ignores that channel while dropping:

#![allow(unused)]
fn main() {
pub fn set_soft_collision(&self, enabled: bool) -> RustealResult<()> {
    let response = if enabled { ECollisionResponse::ECR_Ignore } else { ECollisionResponse::ECR_Block };

    self.as_ref()
        .checked()?
        .get_capsule_component()
        .checked()?
        .set_collision_response_to_channel(self.soft_collision_object_type(), response);

    Ok(())
}
}

soft_collision_object_type is an EditAnywhere ECollisionChannel property, set in the Blueprint child to the channel the platforms use. The platform’s own receive_actor_end_overlap turns the collision back on once the character has passed.

In the editor

1. Edit > Project Settings, Collision, New Object Channel: name it SoftPlatform, Default Response Block.
2. In the platform Blueprint, set its mesh’s Collision Presets to Custom and its Object Type to SoftPlatform.
3. In the character Blueprint’s Class Defaults, set Soft Collision Object Type to the same channel.

Screenshot: the Collision page of Project Settings with the SoftPlatform object channel. (images/recipes/soft_platform_channel.png)

Use case: a moving platform

The goal: a platform that moves to a target when the player interacts with it.

The side-scrolling template leaves the motion to the Blueprint, where a Timeline is the natural tool, and keeps the rules in Rust:

#![allow(unused)]
fn main() {
#[uclass(parent = Actor)]
pub struct MovingPlatform {
    #[component(root)]
    root: SceneComponent,

    #[uproperty(EditAnywhere, BlueprintReadOnly)]
    platform_target: OwnedStruct<FVector>,

    #[uproperty(EditAnywhere, BlueprintReadOnly, default = 2.0)]
    move_duration: f32,

    moving: bool,
}

#[uclass_impl]
impl MovingPlatform {
    #[ufunction(BlueprintCallable)]
    fn reset_interaction(&mut self) {
        self.set_moving(false);
    }

    #[ufunction(BlueprintImplementableEvent, name = "BP_MoveToTarget")]
    fn bp_move_to_target(&self) {}
}

impl MovingPlatform {
    pub fn interact(&mut self) {
        if self.moving() {
            return;
        }

        self.set_moving(true);
        self.bp_move_to_target();
    }
}
}

The Blueprint child implements BP Move To Target with a Timeline that moves the platform to Platform Target over Move Duration, and calls Reset Interaction when it finishes.

To move it from Rust instead, interpolate in receive_tick with k2_set_actor_location, using the engine’s interpolation as plain Rust (current + (target - current) * (delta * speed).clamp(0.0, 1.0)).

Physics

Use case: a prop that reacts to hits

The goal: a box that simulates physics, is pushed where it is hit, and breaks after enough damage.

#![allow(unused)]
fn main() {
use bindings::engine::{ECollisionChannel, KismetSystemLibrary, PrimitiveComponentExt, StaticMeshComponent};

#[uclass(parent = Actor)]
pub struct Crate {
    #[component(root)]
    mesh: StaticMeshComponent,

    #[uproperty(EditAnywhere, name = "CurrentHP", default = 30.0)]
    current_hp: f32,
}

#[uclass_impl]
impl Crate {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let mesh = self.mesh()?.checked()?;
        mesh.set_collision_profile_name(FName::new("BlockAllDynamic").handle(), Some(true));
        mesh.set_simulate_physics(true);
        mesh.set_can_ever_affect_navigation(false);
        Ok(())
    }
}

impl Crate {
    pub fn hit(&mut self, damage: f32, location: DVec3, impulse: DVec3) {
        self.set_current_hp(self.current_hp() - damage);

        if let Ok(mesh) = self.mesh().and_then(|m| m.checked()) {
            let scaled = impulse * f64::from(mesh.get_mass());
            mesh.add_impulse_at_location(&FVector::from_dvec3(scaled), &FVector::from_dvec3(location), None);

            if self.current_hp() <= 0.0 {
                mesh.set_collision_object_type(ECollisionChannel::ECC_Visibility);
            }
        }
    }
}
}

add_impulse_at_location pushes and spins the body from the point that was hit. Multiplying by the mass makes the push the same for a light and a heavy prop; add_impulse(impulse, bone, vel_change = Some(true)) does that for you.

Use case: knockback on a character

A character’s capsule does not simulate physics; its movement component takes the impulse:

#![allow(unused)]
fn main() {
if let Ok(movement) = me.get_character_movement().checked() {
    movement.add_impulse(&FVector::from_dvec3(knockback), Some(true));
}
}

Or replace its velocity at once with launch_character.

Use case: a hit reaction with partial ragdoll

#![allow(unused)]
fn main() {
let mesh = me.get_mesh().checked()?;
mesh.set_physics_blend_weight(0.5);
mesh.set_all_bodies_below_simulate_physics(FName::new("pelvis").handle(), true, Some(false));
}

The combat template blends the ragdoll in when hit and back out on landing (set_physics_blend_weight(0.0) in on_landed).

Use case: a physics constraint

The goal: a training dummy that wobbles on its base.

#![allow(unused)]
fn main() {
use bindings::engine::{PhysicsConstraintComponent, PhysicsConstraintComponentExt};

#[uclass(parent = Actor)]
pub struct Dummy {
    #[component(root)]
    root: SceneComponent,

    #[component(attach = "root", name = "Base Plate")]
    base_plate: StaticMeshComponent,

    #[component(attach = "root")]
    dummy: StaticMeshComponent,

    #[component(attach = "root", name = "Physics Constraint")]
    constraint: PhysicsConstraintComponent,
}

#[uclass_impl]
impl Dummy {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        self.dummy()?.checked()?.set_simulate_physics(true);
        Ok(())
    }

    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        if let (Ok(constraint), Ok(base_plate), Ok(dummy)) =
            (self.constraint().and_then(|c| c.checked()), self.base_plate(), self.dummy())
        {
            constraint.set_constrained_components(
                base_plate.upcast_to(),
                FName::NONE.handle(),
                dummy.upcast_to(),
                FName::NONE.handle(),
            );
        }
    }
}
}

The constraint’s limits (swing, twist) are set on the component in the Blueprint child’s Details panel.

A chain is the same thing repeated: the interactables feature’s BP_DangleBlocks has four cubes and four constraints, the first holding the top cube to the world (its Component Name 1 names no component) and each other one a cube to the one above, with where each piece sits and how far each joint swings. Its Rust parent, DangleBlocks, has no code: the Blueprint is all data.

Collision presets and channels

A component meant to fire overlap events also needs Generate Overlap Events on, which most presets have.

UI

Rusteal UI follows one pattern: a Rust class whose parent is UserWidget declares what the widget can be told, as BlueprintImplementableEvents; a Widget Blueprint child of it draws the layout in the UMG designer and implements those events; the game creates the widget from a class a Blueprint assigns.

Use case: a counter on screen

The goal: a pickups counter that appears with the first pickup and updates with each one.

The widget class:

#![allow(unused)]
fn main() {
use bindings::umg::UserWidget;

#[uclass(parent = UserWidget)]
pub struct CoinsUI {}

#[uclass_impl]
impl CoinsUI {
    #[ufunction(BlueprintImplementableEvent)]
    pub fn update_coins(&self, amount: i32) {}
}
}

The game mode creates it and tells it the count:

#![allow(unused)]
fn main() {
use bindings::engine::{GameModeBase, GameplayStatics};
use bindings::umg::UserWidgetExt;

#[uclass(parent = GameModeBase)]
pub struct CoinGameMode {
    #[uproperty(EditAnywhere)]
    user_interface_class: SubclassOf<CoinsUI>,

    #[uproperty]
    user_interface: UObjectRef<CoinsUI>,

    #[uproperty(BlueprintReadOnly)]
    coins: i32,
}

#[uclass_impl]
impl CoinGameMode {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        if let Err(e) = self.create_user_interface() {
            log::warn!("[MyGame] UI: {e}");
        }
    }
}

impl CoinGameMode {
    fn create_user_interface(&mut self) -> RustealResult<()> {
        let player = GameplayStatics::get_player_controller(self.as_ref().upcast_to(), 0);
        let widget = create_widget_of_class(&player, self.user_interface_class())?;
        self.set_user_interface(widget);
        Ok(())
    }

    pub fn add_coin(&mut self) -> RustealResult<()> {
        let coins = self.coins() + 1;
        self.set_coins(coins);

        let ui = self.user_interface();

        if coins == 1 {
            ui.upcast_to::<UserWidget>().checked()?.add_to_viewport(Some(0));
        }

        CoinsUI::from_obj(ui)?.update_coins(coins);

        Ok(())
    }
}
}

• create_widget_of_class(&owning_player, class) is C++’s CreateWidget<T>(PlayerController, Class).
• add_to_viewport shows it over the whole screen; add_to_player_screen over the owning player’s part of a split screen; remove_from_parent hides it again.
• CoinsUI::from_obj(widget) reaches the Rust class of the widget, whose events run the Widget Blueprint’s graph.

In the editor

1. In the Content Browser, right-click and choose User Interface > Widget Blueprint, and name it UI_Coins.
2. Open it, switch to Graph (top right), click Class Settings in the toolbar, and in the Details panel set Parent Class to CoinsUI.
3. Switch to Designer, add a Canvas Panel and a Text inside it. Select the Text, check Is Variable in the Details panel and name it CoinsText.
4. Switch to Graph. Right-click and add Event Update Coins. From it, get CoinsText, call SetText (Text), and convert Amount to text with To Text (Integer).
5. Compile and Save.
6. Open the game mode’s Blueprint child, and in Class Defaults set User Interface Class to UI_Coins.

Screenshot: UI_Coins’s Graph with Event Update Coins setting the CoinsText text. (images/recipes/ui_update_coins.png)

Use case: a widget that listens to the character

The goal: a stamina meter that updates whenever the character’s stamina changes.

The horror template has the player controller create the widget on possess, and hand the character to it:

#![allow(unused)]
fn main() {
#[uclass(parent = UserWidget)]
pub struct HorrorUI {}

#[uclass_impl]
impl HorrorUI {
    #[ufunction(BlueprintImplementableEvent, name = "BP_SprintMeterUpdated")]
    pub fn bp_sprint_meter_updated(&self, percent: f32) {}

    #[ufunction(BlueprintImplementableEvent, name = "BP_SprintStateChanged")]
    pub fn bp_sprint_state_changed(&self, sprinting: bool) {}
}
}

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_possess(&mut self, possessed_pawn: UObjectRef<Pawn>) {
    let me: UObjectRef<PlayerController> = self.as_ref();

    if !self.horror_ui().is_valid()
        && let Ok(widget) = create_widget_of_class(&me, self.horror_ui_class())
        && let Ok(checked) = widget.checked()
    {
        checked.add_to_player_screen(Some(0));
        self.set_horror_ui(widget);
    }
}
}

The character then calls the widget’s events when the stamina changes. A delegate of your own (#[udelegate]) on the character does the same job and lets any number of widgets, Blueprint or Rust, listen.

Use case: a health bar above a character

The goal: a bar that floats over each enemy.

#![allow(unused)]
fn main() {
use bindings::umg::{WidgetComponent, WidgetComponentExt};

#[uclass(parent = Character)]
pub struct Enemy {
    #[component(attach = "root_component")]
    life_bar: WidgetComponent,

    #[uproperty]
    life_bar_widget: UObjectRef<LifeBar>,
}

#[uclass_impl]
impl Enemy {
    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        if let Ok(widget) = self
            .life_bar()
            .and_then(|bar| bar.checked())
            .and_then(|bar| bar.get_user_widget_object().cast::<LifeBar>())
        {
            self.set_life_bar_widget(widget);
        }
    }
}
}

The Blueprint child sets the Widget Class of the Life Bar component to a Widget Blueprint whose parent is LifeBar, and its Space to Screen. Updating it is LifeBar::from_obj(self.life_bar_widget())?.set_life_percentage(hp / max_hp).

Use case: the buttons of a Widget Blueprint

The goal: a menu whose layout a designer draws in the UMG designer, and whose buttons run Rust functions.

#![allow(unused)]
fn main() {
use bindings::umg::{Button, ButtonExt, UserWidget};

#[uclass(parent = UserWidget)]
pub struct MenuWidget {
    #[uproperty(BindWidget, BlueprintReadOnly)]
    restart_button: UObjectRef<Button>,

    #[uproperty(BindWidget, BlueprintReadOnly)]
    exit_button: UObjectRef<Button>,
}

#[uclass_impl]
impl MenuWidget {
    #[ufunction(Override)]
    fn construct(&mut self) {
        let me = self.as_ref().upcast_to::<UserWidget>();

        for (button, handler) in [(self.restart_button(), "Restart"), (self.exit_button(), "Exit")] {
            if let Ok(button) = button.checked() {
                let _ = button.on_clicked().add_ufunction(&me, handler);
            }
        }
    }

    #[ufunction(BlueprintCallable)]
    pub fn restart(&mut self) {
        let me = self.as_ref();
        let level = GameplayStatics::get_current_level_name(me.upcast_to(), Some(true));
        GameplayStatics::open_level(me.upcast_to(), FName::new(&level).handle(), Some(true), None);
    }

    #[ufunction(BlueprintCallable)]
    pub fn exit(&mut self) {
        KismetSystemLibrary::quit_game(self.as_ref().upcast_to(), UObjectRef::null(), EQuitPreference::Quit, false);
    }
}
}

A BindWidget property is C++’s UPROPERTY(meta = (BindWidget)): when the widget is created, it holds the layout’s widget of the same name (RestartButton for restart_button). The Widget Blueprint must have it, with that name and a compatible class, or it does not compile; BindWidgetOptional lets the layout leave it out, and the property is then null.

In the editor

1. Create a Widget Blueprint whose parent is MenuWidget, or open an existing one, click Class Settings and set Parent Class to MenuWidget.
2. In the Designer, add two Buttons and name them RestartButton and ExitButton in the Details panel.
3. Click Compile. A missing or misnamed button is reported by the compiler.

Screenshot: the UMG designer with RestartButton and ExitButton, and the compiler results naming a missing BindWidget. (images/recipes/bind_widget.png)

Template: vr (the 3D menu).

Use case: playing a Widget Blueprint’s animations

The goal: a flash plays over the screen when the player takes a screenshot, an animation drawn in the UMG designer’s Animations panel and started from Rust.

#![allow(unused)]
fn main() {
use bindings::umg::{EUMGSequencePlayMode, UserWidget, UserWidgetExt, WidgetAnimation};

#[uclass(parent = UserWidget)]
pub struct MainMenu {
    #[uproperty(BindWidgetAnim, BlueprintReadOnly, name = "Screenshot_Show")]
    screenshot_show: UObjectRef<WidgetAnimation>,
}

#[uclass_impl]
impl MainMenu {
    #[ufunction(BlueprintCallable)]
    pub fn take_screenshot(&mut self) {
        let me = self.as_ref().upcast_to::<UserWidget>();

        if let Ok(widget) = me.checked() {
            widget.play_animation(
                self.screenshot_show(),
                Some(0.0),
                Some(1),
                Some(EUMGSequencePlayMode::Forward),
                Some(1.0),
                Some(false),
            );
        }
    }
}
}

BindWidgetAnim binds the Widget Blueprint’s animation of the same name, as BindWidget binds a widget; the property is made Transient, since the engine sets it on each created widget. To run code when the animation ends, set a timer for get_end_time() seconds with KismetSystemLibrary::k2_set_timer.

Template: ar (the main menu’s screenshot flash and tutorial).

Use case: drawing on the HUD

The goal: a selection box drawn while dragging the mouse.

#![allow(unused)]
fn main() {
use bindings::engine::{HUD, HUDExt};

#[uclass(parent = HUD)]
pub struct StrategyHUD {
    #[uproperty(EditAnywhere)]
    selection_box_color: OwnedStruct<FLinearColor>,

    drawing: bool,
    box_start: DVec2,
    box_size: DVec2,
}

#[uclass_impl]
impl StrategyHUD {
    #[ufunction(Override)]
    fn receive_draw_hud(&mut self, _size_x: i32, _size_y: i32) {
        if !self.drawing() {
            return;
        }

        let Ok(me) = self.as_ref().checked() else {
            return;
        };

        let (start, size) = (self.box_start(), self.box_size());
        me.draw_rect(&self.selection_box_color(), start.x as f32, start.y as f32, size.x as f32, size.y as f32);
    }
}
}

receive_draw_hud runs every frame; draw_rect, draw_text, draw_line and draw_texture draw on the canvas. get_actors_in_selection_rectangle returns the actors inside a screen rectangle, which is how the strategy template selects units with a box. The game mode’s Blueprint child sets HUD Class to the HUD’s Blueprint.

AI

AI in Rusteal uses the engine’s tools: AI controllers, StateTree, EQS, AI perception and the navigation mesh. Rust writes the controller, the StateTree tasks and conditions, and the EQS contexts; the StateTree and the EQS queries are assets made in the editor.

The project needs the ai feature, and state-tree for StateTree, in rusteal.toml (see Binding more of the engine):

features = ["core", "engine", "input", "slate", "umg", "enhanced-input", "ai", "state-tree"]

Use case: an AI controller that runs a StateTree

The goal: an enemy’s controller that starts its StateTree when it possesses the enemy.

#![allow(unused)]
fn main() {
use bindings::ai::{AIController, AIControllerExt, BrainComponentExt};
use bindings::engine::{ControllerExt, Pawn};
use bindings::gameplay_state_tree::{StateTreeAIComponent, StateTreeComponentExt};

#[uclass(parent = AIController)]
pub struct EnemyAIController {
    #[component(name = "StateTreeAI")]
    state_tree_ai: StateTreeAIComponent,
}

#[uclass_impl]
impl EnemyAIController {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        me.set_start_ai_logic_on_possess(false);
        me.set_attach_to_pawn(true);
        self.state_tree_ai()?.checked()?.set_start_logic_automatically(false);
        Ok(())
    }

    #[ufunction(Override)]
    fn receive_possess(&mut self, _possessed_pawn: UObjectRef<Pawn>) {
        if let Ok(state_tree) = self.state_tree_ai().and_then(|s| s.checked()) {
            state_tree.start_logic();
        }
    }
}
}

Starting the StateTree on possession, instead of automatically, makes sure the tree finds its pawn: started earlier, it logs that it could not find its context actor.

The enemy uses it, in its class defaults:

#![allow(unused)]
fn main() {
me.set_ai_controller_class(SubclassOf::<EnemyAIController>::base().upcast_to());
me.set_auto_possess_ai(EAutoPossessAI::PlacedInWorldOrSpawned);
}

The controller’s Blueprint child sets the State Tree of the StateTreeAI component.

Use case: a StateTree task

The goal: a task that makes the AI face an actor while its state is active.

#![allow(unused)]
fn main() {
use bindings::ai::{AIController, AIControllerExt};
use bindings::state_tree::{FStateTreeTransitionResult, StateTreeTaskBlueprintBase, StateTreeTaskBlueprintBaseExt};

#[uclass(parent = StateTreeTaskBlueprintBase)]
pub struct StateTreeFaceActorTask {
    #[uproperty(EditAnywhere, category = "Context")]
    controller: UObjectRef<AIController>,

    #[uproperty(EditAnywhere, category = "Input")]
    actor_to_face_towards: UObjectRef<Actor>,
}

#[uclass_impl]
impl StateTreeFaceActorTask {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        self.as_ref().checked()?.set_should_state_change_on_reselect(false);
        Ok(())
    }

    #[ufunction(Override)]
    fn receive_latent_enter_state(&mut self, _transition: UStructRef<FStateTreeTransitionResult>) {
        if let Ok(controller) = self.controller().checked() {
            controller.k2_set_focus(self.actor_to_face_towards());
        }
    }

    #[ufunction(Override)]
    fn receive_exit_state(&mut self, _transition: UStructRef<FStateTreeTransitionResult>) {
        if let Ok(controller) = self.controller().checked() {
            controller.k2_clear_focus();
        }
    }
}
}

• A task’s parent is StateTreeTaskBlueprintBase; it overrides receive_latent_enter_state, receive_exit_state and receive_tick.
• The property categories are the StateTree’s binding categories: Context binds to the tree’s context (the actor, the controller), Input and Parameter to values, Output to values other tasks read.
• A task that finishes on its own calls finish_task(Some(true)) (succeeded) or finish_task(Some(false)) on itself; one that runs until its state is left does not.

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_latent_enter_state(&mut self, _transition: UStructRef<FStateTreeTransitionResult>) {
    let found = self.select_target();

    if let Ok(me) = self.as_ref().checked() {
        me.finish_task(Some(found));
    }
}
}

Use case: a StateTree condition

#![allow(unused)]
fn main() {
use bindings::state_tree::StateTreeConditionBlueprintBase;

#[uclass(parent = StateTreeConditionBlueprintBase)]
pub struct StateTreeIsGroundedCondition {
    #[uproperty(EditAnywhere, category = "Context")]
    character: UObjectRef<Character>,

    #[uproperty(EditAnywhere, category = "Condition", default = false)]
    b_must_be_in_air: bool,
}

#[uclass_impl]
impl StateTreeIsGroundedCondition {
    #[ufunction(Override)]
    fn receive_test_condition(&self) -> bool {
        let Ok(movement) = self.character().checked().and_then(|c| c.get_character_movement().checked()) else {
            return false;
        };

        movement.is_moving_on_ground() != self.b_must_be_in_air()
    }
}
}

In the editor

1. Open the StateTree asset (ST_Enemy).
2. Select a state. In the Details panel, add a task under Tasks and pick State Tree Face Actor Task from the class list.
3. Bind the task’s Controller to the tree’s AI controller context, and its Actor To Face Towards to an output of another task.
4. Add the condition the same way, under the state’s Enter Conditions or a transition’s Conditions, and pick State Tree Is Grounded Condition.
5. Compile and Save.

Rust tasks and conditions are listed under their class names, like Blueprint ones.

Screenshot: a StateTree state with the Rust task added and its Controller bound to the context. (images/recipes/state_tree_task.png)

Use case: AI perception

The goal: an enemy that reacts to what it sees and hears.

#![allow(unused)]
fn main() {
use bindings::ai::{AIPerceptionComponent, AIPerceptionComponentExt, FAIStimulus, FAIStimulusExt};

#[uclass(parent = AIController)]
pub struct GuardController {
    #[component(name = "AIPerception")]
    ai_perception: AIPerceptionComponent,
}

#[uclass_impl]
impl GuardController {
    #[ufunction(Override)]
    fn receive_possess(&mut self, _possessed_pawn: UObjectRef<Pawn>) {
        if let Err(e) = self.bind_perception() {
            log::warn!("[MyGame] AI perception: {e}");
        }
    }
}

impl GuardController {
    fn bind_perception(&self) -> RustealResult<()> {
        let me: UObjectRef<AIController> = self.as_ref();

        self.ai_perception()?
            .checked()?
            .on_target_perception_updated()
            .add(move |actor, stimulus| {
                if let Ok(guard) = GuardController::from_obj(me) {
                    guard.on_perceived(actor, stimulus);
                }
            })?
            .detach();

        Ok(())
    }

    fn on_perceived(&self, actor: UObjectRef<Actor>, stimulus: OwnedStruct<FAIStimulus>) {
        let location = stimulus.as_ref().get_stimulus_location().to_dvec3();
        let heard_a_shot = FName(stimulus.as_ref().get_tag()) == FName::new("Shot");
    }
}
}

The senses (sight, hearing, their ranges and angles) are set on the AIPerception component in the controller’s Blueprint child: Senses Config, +, AI Sight config. Noises come from make_noise (see Projectiles and weapons), which also needs a Pawn Noise Emitter component on the player.

Use case: moving to a point

#![allow(unused)]
fn main() {
let result = ai_controller.move_to_location(
    &FVector::from_dvec3(goal),
    Some(100.0),
    Some(true),
    Some(true),
    Some(true),
    Some(false),
    None,
    Some(true),
);

if result == EPathFollowingRequestResult::AlreadyAtGoal {
}
}

To know when the move ends, bind the controller’s receive_move_completed delegate:

#![allow(unused)]
fn main() {
controller
    .receive_move_completed()
    .add(move |_request_id, _result| {
        if let Ok(mut unit) = Unit::from_obj(me) {
            unit.on_arrived();
        }
    })?
    .detach();
}

A level needs a Nav Mesh Bounds Volume for the AI to find paths.

Use case: running an EQS query from Rust

The goal: a unit asks EQS for the best point around a goal and moves there.

#![allow(unused)]
fn main() {
use bindings::ai::{EEnvQueryRunMode, EnvQuery, EnvQueryInstanceBlueprintWrapper, EnvQueryInstanceBlueprintWrapperExt, EnvQueryManager};

let me: UObjectRef<Unit> = self.as_ref().cast().unwrap_or_default();

let query_instance = EnvQueryManager::run_eqs_query(
    me.upcast_to(),
    self.move_query(),
    me.upcast_to(),
    EEnvQueryRunMode::RandomBest25Pct,
    SubclassOf::<EnvQueryInstanceBlueprintWrapper>::base(),
);

self.set_env_query_instance(query_instance);

query_instance
    .checked()?
    .on_query_finished_event()
    .add(move |finished_query, _status| {
        if let Ok(mut unit) = Unit::from_obj(me) {
            unit.on_eqs_finished(finished_query);
        }
    })?
    .detach();
}

#![allow(unused)]
fn main() {
fn on_eqs_finished(&mut self, query: UObjectRef<EnvQueryInstanceBlueprintWrapper>) {
    let Ok(query) = query.checked() else {
        return;
    };

    let (found, locations) = query.get_query_results_as_locations();

    if let Some(best) = locations.first().filter(|_| found) {
        self.move_to(best.to_dvec3());
    }
}
}

Keep the query instance in a #[uproperty] until it finishes, or the garbage collector may collect it.

Use case: an EQS context

The goal: EQS queries that score points around a location Rust knows, such as where danger was last seen.

#![allow(unused)]
fn main() {
use bindings::ai::EnvQueryContext_BlueprintBase;
use bindings::core_ue::Object;

#[uclass(parent = EnvQueryContext_BlueprintBase)]
pub struct EnvQueryContextDanger {}

#[uclass_impl]
impl EnvQueryContextDanger {
    #[ufunction(Override)]
    fn provide_single_location(
        &self,
        _querier_object: UObjectRef<Object>,
        querier_actor: UObjectRef<Actor>,
        resulting_location: UStructRef<FVector>,
    ) {
        if let Ok(enemy) = Enemy::from_obj(querier_actor) {
            let location = enemy.last_danger_location();
            resulting_location.set_x(location.x);
            resulting_location.set_y(location.y);
            resulting_location.set_z(location.z);
        }
    }
}
}

provide_single_actor(&self, querier_object, querier_actor, resulting_actor: OutRef<UObjectRef<Actor>>) provides an actor instead. In the EQS editor, the context shows in every Context dropdown under its class name.

Point and click

The goal: click where the character should go, and it walks there along the navigation mesh; hold the button and it follows the cursor.

The top-down template’s player controller does both: a short click pathfinds to the point, a held click steers toward the cursor.

#![allow(unused)]
fn main() {
use bindings::ai::{AIBlueprintHelperLibrary, PathFollowingComponent};
use bindings::core_ue::EMouseCursor;
use bindings::engine::{
    ControllerExt, ETraceTypeQuery, FHitResultExt, GameplayStatics, PawnExt, PlayerController,
    PlayerControllerExt
};
use bindings::enhanced_input::{
    ETriggerEvent, EnhancedInputLocalPlayerSubsystemExt, InputAction, InputMappingContext
};

#[uclass(parent = PlayerController)]
pub struct ClickController {
    #[component(name = "Path Following Component")]
    path_following_component: PathFollowingComponent,

    #[uproperty(EditAnywhere, category = "Input", default = 0.3)]
    short_press_threshold: f32,

    #[uproperty(EditAnywhere, category = "Input")]
    default_mapping_context: UObjectRef<InputMappingContext>,

    #[uproperty(EditAnywhere, category = "Input")]
    set_destination_click_action: UObjectRef<InputAction>,

    cached_destination: DVec3,
    follow_time: f32,
}

#[uclass_impl]
impl ClickController {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let me = self.as_ref().checked()?;
        me.set_show_mouse_cursor(true);
        me.set_default_mouse_cursor(EMouseCursor::Default);
        Ok(())
    }

    #[ufunction(Override)]
    fn receive_begin_play(&mut self) {
        if let Err(e) = self.setup_input() {
            log::warn!("[MyGame] input setup failed: {e}");
        }
    }

    #[ufunction]
    fn on_input_started(&mut self) {
        if let Ok(me) = self.as_ref().checked() {
            me.stop_movement();
        }
    }

    #[ufunction]
    fn on_set_destination_triggered(&mut self) {
        let Ok(me) = self.as_ref().checked() else {
            return;
        };

        let delta = GameplayStatics::get_world_delta_seconds(me.as_ref().upcast_to()) as f32;
        self.set_follow_time(self.follow_time() + delta);

        let (hit, out_hit) = me.get_hit_result_under_cursor_by_channel(ETraceTypeQuery::TraceTypeQuery1, true);

        if hit {
            self.set_cached_destination(out_hit.as_ref().get_location().to_dvec3());
        }

        if let Ok(pawn) = me.k2_get_pawn().checked() {
            let direction = (self.cached_destination() - pawn.k2_get_actor_location().to_dvec3()).normalize_or_zero();
            pawn.add_movement_input(&FVector::from_dvec3(direction), Some(1.0), Some(false));
        }
    }

    #[ufunction]
    fn on_set_destination_released(&mut self) {
        if self.follow_time() <= self.short_press_threshold() {
            let destination = FVector::from_dvec3(self.cached_destination());
            AIBlueprintHelperLibrary::simple_move_to_location(self.as_ref().upcast_to(), &destination);
        }

        self.set_follow_time(0.0);
    }
}

impl ClickController {
    fn setup_input(&self) -> RustealResult<()> {
        let me: UObjectRef<PlayerController> = self.as_ref();

        if !me.checked()?.is_local_player_controller() {
            return Ok(());
        }

        enhanced_input_subsystem(me)?
            .checked()?
            .add_mapping_context(self.default_mapping_context(), 0, &OwnedStruct::new());

        let click = self.set_destination_click_action();
        bind_action(&me, click, ETriggerEvent::Started, "OnInputStarted")?;
        bind_action(&me, click, ETriggerEvent::Triggered, "OnSetDestinationTriggered")?;
        bind_action(&me, click, ETriggerEvent::Completed, "OnSetDestinationReleased")?;
        bind_action(&me, click, ETriggerEvent::Canceled, "OnSetDestinationReleased")?;

        Ok(())
    }
}
}

• simple_move_to_location is the Blueprint node Simple Move to Location: it pathfinds for the controller’s pawn, which needs the PathFollowingComponent the controller declares.
• The project needs the ai feature for bindings::ai (see Binding more of the engine), and the level a Nav Mesh Bounds Volume.
• Touch works the same with get_hit_result_under_finger_by_channel(ETouchIndex::Touch1, ...) and a second input action.

The template also spawns a Niagara effect at the clicked point: see Effects and sound.

Effects and sound

Two ways to play effects, and the templates use both:

• From the Blueprint child, through a BlueprintImplementableEvent the Rust class calls (BP_OnHit, BP_OnDeath): the artist picks and tunes the effect in the graph, and Rust says when. This is the default in the templates. See Functions.
• From Rust, with the engine’s functions, when the effect is part of the rule: a cursor marker where the player clicked, a sound at a computed location.

Use case: a Niagara effect at a point

The goal: a marker effect where the player clicked.

The project needs the niagara feature (see Binding more of the engine).

#![allow(unused)]
fn main() {
use bindings::niagara::{ENCPoolMethod, NiagaraFunctionLibrary, NiagaraSystem};

#[uproperty(EditAnywhere, name = "FXCursor", category = "Input")]
fx_cursor: UObjectRef<NiagaraSystem>,
}

#![allow(unused)]
fn main() {
NiagaraFunctionLibrary::spawn_system_at_location(
    self.as_ref().upcast_to(),
    self.fx_cursor(),
    &FVector::from_dvec3(location),
    &FRotator::from_rotator(Rotator::ZERO),
    &FVector::from_dvec3(DVec3::ONE),
    Some(true),
    Some(true),
    Some(ENCPoolMethod::None),
    Some(true),
);
}

The arguments after the scale are auto destroy, auto activate, the pooling method and whether to pre-cull. spawn_system_attached attaches the effect to a component instead, to follow it.

Use case: a sound at a location

#![allow(unused)]
fn main() {
use bindings::engine::{GameplayStatics, SoundBase};

#[uproperty(EditAnywhere)]
impact_sound: UObjectRef<SoundBase>,
}

#![allow(unused)]
fn main() {
GameplayStatics::play_sound_at_location(
    self.as_ref().upcast_to(),
    self.impact_sound(),
    &FVector::from_dvec3(location),
    &FRotator::from_rotator(Rotator::ZERO),
    None,
    None,
    None,
    None,
    None,
    None,
    None,
);
}

The Nones keep the defaults for volume, pitch, start time, attenuation, concurrency, owner and initial parameters. play_sound_2d plays a sound without a location (UI, music), and spawn_sound_at_location returns the audio component, to stop or fade it later.

Use case: a light on the character

The goal: a flashlight attached to the first-person camera.

#![allow(unused)]
fn main() {
use bindings::engine::{ELightUnits, LightComponentExt, LocalLightComponentExt, SpotLightComponent, SpotLightComponentExt};

#[uclass(parent = FirstPersonCharacter)]
pub struct HorrorCharacter {
    #[component(attach = "first_person_camera_component", name = "SpotLight")]
    spot_light: SpotLightComponent,
}

#[uclass_impl]
impl HorrorCharacter {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let light = self.spot_light()?.checked()?;
        light.set_intensity(1500.0);
        light.set_intensity_units(ELightUnits::Lumens);
        light.set_attenuation_radius(2000.0);
        Ok(())
    }
}
}

Turning it on and off is light.set_visibility(on, None), bound to an input action.

Use case: a MetaSound parameter

The goal: a tuning fork whose MetaSound plays a pattern chosen by a seed set on each placed fork.

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_tick(&mut self, _delta_seconds: f32) {
    if let Ok(audio) = self.audio().and_then(|a| a.checked()) {
        audio.set_int_parameter(FName::new("Seed").handle(), self.random_seed());
    }
}
}

The audio component’s Sound is the MetaSound source; any of its inputs is set by name with set_int_parameter, set_float_parameter or set_bool_parameter.

Use case: an effect a moment after a trigger

The goal: a confetti burst one second after a trigger first fires, and never again.

#![allow(unused)]
fn main() {
#[ufunction]
fn trigger_confetti(&mut self) {
    if self.fired() {
        return;
    }

    self.set_fired(true);
    KismetSystemLibrary::k2_set_timer(self.as_ref().upcast_to(), "Burst", 1.0, false, None, None, None);
}

#[ufunction]
fn burst(&mut self) {
    if let Ok(niagara) = self.niagara().and_then(|n| n.checked()) {
        niagara.activate(Some(true));
    }
}
}

The Niagara component is not auto-activated; activate(Some(true)) restarts it from the beginning.

Use case: playing a level sequence

The goal: walking into an area plays a cinematic placed in the level.

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_actor_begin_overlap(&mut self, _other_actor: UObjectRef<Actor>) {
    if let Ok(sequence) = self.seq_ref().checked()
        && let Ok(player) = sequence.get_sequence_player().checked()
    {
        player.play();
    }
}
}

seq_ref is a UObjectRef<LevelSequenceActor> set on the placed trigger. The project binds the sequencer modules with the level-sequence and movie features (see Binding more of the engine).

Vehicles

The vehicle template is the engine’s Vehicle template with its gameplay in Rust: a sports car and an offroad car on Chaos Vehicles, two cameras, a speed and gear HUD, and a time trial variant with laps.

rusteal new Racer --template vehicle
rusteal new Racer --template vehicle --variant time-trial

The project needs the chaos-vehicles feature, which the template turns on (see Binding more of the engine):

features = ["core", "engine", "input", "slate", "umg", "enhanced-input", "chaos-vehicles"]

[codegen.modules]
ChaosVehicles = { module = "chaos_vehicles", feature = "chaos-vehicles", plugin = "ChaosVehiclesPlugin" }

Use case: a car the player drives

The goal: a pawn on Chaos Vehicles, driven with Enhanced Input.

A car’s parent is WheeledVehiclePawn, which brings the skeletal mesh and the Chaos movement component. The input functions pass the axis values to the movement component:

#![allow(unused)]
fn main() {
use bindings::chaos_vehicles::{
    ChaosVehicleMovementComponentExt, ChaosWheeledVehicleMovementComponent, WheeledVehiclePawn,
    WheeledVehiclePawnExt
};
use bindings::enhanced_input::{ETriggerEvent, FInputActionValue, InputAction};
use rusteal_runtime::runtime::Checked;

#[uclass(parent = WheeledVehiclePawn)]
pub struct Car {
    #[uproperty(EditAnywhere, category = "Input")]
    steering_action: UObjectRef<InputAction>,

    #[uproperty(EditAnywhere, category = "Input")]
    throttle_action: UObjectRef<InputAction>,

    #[uproperty(EditAnywhere, category = "Input")]
    brake_action: UObjectRef<InputAction>,

    #[uproperty(EditAnywhere, category = "Input")]
    handbrake_action: UObjectRef<InputAction>,
}

#[uclass_impl]
impl Car {
    #[ufunction(Override)]
    fn receive_restarted(&mut self) {
        if let Err(e) = self.bind_input() {
            log::warn!("[Racer] input binding failed: {e}");
        }
    }

    #[ufunction]
    fn steering(&mut self, value: UStructRef<FInputActionValue>) {
        if let Ok(movement) = self.movement() {
            movement.set_steering_input(value.axis1d() as f32);
        }
    }

    #[ufunction]
    fn throttle(&mut self, value: UStructRef<FInputActionValue>) {
        if let Ok(movement) = self.movement() {
            movement.set_throttle_input(value.axis1d() as f32);
            movement.set_brake_input(0.0);
        }
    }

    #[ufunction]
    fn brake(&mut self, value: UStructRef<FInputActionValue>) {
        if let Ok(movement) = self.movement() {
            movement.set_brake_input(value.axis1d() as f32);
            movement.set_throttle_input(0.0);
        }
    }

    #[ufunction]
    fn start_handbrake(&mut self) {
        if let Ok(movement) = self.movement() {
            movement.set_handbrake_input(true);
        }
    }

    #[ufunction]
    fn stop_handbrake(&mut self) {
        if let Ok(movement) = self.movement() {
            movement.set_handbrake_input(false);
        }
    }
}

impl Car {
    pub fn movement(&self) -> RustealResult<Checked<ChaosWheeledVehicleMovementComponent>> {
        self.as_ref()
            .checked()?
            .get_vehicle_movement_component()
            .cast::<ChaosWheeledVehicleMovementComponent>()?
            .checked()
    }

    fn bind_input(&self) -> RustealResult<()> {
        let me = self.as_ref();

        if !me.checked()?.is_locally_controlled() {
            return Ok(());
        }

        bind_action(&me, self.steering_action(), ETriggerEvent::Triggered, "Steering")?;
        bind_action(&me, self.steering_action(), ETriggerEvent::Completed, "Steering")?;
        bind_action(&me, self.throttle_action(), ETriggerEvent::Triggered, "Throttle")?;
        bind_action(&me, self.throttle_action(), ETriggerEvent::Completed, "Throttle")?;
        bind_action(&me, self.brake_action(), ETriggerEvent::Triggered, "Brake")?;
        bind_action(&me, self.brake_action(), ETriggerEvent::Completed, "Brake")?;
        bind_action(&me, self.handbrake_action(), ETriggerEvent::Started, "StartHandbrake")?;
        bind_action(&me, self.handbrake_action(), ETriggerEvent::Completed, "StopHandbrake")?;

        Ok(())
    }
}
}

• get_vehicle_movement_component() returns the base Chaos movement component; casting it to ChaosWheeledVehicleMovementComponent reaches the wheeled vehicle’s settings.
• Binding Completed to the same function as Triggered sends the final value of the axis (zero) when the key is released, so the car stops steering and accelerating.
• The car’s mesh simulates physics and uses the Vehicle collision profile, set in class defaults: mesh.set_simulate_physics(true), mesh.set_collision_profile_name(FName::new("Vehicle").handle(), Some(true)).

The Blueprint child (BP_SportsCar_Pawn in the template) assigns the skeletal mesh, its physics asset, the Animation Blueprint that turns the wheels, and the input actions.

Use case: engine, gearbox and steering

The goal: tune how the car accelerates, shifts and turns, in code, as the C++ template’s constructor does.

The movement component’s setups are structs: EngineSetup, TransmissionSetup, SteeringSetup, DifferentialSetup. Read one, change its fields, and write it back, in class defaults:

#![allow(unused)]
fn main() {
use bindings::chaos_vehicles::{
    ChaosVehicleMovementComponentExt, ChaosWheeledVehicleMovementComponentExt, ESteeringType,
    FVehicleEngineConfigExt, FVehicleSteeringConfigExt, FVehicleTransmissionConfigExt
};

#[uclass(parent = Car)]
pub struct SportsCar {}

#[uclass_impl]
impl SportsCar {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let movement = Car::from_obj(self.as_ref())?.movement()?;

        movement.set_chassis_height(144.0);
        movement.set_drag_coefficient(0.31);

        let engine = movement.get_engine_setup();
        engine.as_ref().set_max_torque(750.0);
        engine.as_ref().set_max_rpm(7000.0);
        engine.as_ref().set_engine_idle_rpm(900.0);
        movement.set_engine_setup(&engine);

        let transmission = movement.get_transmission_setup();
        let gears = transmission.as_ref();
        gears.set_use_automatic_gears(true);
        gears.set_final_ratio(2.81);
        gears.set_change_up_rpm(6000.0);
        gears.set_change_down_rpm(2000.0);
        gears.forward_gear_ratios().set_all(&[4.25, 2.52, 1.66, 1.22, 1.0])?;
        gears.reverse_gear_ratios().set_all(&[4.04])?;
        movement.set_transmission_setup(&transmission);

        let steering = movement.get_steering_setup();
        steering.as_ref().set_steering_type(ESteeringType::Ackermann);
        steering.as_ref().set_angle_ratio(0.7);
        movement.set_steering_setup(&steering);

        Ok(())
    }
}
}

• The getter returns a copy of the struct; the setter writes the whole copy back. A field the code does not set keeps the engine’s default.
• An array inside a struct (forward_gear_ratios) is a UeArray view into the copy: set_all replaces it, push adds to it.
• The template keeps these steps in a small setup.rs module, with one function per setup, so each car’s class defaults read as a list of values.

Use case: the wheels

The goal: front wheels that steer and rear wheels that drive, each car with its own tires.

A wheel is a class whose parent is ChaosVehicleWheel, configured in class defaults. The movement component creates one wheel object per entry of its WheelSetups, from the class and the bone the entry names:

#![allow(unused)]
fn main() {
use bindings::chaos_vehicles::{
    ChaosVehicleWheel, ChaosVehicleWheelExt, ChaosWheeledVehicleMovementComponentExt, EAxleType,
    FChaosWheelSetup, FChaosWheelSetupExt
};

#[uclass(parent = ChaosVehicleWheel)]
pub struct FrontWheel {}

#[uclass_impl]
impl FrontWheel {
    #[class_defaults]
    fn class_defaults(&mut self) -> RustealResult<()> {
        let wheel = self.as_ref().checked()?;
        wheel.set_axle_type(EAxleType::Front);
        wheel.set_affected_by_steering(true);
        wheel.set_max_steer_angle(40.0);
        wheel.set_wheel_radius(39.0);
        wheel.set_wheel_width(35.0);
        Ok(())
    }
}

fn set_wheels(movement: &Checked<ChaosWheeledVehicleMovementComponent>) -> RustealResult<()> {
    let front = SubclassOf::<FrontWheel>::base().upcast_to::<ChaosVehicleWheel>();
    let rear = SubclassOf::<RearWheel>::base().upcast_to::<ChaosVehicleWheel>();

    let setups = movement.wheel_setups();
    setups.clear()?;

    for (class, bone) in [
        (front, "Phys_Wheel_FL"),
        (front, "Phys_Wheel_FR"),
        (rear, "Phys_Wheel_BL"),
        (rear, "Phys_Wheel_BR"),
    ] {
        let setup = OwnedStruct::<FChaosWheelSetup>::new();
        setup.as_ref().set_wheel_class(class);
        setup.as_ref().set_bone_name(FName::new(bone).handle());
        setups.push(&setup)?;
    }

    Ok(())
}
}

The bone names are the wheel bones of the car’s skeletal mesh. set_wheels runs in the car’s class defaults, next to the engine setup.

Use case: two cameras

The goal: a chase camera behind the car that the player can turn with the mouse and that recenters on its own, and a hood camera, toggled with a key.

#![allow(unused)]
fn main() {
#[uclass(parent = WheeledVehiclePawn)]
pub struct Car {
    #[component(attach = "mesh", name = "Front Spring Arm")]
    front_spring_arm: SpringArmComponent,

    #[component(attach = "front_spring_arm", name = "Front Camera")]
    front_camera: CameraComponent,

    #[component(attach = "mesh", name = "Back Spring Arm")]
    back_spring_arm: SpringArmComponent,

    #[component(attach = "back_spring_arm", name = "Back Camera")]
    back_camera: CameraComponent,

    front_camera_active: bool,
}
}

The front camera starts inactive (set_auto_activate(false) in class defaults). Toggling activates one and deactivates the other:

#![allow(unused)]
fn main() {
#[ufunction(BlueprintCallable)]
pub(crate) fn do_toggle_camera(&mut self) {
    let front_active = !self.front_camera_active();
    self.set_front_camera_active(front_active);

    if let Ok(front) = self.front_camera().and_then(|camera| camera.checked()) {
        front.set_active(front_active, None);
    }

    if let Ok(back) = self.back_camera().and_then(|camera| camera.checked()) {
        back.set_active(!front_active, None);
    }
}
}

Looking around turns the back spring arm (k2_add_local_rotation), and every frame it turns back toward the front:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_tick(&mut self, delta_seconds: f32) {
    let Ok(arm) = self.back_spring_arm().and_then(|arm| arm.checked()) else {
        return;
    };

    let yaw = arm.get_relative_rotation().to_rotator().yaw;
    let yaw = model::f_interp_to(yaw, 0.0, f64::from(delta_seconds), 1.0);

    arm.k2_set_relative_rotation(&FRotator::from_rotator(Rotator::new(0.0, yaw, 0.0)), false, false);
}
}

f_interp_to is the engine’s FMath::FInterpTo written in plain Rust in the template’s model.rs, where it is tested.

Use case: putting a flipped car back on its wheels

The goal: a car upside down for two checks in a row resets itself; a key resets it at any time.

A looping timer checks the car every few seconds:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_begin_play(&mut self) {
    KismetSystemLibrary::k2_set_timer(self.as_ref().upcast_to(), "FlippedCheck", 3.0, true, None, None, None);
}

#[ufunction]
fn flipped_check(&mut self) {
    let Ok(mesh) = self.as_ref().checked().and_then(|me| me.get_mesh().checked()) else {
        return;
    };

    let up_dot = DVec3::Z.dot(mesh.get_up_vector().to_dvec3()) as f32;
    let check = model::flip_check(self.previous_flip_check(), up_dot, -0.2);

    if check.reset {
        self.do_reset_vehicle();
    }

    self.set_previous_flip_check(check.flipped);
}
}

The reset lifts the car, keeps its yaw, teleports it and clears its velocity:

#![allow(unused)]
fn main() {
fn reset(&self) -> RustealResult<()> {
    let me = self.as_ref().checked()?;
    let location = me.k2_get_actor_location().to_dvec3() + DVec3::Z * 50.0;
    let yaw = me.k2_get_actor_rotation().to_rotator().yaw;

    let transform = KismetMathLibrary::make_transform(
        &FVector::from_dvec3(location),
        &FRotator::from_rotator(Rotator::new(0.0, yaw, 0.0)),
        &FVector::from_dvec3(DVec3::ONE),
    );

    me.k2_set_actor_transform(&transform, false, true);

    let mesh = me.get_mesh().checked()?;
    let zero = FVector::from_dvec3(DVec3::ZERO);
    mesh.set_physics_angular_velocity_in_degrees(&zero, None, None);
    mesh.set_physics_linear_velocity(&zero, None, None);

    Ok(())
}
}

The last argument of k2_set_actor_transform is the teleport flag: the physics body moves with the actor instead of being swept there.

Use case: speed and gear on screen

The goal: a HUD showing the speed, in km/h or mph, and the current gear.

The widget class declares what it can be told; its Widget Blueprint draws it:

#![allow(unused)]
fn main() {
#[uclass(parent = UserWidget)]
pub struct VehicleAdvUI {
    #[uproperty(EditAnywhere, BlueprintReadOnly, name = "bIsMPH", category = "Vehicle", default = false)]
    b_is_mph: bool,
}

#[uclass_impl]
impl VehicleAdvUI {
    #[ufunction(BlueprintImplementableEvent)]
    fn on_speed_update(&self, new_speed: f32) {}

    #[ufunction(BlueprintImplementableEvent)]
    fn on_gear_update(&self, new_gear: i32) {}
}

impl VehicleAdvUI {
    pub fn update_speed(&self, forward_speed: f32) {
        self.on_speed_update(model::display_speed(forward_speed, self.b_is_mph()));
    }

    pub fn update_gear(&self, gear: i32) {
        self.on_gear_update(gear);
    }
}
}

The player controller creates it and feeds it every frame:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_tick(&mut self, _delta_seconds: f32) {
    let (Ok(car), Ok(ui)) = (Car::from_obj(self.vehicle_pawn()), VehicleAdvUI::from_obj(self.vehicle_ui())) else {
        return;
    };

    if let Ok(movement) = car.movement() {
        ui.update_speed(movement.get_forward_speed());
        ui.update_gear(movement.get_current_gear());
    }
}
}

get_forward_speed is in centimeters per second; display_speed multiplies it by 0.036 for km/h or 0.022 for mph, as the C++ template does.

Screenshot: the vehicle template in play, with the gear and the speed in the corner of the screen. (images/recipes/vehicle_hud.png)

Use case: a time trial

The goal: a countdown, gates the car must pass in order, laps, and the best lap time.

The time trial variant uses four classes:

A gate checks that the car passing it is going to the right gate:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn receive_actor_begin_overlap(&mut self, other_actor: UObjectRef<Actor>) {
    let Ok(other) = other_actor.checked() else {
        return;
    };

    let Ok(mut controller) = TimeTrialPlayerController::from_obj(other.get_instigator_controller()) else {
        return;
    };

    let me: UObjectRef<TimeTrialTrackGate> = self.as_ref().cast().unwrap_or_default();

    if controller.target_gate() != me {
        return;
    }

    controller.set_target_gate(self.next_marker());

    if self.b_is_finish_line() {
        controller.increment_lap_count();
    }
}
}

The countdown is a widget animation in the Blueprint; when it ends, the Blueprint calls Finish Countdown, and two delegates carry the start to the controller:

#![allow(unused)]
fn main() {
#[uclass(parent = UserWidget)]
pub struct TimeTrialStartUI {}

#[uclass_impl]
impl TimeTrialStartUI {
    #[udelegate]
    pub fn on_countdown_finished(&self) {}

    #[ufunction(BlueprintImplementableEvent, name = "BP_StartCountdown")]
    fn bp_start_countdown(&self) {}

    #[ufunction(BlueprintCallable)]
    fn finish_countdown(&mut self) {
        self.on_countdown_finished();
    }
}
}

The lap UI creates the countdown when it is constructed, listens to it, and passes the start on with its own delegate, which the player controller listens to:

#![allow(unused)]
fn main() {
#[ufunction(Override)]
fn construct(&mut self) {
    if let Err(e) = self.start_countdown() {
        log::error!("[TimeTrial] could not start the countdown: {e}");
    }
}

fn start_countdown(&mut self) -> RustealResult<()> {
    let owning_player = self.as_ref().checked()?.get_owning_player();
    let start_ui = create_widget_of_class(&owning_player, self.start_ui_class())?;
    start_ui.upcast_to::<UserWidget>().checked()?.add_to_viewport(Some(0));

    let countdown = TimeTrialStartUI::from_obj(start_ui)?;
    countdown.on_countdown_finished_add_ufunction(&self.as_ref(), "StartRace")?;
    countdown.start_countdown();

    Ok(())
}
}

#![allow(unused)]
fn main() {
TimeTrialUI::from_obj(widget)?.on_race_start_add_ufunction(&controller, "StartRace")?;
}

Until the race starts, the controller keeps the car’s input off (pawn.disable_input(controller) when it possesses it, enable_input in StartRace). The lap times are plain Rust in time_trial/model.rs, with tests:

#![allow(unused)]
fn main() {
impl LapTimes {
    pub fn start_lap(&mut self, lap: i32, lap_start_time: f32) {
        let lap_time = lap_start_time - self.last_lap_time;

        self.best_lap_time = if lap <= 1 {
            -1.0
        } else if self.best_lap_time < 0.0 || lap_time < self.best_lap_time {
            lap_time
        } else {
            self.best_lap_time
        };

        self.current_lap = lap;
        self.lap_start_time = lap_start_time;
        self.last_lap_time = lap_start_time;
    }
}
}

In the editor

The gates are placed in the level, each one’s Next Marker set to the next gate in the Details panel, and the finish line has Is Finish Line checked and the tag the game mode’s Finish Tag names.