NEOLearn

Resources

Store global data such as settings, scores and timers as resources, add them to an app, and read or change them from systems with Res and ResMut.

Updated October 20, 2026

On this page

A resource is a single value of a type, stored in the world rather than on an entity. Use resources for data there is exactly one of: the score, the game's settings, a level timer, a lookup table. The engine uses them too: Time, ButtonInput<KeyCode>, Assets<Mesh> and AssetServer are all resources.

Define and add a resource#

Rust
use neo::prelude::*;

#[derive(Resource, Default)]
struct Score(u32);

#[derive(Resource)]
struct Difficulty {
    enemy_speed: f32,
}

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .init_resource::<Score>()                                // from Default
        .insert_resource(Difficulty { enemy_speed: 3.0 })        // a value you build
        .add_systems(Update, (add_points, show_score))
        .run();
}
MethodWhat it does
app.init_resource::<T>()Adds T built with Default (or FromWorld). Does nothing if it already exists.
app.insert_resource(value)Adds value, replacing any existing T.
commands.insert_resource(value), commands.init_resource::<T>()The same from a system, applied when commands run.
commands.remove_resource::<T>()Removes it.

There is at most one resource of each type. To keep two values of the same shape, wrap them in two types (struct MusicVolume(f32); and struct EffectsVolume(f32);).

Use a resource in a system#

Rust
fn add_points(mut score: ResMut<Score>) {
    score.0 += 1;
}

fn show_score(score: Res<Score>) {
    if score.is_changed() {
        info!("score: {}", score.0);
    }
}
ParameterAccessIf the resource doesn't exist
Res<T>ReadThe system fails validation and the error handler runs (by default a panic).
ResMut<T>Read and writeThe same.
Option<Res<T>>, Option<ResMut<T>>Read or write, if presentYou get None.
If<Res<T>>ReadThe system is skipped quietly.

Two systems that both take ResMut<Score> never run at the same time. Systems that only read it can.

Res and ResMut track changes like components do: is_changed(), is_added() and set_if_neq. See Change detection.

Build a resource from the world#

Implement FromWorld when a resource needs other resources to be built, for example to load assets once:

Rust
#[derive(Resource)]
struct HitSound(Handle<AudioSource>);

impl FromWorld for HitSound {
    fn from_world(world: &mut World) -> Self {
        let assets = world.resource::<AssetServer>();
        HitSound(assets.load("sounds/hit.ogg"))
    }
}

app.init_resource::<HitSound>();

Every type that implements Default gets FromWorld for free.

Resources or components?#

Use a resource whenUse a component when
There is one of it for the whole game.There can be one per entity.
Many systems need it, without a query.You want to query, filter or iterate it.
It belongs to no object in the world.It describes an object in the world.

A "the player" value is usually better as a Player marker component plus a Single query than a resource holding the player's data.

Access from the world#

Exclusive systems, hooks and tests reach resources through the World:

MethodReturns
world.resource::<T>(), world.resource_mut::<T>()The resource; panics if missing.
world.get_resource::<T>(), world.get_resource_mut::<T>()An Option.
world.contains_resource::<T>()Whether it exists.
world.resource_scope(f)Takes T out of the world and calls f with the world and Mut<T>, so you can use both.

Non-send resources#

Some values can't move between threads, such as handles from certain platform libraries. Add them with app.insert_non_send(value) and read them with NonSend<T> and NonSendMut<T>. Systems that use them run on the main thread. Most game code never needs this.

Next steps#