Struct DirectionalLightComponent 

pub struct DirectionalLightComponent {
    pub intensity: f32,
    pub color: [f32; 3],
    /* private fields */
}

Directional light (infinite distance light).

The renderer interprets this light’s world position as a direction vector. In other words: set the node’s translation to the direction you want (it will be normalized on the GPU).

Fields

intensity: f32

color: [f32; 3]

Linear RGB color in 0..1.

Implementations

impl DirectionalLightComponent

pub fn new() -> Self

Examples found in repository

examples/pointer-events.rs (line 383)

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

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

    use engine::ecs::component::{
        AmbientLightComponent, BackgroundColorComponent, Camera3DComponent, ColorComponent,
        DirectionalLightComponent, InputComponent, InputTransformModeComponent, PointerComponent,
        TransformComponent,
    };

    // Background.
    let bg = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let bg_c = universe
        .world
        .add_component(ColorComponent::rgba(0.12, 0.12, 0.16, 1.0));
    let _ = universe.world.add_child(bg, bg_c);
    universe.add(bg);

    // Lighting.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.30, 0.30, 0.32));
    universe.add(ambient);

    let sun_t = universe
        .world
        .add_component(TransformComponent::new().with_position(2.0, 4.0, 3.0));
    let sun = universe
        .world
        .add_component(DirectionalLightComponent::new());
    let _ = universe.attach(sun_t, sun);
    universe.add(sun_t);

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

    let cam_t = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.5, 4.5));
    let cam = universe
        .world
        .add_component(Camera3DComponent::new().with_fov(70.0));
    let pointer = universe.world.add_component(PointerComponent::new());

    let _ = universe.attach(input, cam_t);
    let _ = universe.attach(cam_t, cam);
    let _ = universe.attach(cam, pointer);

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

    // Scene root for all interactive objects.
    let scene = universe.world.add_component(TransformComponent::new());
    universe.add(scene);

    // --- LEFT: click-only cubes ---
    let click_group = universe
        .world
        .add_component(TransformComponent::new().with_position(-2.2, 0.0, 0.0));
    let _ = universe.attach(scene, click_group);

    for (i, dy) in [-0.55_f32, 0.0, 0.55].iter().enumerate() {
        spawn_click_cube(&mut universe, click_group, [0.0, *dy, 0.0]);
        let _ = i;
    }
    spawn_label(
        &mut universe,
        click_group,
        [-0.25, -1.05, 0.0],
        "click\ncycles color",
    );

    // --- MID: drag-only cube ---
    let drag_cube_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 0.0));
    let _ = universe.attach(scene, drag_cube_root);

    spawn_drag_cube(
        &mut universe,
        drag_cube_root,
        [0.0, 0.0, 0.0],
        [0.35, 0.85, 0.55, 1.0],
    );
    spawn_label(
        &mut universe,
        drag_cube_root,
        [-0.25, -0.80, 0.0],
        "drag\nto move",
    );

    // --- RIGHT: drag + click cube ---
    let both_root = universe
        .world
        .add_component(TransformComponent::new().with_position(2.2, 0.0, 0.0));
    let _ = universe.attach(scene, both_root);

    spawn_both_cube(&mut universe, both_root, [0.0, 0.0, 0.0]);
    spawn_label(
        &mut universe,
        both_root,
        [-0.30, -0.80, 0.0],
        "drag to move\nclick for color",
    );

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

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

examples/button-press.rs (line 474)

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

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

    // Minimal lit scene + pointer raycaster.
    use engine::ecs::component::{
        AmbientLightComponent, BackgroundColorComponent, Camera3DComponent,
        DirectionalLightComponent, InputComponent, InputTransformModeComponent, PointerComponent,
        TransformComponent,
    };

    let bg = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let bg_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.92, 0.92, 0.96, 1.0,
        ));
    let _ = universe.world.add_child(bg, bg_c);
    universe.add(bg);

    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.35, 0.35, 0.35));
    universe.add(ambient);

    let sun_t = universe
        .world
        .add_component(TransformComponent::new().with_position(1.0, 1.0, 1.0));
    let sun = universe
        .world
        .add_component(DirectionalLightComponent::new());
    let _ = universe.attach(sun_t, sun);
    universe.add(sun_t);

    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(2.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 rig_t = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 2.5));
    let _ = universe.attach(input, rig_t);

    let cam = universe
        .world
        .add_component(Camera3DComponent::new().with_far(600.0).with_fov(70.0));
    let _ = universe.attach(rig_t, cam);

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

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

    // The button.
    let button_root = spawn_button(
        &mut universe,
        [0.0, 0.0, 0.0],
        [1.20, 0.45],
        ButtonBorder::new(0.025, 0.025, 0.025, 0.025),
        "click me",
        0.18,
        [0.15, 0.15, 0.20, 1.0],
        [0.85, 0.85, 0.92, 1.0],
    );

    // A small 3-cube stack to the left of the button for gizmo testing:
    //   [cyan]
    // [yellow][light brown]
    //
    // These live under an EditorComponent subtree so clicking attaches the editor gizmo.
    {
        use engine::ecs::component::{EditorComponent, TransformComponent};

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

        // Position the stack in world space (left of the button).
        let stack_root = universe
            .world
            .add_component(TransformComponent::new().with_position(-1.55, 0.0, 0.0));
        let _ = universe.attach(editor_root, stack_root);

        let cube = 0.22_f32;
        let gap = 0.04_f32;
        let step = cube + gap;
        let y_bottom = -0.5 * step;
        let y_top = 0.5 * step;
        let x_left = -0.5 * step;
        let x_right = 0.5 * step;

        let yellow = [1.0, 0.92, 0.22, 1.0];
        let light_brown = [0.80, 0.66, 0.46, 1.0];
        let cyan = [0.20, 0.95, 1.0, 1.0];

        let _bottom_left = spawn_raycastable_colored_cube(
            &mut universe,
            stack_root,
            [x_left, y_bottom, 0.0],
            [cube, cube, 0.06],
            yellow,
        );
        let _bottom_right = spawn_raycastable_colored_cube(
            &mut universe,
            stack_root,
            [x_right, y_bottom, 0.0],
            [cube, cube, 0.06],
            light_brown,
        );
        let _top = spawn_raycastable_colored_cube(
            &mut universe,
            stack_root,
            [0.0, y_top, 0.0],
            [cube, cube, 0.06],
            cyan,
        );

        universe.add(editor_root);
    }

    universe.add_signal_handler(
        engine::ecs::SignalKind::DragStart,
        button_root,
        button_press_handler,
    );
    universe.add_signal_handler(
        engine::ecs::SignalKind::DragEnd,
        button_root,
        button_press_handler,
    );

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

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

examples/vtuber-example.rs (line 63)

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

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

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

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

    // --- Camera rig (WASD + mouse) ---
    // InputComponent is the root, and it owns a Transform (the camera rig).
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(1.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

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

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

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

    universe.add(input);

    // --- lighting ---
    // Directional key light (slightly down + forward Z).
    let sun = universe.world.add_component(
        DirectionalLightComponent::new()
            .with_intensity(1.2)
            .with_color(1.0, 0.98, 0.94),
    );
    let sun_dir = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -0.35, 1.0));
    let _ = universe.attach(sun_dir, sun);
    universe.add(sun_dir);

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

    // --- VTuber model ---
    let model_root = universe.world.add_component(TransformComponent::new());
    let model = universe
        .world
        .add_component(GLTFComponent::new("assets/models/pc-rei.hoodie.glb"));
    // emissive for pc-rei
    let emissive = universe
        .world
        .add_component(engine::ecs::component::EmissiveComponent::on());

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

examples/gestures-and-gizmos.rs (line 81)

fn build_gestures_and_gizmos_scene(universe: &mut engine::Universe) -> Scene {
    use engine::ecs::component::{
        BackgroundColorComponent, BackgroundComponent, Camera3DComponent, ColorComponent,
        DirectionalLightComponent, InputComponent, InputTransformModeComponent, PointerComponent,
        RaycastableComponent, RenderableComponent, TransformComponent, TransformGizmoComponent,
    };
    use engine::graphics::BuiltinMeshType;
    use engine::graphics::primitives::{MaterialHandle, Renderable};

    let tri_mesh = universe.render_assets.get_mesh(BuiltinMeshType::Triangle2D);
    let cube_mesh = universe.render_assets.get_mesh(BuiltinMeshType::Cube);
    let tetra_mesh = universe
        .render_assets
        .get_mesh(BuiltinMeshType::Tetrahedron);

    // BackgroundColor { C.rgba }
    let bg_color = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let bg_color_c = universe
        .world
        .add_component(ColorComponent::rgba(0.90, 0.90, 0.90, 1.0));
    let _ = universe.world.add_child(bg_color, bg_color_c);
    universe.add(bg_color);

    // ambient light
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.25, 0.25, 0.25));
    universe.add(ambient);

    // ground plane
    let ground_tx = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, -2.5, 0.0)
            .with_scale(20.0, 1.0, 20.0),
    );
    let ground_r = universe
        .world
        .add_component(RenderableComponent::new(Renderable::new(
            universe.render_assets.get_mesh(BuiltinMeshType::Cube),
            MaterialHandle::TOON_MESH,
        )));
    let ground_c = universe
        .world
        .add_component(ColorComponent::rgba(0.75, 0.75, 0.75, 1.0));
    let _ = universe.attach(ground_tx, ground_r);
    let _ = universe.attach(ground_r, ground_c);
    let _ = universe.add(ground_tx);

    // Background {
    //     with_occlusion_and_lighting()
    //     // using the example utils to add clouds to the background
    // }
    let bg_root = universe
        .world
        .add_component(BackgroundComponent::new().with_occlusion_and_lighting());
    universe.add(bg_root);

    // DirectionalLight {
    //     T { translate [1, 1, 1] }
    // }
    // Directional lights encode their direction in the node's world position.
    let sun_t = universe
        .world
        .add_component(TransformComponent::new().with_position(1.0, 1.0, 1.0));
    let sun = universe
        .world
        .add_component(DirectionalLightComponent::new());
    let _ = universe.attach(sun_t, sun);
    universe.add(sun_t);

    // i = input
    // t = transform
    // c3d = camera3d
    //
    // I {
    //     T {
    //         C3D { with_fps_rotation().with_roll_axis_y() }
    //     }
    // }
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(2.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );

    let _ = universe.attach(input, input_mode);

    // Forward is -Z, so put the camera at +Z looking toward the origin.
    let rig_t = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 3.5));
    let _ = universe.attach(input, rig_t);

    let cam = universe
        .world
        .add_component(Camera3DComponent::new().with_far(600.0).with_fov(70.0));
    let _ = universe.attach(rig_t, cam);

    // Opt-in: treat this camera rig as a pointer source.
    let pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(cam, pointer);

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

    fn spawn_shape_with_gizmo(
        universe: &mut engine::Universe,
        mesh: engine::graphics::primitives::CpuMeshHandle,
        pos: [f32; 3],
        scale: [f32; 3],
        rot_euler: [f32; 3],
        color: [f32; 4],
    ) {
        let t = universe.world.add_component(
            TransformComponent::new()
                .with_position(pos[0], pos[1], pos[2])
                .with_scale(scale[0], scale[1], scale[2])
                .with_rotation_euler(rot_euler[0], rot_euler[1], rot_euler[2]),
        );
        let r = universe
            .world
            .add_component(RenderableComponent::new(Renderable::new(
                mesh,
                MaterialHandle::TOON_MESH,
            )));
        let c = universe
            .world
            .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
        let rc = universe
            .world
            .add_component(RaycastableComponent::enabled());
        let g = universe.world.add_component(TransformGizmoComponent::new());

        let _ = universe.attach(t, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, rc);
        let _ = universe.attach(t, g);

        universe.add(t);
    }

    fn spawn_shape_raycastable_no_gizmo(
        universe: &mut engine::Universe,
        mesh: engine::graphics::primitives::CpuMeshHandle,
        pos: [f32; 3],
        scale: [f32; 3],
        rot_euler: [f32; 3],
        color: [f32; 4],
    ) {
        let t = universe.world.add_component(
            TransformComponent::new()
                .with_position(pos[0], pos[1], pos[2])
                .with_scale(scale[0], scale[1], scale[2])
                .with_rotation_euler(rot_euler[0], rot_euler[1], rot_euler[2]),
        );
        let r = universe
            .world
            .add_component(RenderableComponent::new(Renderable::new(
                mesh,
                MaterialHandle::TOON_MESH,
            )));
        let c = universe
            .world
            .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
        let rc = universe
            .world
            .add_component(RaycastableComponent::enabled());

        let _ = universe.attach(t, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, rc);

        universe.add(t);
    }

    spawn_shape_with_gizmo(
        universe,
        tri_mesh,
        [-1.2, 0.0, 0.0],
        [0.65, 0.65, 0.65],
        [0.0, 0.0, 0.0],
        [0.2, 0.9, 0.25, 1.0],
    );
    spawn_shape_with_gizmo(
        universe,
        cube_mesh,
        [0.0, 0.0, 0.0],
        [0.55, 0.55, 0.55],
        [0.0, 0.0, 0.0],
        [0.95, 0.25, 0.2, 1.0],
    );
    spawn_shape_with_gizmo(
        universe,
        tetra_mesh,
        [1.2, 0.0, 0.0],
        [0.7, 0.7, 0.7],
        [0.0, 0.0, 0.0],
        [0.2, 0.55, 1.0, 1.0],
    );

    // Standalone tetrahedron: no gizmo, but explicitly raycastable.
    // This helps isolate tetra picking vs gizmo-handle interception.
    spawn_shape_raycastable_no_gizmo(
        universe,
        tetra_mesh,
        [2.6, -0.6, 0.0],
        [0.95, 0.95, 0.95],
        [0.0, 0.0, 0.0],
        [0.85, 0.85, 1.0, 1.0],
    );

    universe.add(input);

    Scene { bg_root }
}

examples/background-occlusion-example.rs (line 75)

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

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

    // Light purple-red background so the occlusion reads.
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.62, 0.38, 0.56, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // A bit of ambient so the cluster volume reads.
    let ambient = universe
        .world
        .add_component(engine::ecs::component::AmbientLightComponent::rgb(
            0.20, 0.15, 0.3,
        ));
    universe.add(ambient);

    // --- Camera rig (WASD/QE) ---
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(2.0));
    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z().with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 6.0),
    );
    let _ = universe.attach(input, rig_transform);

    let camera3d = universe.world.add_component(
        engine::ecs::component::Camera3DComponent::new()
            .with_far(200.0)
            .with_fov(70.0),
    );
    let _ = universe.attach(rig_transform, camera3d);

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

    // Key directional light toward the cloud volume.
    //
    // Directional lights encode their direction in the node's world position.
    // The shader normalizes this vector.
    let sun = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_intensity(1.6)
            .with_color(1.0, 0.98, 0.92),
    );
    // Pointing from the clouds back toward the camera a bit (+Z), and slightly from above.
    let sun_dir = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.15, 0.65, 0.75),
    );
    let _ = universe.attach(sun_dir, sun);

    // A couple point lights to fill/shade the cloud volume.
    let light_a = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(80.0)
            .with_intensity(3.0)
            .with_color(0.9, 0.95, 1.0),
    );
    let light_a_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(8.0, 8.0, 5.0),
    );
    let _ = universe.attach(light_a_tx, light_a);

    let light_b = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(80.0)
            .with_intensity(2.2)
            .with_color(1.0, 0.9, 0.85),
    );
    let light_b_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(-10.0, 4.0, -6.0),
    );
    let _ = universe.attach(light_b_tx, light_b);

    universe.add(input);
    universe.add(sun_dir);
    universe.add(light_a_tx);
    universe.add(light_b_tx);

    let cube_mesh = universe
        .render_assets
        .get_mesh(engine::graphics::BuiltinMeshType::Cube);

    // --- Background occluded+lit world ---
    // Renderables under this node participate in a background stage that depth-writes for
    // self-occlusion + uses the normal lighting shader inputs.
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);

    // Create overlapping cube clusters like cloud puffs.
    // Place them generally in front of the camera (negative Z).
    // Spawn two groups on opposite X sides.
    let cluster_count: u32 = 9;
    for (group_i, group_x) in [-16.0_f32, 16.0_f32].into_iter().enumerate() {
        let group_tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(group_x, 0.0, 0.0),
        );
        let _ = universe.attach(bg_root, group_tx);

        for cluster_i in 0..cluster_count {
            let seed = (0xC10u32 ^ (group_i as u32).wrapping_mul(0x9E37_79B9))
                ^ (cluster_i.wrapping_mul(7919));

            let cx = (rand01(seed ^ 0xA341_316C) - 0.5) * 18.0;
            let cy = (rand01(seed ^ 0xC801_3EA4) - 0.5) * 10.0 + 2.0;
            let cz = -18.0 - rand01(seed ^ 0xB529_7A4D) * 26.0;

            let center_tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new().with_position(cx, cy, cz),
            );
            let _ = universe.attach(group_tx, center_tx);

            let puffs = 18u32;
            for puff_i in 0..puffs {
                let puff_seed = seed ^ puff_i.wrapping_mul(1_103_515_245);

                // Slightly ellipsoidal distribution.
                let ox = (rand01(puff_seed ^ 0x68bc_21eb) - 0.5) * 7.0;
                let oy = (rand01(puff_seed ^ 0x02e5_be93) - 0.5) * 3.0;
                let oz = (rand01(puff_seed ^ 0xa1d3_4f2b) - 0.5) * 7.0;

                let base = 0.7 + rand01(puff_seed ^ 0x9e37_79b9) * 2.6;
                let sx = base * (0.7 + rand01(puff_seed ^ 0x243f_6a88) * 0.8);
                let sy = base * (0.6 + rand01(puff_seed ^ 0x85a3_08d3) * 0.9);
                let sz = base * (0.7 + rand01(puff_seed ^ 0x1319_8a2e) * 0.8);

                let tx = universe.world.add_component(
                    engine::ecs::component::TransformComponent::new()
                        .with_position(ox, oy, oz)
                        .with_scale(sx, sy, sz),
                );
                let renderable =
                    universe
                        .world
                        .add_component(engine::ecs::component::RenderableComponent::new(
                            engine::graphics::primitives::Renderable::new(
                                cube_mesh,
                                engine::graphics::primitives::MaterialHandle::TOON_MESH,
                            ),
                        ));

                // Slight blue-grey variation.
                let t = rand01(puff_seed ^ 0x7f4a_7c15);
                let r = 0.55 + 0.10 * t;
                let g = 0.58 + 0.10 * t;
                let b = 0.66 + 0.12 * t;
                let color = universe
                    .world
                    .add_component(engine::ecs::component::ColorComponent::rgba(r, g, b, 1.0));

                let _ = universe.attach(center_tx, tx);
                let _ = universe.attach(tx, renderable);
                let _ = universe.attach(renderable, color);
            }
        }
    }

    // Foreground reference cube (should never be occluded by background depth).
    let fg_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new()
            .with_position(0.0, -0.5, -4.0)
            .with_scale(1.2, 0.8, 1.2),
    );
    let fg_renderable =
        universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::new(
                engine::graphics::primitives::Renderable::new(
                    cube_mesh,
                    engine::graphics::primitives::MaterialHandle::TOON_MESH,
                ),
            ));
    let fg_color = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.9, 0.2, 0.2, 1.0,
        ));

    universe.add(fg_tx);
    let _ = universe.attach(fg_tx, fg_renderable);
    let _ = universe.attach(fg_renderable, fg_color);

    // Foreground opaque floor: 16x16 larger white cubes, 10 units below the reference cube.
    let floor_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, -10.5, -10.0),
    );
    universe.add(floor_root);

    let spacing = 10_f32;
    let half = 5_f32;
    for x in 0..16u32 {
        for z in 0..64u32 {
            let px = (x as f32 - half) * spacing;
            let pz = (z as f32 * -1.0 + half) * spacing;
            let tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(px, -5.0, pz)
                    .with_scale(5.0, 0.5, 5.0),
            );
            let renderable =
                universe
                    .world
                    .add_component(engine::ecs::component::RenderableComponent::new(
                        engine::graphics::primitives::Renderable::new(
                            cube_mesh,
                            engine::graphics::primitives::MaterialHandle::TOON_MESH,
                        ),
                    ));
            let color = universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

            let _ = universe.attach(floor_root, tx);
            let _ = universe.attach(tx, renderable);
            let _ = universe.attach(renderable, color);
        }
    }

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

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

examples/vr-input.rs (line 249)

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

Additional examples can be found in:

• examples/font-example.rs
• examples/vtuber-joints-example.rs
• examples/audio-graph-example.rs
• examples/gravity-fields.rs

pub fn with_intensity(self, intensity: f32) -> Self

Examples found in repository

examples/vtuber-example.rs (line 64)

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

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

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

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

    // --- Camera rig (WASD + mouse) ---
    // InputComponent is the root, and it owns a Transform (the camera rig).
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(1.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

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

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

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

    universe.add(input);

    // --- lighting ---
    // Directional key light (slightly down + forward Z).
    let sun = universe.world.add_component(
        DirectionalLightComponent::new()
            .with_intensity(1.2)
            .with_color(1.0, 0.98, 0.94),
    );
    let sun_dir = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -0.35, 1.0));
    let _ = universe.attach(sun_dir, sun);
    universe.add(sun_dir);

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

    // --- VTuber model ---
    let model_root = universe.world.add_component(TransformComponent::new());
    let model = universe
        .world
        .add_component(GLTFComponent::new("assets/models/pc-rei.hoodie.glb"));
    // emissive for pc-rei
    let emissive = universe
        .world
        .add_component(engine::ecs::component::EmissiveComponent::on());

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

