refactor(examples): restructure examples (#44)

* refactor(examples): moved examples into more logic folders & changed to allow for per example dependencies
* chore(): updated docs, added docs, updated deps , cargo files etc

.gitignore

@@ -1,2 +1,2 @@
-/target
 *.blend1
+target/

Cargo.toml

@@ -1,51 +1,10 @@
-[package]
-name = "bevy_gltf_flow"
-version = "0.3.0"
-edition = "2021"
-license = "MIT OR Apache-2.0"
-
 [workspace]
 members = [
     "crates/bevy_gltf_components",
     "crates/bevy_gltf_blueprints",
+    #"examples/*"
 ]
+resolver = "2"
 
-[dev-dependencies]
+[profile.dev]
-bevy="0.12"
+opt-level = 1 # Use slightly better optimization, so examples work
-bevy_asset_loader = { version = "0.18", features = ["standard_dynamic_assets" ]} 
-bevy_rapier3d = { version = "0.23.0", features = [ "serde-serialize", "debug-render-3d", "enhanced-determinism"] }
-bevy_editor_pls = { version = "0.6" }
-rand = "0.8.5"
-
-[dependencies]
-bevy = { version = "0.12", default-features = false, features = ["bevy_asset", "bevy_scene", "bevy_gltf"] }
-bevy_gltf_components = { path = "crates/bevy_gltf_components" }
-bevy_gltf_blueprints = { path = "crates/bevy_gltf_blueprints" }
-
-serde = "*"
-ron="*"
-
-[[example]]
-name = "basic"
-path = "examples/basic/main.rs"
-
-[[example]]
-name = "animation"
-path = "examples/animation/main.rs"
-
-[[example]]
-name = "advanced"
-path = "examples/advanced/main.rs"
-
-#### --------------------Dev/ debug-------------------------------
-# Enable high optimizations for dependencies (incl. Bevy), but not for our code:
-[profile.dev.package."*"]
-opt-level = 3
-
-[profile.dev.package.bevy]
-features = ["dynamic"]
-
-#### --------------------Production/ release-------------------------------
-[profile.release]
-strip = "debuginfo"
-lto = "thin"

README.md

@@ -29,11 +29,13 @@ 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/ basic example
+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.
-There is a [video tutorial/explanation](https://youtu.be/CgyNtwgYwdM) for this one too, or you can read the crate docs/ basic example
 
+- [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
 
 
 ## Tools
@@ -48,9 +50,14 @@ Please read the [README]((./tools/gltf_auto_export/README.md)) of the add-on for
 
 ## Examples
 
-- [basic](./examples/basic/) use of ```bevy_gltf_components``` only, to spawn entities with components defined inside gltf files
+you can find all examples, by crate as seperate crates for clearer dependencies in [here](./examples/)
-- [advanced](./examples/advanced/) 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/animation/) how to use and trigger animations from gltf files (a feature of ```bevy_gltf_blueprints```)
+- [bevy_gltf_components](./examples/bevy_gltf_components/) 
+    * [basic](./examples/bevy_gltf_components/basic/) use of ```bevy_gltf_components``` only, to spawn entities with components defined inside gltf files
+
+- [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```)
 
 ## Workflow
 
@@ -127,12 +134,11 @@ you will get a warning **per entity**
 
 ## 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 within Blender (currently it also goes via RON)
+- 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
 - I have a number of other tools/ code  helpers that I have not yet included here, because they need cleanup/ might make this example too complex
 
-
 ## Credits
 
 - somebody I cannot recall helped me originally with the gltf loading tracker in the Bevy Discord, so thanks ! And if it was you, please let me know so I can give credit where credit is due :)

assets/advanced/assets_game.assets.ron

@@ -1,6 +0,0 @@
-({
-    "world":File (path: "advanced/models/World.glb"),
-    "models": Folder (
-        path: "advanced/models/library",
-    ),
-})

assets/animation/assets_game.assets.ron

@@ -1,6 +0,0 @@
-({
-    "world":File (path: "animation/models/Level1.glb"),
-    "models": Folder (
-        path: "animation/models/library",
-    ),
-})

examples/README.md

@@ -0,0 +1,4 @@
+# Examples
+
+This folder contains numerous examples showing how to use both bevy_gltf_components and bevy_gltf_blueprints. 
+Each example is its own crate so its dependencies are specific & clear.

examples/basic/README.md

@@ -1,128 +0,0 @@
-
-# Workflow with blender / demo information
-
-This example, is actually closer to a boilerplate + tooling showcases how to use a minimalistic [Blender](https://www.blender.org/) (gltf) centric workflow for [Bevy](https://bevyengine.org/), ie defining entites & their components
-inside Blender using Blender's objects **custom properties**.
-Aka "Blender as editor for Bevy"
-
-It also allows you to setup 'blueprints' in Blender by using collections (the recomended way to go most of the time), or directly on single use objects .
-
-## Features
-
-* 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 (RON, though an older JSON version is also available)
-* no plugin or extra tools needed in Blender (but I provide a little Blender plugin to auto-export to gltf on save if you want !)
-* define components in Blender Collections & override any of them in your collection instances if you want
-* code to auto add additional required components in Bevy (if B is needed with A but B is not present, it adds it:  optional & configurable)
-* minimal setup & code,  you can have something basic running fast
-* opensource 
-
-There is a [video tutorial/explanation](https://youtu.be/-lcScjQCA3c) if you want, or you can skip to the text version ahead
-
-
-## Running this example
-
-```
-cargo run --example general  --features bevy/dynamic_linking
-```
-
-## Workflow
-
-The workflow goes as follows (once you got your Bevy code setup)
-
-### All core/helper modules
-
-see the [example](./examples/general/) for more information on how to set things up
-
-
-### Then...
-
-- 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 a mesh/ 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/general/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/general/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/general/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 :
-    !!**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)
-
-
-- 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)
-
-
-### Additional notes
-
-* You usually define either the Components directly or use ```Proxy components``` that get replaced in Bevy systems with the actual Components that you want (usually when for some reason, ie external crates with unregistered components etc) you cannot use the components directly.
-
-Included are the following modules / tools
- * [```process_gltf```](./src/process_gltfs.rs) the most important module: this is the one extracting ```component``` information from the gltf files
- * [```insert_dependant_component```](./examples/general/core/relationships/relationships_insert_dependant_components.rs)  a small utility to automatically inject 
-    components that are dependant on an other component
-    for example an Entity with a Player component should also always have a ShouldBeWithPlayer component
-    you get a warning if you use this though, as I consider this to be stop-gap solution (usually you should have either a bundle, or directly define all needed components)
- * [```camera```](./examples/general/core/camera/) an example post process/replace proxies plugin, for Camera that also adds CameraTracking functions (to enable a camera to follow an object, ie the player)
- * [```lighting```](./examples/general/core/lighting/) an other example post process/replace proxies plugin for lighting, that toggles shadows, lighting config, etc so that things look closer to the original Blender data
- * [```physics```](./examples/general/core/physics/) an other example post process/replace proxies plugin for physics, that add [Rapier](https://rapier.rs/docs/user_guides/bevy_plugin/getting_started_bevy) Colliders, Rigidbodies etc . Most of these do not need proxies these days, as the most Rapier components are in the Registry & can be used directly
-
-Feel free to use as you want, rip it appart, use any/all parts that you need !
-
-This tooling and workflow has enabled me to go from a blank Bevy + Blender setup to a working barebones level in very little time (30 minutes or so ?) !
-You can then add your own components & systems for your own gameplay very easilly
-
-## Information
-- the Bevy/ Rust code is [here](./examples/general/main.rs)
-- the Blender file is [here](./assets/models/level.blend)
-- I added [bevy_editor_pls](https://github.com/jakobhellermann/bevy_editor_pls) as a dependency for convenience so you can inspect your level/components

examples/bevy_gltf_blueprints/animation/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "bevy_gltf_blueprints_basic_example"
+version = "0.3.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+
+[workspace]
+
+[dependencies]
+bevy="0.12"
+bevy_gltf_blueprints = { path = "../../../crates/bevy_gltf_blueprints" }
+bevy_rapier3d = { version = "0.23.0", features = [ "serde-serialize", "debug-render-3d", "enhanced-determinism"] }
+bevy_asset_loader = { version = "0.18", features = ["standard_dynamic_assets" ]} 
+bevy_editor_pls = { version = "0.6" }
+rand = "0.8.5"
+
+#### --------------------Dev/ debug-------------------------------
+# Enable high optimizations for dependencies (incl. Bevy), but not for our code:
+[profile.dev.package."*"]
+opt-level = 3
+
+[profile.dev.package.bevy]
+features = ["dynamic"]
+
+#### --------------------Production/ release-------------------------------
+[profile.release]
+strip = "debuginfo"
+lto = "thin"

examples/bevy_gltf_blueprints/animation/README.md

@@ -7,10 +7,10 @@ Two animated blueprints are provided: Bevy's Fox, and a Robot I created.
 There is almost no boilerplate, other than setting up ```Bevy_gltf_blueprints```
 
 If you want to jump straight to controlling the imported animations, jump to : 
-[]('./game/in_game.rs#86')
+[]('./src/game/in_game.rs#86')
 
 ## Running this example
 
 ```
-cargo run --example animation  --features bevy/dynamic_linking
+cargo run --features bevy/dynamic_linking
 ```

examples/bevy_gltf_blueprints/animation/assets/assets_game.assets.ron

@@ -0,0 +1,6 @@
+({
+    "world":File (path: "models/Level1.glb"),
+    "models": Folder (
+        path: "models/library",
+    ),
+})

examples/bevy_gltf_blueprints/animation/src/assets/mod.rs

@@ -19,7 +19,7 @@ impl Plugin for AssetsPlugin {
             )
             .add_dynamic_collection_to_loading_state::<_, StandardDynamicAssetCollection>(
                 AppState::CoreLoading,
-                "advanced/assets_core.assets.ron",
+                "assets_core.assets.ron",
             )
             .add_collection_to_loading_state::<_, CoreAssets>(AppState::CoreLoading)
             // load game assets
@@ -28,7 +28,7 @@ impl Plugin for AssetsPlugin {
             )
             .add_dynamic_collection_to_loading_state::<_, StandardDynamicAssetCollection>(
                 AppState::AppLoading,
-                "advanced/assets_game.assets.ron",
+                "assets_game.assets.ron",
             )
             .add_collection_to_loading_state::<_, GameAssets>(AppState::AppLoading);
     }

examples/bevy_gltf_blueprints/animation/src/core/mod.rs

@@ -21,7 +21,7 @@ impl Plugin for CorePlugin {
             CameraPlugin,
             PhysicsPlugin,
             BlueprintsPlugin {
-                library_folder: "animation/models/library".into(),
+                library_folder: "models/library".into(),
             },
         ));
     }

examples/bevy_gltf_blueprints/basic/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "bevy_gltf_blueprints_basic_example"
+version = "0.3.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+
+[workspace]
+
+[dependencies]
+bevy="0.12"
+bevy_gltf_blueprints = { path = "../../../crates/bevy_gltf_blueprints" }
+bevy_rapier3d = { version = "0.23.0", features = [ "serde-serialize", "debug-render-3d", "enhanced-determinism"] }
+bevy_asset_loader = { version = "0.18", features = ["standard_dynamic_assets" ]} 
+bevy_editor_pls = { version = "0.6" }
+rand = "0.8.5"
+
+#### --------------------Dev/ debug-------------------------------
+# Enable high optimizations for dependencies (incl. Bevy), but not for our code:
+[profile.dev.package."*"]
+opt-level = 3
+
+[profile.dev.package.bevy]
+features = ["dynamic"]
+
+#### --------------------Production/ release-------------------------------
+[profile.release]
+strip = "debuginfo"
+lto = "thin"

examples/bevy_gltf_blueprints/basic/README.md

@@ -11,7 +11,7 @@ It also allows you to setup 'blueprints' in Blender by using collections (the re
 ## Running this example
 
 ```
-cargo run --example advanced  --features bevy/dynamic_linking
+cargo run --features bevy/dynamic_linking
 ```
 
 ### Additional notes

examples/bevy_gltf_blueprints/basic/TODO.md

@@ -18,7 +18,7 @@
         - [x] how to deal with states that are not defined as part of the plugin/crate ?
         - [x] same issue for the assets
 
-- [ ] support multiple main scenes in the blender plugin ?
+- [x] support multiple main scenes in the blender plugin ?
 - [ ] study possibilities of expanding the bevy & blender tooling side to define UIS
         - likely using the blender data only as a placeholder/ directly replace in Python
 

examples/bevy_gltf_blueprints/basic/assets/assets_game.assets.ron

@@ -0,0 +1,6 @@
+({
+    "world":File (path: "models/World.glb"),
+    "models": Folder (
+        path: "models/library",
+    ),
+})

examples/bevy_gltf_blueprints/basic/src/assets/mod.rs

@@ -19,7 +19,7 @@ impl Plugin for AssetsPlugin {
             )
             .add_dynamic_collection_to_loading_state::<_, StandardDynamicAssetCollection>(
                 AppState::CoreLoading,
-                "animation/assets_core.assets.ron",
+                "assets_core.assets.ron",
             )
             .add_collection_to_loading_state::<_, CoreAssets>(AppState::CoreLoading)
             // load game assets
@@ -28,7 +28,7 @@ impl Plugin for AssetsPlugin {
             )
             .add_dynamic_collection_to_loading_state::<_, StandardDynamicAssetCollection>(
                 AppState::AppLoading,
-                "animation/assets_game.assets.ron",
+                "assets_game.assets.ron",
             )
             .add_collection_to_loading_state::<_, GameAssets>(AppState::AppLoading);
     }

examples/bevy_gltf_blueprints/basic/src/core/mod.rs

@@ -25,7 +25,7 @@ impl Plugin for CorePlugin {
             PhysicsPlugin,
             // SaveLoadPlugin,
             BlueprintsPlugin {
-                library_folder: "advanced/models/library".into(),
+                library_folder: "models/library".into(),
             },
         ));
     }

examples/bevy_gltf_components/basic/Cargo.toml

@@ -0,0 +1,27 @@
+[package]
+name = "bevy_gltf_components_basic_example"
+version = "0.3.0"
+edition = "2021"
+license = "MIT OR Apache-2.0"
+
+[workspace]
+
+[dependencies]
+bevy="0.12"
+bevy_gltf_components = { path = "../../../crates/bevy_gltf_components" }
+bevy_rapier3d = { version = "0.23.0", features = [ "serde-serialize", "debug-render-3d", "enhanced-determinism"] }
+bevy_editor_pls = { version = "0.6" }
+
+
+#### --------------------Dev/ debug-------------------------------
+# Enable high optimizations for dependencies (incl. Bevy), but not for our code:
+[profile.dev.package."*"]
+opt-level = 3
+
+[profile.dev.package.bevy]
+features = ["dynamic"]
+
+#### --------------------Production/ release-------------------------------
+[profile.release]
+strip = "debuginfo"
+lto = "thin"

examples/bevy_gltf_components/basic/README.md

@@ -0,0 +1,33 @@
+
+# Basic bevy_gltf_components demo
+
+## Running this example
+
+```
+cargo run --features bevy/dynamic_linking
+```
+
+
+### Additional notes
+
+* You usually define either the Components directly or use ```Proxy components``` that get replaced in Bevy systems with the actual Components that you want (usually when for some reason, ie external crates with unregistered components etc) you cannot use the components directly.
+
+Included are the following modules / tools
+ * [```process_gltf```](./src/process_gltfs.rs) the most important module: this is the one extracting ```component``` information from the gltf files
+ * [```insert_dependant_component```](./src/core/relationships/relationships_insert_dependant_components.rs)  a small utility to automatically inject 
+    components that are dependant on an other component
+    for example an Entity with a Player component should also always have a ShouldBeWithPlayer component
+    you get a warning if you use this though, as I consider this to be stop-gap solution (usually you should have either a bundle, or directly define all needed components)
+ * [```camera```](./src/core/camera/) an example post process/replace proxies plugin, for Camera that also adds CameraTracking functions (to enable a camera to follow an object, ie the player)
+ * [```lighting```](./src/core/lighting/) an other example post process/replace proxies plugin for lighting, that toggles shadows, lighting config, etc so that things look closer to the original Blender data
+ * [```physics```](./src/core/physics/) an other example post process/replace proxies plugin for physics, that add [Rapier](https://rapier.rs/docs/user_guides/bevy_plugin/getting_started_bevy) Colliders, Rigidbodies etc . Most of these do not need proxies these days, as the most Rapier components are in the Registry & can be used directly
+
+Feel free to use as you want, rip it appart, use any/all parts that you need !
+
+This tooling and workflow has enabled me to go from a blank Bevy + Blender setup to a working barebones level in very little time (30 minutes or so ?) !
+You can then add your own components & systems for your own gameplay very easilly
+
+## Information
+- the Bevy/ Rust code is [here](./src/main.rs)
+- the Blender file is [here](./assets/basic.blend)
+- I added [bevy_editor_pls](https://github.com/jakobhellermann/bevy_editor_pls) as a dependency for convenience so you can inspect your level/components