EDIT: These instructions tend to rot over time due to changes in xcode and SDL2's project structure.

Initialize a git repo and get SDL2

Run through these commands to init a git repo and grab SDL2.

cd ~/dev/rust
mkdir ios-sdl2
cd ios-sdl2
git init
git submodule add --name SDL2 https://github.com/spurious/SDL-mirror.git SDL2
git commit -m "Initial commit"

Now's a good time to add some things to your .gitignore

/target
Cargo.lock
xcuserdata

Commit the .gitignore

git add .gitignore
git commit -m "Add gitignore file"

Build SDL2

Open SDL2's iOS xcode project

open -a xcode SDL2/Xcode/SDL/SDL.xcodeproj

Set up the build scheme like this and hit play:

EDIT: The screenshot is a bit old, the correct setting is Framework-iOS > Any iOS Device (arm64 armv7)

Once this finishes, you will have a libSDL2.a file... somewhere. (xcode put mine somewhere in ~/Library/Developer/Xcode/DerivedData/HASHED_FOLDER/Build/Products/ - but that's fine. We'll pull it in later.

Include files are in SDL2/include

Setup the xcode project

xcode will be used to deploy your app to the device. There's an example project we can pull from SDL2 to help us get started

cp -r "SDL2/Xcode-iOS/Template/SDL iOS Application" xcode

We need to fix up a few names from the template. There's a placeholder ___PROJECTNAME___ used as both a filename and within some files. (That's PROJECTNAME surrounded by three underscores)

• Rename ___PROJECTNAME___.xcodeproj
• Find and replace ___PROJECTNAME___ in ios-sdl2.xcodeproj/project.pbxproj

Here's a script to do that and commit the changes

cd xcode
mv ___PROJECTNAME___.xcodeproj ios-sdl2.xcodeproj
sed -i "" 's/___PROJECTNAME___/ios-sdl2/g' ios-sdl2.xcodeproj/project.pbxproj
cd ..
git add xcode
git commit -m "Add xcode project"

Link against SDL2

Now launch xcode (the project is in /xcode/ios-sdl2.xcodeproj) and hit the play.

You should get an error like this:

SDL.h file not found

This is because we copy/pasted a template. It has paths that need to be fixed and will not build immediately.

Add SDL2 headers to the include path

• Open the files "tab" (see image below)
• Select the root node "ios-sdl2"
• Select Build Settings at the top

• Use the search below and to the right and find "User Header Search Paths"
• Double click and modify the entry to "../SDL2/include"

Fix Broken Reference to SDL2 Library

First, CLOSE ALL INSTANCES OF XCODE. We need to make absolutely sure the SDL2 project is not open. Otherwise the following steps will fail. Now reopen /xcode/ios-sdl2.xcodeproj

We should fix up the SDL.xcodeproj reference that's in the files list. Point it at SDL2/Xcode/SDL/SDL.xcodeproj.

This does a couple things:

• Makes SDL2 source code available in your project
• Allows you to easily static link against the output of this library

Add SDL2 as a Link Dependency

We need to fix up library reference so that the project builds.

• Select ios-sdl2 project in the top left corner. This will bring up the project configuration if it isn't already showing
• Scroll down to the Frameworks, Libraries, and Embedded Content section. You may see libSDL2.a with an empty outline

• If this is the case, select it and remove it with the "-".
• Click "+" so we can add it back correctly.
• Select libSDL2.a from the libSDL-iOS target and click add

Now it should look like this...

Final steps for Running in Simulator

If you try to run it now, you'll likely have a few link errors. Fix this up by going back to the Frameworks, Libraries, and Embedded Content section. Add these frameworks. (Click plus and type in the text box to quickly find it)

• AVFoundation.framework
• Security.framework

EDIT: I didn't need to do this step at this point, but I needed to add Security.framework later! (Also, you'll follow this step later to add a rust static library...)

With link errors solved, we get a new error message:

The application's Info.plist does not contain CFBundleShortVersionString.
Ensure your bundle contains a CFBundleShortVersionString.

Open Info.plist and add it.

• Open the files "tab" if it isn't already open
• Select Info.plist
• Right click Information Property List
• Select "Add Row"
• Type in CFBundleShortVersionString and hit enter. It will likely change to "Bundle version string (short)" - that's fine
• Set the value to "0.1.0"

At this point when you hit play, the simulator should come up. SDL2 should load and start drawing!

Deploying to a device

To follow this step, you may need an apple developer account. I'm not going to cover this in detail but I'll just mention briefly a few things I set:

• In the project settings under General, you can pick a target version, like iOS 12.4
• In the project settings under Signing & Capabilities, select your team and set a bundle identifier
• When I switched to iOS 12.4, I needed to add Metal.framework

