docs(README): updated docs, images etc

* updated images & text from JSON => RON
 * also added a section for the Blender tool
This commit is contained in:
kaosat.dev 2023-07-27 01:53:48 +02:00
parent cf6af7b3ef
commit bd6957bae3
26 changed files with 70 additions and 26 deletions

View File

@ -1,7 +1,7 @@
# Blender_gltf_components
![demo](./_docs/blender_gltf_components.png)
![demo](./docs/blender_gltf_components.png)
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
@ -10,12 +10,20 @@ 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 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
## Workflow
The workflow goes as follows (once you got your Bevy code setup)
- add the ```process_gltf``` [module code](./process_gltf/)
- add the ```process_gltf``` [module code](./core/process_gltf/)
- add the ```ProcessGltfPlugin```, to your app
```rust
.add_plugins((
@ -27,38 +35,42 @@ 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 registration](./docs/component_registration.png)
- Create a mesh/ collection (for reuse) in Blender
- Go to object properties => add a **STRING** property, and add your component data
- unit structs, enums, and more complex strucs / components are all supported, if the fields are basic data types
- for structs with no params: use ```null``` as a value
- for structs with params: use a json representation of your fields (see below)
- for structs with no params (unit structs): use an empty value
- for structs with params: use a RON representation of your fields (see below)
![unit struct components in Blender](./_docs/components_blender.png)
![unit struct components in Blender](./docs/components_blender.png)
In rust:
![unit struct components in Bevy](./_docs/demo_simple_components.png)
![unit struct components in Bevy](./docs/demo_simple_components.png)
(the Rust struct for these components for reference is [here](./main.rs#40) )
(the Rust struct for these components for reference is [here](./src/game.rs#34) )
![complex components in Blender](./_docs/components_blender_parameters.png)
![complex components in Blender](./docs/components_blender_parameters.png)
In rust:
![complex components in Blender](./_docs/camera_tracking_component.png)
![complex components in Blender](./docs/camera_tracking_component.png)
(the Rust struct for this component for reference is [here](./camera/camera_tracking.rs#14) )
(the Rust struct for this component for reference is [here](./src/core/camera/camera_tracking.rs#21) )
Other examples of parameters, Enums (no quotes), strucs with fields etc
![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)
![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)
@ -70,34 +82,36 @@ The workflow goes as follows (once you got your Bevy code setup)
- custom properties
- cameras & lights if you want a complete level (as in this example)
![gltf_export](./_docs/gltf_export.png)
![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)
![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)
![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
* 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```](./process_gltf/) the most important module: this is the one extracting ```component``` information from the gltf files
* [```insert_dependant_component```](/examples/blender_gltf_components/relationships/relationships_insert_dependant_components.rs) a small utility to automatically inject
* [```process_gltf```](./src/core/process_gltf/) 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```](./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```](./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
* [```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
@ -107,22 +121,52 @@ This tooling and workflow has enabled me to go from a blank Bevy + Blender setup
You can then add your own components & systems for your own gameplay very easilly
## Information
- the Bevy/ Rust code is [here](/examples/blender_gltf_components/main.rs)
- the Blender file is [here](../../assets/models/level.blend)
- the Bevy/ Rust code is [here](./src/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
## Limitations / issues
- the components have to be defined in ```JSON``` in Blender, which is a relic of my initial implementation, not very practical, rather verbose, will likely try switching to RON at some point, or even use the AppTypeRegistry and some Python code on the Blender side for a nicer UI (although this loses the "fast & easy, no tooling" approach)
- the 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)
- the asset management in this example is stripped down for demo purposes, I normally use https://github.com/NiklasEi/bevy_asset_loader to define, organise and preload assets
(in a different state that comes before the actual game/level), so you will see some of the changes to the level/scene "flash by"
- I did not include `bevy_rapier`/physics code that I usually use to trim down the demo, but I kept some of the proxy items in the Blender scene, might add physics back as I wanted a cleaner way to define colliders from within Blender (currently it also goes via json)
- Some of `bevy_rapier`/physics code / ways to define colliders could perhaps be done better 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
* gltf spawning tools where you just need to preload gltf files then you can spawn 1...n entities defined in gltf files by name (for example enemies, powerups, etc)
* simplified animation logic: ie instead of having to manually specify the animations you need from a gltf file, it is integrated with the spawning system above, which creates a ```Animations``` component in all entities that have an ```AnimationPlayer``` and you can simply query for both to easilly control your animations per entity.
## Bonus !!
- for convenience I also added a [Blender addon](./tools/blender_auto_export/blender_auto_export_gltf.py) that automatically exports your level/world from Blender to gltf whenever you save your Blend file
(actually when you save inside your level/world scene or in the "library" scene, where I personally usually store all collections to instanciate).
It is **very** barebones and messy, but it does a minimal ok job.
### Installation:
* in Blender go to edit => preferences => install
![blender addon install](./docs/blender_addon_install.png)
* choose the path where ```blender_auto_export/blender_auto_export_gltf.py``` is stored
![blender addon install](./docs/blender_addon_install2.png)
### Usage:
* before it can automatically save to gltf, you need to configure it
* go to file => export => gltf auto export
![blender addon use](./docs/blender_addon_use.png)
* set up your parameters: output path, name of your main scene etc
![blender addon use2](./docs/blender_addon_use2.png)
* click on "apply settings"
* now next time you save your blend file you will get an automatically exported gltf file
## 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 :)

Binary file not shown.

Before

Width:  |  Height:  |  Size: 315 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 142 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 25 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 164 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 212 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 410 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 42 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 72 KiB

BIN
docs/blender_addon_use.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 287 KiB

BIN
docs/blender_addon_use2.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 299 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 964 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 24 KiB

View File

Before

Width:  |  Height:  |  Size: 4.1 KiB

After

Width:  |  Height:  |  Size: 4.1 KiB

View File

Before

Width:  |  Height:  |  Size: 59 KiB

After

Width:  |  Height:  |  Size: 59 KiB

BIN
docs/components_bevy.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 219 KiB

View File

Before

Width:  |  Height:  |  Size: 199 KiB

After

Width:  |  Height:  |  Size: 199 KiB

BIN
docs/components_bevy3.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 121 KiB

BIN
docs/components_blender.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 372 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 68 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 10 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 11 KiB

View File

Before

Width:  |  Height:  |  Size: 106 KiB

After

Width:  |  Height:  |  Size: 106 KiB