Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BRP resource methods #17423

Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Conversation

mweatherley
Copy link
Contributor

@mweatherley mweatherley commented Jan 18, 2025

Objective

So far, built-in BRP methods allow users to interact with entities' components, but global resources have remained beyond its reach. The goal of this PR is to take the first steps in rectifying this shortfall.

Solution

Added five new default methods to BRP:

  • bevy/get_resource: Extracts the value of a given resource from the world.
  • bevy/insert_resource: Serializes an input value to a given resource type and inserts it into the world.
  • bevy/remove_resource: Removes the given resource from the world.
  • bevy/mutate_resource: Replaces the value of a field in a given resource with the result of serializing a given input value.
  • bevy/list_resources: Lists all resources in the type registry with an available ReflectResource.

Testing

Added a test resource to the server example scene that you can use to mess around with the new BRP methods.

Showcase

Resources can now be retrieved and manipulated remotely using a handful of new BRP methods. For example, a resource that looks like this:

#[derive(Resource, Reflect, Serialize, Deserialize)]
#[reflect(Resource, Serialize, Deserialize)]
pub struct PlayerSpawnSettings {
  pub location: Vec2,
  pub lives: u8,
}

can be manipulated remotely as follows.

Retrieving the value of the resource:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bevy/get_resource",
  "params": {
    "resource": "path::to::my::module::PlayerSpawnSettings"
  }
}

Inserting a resource value into the world:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "bevy/insert_resource",
  "params": {
    "resource": "path::to::my::module::PlayerSpawnSettings",
    "value": {
      "location": [
        2.5, 
        2.5
      ],
      "lives": 25
    }
  }
}

Removing the resource from the world:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "bevy/remove_resource",
  "params": {
    "resource": "path::to::my::module::PlayerSpawnSettings"
  }
}

Mutating a field of the resource specified by a path:

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "bevy/mutate_resource",
  "params": {
    "resource": "path::to::my::module::PlayerSpawnSettings",
    "path": ".location.x",
    "value": -3.0
  }
}

Listing all manipulable resources in the type registry:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "bevy/list_resources"
}

@alice-i-cecile alice-i-cecile added C-Usability A targeted quality-of-life change that makes Bevy easier to use A-Reflection Runtime information about types X-Uncontroversial This work is generally agreed upon D-Straightforward Simple bug fixes and API improvements, docs, test and examples S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Jan 19, 2025
@alice-i-cecile alice-i-cecile added this to the 0.16 milestone Jan 19, 2025
@alice-i-cecile alice-i-cecile added the M-Needs-Release-Note Work that should be called out in the blog due to impact label Jan 19, 2025
@mweatherley mweatherley marked this pull request as ready for review January 19, 2025 23:44
@mweatherley mweatherley changed the title BRP Resource methods BRP resource methods Jan 19, 2025
@mweatherley mweatherley added S-Needs-Review Needs reviewer attention (from anyone!) to move forward and removed S-Waiting-on-Author The author needs to make changes or address concerns before this can be merged labels Jan 19, 2025
@purplg
Copy link
Contributor

purplg commented Jan 20, 2025

This looks good to me. Excited to see these new methods implemented.

Do we want to consider renaming the methods to be a little more hierarchical in the future or maybe some other scheme? For example:

  • bevy/mutate_component -> bevy/component/mutate
  • bevy/list_resources -> bevy/resource/list
  • bevy/insert_resource -> bevy/resource/insert
  • bevy/remove_resource -> bevy/resource/remove
  • bevy/mutate_resource -> bevy/resource/mutate

I feel like they may get a little unwieldy over time as more and more methods are added.

@mweatherley
Copy link
Contributor Author

Do we want to consider renaming the methods to be a little more hierarchical in the future or maybe some other scheme?

This is a very good idea. I'll change them when I have time :)

(I guess there's also the question of which other methods, if any, should get moved to the bevy/component/ namespace.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-Reflection Runtime information about types C-Usability A targeted quality-of-life change that makes Bevy easier to use D-Straightforward Simple bug fixes and API improvements, docs, test and examples M-Needs-Release-Note Work that should be called out in the blog due to impact S-Needs-Review Needs reviewer attention (from anyone!) to move forward X-Uncontroversial This work is generally agreed upon
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants