From 33afd38ee11a05379c2a483201f3692b92366b9c Mon Sep 17 00:00:00 2001
From: Jer <alphastrata@gmail.com>
Date: Tue, 31 Dec 2024 11:29:27 +1100
Subject: [PATCH] show these 'fully qualified paths' for bevy_remote's rpc
 (#16944)

# Objective

It is not obvious that one would know these:
```json
{
  "id": 1,
  "jsonrpc": "2.0",
  "result": [
    "bevy_animation::AnimationPlayer",
    "bevy_animation::AnimationTarget",
    "bevy_animation::graph::AnimationGraphHandle",
    "bevy_animation::transition::AnimationTransitions",
    "bevy_audio::audio::PlaybackSettings",
    "bevy_audio::audio::SpatialListener",
    "bevy_core_pipeline::bloom::settings::Bloom",
    "bevy_core_pipeline::contrast_adaptive_sharpening::ContrastAdaptiveSharpening",
   **... snipping for brevity ...**
    "bevy_ui::ui_node::Node",
    "bevy_ui::ui_node::Outline",
    "bevy_ui::ui_node::ScrollPosition",
    "bevy_ui::ui_node::TargetCamera",
    "bevy_ui::ui_node::UiAntiAlias",
    "bevy_ui::ui_node::ZIndex",
    "bevy_ui::widget::button::Button",
    "bevy_window::monitor::Monitor",
    "bevy_window::window::PrimaryWindow",
    "bevy_window::window::Window",
    "bevy_winit::cursor::CursorIcon",
    "server::Cube"
  ]
}
```
Especially if you for example, are reading the GH examples because:

![image](https://github.com/user-attachments/assets/46c9c983-4bf9-4e70-9d6e-8de936505fbb)
If you for example expand these things, due to the number of places bevy
re-exports things you'll find it difficult to find the true path of
something.
i.e you'd probably be forgiven for writing a query (using the
`client.rs` example):
```sh
$ cargo run --example client --  bevy_pbr::mesh_material::MeshMaterial3d | jq
{
  "error": {
    "code": -23402,
    "message": "Unknown component type: `bevy_pbr::mesh_material::MeshMaterial3d`"
  },
  "id": 1,
  "jsonrpc": "2.0"
}
```
which is where
https://github.com/bevyengine/bevy/blob/8d9a00f5483b2ba28f40081759bd3d6f8b8a686d/crates/bevy_pbr/src/mesh_material.rs#L41
would lead you to believe it is...

I've worked with bevy a lot, so it's no issue for me, but for others...
?

## Solution

- Add some more docs, including a sample request (`json` and `rust`)

## Testing

N/A

---

## Showcase
N/A

---------

Co-authored-by: Benjamin Brienen <benjamin.brienen@outlook.com>
---
 crates/bevy_remote/src/lib.rs | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

diff --git a/crates/bevy_remote/src/lib.rs b/crates/bevy_remote/src/lib.rs
index e1ff833053..81dd2e0185 100644
--- a/crates/bevy_remote/src/lib.rs
+++ b/crates/bevy_remote/src/lib.rs
@@ -133,7 +133,8 @@
 //!
 //! `params`:
 //! - `data`:
-//!   - `components` (optional): An array of [fully-qualified type names] of components to fetch.
+//!   - `components` (optional): An array of [fully-qualified type names] of components to fetch,
+//!     see _below_ example for a query to list all the type names in **your** project.
 //!   - `option` (optional): An array of fully-qualified type names of components to fetch optionally.
 //!   - `has` (optional): An array of fully-qualified type names of components whose presence will be
 //!      reported as boolean values.
@@ -142,8 +143,8 @@
 //!     on entities in order for them to be included in results.
 //!   - `without` (optional): An array of fully-qualified type names of components that must *not* be
 //!     present on entities in order for them to be included in results.
-//! - `strict` (optional): A flag to enable strict mode which will fail if any one of the
-//!   components is not present or can not be reflected. Defaults to false.
+//!   - `strict` (optional): A flag to enable strict mode which will fail if any one of the
+//!     components is not present or can not be reflected. Defaults to false.
 //!
 //! `result`: An array, each of which is an object containing:
 //! - `entity`: The ID of a query-matching entity.
@@ -152,6 +153,8 @@
 //! - `has`: A map associating each type name from `has` to a boolean value indicating whether or not the
 //!   entity has that component. If `has` was empty or omitted, this key will be omitted in the response.
 //!
+//!
+//!
 //! ### bevy/spawn
 //!
 //! Create a new entity with the provided components and return the resulting entity ID.
@@ -567,6 +570,26 @@ pub struct RemoteWatchingRequests(Vec<(BrpMessage, RemoteWatchingMethodSystemId)
 ///     }
 /// }
 /// ```
+/// Or, to list all the fully-qualified type paths in **your** project, pass Null to the
+/// `params`.
+/// ```json
+/// {
+///    "jsonrpc": "2.0",
+///    "method": "bevy/list",
+///    "id": 0,
+///    "params": null
+///}
+///```
+///
+/// In Rust:
+/// ```ignore
+///    let req = BrpRequest {
+///         jsonrpc: "2.0".to_string(),
+///         method: BRP_LIST_METHOD.to_string(), // All the methods have consts
+///         id: Some(ureq::json!(0)),
+///         params: None,
+///     };
+/// ```
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct BrpRequest {
     /// This field is mandatory and must be set to `"2.0"` for the request to be accepted.