Struct GLTFSystem 

pub struct GLTFSystem { /* private fields */ }

Implementations

impl GLTFSystem

pub fn new() -> Self

pub fn register_component(&mut self, component_id: ComponentId)

pub fn tracked_components(&self) -> impl Iterator<Item = ComponentId> + '_

pub fn tracked_component_count(&self) -> usize

pub fn cached_resource_count(&self) -> usize

pub fn cached_mesh_count(&self) -> usize

pub fn cached_texture_count(&self) -> usize

pub fn cached_cpu_bytes(&self) -> usize

pub fn tick_with_queue( &mut self, world: &mut World, visuals: &mut VisualWorld, skinned_mesh: &mut SkinnedMeshSystem, emit: &mut dyn SignalEmitter, _dt_sec: f32, )

Discover GLTFComponents and spawn their node/renderable hierarchy.

This runs during SystemWorld::tick so we have access to a SignalEmitter via world.init_component_tree(..., emit).

Examples found in repository

examples/bisket-vr-debug.rs (lines 1113-1119)

fn tick_gltf(universe: &mut engine::Universe) {
    let systems = &mut universe.systems;
    systems.gltf.tick_with_queue(
        &mut universe.world,
        &mut universe.visuals,
        &mut systems.skinned_mesh,
        &mut universe.command_queue,
        0.0,
    );
}

examples/bisket-vr-demo.rs (lines 318-324)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();

    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);

    let output = scripting::MeowMeowRunner::eval_with_world_and_assets_at_path(
        include_str!("bisket-vr-demo.mms"),
        Some("examples/bisket-vr-demo.mms"),
        &mut universe.world,
        &mut universe.systems.rx,
        Some(&mut universe.render_assets),
        &mut universe.command_queue,
    );

    for error in &output.errors {
        eprintln!("[mms] {error}");
    }
    println!(
        "[mms] {} intent(s) from bisket-vr-demo.mms",
        output.intents.len()
    );

    let scope = engine::ecs::ComponentId::default();
    for intent in output.intents {
        universe.command_queue.push_intent_now(scope, intent);
    }

    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Force the glTF subtree to spawn so the armature exists before we query for
    // bone markers (otherwise the bone components aren't in the world yet).
    {
        let systems = &mut universe.systems;
        systems.gltf.tick_with_queue(
            &mut universe.world,
            &mut universe.visuals,
            &mut systems.skinned_mesh,
            &mut universe.command_queue,
            0.0,
        );
    }
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Find any global root to start the descendant search from. Scanning all
    // components is fine here — this only runs once at startup.
    let roots: Vec<engine::ecs::ComponentId> = universe
        .world
        .all_components()
        .filter(|&id| universe.world.parent_of(id).is_none())
        .collect();

    // ----------------------------------------------------------------------
    // Dump button — click to print a bone snapshot for offline analysis.
    //
    // Topology: scene_root → OV → button_t → button_r (+ C, EM, Raycastable).
    // OV phase so the cube is visible through the avatar body in first-person VR.
    // Click handler walks the cached bone list, prints world pos + segment
    // lengths to stdout.  Compare with bisket-vr-debug harness output.
    // ----------------------------------------------------------------------
    {
        // Resolve AVC + driven_t for the dump.
        let avc_id_opt = universe.world.all_components().find(|&id| {
            universe
                .world
                .get_component_by_id_as::<AvatarControlComponent>(id)
                .is_some()
        });
        if let Some(avc_id) = avc_id_opt {
            let driven_t = universe.world.parent_of(avc_id).unwrap_or(avc_id);
            let head_ik_offset_yaw = universe
                .world
                .get_component_by_id_as::<AvatarControlComponent>(avc_id)
                .map(|c| {
                    if c.forward_plus_z {
                        0.0
                    } else {
                        std::f32::consts::PI
                    }
                })
                .unwrap_or(std::f32::consts::PI);

            // Find each bone under any root (model_root is unique per avatar here).
            let mut bones: Vec<(String, ComponentId)> = Vec::new();
            for name in DUMP_BONES {
                let sel = format!("[name='{}']", name);
                if let Some(bone) = roots.iter().find_map(|&r| universe.find_component(r, &sel)) {
                    bones.push((name.to_string(), bone));
                } else {
                    eprintln!("[dump] bone not found: {}", name);
                }
            }
            // splice_head = parent of head bone (runtime-inserted by AVC).
            let splice_head = bones
                .iter()
                .find(|(n, _)| n == "J_Bip_C_Head")
                .and_then(|(_, head)| universe.world.parent_of(*head))
                .unwrap_or(avc_id);

            let head_bone = bones
                .iter()
                .find(|(n, _)| n == "J_Bip_C_Head")
                .map(|(_, id)| *id)
                .unwrap_or(splice_head);

            let upper_chest = bones
                .iter()
                .find(|(n, _)| n == "J_Bip_C_UpperChest")
                .map(|(_, id)| *id);

            // Find CameraXR + its transform wrapper to recover authored eye offset.
            let cxr_id = universe.world.all_components().find(|&cid| {
                universe
                    .world
                    .get_component_by_id_as::<mittens_engine::engine::ecs::component::CameraXRComponent>(cid)
                    .is_some()
            });
            let camera_wrapper_t = cxr_id.and_then(|cid| {
                universe.world.parent_of(cid).filter(|&p| {
                    universe
                        .world
                        .get_component_by_id_as::<TransformComponent>(p)
                        .is_some()
                })
            });
            let authored_eye_offset_head_local = camera_wrapper_t
                .and_then(|t| {
                    universe
                        .world
                        .get_component_by_id_as::<TransformComponent>(t)
                })
                .map(|t| t.transform.translation)
                .unwrap_or([0.0, 0.0, 0.0]);

            let _ = DUMP_TARGETS.set(DumpTargets {
                bones,
                driven_t,
                splice_head,
                head_bone,
                upper_chest,
                camera_wrapper_t,
                authored_eye_offset_head_local,
                head_ik_offset_yaw,
            });

            // Spawn the button.  Position chosen so it's reachable in-VR from
            // a standing pose: 0.35 m to the right, hip-height, slightly out.
            let btn_t = universe.world.add_component(
                TransformComponent::new()
                    .with_position(0.35, 1.05, -0.35)
                    .with_scale(0.06, 0.06, 0.06),
            );
            let btn_r = universe.world.add_component(RenderableComponent::cube());
            let btn_c = universe
                .world
                .add_component(ColorComponent::rgba(0.95, 0.20, 0.40, 1.0));
            let btn_em = universe.world.add_component(EmissiveComponent::on());
            let btn_rcast = universe
                .world
                .add_component(RaycastableComponent::enabled());
            let btn_ov = universe.world.add_component(OverlayComponent::new());
            let _ = universe.world.add_child(btn_r, btn_c);
            let _ = universe.world.add_child(btn_r, btn_em);
            let _ = universe.world.add_child(btn_r, btn_rcast);
            let _ = universe.world.add_child(btn_t, btn_r);
            let _ = universe.world.add_child(btn_ov, btn_t);

            // Attach to a stable scene root (the first global root we found).
            let scene_root = roots
                .iter()
                .copied()
                .find(|&r| {
                    universe
                        .world
                        .get_component_by_id_as::<TransformComponent>(r)
                        .is_some()
                        || universe.world.children_of(r).len() > 0
                })
                .unwrap_or_else(|| roots[0]);
            let _ = universe.attach(scene_root, btn_ov);

            // Wire Click handler.  Scope = the renderable (where the raycast hits).
            universe.add_signal_handler(SignalKind::Click, btn_r, on_dump_click);

            println!(
                "[dump] button spawned at [0.35, 1.05, -0.35] — click in VR or with desktop pointer to dump bones"
            );
        } else {
            eprintln!("[dump] AvatarControlComponent not found — skipping dump button");
        }
    }

    for kind in [
        SignalKind::DragStart,
        SignalKind::DragMove,
        SignalKind::DragEnd,
        SignalKind::Click,
    ] {
        universe
            .systems
            .rx
            .add_global_handler(kind, on_xr_pointer_event);
    }

    universe.enable_meow_meow_repl();
    engine::Windowing::run_app(universe).expect("Windowing failed");
}

