Resources v2

[alice-i-cecile]

Resources in Bevy are fantastically useful global singletons, but there are some strange warts in how they currently work. In the next few posts on this thread, I'm going to go over a few of the problems, and how I propose we fix them.

TL;DR:

1. Reduce the number of ways to initialize resources.
2. Make the syntax for working with resources mirror that of components.
3. Use generics to differentiate between variants of a resource.
4. Allow ordinary systems to access thread-local resources.
5. Give Local resources a name: "system-local resources".
6. Clean up FromResources for clarity.

Inconsistent, Confusing API for Initialization

Right now, there are many ways to set up a resource:

1. init_resource: Adds a new resource of the type set, with default values set via FromResources.
2. add_resource: Adds a new resource.
3. insert_resource: The same as 2, but via Commands rather than in the AppBuilder.
4. Implicitly, with Local: Automatically creates a new resource of the appropriate type if it doesn't exist, but that can only be seen by the calling system.
5. Indirectly, with [add_event] (https://docs.rs/bevy/0.4.0/bevy/app/struct.AppBuilder.html#method.add_event): Sets up the resource for you, and then adds a nice little system to handle cleanup for you.
6. Variants of 1-3 but for "thread-local" resources: These can't trivially be handled by the same method, due to the lack of send + sync on those resources.
7. Mutating resource directly in a "thread-local system":

All of these other than 4 overwrite existing values for the events.

Proposal: Condense Resource Initialization Options

One of the stated goals of Bevy is that there should be one, good way to accomplish each desired behavior. To that end, I recommend the following changes to the API:

• Renamed add_resource and insert_resource to set_resource: This makes it much clearer that these operations overwrite any existing values, and uses the same name for the same behavior.
• Remove or deemphasize the ability to add resources via commands: This is largely a foot-gun: the delayed effects of commands means that new users will encounter a strange delay. This might be worth keeping around to eventually support future functionality, but should be documented as such.
• Remove init_resource in favor of implicit auto-initialization: This reduces boilerplate, avoids accidentally overwriting values due to AppBuilder method ordering, and makes the behavior consistent with system-local resources. This is the most controversial proposal: it's fairly magic, and will need to be tested to ensure that appropriate solutions still exist for foreign types that don't impl Default.
• Condense "thread-local" variants: What it says on the tin. If we can weaken the trait bound on the public interface, then handle them distinctly internally, we can reduce the API surface by simply cutting these. I'm not convinced this is possible, but see below for more thoughts on these.

[alice-i-cecile]

Similar but Distinct Syntax and Behavior between Resources and Components

There are three facets to this:

1. Components don't need to be explicitly declared. See the arguments in the post above.
2. Resource parameters use a similar but distinct syntax.
3. ChangedRes and friends automatically skip systems if no changes have occured.

For 2, when working with a single component we have:

Query<&T>, Query<&mut T> and Query<&mut T, Changed<T>>

But for a resource, the equivalent looks like:

Res<R>, ResMut<R> and ChangedRes<R>

This proliferation of wrapper types is confusing, especially to beginners, and limits our possible directions to expand.

For 3. systems are automatically skipped by the scheduler if at least one of their ChangedRes (or similar) parameters has not changed during this frame. This behavior is very magical, occurs silently, and does not function the same when working with Changed components.

Proposal: Use a filtering syntax for Resources

Borrowing directly from the API for components, replace the existing syntax by adding a second optional type parameter:

Res<&T>, Res<&mut T> and Res<&mut T, Changed<T>>

Benefits:

1. Makes the API more consistent and reduces number of types.
2. By allowing the second type to be a tuple, allows us to combine filters if users / future Bevy wants to add more interesting / complex variants.
3. Allows us to pass resources by value, rather than reference when desired, such as you might do for small Copy resources like a Score.

Costs:

1. Refactoring might be a pain.
2. Repeated types in the second type parameter: unlike with component queries, you can't use the behavior of other types to filter.

Proposal: Always run ChangedRes systems

Benefits:

1. No more magical behavior, making the code easier to reason about. Optionally running systems should be handled explicitly, with a run criteria.
2. More consistent system scheduling. This should help us get towards being able to determine a fixed system order at the start of each stage in cases where that behavior is desired.
3. Consistency with how changed components work.
4. Can operate on the fact that things haven't changed.

Costs:

1. Users may have to write small loops at the start of their systems to break early if nothing has changed.

[alice-i-cecile]

I like replacing the ChangedRes behavior with run criteria for sure: it's much more explicit, and more clear.

On a related note, I'm not convinced that there's a lot of use for these "resource filters" if they don't control whether the system runs directly. You'll get the same thing back in your Res box, no matter their value.

@cart's proposal on Discord seems like it might be a better fit: just give each Res object some private fields, then use accessor methods like my_res.is_changed in your function body to handle it.

[alice-i-cecile]

Currently Or<> is supported for resources. Would that be supported with the new API?

Huh! I had no idea. This seems to be where it's defined, but I can't see where it applies to resources. How do you use it currently?

In any case, I would expect that supporting Or in resource filters like this to be a natural fit.

[DJMcNab]

I think it might be around here?

bevy/crates/bevy_ecs/src/system/system_param.rs

Line 319 in 6c07c80

impl<$($param: SystemParam),*> SystemParam for Or<($(Option<$param>,)*)> {

[fenduru]

Just want to throw in my vote (as a very new user that ran into some confusion here) for the first proposal, as the consistency with Query reduces the cognitive overhead.

There doesn't really seem to be a conceptual difference between Resources and Components other than the fact that a resource is only added once - it is almost like a Component on a special GlobalEntity (in fact, if resources weren't baked into the system I think it would be reasonable to implement resources this way in user-space).

[TheRawMeatball]

ChangedRes problem should be solved by #1313

[alice-i-cecile]

Unclear How to Extend Behavior of Resources when Variants are Needed

It's common to begin writing a game using a true singleton, but then find that you need to extend the behavior to include multiple copies. For example, you might begin with a single Score, then add multiplayer, start with a single Planet then add multiple worlds, or start with a single UnitStats then incorporate multiple copies.

With the current patterns, refactoring for this is painful. As I see it, the obvious options are:

1. Wrap all of these in a meta-resource that collects similar resources, then extract them. This creates unnecessarily restrictive locks on read-write access as well as forcing boilerplate code rewrites.
2. Use a thin wrapper around each variant. This is a huge amount of boilerplate, and requires nasty macros and insertion via commands if you need to create new variants at run time.
3. Create phantom entities, and then refactor your resource as a component that belongs to these entities. This can work well in some cases (such as when you have many properties that vary across a set in a two dimensional fashion), but requires a painful refactor and ends up forcing you to blur any line you'd drawn between resources and entities to get proper variant-like behavior.

Proposal: Resource Variants through Generics as Idiomatic Bevy

But there's a better way! As shown here, you can use generic type arguments on the resources that you define in order to allow the creation of resource variants differentiated by their type, which can be seamlessly called and created using Bevy.

This results in particularly elegant code (once initialization is set up), and becomes exceptionally powerful once const generics arrive, allowing you to do things like specifying Score<1> or Stats<"Goblin"> as your resource type for a system :)

