change return type of World::resource_ref to Ref

[atornity]

Objective

Closes #11825

Solution

Change return type of get_resource_ref and resource_ref from Res to Ref and implement From Res<T> for Ref<T>.

Migration guide

Previously World::get_resource_ref::<T> and World::resource_ref::<T> would return a Res<T> which was inconsistent with the rest of the World API (notably resource_scope). This has been fixed and the methods now return Ref<T>.

This means it is no longer possible to get Res<T> from World. If you were relying on this, you should try using Ref<T> instead since it has the same functionality.

Before

let my_resource: Res<MyResource> = world.resource_ref();
function_taking_resource(my_resource);

fn function_taking_resource(resource: Res<MyResource>) { /* ... */ }

After

let my_resource: Ref<MyResource> = world.resource_ref();
function_taking_resource(my_resource);

fn function_taking_resource(resource: Ref<MyResource>) { /* ... */ }

[alice-i-cecile]

We should only allow conversions to Ref from Res, not the other way around. Ditto for ResMut and Mut. Otherwise, it's possible to get a Ref or Mut from a Query and then treat it as a resource, which is very confusing.

[atornity]

We should only allow conversions to Ref from Res, not the other way around. Ditto for ResMut and Mut. Otherwise, it's possible to get a Ref or Mut from a Query and then treat it as a resource, which is very confusing.

You would only be able to convert Ref to Res if the inner value is a resource. Although I would like to replace From<Ref> to a new constructor from_ref.

I'm okay with removing it altogether though, but I do remember needing to get a Res from a world (this was my motivation for adding get_resource_ref) forever ago, and if there is no conversion then it will no longer be possible once get_resource_ref returns a Ref.

Anyways, I don't see a problem with potentially getting Res from a Ref in a query since the component need to also be a resource for that to be possible, and you cant really so anything weird/funky with it anyways.

What do you think? (Sorry for the ramble, I'm on my phone)

[atornity]

Alternatively, I could add a into_raw or similar to get the value and ticks from a Ref which can then be used to construct a Res with the new method

Nvm, Res doesn't have a new method

[alice-i-cecile]

You would only be able to convert Ref to Res if the inner value is a resource

Ah, I see: the trait bound on the From impl will enforce that. Hmm. Okay, I don't hate exposing this then.

[atornity]

Ah, I see: the trait bound on the From impl will enforce that. Hmm. Okay, I don't hate exposing this then.

Great, thoughts on From impl vs a new from_ref constructor?

A new constructor would mean you can't do let my_res = my_ref.into(), but you can still do let my_res = Res::from_ref(my_ref)

[alice-i-cecile]

No strong feelings. IMO let's stick with the From impls for consistency.

[maniwani]

This seems like the opposite of what was requested in the linked issue?

The only reason that Res<T> and ResMut<T> exist is that system params need to use the type to distinguish resources from other data.

This is true¹. Functions that aren't systems should only be taking or providing Ref<T> and Mut<T> as parameters, not Res<T> and ResMut<T>.

I don't think we should encourage using them interchangeably even if Res<T> and ResMut<T> transparently wrap Ref<T> and Mut<T>. I think it should be one-way conversions from Res<T> to Ref<T> and from ResMut<T> to Mut<T>.

Footnotes

1. Technically, they exist to distinguish between send and non-send resources, but same principle, param types control system fetch/execution. ↩

[atornity]

I don't think we should encourage using them interchangeably even if Res<T> and ResMut<T> transparently wrap Ref<T> and Mut<T>. I think it should be one-way conversions from Res<T> to Ref<T> and from ResMut<T> to Mut<T>.

Yeah, I once needed to get a Res from a World and I wanted to make sure that's still possible once I change the resource_ref to return a Ref. But I'm realizing that my use case was way to niche and I abandoned that project forever ago anyways, so I don't need it anymore. Once I have time, I'll fix up the pr to remove some of the conversions as well as change the return type of the resource_ref methods.

[atornity]

@alice-i-cecile are you sure this is controversial now? I removed the conversion from Ref/Mut -> Res/ResMut which is the only part that got pushback afaik.

[pablo-lua]

No reason why not expose this method, can reduce confusion over the types Res and Ref.

[github-actions]

It looks like your PR is a breaking change, but you didn't provide a migration guide.

Could you add some context on what users should update when this change get released in a new version of Bevy?
It will be used to help writing the migration guide for the version. Putting it after a ## Migration Guide will help it get automatically picked up by our tooling.

[ethereumdegen]

This broke my code and there is nothing in the migration guide... what do i do. now im blocked on my project and nobody can help me

#16831