Struct ActionComponent 

pub struct ActionComponent {
    pub signal: IntentValue,
    pub target_sources: Vec<ComponentRef>,
    pub resolved: bool,
}

Fields

signal: IntentValue

Runtime intent. ComponentId slots inside are ComponentId::null() placeholders until resolution; after resolution, they’re real ids filled in from target_sources in the variant’s declaration order.

target_sources: Vec<ComponentRef>

Authoring metadata, one entry per ComponentId slot in signal, ordered by the slot’s declaration order in the variant. Used by dump (lossless round-trip) and by resolution (look up ids).

resolved: bool

Whether signal’s ComponentId slots hold real ids (true) or null placeholders (false). Set by the resolution pass invoked by AnimationSystem per the owning AnimationComponent’s configured resolve timing.

Implementations

impl ActionComponent

pub fn new(signal: IntentValue) -> Self

Construct from an already-resolved IntentValue (no ComponentId targets, or all targets pre-resolved). Use this for built-in / engine-emitted actions; MMS authoring goes through the registry which builds with new_authored instead.

Examples found in repository

examples/mesh-factory-example.rs (lines 94-101)

    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 (lines 114-119)

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 (lines 299-304)

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

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

    // 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 (lines 213-217)

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 (lines 271-283)

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 (lines 654-664)

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 new_authored( signal: IntentValue, target_sources: Vec<ComponentRef>, ) -> Self

Construct from a signal whose ComponentId slots are placeholders plus the authoring sources for each slot (in declaration order). resolved starts false; resolution happens when the owning AnimationSystem first processes this action.

pub fn print(message: impl Into<String>) -> Self

Trait Implementations

impl Clone for ActionComponent

fn clone(&self) -> ActionComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for ActionComponent

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

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

fn as_any(&self) -> &dyn Any

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

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

Called when component is added to the World

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

Encode this component as an MMS Component Expression AST node.

fn set_id(&mut self, _component: ComponentId)

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 ActionComponent

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

Formats the value using the given formatter.

impl Default for ActionComponent

fn default() -> Self

Returns the “default value” for a type.