Bevy Code & Blender addon for a simple workflow to add & edit Bevy components in Blender
Go to file
Mark Moissette 5429bf4779
feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95)
* feat(bevy_gltf_save_load): saving & loading implemented
   * created new crate for save & load features, uses & filters out blueprints for efficient loading
   * saving & loading, even with dynamically spawned nested hierarchies works 
   * component filter , resource filter & save path root are configurable
   * for saving: added removal & cleanup logic for children component with children
  that have been filtered out: ie no more invalid children getting stored in the save files !
   * added sending of event once saving is done

* feat(examples/save-load): example for the new crate
   * loading level static & dynamic data as blueprints
   * added a bit of ui when entering saving & loading states & cleanup when exiting

* feat(bevy_gltf_blueprints): significant rewrite of how the crate works
     * simplified spawning process, no more spawning children containing blueprints etc
     * simplified post process : instead of copying original entity  into blueprint root
      we now copy blueprint root data (components & children) into the original entity ! fixes #96 
     * much simpler code wise
     * solves issue with needing to register components that we only use on the bevy side (not gltf)
    since we are not copying the bevy data into the blueprints data
     * added **copyComponents** helper to copy components from one entity to another, excluding existing
     components on the target entity, & some bells & whistles
     * **Name** is now optional when spawning a blueprint: closes #97 
     * **Transform** is now optional when spawning a blueprint: closes #98 
     * removed transform from bundle (BREAKING change)
     * added (optional)  **NoInBlueprint** component to have finer control over whether to inject the **InBlueprint** component inside spawned blueprint entities
     * added (optional) **Library**  component, so we can override library path when we want
     * added (optional) **AddToGameWorld** component for convenience   to automatically add entities to the game world, if there is one

* chore(bevy_gltf_components): removed verbose output, cleaned it up a bit

* feat(tools/auto_export): added option to split out "dynamic" objects in main scenes
   * ie if a collection instance (or its original collection) has a "dynamic" (aka mutable, saveable etc)
     flag it can get exported to a seperate gltf file (essentially acting like an "initial save")
   * the rest of the levels (the "static" data) is exported without the dynamic objects and
     can be reused with save files !
2024-01-10 14:49:29 +01:00
crates feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95) 2024-01-10 14:49:29 +01:00
docs refactor(tools/gltf_auto_export): complete restructuring of the tool (#67) 2023-12-04 14:48:52 +01:00
examples feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95) 2024-01-10 14:49:29 +01:00
tools/gltf_auto_export feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95) 2024-01-10 14:49:29 +01:00
.gitignore refactor(tools/gltf_auto_export): complete restructuring of the tool (#67) 2023-12-04 14:48:52 +01:00
Cargo.lock feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95) 2024-01-10 14:49:29 +01:00
Cargo.toml feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95) 2024-01-10 14:49:29 +01:00
LICENSE.md fix(): various Fixes and tweaks (#7) 2023-09-28 16:53:21 +02:00
LICENSE_APACHE.md docs(): readme tweaks + added licenses 2023-07-27 02:08:57 +02:00
LICENSE_MIT.md docs(): readme tweaks + added licenses 2023-07-27 02:08:57 +02:00
README.md feat(Save & load): new crate bevy_gltf_save_load + lots of upgrades & improvements (#95) 2024-01-10 14:49:29 +01:00
rust-toolchain.toml chore(rust): Add specific Rust version via rust-toolchain (#91) 2024-01-03 10:43:16 +01:00

README.md

Bevy tracking License

Blender_bevy_components_workflow

demo

Crates & tools for adding components from gltf files in the Bevy game engine.

It enables minimalistic Blender (gltf) centric workflow for Bevy, 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 (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 to auto-export to gltf on save (and more !) if you want !)
  • 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 for reuse
  • minimal setup & code, you can have something basic running fast
  • minimal dependencies: Bevy, Serde & Ron only !
  • opensource

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 if you want, or you can read the crate docs. The examples for the crate are here

  • 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 for this one too, or you can read the crate docs The examples for the crate are here

Note: this is the recomended crate to use and uses bevy_gltf_components under the hood

  • 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

Note: this uses bevy_gltf_blueprints under the hood

Tools

Blender: gltf_auto_export

  • for convenience I also added a Blender addon that automatically exports your level/world from Blender to gltf whenever you save your Blend file
  • it also supports automatical exports of collections as Gltf blueprints & more !

Please read the README of the add-on for installation & use instructions

Examples

you can find all examples, by crate as seperate crates for clearer dependencies in here

  • bevy_gltf_components

    • basic use of bevy_gltf_components only, to spawn entities with components defined inside gltf files
  • 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 how to use and trigger animations from gltf files (a feature of bevy_gltf_blueprints)

Workflow

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

  • 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

      In rust:

      unit struct components in Bevy

      (the Rust struct for these components for reference is here )

      complex components in Blender

      In rust:

      complex components in Blender

      (the Rust struct for this component for reference is here )

      There is an other examples of using various Component types: Enums, Tupple structs, strucs with fields etc here, even colors, Vecs (arrays), Vec2, Vec3 etc are all supported

      complex components in Blender

  • 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

    • 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
    • or much better, using 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 components in bevy components in bevy

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

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

  • 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 :)

Contributors

Thanks to all the contributors helping out with this project ! Big kudos to you, contributions are always appreciated ! :)

License

This repo, all its code, contents & assets is Dual-licensed under either of