Struct AvatarControlComponent 

pub struct AvatarControlComponent {

    pub head_bone: String,
    pub left_hand_bone: Option<String>,
    pub right_hand_bone: Option<String>,
    pub left_upper_arm_bone: Option<String>,
    pub left_lower_arm_bone: Option<String>,
    pub right_upper_arm_bone: Option<String>,
    pub right_lower_arm_bone: Option<String>,
    pub left_arm_pole_direction: [f32; 3],
    pub right_arm_pole_direction: [f32; 3],
    pub body_yaw_threshold: f32,
    pub body_yaw_rate: f32,
    pub forward_plus_z: bool,
    pub forward_plus_z_overridden: bool,
    pub initial_body_yaw: f32,
    pub initial_body_yaw_overridden: bool,
    pub hand_rotation_smoothing: Option<f32>,
    pub camera_bone: Option<String>,
    pub avatar_height: Option<f32>,
    pub hips_bone: Option<String>,
    pub eye_height_from_head_bone: Option<f32>,
    pub head_ik_eye_height: Option<f32>,
    pub hand_grip_rotation_left: Option<[f32; 4]>,
    pub hand_grip_rotation_right: Option<[f32; 4]>,
    pub calibrate_hand_transforms: bool,
    pub skip_body_pipeline: bool,
    pub ik_debug: bool,
    pub neck_bone: Option<String>,
    /* private fields */
}

Coordinates all pose drivers for a humanoid avatar.

Design rule: every transform driver that moves this avatar’s bones must be a child of (or otherwise routed through) this component. This includes the primary body/head driver (Input / InputXR) and any hand controllers (ControllerXR). Uncoordinated drivers that bypass this component and write directly to armature bones are the root cause of the torso-rotation bug in the old two-input design.

Multiple drivers are fine; what matters is that they all appear in this node’s subtree so AvatarControlSystem can discover and route them during init.

Controller discovery

Hand controllers are discovered automatically by topology: any ControllerXRComponent that is a direct child of this component is registered as a hand driver. Its hand field (Left / Right) determines which hand bone it drives. The bone is displaced under the controller’s first TransformComponent child (the driven transform written by OpenXRSystem).

If no controller is present for a configured hand bone, a plain TransformComponent splice is inserted instead (for IK-only or static setups).

Topology (after init)

Input  (or  InputXR)                    ← primary driver
  └── driven_t
        └── AvatarControlComponent
              ├── model_root  (TransformComponent, Y offset)
              │     └── GLTFComponent
              │           └── [armature]
              │                 J_Bip_C_Neck
              │                   └── splice_head  ← injected by system
              │                         └── J_Bip_C_Head (displaced; aim-driven by driven_t)
              │                 left_lower_arm
              │                   └── ControllerXR (Left, Grip)  ← moved here by system
              │                         └── controller_driven_t
              │                               └── J_Bip_L_Hand (displaced)
              │                 right_lower_arm
              │                   └── ControllerXR (Right, Grip)
              │                         └── controller_driven_t
              │                               └── J_Bip_R_Hand (displaced)
              ├── ControllerXR (Left,  Grip) { T }  ← declared here; re-parented on init
              └── ControllerXR (Right, Grip) { T }

Fields

head_bone: String

Name of the bone to displace for head rotation. Default: “J_Bip_C_Head”.

This bone receives the HMD/Input world rotation directly via an AimConstraint IK chain. Rotating the head bone (not the neck) is critical for VR/desktop: rotating the neck twists the entire torso from the neck up, which looks wrong. The head’s rotation is isolated from the spine so the body can yaw-follow underneath independently.

left_hand_bone: Option<String>

Name of the left hand bone to splice. None = no left hand splice.

right_hand_bone: Option<String>

Name of the right hand bone to splice. None = no right hand splice.

left_upper_arm_bone: Option<String>

