Struct AnimationComponent 

pub struct AnimationComponent {
    pub state: AnimationState,
    pub resolve_targets: ResolveTargetsMode,
    pub length_beats: Option<f64>,
    pub scope_source: Option<ComponentRef>,
    pub resolved_scope: Option<ComponentId>,
    /* private fields */
}

Fields

state: AnimationState

resolve_targets: ResolveTargetsMode

length_beats: Option<f64>

Explicit loop length in beats. None falls back to the derived default in AnimationSystem (floor(max_keyframe_beat) + 1). Authored via Animation.length(beats).

scope_source: Option<ComponentRef>

resolved_scope: Option<ComponentId>

Implementations

impl AnimationComponent

pub fn new() -> Self

Examples found in repository

examples/mesh-factory-example.rs (line 81)

    fn spawn_labeled_mesh(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        label: &str,
        mesh: engine::graphics::primitives::CpuMeshHandle,
        scale: [f32; 3],
        color: [f32; 4],
    ) {
        use engine::ecs::component::{
            ActionComponent, AnimationComponent, AnimationState, ColorComponent, EmissiveComponent,
            KeyframeComponent, RenderableComponent, TextComponent, TransformComponent,
        };
        use engine::graphics::primitives::{MaterialHandle, Renderable};

        // Mesh.
        let root = universe.world.add_component(
            TransformComponent::new()
                .with_position(x, y, 0.0)
                .with_scale(scale[0], scale[1], scale[2]),
        );

        // Spin each shape around its own +Y axis using AnimationComponent + keyframes.
        // We fill [0, 2) beats densely so it looks smooth.
        let anim = universe
            .world
            .add_component(AnimationComponent::new().with_state(AnimationState::Looping));
        let _ = universe.attach(root, anim);

        let steps: usize = 64;
        for i in 0..steps {
            let beat = (i as f64) * (2.0 / (steps as f64));
            let kf = universe.world.add_component(KeyframeComponent::new(beat));
            let _ = universe.attach(anim, kf);

            // Full turn over 2 beats.
            let angle = (std::f64::consts::TAU * (beat / 2.0)) as f32;
            let rotation = utils::math::quat_from_axis_angle([0.0, 1.0, 0.0], angle);

            let action_cid = universe.world.add_component(ActionComponent::new(
                engine::ecs::IntentValue::UpdateTransform {
                    component_ids: vec![root],
                    translation: [x, y, 0.0],
                    rotation_quat_xyzw: rotation,
                    scale,
                },
            ));
            let _ = universe.attach(kf, action_cid);
        }

        let renderable = universe
            .world
            .add_component(RenderableComponent::new(Renderable::new(
                mesh,
                MaterialHandle::TOON_MESH,
            )));
        let color_c = universe
            .world
            .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
        let emissive = universe.world.add_component(EmissiveComponent::on());

        let _ = universe.attach(root, renderable);
        let _ = universe.attach(renderable, color_c);
        let _ = universe.attach(renderable, emissive);

        universe.add(root);

        // Label (separate transform so we can scale text independently).
        let text_root = universe.world.add_component(
            TransformComponent::new()
                .with_position(x, y + 0.75, 0.05)
                .with_scale(0.09, 0.09, 1.0),
        );
        let text = universe
            .world
            .add_component(TextComponent::with_word_wrap_tokens(
                label,
                LABEL_WRAP_AT,
                ["::", "(", ")", ",", "."],
            ));
        let text_color = universe
            .world
            .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
        let text_emissive = universe.world.add_component(EmissiveComponent::on());
        let _ = universe.attach(text_root, text);
        let _ = universe.attach(text, text_color);
        let _ = universe.attach(text, text_emissive);
        universe.add(text_root);
    }

