feat(tools/bevy_blueprints): bevy plugin + blender addon for componen…

…ts UI to more easily create components (#70) * adds a new crate: ```bevy_registry_export``` to be able to create a json import of the registered component/type definitions * adds a new Blender addon: ```bevy_components``` that takes that json data to generate custom UIs for components , to be to add & edit components easily in Blender * also adds component metadata per object for more advanced features * etc * updates to bevy_gltf_components & bevy_gltf_blueprints to add legacy_mode to support the "old"/current style component definitions * same with gltf_auto_export Blender add_on * closes #60
kaosat-dev · Feb 5, 2024 · cfbda24 · cfbda24
1 parent 5c8f41b
commit cfbda24
Show file tree

Hide file tree

Showing 117 changed files with 19,916 additions and 178 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -3,6 +3,7 @@ members = [
     "crates/bevy_gltf_components",
     "crates/bevy_gltf_blueprints",
     "crates/bevy_gltf_save_load",
+    "crates/bevy_registry_export",
     "examples/bevy_gltf_components/basic/",
     "examples/bevy_gltf_components/basic_wasm/",
     "examples/bevy_gltf_blueprints/basic/",
@@ -15,6 +16,7 @@ members = [
     "examples/bevy_gltf_blueprints/multiple_levels_multiple_blendfiles",
     "examples/bevy_gltf_blueprints/materials/",
     "examples/bevy_gltf_save_load/basic/",
+    "examples/bevy_registry_export/basic"
 
 ]
 resolver = "2"

diff --git a/README-workflow-classic.md b/README-workflow-classic.md
@@ -0,0 +1,73 @@
+# Workflow: classic
+
+The workflow goes as follows (once you got your Bevy code setup)
+
+- create & register all your components you want to be able to set from the Blender side (this is basic Bevy, no specific work needed)
+
+![component registration](./docs/component_registration.png)
+
+## Component creation
+- Create an object / collection (for reuse) in Blender
+- Go to object properties => add a property, and add your component data
+    - unit structs, enums, and more complex strucs / components are all supported, (if the fields are basic data types at least,
+    have not tried more complex ones yet, but should also work)
+        - for structs with no params (unit structs): use a **STRING** property & an empty value 
+        - for structs with params: use a RON representation of your fields (see below) 
+        - for tupple strucs you can use any of the built in Blender custom property types: Strings, Booleans, floats, Vectors, etc
+
+        ![unit struct components in Blender](./docs/components_blender.png)
+
+        In rust:
+
+        ![unit struct components in Bevy](./docs/demo_simple_components.png)
+
+        (the Rust struct for these components for reference is [here](./examples/basic/game.rs#34) )
+
+
+        ![complex components in Blender](./docs/components_blender_parameters.png)
+
+        In rust:
+
+        ![complex components in Blender](./docs/camera_tracking_component.png)
+
+        (the Rust struct for this component for reference is [here](./examples/basic/core/camera/camera_tracking.rs#21) )
+
+        There is an other examples of using various Component types: Enums, Tupple structs,  strucs with fields etc [here](./examples/basic/test_components.rs),
+        even colors, Vecs (arrays), Vec2, Vec3 etc are all supported
+
+        ![complex components in Blender](./docs/components_blender_parameters2.png)
+
+- for collections & their instances: 
+    * I usually create a library scene with nested collections
+        * the leaf collections are the assets you use in your level
+        * add an empty called xxxx_components
+        * add the components as explained in the previous part
+
+        ![blender collection asset](./docs/blender_collections.png)
+
+    * In the Level/world itself, just create an instance of the collection (standard Blender, ie Shift+A -> collection instance -> pick the collection)
+
+## Exporting to gltf 
+
+- export your level as a glb/gltf file :
+    - using Blender's default gltf exporter
+        !!**IMPORTANT** you need to check the following:
+        - custom properties
+        - cameras & lights if you want a complete level (as in this example)
+        ![gltf_export](./docs/gltf_export.png)
+    - or much better, using [gltf_auto_export](./tools/gltf_auto_export/)
+
+## Now use your gltf files in Bevy
+
+- load it in Bevy (see the various examples for this)
+- you should see the components attached to your entities in Bevy
+
+![components in bevy](./docs/components_bevy.png)
+![components in bevy](./docs/components_bevy2.png)
+![components in bevy](./docs/components_bevy3.png)
+
+
+> note: you get a warning if there are any unregistered components in your gltf file (they get ignored)
+you will get a warning **per entity**
+
+![missing components warnings](./docs/component_warnings.png)
diff --git a/README-workflow-ui.md b/README-workflow-ui.md
@@ -0,0 +1,40 @@
+# Workflow: UI
+
+The workflow goes as follows (once you got your Bevy code setup)
+
+## Bevy side
+- create & register all your components you want to be able to set from the Blender side (this is basic Bevy, no specific work needed)
+- follow the instructions in the [bevy_registry_export](./crates/bevy_registry_export/) to generate a registry export
+
+## Component creation
+
+Setup the Blender [bevy_components](./tools/bevy_components/README.md) add-on
+to add & edit your components visually & reliably
+
+![bevy_components](./docs/bevy_components.png)
+
+
+## Exporting to gltf 
+
+- export your level as a glb/gltf file :
+    - using Blender's default gltf exporter
+        !!**IMPORTANT** you need to check the following:
+        - custom properties
+        - cameras & lights if you want a complete level (as in this example)
+        ![gltf_export](./docs/gltf_export.png)
+    - or much better, using [gltf_auto_export](./tools/gltf_auto_export/)
+
+## Now use your gltf files in Bevy
+
+- load it in Bevy (see the various examples for this)
+- you should see the components attached to your entities in Bevy
+
+![components in bevy](./docs/components_bevy.png)
+![components in bevy](./docs/components_bevy2.png)
+![components in bevy](./docs/components_bevy3.png)
+
+
+> note: you get a warning if there are any unregistered components in your gltf file (they get ignored)
+you will get a warning **per entity**
+
+![missing components warnings](./docs/component_warnings.png)
diff --git a/README.md b/README.md
@@ -18,7 +18,8 @@ It also allows you to setup 'blueprints' in Blender by using collections (the re
 
 * Useful if you want to use Blender (or any editor allowing to export gltf with configurable gltf_extras) as your Editor
 * define Bevy components as custom properties in Blender (some visually , some using RON, though an older JSON version is also available)
-* no plugin or extra tools needed in Blender (but I provide a [little Blender plugin](./tools/gltf_auto_export/README.md) to auto-export to gltf on save (and more !) if you want !)
+* no plugin or extra tools needed in Blender (but I provide a [little Blender add-on](./tools/gltf_auto_export/README.md) to auto-export to gltf on save (and more !) if you want !)
+* now also with a nice UI tool to add & edit Bevy components in [Blender](./tools/bevy_components/README.md)
 * define components in Blender Collections & override any of them in your collection instances if you want
 * ability to automatically turn your Blender collections into [gltf Blueprints](./crates/bevy_gltf_blueprints/README.md) for reuse
 * minimal setup & code,  you can have something basic running fast
@@ -29,18 +30,23 @@ It also allows you to setup 'blueprints' in Blender by using collections (the re
 ## Crates
 
 - [bevy_gltf_components](./crates/bevy_gltf_components/) This crate allows you to define components direclty inside gltf files and instanciate/inject the components on the Bevy side.
-There is a [video tutorial/explanation](https://youtu.be/-lcScjQCA3c) if you want, or you can read the crate docs.
-The examples for the crate are [here](./examples/bevy_gltf_components/)
+
+    There is a [video tutorial/explanation](https://youtu.be/-lcScjQCA3c) if you want, or you can read the crate docs.
+    The examples for the crate are [here](./examples/bevy_gltf_components/)
 
 - [bevy_gltf_blueprints](./crates/bevy_gltf_blueprints/) This crate adds the ability to define Blueprints/Prefabs for Bevy inside gltf files and spawn them in Bevy. With the ability to override and add components when spawning, efficient "level" loading etc
-There is a [video tutorial/explanation](https://youtu.be/CgyNtwgYwdM) for this one too, or you can read the crate docs
-The examples for the crate are [here](./examples/bevy_gltf_blueprints/)
-> Note: this is the recomended crate to use and uses ```bevy_gltf_components``` under the hood
+
+    There is a [video tutorial/explanation](https://youtu.be/CgyNtwgYwdM) for this one too, or you can read the crate docs
+    The examples for the crate are [here](./examples/bevy_gltf_blueprints/)
+    > Note: this is the recomended crate to use and uses ```bevy_gltf_components``` under the hood
 
 - [bevy_gltf_save_load](./crates/bevy_gltf_save_load/) This crate adds the ability to save & load your game state in a relatively simple way, by leveraging the blueprint functionality of 
 bevy_gltf_blueprints to only save a minimal subset of dynamic data, seperating dynamic & static parts of levels etc.
 The examples for the crate are [here](./examples/bevy_gltf_save_load/)
-> Note: this uses ```bevy_gltf_blueprints``` under the hood
+    > Note: this uses ```bevy_gltf_blueprints``` under the hood
+
+- [bevy_registry_export](./crates/bevy_registry_export/) This crate adds the ability to export your project's Bevy registry to json, in order to be able to generate custom component UIs on the Blender side in the Blender [bevy_components](./tools/bevy_components/README.md) add-on
+
 
 ## Tools
 
@@ -51,6 +57,13 @@ The examples for the crate are [here](./examples/bevy_gltf_save_load/)
 
 Please read the [README]((./tools/gltf_auto_export/README.md)) of the add-on for installation & use instructions
 
+### Blender: bevy_components
+
+- an add-on for Blender to allow easilly adding & editing Bevy components , using automatically generated UIs for each component
+
+Please read the [README]((./tools/bevy_components/README.md)) of the add-on for installation & use instructions
+
+
 
 ## Examples
 
@@ -62,6 +75,12 @@ you can find all examples, by crate as seperate crates for clearer dependencies
 - [bevy_gltf_blueprints](./examples/bevy_gltf_blueprints/) 
     * [basic](./examples/bevy_gltf_blueprints/basic/) more advanced example : use of ```bevy_gltf_blueprints``` to spawn a level and then populate it with entities coming from different gltf files, live (at runtime) spawning of entities etc
     * [animation](./examples/bevy_gltf_blueprints/animation/) how to use and trigger animations from gltf files (a feature of ```bevy_gltf_blueprints```)
+    * & lots more
+
+- [bevy_gltf_save_load](./examples/bevy_gltf_save_load/) 
+
+- [bevy_registry_export](./examples/bevy_registry_export/) 
+
 
 ## Workflow
 
@@ -70,74 +89,12 @@ The workflow goes as follows (once you got your Bevy code setup)
 - create & register all your components you want to be able to set from the Blender side (this is basic Bevy, no specific work needed)
 
 ![component registration](./docs/component_registration.png)
-- Create an object / collection (for reuse) in Blender
-- Go to object properties => add a property, and add your component data
-    - unit structs, enums, and more complex strucs / components are all supported, (if the fields are basic data types at least,
-    have not tried more complex ones yet, but should also work)
-        - for structs with no params (unit structs): use a **STRING** property & an empty value 
-        - for structs with params: use a RON representation of your fields (see below) 
-        - for tupple strucs you can use any of the built in Blender custom property types: Strings, Booleans, floats, Vectors, etc
-
-        ![unit struct components in Blender](./docs/components_blender.png)
-
-        In rust:
-
-        ![unit struct components in Bevy](./docs/demo_simple_components.png)
-
-        (the Rust struct for these components for reference is [here](./examples/basic/game.rs#34) )
-
-
-        ![complex components in Blender](./docs/components_blender_parameters.png)
-
-        In rust:
-
-        ![complex components in Blender](./docs/camera_tracking_component.png)
-
-        (the Rust struct for this component for reference is [here](./examples/basic/core/camera/camera_tracking.rs#21) )
-
-        There is an other examples of using various Component types: Enums, Tupple structs,  strucs with fields etc [here](./examples/basic/test_components.rs),
-        even colors, Vecs (arrays), Vec2, Vec3 etc are all supported
-
-        ![complex components in Blender](./docs/components_blender_parameters2.png)
-
-- for collections & their instances: 
-    * I usually create a library scene with nested collections
-        * the leaf collections are the assets you use in your level
-        * add an empty called xxxx_components
-        * add the components as explained in the previous part
-
-        ![blender collection asset](./docs/blender_collections.png)
-
-    * In the Level/world itself, just create an instance of the collection (standard Blender, ie Shift+A -> collection instance -> pick the collection)
-
-
-- export your level as a glb/gltf file :
-    - using Blender's default gltf exporter
-        !!**IMPORTANT** you need to check the following:
-        - custom properties
-        - cameras & lights if you want a complete level (as in this example)
-        ![gltf_export](./docs/gltf_export.png)
-    - or much better, using [gltf_auto_export](./tools/gltf_auto_export/)
-
-
-
-- load it in Bevy (see the demo main file for this)
-- you should see the components attached to your entities in Bevy
-
-![components in bevy](./docs/components_bevy.png)
-![components in bevy](./docs/components_bevy2.png)
-![components in bevy](./docs/components_bevy3.png)
-
-
-> note: you get a warning if there are any unregistered components in your gltf file (they get ignored)
-you will get a warning **per entity**
-
-![missing components warnings](./docs/component_warnings.png)
-
 
+- then you have two options
+    - add your components to objects in Blender **manually** as **custom properties**  : see [here](./README-workflow-classic.md) for more details
+    - add your components to objects in Blender **with a nice UI** see [here](./README-workflow-ui.md) for more details 
 
 ## Limitations / issues
-- some components have to be defined in ```text``` in Blender, might try using the AppTypeRegistry and some Python code on the Blender side for a nicer UI (although this loses the "fast & easy, no tooling" approach)
 - Some of `bevy_rapier`/physics code / ways to define colliders could perhaps be done better/visually within Blender (currently it also goes via RON)
 
 ## Future work
@@ -153,6 +110,9 @@ Thanks to all the contributors helping out with this project ! Big kudos to you,
 
 - [GitGhillie](https://github.com/GitGhillie)
 - [Azorlogh](https://github.com/Azorlogh)
+- [BSDGuyShawn](https://github.com/BSDGuyShawn)
+- [yukkop](https://github.com/yukkop)
+- [killercup](https://github.com/killercup)
 
 ## License
 

diff --git a/crates/bevy_gltf_blueprints/Cargo.toml b/crates/bevy_gltf_blueprints/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bevy_gltf_blueprints"
-version = "0.6.0"
+version = "0.7.0"
 authors = ["Mark 'kaosat-dev' Moissette"]
 description = "Adds the ability to define Blueprints/Prefabs for [Bevy](https://bevyengine.org/) inside gltf files and spawn them in Bevy."
 homepage = "https://github.com/kaosat-dev/Blender_bevy_components_workflow"
@@ -17,5 +17,6 @@ workspace = true
 bevy = { version = "0.12", default-features = false, features = ["bevy_asset", "bevy_scene", "bevy_gltf", "bevy_animation", "animation"] }
 
 [dependencies]
-bevy_gltf_components = "0.2"
+bevy_gltf_components = "0.3"
+#bevy_gltf_components = { path = "../bevy_gltf_components" }
 bevy = { version = "0.12", default-features = false, features = ["bevy_asset", "bevy_scene", "bevy_gltf", "bevy_animation", "animation"] }
diff --git a/crates/bevy_gltf_blueprints/README.md b/crates/bevy_gltf_blueprints/README.md
@@ -26,7 +26,7 @@ Here's a minimal usage example:
 # Cargo.toml
 [dependencies]
 bevy="0.12"
-bevy_gltf_blueprints = { version = "0.6"} 
+bevy_gltf_blueprints = { version = "0.7"} 
 
 ```
 
@@ -64,7 +64,7 @@ fn spawn_blueprint(
 Add the following to your `[dependencies]` section in `Cargo.toml`:
 
 ```toml
-bevy_gltf_blueprints = "0.6"
+bevy_gltf_blueprints = "0.7"
 ```
 
 Or use `cargo add`:
@@ -307,6 +307,25 @@ see https://github.com/kaosat-dev/Blender_bevy_components_workflow/tree/main/exa
 
 Generating optimised blueprints and material libraries can be automated using the latests version of the [Blender plugin](https://github.com/kaosat-dev/Blender_bevy_components_workflow/tree/main/tools/gltf_auto_export)
 
+
+## Legacy mode
+
+Starting in version 0.7 there is a new parameter ```legacy_mode``` for backwards compatibility
+
+To disable the legacy mode: (enabled by default)
+
+```rust no_run
+BlueprintsPlugin{legacy_mode: false}
+```
+
+
+You **need** to disable legacy mode if you want to use the [```bevy_components```](https://github.com/kaosat-dev/Blender_bevy_components_workflow/tree/tools_bevy_blueprints/tools/bevy_components) Blender addon + the [```bevy_registry_export crate```](https://crates.io/crates/bevy_registry_export) ! 
+As it create custom properties that are writen in real **ron** file format instead of a simplified version (the one in the legacy mode)
+
+
+> Note: the legacy mode support will be dropped in future versions, and the default behaviour will be NO legacy mode
+
+
 ## Examples
 
 https://github.com/kaosat-dev/Blender_bevy_components_workflow/tree/main/examples/bevy_gltf_blueprints/basic
@@ -333,7 +352,7 @@ The main branch is compatible with the latest Bevy release, while the branch `be
 Compatibility of `bevy_gltf_blueprints` versions:
 | `bevy_gltf_blueprints` | `bevy` |
 | :--                 | :--    |
-| `0.3 - 0.6`         | `0.12` |
+| `0.3 - 0.7`         | `0.12` |
 | `0.1 - 0.2`         | `0.11` |
 | branch `main`       | `0.12` |
 | branch `bevy_main`  | `main` |

diff --git a/crates/bevy_gltf_blueprints/src/lib.rs b/crates/bevy_gltf_blueprints/src/lib.rs
@@ -78,6 +78,8 @@ impl fmt::Display for GltfFormat {
 #[derive(Debug, Clone)]
 /// Plugin for gltf blueprints
 pub struct BlueprintsPlugin {
+    pub legacy_mode: bool, // flag that gets passed on to bevy_gltf_components
+
     pub format: GltfFormat,
     /// The base folder where library/blueprints assets are loaded from, relative to the executable.
     pub library_folder: PathBuf,
@@ -91,6 +93,7 @@ pub struct BlueprintsPlugin {
 impl Default for BlueprintsPlugin {
     fn default() -> Self {
         Self {
+            legacy_mode: true,
             format: GltfFormat::GLB,
             library_folder: PathBuf::from("models/library"),
             aabbs: false,
@@ -110,7 +113,9 @@ fn materials_library_enabled(blueprints_config: Res<BluePrintsConfig>) -> bool {
 
 impl Plugin for BlueprintsPlugin {
     fn build(&self, app: &mut App) {
-        app.add_plugins(ComponentsFromGltfPlugin)
+        app.add_plugins(ComponentsFromGltfPlugin{
+            legacy_mode: self.legacy_mode
+        })
             .register_type::<BlueprintName>()
             .register_type::<MaterialInfo>()
             .register_type::<SpawnHere>()

diff --git a/crates/bevy_gltf_components/Cargo.toml b/crates/bevy_gltf_components/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "bevy_gltf_components"
-version = "0.2.2"
+version = "0.3.0"
 authors = ["Mark 'kaosat-dev' Moissette"]
 description = "Allows you to define [Bevy](https://bevyengine.org/) components direclty inside gltf files and instanciate the components on the Bevy side."
 homepage = "https://github.com/kaosat-dev/Blender_bevy_components_workflow"