examples/background-occlusion-example.rs (line 76)

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

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

    // Light purple-red background so the occlusion reads.
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.62, 0.38, 0.56, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // A bit of ambient so the cluster volume reads.
    let ambient = universe
        .world
        .add_component(engine::ecs::component::AmbientLightComponent::rgb(
            0.20, 0.15, 0.3,
        ));
    universe.add(ambient);

    // --- Camera rig (WASD/QE) ---
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(2.0));
    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z().with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 6.0),
    );
    let _ = universe.attach(input, rig_transform);

    let camera3d = universe.world.add_component(
        engine::ecs::component::Camera3DComponent::new()
            .with_far(200.0)
            .with_fov(70.0),
    );
    let _ = universe.attach(rig_transform, camera3d);

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

    // Key directional light toward the cloud volume.
    //
    // Directional lights encode their direction in the node's world position.
    // The shader normalizes this vector.
    let sun = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_intensity(1.6)
            .with_color(1.0, 0.98, 0.92),
    );
    // Pointing from the clouds back toward the camera a bit (+Z), and slightly from above.
    let sun_dir = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.15, 0.65, 0.75),
    );
    let _ = universe.attach(sun_dir, sun);

    // A couple point lights to fill/shade the cloud volume.
    let light_a = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(80.0)
            .with_intensity(3.0)
            .with_color(0.9, 0.95, 1.0),
    );
    let light_a_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(8.0, 8.0, 5.0),
    );
    let _ = universe.attach(light_a_tx, light_a);

    let light_b = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(80.0)
            .with_intensity(2.2)
            .with_color(1.0, 0.9, 0.85),
    );
    let light_b_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(-10.0, 4.0, -6.0),
    );
    let _ = universe.attach(light_b_tx, light_b);

    universe.add(input);
    universe.add(sun_dir);
    universe.add(light_a_tx);
    universe.add(light_b_tx);

    let cube_mesh = universe
        .render_assets
        .get_mesh(engine::graphics::BuiltinMeshType::Cube);

    // --- Background occluded+lit world ---
    // Renderables under this node participate in a background stage that depth-writes for
    // self-occlusion + uses the normal lighting shader inputs.
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);

    // Create overlapping cube clusters like cloud puffs.
    // Place them generally in front of the camera (negative Z).
    // Spawn two groups on opposite X sides.
    let cluster_count: u32 = 9;
    for (group_i, group_x) in [-16.0_f32, 16.0_f32].into_iter().enumerate() {
        let group_tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(group_x, 0.0, 0.0),
        );
        let _ = universe.attach(bg_root, group_tx);

        for cluster_i in 0..cluster_count {
            let seed = (0xC10u32 ^ (group_i as u32).wrapping_mul(0x9E37_79B9))
                ^ (cluster_i.wrapping_mul(7919));

            let cx = (rand01(seed ^ 0xA341_316C) - 0.5) * 18.0;
            let cy = (rand01(seed ^ 0xC801_3EA4) - 0.5) * 10.0 + 2.0;
            let cz = -18.0 - rand01(seed ^ 0xB529_7A4D) * 26.0;

            let center_tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new().with_position(cx, cy, cz),
            );
            let _ = universe.attach(group_tx, center_tx);

            let puffs = 18u32;
            for puff_i in 0..puffs {
                let puff_seed = seed ^ puff_i.wrapping_mul(1_103_515_245);

                // Slightly ellipsoidal distribution.
                let ox = (rand01(puff_seed ^ 0x68bc_21eb) - 0.5) * 7.0;
                let oy = (rand01(puff_seed ^ 0x02e5_be93) - 0.5) * 3.0;
                let oz = (rand01(puff_seed ^ 0xa1d3_4f2b) - 0.5) * 7.0;

                let base = 0.7 + rand01(puff_seed ^ 0x9e37_79b9) * 2.6;
                let sx = base * (0.7 + rand01(puff_seed ^ 0x243f_6a88) * 0.8);
                let sy = base * (0.6 + rand01(puff_seed ^ 0x85a3_08d3) * 0.9);
                let sz = base * (0.7 + rand01(puff_seed ^ 0x1319_8a2e) * 0.8);

                let tx = universe.world.add_component(
                    engine::ecs::component::TransformComponent::new()
                        .with_position(ox, oy, oz)
                        .with_scale(sx, sy, sz),
                );
                let renderable =
                    universe
                        .world
                        .add_component(engine::ecs::component::RenderableComponent::new(
                            engine::graphics::primitives::Renderable::new(
                                cube_mesh,
                                engine::graphics::primitives::MaterialHandle::TOON_MESH,
                            ),
                        ));

                // Slight blue-grey variation.
                let t = rand01(puff_seed ^ 0x7f4a_7c15);
                let r = 0.55 + 0.10 * t;
                let g = 0.58 + 0.10 * t;
                let b = 0.66 + 0.12 * t;
                let color = universe
                    .world
                    .add_component(engine::ecs::component::ColorComponent::rgba(r, g, b, 1.0));

                let _ = universe.attach(center_tx, tx);
                let _ = universe.attach(tx, renderable);
                let _ = universe.attach(renderable, color);
            }
        }
    }

    // Foreground reference cube (should never be occluded by background depth).
    let fg_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new()
            .with_position(0.0, -0.5, -4.0)
            .with_scale(1.2, 0.8, 1.2),
    );
    let fg_renderable =
        universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::new(
                engine::graphics::primitives::Renderable::new(
                    cube_mesh,
                    engine::graphics::primitives::MaterialHandle::TOON_MESH,
                ),
            ));
    let fg_color = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.9, 0.2, 0.2, 1.0,
        ));

    universe.add(fg_tx);
    let _ = universe.attach(fg_tx, fg_renderable);
    let _ = universe.attach(fg_renderable, fg_color);

    // Foreground opaque floor: 16x16 larger white cubes, 10 units below the reference cube.
    let floor_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, -10.5, -10.0),
    );
    universe.add(floor_root);

    let spacing = 10_f32;
    let half = 5_f32;
    for x in 0..16u32 {
        for z in 0..64u32 {
            let px = (x as f32 - half) * spacing;
            let pz = (z as f32 * -1.0 + half) * spacing;
            let tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(px, -5.0, pz)
                    .with_scale(5.0, 0.5, 5.0),
            );
            let renderable =
                universe
                    .world
                    .add_component(engine::ecs::component::RenderableComponent::new(
                        engine::graphics::primitives::Renderable::new(
                            cube_mesh,
                            engine::graphics::primitives::MaterialHandle::TOON_MESH,
                        ),
                    ));
            let color = universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

            let _ = universe.attach(floor_root, tx);
            let _ = universe.attach(tx, renderable);
            let _ = universe.attach(renderable, color);
        }
    }

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

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

examples/vr-input.rs (line 250)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(xr_input);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