Finally, write some Rust!

Time to get a rust project up and running! The general approach is that we will create a C library, link it, and call into it. I highly recommend checking out this repo: https://github.com/thombles/dw2019rust. Most of the below steps are covered in detail there.

First thing you'll need to do is grab the rust toolchains for:

• Physical devices: aarch64-apple-ios
• Simulators:  x86_64-apple-ios

rustup target add aarch64-apple-ios x86_64-apple-ios

Now create a rust library

cargo new --lib game-ios

Modify the .toml to create a library. I'll also add in sdl2 and a simple logging crate.

[lib]
crate-type = ["lib", "staticlib"]

[dependencies]
sdl2 = "0.34"
env_logger = "0.6"
log="0.4"

And modify lib.rs

#[no_mangle]
pub extern "C" fn run_the_game() {
    env_logger::Builder::from_default_env()
        .filter_level(log::LevelFilter::Info)
        .init();

    log::info!("Started!");
}

Finally, some rust code! Rather than a standard main function, we expose a C-ABI compatible function. The main.c in our xcode project can link against the library created by rust and call into it.

For convenience, create an example. This allows building and running the library outside of xcode. I added examples/run_the_game.rs with:

use game_ios::*;

fn main() {
    run_the_game();
}

Add a workspace file (Cargo.toml) at the root of the project

[workspace]
members = [
    "game-ios",
]

This does two things:

• Allows you to run cargo build and cargo run --example run_the_game in the base of the project
• Puts the output folder ("target") in the base of the project

At this point your project structure should look like this:

Linking Rust from xcode

First, let's automate building the rust project from xcode. Here's a script that will work. For information about the "lipo" commands, see here: https://github.com/thombles/dw2019rust/blob/master/modules/02 - Cross-compiling for Xcode.md

set -e
RUST_PROJ="/Users/pmd/dev/rust/ios-sdl2" <-- EDIT TO MATCH YOUR PATH
PATH="$PATH:/Users/pmd/.cargo/bin" <-- EDIT TO MATCH YOUR PATH

cd "$RUST_PROJ"
cargo build --package game-ios --target aarch64-apple-ios --verbose
cargo build --package game-ios --target x86_64-apple-ios --verbose

lipo -create target/aarch64-apple-ios/debug/libgame_ios.a target/x86_64-apple-ios/debug/libgame_ios.a -output target/libgame_ios.a

We can add this to xcode.

• Open the project settings and under the "Build Phases" section
• Add a Run Script phase
• Drag it up to be earlier in the build
• Add the script. Be sure to update the paths!

More info on setting up build scripts here: https://github.com/thombles/dw2019rust/blob/master/modules/04 - Build automation.md

Errors you might see now:

• library not found for -ISystem/linking with cc failed: exit code 1: I didn't use to have this problem and hopefully there's a better solution... but running cargo build manually once fixed it for me
• Missing symbol _run_the_game: follow the steps above "Final steps for Running in Simulator" to add the rust static library to your project. It's in target/libgame_ios.a

This will likely fail with an error message about a missing symbol

Finally, we need to add the rust output directory to the library search path. This is in the same area we updated the include paths for SDL.

Starting the Rust Code

We're close! Update main.c

// Including SDL.h is required to let SDL hook main and set up the app delegate
#include "SDL.h"
#include <stdio.h>

extern void run_the_game();

int main(int argc, char *argv[])
{
    run_the_game();
    printf("run_the_game returned");
    return 0;
}

If you get a linker error "Undefined symbol: _SecRandomCopyBytes", ensure Security.framework is included. (See steps above)

Now you should see in the output:

[2020-07-21T07:08:50Z INFO  game_ios] Started!
run_the_game returned

One More Build Config Setting

Rust does not produce bitcode compatible with xcode LLVM. So to run on a physical device, it must be disabled. It's in the same area as where we modified header/library paths, but make sure to enable showing "All" settings. More info here: https://github.com/thombles/dw2019rust/blob/master/modules/02 - Cross-compiling for Xcode.md#1-use-a-physical-iphone-or-ipad

A More Visual Demo

This code will make the screen change colors and print events to the console

use sdl2::pixels::Color;
use sdl2::event::Event;
use sdl2::keyboard::Keycode;
use std::time::Duration;

#[no_mangle]
pub extern "C" fn run_the_game() {
    env_logger::Builder::from_default_env()
        .filter_level(log::LevelFilter::Info)
        .init();

    log::info!("Started!");

    do_run_the_game().unwrap();
}