Explicit left upper arm bone name for TwoBoneIK. If None and left_hand_bone is set, topology derivation fills it in.

left_lower_arm_bone: Option<String>

Explicit left lower arm bone name for TwoBoneIK. If None and left_hand_bone is set, topology derivation fills it in.

right_upper_arm_bone: Option<String>

Explicit right upper arm bone name for TwoBoneIK. If None and right_hand_bone is set, topology derivation fills it in.

right_lower_arm_bone: Option<String>

Explicit right lower arm bone name for TwoBoneIK. If None and right_hand_bone is set, topology derivation fills it in.

left_arm_pole_direction: [f32; 3]

Body-local pole hint for the left elbow in the 2-bone arm IK solve. Transformed to world-space each tick by the solver using the model root rotation, so the elbow stays anatomically correct when the body turns. Default [-1, 0, -1] (elbow out + slightly back).

right_arm_pole_direction: [f32; 3]

Body-local pole hint for the right elbow in the 2-bone arm IK solve. Transformed to world-space each tick by the solver using the model root rotation, so the elbow stays anatomically correct when the body turns. Default [1, 0, -1].

body_yaw_threshold: f32

Yaw delta (radians) that triggers body rotation. Default: π/4 (45°).

body_yaw_rate: f32

Body rotation rate (radians/sec). Default: 3.0.

forward_plus_z: bool

Use +Z as the authored forward axis override.

When not explicitly overridden, AVC keeps the shared XR-style default (false) for both desktop and XR. This override remains available for assets that were authored with a different convention.

forward_plus_z_overridden: bool

Whether forward_plus_z was explicitly authored as an override.

initial_body_yaw: f32

Initial body yaw (radians) seeded into the YawFollow pipeline op.

When not explicitly overridden, AVC uses the shared default π.

initial_body_yaw_overridden: bool

Whether initial_body_yaw was explicitly authored as an override.

hand_rotation_smoothing: Option<f32>

Optional rotation smoothing for hand pose drivers (ControllerXR etc.). Applied to the rotation channel of each discovered hand driver’s pipeline. Equivalent to QuatTemporalFilter smoothing_factor. None = no smoothing pipeline.

camera_bone: Option<String>

Bone used as the camera anchor and as the source for auto-calibrating model_root.y.

When set, AvatarControlSystem will:

1. Measure this bone’s local Y height above model_root in the GLTF rest pose.
2. Override model_root’s Y translation to -bone_local_y, so the bone sits exactly at driven_t’s world position (= HMD height in XR; body origin on desktop).
3. Re-parent any Camera3DComponent or CameraXRComponent direct children of this AVC under this bone, giving them the bone’s world transform each tick.

Typically the same as head_bone (e.g. "J_Bip_C_Head") so the camera inherits both the head’s world position (eye height) and rotation. If None, no auto-calibration or camera re-parenting is performed.

avatar_height: Option<f32>

Explicit avatar height (metres) used to set model_root.y = -avatar_height. Overrides the camera_bone auto-calibration if both are set. Use this when the camera bone lookup fails or the mesh height is known in advance.

hips_bone: Option<String>

Name of the hips bone — the FABRIK spine chain root. Default: "J_Bip_C_Hips".

Resolved against model_root once during try_init_splices. If None or not found, no spine FABRIK chain is wired — head bone falls back to FK (visible detachment from neck under pitch).

eye_height_from_head_bone: Option<f32>

Vertical distance (metres) from the head bone pivot to the eyes.

VRM J_Bip_C_Head pivot sits at the skull base; the eye line is typically ~0.08 m above that. When this is set, AVC shifts model_root.y down by this amount so the EYES (not the bone pivot) land at driven_t’s world Y — i.e. at HMD height in VR, or at the desktop input height.

Without this, the avatar’s eyes sit above the HMD eye position and the face/hair mesh swings into the XR camera frustum when pitching down.