To make this change, I think we want:

1. Better examples: this is a fairly advanced Rust idiom, and isn't obvious to game programmers coming from other languages.
2. Possible unification of Timer, Event, Handle and possibly other Bevy-internal resource types to use this idiom.

[BoxyUwU]

Small note that min_const_generics (the version of const generics that's being stabilized for 1.51) doesn't support strings so Stats<"Goblin"> is a bit further in the future :P

[alice-i-cecile]

Small note that min_const_generics (the version of const generics that's being stabilized for 1.51) doesn't support strings so Stats<"Goblin"> is a bit further in the future :P

Yep, sadly. One day we'll be able to support custom enum types (probably!), which will give us really fancy stuff like SupplyCap<Forces::Orc> :)

[alice-i-cecile]

"Thread-local resources" and "thread-local systems" are kind of a mess

As I understand it, the current "thread-local resources" cannot be sent safely across threads, because they lack Send + Sync. They can only be accessed in "thread-local systems", which get full, blocking access to both World and Resources.

On the face of it, that seems reasonable: you handle thread-local resources in thread-local systems and don't worry about multithreading them. There are a few problems though:

1. In standard terminology, "thread-local X" means that we can create multiple copies of X, one per thread. This is in direct parallel to how the existing system-local resources work, and may be very useful for things like accumulating events. As it stands, there's no API to stick thread-local resources on a particular thread.
2. As long as we schedule systems onto the same thread as contains the resource, we can access it in an ordinary system. This gives us huge parallelism, safety and clarity benefits, as you can use the much nicer query syntax rather than mucking about with the internals.
3. "Thread-local systems" as they currently stand have nothing to do with being isolated on a single thread. Instead, they should be something closer to "global systems" and heavily discouraged for most uses (especially now that we can run systems in sequence explicitly).

Proposal: allow regular systems to access thread-local resources

This will require some scheduler work, but should be perfectly feasible. As long as we stick the system that requires a thread-local resource on the same thread as the resource in question, everything works just fine, as the data itself never has to cross the thread boundary.

By default, we should stick all thread-local resources on the same thread to allow systems to access multiple of them at once.

Rename "thread-local systems" to "global systems"

Much better clarity, and avoids false connection to thread-local resources.

Proposal: Design an API to create and access a copy of a resource for each active thread

This has a few steps:

1. Allow users to specify which thread they want to spawn a thread-local resource on. This alone will be useful for when you want dedicated threads for things like audio or UI.
2. Create some sugar to read in all copies of a resource with a given resource variant (as discussed in the post above). This will also be helpful for other purposes.
3. Create a hook or some sugar to automatically initialize a copy of these resources when a new thread is created.

Down the road, I can see a lot of use for this in accumulating events (and commands!) across disparate systems in a nonblocking way, eventually aggregating them in a later system.

[Ratysz]

First and second proposals are pretty much implemented in #1144 ("collateral changes" section). Relevant parts:

• What Bevy calls "thread-local systems" is split into new "exclusive systems" and "thread-local systems": the former is what you call "global systems", i.e., has exclusive (mutable) access to entirety of resources and/or world, and the latter is any parallelizable (does not mutably access entirety of resources and/or world) system with a ThreadLocal resource argument.
• ThreadLocal resource argument fetches its resource from the "thread-local" storage of Resources, and makes any system that has it run on the main thread during the parallel portion of the stage. Thread-agnostic (does not have a thread-local argument) systems are allowed to run on other threads during that time.

(I have to note that any diffirentiation of this kind exists only in the executor itself - properties of systems are fully inferred from their arguments.)

I'm not attached to any of the terminology. In fact, I think anything "thread-local" should be named something like "non-send" instead (although that does make it sound like "nonsense", which is a win for low-key nihilistic humor, but might not be desireable), to differentiate it from resources that are thread-local in the way the term is used by the rest of the world.

The third proposal should be covered by expanding the non-send resources to work with more threads than just the main one (fulfilling point 1), and introducing true thread-local resources (fulfilling points 2 and 3). These two should not be intermingled.

[alice-i-cecile]

Yes please! I'm thrilled to hear this has been on your mind too.

[alice-i-cecile]

System-local resources lack a proper name in the code and documentation

This is a simple problem: Local creates resources that are local to a specific system. This is in contrast to what we were calling "thread-local" resources (or actual thread-local resources). This behavior and nomenclature is confusing to newcomers and readers of the code.

These are rare and strange enough that I think the clarity gained from calling the type SystemLocal is worth the extra typing.

[inodentry]

rare and strange enough

I'd like to question that. They are awesome with EventReaders, to let multiple systems handle the same events. Every system in my project that receives events has a Local<EventReader<T>>.

That said, I agree that it would be nice for it to be called SystemLocal. Makes it very clear what it is.

[TheRawMeatball]

Local<EventReader<T>> is no longer necessary! With what is (currently) the last merged PR, you can write a system like this:

fn system(events: EventReader<MyEvent>) {
    for event in events.iter() {
        println!("{:?}", event);
    }
}

[alice-i-cecile]

FromResources cleanup

1. By convention, From* traits in Rust take ownership of their function arguments. This isn't the case here, and so the trait should be renamed to something like InitWithResources or DefaultWithResources for clarity.
2. The trait as a whole seems overly powerful: it's not clear to me that we should be allowing full access to Resources here, instead of just relying on default and then having nice helper functions to set up an appropriate system like init_index does.

[ktmattson-alion]

I know this is ancient history, but sometimes understanding open source code depends on understanding its history.

I have been trying to understand the reason that both init_resource and insert_resource exist and when to use which. I see that since this discussion, add_resource has been removed (or renamed? which is even more confusing,) but the other two items remain.

Is the distinction between init_resource and insert_resource still that the latter operates via Commands? If so, this fact and its implications remain undocumented. If however they both operate in the same way -- and this is pure opinion -- I don't follow the need for init_resource; it seems unparsimonious.

FWIW, I would also have picked upsert_resource over insert_ or set_

[tim-blackbird]

Unlike insert_resource, init_resource does nothing if the resource already exists.

[ktmattson-alion]

Looking through the source it would seem that neither will use Commands. Is this correct?

In DBMS APIs, bevy's init_ would be an insert, while its insert_ would be an upsert. I'm still having a hard time understanding why you'd need a call that does nothing like init_resource does. That is, if you don't actually care to even know what the resource state was at the time of the init, what is the benefit over clobbering whatever might have been there?

In other words, if I use init_resource<MyResource>, all that I know post-call is that MyResource is either in its FromWorld state... or not. On balance, I'm not sure this is more clear than, e.g. insert_resource(MyResource::default())

[tim-blackbird]

Looking through the source it would seem that neither will use Commands. Is this correct?

Yes. This is unrelated to Commands.

In DBMS APIs, bevy's init_ would be an insert, while its insert_ would be an upsert.

From some quick googling this doesn't seem to be true for all DBMS.
upsert isn't idiomatic in rust (perhaps even programming in general?).

I'm still having a hard time understanding why you'd need a call that does nothing like init_resource does.

init_resource is used commonly in Bevy to avoid overwriting user configuration set before a plugin was added while ensuring the resource does exist by the time the app runs.
For example the ClearColor set in this example would be overwritten if insert_resource was used instead of init_resource in the relevant plugin.

[ktmattson-alion]

Fair on upsert, it's kind of a gross word anyway.

Thanks for the answers, although I think I'm still not quite getting it. It seems like the use case for init_resource is when you truly don't care what the state of a resource is, other than that it exists. I guess it would be inconvenient for chaining methods if it responded as to whether or not the resource was added, and can be trusted to actually be in its default state.