pub fn do_run_the_game() -> Result<(), String> {
    let sdl_context = sdl2::init()?;
    let video_subsystem = sdl_context.video()?;
    let window = video_subsystem.window("rust-sdl2 demo", 800, 600)
        .position_centered()
        .opengl()
        .build()
        .map_err(|e| e.to_string())?;
        
    let mut canvas = window.into_canvas().build().map_err(|e| e.to_string())?;

    canvas.set_draw_color(Color::RGB(255, 0, 255));
    canvas.clear();
    canvas.present();
    let mut event_pump = sdl_context.event_pump()?;

    let t0 = std::time::Instant::now();
    
    'running: loop {
        for event in event_pump.poll_iter() {
            println!("{:?}", event);
            match event {
                Event::Quit {..} | Event::KeyDown { keycode: Some(Keycode::Escape), .. } => {
                    break 'running
                },
                _ => {}
            }
        }
    
        let time = (std::time::Instant::now() - t0).as_secs_f32();
        let fraction = (time.sin() + 1.0) / 2.0;

        let color = (fraction * 255.0) as u8;
        canvas.set_draw_color(Color::RGB(0, 0, color)); 
        canvas.clear();
        canvas.present();
        ::std::thread::sleep(Duration::new(0, 1_000_000_000u32 / 30));
    }

    Ok(())
}

Commit all the changes

git add .
git commit -m "Rust app works"

And the output is here:

In late 2019/early 2020, @kabergstrom and I explored how legion and atelier-assets could be integrated together, particularly in the context of implementing an editing workflow. Some of the goals we started with are here: Rich Editing Experience Using atelier-assets and legion.

After we produced a working prototype implementing interactive editing, including support for undo and redo, I reworked my own engine to use it.

Video: https://www.youtube.com/watch?v=9Vwi29RuQBE&feature=youtu.be

Github: https://github.com/aclysma/atelier-legion-demo.git

This document demonstrates what using the API feels like and discusses the lessons learned during implementation.

As a quick feature run-down, the demo supports:

• Loading and saving the edited state as a prefab
• Hot-reloading the edited state when the file changes
• Undo and Redo
• Creating/Deleting entities
• Adding/Removing components
• Multiple selection
• Drag to transform, scale, and rotate
• Rendering and physics components respect transform, scale, and rotate component data.

In order to try the demo for yourself, you can do something like this:

git clone https://github.com/aclysma/atelier-legion-demo.git
cd atelier-legion-demo
git submodule init
git submodule update
cargo run

Cloneable and Non-Cloneable Components

The demo contains components that represent position, rotation, and scaling. Additionally, it has a few components for rendering and physics.

These components can be divided into two categories - cloneable and non-cloneable.

The components in this image are examples and don’t necessarily match the demo

Cloneable Components

Cloneable components must implement a number of traits:

• Clone - Used for cloning edit-time data into the runtime world
• Serialize/Deserialize - Used for saving/loading data in the editor
• Default - Used when adding a component to an entity to determine initial state
• PartialEq - Required for SerdeDiff…
• SerdeDiff - SerdeDiff lets us determine what changed in user-edited data
• TypeUuid - In our implementation, we use UUIDs to identify types in a registry.

If a structure implements the above traits, then it can be used to represent a component at all stages of the pipeline - editing, loading, and running.

One example of this would be a Position component. It might be defined like this:

#[derive(
    Clone, Serialize, Deserialize, Default, 
    PartialEq, SerdeDiff, TypeUuid
)]
#[uuid = "8bf67228-f96c-4649-b306-ecd107194cf0"]
Struct PositionComponent {
    position: Vec3
}

The PositionComponent structure defines the format of positions at edit/load time as well as at runtime in the shipped game.

Non-Cloneable Components

Sometimes, components at runtime won’t be able to implement some of these traits. A common case is data within the component that is not cloneable or serializable. For example, a physics component that represents a rigid body attached to the entity might need a handle to the rigid body in a physics engine.

This clearly can’t be serialized as it would be meaningless once deserialized. Further, the data required to describe how to create the rigid body is not the same as the data required to represent the rigid body once it has been created.

In order to support this, we have the concept of ComponentDefinitions. The ComponentDefinition is used for editing and loading and the actual Component is only used in the game world at runtime.

// This is the edit-time representation, it must support
// a number of traits
#[derive(
    Clone, Serialize, Deserialize, Default, 
    PartialEq, SerdeDiff, TypeUuid
)]
#[uuid = "8bf67228-f96c-4649-b306-ecd107194cf1"]
pub struct RigidBodyBallComponentDef {
   pub radius: f32,
   pub is_static: bool,
}

// Runtime data, no derives required for this!
pub struct RigidBodyComponent {
   pub handle: DefaultBodyHandle,
   delete_body_tx: crossbeam_channel::Sender<DefaultBodyHandle>,
}

In this example, the handle points to a rigid body stored in an nphysics world.

