Blender_bevy_components_wor.../crates/bevy_gltf_blueprints
Mark Moissette 528e13a250
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 14:10:45 +02:00
..
src feat(): Blueprints, crates, enhanced Blender tooling & more (#5) 2023-09-28 14:10:45 +02:00
Cargo.toml feat(): Blueprints, crates, enhanced Blender tooling & more (#5) 2023-09-28 14:10:45 +02:00
LICENCE.md feat(): Blueprints, crates, enhanced Blender tooling & more (#5) 2023-09-28 14:10:45 +02:00
LICENSE_APACHE.md feat(): Blueprints, crates, enhanced Blender tooling & more (#5) 2023-09-28 14:10:45 +02:00
LICENSE_MIT.md feat(): Blueprints, crates, enhanced Blender tooling & more (#5) 2023-09-28 14:10:45 +02:00
README.md feat(): Blueprints, crates, enhanced Blender tooling & more (#5) 2023-09-28 14:10:45 +02:00

Crates.io Docs License Bevy tracking

bevy_gltf_blueprints

Built upon bevy_gltf_components this crate adds the ability to define Blueprints/Prefabs for Bevy inside gltf files and spawn them in Bevy.

A blueprint is a set of overrideable components + a hierarchy: ie

* just a Gltf file with Gltf_extras specifying components 
* a component called BlueprintName

Particularly useful when using Blender as an editor for the Bevy game engine, combined with the Blender plugin that does a lot of the work for you

Usage

Here's a minimal usage example:

# Cargo.toml
[dependencies]
bevy_gltf_blueprints = { version = "0.1.0"} 

use bevy::prelude::*;
use bevy_gltf_blueprints::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugin(BlueprintsPlugin)

        .run();
}

// not shown here: any other setup that is not specific to blueprints

fn spawn_blueprint(
    mut commands: Commands,
    keycode: Res<Input<KeyCode>>,
){
    if keycode.just_pressed(KeyCode::S) {
        let new_entity = commands.spawn((
            BlueprintName("Health_Pickup".to_string()), // mandatory !!
            SpawnHere, // mandatory !!
            TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)), // VERY important !!
            // any other component you want to insert
        ));
    }
}

Setup

  • configure your "library"/"blueprints" path: advanced/models/library/

Spawning entities from blueprints

You can spawn entities from blueprints like this:

commands.spawn((
    BlueprintName("Health_Pickup".to_string()), // mandatory !!
    SpawnHere, // mandatory !!
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)), // VERY important !!
    // any other component you want to insert
))

Once spawning of the actual entity is done, the spawned Blueprint will be gone/merged with the contents of Blueprint !

Important : you can add or override components present inside your Blueprint when spawning the BluePrint itself: ie

Adding components not specified inside the blueprint

you can just add any additional components you need when spawning :

commands.spawn((
    BlueprintName("Health_Pickup".to_string()),
    SpawnHere,
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)),
    // from Rapier/bevy_xpbd: this means the entity will also have a velocity component when inserted into the world
    Velocity {
        linvel: Vec3::new(vel_x, vel_y, vel_z),
        angvel: Vec3::new(0.0, 0.0, 0.0),
      },
))

Overriding components specified inside the blueprint

any component you specify when spawning the Blueprint that is also specified within the Blueprint will override that component in the final spawned entity

for example

commands.spawn((
    BlueprintName("Health_Pickup".to_string()),
    SpawnHere,
    TransformBundle::from_transform(Transform::from_xyz(x, 2.0, y)),
    HealthPowerUp(20)// if this is component is also present inside the "Health_Pickup" blueprint, that one will be replaced with this component during spawning
))

BluePrintBundle

There is also a bundle for convenience , which just has

  • a BlueprintName component
  • a SpawnHere component
  • a TransformBundle sub-bundle (so we know where to spawn)

BluePrintBundle

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 Blueprint based spawning,

so bevy_gltf_blueprints provides a SystemSet for that purpose:GltfBlueprintsSet

Typically , the order of systems should be

bevy_gltf_components (GltfComponentsSet::Injection) => bevy_gltf_blueprints (GltfBlueprintsSet::Spawn, GltfBlueprintsSet::AfterSpawn) => replace_proxies

see https://github.com/kaosat-dev/Blender_bevy_components_worklflow/tree/main/examples/advanced for how to set it up correctly

Examples

https://github.com/kaosat-dev/Blender_bevy_components_worklflow/tree/main/examples/advanced

License

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