examples/text-animation.rs (line 103)

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

    // Input-driven camera rig.
    // Topology: I { T { C3D } }
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(1.5));
    let camera3d = universe
        .world
        .add_component(engine::ecs::component::Camera3DComponent::new());
    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 2.5),
    );
    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z().with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);
    let _ = universe.attach(input, rig_transform);
    let _ = universe.attach(rig_transform, camera3d);

    // Small on-screen help.
    example_util::spawn_desktop_camera_controls_hint(&mut universe, rig_transform);
    universe.add(input);

    // Light so we can see non-emissive materials.
    let light_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 2.0),
    );
    let light = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(25.0)
            .with_color(1.0, 1.0, 1.0),
    );
    let _ = universe.attach(light_transform, light);
    universe.add(light_transform);

    use engine::ecs::component::{
        ColorComponent, TextComponent, TextShadowComponent, TextureComponent,
        TextureFilteringComponent, TransformComponent, TransparentCutoutComponent,
    };

    // Styled text root.
    let text_root = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, 0.0, 0.0)
            .with_scale(0.25, 0.25, 1.0),
    );

    // Color must be an ancestor of the glyph renderables.
    let color_id = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let _ = universe.attach(text_root, color_id);

    // This is the component we animate via SetText.
    let text_id = universe.world.add_component(TextComponent::new(">w<"));
    let _ = universe.attach(color_id, text_id);

    // Route into cutout pass for cleaner edges.
    let cutout = universe
        .world
        .add_component(TransparentCutoutComponent::new());
    let _ = universe.attach(text_id, cutout);

    // Font atlas.
    let tex = universe.world.add_component(TextureComponent::with_uri(
        "assets/textures/font_system.dds",
    ));
    let _ = universe.attach(text_id, tex);

    let shadow = universe.world.add_component(
        TextShadowComponent::new()
            .with_scale(1.35)
            .with_offset([0.06, -0.06, 0.0015]),
    );
    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest_magnification());

    let _ = universe.attach(text_id, shadow);
    let _ = universe.attach(text_id, filtering);

    universe.add(text_root);

    let clock_component = universe
        .world
        .add_component(engine::ecs::component::ClockComponent::new().with_bpm(140.0));
    let _ = universe.add(clock_component);

    // Looping animation: 4 beats long, 4 keyframes.
    let anim = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    let faces = [">w<", "^w^", "-_-", "o_o"];
    for (i, &face) in faces.iter().enumerate() {
        let kf = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(i as f64));

        // Each keyframe emits a SetText intent.
        let action = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::SetText {
                    component_ids: vec![text_id],
                    text: face.to_string(),
                },
            ));

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

    universe.add(anim);

    // 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/raycast-topology-animation.rs (line 291)

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

    // Background.
    let bg_color = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let bg_color_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.1, 0.1, 0.1, 1.0,
        ));
    let _ = universe.world.add_child(bg_color, bg_color_c);
    universe.add(bg_color);

    // Camera rig so we can see the scene.
    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(0.0, 2.0, 8.0)
            .with_rotation_euler(-0.25, 0.0, 0.0),
    );

    let camera3d = universe
        .world
        .add_component(engine::ecs::component::Camera3DComponent::new());

    let input_mode = universe.world.add_component(
        engine::ecs::component::InputTransformModeComponent::forward_z()
            .with_roll_axis_y()
            .with_fps_rotation(),
    );

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

    // Two rotating anchor transforms that the raycaster will be reparented under.
    // Each ring has its own anchor at a different height.
    let anchor_a = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 1.0, 0.0),
    );
    let anchor_b = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 2.2, 0.0),
    );

    // Visual markers for A/B.
    fn marker(universe: &mut engine::Universe, parent: engine::ecs::ComponentId, rgba: [f32; 4]) {
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let rc = universe
            .world
            .add_component(engine::ecs::component::RaycastableComponent::disabled());
        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 t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_scale(0.15, 0.15, 0.15),
        );
        let _ = universe.attach(parent, t);
        let _ = universe.attach(t, r);
        let _ = universe.attach(r, rc);
        let _ = universe.attach(r, c);
        let _ = universe.attach(r, e);
    }

    marker(&mut universe, anchor_a, [0.9, 0.2, 0.2, 1.0]);
    marker(&mut universe, anchor_b, [0.2, 0.2, 0.9, 1.0]);

    universe.add(anchor_a);
    universe.add(anchor_b);

    // A ring of cubes around the origin to see which one gets hit.
    fn ring_cube(
        universe: &mut engine::Universe,
        ring_root: engine::ecs::ComponentId,
        x: f32,
        y: f32,
        z: f32,
        rgba: [f32; 4],
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(0.35, 0.35, 0.35),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let rc = universe
            .world
            .add_component(engine::ecs::component::RaycastableComponent::enabled());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                rgba[0], rgba[1], rgba[2], rgba[3],
            ));
        let _ = universe.attach(ring_root, t);
        let _ = universe.attach(t, r);
        let _ = universe.attach(r, rc);
        let _ = universe.attach(r, c);
    }

    // Two rings: one per anchor height.
    let n = 28;
    let (radius_a, y_a) = (4.0, 1.0);
    let (radius_b, y_b) = (2.6, 2.2);

    let ring_a_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    let ring_b_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());

    for i in 0..n {
        let a = (i as f32) * (std::f32::consts::TAU / (n as f32));
        let (x, z) = (radius_a * a.cos(), radius_a * a.sin());
        let color = if i % 2 == 0 {
            [0.55, 0.20, 0.20, 1.0]
        } else {
            [0.20, 0.55, 0.20, 1.0]
        };
        ring_cube(&mut universe, ring_a_root, x, y_a, z, color);
    }

    for i in 0..n {
        let a = (i as f32) * (std::f32::consts::TAU / (n as f32));
        let (x, z) = (radius_b * a.cos(), radius_b * a.sin());
        let color = if i % 2 == 0 {
            [0.20, 0.25, 0.60, 1.0]
        } else {
            [0.20, 0.55, 0.55, 1.0]
        };
        ring_cube(&mut universe, ring_b_root, x, y_b, z, color);
    }

    // Init rings and attach scoped interaction handlers.
    universe.add(ring_a_root);
    universe.add(ring_b_root);
    universe.add_signal_handler(
        engine::ecs::SignalKind::RayIntersected,
        ring_a_root,
        ring_a_handler,
    );
    universe.add_signal_handler(
        engine::ecs::SignalKind::RayIntersected,
        ring_b_root,
        ring_b_handler,
    );

    // The raycaster component we will move between parents.
    // Source is inferred from topology:
    // - Under transforms A/B (no camera child) => parent-forward (-Z)
    // - Under camera rig transform (has camera child) => cursor-through-camera
    let raycaster = universe.world.add_component(
        engine::ecs::component::RayCastComponent::event_driven().with_max_distance(25.0),
    );

    // Global animation: move the raycaster between anchors.
    // Loop length is 8 beats (we include a noop keyframe at beat 7.0 to force loop_len=8).
    let anim_global = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());
    {
        // beat 0: attach to A.
        let kf0 = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(0.0));
        let act0 = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::Attach {
                    parents: vec![anchor_a],
                    child: raycaster,
                },
            ));
        let _ = universe.attach(kf0, act0);
        let _ = universe.attach(anim_global, kf0);

        // beat 4: attach to B.
        let kf4 = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(4.0));
        let act4 = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::Attach {
                    parents: vec![anchor_b],
                    child: raycaster,
                },
            ));
        let _ = universe.attach(kf4, act4);
        let _ = universe.attach(anim_global, kf4);

        // beat 7: noop to make loop_len=8.
        let kf7 = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(7.0));
        let noop = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::Noop,
            ));
        let _ = universe.attach(kf7, noop);
        let _ = universe.attach(anim_global, kf7);
    }
    universe.add(anim_global);

    // Ring A animation: rotate anchor A around Y (1 rev / 8 beats).
    // Also triggers Action::raycast(raycaster) on downbeats in the first half: beats 0,1,2,3.
    let anim_a = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    // Ring B animation: rotate anchor B differently (yaw + pitch).
    // Also triggers Action::raycast(raycaster) on offbeats in the second half: beats 4.5,5.5,6.5,7.5.
    let anim_b = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    let loop_beats = 8.0;
    let steps = 64;

    for step in 0..=steps {
        let t = (step as f32) / (steps as f32);
        let beat = (t as f64) * (loop_beats as f64);

        // Keyframe beats are per-animation local beats.
        let kf_a = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(beat));
        let kf_b = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(beat));

        // Anchor A rotation: smooth yaw.
        let yaw_a = t * std::f32::consts::TAU;
        let a_set = engine::ecs::component::ActionComponent::new(
            engine::ecs::IntentValue::UpdateTransform {
                component_ids: vec![anchor_a],
                translation: [0.0, 1.0, 0.0],
                rotation_quat_xyzw: quat_from_yaw(yaw_a),
                scale: [1.0, 1.0, 1.0],
            },
        );
        let a_set_id = universe.world.add_component(a_set);
        let _ = universe.attach(kf_a, a_set_id);

        // Anchor B rotation: yaw + pitch (different pattern).
        let yaw_b = -t * std::f32::consts::TAU * 1.5;
        let pitch_b = (t * std::f32::consts::TAU).sin() * 0.35;
        let rot_b = quat_mul(quat_from_yaw(yaw_b), quat_from_pitch(pitch_b));
        let b_set = engine::ecs::component::ActionComponent::new(
            engine::ecs::IntentValue::UpdateTransform {
                component_ids: vec![anchor_b],
                translation: [0.0, 2.2, 0.0],
                rotation_quat_xyzw: rot_b,
                scale: [1.0, 1.0, 1.0],
            },
        );
        let b_set_id = universe.world.add_component(b_set);
        let _ = universe.attach(kf_b, b_set_id);

        // Per-ring raycast patterns.
        // A: downbeats in first half (0..4): step % 8 == 0 -> beats 0,1,2,3,4.
        if beat < 4.0 && step % 8 == 0 {
            let act = universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::RequestRaycast {
                        component_ids: vec![raycaster],
                    },
                ));
            let _ = universe.attach(kf_a, act);
        }

        // B: offbeats in second half (4..8): step % 8 == 4 -> beats 0.5,1.5,...,7.5.
        if beat >= 4.0 && step % 8 == 4 {
            let act = universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::RequestRaycast {
                        component_ids: vec![raycaster],
                    },
                ));
            let _ = universe.attach(kf_b, act);
        }

        let _ = universe.attach(anim_a, kf_a);
        let _ = universe.attach(anim_b, kf_b);
    }

    universe.add(anim_a);
    universe.add(anim_b);

    // Process init-time registrations.
    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/animation-for-topology.rs (line 195)

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 scene with a camera so the window opens.
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.06, 0.06, 0.07, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // 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(0.0, 0.0, 9.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);

    // Light so we can see non-emissive materials.
    let light_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(2.0, 3.5, 6.0),
    );
    let light = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(30.0)
            .with_color(1.0, 1.0, 1.0),
    );
    let _ = universe.attach(light_tx, light);
    universe.add(light_tx);

    // ClockComponent drives the animation timeline in beats.
    let clock = universe
        .world
        .add_component(engine::ecs::component::ClockComponent::new().with_bpm(140.0));
    universe.add(clock);

    // Root for all visualization objects.
    let viz_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    universe.add(viz_root);

    let anchor_count = 16usize;
    let cube_pool_size = 8usize;

    // Three grids side-by-side.
    let layout_a = GridLayout {
        origin: (-6.0, 0.0, 0.0),
        spacing: 1.1,
    };
    let layout_b = GridLayout {
        origin: (0.0, 0.0, 0.0),
        spacing: 1.1,
    };
    let layout_c = GridLayout {
        origin: (6.0, 0.0, 0.0),
        spacing: 1.1,
    };

    // --- Grid A: detach + re-attach (reparent) ---
    let grid_a_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    let _ = universe.attach(viz_root, grid_a_root);

    let mut anchors_a: Vec<engine::ecs::ComponentId> = Vec::with_capacity(anchor_count);
    for i in 0..anchor_count {
        let (x, y, z) = grid_anchor_local(layout_a, i);
        let anchor = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(x, y, z),
        );
        let _ = universe.attach(grid_a_root, anchor);
        anchors_a.push(anchor);
        spawn_emissive_marker_cube(
            &mut universe,
            anchor,
            (0.0, -0.35, 0.0),
            0.06,
            [0.18, 0.18, 0.22, 1.0],
        );
    }

    let mut cubes_a: Vec<engine::ecs::ComponentId> = Vec::with_capacity(cube_pool_size);
    for i in 0..cube_pool_size {
        let t = (i as f32) / ((cube_pool_size - 1) as f32).max(1.0);
        let rgba = [0.10, 0.40 + 0.50 * t, 0.90 - 0.70 * t, 1.0];
        cubes_a.push(spawn_detached_cube_prefab(&mut universe, 0.22, rgba));
    }

    let anim_a = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());
    for i in 0..anchor_count {
        let cube = cubes_a[i % cube_pool_size];
        let parent = anchors_a[i];

        // Explicit detach+attach to test topology changes via animations.

        // Put them on separate keyframes so ordering is time-deterministic.
        let beat_detach = i as f64;
        let beat_attach = i as f64 + 0.05;

        let kf_detach = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(beat_detach));
        let _ = universe.attach(anim_a, kf_detach);
        let detach_action =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::Detach {
                        component_ids: vec![cube],
                    },
                ));
        let _ = universe.attach(kf_detach, detach_action);

        let kf_attach = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(beat_attach));
        let _ = universe.attach(anim_a, kf_attach);
        let attach_action =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::Attach {
                        parents: vec![parent],
                        child: cube,
                    },
                ));
        let _ = universe.attach(kf_attach, attach_action);
    }
    universe.add(anim_a);

    // --- Grid B: continuously spawn (attach_clone) + delete-behind (remove_child) ---
    //
    // Uses the new actions:
    // - `Action::attach_clone(parent, prefab_root)`
    // - `Action::remove_child(parent, index)`
    //
    // This avoids needing a pre-built pool of cube ComponentIds.
    let grid_b_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    let _ = universe.attach(viz_root, grid_b_root);

    let mut anchors_b: Vec<engine::ecs::ComponentId> = Vec::with_capacity(anchor_count);
    for i in 0..anchor_count {
        let (x, y, z) = grid_anchor_local(layout_b, i);
        let anchor = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(x, y, z),
        );
        let _ = universe.attach(grid_b_root, anchor);
        anchors_b.push(anchor);

        // Marker is attached under the grid root (not under the anchor), so anchor child index 0
        // remains reserved for the dynamic cube subtree.
        spawn_emissive_marker_cube(
            &mut universe,
            grid_b_root,
            (x, y - 0.35, z),
            0.06,
            [0.22, 0.18, 0.18, 1.0],
        );
    }

    // Detached prefab that will be cloned on demand (reddish cube).
    let prefab_b = spawn_detached_cube_prefab(&mut universe, 0.20, [0.90, 0.25, 0.15, 1.0]);

    let steps_b = 32usize;
    let window = 8usize;

    let anim_b = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    // Phase 1: each beat, spawn a cube under an anchor; delete-behind by removing child(0).
    for i in 0..steps_b {
        let parent = anchors_b[i % anchor_count];

        let beat_attach = i as f64;
        let beat_remove = i as f64 + 0.05;

        let kf_attach = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(beat_attach));
        let _ = universe.attach(anim_b, kf_attach);

        let attach_action =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::AttachClone {
                        parents: vec![parent],
                        prefab_root: prefab_b,
                    },
                ));
        let _ = universe.attach(kf_attach, attach_action);

        if i >= window {
            let remove_parent = anchors_b[(i - window) % anchor_count];
            let kf_remove = universe
                .world
                .add_component(engine::ecs::component::KeyframeComponent::new(beat_remove));
            let _ = universe.attach(anim_b, kf_remove);

            let remove_action =
                universe
                    .world
                    .add_component(engine::ecs::component::ActionComponent::new(
                        engine::ecs::IntentValue::RemoveChild {
                            parents: vec![remove_parent],
                            index: 0,
                        },
                    ));
            let _ = universe.attach(kf_remove, remove_action);
        }
    }

    // Phase 2: cleanup tail so the loop doesn't accumulate cubes.
    for j in 0..window {
        let remove_parent = anchors_b[(steps_b - window + j) % anchor_count];
        let beat_remove = steps_b as f64 + j as f64 + 0.05;

        let kf_remove = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(beat_remove));
        let _ = universe.attach(anim_b, kf_remove);

        let remove_action =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::RemoveChild {
                        parents: vec![remove_parent],
                        index: 0,
                    },
                ));
        let _ = universe.attach(kf_remove, remove_action);
    }

    universe.add(anim_b);

    // --- Grid C: move cubes via set_position (no topology changes) ---
    let grid_c_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    let _ = universe.attach(viz_root, grid_c_root);

    let mut anchors_c: Vec<(f32, f32, f32)> = Vec::with_capacity(anchor_count);
    for i in 0..anchor_count {
        let (x, y, z) = grid_anchor_local(layout_c, i);
        anchors_c.push((x, y, z));

        let anchor = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(x, y, z),
        );
        let _ = universe.attach(grid_c_root, anchor);
        spawn_emissive_marker_cube(
            &mut universe,
            anchor,
            (0.0, -0.35, 0.0),
            0.06,
            [0.18, 0.22, 0.18, 1.0],
        );
    }

    let mut cubes_c: Vec<engine::ecs::ComponentId> = Vec::with_capacity(cube_pool_size);
    for i in 0..cube_pool_size {
        let t = (i as f32) / ((cube_pool_size - 1) as f32).max(1.0);
        let rgba = [0.25, 0.85 - 0.55 * t, 0.25 + 0.55 * t, 1.0];
        let cube_root = spawn_detached_cube_prefab(&mut universe, 0.22, rgba);
        let _ = universe.attach(grid_c_root, cube_root);
        cubes_c.push(cube_root);
    }

    let anim_c = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());
    for i in 0..anchor_count {
        let kf = universe
            .world
            .add_component(engine::ecs::component::KeyframeComponent::new(i as f64));
        let _ = universe.attach(anim_c, kf);

        let cube = cubes_c[i % cube_pool_size];
        let (x, y, z) = anchors_c[i];
        let setpos_action =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::SetPosition {
                        component_ids: vec![cube],
                        position: [x, y, z],
                    },
                ));
        let _ = universe.attach(kf, setpos_action);
    }
    universe.add(anim_c);

    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/animation-example.rs (line 249)

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 scene with a camera so the window opens.
    let clear = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.08, 0.08, 0.08, 1.0,
        ));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // 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);

    // Light so we can see non-emissive materials (even though our cubes are emissive).
    let light_tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 2.5, 4.0),
    );
    let light = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_distance(25.0)
            .with_color(1.0, 1.0, 1.0),
    );
    let _ = universe.attach(light_tx, light);
    universe.add(light_tx);

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

    // Audio output + oscillators driven by scheduled actions.
    let audio_out = universe
        .world
        .add_component(engine::ecs::component::AudioOutputComponent::new());
    universe.add(audio_out);

    // Noise oscillator: short white-noise hits.
    let osc_noise = engine::ecs::component::AudioOscillator::noise()
        .with_frequency(0.0)
        .with_amplitude(0.06)
        .with_enabled(false);
    let osc_noise_comp =
        universe
            .world
            .add_component(engine::ecs::component::AudioOscillatorComponent::single(
                osc_noise,
            ));
    let _ = universe.attach(audio_out, osc_noise_comp);

    // Drum oscillator: retriggers (phase + sweep) every enable.
    let osc_drum = engine::ecs::component::AudioOscillator::drum()
        // A low-ish pitch scale; actual pitch is set by scheduled notes.
        .with_frequency(32.0)
        .with_amplitude(0.40)
        .with_enabled(false);
    let osc_drum_comp =
        universe
            .world
            .add_component(engine::ecs::component::AudioOscillatorComponent::single(
                osc_drum,
            ));

    let _ = universe.attach(audio_out, osc_drum_comp);

    // --- Visual layout helpers ---
    fn spawn_text(universe: &mut engine::Universe, pos: (f32, f32, f32), scale: f32, 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, 38,
                ));
        let _ = universe.attach(tx, t);
        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 / lanes ---
    let lane_x = -2.6_f32;
    let lane_title_z = -0.4_f32;
    let lane_cfg_z = -0.4_f32;
    let _lane_cube_z = -0.8_f32;
    let drum_y = 0.9_f32;
    let noise_y = -0.4_f32;

    spawn_text(
        &mut universe,
        (lane_x, drum_y + 0.55, lane_title_z),
        0.09,
        "Audio Source A: Drum (kick)",
    );
    spawn_text(
        &mut universe,
        (lane_x, drum_y + 0.25, lane_cfg_z),
        0.07,
        "type=Drum\namp=0.40\nbase_freq=32Hz\nkick: C0 dur=0.12 vel=0.90\nlookahead=0.10s",
    );

    spawn_text(
        &mut universe,
        (lane_x, noise_y + 0.55, lane_title_z),
        0.09,
        "Audio Source B: Noise",
    );
    spawn_text(
        &mut universe,
        (lane_x, noise_y + 0.25, lane_cfg_z),
        0.07,
        "type=Noise\namp=0.06\nnoise: C9 dur=0.06 vel=0.25\noffset=+0.5 beats\nlookahead=0.10s",
    );

    // Representative cubes for the two audio sources.
    let viz_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    universe.add(viz_root);
    spawn_emissive_cube(
        &mut universe,
        viz_root,
        (lane_x - 0.28, drum_y + 0.55, lane_title_z),
        0.16,
        [1.00, 0.90, 0.10, 1.0],
    );
    spawn_emissive_cube(
        &mut universe,
        viz_root,
        (lane_x - 0.28, noise_y + 0.55, lane_title_z),
        0.16,
        [1.00, 1.00, 1.00, 1.0],
    );

    // Timeline roots so we can "reset all" via a single set_color action.
    let kick_timeline_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    let noise_timeline_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    let _ = universe.attach(viz_root, kick_timeline_root);
    let _ = universe.attach(viz_root, noise_timeline_root);

    // Animation with 16 keyframes: each keyframe schedules a kick at offset 0.0,
    // and a noise hit at offset 0.5.
    let anim = universe
        .world
        .add_component(engine::ecs::component::AnimationComponent::new());

    let kick_dur = 0.12_f32;
    let noise_dur = 0.06_f32;

    // Requested palette:
    // - kick: dark yellow -> bright yellow
    // - noise: grey -> white
    let kick_dark = [0.35, 0.28, 0.02, 1.0];
    let kick_bright = [1.00, 0.90, 0.10, 1.0];
    let noise_dark = [0.35, 0.35, 0.35, 1.0];
    let noise_bright = [1.00, 1.00, 1.00, 1.0];

    let beat_spacing = 0.38_f32;
    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 kick = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::AudioSchedulePlay {
                    component_ids: vec![osc_drum_comp],
                    beat_offset: 0.0,
                    beat_context: None,
                    note: Some(
                        engine::ecs::component::MusicNote::c(0, kick_dur).with_velocity(0.9),
                    ),
                    gain: None,
                    rate: None,
                    duration: None,
                },
            ));

        let noise = universe
            .world
            .add_component(engine::ecs::component::ActionComponent::new(
                engine::ecs::IntentValue::AudioSchedulePlay {
                    component_ids: vec![osc_noise_comp],
                    beat_offset: 0.5,
                    beat_context: None,
                    note: Some(
                        engine::ecs::component::MusicNote::c(9, noise_dur).with_velocity(0.25),
                    ),
                    gain: None,
                    rate: None,
                    duration: None,
                },
            ));

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

        // Each keyframe drives visualization purely via normal actions:
        // 1) reset all timeline cubes to their base colors
        // 2) brighten the current beat's cubes
        let reset_kick_lane =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::SetColor {
                        component_ids: vec![kick_timeline_root],
                        rgba: kick_dark,
                    },
                ));
        let reset_noise_lane =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::SetColor {
                        component_ids: vec![noise_timeline_root],
                        rgba: noise_dark,
                    },
                ));
        let _ = universe.attach(kf, reset_kick_lane);
        let _ = universe.attach(kf, reset_noise_lane);

        // Timeline cubes: one cube per scheduled audio operation.
        // Kick (offset 0.0) on the drum lane.
        let kick_x = (kf_beat as f32) * beat_spacing;
        let kick_cube = spawn_op_cube(
            &mut universe,
            kick_timeline_root,
            (kick_x, drum_y, -1.3),
            0.10,
            kick_dark,
        );

        // Noise (offset 0.5) on the noise lane.
        let noise_x = ((kf_beat + 0.5) as f32) * beat_spacing;
        let noise_cube = spawn_op_cube(
            &mut universe,
            noise_timeline_root,
            (noise_x, noise_y, -1.3),
            0.10,
            noise_dark,
        );

        let brighten_kick =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::SetColor {
                        component_ids: vec![kick_cube],
                        rgba: kick_bright,
                    },
                ));
        let brighten_noise =
            universe
                .world
                .add_component(engine::ecs::component::ActionComponent::new(
                    engine::ecs::IntentValue::SetColor {
                        component_ids: vec![noise_cube],
                        rgba: noise_bright,
                    },
                ));
        let _ = universe.attach(kf, brighten_kick);
        let _ = universe.attach(kf, brighten_noise);
    }

    universe.add(anim);

    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/audio-graph-example.rs (line 627)

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