It’s important to note here, for non-cloneable components, the end-user does not edit actual component data - they edit the component definition. So from an end-user’s perspective, they just see radius and is_staticas editable fields.

Transforming from Definitions to Components

We support three methods for a downstream user to transform a component definition into a real components:

Via Into/From

If an end-user implements the standard library’s Into or From, the components can simply be registered like this:

registry.add_mapping_into::<RigidBodyBallComponentDef, RigidBodyComponent>();

The engine will do the equivalent of…

let component = component_definition.into();

…to spawn the component

Via SpawnInto/SpawnFrom

While using Into/From is convenient and familiar to many, it does not allow us to pass extra data for the end user’s implementation to use. In order to support this, we have parallel traits SpawnInto/SpawnFrom that mimic Into/From, but allow the end user to access other entity or system data.

/// Trait for mapping one type into another with world.clone_from()
pub trait SpawnInto<IntoT: Sized>
where
   Self: Sized,
{
   fn spawn_into(
       src_world: &World,
       src_component_storage: &ComponentStorage,
       src_component_storage_indexes: Range<ComponentIndex>,
       resources: &Resources,
       src_entities: &[Entity],
       dst_entities: &[Entity],
       from: &[Self],
       into: &mut [MaybeUninit<IntoT>],
   );
}

One expected usage would be looking up position/rotation/scaling components on the entity to properly place the rigid body into the world. Another expected usage includes looking up a system. In the case of a rigid body component, we might need write access to the physics world so that we can insert the rigid body and get a handle to it.

The SpawnInto/SpawnFrom traits operate on blocks of data at a time. For example, if a prefab contains many entities with RigidBody components, construction of those components can be batched.

Via Closure

We also support using a closure, equivalent to the SpawnFrom/SpawnInto trait

