Blender_bevy_components_wor.../tools/blenvy/README.md

179 lines
7.5 KiB
Markdown

# Blenvy: Blender add-on
This [Blender addon](https://github.com/kaosat-dev/Blenvy/tree/main/tools/blenvy) gives you:
- an easy to use UI to add and configure your [Bevy](https://bevyengine.org/) components inside Blender
- the UI is **automatically generated** based on a **registry schema** file, an export of all your **registered** Bevy components's information, generated
by the registry export part of the [Blenvy](https://crates.io/crates/blenvy) crate
- the ability to **toggle components** on/off without having to remove the component from the object
- an easy way to create blueprints/prefabs (just collections !) & levels
- a way to setup you assets for your levels & blueprints
- an automatic export of your level/world from Blender to gltf whenever you save your Blend file.
- export of used /marked collections as [Gltf blueprints](../../crates/blenvy/README.md)
- change detection, so that only the levels & blueprints you have changed get exported when you save your blend file
- export of material librairies
> IMPORTANT !! if you have previously used the "old" add-ons (*gltf_auto_export* & *bevy_components*), please see the [migration guide](../../Migration_guide.md)
If you can I would generally recommend starting fresh, but a lot of effort has been put to make transitioning easier
## Installation:
* grab the latest release zip file
![blender addon install](./docs/blender_addon_install_zip.png)
* up to Blender 4.1 go to edit => preferences => add-ons, click on install and choose the path where ```blenvy.zip``` is stored
![blender addon install](./docs/blender_addon_install.png)
* for Blender 4.2 , just drag & drop the zip file onto Blender to start the installation process
## Quickstart
* create your Bevy project
* setup the Blenvy crate
* create a Blender project
* set your level & library scenes (the **only** things that are not pre-configured)
![blenvy common settings](./docs/blenvy_configuration_common.png)
* create your blueprints & levels
* add components (remember to configure the Bevy side first )
* save your blend file at any point , the rest is done automatically (export of levels & blueprints, etc)
## Configuration:
### Bevy side
- setup the [Blenvy crate](https://crates.io/crates/blenvy) for your project (see the crate's documentation for that), and compile/run it to get the ```registry.json``` file to enable adding/editing your components in Blender
### Blender side
> The add-on comes almost completely pre-configured with sensible defaults, but you can set the following settings to your liking
#### Common
The first tab (and the one that is open by default in a new project) contains the common settings:
![blenvy common settings](./docs/blenvy_configuration_common.png)
you **need** to tell Blenvy
- what your level scenes are (what Blender scenes should become levels in Bevy)
- what your library scenes are (what Blender scenes will store your library of re-useable blueprints)
Blenvy is opinionated !
- keep you art/sources (usually not delivered with your game) seperate from your game assets
- keep your blueprints/levels/materials gltf files seperate
##### Root Folder (default: ../)
- this is the same folder as your Bevy projects main folder: the path here is relative to the current .blend file
##### Assets Folder (default: ./assets)
- a path, relative to the *root* folder above, where you want to store your assets (delivered with your game)
##### Blueprints Folder (default: blueprints)
- a path, relative to the *assets* folder above, where you want to store your *blueprints*
##### Levels Folder (default: levels)
- a path, relative to the *assets* folder above, where you want to store your *levels*
##### Materials Folder (default: materials)
- a path, relative to the *assets* folder above, where you want to store your *materials*
##### Level scenes
- what are the scenes in your .blend file that are levels/worlds
##### library scenes
- library scenes: what are the scenes in your .blend file that contain your libraries of blueprints (that you then use in your levels)
#### Recomended folder structure
![recomended folder structure](./docs/blenvy_recommended_folder_structure.png)
![recomended folder structure art](./docs/blenvy_recommended_folder_structure_art.png)
![recomended folder structure assets](./docs/blenvy_recommended_folder_structure_assets.png)
##### Components & export settings:
- for components please see [here](./README-components.md#configuration)
- for export please see [here](./README-export.md#configuration)
### Multiple blend file workflow
If you want to use multiple blend files (recomended if your project starts to grow even a bit), use Blender's asset library etc, we got you coverred too !
There are only a few things to keep in mind
#### Assets/library/blueprints files
- mark your library scenes as specified above, but **do NOT** specify a **level** scene
- mark any collection in your scenes as "assets"
- choose "split" for the combine mode (as you want your gltf blueprints to be saved for external use)
- do your Blender things as normal
- anytime you save your file, it will automatically export any relevant collections/blueprints
- (optional) activate the **material library** option, so you only have one set of material per asset library (recomended)
#### Level/world files
- mark your level scenes as specified above ( personally I recommended **NOT** specifying a **library** scene in this case to keep things tidy, but that is up to you)
- configure your asset libraries as you would usually do, I recomend using the "link" mode so that any changes to asset files are reflected correctly
- drag & drop any assets from the blueprints library (as you would normally do in Blender as well)
- choose "split" for the combine mode (as you want your gltf blueprints to be external usually & use the gltf files generated from your assets library)
- do your Blender things as normal
- anytime you save your file, it will automatically export your level(s)
Take a look at the [relevant](../../examples/demo/) example for more [details](../../examples/demo/art/)
## Useage
### Components
- for a detailed overview on how to add, edit, remove etc components please see [here](./README-components.md)
### Export
- for a detailed overview on auto exporting gltf files please see [here](./README-export.md)
### Levels
- for a detailed overview of blueprints please see [here](./README-levels.md)
### Blueprints
- for a detailed overview of blueprints please see [here](./README-blueprints.md)
> [!TIP]
> you can right click on a Blueprint instance in your level scenes or press SHIFT + F to edit a Blueprint in a seperate temprary scene !
> you can right click or press SHIFT + F to create a new empty Blueprint and an instance of it from your main scenes
> right click again & select the option to stop editing it, or
## Development
- I highly recomend (if you are using vscode like me) to use
[this](https://marketplace.visualstudio.com/items?itemName=JacquesLucke.blender-development) excellent extension , works easilly and fast , even for the latest
versions of Blender (v4.0 as of this writing)
- this [article](https://polynook.com/learn/set-up-blender-addon-development-environment-in-windows) might also help out
(easy enough to get it working on linux too)
## License
This tool, all its code, contents & assets is Dual-licensed under either of
- Apache License, Version 2.0, ([LICENSE-APACHE](../LICENSE_APACHE.md) or https://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](../LICENSE_MIT.md) or https://opensource.org/licenses/MIT)