examples/vr-input.rs (lines 434-440)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();

    let options = match parse_options() {
        Ok(options) => options,
        Err(message) => {
            eprintln!("{message}");
            std::process::exit(2);
        }
    };

    println!(
        "[vr-input] xr controller rotation filter pipeline: {}",
        if options.xr_controller_rotation_filter {
            "enabled"
        } else {
            "disabled"
        }
    );

    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);

    let renderer_settings = universe
        .world
        .add_component(RendererSettingsComponent::msaa_off().with_window_size(320, 240));
    universe.add(renderer_settings);

    let render_graph = universe.world.add_component(RenderGraphComponent::new());
    let emissive_pass = universe.world.add_component(EmissivePassComponent::new());
    let blur_pass = universe.world.add_component(
        BlurPassComponent::new()
            .with_radius_ndc(0.06)
            .with_half_res(true),
    );
    let bloom = universe.world.add_component(
        BloomComponent::new()
            .with_intensity(0.95)
            .with_emissive_scale(1.2),
    );
    let _ = universe.attach(emissive_pass, blur_pass);
    let _ = universe.attach(render_graph, emissive_pass);
    let _ = universe.attach(render_graph, bloom);
    universe.add(render_graph);

    // Sky base.
    let background = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let background_c = universe
        .world
        .add_component(ColorComponent::rgba(0.62, 0.80, 1.00, 1.0));
    let _ = universe.world.add_child(background, background_c);
    universe.add(background);

    // Lighting for the model.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.18, 0.18, 0.22));
    universe.add(ambient);

    let sun = universe.world.add_component(
        DirectionalLightComponent::new()
            .with_intensity(1.1)
            .with_color(1.0, 0.98, 0.95),
    );
    let sun_dir = universe
        .world
        .add_component(TransformComponent::new().with_position(0.15, -0.45, 1.0));
    let _ = universe.attach(sun_dir, sun);
    universe.add(sun_dir);

    // --- Desktop camera rig (for debugging while in VR) ---
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(1.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    let desktop_rig = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 1.2, 3.5));
    let _ = universe.attach(input, desktop_rig);

    let camera3d = universe.world.add_component(Camera3DComponent::new());
    let _ = universe.attach(desktop_rig, camera3d);

    let pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(camera3d, pointer);

    example_util::spawn_desktop_camera_controls_hint(&mut universe, desktop_rig);
    universe.add(input);

    // --- XR rig (Aim controller debug cubes only; camera has moved to AVC) ---
    let xr_input = universe.world.add_component(InputXRComponent::on());
    let xr_gamepad = universe.world.add_component(
        mittens_engine::engine::ecs::component::InputXRGamepadComponent::new().speed(1.5),
    );
    let xr_rig = universe.world.add_component(TransformComponent::new());
    let _ = universe.attach(xr_input, xr_rig);
    let _ = universe.attach(xr_input, xr_gamepad);

    // renderer stats
    let renderer_stats = universe
        .world
        .add_component(RendererStatsComponent::new().with_camera_target(CameraTarget::Xr));
    let render_stats_rig = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 1.85, 0.6));
    let _ = universe.attach(render_stats_rig, renderer_stats);
    let _ = universe.attach(xr_rig, render_stats_rig);

    universe.add(xr_input);

    // Background "skybox" content.
    spawn_sun_background(&mut universe);

    // --- VTuber model — single-input topology ---
    //
    // InputXRComponent drives body translation and head rotation through AvatarControlSystem.
    // AvatarControlSystem:
    //   - Splices a TransformComponent under J_Bip_C_Head's parent (the neck) to drive
    //     head rotation directly. Rotating the head — not the neck — isolates the spine
    //     so the torso doesn't twist with HMD yaw.
    //   - Strips rotation from model_root (body faces body_yaw, not raw HMD yaw).
    //   - Bakes the π Y handedness correction into the head rotation math.
    //   - Smoothly rotates body to follow head when yaw delta exceeds threshold.
    //   - Measures J_Bip_C_Head local Y in the rest pose and sets model_root.y = -bone_local_y,
    //     so the head bone sits at driven_t world Y (= HMD height) with no hardcoded constant.
    //   - Re-parents CameraXRComponent under J_Bip_C_Head for first-person alignment.
    //
    // Topology (after AVC init):
    //   editor_root
    //     └── avatar_input_xr (InputXRComponent)
    //           └── avatar_driven_t (TransformComponent)
    //                 └── AvatarControlComponent
    //                       ├── body_pipeline → pipeline_output
    //                       │     └── model_root (y auto-calibrated from J_Bip_C_Head)
    //                       │           └── GLTFComponent → ... → J_Bip_C_Head
    //                       │                                           └── CameraXRComponent
    //                       ├── CTLXR(Left, Grip) → re-parented to lower_arm
    //                       └── CTLXR(Right, Grip) → re-parented to lower_arm

    let editor_root = universe.world.add_component(EditorComponent::new());

    let avatar_input_xr = universe.world.add_component(InputXRComponent::on());
    let avatar_xr_gamepad = universe.world.add_component(
        mittens_engine::engine::ecs::component::InputXRGamepadComponent::new().speed(1.5),
    );
    let avatar_driven_t = universe.world.add_component(TransformComponent::new());
    let _ = universe.attach(avatar_input_xr, avatar_driven_t);
    let _ = universe.attach(avatar_input_xr, avatar_xr_gamepad);

    // AvatarControlComponent: -Z forward (OpenXR default), body starts facing -Z (π yaw).
    // camera_bone triggers auto-calibration of model_root.y from J_Bip_C_Head rest pose height,
    // and causes any CameraXR/Camera3D direct children of AVC to be re-parented to that bone.
    let avatar_control = universe.world.add_component(
        AvatarControlComponent::new()
            .with_head_bone("J_Bip_C_Head")
            .with_camera_bone("J_Bip_C_Head")
            .with_left_hand_bone("J_Bip_L_Hand")
            .with_right_hand_bone("J_Bip_R_Hand")
            .with_initial_yaw(std::f32::consts::PI)
            .with_hand_rotation_smoothing(220.0),
    );
    let _ = universe.attach(avatar_driven_t, avatar_control);

    // CameraXR as a direct child of AVC — discovered and re-parented to J_Bip_C_Head at init.
    let camera_xr = universe.world.add_component(CameraXRComponent::on());
    let _ = universe.attach(avatar_control, camera_xr);
    let head_pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(camera_xr, head_pointer);

    // Grip controllers for hand bone splicing — children of AvatarControlComponent so
    // AvatarControlSystem discovers them by topology. Each needs a TransformComponent
    // child (driven_t) that OpenXRSystem writes each tick.
    let left_grip = universe.world.add_component(ControllerXRComponent::new(
        true,
        ControllerHand::Left,
        ControllerPoseKind::Grip,
    ));
    let left_grip_t = universe.world.add_component(TransformComponent::new());
    let _ = universe.attach(left_grip, left_grip_t);
    let left_pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(left_grip_t, left_pointer);
    let _ = universe.attach(avatar_control, left_grip);

    let right_grip = universe.world.add_component(ControllerXRComponent::new(
        true,
        ControllerHand::Right,
        ControllerPoseKind::Grip,
    ));
    let right_grip_t = universe.world.add_component(TransformComponent::new());
    let _ = universe.attach(right_grip, right_grip_t);
    let right_pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(right_grip_t, right_pointer);
    let _ = universe.attach(avatar_control, right_grip);

    // model_root: no explicit Y offset — AvatarControlSystem calibrates it from J_Bip_C_Head.
    let model_root = universe.world.add_component(TransformComponent::new());
    let model = universe
        .world
        .add_component(GLTFComponent::new("assets/models/pc-rei.hoodie.glb"));
    let emissive = universe.world.add_component(EmissiveComponent::on());
    let _ = universe.attach(model, emissive);

    let _ = universe.attach(editor_root, avatar_input_xr);
    let _ = universe.attach(avatar_control, model_root);
    let _ = universe.attach(model_root, model);
    universe.add(editor_root);

    // --- Controller debug cubes (tracked poses) ---
    let _left = spawn_controller_cube(
        &mut universe,
        xr_rig,
        ControllerHand::Left,
        (0.10, 0.90, 1.00, 1.0),
        220.0,
        options.xr_controller_rotation_filter,
    );
    let _right = spawn_controller_cube(
        &mut universe,
        xr_rig,
        ControllerHand::Right,
        (1.00, 0.35, 0.35, 1.0),
        220.0,
        options.xr_controller_rotation_filter,
    );

    // Enable OpenXR runtime.
    let xr_root = universe.world.add_component(XrComponent::on());
    universe.add(xr_root);

    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Force the glTF subtree to spawn so we can query the armature for bone markers.
    {
        let systems = &mut universe.systems;
        systems.gltf.tick_with_queue(
            &mut universe.world,
            &mut universe.visuals,
            &mut systems.skinned_mesh,
            &mut universe.command_queue,
            0.0,
        );
    }
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Bone markers for editor inspection.
    let marker_joints: &[(&str, (f32, f32, f32, f32))] = &[
        ("[name='J_Bip_C_Head']", (0.85, 0.20, 0.85, 0.9)),
        ("[name='J_Bip_C_Neck']", (0.20, 0.85, 0.85, 0.9)),
        ("[name='J_Bip_C_UpperChest']", (0.20, 0.20, 0.85, 0.9)),
        ("[name='J_Bip_L_UpperArm']", (0.85, 0.85, 0.20, 0.9)),
        ("[name='J_Bip_R_UpperArm']", (0.85, 0.60, 0.20, 0.9)),
    ];

    for &(selector, color) in marker_joints {
        let Some(bone) = universe.find_component(model_root, selector) else {
            continue;
        };
        let marker_t = universe
            .world
            .add_component(TransformComponent::new().with_scale(0.025, 0.025, 0.025));
        let marker_r = universe.world.add_component(RenderableComponent::cube());
        let marker_c = universe
            .world
            .add_component(ColorComponent::rgba(color.0, color.1, color.2, color.3));
        let marker_rcast = universe
            .world
            .add_component(RaycastableComponent::enabled());
        let _ = universe.world.add_child(marker_r, marker_c);
        let _ = universe.world.add_child(marker_r, marker_rcast);
        let _ = universe.world.add_child(marker_t, marker_r);
        let _ = universe.attach(bone, marker_t);
    }

    universe.enable_repl();
    engine::Windowing::run_app(universe).expect("Windowing failed");
}