examples/font-example.rs (line 42)

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

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

    // Dark background so the font texture pops.
    let background = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let background_c = universe
        .world
        .add_component(ColorComponent::rgba(0.20, 0.2, 0.20, 1.0));
    let _ = universe.world.add_child(background, background_c);
    universe.add(background);

    // Ambient so text is readable even without explicit lights.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.50, 0.50, 0.50));
    universe.add(ambient);

    let directional_tx = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.5, 1.0));
    let directional_light = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_color(1.0, 1.0, 1.0)
            .with_intensity(0.8),
    );
    let _ = universe.attach(directional_tx, directional_light);
    universe.add(directional_tx);

    // --- background clouds ---
    // Background stage (occluded + lit) so the cloud volume self-occludes but won't occlude
    // the foreground text (renderer clears depth before foreground).
    let bg_root = universe
        .world
        .add_component(BackgroundComponent::new().with_occlusion_and_lighting());
    universe.add(bg_root);

    let mut bg_cloud_params = example_util::CloudRingParams::default();
    bg_cloud_params.cloud_count = 6;
    bg_cloud_params.seed = 0xF0_17_C10u32;
    example_util::spawn_cloud_ring(&mut universe, bg_root, bg_cloud_params);

    // I {
    //   // not fps rotation, just relative rotation
    //   with_forward_z()
    //   with_roll_axis_y()
    //   C3D {}
    // }
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(2.0));
    let input_mode = universe
        .world
        .add_component(InputTransformModeComponent::forward_z().with_roll_axis_y());
    let _ = universe.attach(input, input_mode);

    let rig_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(1.8, -0.5, 2.5));
    let _ = universe.attach(input, rig_transform);

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

    // Click-to-pick: treat this camera rig as a pointer source.
    let pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(camera, pointer);

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

    universe.add(input);

    // --- foreground clouds ---
    // Normal foreground renderables (not background stage).
    // Offset the ring forward (negative Z) so several clusters are in view.
    let fg_cloud_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -6.0, -10.0));
    universe.add(fg_cloud_root);

    let mut fg_cloud_params = example_util::CloudRingParams::default();
    fg_cloud_params.cloud_count = 4;
    fg_cloud_params.radius = 9.0;
    fg_cloud_params.center_y = 1.0;
    fg_cloud_params.puffs_per_cloud = 22;
    fg_cloud_params.angle_jitter = 0.35;
    fg_cloud_params.high_y_probability = 0.35;
    fg_cloud_params.high_y_multiplier = 1.4;
    fg_cloud_params.seed = 0xF0_17_C102u32;
    example_util::spawn_cloud_ring(&mut universe, fg_cloud_root, fg_cloud_params);

    // T {
    //   with_translation(0,0, -2)
    //   TXT {
    //     "ababaabbaabbaaabbbaaabbbaaaabbbbaaaaabbbbbababababa"
    //     TextureComponent { assets/images/test.font_system.png }
    //   }
    // }
    fn estimate_text_height_world(text: &str, scale: f32) -> f32 {
        let line_count = text.lines().count().max(1) as f32;
        // Text quads are ~1 unit tall per line in text-space.
        // Add some padding so blocks don't feel cramped.
        let pad_lines = 1.25;
        (line_count + pad_lines) * scale
    }

    fn spawn_text_block(
        universe: &mut engine::Universe,
        position: (f32, f32, f32),
        scale: f32,
        text: &str,
        font_texture_uri: Option<&str>,
        text_color_rgba: Option<[f32; 4]>,
        shadow: Option<TextShadowComponent>,
        filtering: TextureFilteringComponent,
    ) -> f32 {
        // T_root { T_scale { [Color] { TXT { shadow, filtering } } } }
        let text_root = universe.world.add_component(
            TransformComponent::new().with_position(position.0, position.1, position.2),
        );

        let text_scale = universe
            .world
            .add_component(TransformComponent::new().with_scale(scale, scale, 1.0));
        let _ = universe.attach(text_root, text_scale);

        let text_parent = if let Some([r, g, b, a]) = text_color_rgba {
            let color = universe
                .world
                .add_component(ColorComponent::rgba(r, g, b, a));
            let _ = universe.attach(text_scale, color);
            color
        } else {
            text_scale
        };

        let text_c = universe.world.add_component(TextComponent::new(text));
        let _ = universe.attach(text_parent, text_c);

        // Explicit opt-in: make the glyph renderables pickable.
        // TextSystem will propagate this to all spawned glyph quads.
        let raycastable = universe
            .world
            .add_component(RaycastableComponent::enabled());
        let _ = universe.attach(text_c, raycastable);

        // Route glyph quads into the alpha-to-coverage cutout pass.
        let cutout = universe
            .world
            .add_component(TransparentCutoutComponent::new());
        let _ = universe.attach(text_c, cutout);

        if let Some(shadow) = shadow {
            let shadow_id = universe.world.add_component(shadow);
            let _ = universe.attach(text_c, shadow_id);
        }

        // Optional: override the font atlas for this text block.
        // TextSystem will propagate this to all glyph renderables.
        if let Some(uri) = font_texture_uri {
            let tex = universe
                .world
                .add_component(TextureComponent::with_uri(uri));
            let _ = universe.attach(text_c, tex);
        }

        let filtering_id = universe.world.add_component(filtering);
        let _ = universe.attach(text_c, filtering_id);

        universe.add(text_root);

        estimate_text_height_world(text, scale)
    }

    // --- text blocks ---
    // Multi-line samples at different scales.
    // (Text literals omitted in the README/snippet; see constants below.)
    const TEXT_BIG: &str = "CAT ENGINE\nfont example\nBIG TEXT";
    const TEXT_MED: &str = "multi-line\ntext block\nmedium";
    const TEXT_SMALL: &str = "small\ntext";
    const TEXT_TINY: &str = "tiny\ntext\n(zoom in)";

    // Stack vertically; advance by (measured height + gap) so big text gets more room.
    let x = -1.2;
    let z = -2.0;
    let mut y = 1.2;
    let gap = 0.15;

    let shadow_crisp = Some(
        TextShadowComponent::new()
            .with_scale(1.35)
            .with_offset([0.06, -0.06, 0.0015]),
    );

    y -= spawn_text_block(
        &mut universe,
        (x, y, z),
        0.55,
        TEXT_BIG,
        None,
        Some([1.0, 1.0, 1.0, 1.0]),
        shadow_crisp,
        TextureFilteringComponent::nearest_magnification(),
    ) + gap;
    y -= spawn_text_block(
        &mut universe,
        (x, y, z),
        0.25,
        TEXT_MED,
        None,
        Some([0.60, 0.95, 1.00, 1.0]),
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.15, 1.0])
                .with_scale(1.20)
                .with_offset([0.05, -0.04, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    y -= spawn_text_block(
        &mut universe,
        (x, y, z),
        0.14,
        TEXT_SMALL,
        None,
        Some([1.0, 0.88, 0.35, 1.0]),
        Some(
            TextShadowComponent::new()
                .with_rgba([0.15, 0.0, 0.0, 1.0])
                .with_scale(1.55)
                .with_offset([0.08, -0.08, 0.0015]),
        ),
        TextureFilteringComponent::nearest(),
    ) + gap;
    let _ = spawn_text_block(
        &mut universe,
        (x, y, z),
        0.08,
        TEXT_TINY,
        None,
        Some([0.90, 1.0, 0.70, 1.0]),
        shadow_crisp,
        TextureFilteringComponent::nearest_magnification(),
    );

    // Left block: explicit multi-line text using the default font_system atlas.
    const TEXT_LEFT: &str = "even though there's hexes\nto the solar plexus in my lexus\ni'm feelin' reckless,\nwhen i'm eating breakfast";
    let _ = spawn_text_block(
        &mut universe,
        (x - 8.1, 1.1, z),
        0.22,
        TEXT_LEFT,
        Some("assets/textures/font_system.dds"),
        Some([0.95, 0.95, 0.95, 1.0]),
        Some(
            TextShadowComponent::new()
                .with_scale(1.25)
                .with_offset([0.05, -0.05, 0.0015]),
        ),
        TextureFilteringComponent::nearest_magnification(),
    );

    // Alt atlas: put it *behind* the original stack (slightly farther from the camera)
    // and tint it dark grey.
    let alt_atlas = Some("assets/textures/font_system.0.0.dds");
    let alt_z = z - 0.05;
    let alt_grey = Some([0.25, 0.25, 0.25, 1.0]);

    let mut y_alt = 1.2;
    y_alt -= spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.55,
        TEXT_BIG,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    y_alt -= spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.25,
        TEXT_MED,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    y_alt -= spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.14,
        TEXT_SMALL,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    let _ = spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.08,
        TEXT_TINY,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    );

    universe.enable_repl();

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

    // Add an OpenXR component so OpenXRSystem initializes and starts polling events.
    let xr_root = universe
        .world
        .add_component(engine::ecs::component::XrComponent::on());
    universe.add(xr_root);

    // Process init-time registrations (Text expands into glyph subtrees here).
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    let print_transform_updates: bool = false;

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

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

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

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

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

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

examples/audio-graph-example.rs (line 85)

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

    // Debug toggle: allow isolating stack overflows to audio vs. non-audio init.
    // Set `CAT_AUDIO_EXAMPLE_DISABLE_AUDIO=1` to skip creating audio components and
    // skip scheduling audio notes. The UI/text/cube visualization will still spawn.
    let audio_enabled = std::env::var("CAT_AUDIO_EXAMPLE_DISABLE_AUDIO")
        .ok()
        .as_deref()
        != Some("1");

    // If set, we still build audio graph components but we don't start the CPAL output stream.
    // This helps distinguish "audio graph / scheduling" issues from "CPAL backend" issues.
    let audio_output_enabled = std::env::var("CAT_AUDIO_EXAMPLE_AUDIO_OUTPUT_OFF")
        .ok()
        .as_deref()
        != Some("1");

    println!("[audio-graph-example] start");

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

    println!("[audio-graph-example] universe created");

    // Minimal scene with a camera so the window opens (copied from animation-example).
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.07, 0.07, 0.07, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // Ambient light so unlit areas aren't pitch black.
    // Keep it dark to match the background clear color.
    // (User request) 2.5x brighter.
    let ambient = universe
        .world
        .add_component(engine::ecs::component::AmbientLightComponent::rgb(
            0.075, 0.075, 0.075,
        ));
    universe.add(ambient);

    // Input-driven camera rig.
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(2.0));
    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(2.0, 0.0, 7.0),
    );
    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z().with_roll_axis_y(),
    );
    let camera3d = universe.world.add_component(
        engine::ecs::component::Camera3DComponent::new()
            .with_far(250.0)
            .with_fov(70.0),
    );
    let _ = universe.attach(input, input_mode);
    let _ = universe.attach(input, rig_transform);
    let _ = universe.attach(rig_transform, camera3d);

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

    // Directional light (sun-ish). Note: the renderer interprets the node's world position
    // as a direction vector (see DirectionalLightComponent docs).
    let light_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.2, 0.7, 1.0),
    );
    let light = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_color(1.0, 1.0, 1.0)
            .with_intensity(0.35),
    );
    let _ = universe.attach(light_tx, light);
    universe.add(light_tx);

    // --- Background clouds (occluded + lit) ---
    // Mirrors the vtuber example: use a BackgroundComponent stage so the cloud volume
    // self-occludes and is lit, but renders as background.
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);
    let mut cloud_params = example_util::CloudRingParams::default();
    cloud_params.cloud_count = 7;
    cloud_params.radius = 22.0;
    // Move the ring up by ~one cloud height. The cloud generator uses a ~4.0 unit
    // vertical spread for puff offsets, so +4.0 is a good "one height" bump.
    cloud_params.center_y = 6.0;
    cloud_params.puffs_per_cloud = 26;
    cloud_params.angle_jitter = 0.0;
    cloud_params.high_y_probability = 0.0;
    cloud_params.high_y_multiplier = 1.0;
    cloud_params.seed = 0xA0_D1_0C_01u32;
    example_util::spawn_cloud_ring(&mut universe, bg_root, cloud_params);

    // ClockComponent sets global tempo.
    if audio_enabled {
        let clock = universe
            .world
            .add_component(engine::ecs::component::ClockComponent::new().with_bpm(128.0));
        universe.add(clock);
    }

    if audio_enabled {
        println!("[audio-graph-example] clock added");
    } else {
        println!("[audio-graph-example] audio disabled; skipping clock");
    }

    // Audio output + 2 oscillator sources.
    let audio_out = if audio_enabled {
        let audio_out_comp = if audio_output_enabled {
            engine::ecs::component::AudioOutputComponent::new()
        } else {
            engine::ecs::component::AudioOutputComponent::off()
        };
        let audio_out = universe.world.add_component(audio_out_comp);
        universe.add(audio_out);
        Some(audio_out)
    } else {
        None
    };

    match (audio_enabled, audio_output_enabled) {
        (false, _) => println!("[audio-graph-example] audio disabled; skipping audio output"),
        (true, true) => println!("[audio-graph-example] audio output added (CPAL on)"),
        (true, false) => println!("[audio-graph-example] audio output added (CPAL off)"),
    }

    // Track A: square lead.
    let osc_a_comp =
        if audio_enabled {
            let osc_a = engine::ecs::component::AudioOscillator::square()
                .with_frequency(110.0)
                .with_amplitude(0.12)
                .with_enabled(false);
            let osc_a_comp = universe.world.add_component(
                engine::ecs::component::AudioOscillatorComponent::single(osc_a),
            );
            if let Some(audio_out) = audio_out {
                let _ = universe.attach(audio_out, osc_a_comp);
            }
            Some(osc_a_comp)
        } else {
            None
        };

    if audio_enabled {
        println!("[audio-graph-example] track A created");
    } else {
        println!("[audio-graph-example] audio disabled; skipping track A");
    }

    // Effect tree A (single chain):
    // osc_a
    //   Gain
    //     BandPass
    //       Limiter
    let mut bp_a_comp: Option<engine::ecs::ComponentId> = None;
    if let Some(osc_a_comp) = osc_a_comp {
        let gain_a = universe
            .world
            .add_component(engine::ecs::component::AudioGainComponent::new(3.2));
        let bp_a = universe.world.add_component(
            engine::ecs::component::AudioBandPassFilterComponent::new(120.0, 3.0, 0.40),
        );
        bp_a_comp = Some(bp_a);
        let lim_a =
            universe
                .world
                .add_component(engine::ecs::component::AudioLimiterComponent::new(
                    4.0, 80.0, 0.90,
                ));

        let _ = universe.attach(osc_a_comp, gain_a);
        let _ = universe.attach(gain_a, bp_a);
        let _ = universe.attach(bp_a, lim_a);
    }

    if audio_enabled {
        println!("[audio-graph-example] track A effects attached");
    }

    // --- Visual layout helpers (copied/adapted from animation-example) ---
    fn spawn_text(
        universe: &mut engine::Universe,
        pos: (f32, f32, f32),
        scale: f32,
        wrap_cols: usize,
        text: &str,
    ) {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, 1.0),
        );
        let t =
            universe
                .world
                .add_component(engine::ecs::component::TextComponent::with_word_wrap(
                    text, wrap_cols,
                ));
        let _ = universe.attach(tx, t);

        // TextSystem looks for an immediate TextureFilteringComponent child.
        let filtering = universe
            .world
            .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
        let _ = universe.attach(t, filtering);

        // TextSystem also supports styling from immediate Emissive children.
        let emissive = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(t, emissive);

        universe.add(tx);
    }

    fn spawn_emissive_cube(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        pos: (f32, f32, f32),
        scale: f32,
        rgba: [f32; 4],
    ) {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, scale),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                rgba[0], rgba[1], rgba[2], rgba[3],
            ));
        let e = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, e);
    }

    fn spawn_op_cube(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        pos: (f32, f32, f32),
        scale: f32,
        base_rgba: [f32; 4],
    ) -> engine::ecs::ComponentId {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, scale),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                base_rgba[0],
                base_rgba[1],
                base_rgba[2],
                base_rgba[3],
            ));
        let e = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());

        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, e);

        tx
    }

    // --- HUD / lane (single track) ---
    let lane_x = -2.6_f32;
    let lane_title_z = -0.4_f32;
    let lane_cfg_z = -0.4_f32;
    let lane_pat_z = -1.3_f32;
    let lane_graph_z = -1.15_f32;

    // Content for pattern/chain/graph starts at x=0; keep section labels aligned there.
    // This also keeps them from overlapping the config block (which is anchored at lane_x).
    let lane_labels_x = lane_x + 1.6_f32;

    let track_a_y = 0.9_f32;

    spawn_text(
        &mut universe,
        (lane_x, track_a_y + 0.55, lane_title_z),
        0.09,
        42,
        "Track A: AudioOscillator::square()",
    );
    spawn_text(
        &mut universe,
        (lane_x, track_a_y + 0.25, lane_cfg_z),
        0.07,
        48,
        "oscillators=1\nfrequency_hz=110.0\namplitude=0.12\nenabled=false\nlookahead=0.10s",
    );

    let viz_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    universe.add(viz_root);

    println!("[audio-graph-example] viz root added");

    // Small identifier cubes next to titles.
    spawn_emissive_cube(
        &mut universe,
        viz_root,
        (lane_x - 0.28, track_a_y + 0.55, lane_title_z),
        0.16,
        [0.85, 0.40, 1.00, 1.0],
    );

    // Pattern roots so we can reset via one SetColor action.
    let track_a_pattern_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    let _ = universe.attach(viz_root, track_a_pattern_root);

    // Labels for pattern/chain/graph sections.
    spawn_text(
        &mut universe,
        (lane_labels_x, track_a_y, lane_title_z),
        0.06,
        42,
        "pattern",
    );
    spawn_text(
        &mut universe,
        (lane_labels_x, track_a_y - 0.40, lane_title_z),
        0.06,
        42,
        "graph",
    );

    // --- Processing chain + graph visualization (compiled graph → cubes + labels) ---
    use engine::ecs::system::audio_graph_compiler::{
        AudioGraphCompiler, AudioGraphNode, AudioGraphNodeKind,
    };

    fn effect_grey_for_depth(depth: usize) -> f32 {
        // depth=1 => medium grey; deeper => lighter, capped.
        let base = 0.55;
        let step = 0.13;
        let d = depth.saturating_sub(1) as f32;
        (base + step * d).min(0.92)
    }

    fn node_rgba(node: &AudioGraphNode, depth: usize) -> [f32; 4] {
        match node.kind {
            AudioGraphNodeKind::OscillatorSource { .. } => [1.0, 0.78, 0.22, 1.0],
            _ => {
                let g = effect_grey_for_depth(depth);
                [g, g, g, 1.0]
            }
        }
    }

    fn node_label(node: &AudioGraphNode) -> String {
        match &node.kind {
            AudioGraphNodeKind::OscillatorSource { voices } => {
                format!("OscillatorSource voices={voices}")
            }
            AudioGraphNodeKind::Gain { gain } => {
                format!("Gain gain={gain:.3}")
            }
            AudioGraphNodeKind::LowPass {
                cutoff_hz,
                resonance,
            } => {
                format!("LowPass cutoff={cutoff_hz:.1}Hz res={resonance:.3}")
            }
            AudioGraphNodeKind::BandPass {
                center_hz,
                bandwidth_octaves,
                resonance,
            } => {
                format!(
                    "BandPass center={center_hz:.1}Hz bw={bandwidth_octaves:.3}oct res={resonance:.3}"
                )
            }
            AudioGraphNodeKind::HighPass {
                cutoff_hz,
                resonance,
            } => {
                format!("HighPass cutoff={cutoff_hz:.1}Hz res={resonance:.3}")
            }
            AudioGraphNodeKind::Limiter {
                attack_ms,
                release_ms,
                threshold,
            } => {
                format!("Limiter atk={attack_ms:.1}ms rel={release_ms:.1}ms thr={threshold:.3}")
            }
            AudioGraphNodeKind::ClipSource => "ClipSource".to_string(),
        }
    }

    fn compute_layout(
        node: &AudioGraphNode,
        depth: usize,
        x_cursor: &mut i32,
        out: &mut std::collections::HashMap<*const AudioGraphNode, (i32, usize)>,
    ) -> i32 {
        // Depth-only layout:
        // - keep children directly below their parent on X
        // - use Z sibling offsets (in spawn_graph_tree) to show branching
        let _ = x_cursor;
        for ch in node.children.iter() {
            let _ = compute_layout(ch, depth + 1, x_cursor, out);
        }

        let my_x = 0;
        out.insert(node as *const AudioGraphNode, (my_x, depth));
        my_x
    }

    fn spawn_graph_tree(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        node: &AudioGraphNode,
        bp_component: Option<engine::ecs::ComponentId>,
        bp_label_out: &mut Option<engine::ecs::ComponentId>,
        origin: (f32, f32, f32),
        layout: &std::collections::HashMap<*const AudioGraphNode, (i32, usize)>,
        dx: f32,
        dy: f32,
        cube_scale: f32,
        sibling_index: usize,
        sibling_count: usize,
    ) {
        let Some((x_unit, depth)) = layout.get(&(node as *const AudioGraphNode)).copied() else {
            return;
        };

        let x = origin.0 + (x_unit as f32) * dx;
        let y = origin.1 - (depth as f32) * dy;

        // Push siblings “behind” each other along Z to reduce overlap between
        // a sibling's cube and another node's label.
        let dz_sibling = 0.18;
        let z = origin.2 - (sibling_index as f32) * dz_sibling;

        // Keep text slightly in front of its cube.
        let z_text = z + 0.03;

        let rgba = node_rgba(node, depth);
        let cube_tx = spawn_op_cube(universe, parent, (x, y, z), cube_scale, rgba);
        let _ = cube_tx;

        // Label next to the cube.
        let label = node_label(node);
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x + 0.14, y + 0.02, z_text)
                .with_scale(0.06, 0.06, 1.0),
        );
        let t =
            universe
                .world
                .add_component(engine::ecs::component::TextComponent::with_word_wrap(
                    &label, 25,
                ));
        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, t);

        if bp_component == Some(node.component) {
            *bp_label_out = Some(t);
        }

        let filtering = universe
            .world
            .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
        let _ = universe.attach(t, filtering);

        let emissive = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(t, emissive);

        universe.add(tx);

        // Mix/branch label if branching.
        if node.children.len() > 1 {
            let mut weights: Vec<f32> = Vec::with_capacity(node.children.len());
            for i in 0..node.children.len() {
                let w = node
                    .mix
                    .as_ref()
                    .map(|m| m.weights.get(i).copied().unwrap_or(1.0))
                    .unwrap_or(1.0);
                weights.push(w);
            }
            let mix_label = if node.mix.is_some() {
                format!("Mix weights={weights:?}")
            } else {
                format!("Mix <implicit> w={weights:?}")
            };
            let mix_tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(x + 0.14, y - 0.11, z_text)
                    .with_scale(0.05, 0.05, 1.0),
            );
            let mix_t = universe.world.add_component(
                engine::ecs::component::TextComponent::with_word_wrap(&mix_label, 25),
            );
            let _ = universe.attach(parent, mix_tx);
            let _ = universe.attach(mix_tx, mix_t);

            let filtering = universe
                .world
                .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
            let _ = universe.attach(mix_t, filtering);

            let emissive = universe
                .world
                .add_component(engine::ecs::component::EmissiveComponent::on());
            let _ = universe.attach(mix_t, emissive);

            universe.add(mix_tx);
        }

        let child_count = node.children.len().max(1);
        for (i, ch) in node.children.iter().enumerate() {
            // Each node's children form a sibling group; offset them in Z.
            // For the root node, sibling_index is 0.
            let _ = sibling_count;
            spawn_graph_tree(
                universe,
                parent,
                ch,
                bp_component,
                bp_label_out,
                origin,
                layout,
                dx,
                dy,
                cube_scale,
                i,
                child_count,
            );
        }
    }

    // Compile + display chain and graph for the track.
    let compiled_a = if audio_enabled {
        println!("[audio-graph-example] compiling graph...");
        let Some(osc_a_comp) = osc_a_comp else {
            panic!("audio_enabled but track A was not created");
        };
        let compiled_a =
            AudioGraphCompiler::compile(&universe.world, osc_a_comp).expect("compile A");
        println!("[audio-graph-example] graph compiled");
        Some(compiled_a)
    } else {
        println!("[audio-graph-example] audio disabled; skipping graph compilation");
        None
    };

    // Full compiled graph visualization (tree layout + mix labels).
    let mut bp_graph_label_text: Option<engine::ecs::ComponentId> = None;
    if let Some(compiled_a) = &compiled_a {
        let mut x_cursor = 0;
        let mut layout: std::collections::HashMap<*const AudioGraphNode, (i32, usize)> =
            std::collections::HashMap::new();
        let _root_x = compute_layout(&compiled_a.root, 0, &mut x_cursor, &mut layout);

        // With depth-only X layout, we keep the tree centered at x=0.
        // Pull the graph up now that we don't show the separate chain view.
        let origin = (0.0, track_a_y - 0.40, lane_graph_z);

        spawn_graph_tree(
            &mut universe,
            viz_root,
            &compiled_a.root,
            bp_a_comp,
            &mut bp_graph_label_text,
            origin,
            &layout,
            0.45,
            0.28,
            0.08,
            0,
            1,
        );
    } else {
        spawn_text(
            &mut universe,
            (0.0, track_a_y - 0.40, lane_graph_z),
            0.06,
            60,
            "(audio disabled)",
        );
    }

    // Animation with 16 keyframes drives scheduled notes + pattern highlights.
    let anim = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    let dur_a = 0.85_f32;
    let beat_spacing = 0.38_f32;

    let a_dark = [0.18, 0.08, 0.22, 1.0];
    let a_bright = [0.85, 0.40, 1.00, 1.0];

    for i in 0..16 {
        let kf_beat = i as f64;
        let kf = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(kf_beat));

        let _ = universe.attach(anim, kf);

        // Scheduled audio note (sample-accurate via lookahead).
        // Pulse every beat.
        if audio_enabled {
            let Some(osc_a_comp) = osc_a_comp else {
                panic!("audio_enabled but track A was not created");
            };

            let note_a = engine::ecs::component::MusicNote::c(1, dur_a).with_velocity(0.80);

            let act_a = universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::AudioSchedulePlay {
                        component_ids: vec![osc_a_comp],
                        beat_offset: 0.0,
                        beat_context: None,
                        note: Some(note_a),
                        gain: None,
                        rate: None,
                        duration: None,
                    },
                ));

            let _ = universe.attach(kf, act_a);
        }

        // Keyframed band-pass center.
        // This is an immediate parameter update applied RT-side (no graph rebuild).
        if audio_enabled {
            if let Some(bp_a_comp) = bp_a_comp {
                let t = (i as f32) / 15.0;
                let center_hz = 10.0 + t * (1000.0 - 10.0);

                let bp_center =
                    universe
                        .world
                        .add_component(engine::ecs::component::ActionComponent::new(
                            engine::ecs::IntentValue::AudioBandPassSetCenterHz {
                                component_ids: vec![bp_a_comp],
                                center_hz,
                            },
                        ));
                let _ = universe.attach(kf, bp_center);

                // Update the BandPass node label in the graph visualization.
                if let Some(text_id) = bp_graph_label_text {
                    let label =
                        universe
                            .world
                            .add_component(engine::ecs::component::ActionComponent::new(
                                engine::ecs::IntentValue::SetText {
                                    component_ids: vec![text_id],
                                    text: format!("BandPass center={center_hz:.1}Hz"),
                                },
                            ));
                    let _ = universe.attach(kf, label);
                }
            }
        }

        // Visualization reset per keyframe.
        let reset_a = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![track_a_pattern_root],
                    rgba: a_dark,
                },
            ));
        let _ = universe.attach(kf, reset_a);

        // Pattern cube per step for each track.
        let x = (kf_beat as f32) * beat_spacing;
        let cube_a = spawn_op_cube(
            &mut universe,
            track_a_pattern_root,
            (x, track_a_y, lane_pat_z),
            0.10,
            a_dark,
        );

        let bright_a = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![cube_a],
                    rgba: a_bright,
                },
            ));
        let _ = universe.attach(kf, bright_a);
    }
    universe.add(anim);

    println!("[audio-graph-example] animation created");

    // Keep window open.
    println!("[audio-graph-example] processing commands...");
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    println!("[audio-graph-example] commands processed; launching window");

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