pub fn with_state(self, state: AnimationState) -> Self

Examples found in repository

examples/mesh-factory-example.rs (line 81)

    fn spawn_labeled_mesh(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        label: &str,
        mesh: engine::graphics::primitives::CpuMeshHandle,
        scale: [f32; 3],
        color: [f32; 4],
    ) {
        use engine::ecs::component::{
            ActionComponent, AnimationComponent, AnimationState, ColorComponent, EmissiveComponent,
            KeyframeComponent, RenderableComponent, TextComponent, TransformComponent,
        };
        use engine::graphics::primitives::{MaterialHandle, Renderable};

        // Mesh.
        let root = universe.world.add_component(
            TransformComponent::new()
                .with_position(x, y, 0.0)
                .with_scale(scale[0], scale[1], scale[2]),
        );

        // Spin each shape around its own +Y axis using AnimationComponent + keyframes.
        // We fill [0, 2) beats densely so it looks smooth.
        let anim = universe
            .world
            .add_component(AnimationComponent::new().with_state(AnimationState::Looping));
        let _ = universe.attach(root, anim);

        let steps: usize = 64;
        for i in 0..steps {
            let beat = (i as f64) * (2.0 / (steps as f64));
            let kf = universe.world.add_component(KeyframeComponent::new(beat));
            let _ = universe.attach(anim, kf);

            // Full turn over 2 beats.
            let angle = (std::f64::consts::TAU * (beat / 2.0)) as f32;
            let rotation = utils::math::quat_from_axis_angle([0.0, 1.0, 0.0], angle);

            let action_cid = universe.world.add_component(ActionComponent::new(
                engine::ecs::IntentValue::UpdateTransform {
                    component_ids: vec![root],
                    translation: [x, y, 0.0],
                    rotation_quat_xyzw: rotation,
                    scale,
                },
            ));
            let _ = universe.attach(kf, action_cid);
        }

        let renderable = universe
            .world
            .add_component(RenderableComponent::new(Renderable::new(
                mesh,
                MaterialHandle::TOON_MESH,
            )));
        let color_c = universe
            .world
            .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
        let emissive = universe.world.add_component(EmissiveComponent::on());

        let _ = universe.attach(root, renderable);
        let _ = universe.attach(renderable, color_c);
        let _ = universe.attach(renderable, emissive);

        universe.add(root);

        // Label (separate transform so we can scale text independently).
        let text_root = universe.world.add_component(
            TransformComponent::new()
                .with_position(x, y + 0.75, 0.05)
                .with_scale(0.09, 0.09, 1.0),
        );
        let text = universe
            .world
            .add_component(TextComponent::with_word_wrap_tokens(
                label,
                LABEL_WRAP_AT,
                ["::", "(", ")", ",", "."],
            ));
        let text_color = universe
            .world
            .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
        let text_emissive = universe.world.add_component(EmissiveComponent::on());
        let _ = universe.attach(text_root, text);
        let _ = universe.attach(text, text_color);
        let _ = universe.attach(text, text_emissive);
        universe.add(text_root);
    }

pub fn with_resolve_targets(self, mode: ResolveTargetsMode) -> Self

pub fn with_length_beats(self, beats: f64) -> Self

pub fn with_scope_source(self, source: ComponentRef) -> Self

pub fn with_playing(self, playing: bool) -> Self

Backward-compatible helper for older callers.

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

Trait Implementations

impl Clone for AnimationComponent

fn clone(&self) -> AnimationComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for AnimationComponent

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 Debug for AnimationComponent

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

Formats the value using the given formatter.

impl Default for AnimationComponent

fn default() -> Self

Returns the “default value” for a type.