examples/vtuber-joints-example.rs (lines 284-290)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();

    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);

    // Slow the global beat clock so beat-based animations run half as fast.
    let clock = universe
        .world
        .add_component(ClockComponent::new().with_bpm(60.0));
    universe.add(clock);

    // Light pink background.
    let background = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let background_c = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 0.82, 0.90, 1.0));
    let _ = universe.world.add_child(background, background_c);
    universe.add(background);

    // Small ambient so shadowed areas aren't pure black.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.10, 0.10, 0.12));
    universe.add(ambient);

    // --- Camera rig (WASD + mouse) ---
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(1.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    // Start slightly pulled back looking towards the origin.
    let rig_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 6.0));
    let _ = universe.attach(input, rig_transform);

    let camera3d = universe.world.add_component(Camera3DComponent::new());
    let _ = universe.attach(rig_transform, camera3d);

    // Pointer so gizmos can be interacted with.
    let pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(camera3d, pointer);

    // Topology: I { T { C3D } } — add a small camera-attached controls hint.
    example_util::spawn_desktop_camera_controls_hint(&mut universe, rig_transform);

    universe.add(input);

    // --- lighting ---
    let sun = universe.world.add_component(
        DirectionalLightComponent::new()
            .with_intensity(1.2)
            .with_color(1.0, 0.98, 0.94),
    );
    let sun_dir = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -0.35, 1.0));
    let _ = universe.attach(sun_dir, sun);
    universe.add(sun_dir);

    let light_transform = universe.world.add_component(
        TransformComponent::new()
            .with_position(1.0, 6.0, 3.0)
            .with_scale(0.1, 0.1, 0.1),
    );
    let light = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(120.0)
            .with_color(1.0, 1.0, 1.0),
    );
    let _ = universe.attach(light_transform, light);
    universe.add(light_transform);

    // --- VTuber model ---
    let model_uri = "assets/models/pc-rei.hoodie.glb";

    // Wrap the model subtree in an editor root so transform-only glTF nodes can be visualized
    // (and thus raycasted/selected) without affecting non-editor scenes.
    let editor_root = universe.world.add_component(EditorComponent::new());

    let model_root = universe.world.add_component(TransformComponent::new());
    let model = universe.world.add_component(GLTFComponent::new(model_uri));

    // emissive for pc-rei
    let emissive = universe.world.add_component(EmissiveComponent::on());
    let _ = universe.attach(model, emissive);

    let xr_input = universe.world.add_component(InputXRComponent::on());
    let xr_gamepad = universe
        .world
        .add_component(engine::ecs::component::InputXRGamepadComponent::new().speed(1.5));
    let xr_head = universe.world.add_component(TransformComponent::new());
    let xr_camera = universe.world.add_component(CameraXRComponent::on());
    let _ = universe.attach(xr_input, xr_head);
    let _ = universe.attach(xr_input, xr_gamepad);
    let _ = universe.attach(xr_head, xr_camera);
    let xr_pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(xr_camera, xr_pointer);
    let _ = universe.attach(xr_head, editor_root);

    let _ = universe.attach(model_root, model);

    let _ = universe.attach(editor_root, model_root);

    // Initialize the editor root so GLTFComponent gets registered.
    universe.add(xr_input);
    universe.add(editor_root);

    // --- Background clouds (occluded + lit) ---
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);
    let mut cloud_params = example_util::CloudRingParams::default();
    cloud_params.cloud_count = 8; // +3 clusters
    cloud_params.angle_jitter = 0.35;
    cloud_params.high_y_probability = 0.5;
    cloud_params.high_y_multiplier = 1.5;
    cloud_params.seed = 0x57_55_B0_01u32;
    example_util::spawn_cloud_ring(&mut universe, bg_root, cloud_params);

    // --- Simple environment ---
    let spawn_cube = |universe: &mut engine::Universe,
                      position: (f32, f32, f32),
                      scale: (f32, f32, f32),
                      color: (f32, f32, f32, f32)| {
        let transform = universe.world.add_component(
            TransformComponent::new()
                .with_position(position.0, position.1, position.2)
                .with_scale(scale.0, scale.1, scale.2),
        );
        let renderable = universe.world.add_component(RenderableComponent::cube());
        let color = universe
            .world
            .add_component(ColorComponent::rgba(color.0, color.1, color.2, color.3));

        let _ = universe.attach(transform, renderable);
        let _ = universe.attach(renderable, color);

        universe.add(transform);
    };

    // floor
    spawn_cube(
        &mut universe,
        (0.0, -0.05, 0.0),
        (10.0, 0.1, 10.0),
        (0.92, 0.92, 0.92, 1.0),
    );

    // back wall
    spawn_cube(
        &mut universe,
        (-3.0, 1.5, -5.0),
        (3.0, 3.0, 1.0),
        (0.95, 0.94, 0.96, 1.0),
    );

    // desk
    spawn_cube(
        &mut universe,
        (0.0, 0.35, 1.0),
        (1.0, 0.75, 0.5),
        (0.75, 0.70, 0.65, 1.0),
    );

    // --- Editor-side stacked cubes (inside the editor subtree for picking/gizmos) ---
    {
        let spawn_editor_cube = |universe: &mut engine::Universe,
                                 editor_root: engine::ecs::ComponentId,
                                 name: &str,
                                 position: (f32, f32, f32),
                                 scale: (f32, f32, f32),
                                 color: (f32, f32, f32, f32)| {
            let transform = universe.world.add_component_boxed_named(
                format!("{name}_t"),
                Box::new(
                    TransformComponent::new()
                        .with_position(position.0, position.1, position.2)
                        .with_scale(scale.0, scale.1, scale.2),
                ),
            );
            let renderable = universe.world.add_component_boxed_named(
                format!("{name}_r"),
                Box::new(RenderableComponent::cube()),
            );
            let color_comp = universe.world.add_component_boxed_named(
                format!("{name}_color"),
                Box::new(ColorComponent::rgba(color.0, color.1, color.2, color.3)),
            );
            let raycastable = universe.world.add_component_boxed_named(
                format!("{name}_raycastable"),
                Box::new(RaycastableComponent::enabled()),
            );

            let _ = universe.world.add_child(transform, renderable);
            let _ = universe.world.add_child(renderable, color_comp);
            let _ = universe.world.add_child(renderable, raycastable);

            // One attach into the initialized editor subtree triggers init for the new subtree.
            let _ = universe.attach(editor_root, transform);
        };

        // Place the stack beside the desk (a bit to the right).
        let stack_x = 1.35;
        let stack_z = 1.0;
        let s = 0.25;
        let half = 0.5 * s;
        let light_brown = (0.80, 0.72, 0.55, 1.0);
        let cyan = (0.20, 1.00, 1.00, 1.0);

        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_0",
            (stack_x, half, stack_z),
            (s, s, s),
            light_brown,
        );
        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_1",
            (stack_x, half + 1.0 * s, stack_z),
            (s, s, s),
            light_brown,
        );
        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_2",
            (stack_x, half + 2.0 * s, stack_z),
            (s, s, s),
            light_brown,
        );
        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_top",
            (stack_x, half + 3.0 * s, stack_z),
            (s, s, s),
            cyan,
        );
    }

    let xr_root = universe
        .world
        .add_component(engine::ecs::component::XrComponent::on());
    universe.add(xr_root);

    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Spawn the glTF subtree once up-front so joint ComponentIds exist.
    {
        let systems = &mut universe.systems;
        systems.gltf.tick_with_queue(
            &mut universe.world,
            &mut universe.visuals,
            &mut systems.skinned_mesh,
            &mut universe.command_queue,
            0.0,
        );
    }
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Register imported meshes into RenderAssets early so we can inspect skin weights
    // (textures will still be uploaded later during normal rendering).
    universe
        .systems
        .gltf
        .flush_mesh_imports_only(&mut universe.render_assets);

    // --- Joint printout + animation binding (in the example) ---
    let all_joints = collect_joint_transforms(
        &universe.world,
        &universe.systems.skinned_mesh,
        &universe.visuals,
        model,
        model_root,
    );
    println!("[vtuber-joints-example] joints found: {}", all_joints.len());
    for (i, (node_index, joint_tx)) in all_joints.iter().enumerate() {
        println!("  joint[{i:03}] node_index={node_index} transform={joint_tx:?}");
    }

    let node_index_to_transform: HashMap<usize, engine::ecs::ComponentId> =
        all_joints.iter().copied().collect();

    // Example settings are hardcoded to keep this example simple.
    let joint_offset: usize = 0;
    let wiggle_count: usize = 16;

    let target_mesh_key = "pc-rei.hoodie:Body_(merged).baked:prim0".to_string();
    let target_joint_names: Vec<String> = vec![
        "J_Bip_L_UpperArm".to_string(),
        "J_Bip_R_UpperArm".to_string(),
    ];

    let print_transform_updates: bool = false;

    let selected_joint_transforms: Vec<(usize, engine::ecs::ComponentId)> =
        select_named_joints(&universe.world, &all_joints, &target_joint_names)
            .or_else(|| {
                select_body_prim0_influencers(
                    &universe,
                    model_root,
                    &target_mesh_key,
                    wiggle_count,
                    &node_index_to_transform,
                )
            })
            .unwrap_or_else(|| select_joint_range(&all_joints, joint_offset, wiggle_count));
    println!(
        "[vtuber-joints-example] wiggle selection: target_mesh_key='{}' offset={} count={} selected={}",
        target_mesh_key,
        joint_offset,
        wiggle_count,
        selected_joint_transforms.len()
    );

    debug_print_selected_joint_influence(
        &universe,
        &target_mesh_key,
        model_root,
        &selected_joint_transforms,
    );

    println!("[vtuber-joints-example] selected joints:");
    for (i, (node_index, joint_tx)) in selected_joint_transforms.iter().enumerate() {
        let name = universe
            .world
            .get_component_record(*joint_tx)
            .map(|n| n.name.as_str())
            .unwrap_or("<unknown>");
        println!("  sel[{i:02}] node_index={node_index} name={name} transform={joint_tx:?}");
    }

    if print_transform_updates {
        println!("[vtuber-joints-example] note: joint animation disabled");
    }

    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    universe.enable_repl();
    engine::Windowing::run_app(universe).expect("Windowing failed");
}