Additional examples can be found in:

• examples/gravity-fields.rs

pub fn with_color(self, r: f32, g: f32, b: f32) -> Self

Examples found in repository

examples/vtuber-example.rs (line 65)

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

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

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

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

    // --- Camera rig (WASD + mouse) ---
    // InputComponent is the root, and it owns a Transform (the camera rig).
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(1.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

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

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

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

    universe.add(input);

    // --- lighting ---
    // Directional key light (slightly down + forward Z).
    let sun = universe.world.add_component(
        DirectionalLightComponent::new()
            .with_intensity(1.2)
            .with_color(1.0, 0.98, 0.94),
    );
    let sun_dir = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -0.35, 1.0));
    let _ = universe.attach(sun_dir, sun);
    universe.add(sun_dir);

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

    // --- VTuber model ---
    let model_root = universe.world.add_component(TransformComponent::new());
    let model = universe
        .world
        .add_component(GLTFComponent::new("assets/models/pc-rei.hoodie.glb"));
    // emissive for pc-rei
    let emissive = universe
        .world
        .add_component(engine::ecs::component::EmissiveComponent::on());

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

examples/background-occlusion-example.rs (line 77)

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

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

    // Light purple-red background so the occlusion reads.
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.62, 0.38, 0.56, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // A bit of ambient so the cluster volume reads.
    let ambient = universe
        .world
        .add_component(engine::ecs::component::AmbientLightComponent::rgb(
            0.20, 0.15, 0.3,
        ));
    universe.add(ambient);

    // --- Camera rig (WASD/QE) ---
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(2.0));
    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z().with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 6.0),
    );
    let _ = universe.attach(input, rig_transform);

    let camera3d = universe.world.add_component(
        engine::ecs::component::Camera3DComponent::new()
            .with_far(200.0)
            .with_fov(70.0),
    );
    let _ = universe.attach(rig_transform, camera3d);

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

    // Key directional light toward the cloud volume.
    //
    // Directional lights encode their direction in the node's world position.
    // The shader normalizes this vector.
    let sun = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_intensity(1.6)
            .with_color(1.0, 0.98, 0.92),
    );
    // Pointing from the clouds back toward the camera a bit (+Z), and slightly from above.
    let sun_dir = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.15, 0.65, 0.75),
    );
    let _ = universe.attach(sun_dir, sun);

    // A couple point lights to fill/shade the cloud volume.
    let light_a = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(80.0)
            .with_intensity(3.0)
            .with_color(0.9, 0.95, 1.0),
    );
    let light_a_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(8.0, 8.0, 5.0),
    );
    let _ = universe.attach(light_a_tx, light_a);

    let light_b = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(80.0)
            .with_intensity(2.2)
            .with_color(1.0, 0.9, 0.85),
    );
    let light_b_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(-10.0, 4.0, -6.0),
    );
    let _ = universe.attach(light_b_tx, light_b);

    universe.add(input);
    universe.add(sun_dir);
    universe.add(light_a_tx);
    universe.add(light_b_tx);

    let cube_mesh = universe
        .render_assets
        .get_mesh(engine::graphics::BuiltinMeshType::Cube);

    // --- Background occluded+lit world ---
    // Renderables under this node participate in a background stage that depth-writes for
    // self-occlusion + uses the normal lighting shader inputs.
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);

    // Create overlapping cube clusters like cloud puffs.
    // Place them generally in front of the camera (negative Z).
    // Spawn two groups on opposite X sides.
    let cluster_count: u32 = 9;
    for (group_i, group_x) in [-16.0_f32, 16.0_f32].into_iter().enumerate() {
        let group_tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(group_x, 0.0, 0.0),
        );
        let _ = universe.attach(bg_root, group_tx);

        for cluster_i in 0..cluster_count {
            let seed = (0xC10u32 ^ (group_i as u32).wrapping_mul(0x9E37_79B9))
                ^ (cluster_i.wrapping_mul(7919));

            let cx = (rand01(seed ^ 0xA341_316C) - 0.5) * 18.0;
            let cy = (rand01(seed ^ 0xC801_3EA4) - 0.5) * 10.0 + 2.0;
            let cz = -18.0 - rand01(seed ^ 0xB529_7A4D) * 26.0;

            let center_tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new().with_position(cx, cy, cz),
            );
            let _ = universe.attach(group_tx, center_tx);

            let puffs = 18u32;
            for puff_i in 0..puffs {
                let puff_seed = seed ^ puff_i.wrapping_mul(1_103_515_245);

                // Slightly ellipsoidal distribution.
                let ox = (rand01(puff_seed ^ 0x68bc_21eb) - 0.5) * 7.0;
                let oy = (rand01(puff_seed ^ 0x02e5_be93) - 0.5) * 3.0;
                let oz = (rand01(puff_seed ^ 0xa1d3_4f2b) - 0.5) * 7.0;

                let base = 0.7 + rand01(puff_seed ^ 0x9e37_79b9) * 2.6;
                let sx = base * (0.7 + rand01(puff_seed ^ 0x243f_6a88) * 0.8);
                let sy = base * (0.6 + rand01(puff_seed ^ 0x85a3_08d3) * 0.9);
                let sz = base * (0.7 + rand01(puff_seed ^ 0x1319_8a2e) * 0.8);

                let tx = universe.world.add_component(
                    engine::ecs::component::TransformComponent::new()
                        .with_position(ox, oy, oz)
                        .with_scale(sx, sy, sz),
                );
                let renderable =
                    universe
                        .world
                        .add_component(engine::ecs::component::RenderableComponent::new(
                            engine::graphics::primitives::Renderable::new(
                                cube_mesh,
                                engine::graphics::primitives::MaterialHandle::TOON_MESH,
                            ),
                        ));

                // Slight blue-grey variation.
                let t = rand01(puff_seed ^ 0x7f4a_7c15);
                let r = 0.55 + 0.10 * t;
                let g = 0.58 + 0.10 * t;
                let b = 0.66 + 0.12 * t;
                let color = universe
                    .world
                    .add_component(engine::ecs::component::ColorComponent::rgba(r, g, b, 1.0));

                let _ = universe.attach(center_tx, tx);
                let _ = universe.attach(tx, renderable);
                let _ = universe.attach(renderable, color);
            }
        }
    }

    // Foreground reference cube (should never be occluded by background depth).
    let fg_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new()
            .with_position(0.0, -0.5, -4.0)
            .with_scale(1.2, 0.8, 1.2),
    );
    let fg_renderable =
        universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::new(
                engine::graphics::primitives::Renderable::new(
                    cube_mesh,
                    engine::graphics::primitives::MaterialHandle::TOON_MESH,
                ),
            ));
    let fg_color = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.9, 0.2, 0.2, 1.0,
        ));

    universe.add(fg_tx);
    let _ = universe.attach(fg_tx, fg_renderable);
    let _ = universe.attach(fg_renderable, fg_color);

    // Foreground opaque floor: 16x16 larger white cubes, 10 units below the reference cube.
    let floor_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, -10.5, -10.0),
    );
    universe.add(floor_root);

    let spacing = 10_f32;
    let half = 5_f32;
    for x in 0..16u32 {
        for z in 0..64u32 {
            let px = (x as f32 - half) * spacing;
            let pz = (z as f32 * -1.0 + half) * spacing;
            let tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(px, -5.0, pz)
                    .with_scale(5.0, 0.5, 5.0),
            );
            let renderable =
                universe
                    .world
                    .add_component(engine::ecs::component::RenderableComponent::new(
                        engine::graphics::primitives::Renderable::new(
                            cube_mesh,
                            engine::graphics::primitives::MaterialHandle::TOON_MESH,
                        ),
                    ));
            let color = universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

            let _ = universe.attach(floor_root, tx);
            let _ = universe.attach(tx, renderable);
            let _ = universe.attach(renderable, color);
        }
    }

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

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

