Blender_bevy_components_wor.../crates/bevy_gltf_components/README.md

142 lines
5.4 KiB
Markdown
Raw Normal View History

feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
[![Crates.io](https://img.shields.io/crates/v/bevy_gltf_components)](https://crates.io/crates/bevy_gltf_components)
[![Docs](https://img.shields.io/docsrs/bevy_gltf_components)](https://docs.rs/bevy_gltf_components/latest/bevy_gltf_components/)
[![License](https://img.shields.io/crates/l/bevy_gltf_components)](https://github.com/kaosat-dev/Blender_bevy_components_workflow/blob/main/crates/bevy_gltf_components/License.md)
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)
# bevy_gltf_components
This crate allows you to define [Bevy](https://bevyengine.org/) components direclty inside gltf files and instanciate the components on the Bevy side.
## Usage
***important*** : the plugin for processing gltf files runs in ***update*** , so you cannot use the components directly if you spawn your scene from gltf in ***setup*** (the additional components will not show up)
Please see the
* [example](https://github.com/kaosat-dev/Blender_bevy_components_workflow/examples/basic)
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
* or use [```bevy_asset_loader```](https://github.com/NiklasEi/bevy_asset_loader) for a reliable workflow.
* alternatively, use the [```bevy_gltf_blueprints```](https://github.com/kaosat-dev/Blender_bevy_components_workflow/blob/main/crates/bevy_gltf_blueprints) crate, build on this crate's features,
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
that allows you to directly spawn entities from gltf based blueprints.
Here's a minimal usage example:
```toml
# Cargo.toml
[dependencies]
bevy="0.13"
bevy_gltf_components = { version = "0.5"}
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
```
```rust no_run
//too barebones of an example to be meaningfull, please see https://github.com/kaosat-dev/Blender_bevy_components_workflow/examples/basic for a real example
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugin(ComponentsFromGltfPlugin::default())
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
.add_system(spawn_level)
.run();
}
fn spawn_level(
asset_server: Res<AssetServer>,
mut commands: bevy::prelude::Commands,
keycode: Res<Input<KeyCode>>,
){
if keycode.just_pressed(KeyCode::Return) {
commands.spawn(SceneBundle {
scene: asset_server.load("basic/models/level1.glb#Scene0"),
transform: Transform::from_xyz(2.0, 0.0, -5.0),
..Default::default()
});
}
}
```
## Installation
Add the following to your `[dependencies]` section in `Cargo.toml`:
```toml
bevy_gltf_components = "0.5"
```
Or use `cargo add`:
```toml
cargo add bevy_gltf_components
```
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
## Configuration
starting with version 0.3, this plugin is configurable
Use the default configuration:
```rust no_run
ComponentsFromGltfPlugin::default()
```
Or disable the legacy mode: (enabled by default)
```rust no_run
ComponentsFromGltfPlugin{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
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
## SystemSet
the ordering of systems is very important !
For example to replace your proxy components (stand-in components when you cannot/ do not want to use real components in the gltf file) with actual ones,
which should happen **AFTER** the components from the gltf files have been injected,
so ```bevy_gltf_components``` provides a **SystemSet** for that purpose:[```GltfComponentsSet```](./src/lib.rs#46)
Typically , the order of systems should be
***bevy_gltf_components (GltfComponentsSet::Injection)*** => ***replace_proxies***
## Additional features
- as of version 0.5 , this crate also includes automatic handling of lights in gltf files, to attempt to match Blender's eevee rendering as close as possible:
* **BlenderLightShadows** (automatically generated by the gltf_auto_export Blender add-on) allows you to toggle light's shadows on/off in Blender and have matching
behaviour in Bevy
* **BlenderBackgroundShader** aka background color is also automatically set on the Bevy side
* **BlenderShadowSettings** sets the cascade_size on the bevy side to match the one configured in Blender
If these components are present in your gltf file, they will be handled automatically by this crate, will be ignored otherwise.
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
## Examples
https://github.com/kaosat-dev/Blender_bevy_components_workflow/tree/main/examples/basic
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
## Compatible Bevy versions
The main branch is compatible with the latest Bevy release, while the branch `bevy_main` tries to track the `main` branch of Bevy (PRs updating the tracked commit are welcome).
Compatibility of `bevy_gltf_components` versions:
| `bevy_gltf_components` | `bevy` |
| :-- | :-- |
| `0.5` | `0.13` |
| `0.2 - 0.4` | `0.12` |
| `0.1` | `0.11` |
| branch `main` | `0.13` |
| branch `bevy_main` | `main` |
feat(): Blueprints, crates, enhanced Blender tooling & more (#5) * feat(bevy_gltf_components): * create crate * added SystemSet (GltfComponentsSet) to run process_loaded_scenes (where components are injected) in a specific systemset & allow ordering other systems relative to it * feat(bevy_gltf_blueprints): * created crate * made the blueprint library path configurable * added BluePrintBundle helper * added SystemSet (GltfBlueprintsSet) for better system ordering * integrated into advanced demo * feat(tools-blender-auto-export): * renamed blender tool to gltf_auto_export * rewritten auto_export * added blueprint / prefab support * creates scene with empties with BlueprintName components in the scene * export of the main scene now exports this scene instead of real main scene * changes collection stand in names in original scene & sets them back after export to have correctly named collection instance exports * also added an additional 'SpawnHere' component to not conflate BlueprintNames & spawning requests * toggling & blueprint library output parameters added * added correct handling/ restoring of saved selection when using blueprints * feat(examples): * added advanced example * general example renamed to "basic", and cleaned up * feat(various): a lot of experiments with saving & loading etc * chore(assets): updated blend & generated assets * fix(examples-advanced): disabling hot reloading as it messes up scenes in experiments with save & loading * docs(): * added & fleshing out docs for the various crates & main README * added process doc image & tweaks to README * added missing licence info where relevant * fixed broken links * clarified some aspects * added updated screenshots where relevant * added tweaks & improvements etc
2023-09-28 12:10:45 +00:00
## License
This crate, 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)