Docs: SceneSpawner

[ChristopherBiscardi]

while we wait for bsn (maybe 0.18?) its useful to document the behavior of SceneRoot and SceneSpawner, specifically around the behavior of SceneRoot causing an additional parent node.

Using the example program below with a default cube scene (no camera, no light, but that's not particularly critical to the example).

use bevy::{
    input::common_conditions::input_toggle_active,
    prelude::*, scene::SceneInstanceReady,
};
use bevy_inspector_egui::{
    bevy_egui::EguiPlugin, quick::WorldInspectorPlugin,
};
use bevy_skein::SkeinPlugin;

fn main() {
    App::new()
        .register_type::<Character>()
        .add_plugins((
            DefaultPlugins,
            SkeinPlugin::default(),
            EguiPlugin::default(),
            WorldInspectorPlugin::default().run_if(
                input_toggle_active(true, KeyCode::Escape),
            ),
        ))
        .add_systems(Startup, startup)
        .add_systems(Update, on_load_gltf)
        .add_observer(
            |trigger: Trigger<SceneInstanceReady>| {
                info!(event = ?trigger.event());
            },
        )
        .run();
}

#[derive(Component, Reflect, Debug)]
#[reflect(Component)]
struct Character {
    name: String,
}

#[derive(Resource)]
struct Hold(Handle<Gltf>);

fn startup(
    mut commands: Commands,
    asset_server: Res<AssetServer>,
) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(0., 4., 10.)
            .looking_at(Vec3::ZERO, Vec3::Y),
    ));

    // commands.spawn((
    //     Name::new("MySceneContainer"),
    //     SceneRoot(
    //         asset_server.load(
    //             // Change this to your exported gltf file
    //             GltfAssetLabel::Scene(0)
    //                 .from_asset("Untitled.gltf"),
    //         ),
    //     ),
    // ));

    let gltf = asset_server.load("Untitled.gltf");
    commands.insert_resource(Hold(gltf));
}

fn on_load_gltf(
    mut events: EventReader<AssetEvent<Gltf>>,
    gltfs: Res<Assets<Gltf>>,
    mut scene_spawner: ResMut<SceneSpawner>,
) {
    for event in events.read() {
        match event {
            AssetEvent::LoadedWithDependencies { id } => {
                let Some(gltf) = gltfs.get(*id) else {
                    continue;
                };

                let Some(scene_handle) =
                    gltf.default_scene.as_ref()
                else {
                    continue;
                };

                scene_spawner.spawn(scene_handle.clone());
            }
            _ => {}
        }
    }
}

The "SceneRoot Entity" is inserted as the parent, or not, depending on the approach chosen.

[shining-grimace]

Thanks for the awesome work on this tool! I've just started using it, and finding it overall a treat to work with and the documentation is super-helpful.

Commenting here on one thing that stumped me, which was related to how spawning a SceneRoot works.

What I was trying to do was get Avian's Collider::trimesh_from_mesh going, by adding my own marker component to the Blender object, and using an on_add hook to look up the Mesh3d component. I had to get bevy_inspector_egui set up to figure out the scene hierarchy added when the scene was spawned.

The extra parent node was surprising but didn't cause problems for me; what did lose me some time was not realising that components added to the Blender object are on the parent entity relative to the mesh entity - they're not the same thing. Might be obvious given how glTF works in Bevy - I don't know if this is skein-specific in any way - but it would be great to see Inserting Components updated to show how the Blender object, mesh, and material are structured in Bevy entities, as this will help understanding where components inserted in Blender will fall relative to others.

[ChristopherBiscardi]

I don't know if this is skein-specific in any way

It is not skein-specific, but it is a thing many people have been confused about in the Blender UI so its a good callout for the docs, thanks. The avian "trimesh_from_mesh" does need to be added to the Mesh data specifically (or more accurately, end up on an Entity that has the Mesh data). One alternative is the ColliderConstructorHierarchy component which will search down the hierarchy for you, so can be placed on Objects.

You can add Components using Skein to Objects, Meshes, and Materials, but the hierarchy in Bevy is something like:

• Object
  • Mesh & Material

And if you use multiple materials on a mesh, you'll end up with multiple mesh/material children.

[ChristopherBiscardi]

Here's a program that uses SceneSpawner to insert arbitrary components on a scene without using the artificial SceneRoot extra entity.

This program has extra scaffolding for example/clarity sake, but the key is:

• if you've loaded your gltf/scene
• and implemented a custom command

then you can spawn in arbitrary instances of that scene with arbitrary components on the root as such

commands.queue(SpawnMyCar {
    scene: scene_handle.clone(),
    components: (SomethingElse(1),),
});

here's the full program, which we might want to clean up and put in an example. The program assumes there is a MyRootMarker component on the true scene root entity, such as having placed it there in Blender.

use bevy::prelude::*;
use bevy_skein::SkeinPlugin;