examples/vr-input.rs (line 251)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(xr_input);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

examples/font-example.rs (line 41)

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

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

    // Dark background so the font texture pops.
    let background = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let background_c = universe
        .world
        .add_component(ColorComponent::rgba(0.20, 0.2, 0.20, 1.0));
    let _ = universe.world.add_child(background, background_c);
    universe.add(background);

    // Ambient so text is readable even without explicit lights.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.50, 0.50, 0.50));
    universe.add(ambient);

    let directional_tx = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.5, 1.0));
    let directional_light = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_color(1.0, 1.0, 1.0)
            .with_intensity(0.8),
    );
    let _ = universe.attach(directional_tx, directional_light);
    universe.add(directional_tx);

    // --- background clouds ---
    // Background stage (occluded + lit) so the cloud volume self-occludes but won't occlude
    // the foreground text (renderer clears depth before foreground).
    let bg_root = universe
        .world
        .add_component(BackgroundComponent::new().with_occlusion_and_lighting());
    universe.add(bg_root);

    let mut bg_cloud_params = example_util::CloudRingParams::default();
    bg_cloud_params.cloud_count = 6;
    bg_cloud_params.seed = 0xF0_17_C10u32;
    example_util::spawn_cloud_ring(&mut universe, bg_root, bg_cloud_params);

    // I {
    //   // not fps rotation, just relative rotation
    //   with_forward_z()
    //   with_roll_axis_y()
    //   C3D {}
    // }
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(2.0));
    let input_mode = universe
        .world
        .add_component(InputTransformModeComponent::forward_z().with_roll_axis_y());
    let _ = universe.attach(input, input_mode);

    let rig_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(1.8, -0.5, 2.5));
    let _ = universe.attach(input, rig_transform);

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

    // Click-to-pick: treat this camera rig as a pointer source.
    let pointer = universe.world.add_component(PointerComponent::new());
    let _ = universe.attach(camera, pointer);

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

    universe.add(input);

    // --- foreground clouds ---
    // Normal foreground renderables (not background stage).
    // Offset the ring forward (negative Z) so several clusters are in view.
    let fg_cloud_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, -6.0, -10.0));
    universe.add(fg_cloud_root);

    let mut fg_cloud_params = example_util::CloudRingParams::default();
    fg_cloud_params.cloud_count = 4;
    fg_cloud_params.radius = 9.0;
    fg_cloud_params.center_y = 1.0;
    fg_cloud_params.puffs_per_cloud = 22;
    fg_cloud_params.angle_jitter = 0.35;
    fg_cloud_params.high_y_probability = 0.35;
    fg_cloud_params.high_y_multiplier = 1.4;
    fg_cloud_params.seed = 0xF0_17_C102u32;
    example_util::spawn_cloud_ring(&mut universe, fg_cloud_root, fg_cloud_params);

    // T {
    //   with_translation(0,0, -2)
    //   TXT {
    //     "ababaabbaabbaaabbbaaabbbaaaabbbbaaaaabbbbbababababa"
    //     TextureComponent { assets/images/test.font_system.png }
    //   }
    // }
    fn estimate_text_height_world(text: &str, scale: f32) -> f32 {
        let line_count = text.lines().count().max(1) as f32;
        // Text quads are ~1 unit tall per line in text-space.
        // Add some padding so blocks don't feel cramped.
        let pad_lines = 1.25;
        (line_count + pad_lines) * scale
    }

    fn spawn_text_block(
        universe: &mut engine::Universe,
        position: (f32, f32, f32),
        scale: f32,
        text: &str,
        font_texture_uri: Option<&str>,
        text_color_rgba: Option<[f32; 4]>,
        shadow: Option<TextShadowComponent>,
        filtering: TextureFilteringComponent,
    ) -> f32 {
        // T_root { T_scale { [Color] { TXT { shadow, filtering } } } }
        let text_root = universe.world.add_component(
            TransformComponent::new().with_position(position.0, position.1, position.2),
        );

        let text_scale = universe
            .world
            .add_component(TransformComponent::new().with_scale(scale, scale, 1.0));
        let _ = universe.attach(text_root, text_scale);

        let text_parent = if let Some([r, g, b, a]) = text_color_rgba {
            let color = universe
                .world
                .add_component(ColorComponent::rgba(r, g, b, a));
            let _ = universe.attach(text_scale, color);
            color
        } else {
            text_scale
        };

        let text_c = universe.world.add_component(TextComponent::new(text));
        let _ = universe.attach(text_parent, text_c);

        // Explicit opt-in: make the glyph renderables pickable.
        // TextSystem will propagate this to all spawned glyph quads.
        let raycastable = universe
            .world
            .add_component(RaycastableComponent::enabled());
        let _ = universe.attach(text_c, raycastable);

        // Route glyph quads into the alpha-to-coverage cutout pass.
        let cutout = universe
            .world
            .add_component(TransparentCutoutComponent::new());
        let _ = universe.attach(text_c, cutout);

        if let Some(shadow) = shadow {
            let shadow_id = universe.world.add_component(shadow);
            let _ = universe.attach(text_c, shadow_id);
        }

        // Optional: override the font atlas for this text block.
        // TextSystem will propagate this to all glyph renderables.
        if let Some(uri) = font_texture_uri {
            let tex = universe
                .world
                .add_component(TextureComponent::with_uri(uri));
            let _ = universe.attach(text_c, tex);
        }

        let filtering_id = universe.world.add_component(filtering);
        let _ = universe.attach(text_c, filtering_id);

        universe.add(text_root);

        estimate_text_height_world(text, scale)
    }

    // --- text blocks ---
    // Multi-line samples at different scales.
    // (Text literals omitted in the README/snippet; see constants below.)
    const TEXT_BIG: &str = "CAT ENGINE\nfont example\nBIG TEXT";
    const TEXT_MED: &str = "multi-line\ntext block\nmedium";
    const TEXT_SMALL: &str = "small\ntext";
    const TEXT_TINY: &str = "tiny\ntext\n(zoom in)";

    // Stack vertically; advance by (measured height + gap) so big text gets more room.
    let x = -1.2;
    let z = -2.0;
    let mut y = 1.2;
    let gap = 0.15;

    let shadow_crisp = Some(
        TextShadowComponent::new()
            .with_scale(1.35)
            .with_offset([0.06, -0.06, 0.0015]),
    );

    y -= spawn_text_block(
        &mut universe,
        (x, y, z),
        0.55,
        TEXT_BIG,
        None,
        Some([1.0, 1.0, 1.0, 1.0]),
        shadow_crisp,
        TextureFilteringComponent::nearest_magnification(),
    ) + gap;
    y -= spawn_text_block(
        &mut universe,
        (x, y, z),
        0.25,
        TEXT_MED,
        None,
        Some([0.60, 0.95, 1.00, 1.0]),
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.15, 1.0])
                .with_scale(1.20)
                .with_offset([0.05, -0.04, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    y -= spawn_text_block(
        &mut universe,
        (x, y, z),
        0.14,
        TEXT_SMALL,
        None,
        Some([1.0, 0.88, 0.35, 1.0]),
        Some(
            TextShadowComponent::new()
                .with_rgba([0.15, 0.0, 0.0, 1.0])
                .with_scale(1.55)
                .with_offset([0.08, -0.08, 0.0015]),
        ),
        TextureFilteringComponent::nearest(),
    ) + gap;
    let _ = spawn_text_block(
        &mut universe,
        (x, y, z),
        0.08,
        TEXT_TINY,
        None,
        Some([0.90, 1.0, 0.70, 1.0]),
        shadow_crisp,
        TextureFilteringComponent::nearest_magnification(),
    );

    // Left block: explicit multi-line text using the default font_system atlas.
    const TEXT_LEFT: &str = "even though there's hexes\nto the solar plexus in my lexus\ni'm feelin' reckless,\nwhen i'm eating breakfast";
    let _ = spawn_text_block(
        &mut universe,
        (x - 8.1, 1.1, z),
        0.22,
        TEXT_LEFT,
        Some("assets/textures/font_system.dds"),
        Some([0.95, 0.95, 0.95, 1.0]),
        Some(
            TextShadowComponent::new()
                .with_scale(1.25)
                .with_offset([0.05, -0.05, 0.0015]),
        ),
        TextureFilteringComponent::nearest_magnification(),
    );

    // Alt atlas: put it *behind* the original stack (slightly farther from the camera)
    // and tint it dark grey.
    let alt_atlas = Some("assets/textures/font_system.0.0.dds");
    let alt_z = z - 0.05;
    let alt_grey = Some([0.25, 0.25, 0.25, 1.0]);

    let mut y_alt = 1.2;
    y_alt -= spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.55,
        TEXT_BIG,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    y_alt -= spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.25,
        TEXT_MED,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    y_alt -= spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.14,
        TEXT_SMALL,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    ) + gap;
    let _ = spawn_text_block(
        &mut universe,
        (x, y_alt, alt_z),
        0.08,
        TEXT_TINY,
        alt_atlas,
        alt_grey,
        Some(
            TextShadowComponent::new()
                .with_rgba([0.0, 0.0, 0.0, 1.0])
                .with_scale(1.15)
                .with_offset([0.03, -0.03, 0.0015]),
        ),
        TextureFilteringComponent::linear(),
    );

    universe.enable_repl();

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

    // Add an OpenXR component so OpenXRSystem initializes and starts polling events.
    let xr_root = universe
        .world
        .add_component(engine::ecs::component::XrComponent::on());
    universe.add(xr_root);

    // Process init-time registrations (Text expands into glyph subtrees here).
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    let print_transform_updates: bool = false;

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

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

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

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

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

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

examples/audio-graph-example.rs (line 84)

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

    // Debug toggle: allow isolating stack overflows to audio vs. non-audio init.
    // Set `CAT_AUDIO_EXAMPLE_DISABLE_AUDIO=1` to skip creating audio components and
    // skip scheduling audio notes. The UI/text/cube visualization will still spawn.
    let audio_enabled = std::env::var("CAT_AUDIO_EXAMPLE_DISABLE_AUDIO")
        .ok()
        .as_deref()
        != Some("1");

    // If set, we still build audio graph components but we don't start the CPAL output stream.
    // This helps distinguish "audio graph / scheduling" issues from "CPAL backend" issues.
    let audio_output_enabled = std::env::var("CAT_AUDIO_EXAMPLE_AUDIO_OUTPUT_OFF")
        .ok()
        .as_deref()
        != Some("1");

    println!("[audio-graph-example] start");

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

    println!("[audio-graph-example] universe created");

    // Minimal scene with a camera so the window opens (copied from animation-example).
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.07, 0.07, 0.07, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // Ambient light so unlit areas aren't pitch black.
    // Keep it dark to match the background clear color.
    // (User request) 2.5x brighter.
    let ambient = universe
        .world
        .add_component(engine::ecs::component::AmbientLightComponent::rgb(
            0.075, 0.075, 0.075,
        ));
    universe.add(ambient);

    // Input-driven camera rig.
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(2.0));
    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(2.0, 0.0, 7.0),
    );
    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z().with_roll_axis_y(),
    );
    let camera3d = universe.world.add_component(
        engine::ecs::component::Camera3DComponent::new()
            .with_far(250.0)
            .with_fov(70.0),
    );
    let _ = universe.attach(input, input_mode);
    let _ = universe.attach(input, rig_transform);
    let _ = universe.attach(rig_transform, camera3d);

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

    // Directional light (sun-ish). Note: the renderer interprets the node's world position
    // as a direction vector (see DirectionalLightComponent docs).
    let light_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.2, 0.7, 1.0),
    );
    let light = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_color(1.0, 1.0, 1.0)
            .with_intensity(0.35),
    );
    let _ = universe.attach(light_tx, light);
    universe.add(light_tx);

    // --- Background clouds (occluded + lit) ---
    // Mirrors the vtuber example: use a BackgroundComponent stage so the cloud volume
    // self-occludes and is lit, but renders as background.
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);
    let mut cloud_params = example_util::CloudRingParams::default();
    cloud_params.cloud_count = 7;
    cloud_params.radius = 22.0;
    // Move the ring up by ~one cloud height. The cloud generator uses a ~4.0 unit
    // vertical spread for puff offsets, so +4.0 is a good "one height" bump.
    cloud_params.center_y = 6.0;
    cloud_params.puffs_per_cloud = 26;
    cloud_params.angle_jitter = 0.0;
    cloud_params.high_y_probability = 0.0;
    cloud_params.high_y_multiplier = 1.0;
    cloud_params.seed = 0xA0_D1_0C_01u32;
    example_util::spawn_cloud_ring(&mut universe, bg_root, cloud_params);

    // ClockComponent sets global tempo.
    if audio_enabled {
        let clock = universe
            .world
            .add_component(engine::ecs::component::ClockComponent::new().with_bpm(128.0));
        universe.add(clock);
    }

    if audio_enabled {
        println!("[audio-graph-example] clock added");
    } else {
        println!("[audio-graph-example] audio disabled; skipping clock");
    }

    // Audio output + 2 oscillator sources.
    let audio_out = if audio_enabled {
        let audio_out_comp = if audio_output_enabled {
            engine::ecs::component::AudioOutputComponent::new()
        } else {
            engine::ecs::component::AudioOutputComponent::off()
        };
        let audio_out = universe.world.add_component(audio_out_comp);
        universe.add(audio_out);
        Some(audio_out)
    } else {
        None
    };

    match (audio_enabled, audio_output_enabled) {
        (false, _) => println!("[audio-graph-example] audio disabled; skipping audio output"),
        (true, true) => println!("[audio-graph-example] audio output added (CPAL on)"),
        (true, false) => println!("[audio-graph-example] audio output added (CPAL off)"),
    }

    // Track A: square lead.
    let osc_a_comp =
        if audio_enabled {
            let osc_a = engine::ecs::component::AudioOscillator::square()
                .with_frequency(110.0)
                .with_amplitude(0.12)
                .with_enabled(false);
            let osc_a_comp = universe.world.add_component(
                engine::ecs::component::AudioOscillatorComponent::single(osc_a),
            );
            if let Some(audio_out) = audio_out {
                let _ = universe.attach(audio_out, osc_a_comp);
            }
            Some(osc_a_comp)
        } else {
            None
        };

    if audio_enabled {
        println!("[audio-graph-example] track A created");
    } else {
        println!("[audio-graph-example] audio disabled; skipping track A");
    }

    // Effect tree A (single chain):
    // osc_a
    //   Gain
    //     BandPass
    //       Limiter
    let mut bp_a_comp: Option<engine::ecs::ComponentId> = None;
    if let Some(osc_a_comp) = osc_a_comp {
        let gain_a = universe
            .world
            .add_component(engine::ecs::component::AudioGainComponent::new(3.2));
        let bp_a = universe.world.add_component(
            engine::ecs::component::AudioBandPassFilterComponent::new(120.0, 3.0, 0.40),
        );
        bp_a_comp = Some(bp_a);
        let lim_a =
            universe
                .world
                .add_component(engine::ecs::component::AudioLimiterComponent::new(
                    4.0, 80.0, 0.90,
                ));

        let _ = universe.attach(osc_a_comp, gain_a);
        let _ = universe.attach(gain_a, bp_a);
        let _ = universe.attach(bp_a, lim_a);
    }

    if audio_enabled {
        println!("[audio-graph-example] track A effects attached");
    }

    // --- Visual layout helpers (copied/adapted from animation-example) ---
    fn spawn_text(
        universe: &mut engine::Universe,
        pos: (f32, f32, f32),
        scale: f32,
        wrap_cols: usize,
        text: &str,
    ) {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, 1.0),
        );
        let t =
            universe
                .world
                .add_component(engine::ecs::component::TextComponent::with_word_wrap(
                    text, wrap_cols,
                ));
        let _ = universe.attach(tx, t);

        // TextSystem looks for an immediate TextureFilteringComponent child.
        let filtering = universe
            .world
            .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
        let _ = universe.attach(t, filtering);

        // TextSystem also supports styling from immediate Emissive children.
        let emissive = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(t, emissive);

        universe.add(tx);
    }

    fn spawn_emissive_cube(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        pos: (f32, f32, f32),
        scale: f32,
        rgba: [f32; 4],
    ) {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, scale),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                rgba[0], rgba[1], rgba[2], rgba[3],
            ));
        let e = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, e);
    }

    fn spawn_op_cube(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        pos: (f32, f32, f32),
        scale: f32,
        base_rgba: [f32; 4],
    ) -> engine::ecs::ComponentId {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, scale),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                base_rgba[0],
                base_rgba[1],
                base_rgba[2],
                base_rgba[3],
            ));
        let e = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());

        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, e);

        tx
    }

    // --- HUD / lane (single track) ---
    let lane_x = -2.6_f32;
    let lane_title_z = -0.4_f32;
    let lane_cfg_z = -0.4_f32;
    let lane_pat_z = -1.3_f32;
    let lane_graph_z = -1.15_f32;

    // Content for pattern/chain/graph starts at x=0; keep section labels aligned there.
    // This also keeps them from overlapping the config block (which is anchored at lane_x).
    let lane_labels_x = lane_x + 1.6_f32;

    let track_a_y = 0.9_f32;

    spawn_text(
        &mut universe,
        (lane_x, track_a_y + 0.55, lane_title_z),
        0.09,
        42,
        "Track A: AudioOscillator::square()",
    );
    spawn_text(
        &mut universe,
        (lane_x, track_a_y + 0.25, lane_cfg_z),
        0.07,
        48,
        "oscillators=1\nfrequency_hz=110.0\namplitude=0.12\nenabled=false\nlookahead=0.10s",
    );

    let viz_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    universe.add(viz_root);

    println!("[audio-graph-example] viz root added");

    // Small identifier cubes next to titles.
    spawn_emissive_cube(
        &mut universe,
        viz_root,
        (lane_x - 0.28, track_a_y + 0.55, lane_title_z),
        0.16,
        [0.85, 0.40, 1.00, 1.0],
    );

    // Pattern roots so we can reset via one SetColor action.
    let track_a_pattern_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    let _ = universe.attach(viz_root, track_a_pattern_root);

    // Labels for pattern/chain/graph sections.
    spawn_text(
        &mut universe,
        (lane_labels_x, track_a_y, lane_title_z),
        0.06,
        42,
        "pattern",
    );
    spawn_text(
        &mut universe,
        (lane_labels_x, track_a_y - 0.40, lane_title_z),
        0.06,
        42,
        "graph",
    );

    // --- Processing chain + graph visualization (compiled graph → cubes + labels) ---
    use engine::ecs::system::audio_graph_compiler::{
        AudioGraphCompiler, AudioGraphNode, AudioGraphNodeKind,
    };

    fn effect_grey_for_depth(depth: usize) -> f32 {
        // depth=1 => medium grey; deeper => lighter, capped.
        let base = 0.55;
        let step = 0.13;
        let d = depth.saturating_sub(1) as f32;
        (base + step * d).min(0.92)
    }

    fn node_rgba(node: &AudioGraphNode, depth: usize) -> [f32; 4] {
        match node.kind {
            AudioGraphNodeKind::OscillatorSource { .. } => [1.0, 0.78, 0.22, 1.0],
            _ => {
                let g = effect_grey_for_depth(depth);
                [g, g, g, 1.0]
            }
        }
    }

    fn node_label(node: &AudioGraphNode) -> String {
        match &node.kind {
            AudioGraphNodeKind::OscillatorSource { voices } => {
                format!("OscillatorSource voices={voices}")
            }
            AudioGraphNodeKind::Gain { gain } => {
                format!("Gain gain={gain:.3}")
            }
            AudioGraphNodeKind::LowPass {
                cutoff_hz,
                resonance,
            } => {
                format!("LowPass cutoff={cutoff_hz:.1}Hz res={resonance:.3}")
            }
            AudioGraphNodeKind::BandPass {
                center_hz,
                bandwidth_octaves,
                resonance,
            } => {
                format!(
                    "BandPass center={center_hz:.1}Hz bw={bandwidth_octaves:.3}oct res={resonance:.3}"
                )
            }
            AudioGraphNodeKind::HighPass {
                cutoff_hz,
                resonance,
            } => {
                format!("HighPass cutoff={cutoff_hz:.1}Hz res={resonance:.3}")
            }
            AudioGraphNodeKind::Limiter {
                attack_ms,
                release_ms,
                threshold,
            } => {
                format!("Limiter atk={attack_ms:.1}ms rel={release_ms:.1}ms thr={threshold:.3}")
            }
            AudioGraphNodeKind::ClipSource => "ClipSource".to_string(),
        }
    }

    fn compute_layout(
        node: &AudioGraphNode,
        depth: usize,
        x_cursor: &mut i32,
        out: &mut std::collections::HashMap<*const AudioGraphNode, (i32, usize)>,
    ) -> i32 {
        // Depth-only layout:
        // - keep children directly below their parent on X
        // - use Z sibling offsets (in spawn_graph_tree) to show branching
        let _ = x_cursor;
        for ch in node.children.iter() {
            let _ = compute_layout(ch, depth + 1, x_cursor, out);
        }

        let my_x = 0;
        out.insert(node as *const AudioGraphNode, (my_x, depth));
        my_x
    }

    fn spawn_graph_tree(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        node: &AudioGraphNode,
        bp_component: Option<engine::ecs::ComponentId>,
        bp_label_out: &mut Option<engine::ecs::ComponentId>,
        origin: (f32, f32, f32),
        layout: &std::collections::HashMap<*const AudioGraphNode, (i32, usize)>,
        dx: f32,
        dy: f32,
        cube_scale: f32,
        sibling_index: usize,
        sibling_count: usize,
    ) {
        let Some((x_unit, depth)) = layout.get(&(node as *const AudioGraphNode)).copied() else {
            return;
        };

        let x = origin.0 + (x_unit as f32) * dx;
        let y = origin.1 - (depth as f32) * dy;

        // Push siblings “behind” each other along Z to reduce overlap between
        // a sibling's cube and another node's label.
        let dz_sibling = 0.18;
        let z = origin.2 - (sibling_index as f32) * dz_sibling;

        // Keep text slightly in front of its cube.
        let z_text = z + 0.03;

        let rgba = node_rgba(node, depth);
        let cube_tx = spawn_op_cube(universe, parent, (x, y, z), cube_scale, rgba);
        let _ = cube_tx;

        // Label next to the cube.
        let label = node_label(node);
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x + 0.14, y + 0.02, z_text)
                .with_scale(0.06, 0.06, 1.0),
        );
        let t =
            universe
                .world
                .add_component(engine::ecs::component::TextComponent::with_word_wrap(
                    &label, 25,
                ));
        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, t);

        if bp_component == Some(node.component) {
            *bp_label_out = Some(t);
        }

        let filtering = universe
            .world
            .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
        let _ = universe.attach(t, filtering);

        let emissive = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(t, emissive);

        universe.add(tx);

        // Mix/branch label if branching.
        if node.children.len() > 1 {
            let mut weights: Vec<f32> = Vec::with_capacity(node.children.len());
            for i in 0..node.children.len() {
                let w = node
                    .mix
                    .as_ref()
                    .map(|m| m.weights.get(i).copied().unwrap_or(1.0))
                    .unwrap_or(1.0);
                weights.push(w);
            }
            let mix_label = if node.mix.is_some() {
                format!("Mix weights={weights:?}")
            } else {
                format!("Mix <implicit> w={weights:?}")
            };
            let mix_tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(x + 0.14, y - 0.11, z_text)
                    .with_scale(0.05, 0.05, 1.0),
            );
            let mix_t = universe.world.add_component(
                engine::ecs::component::TextComponent::with_word_wrap(&mix_label, 25),
            );
            let _ = universe.attach(parent, mix_tx);
            let _ = universe.attach(mix_tx, mix_t);

            let filtering = universe
                .world
                .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
            let _ = universe.attach(mix_t, filtering);

            let emissive = universe
                .world
                .add_component(engine::ecs::component::EmissiveComponent::on());
            let _ = universe.attach(mix_t, emissive);

            universe.add(mix_tx);
        }

        let child_count = node.children.len().max(1);
        for (i, ch) in node.children.iter().enumerate() {
            // Each node's children form a sibling group; offset them in Z.
            // For the root node, sibling_index is 0.
            let _ = sibling_count;
            spawn_graph_tree(
                universe,
                parent,
                ch,
                bp_component,
                bp_label_out,
                origin,
                layout,
                dx,
                dy,
                cube_scale,
                i,
                child_count,
            );
        }
    }

    // Compile + display chain and graph for the track.
    let compiled_a = if audio_enabled {
        println!("[audio-graph-example] compiling graph...");
        let Some(osc_a_comp) = osc_a_comp else {
            panic!("audio_enabled but track A was not created");
        };
        let compiled_a =
            AudioGraphCompiler::compile(&universe.world, osc_a_comp).expect("compile A");
        println!("[audio-graph-example] graph compiled");
        Some(compiled_a)
    } else {
        println!("[audio-graph-example] audio disabled; skipping graph compilation");
        None
    };

    // Full compiled graph visualization (tree layout + mix labels).
    let mut bp_graph_label_text: Option<engine::ecs::ComponentId> = None;
    if let Some(compiled_a) = &compiled_a {
        let mut x_cursor = 0;
        let mut layout: std::collections::HashMap<*const AudioGraphNode, (i32, usize)> =
            std::collections::HashMap::new();
        let _root_x = compute_layout(&compiled_a.root, 0, &mut x_cursor, &mut layout);

        // With depth-only X layout, we keep the tree centered at x=0.
        // Pull the graph up now that we don't show the separate chain view.
        let origin = (0.0, track_a_y - 0.40, lane_graph_z);

        spawn_graph_tree(
            &mut universe,
            viz_root,
            &compiled_a.root,
            bp_a_comp,
            &mut bp_graph_label_text,
            origin,
            &layout,
            0.45,
            0.28,
            0.08,
            0,
            1,
        );
    } else {
        spawn_text(
            &mut universe,
            (0.0, track_a_y - 0.40, lane_graph_z),
            0.06,
            60,
            "(audio disabled)",
        );
    }

    // Animation with 16 keyframes drives scheduled notes + pattern highlights.
    let anim = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    let dur_a = 0.85_f32;
    let beat_spacing = 0.38_f32;

    let a_dark = [0.18, 0.08, 0.22, 1.0];
    let a_bright = [0.85, 0.40, 1.00, 1.0];

    for i in 0..16 {
        let kf_beat = i as f64;
        let kf = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(kf_beat));

        let _ = universe.attach(anim, kf);

        // Scheduled audio note (sample-accurate via lookahead).
        // Pulse every beat.
        if audio_enabled {
            let Some(osc_a_comp) = osc_a_comp else {
                panic!("audio_enabled but track A was not created");
            };

            let note_a = engine::ecs::component::MusicNote::c(1, dur_a).with_velocity(0.80);

            let act_a = universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::AudioSchedulePlay {
                        component_ids: vec![osc_a_comp],
                        beat_offset: 0.0,
                        beat_context: None,
                        note: Some(note_a),
                        gain: None,
                        rate: None,
                        duration: None,
                    },
                ));

            let _ = universe.attach(kf, act_a);
        }

        // Keyframed band-pass center.
        // This is an immediate parameter update applied RT-side (no graph rebuild).
        if audio_enabled {
            if let Some(bp_a_comp) = bp_a_comp {
                let t = (i as f32) / 15.0;
                let center_hz = 10.0 + t * (1000.0 - 10.0);

                let bp_center =
                    universe
                        .world
                        .add_component(engine::ecs::component::ActionComponent::new(
                            engine::ecs::IntentValue::AudioBandPassSetCenterHz {
                                component_ids: vec![bp_a_comp],
                                center_hz,
                            },
                        ));
                let _ = universe.attach(kf, bp_center);

                // Update the BandPass node label in the graph visualization.
                if let Some(text_id) = bp_graph_label_text {
                    let label =
                        universe
                            .world
                            .add_component(engine::ecs::component::ActionComponent::new(
                                engine::ecs::IntentValue::SetText {
                                    component_ids: vec![text_id],
                                    text: format!("BandPass center={center_hz:.1}Hz"),
                                },
                            ));
                    let _ = universe.attach(kf, label);
                }
            }
        }

        // Visualization reset per keyframe.
        let reset_a = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![track_a_pattern_root],
                    rgba: a_dark,
                },
            ));
        let _ = universe.attach(kf, reset_a);

        // Pattern cube per step for each track.
        let x = (kf_beat as f32) * beat_spacing;
        let cube_a = spawn_op_cube(
            &mut universe,
            track_a_pattern_root,
            (x, track_a_y, lane_pat_z),
            0.10,
            a_dark,
        );

        let bright_a = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![cube_a],
                    rgba: a_bright,
                },
            ));
        let _ = universe.attach(kf, bright_a);
    }
    universe.add(anim);

    println!("[audio-graph-example] animation created");

    // Keep window open.
    println!("[audio-graph-example] processing commands...");
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    println!("[audio-graph-example] commands processed; launching window");

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

Additional examples can be found in:

• examples/gravity-fields.rs

pub fn id(&self) -> Option<ComponentId>

Trait Implementations

impl Clone for DirectionalLightComponent

fn clone(&self) -> DirectionalLightComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for DirectionalLightComponent

fn set_id(&mut self, component: ComponentId)

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

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

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 Copy for DirectionalLightComponent

impl Debug for DirectionalLightComponent

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

Formats the value using the given formatter.

impl Default for DirectionalLightComponent

fn default() -> Self

Returns the “default value” for a type.