clone_merge_impl.add_mapping_closure::<RigidBodyBoxComponentDef, RigidBodyComponent>(|
   src_world,
   src_component_storage,
   src_component_storage_indexes,
   resources,
   src_entities,
   dst_entities,
   src_data,
   dst_data
| {
   // implement here
};

In practice, since the closure needs to take so many parameters, using the SpawnFrom/SpawnInto trait ends up being cleaner. However, it could be useful for cases where it’s not possible to implement the trait due to Rust’s orphaning rules.

Diffing Components

In order to implement the demo, we needed a way to detect and reproduce changes to data in a general way. We published a new crate, serde-diff, that allows two instances of the same struct to be compared, resulting in a Diff. The Diff is serializable/deserializable and can be re-applied to other instances of the same struct. This is used for two major features - transactions and prefabs.

Transactions

In the demo, the editing tools do not modify world data directly. Instead, when a tool needs to modify state, it creates a transaction. Any entities that will be modified are added to the transaction. This allows the transaction to copy entity data into two new legion worlds - a baseline “before” state that is immutable, and the mutable “after” state.

// Example of creating a transaction
let tx = TransactionBuilder::new()
    .add_entity(entity_one)
    .add_entity(entity_two)
    .begin(universe, world, clone_impl);

Most of the time the transaction will just operate on whatever is selected in the editor. In the demo, we have a shorthand for this.

// Create a transaction - this helper function adds all 
// the selected entities to the transaction
let tx = editor_ui_state.create_transaction_from_selected(
    &*editor_selection,
    &*universe_resource,
);

The end-user’s code can then modify the transaction’s world freely. This code that performs the edit doesn’t need to be aware of the transaction - just the transaction’s “after” legion world (likely passed via mutable ref).

// Adding, deleting, and modifying entity data is supported here
tx.world_mut().delete_all();

Once the end-user’s code runs, the transaction can be committed. The data owned by the transaction in the “before” and “after” worlds is compared to produce diffs. The diff data supports creating/destroying entities, adding/removing components, and modifying component data.

// Now generate the necessary data to apply/revert the change
let tx_diffs = tx.create_transaction_diffs(component_registry);

The TransactionDiffs returned by create_transaction_diffs contains an “apply” set of diffs and a “revert” set of diffs.

These diffs can be used for several purposes:

• Applying changes to the runtime state
• Sending the changes back to the atelier daemon to commit changes to disk, and possibly other connected devices
• Implementing Undo/Redo

Prefabs

Because serde-diff allows us to capture and persist changes with per-field granularity, we can use it to implement prefabs. Prefabs can contain entities and references to other prefabs. The “prefab references” can also include diffs to be applied to components of specific entities in the referenced prefab.

Prefabs can be stored in two forms, cooked and uncooked.

Uncooked Prefabs

Uncooked prefabs are hierarchical and editor-friendly. In memory, an uncooked prefab contains a legion world with entity data and references to other prefabs. These prefab references also contain any diffs that would need to be applied to the referenced prefab.

Cooked Prefabs

At runtime, we don’t want to incur the cost of loading and tracking a prefab hierarchy or applying the diffs. To avoid the cost, we can flatten an uncooked prefab and all the other uncooked prefabs that it references into a single cooked prefab where all the data is stored in a legion world. Spawning such a prefab is straightforward - the data is simply cloned or transformed from the cooked prefab’s legion world into the game world.

Currently, the demo is loading uncooked prefabs and cooking them “in-game”. In the future, the cooking process would be pulled into atelier assets and the game would only interact with cooked prefabs.

When we make this change, we can still use transaction diffs. The editor can immediately apply the diffs to in-memory cooked data, allowing for a responsive editor experience. (For example, selecting entities and dragging them to change their position.) Additionally, the editor can forward the diffs to the daemon, which can apply the diffs to the uncooked form (potentially to be saved to disk.)

Component Registration

In order for Rust to emit the necessary code for cloning, creating diffs, applying diffs, etc., there must be a registry for all component types. Registering the component will cause rustc to emit all the necessary code to support contrustructing, transforming, and diffing components.

Additionally, this component registry can be used to implement the CloneImpl trait, required to use clone_from in legion.

Key Lessons/Techniques Learned

Putting Everything into Legion Worlds Works Well

We are using legion for storing data in uncooked prefabs, cooked prefabs, transactions, and runtime data. In order to copy and transform data between these worlds, we developed a new “clone_from” feature in legion.

This allows us to use a relatively small amount of code to accomplish quite a lot - and any fixes/improvements/tooling can potentially benefit all stages of the pipeline. Further, the onboarding process for using the engine is quicker since once someone has working knowledge of legion, they can comfortably interact with data across the entire pipeline.

Using Diffing/Transactions is both Powerful and Intuitive

If someone wants to implement a new tool in the demo, they only need to know how to create a transaction and apply the change to a legion world. The lowers the barrier to contributing new features and the simplicity makes it likely that the tool will be robust from the start.

Using this API provides automatic support for undo/redo, a notoriously difficult and error prone feature to implement by hand.

Separating Creation and Runtime Data is Beneficial

It’s common that the data required to create a component is not the same as the data required to represent the component at runtime. Further, it’s common for runtime data to not be cloneable, serializable, or both. (For example, any FFI type.)

Integrating a physics engine with an ECS is a common question that comes up in a community - and often the solution is awkward. But by separating the construction data and runtime data, and providing a way to see init data for other components (like position,) we produced a clean integration between nphysics and legion.

We believe that many systems with runtime handles can be made cleaner by maintaining this separation of initialization and runtime data.

Immediate-Mode UI is Quick and Easy to Use

For this project, we used imgui. We appreciated that we only needed to work in a single language to prototype UI, and that it’s API is straightforward to use.

In addition to imgui, we have a simple immediate-mode shape drawing API that detects clicking and dragging. This made implementing interactive widgets in world space more straightforward.

Conceivably other interactive tools could be built on top of this fairly easily, and the code that implements it won’t need to worry about coordinate systems, windowing, or input devices. It just knows that the line it asked to be drawn (using world-space coordinates) was dragged.

Generally, we believe that for an open source editor to work, it must be easy and straightforward to create tools that are efficient and reliable. New contributors need to be productive with little ramp-up time or help, and the code they produce needs to be easily readable by others. Coordinate space changes can be very tricky and removing the need to deal with this in every editor tool reduces the maintenance workload for everyone.

Unsolved Problems/Future Work

Editing Prefabs by Hand

While the demo technically supports nested prefabs, the format they are stored with is not very human readable. Currently, the data for specifying component overrides for an entity in a referenced prefab is stored like this:

component_overrides: [
   (
       component_type: "f5780013-bae4-49f0-ac0e-a108ff52fec0",
       diff: r##"[ Enter(Field("position")), Value(Vec2(300.0, 300.0)) ]"##,
   ),
],

In this case, the component_type guid indicates that it’s a Position component, and the diff field describes a sequence of enter/value/exit commands.

While a sequence of commands is runtime performance friendly (aside from using strings), any non-trivial example becomes painful to read and write in a text editor. When saving this data in user-readable formats like RON, we would like to explore saving it in a more familiar hierarchical form. For example, [Enter(Field(“Circle”)), Enter(Field(“Radius”)), Value(5.0)] could be represented as { Circle: { Radius: 5.0 } } or { “Circle.Radius”: 5.0 }

It should be possible to convert between commands and either of the other forms. So we believe this to be a very solvable problem, just a matter of putting in some time to implement it. To generalize, we want serde_diff to support both a human-readable format and a machine-readable format.

Editing Prefabs with a UI

Currently, we do not support any form of prefab editing. All changes are applied directly to the opened prefab entities.

Designing a UI to work well with this is a lot of work and ended up being out of scope for this demo. Much of the groundwork to create such a UI is laid with the APIs for prefab cooking being implemented in the demo and this is an area that is ripe for experimentation and prototyping.

Entity References

It’s not uncommon for one entity to need to reference another entity. For example, a heat-seeking missile meant to follow a player in a game might be implemented as a missile entity and a player entity, and the missile entity might have a component that needs to reference the player entity.

Currently, when we clone merge components from one legion world to another, any Entity stored in a component is naively copied by value. It still refers to an entity in the old world. Ideally, we could detect that an entity reference exists in component data and fix the copy in the new world to point to the copied entity in the same (new) world.

We don’t want to add complexity to legion’s Entity type, so we are considering adding a new type, EntityHandle. We could use the same technique as we use for asset handles where we store context data in TLS. This would allow serialization/deserialization to look up what a particular Entity reference should be changed to, and we can use a custom Clone impl to patch the reference as it is cloned.

Sharing Editor Code

Ideally we’d like to wrap up the editing tools in this demo in a way that is reusable. (For example, dragging an entity to change the position, or just detecting that an entity has been clicked.)

As it is now, if someone wants to use the editing tools in the demo, they would need to copy the code and modify it to use their math and input libraries of choice. This will make it difficult for us as a community to share tooling improvements.

Unfortunately, the editor code needs to be aware of coordinate systems, input, and windowing code. Much of the choices for these things are opinionated and game-specific.

We haven’t done much work on this yet, but we are hoping that we can insert a layer of abstraction using a trait object to handle this. The reusable editing tools could then delegate the opinionated and game-specific logic to a trait object provided by the user.

Saving Edited Data to Disk

Atelier currently does not support writing modified data back to disk. While we do have a plan for implementing this (see the “Prefabs” section) it requires further work in atelier to support it.

However, there is value in having opinionated guides to the ecosystem, even if the working group isn't the right place for it. It was proposed that individuals could write their own guides to fill this purpose. So here's mine!

I've only been involved in the Rust community for a few months, so I haven't actually used that many of these. However, I'll list out where I would point someone if they asked.

All-In-Ones

My personal preference is to find things that do one thing well and glue them together. But, if I wanted to ship something ASAP in Rust, I'd probably start with ggez, mostly because it's based on an existing framework. Or SDL2 if you want something battle-tested and don't mind native code

• ggez - It's been around for a while, and it's based on an existing technical design (LÖVE). It also has clearly defined scope. If I were looking for a single library to meet broad but basic needs, I would start here.
• amethyst - This is a big ambitious project, and clearly a lot of good work has gone on here. They even have some sponsors!
  • The scope is very ambitious, and until recently it wasn't clear if there was much practical usage to help inform the technical design. However, they recently announced two showcase games. I'm hoping this will help prioritize the minimum required features for this project to see real-world usage.
  • Several reusable libraries (rendy, sheep, laminar) have come from this community already. This has been to the benefit of the broader ecosystem.
  • I wouldn't discourage anyone from giving this one a try.
• sdl2 - Putting Rust logic on top of proven, shipped C code is a legitimate strategy.
• coffee - Worth keeping an eye on! It's still... brewing.
• piston - Mentioned for completeness because it's been around for a long time and it has lots of downloads on crates.io. But the technical design, vision, and scope does not seem as well-defined as amethyst or ggez.

Low-Level Rendering

icefoxen's guide is more detailed than what I intend to do here, so I highly recommend giving that one a look.

First, you need a window to draw on. You will almost certainly use winit and most (all?) of the below build on that. (May 2020 edit: I've switched to using sdl2 for window management)

Once you have a window, there are a few options:

• There are wrappers around C-APIs if you want to write DirectX, Vulkan, etc. directly. (ash, winapi/d3d12-rs, gl-rs, metal-rs)
• There is a Vulkan-like API gfx-hal that abstracts all these that quite a few people are using. It makes no attempt to be safe. There's a good tutorial available for this one.
• The amethyst crew recently put out rendy. It sits on top of gfx-hal and takes care of a lot its boilerplate, but without hiding gfx-hal itself. You'll still need to write some "unsafe" code.
• There are a couple "safe" (mostly) crates around OpenGL, glium and luminance. And gfx (before it became gfx_hal) attempted to be a safe API as well.
• (July 2020 edit: I've been working on my own renderer)

I'm personally using Rendy, and I think gfx-hal and rendy are likely to be broadly adopted and supported long term. (May 2020 edit: I've switched to using ash/vulkan directly)

For higher level rendering, you could use sdl2, one of the above all-in-ones, or if you just want some shapes (pong?) maybe even wrap something like skia. There's even some terminal rendering libraries like tui-rs if you want to make something truly old-school. (May 2020 edit: I released Skulpin last year which embeds Skia into a Vulkan-backed window. It's even getting some real use!)

ECS

If you don't know what this is, I'd watch this video. ECS designs have their own merit, but aside from those benefits, specifically in Rust, they provide a good foundation that is relatively friendly to the borrow-checker.

• specs is by far the most popular. It's a great place to start. There are some good ideas in legion too.
• For a while I used shred - which is basically specs without the entities/components.

I ended up doing my own thing, but it's too early to recommend it to anyone in good conscience. (May 2020 edit: I've switched to legion, highly recommended!)