fn main() {
    App::new()
        .add_plugins((DefaultPlugins, SkeinPlugin::default()))
        .add_systems(Startup, startup)
        .add_systems(Update, on_load_gltf)
        .add_systems(Update, check_for_spawned_scene)
        .run();
}

#[derive(Component, Default, Reflect, Debug)]
#[reflect(Component, Default)]
#[type_path = "api"]
struct Character {
    name: String,
}

#[derive(Component, Default, Reflect, Debug)]
#[reflect(Component, Default)]
#[type_path = "api"]
struct MyRootMarker;

#[derive(Component, Default, Reflect, Debug)]
#[reflect(Component, Default)]
#[type_path = "api"]
struct SomethingElse(u32);

#[derive(Resource, Clone)]
struct CarGltf(Handle<Gltf>);

fn check_for_spawned_scene(
    query: Query<Entity, With<MyRootMarker>>,
    children: Query<&Children>,
    mut commands: Commands,
    mut local: Local<bool>,
) {
    if *local {
        return;
    }
    for root in &query {
        commands.entity(root).log_components();

        for entity in children.iter_descendants(root) {
            *local = true;
            commands.entity(entity).log_components();
        }
    }
}

fn startup(mut commands: Commands, asset_server: Res<AssetServer>) {
    let car_gltf = CarGltf(asset_server.load("demo.gltf"));
    commands.insert_resource(car_gltf);
}

fn on_load_gltf(
    mut reader: MessageReader<AssetEvent<Gltf>>,
    car: Res<CarGltf>,
    gltfs: Res<Assets<Gltf>>,
    mut commands: Commands,
) {
    for event in reader.read() {
        let AssetEvent::LoadedWithDependencies { id } = event else {
            continue;
        };

        if *id == car.0.id() {
            commands.queue(SpawnMyCar {
                scene: gltfs.get(&car.0).unwrap().named_scenes["Scene"].clone(),
                components: (SomethingElse(1),),
            });
        }
    }
}

struct SpawnMyCar<T: Bundle> {
    scene: Handle<Scene>,
    components: T,
}

impl<T: Bundle> Command for SpawnMyCar<T> {
    fn apply(self, world: &mut World) -> () {
        world.resource_scope(|world, mut scene_spawner: Mut<SceneSpawner>| {
            let instance = scene_spawner
                .spawn_sync(world, &self.scene)
                .expect("scene should have spawned");

            if !scene_spawner.instance_is_ready(instance) {
                panic!("instance not ready and should be");
            }

            let Some(root_entity) = scene_spawner
                .iter_instance_entities(instance)
                .find(|entity| world.entity(*entity).get::<MyRootMarker>().is_some())
            else {
                panic!("no MyRootMarker component on Scene's root entity!");
            };

            world.entity_mut(root_entity).insert(self.components);
        });
    }
}

[ChristopherBiscardi]

gltf file for the above program is a single-scene with a single empty in it.

{
  "asset": {
    "generator": "Khronos glTF Blender I/O v4.2.57",
    "version": "2.0"
  },
  "scene": 0,
  "scenes": [
    {
      "extras": {
        "skein": [
          {
            "api::MyRootMarker": {}
          }
        ]
      },
      "name": "Scene",
      "nodes": [0]
    }
  ],
  "nodes": [
    {
      "extras": {
        "skein": [
          {
            "api::Character": {
              "name": "Hollow Knight"
            }
          }
        ]
      },
      "name": "Empty"
    }
  ]
}

[ChristopherBiscardi]

and logs for the run look like this: (with the 0.17 DebugName spam removed). Not that MyRootMarker (from the gltf data) and SomethingElse (from the spawning logic) are both on the scene's root node. While additional scene components like Character still exist in the spawned scene children.

2025-11-21T21:12:36.217337Z  INFO bevy_ecs::system::commands::entity_command: Entity 35v0: [
 "bevy_transform::components::transform::Transform", 
 "bevy_transform::components::global_transform::GlobalTransform", 
 "bevy_transform::components::transform::TransformTreeChanged", 
 "bevy_camera::visibility::Visibility", 
 "bevy_camera::visibility::InheritedVisibility", 
 "bevy_camera::visibility::ViewVisibility", 
 "bevy_gltf::assets::GltfSceneExtras", 
 "bevy_ecs::hierarchy::Children", 
 "skein_scenespawner_test::MyRootMarker", 
 "skein_scenespawner_test::SomethingElse"
]
2025-11-21T21:12:36.217362Z  INFO bevy_ecs::system::commands::entity_command: Entity 34v0: [
 "bevy_transform::components::transform::Transform", 
 "bevy_transform::components::global_transform::GlobalTransform", 
 "bevy_transform::components::transform::TransformTreeChanged", 
 "bevy_camera::visibility::Visibility", 
 "bevy_camera::visibility::InheritedVisibility", 
 "bevy_camera::visibility::ViewVisibility", 
 "bevy_gltf::assets::GltfExtras", 
 "bevy_ecs::name::Name", 
 "skein_scenespawner_test::Character", 
 "bevy_ecs::hierarchy::ChildOf"
]