Applies on top of either camera_bone auto-calibration or avatar_height override. Default: None (no adjustment).

head_ik_eye_height: Option<f32>

Vertical offset (metres) used exclusively for the head IK target calculation.

This is decoupled from the camera position transform (T { CXR } wrapper) so the camera can be positioned freely without affecting how the FABRIK solver bends the spine. Typically set to a small value like 0.04–0.08 to account for the gap between the head bone pivot and the eye position, causing the spine to bend so the head lands at the right height relative to the HMD.

When set, the FABRIK target_position_offset uses this value (Y-only) instead of reading the camera transform’s translation. If None, no offset is applied to the IK target (the head bone pivot chases the HMD position directly). Default: None.

hand_grip_rotation_left: Option<[f32; 4]>

Local-space rotation offset applied to the left hand IK target (after grip pose).

Use this to correct for the gap between how the runtime reports grip orientation and what the armature expects for the hand bone. For standard VRM rigs with Vive-family controllers, quat_rotation_y(PI/2) (90° CW from above) is typical. None = no offset (raw grip pose drives the hand bone directly).

hand_grip_rotation_right: Option<[f32; 4]>

Local-space rotation offset applied to the right hand IK target (after grip pose).

For standard VRM rigs with Vive-family controllers, quat_rotation_y(-PI/2) (90° CCW from above) is typical. None = no offset.

calibrate_hand_transforms: bool

Enable interactive capture of live hand grip offsets.

When enabled, pressing Enter captures the current controller-to-hand rotation offset for the first initialized AVC in the world and prints MMS-ready hand_grip_rotation_left/right([...]) lines to the console.

skip_body_pipeline: bool

Debug/diagnostic flag: skip creation of the body-rotation pipeline entirely. When true, model_root stays directly under AVC and only head rotation is applied. Use this to isolate whether torso-twist bugs originate in the body pipeline.

ik_debug: bool

Debug/diagnostic flag: when enabled, arm TwoBoneIK chains spawn overlay visualizations for the actual target vector, transformed pole vector, bend-plane normal, and solved elbow direction used by the solver.

neck_bone: Option<String>

Name of the neck bone used by the Phase 2 rest-pin. When set and the bone is found under model_root, the body-follow system records its rest local translation at init and restores it each tick if any other system perturbs it. Default: "J_Bip_C_Neck".

Implementations

impl AvatarControlComponent

pub fn new() -> Self

Examples found in repository

examples/vr-input.rs (line 348)

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");
}

pub fn with_head_bone(self, name: impl Into<String>) -> Self

Examples found in repository

examples/vr-input.rs (line 349)

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");
}

pub fn with_left_hand_bone(self, name: impl Into<String>) -> Self

Examples found in repository

examples/vr-input.rs (line 351)

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");
}

pub fn with_right_hand_bone(self, name: impl Into<String>) -> Self

Examples found in repository

examples/vr-input.rs (line 352)

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");
}

pub fn with_left_upper_arm_bone(self, name: impl Into<String>) -> Self

pub fn with_left_lower_arm_bone(self, name: impl Into<String>) -> Self

pub fn with_right_upper_arm_bone(self, name: impl Into<String>) -> Self

pub fn with_right_lower_arm_bone(self, name: impl Into<String>) -> Self

pub fn with_left_arm_pole_direction(self, dir: [f32; 3]) -> Self

Override the left elbow pole direction (body-local).

pub fn with_right_arm_pole_direction(self, dir: [f32; 3]) -> Self

Override the right elbow pole direction (body-local).

pub fn with_body_yaw_threshold(self, t: f32) -> Self

pub fn with_body_yaw_rate(self, r: f32) -> Self

pub fn with_initial_yaw(self, yaw: f32) -> Self

Override the initial body yaw (radians) seeded into the YawFollow pipeline op. Use std::f32::consts::PI for rigs that face -Z at rest.

Examples found in repository