Math

There was a lot of good discussion here about the state of math libraries in Rust.

• nalgebra is complete, well documented, and likely to be maintained for a long time. However, in my opinion, it is overly general for gamedev. nalgebra-glm is a wrapper that pairs most of that back.
• If you want something lower level, look at glam. It's a bit more efficient too.
• In my opinion, the ideal math crate for lowest-level gamedev math in Rust does not exist yet. If I were to build it myself, I would port DirectXMath without attempting to be Rust idiomatic. Then I'd put a wrapper around it that looks more like glam. (May 2020 edit: Using glam for now!)

Physics

• nphysics is a solid default choice. I think it has a bright future ahead of it. It uses nalgebra, so using both of them together is a natural choice.
• You could also go with bullet or box2d. I'm not sure what the state of using this in Rust would be. Bullet has heavy integration with python, so I expect their C bindings are fairly complete. Embark very recently released some physx bindings as well.

Sound

I haven't gotten far enough along to care about audio yet. There are some audio crates (cpal and rodio), but I haven't heard glowing reviews for any of them. I'd consider wrapping some C/C++ code. First places I'd look are sdl2, SoLoud, FMOD (not open source), and OpenAL.

Networking

Networking in gamedev is a really complex topic. It's actually my day job. But I haven't gotten far enough along to try anything myself in Rust yet.