pub fn flush_imports( &mut self, render_assets: &mut RenderAssets, texture_system: &mut TextureSystem, uploader: &mut dyn RenderUploader, )

pub fn flush_mesh_imports_only(&mut self, render_assets: &mut RenderAssets)

Register imported CPU meshes into RenderAssets without uploading textures.

This is useful for headless/early inspection (e.g. examples that want to analyze JOINTS_0/WEIGHTS_0) before a renderer is initialized.

Examples found in repository

examples/vtuber-joints-example.rs (line 304)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();

    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);

    // Slow the global beat clock so beat-based animations run half as fast.
    let clock = universe
        .world
        .add_component(ClockComponent::new().with_bpm(60.0));
    universe.add(clock);

    // Light pink background.
    let background = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let background_c = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 0.82, 0.90, 1.0));
    let _ = universe.world.add_child(background, background_c);
    universe.add(background);

    // Small ambient so shadowed areas aren't pure black.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.10, 0.10, 0.12));
    universe.add(ambient);

    // --- Camera rig (WASD + mouse) ---
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(1.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    // Start slightly pulled back looking towards the origin.
    let rig_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 6.0));
    let _ = universe.attach(input, rig_transform);

    let camera3d = universe.world.add_component(Camera3DComponent::new());
    let _ = universe.attach(rig_transform, camera3d);

    // Pointer so gizmos can be interacted with.
    let pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(camera3d, pointer);

    // Topology: I { T { C3D } } — add a small camera-attached controls hint.
    example_util::spawn_desktop_camera_controls_hint(&mut universe, rig_transform);

    universe.add(input);

    // --- lighting ---
    let sun = universe.world.add_component(
        DirectionalLightComponent::new()
            .with_intensity(1.2)
            .with_color(1.0, 0.98, 0.94),
    );
    let sun_dir = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -0.35, 1.0));
    let _ = universe.attach(sun_dir, sun);
    universe.add(sun_dir);

    let light_transform = universe.world.add_component(
        TransformComponent::new()
            .with_position(1.0, 6.0, 3.0)
            .with_scale(0.1, 0.1, 0.1),
    );
    let light = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(120.0)
            .with_color(1.0, 1.0, 1.0),
    );
    let _ = universe.attach(light_transform, light);
    universe.add(light_transform);

    // --- VTuber model ---
    let model_uri = "assets/models/pc-rei.hoodie.glb";

    // Wrap the model subtree in an editor root so transform-only glTF nodes can be visualized
    // (and thus raycasted/selected) without affecting non-editor scenes.
    let editor_root = universe.world.add_component(EditorComponent::new());

    let model_root = universe.world.add_component(TransformComponent::new());
    let model = universe.world.add_component(GLTFComponent::new(model_uri));

    // emissive for pc-rei
    let emissive = universe.world.add_component(EmissiveComponent::on());
    let _ = universe.attach(model, emissive);

    let xr_input = universe.world.add_component(InputXRComponent::on());
    let xr_gamepad = universe
        .world
        .add_component(engine::ecs::component::InputXRGamepadComponent::new().speed(1.5));
    let xr_head = universe.world.add_component(TransformComponent::new());
    let xr_camera = universe.world.add_component(CameraXRComponent::on());
    let _ = universe.attach(xr_input, xr_head);
    let _ = universe.attach(xr_input, xr_gamepad);
    let _ = universe.attach(xr_head, xr_camera);
    let xr_pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(xr_camera, xr_pointer);
    let _ = universe.attach(xr_head, editor_root);

    let _ = universe.attach(model_root, model);

    let _ = universe.attach(editor_root, model_root);

    // Initialize the editor root so GLTFComponent gets registered.
    universe.add(xr_input);
    universe.add(editor_root);

    // --- Background clouds (occluded + lit) ---
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);
    let mut cloud_params = example_util::CloudRingParams::default();
    cloud_params.cloud_count = 8; // +3 clusters
    cloud_params.angle_jitter = 0.35;
    cloud_params.high_y_probability = 0.5;
    cloud_params.high_y_multiplier = 1.5;
    cloud_params.seed = 0x57_55_B0_01u32;
    example_util::spawn_cloud_ring(&mut universe, bg_root, cloud_params);

    // --- Simple environment ---
    let spawn_cube = |universe: &mut engine::Universe,
                      position: (f32, f32, f32),
                      scale: (f32, f32, f32),
                      color: (f32, f32, f32, f32)| {
        let transform = universe.world.add_component(
            TransformComponent::new()
                .with_position(position.0, position.1, position.2)
                .with_scale(scale.0, scale.1, scale.2),
        );
        let renderable = universe.world.add_component(RenderableComponent::cube());
        let color = universe
            .world
            .add_component(ColorComponent::rgba(color.0, color.1, color.2, color.3));

        let _ = universe.attach(transform, renderable);
        let _ = universe.attach(renderable, color);

        universe.add(transform);
    };

    // floor
    spawn_cube(
        &mut universe,
        (0.0, -0.05, 0.0),
        (10.0, 0.1, 10.0),
        (0.92, 0.92, 0.92, 1.0),
    );

    // back wall
    spawn_cube(
        &mut universe,
        (-3.0, 1.5, -5.0),
        (3.0, 3.0, 1.0),
        (0.95, 0.94, 0.96, 1.0),
    );

    // desk
    spawn_cube(
        &mut universe,
        (0.0, 0.35, 1.0),
        (1.0, 0.75, 0.5),
        (0.75, 0.70, 0.65, 1.0),
    );

    // --- Editor-side stacked cubes (inside the editor subtree for picking/gizmos) ---
    {
        let spawn_editor_cube = |universe: &mut engine::Universe,
                                 editor_root: engine::ecs::ComponentId,
                                 name: &str,
                                 position: (f32, f32, f32),
                                 scale: (f32, f32, f32),
                                 color: (f32, f32, f32, f32)| {
            let transform = universe.world.add_component_boxed_named(
                format!("{name}_t"),
                Box::new(
                    TransformComponent::new()
                        .with_position(position.0, position.1, position.2)
                        .with_scale(scale.0, scale.1, scale.2),
                ),
            );
            let renderable = universe.world.add_component_boxed_named(
                format!("{name}_r"),
                Box::new(RenderableComponent::cube()),
            );
            let color_comp = universe.world.add_component_boxed_named(
                format!("{name}_color"),
                Box::new(ColorComponent::rgba(color.0, color.1, color.2, color.3)),
            );
            let raycastable = universe.world.add_component_boxed_named(
                format!("{name}_raycastable"),
                Box::new(RaycastableComponent::enabled()),
            );

            let _ = universe.world.add_child(transform, renderable);
            let _ = universe.world.add_child(renderable, color_comp);
            let _ = universe.world.add_child(renderable, raycastable);

            // One attach into the initialized editor subtree triggers init for the new subtree.
            let _ = universe.attach(editor_root, transform);
        };

        // Place the stack beside the desk (a bit to the right).
        let stack_x = 1.35;
        let stack_z = 1.0;
        let s = 0.25;
        let half = 0.5 * s;
        let light_brown = (0.80, 0.72, 0.55, 1.0);
        let cyan = (0.20, 1.00, 1.00, 1.0);

        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_0",
            (stack_x, half, stack_z),
            (s, s, s),
            light_brown,
        );
        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_1",
            (stack_x, half + 1.0 * s, stack_z),
            (s, s, s),
            light_brown,
        );
        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_2",
            (stack_x, half + 2.0 * s, stack_z),
            (s, s, s),
            light_brown,
        );
        spawn_editor_cube(
            &mut universe,
            editor_root,
            "editor_stack_top",
            (stack_x, half + 3.0 * s, stack_z),
            (s, s, s),
            cyan,
        );
    }

    let xr_root = universe
        .world
        .add_component(engine::ecs::component::XrComponent::on());
    universe.add(xr_root);

    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Spawn the glTF subtree once up-front so joint ComponentIds exist.
    {
        let systems = &mut universe.systems;
        systems.gltf.tick_with_queue(
            &mut universe.world,
            &mut universe.visuals,
            &mut systems.skinned_mesh,
            &mut universe.command_queue,
            0.0,
        );
    }
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    // Register imported meshes into RenderAssets early so we can inspect skin weights
    // (textures will still be uploaded later during normal rendering).
    universe
        .systems
        .gltf
        .flush_mesh_imports_only(&mut universe.render_assets);

    // --- Joint printout + animation binding (in the example) ---
    let all_joints = collect_joint_transforms(
        &universe.world,
        &universe.systems.skinned_mesh,
        &universe.visuals,
        model,
        model_root,
    );
    println!("[vtuber-joints-example] joints found: {}", all_joints.len());
    for (i, (node_index, joint_tx)) in all_joints.iter().enumerate() {
        println!("  joint[{i:03}] node_index={node_index} transform={joint_tx:?}");
    }

    let node_index_to_transform: HashMap<usize, engine::ecs::ComponentId> =
        all_joints.iter().copied().collect();

    // Example settings are hardcoded to keep this example simple.
    let joint_offset: usize = 0;
    let wiggle_count: usize = 16;

    let target_mesh_key = "pc-rei.hoodie:Body_(merged).baked:prim0".to_string();
    let target_joint_names: Vec<String> = vec![
        "J_Bip_L_UpperArm".to_string(),
        "J_Bip_R_UpperArm".to_string(),
    ];

    let print_transform_updates: bool = false;

    let selected_joint_transforms: Vec<(usize, engine::ecs::ComponentId)> =
        select_named_joints(&universe.world, &all_joints, &target_joint_names)
            .or_else(|| {
                select_body_prim0_influencers(
                    &universe,
                    model_root,
                    &target_mesh_key,
                    wiggle_count,
                    &node_index_to_transform,
                )
            })
            .unwrap_or_else(|| select_joint_range(&all_joints, joint_offset, wiggle_count));
    println!(
        "[vtuber-joints-example] wiggle selection: target_mesh_key='{}' offset={} count={} selected={}",
        target_mesh_key,
        joint_offset,
        wiggle_count,
        selected_joint_transforms.len()
    );

    debug_print_selected_joint_influence(
        &universe,
        &target_mesh_key,
        model_root,
        &selected_joint_transforms,
    );

    println!("[vtuber-joints-example] selected joints:");
    for (i, (node_index, joint_tx)) in selected_joint_transforms.iter().enumerate() {
        let name = universe
            .world
            .get_component_record(*joint_tx)
            .map(|n| n.name.as_str())
            .unwrap_or("<unknown>");
        println!("  sel[{i:02}] node_index={node_index} name={name} transform={joint_tx:?}");
    }

    if print_transform_updates {
        println!("[vtuber-joints-example] note: joint animation disabled");
    }

    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    universe.enable_repl();
    engine::Windowing::run_app(universe).expect("Windowing failed");
}

Trait Implementations

impl Debug for GLTFSystem

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for GLTFSystem

fn default() -> GLTFSystem

Returns the “default value” for a type.

impl System for GLTFSystem

fn tick( &mut self, _world: &mut World, _visuals: &mut VisualWorld, _input: &InputState, _dt_sec: f32, )