examples/vr-input.rs (line 353)

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");
}

pub fn with_forward_plus_z(self) -> Self

Use +Z as the authored forward axis override.

pub fn with_hand_rotation_smoothing(self, factor: f32) -> Self

Enable rotation smoothing for hand pose drivers. Set to e.g. 220.0 for smooth VR controller rotation.

Examples found in repository

examples/vr-input.rs (line 354)

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");
}

pub fn with_body_pipeline_disabled(self) -> Self

Skip creation of the body-rotation pipeline. Only head rotation will be applied. Use to isolate whether torso-twist bugs originate in the body pipeline.

pub fn with_ik_debug(self) -> Self

Enable TwoBoneIK debug visualizations for chains owned by this AVC.

pub fn with_camera_bone(self, name: impl Into<String>) -> Self

Set the bone used as the camera anchor and for auto-calibrating model_root.y.

AvatarControlSystem will measure this bone’s local Y in the rest pose and set model_root.y = -bone_local_y so the bone sits at driven_t’s world position. Any Camera3DComponent or CameraXRComponent direct children of this AVC are re-parented under this bone during init.

Examples found in repository

examples/vr-input.rs (line 350)

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");
}

pub fn with_avatar_height(self, height: f32) -> Self

Explicitly set model_root.y = -height during init, bypassing camera_bone auto-calibration. Use when the bone lookup is unreliable or the mesh height is known in advance. Camera re-parenting still uses camera_bone if set.

pub fn with_eye_height_from_head_bone(self, dy: f32) -> Self

Shift model_root.y down so the avatar’s EYES (not the head bone pivot) land at driven_t’s world Y. Default eye offset for VRM is ~0.08.

pub fn with_hips_bone(self, name: impl Into<String>) -> Self

Set the hips bone name — root of the spine FABRIK chain. Default (when unset): "J_Bip_C_Hips".

pub fn with_neck_bone(self, name: impl Into<String>) -> Self

Override the neck bone name used by the Phase 2 rest-pin. Pass None to disable the pin entirely.

pub fn without_neck_pin(self) -> Self

Disable the neck rest-pin.

pub fn with_head_ik_eye_height(self, dy: f32) -> Self

Set the vertical offset for the head IK target calculation (metres). Decoupled from the camera position so spine bending and camera positioning can be controlled independently. Default: None.

pub fn with_hand_grip_rotation_left(self, q: [f32; 4]) -> Self

Set a rotation offset applied to the left hand grip IK target. Quaternion in [x, y, z, w] order.

pub fn with_hand_grip_rotation_right(self, q: [f32; 4]) -> Self

Set a rotation offset applied to the right hand grip IK target.

pub fn with_calibrate_hand_transforms(self) -> Self

Trait Implementations

impl Clone for AvatarControlComponent

fn clone(&self) -> AvatarControlComponent

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Component for AvatarControlComponent

fn name(&self) -> &'static str

Short debug/type name for this component kind (e.g. “transform”, “camera”).

fn set_id(&mut self, id: ComponentId)

fn init(&mut self, emit: &mut dyn SignalEmitter, component: ComponentId)

Called when component is added to the World

fn as_any(&self) -> &dyn Any

fn as_any_mut(&mut self) -> &mut dyn Any

fn to_mms_ast(&self, _world: &World) -> ComponentExpression

Encode this component as an MMS Component Expression AST node.

fn cleanup(&mut self, _emit: &mut dyn SignalEmitter, _component: ComponentId)

Called when component is removed from the World.

fn encode(&self) -> HashMap<String, Value>

Encode component data to a HashMap for serialization.

fn decode(&mut self, _data: &HashMap<String, Value>) -> Result<(), String>

Decode component data from a HashMap after deserialization.

impl Debug for AvatarControlComponent

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

Formats the value using the given formatter.

impl Default for AvatarControlComponent

fn default() -> Self

Returns the “default value” for a type.