I'm going to consider backend systems out of scope for the time being. And with async/futures landing imminently, the state of that ecosystem is likely to change. (keep an eye on tokio)

For replicating simulations:

• Amethyst is working on laminar but I'm not sure how far along they are.
• The fastest path to ship something today is probably going to be opening a TCP socket and doing it yourself. Some kinds of games won't work well on TCP, but many will.
• But if you want to use UDP, enet will at least get you started with a reliable UDP implementation with flow control.

Honorable Mentions

• (May 2020 edit: atelier-assets makes a great asset pipeline although it may be overkill for some people)
• imgui-rs is awesome. I'm using it. In its current form you may need some unsafe code to make it easier to use.
• serde is a flexible serialization library
• strum for turning enums into strings, and counting the number of elements in an enum
• named_type for getting names out of types at runtime
• quote and syn to get compile-time reflection (this is deserving of a blog post later)
• log and env_logger for a basic logging framework. (but tracing looks promising)
• lazy_static for those times you really need a global
• If you need something from C/C++ likely someone already wrapped it for you! For example, I ported some code to rust that used gpc - I was able to drop that into Rust and it worked immediately.
• image is the unsung hero of loading textures
• sheep for sprite sheet processing (it's pretty new!)

Final Comment

I will probably write something more about this later, but dependency management is one area where Rust shines. I expect that this will enable the community to build many small, high quality, single-purpose libraries that do one thing well. I think this will be key in the formation of a vibrant ecosystem that can support a broad variety of games and creators.

Lately, I’ve been exploring rust.

Why Rust?

My interest in Rust grew as I became aware of these three facts:

1. Rust has been the “most loved” language in the stack overflow developer survey four years in a row.
2. Rust is a memory-safe language with performance comparable with C++! (It in fact goes through the same optimizer that clang uses, LLVM) (See also latest techempower benchmarks)
3. Rust carries forward two very important features of C++:  destructors, and const-ness.

My Favorite Feature in C++ is Back!

Memory, locks, file handles, database transactions, TCP sockets: Good software engineering is all about resource management.

In my opinion, the single most important feature of C++ is the destructor. RAII-style programming leverages the destructor to ensure that cleanup code always runs. Further, it's clearly defined when it will run. For many of these resources, the timing is crucially important.

void write_to_db(DatabaseConnection &connection)
{
    Transaction tx = connection.StartTransaction();
    Data d = get_data();
    tx.write_data(d);
    
    // * Transaction has a destructor, so we can't forget 
    //   to clean it up.
    // * Even if get_data() throws an exception, it is still 
    //   guarateed to be cleaned up!
    // * Any code that run after leaving this function can safely
    //   assume the transaction is written
}

I'm having a hard time thinking of a recent popular language that isn't garbage collected. I think garbage collection can be a good solution for managing memory in many cases, but I also believe that garbage collection is a targetted solution for memory management that ignores the general problem of resource management.

const++

Rust has the concept of immutability, and when I first looked at the language, I thought that the mut keyword was roughly equivalent to not-being-const in C++. (In Rust, dangerous features are opt-in, rather than opt-out.) But as it turns out, rust takes the concept further.

Many languages (like C++) are not particularly “aware” of threads. Sure, you can call an API that will make the OS spawn a new thread, executing your code. But there is no static analysis that reasons about that thread, and there are no language facilities to add helpful annotation for that analysis. Most languages make no effort to help you write correct multi-threaded code.

use std::thread;
fn main() {
    let mut numbers = vec![17, 42, 5];
    thread::spawn(move || { 
        //        ---- <-- Notice the move keyword!
        numbers[0] = 2;
        println!("The first number is now {}", numbers[0]);
    });

    // A subtle problem.. this push could cause the Vec to allocate
    // a new buffer. The other thread could read/write to this buffer
    // during this time, resulting in undefined behavior!
    numbers.push(20);
}

ReadWrite locks are a common and useful synchronization primitive, and Rust somewhat bakes this into the language. Holding an immutable reference to string is a bit like holding a read lock, and having a mutable reference is a bit like holding a write lock. However, all of this happens at compile time. Rust has a powerful static analysis system (people call it the “borrow-checker”) that ensures the written code never violates the constraint of "many readers, or one writer, but never at the same time."

The type system is even aware of “moving” data across threads, and can provide compile-time errors for when, for example, an OpenGL context gets shared across a thread boundary.

By the way, Rust's memory model also allows it to aggressively use noalias – so it's entirely plausible for Rust to be faster than C++ on average, despite using the same optimizer. (Well, if it weren't for bugs in llvm, that is.)

Free Lunch?

And here we come to the downside. Rust is not an easy language. The static analyzer must be able to understand your code, or you have to opt-out of the safety it provides. Lifetime annotation in Rust is powerful, but it is a new and complex language concept. Some designs work well with it, and some don’t. Even some "sound" designs are just not practical to use in Rust.

But it's not all bad. My experience so far has been that when code is sufficiently complicated that the borrow checker cannot validate it, it’s a code smell. But when the code can be validated, it very often works on the first try. That's a great property to have in a language! Designs that work well with the borrow checker are safe and tend to be very maintainable code.

Scalability

When I say “scalability” in the context of a language - what I mean is the ability of a codebase and team to change and grow in size, without diminishing returns of productivity. Requirements change, and code routinely needs to be refactored. Ideally, our tools for detecting errors in code are thorough enough that we can change our code without fear.

Dynamically-typed languages like python and javascript are not scalable. I'm amazed that the linting tools for python and javascript work as well as they do, but they simply cannot match a typesafe language's ability to find silly bugs as early as possible.

While C++ is not dynamically typed, it has it's own major scalability problem. Just as renaming a variable can cause unexpected runtime errors in a dynamically typed language, so also can altered memory access patterns cause unexpected runtime errors in a C++ application. This can lead to all sorts of unpleasant surprises at runtime.

Memory usage semantics should be part of the API, both for readability, and for compile-time verification. Here’s a C++ example to illustrate:

void the_function(char *buffer);
void the_function(char &buffer);
void the_function(std::unique_ptr<char *> buffer);

These are all different ways to effectively pass a pointer. But an experienced C++ developer could intuit certain things from the second and third case, where the first case would be ambiguous. Rust makes these semantics explicit, and enforces them.

This is not only beneficial to teams, but also the OSS community in general. When semantics for memory handling and concurrency are part of the API, breaking upstream changes are much more likely to be caught!

The Inflection Point

It’s easy to speak of Rust as a language, but it’s probably more correct to consider it as an ecosystem. For-profit ventures require libraries for common functionality, tools for enhancing productivity, and a talent-pool to hire from. Deficiencies in these and other areas represent risks to a project, and every organization has its own tolerance for risk.

However, I think this ecosystem is going to be big. As long as people enjoy working in it (and apparently they do, for four years running!), more libraries will be written, the tooling will get better, and the talent pool will grow. I’d like to see a bit more corporate investment, and not just from mozilla. But even in the last half year, there have been promising signs from Microsoft, Facebook and Amazon.

• Microsoft Security Response Center endorsed Rust in a recent blog series ("Rust represents the best alternative to C and C++ currently available.")
• Facebook’s new cryptocurrency is implemented in Rust
• Amazon is using Rust for virtualization technology

I think Rust is in an incredible position for exponential growth. I'm very excited about the ecosystem's future!