Struct World 

pub struct World { /* private fields */ }

World: owns all global components.

Implementations

impl World

pub fn component_id_by_guid(&self, guid: Uuid) -> Option<ComponentId>

Fast GUID -> ComponentId lookup.

pub fn set_component_guid( &mut self, id: ComponentId, new_guid: Uuid, ) -> Result<(), String>

Replace the GUID of an already-inserted component, keeping its ComponentId stable. Used by spawn paths that restore an authored guid = "..." property after create_component has already minted a fresh GUID.

Returns Err if the target id is missing, or if the new guid is already taken by another component (would silently overwrite the reverse index otherwise).

pub fn add_component<T: Component>(&mut self, c: T) -> ComponentId

Add a new component to the world (no parent) and return its id.

Note: this currently does not call Component::init. That should happen via a higher-level API that has access to SystemWorld and VisualWorld.

Examples found in repository

examples/transparent-cutout-example.rs (lines 19-23)

fn spawn_gold_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    position: (f32, f32, f32),
    scale: f32,
    color: (f32, f32, f32),
) {
    let t = universe.world.add_component(
        TransformComponent::new()
            .with_position(position.0, position.1, position.2)
            .with_scale(scale, scale, scale),
    );
    let r = universe.world.add_component(RenderableComponent::cube());
    let c = universe
        .world
        .add_component(ColorComponent::rgba(color.0, color.1, color.2, 1.0));

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

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

    // Orange/yellow-ish clear color so cutout edges read.
    let clear = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let clear_c = universe
        .world
        .add_component(ColorComponent::rgba(0.98, 0.72, 0.22, 1.0));
    let _ = universe.world.add_child(clear, clear_c);
    universe.add(clear);

    // Warm-ish ambient so the gold cubes don’t go too dark.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.22, 0.16, 0.08));
    universe.add(ambient);

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

    // Start a bit pulled back, looking toward the origin.
    let rig_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 5.0));
    let _ = universe.attach(input, rig_transform);

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

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

    // Key light for toon shading.
    let light = universe.world.add_component(
        PointLightComponent::new()
            .with_distance(50.0)
            .with_intensity(2.2)
            .with_color(1.0, 0.98, 0.92),
    );
    let light_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(2.0, 3.0, 4.0));
    let _ = universe.attach(light_transform, light);
    universe.add(light_transform);

    // --- Transparent cutout: 100 cat faces in a 10x10 grid ---
    // Place them *behind* the starting camera position (camera starts at z=+5.0).
    // Not attached to the camera rig.
    let cat_grid_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 9.0));
    universe.add(cat_grid_root);

    let grid_w: i32 = 10;
    let grid_h: i32 = 10;
    let spacing: f32 = 0.7;
    let half_w = (grid_w as f32 - 1.0) * spacing * 0.5;
    let half_h = (grid_h as f32 - 1.0) * spacing * 0.5;

    for y in 0..grid_h {
        for x in 0..grid_w {
            // Topology: cat_grid_root { T_quad { R_quad { Texture + Filtering + Cutout + Color } } }
            let px = x as f32 * spacing - half_w;
            let py = y as f32 * spacing - half_h;

            let pz: f32 = (x as f32) % half_w;

            let quad_t = universe.world.add_component(
                TransformComponent::new()
                    .with_position(px, py, pz)
                    .with_scale(0.55, 0.55, 1.0),
            );
            let quad_r = universe.world.add_component(RenderableComponent::square());

            let quad_tex = universe.world.add_component(TextureComponent::with_uri(
                "assets/textures/cat-face-amused.dds",
            ));
            let quad_filtering = universe
                .world
                .add_component(TextureFilteringComponent::linear());
            let quad_cutout = universe
                .world
                .add_component(TransparentCutoutComponent::new());
            let quad_color = universe
                .world
                .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));

            let _ = universe.attach(cat_grid_root, quad_t);
            let _ = universe.attach(quad_t, quad_r);
            let _ = universe.attach(quad_r, quad_tex);
            let _ = universe.attach(quad_r, quad_filtering);
            let _ = universe.attach(quad_r, quad_cutout);
            let _ = universe.attach(quad_r, quad_color);
        }
    }

    // --- Gold/yellow cubes behind the quad ---
    // Parent them under a transform so it’s easy to tweak their depth.
    let cubes_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 4.6));

    // point light for cats
    let cat_light_tx = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 2.0, 7.0));

    let cat_light = universe.world.add_component(
        PointLightComponent::new()
            .with_distance(150.0)
            .with_intensity(1.5)
            .with_color(1.0, 0.98, 0.92),
    );
    let _ = universe.attach(cat_light_tx, cat_light);
    let _ = universe.attach(cubes_root, cat_light_tx);

    universe.add(cubes_root);

    let gold_a = (1.0, 0.86, 0.22);
    let gold_b = (1.0, 0.74, 0.10);
    let gold_c = (0.95, 0.92, 0.32);

    // A loose cluster that’s visible through the cutout (transparent) area.
    spawn_gold_cube(&mut universe, cubes_root, (-1.1, -0.3, -0.2), 0.45, gold_a);
    spawn_gold_cube(&mut universe, cubes_root, (1.0, -0.4, -0.4), 0.40, gold_b);
    spawn_gold_cube(&mut universe, cubes_root, (-0.2, 0.9, -0.6), 0.38, gold_c);
    spawn_gold_cube(&mut universe, cubes_root, (0.7, 0.6, -0.9), 0.32, gold_a);
    spawn_gold_cube(&mut universe, cubes_root, (-0.8, 0.4, -1.1), 0.36, gold_b);

    // Bigger orange/yellow cubes behind the cluster (to make the cutout depth obvious).
    let orange_gold_a = (1.0, 0.62, 0.10);
    let orange_gold_b = (1.0, 0.78, 0.18);
    spawn_gold_cube(
        &mut universe,
        cubes_root,
        (0.0, -0.1, -2.1),
        1.15,
        orange_gold_b,
    );
    spawn_gold_cube(
        &mut universe,
        cubes_root,
        (-1.8, 0.6, -2.6),
        0.95,
        orange_gold_a,
    );
    spawn_gold_cube(
        &mut universe,
        cubes_root,
        (1.9, 0.7, -2.9),
        1.05,
        orange_gold_b,
    );
    spawn_gold_cube(
        &mut universe,
        cubes_root,
        (0.9, 1.8, -3.2),
        0.90,
        orange_gold_a,
    );
    spawn_gold_cube(
        &mut universe,
        cubes_root,
        (-0.9, 1.7, -3.5),
        1.10,
        orange_gold_b,
    );

    // Process init-time registrations (loads textures, registers renderables, etc.).
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

examples/opacity-example.rs (lines 20-24)

fn spawn_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    position: (f32, f32, f32),
    scale: (f32, f32, f32),
    color: Option<(f32, f32, f32, f32)>,
    opacity: Option<OpacityComponent>,
) {
    let t = universe.world.add_component(
        TransformComponent::new()
            .with_position(position.0, position.1, position.2)
            .with_scale(scale.0, scale.1, scale.2),
    );
    let r = universe.world.add_component(RenderableComponent::cube());

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

    if let Some((cr, cg, cb, ca)) = color {
        let c = universe
            .world
            .add_component(ColorComponent::rgba(cr, cg, cb, ca));
        let _ = universe.attach(r, c);
    }

    if let Some(o) = opacity {
        let o = universe.world.add_component(o);
        let _ = universe.attach(r, o);
    }
}

fn spawn_text_label(universe: &mut engine::Universe, position: (f32, f32, f32), text: &str) {
    // T_root { T_scale { TXT { filtering } } }
    let text_root = universe
        .world
        .add_component(TransformComponent::new().with_position(position.0, position.1, position.2));

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

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

    // Keep it crisp.
    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest());
    let _ = universe.attach(text_c, filtering);

    // White label.
    let color = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let _ = universe.attach(text_c, color);

    universe.add(text_root);
}

fn text_block_dimensions(text: &str) -> (usize, usize) {
    let mut max_cols = 0usize;
    let mut rows = 1usize;
    let mut cur = 0usize;

    for ch in text.chars() {
        if ch == '\n' {
            max_cols = max_cols.max(cur);
            cur = 0;
            rows += 1;
        } else {
            cur += 1;
        }
    }
    max_cols = max_cols.max(cur);

    (max_cols.max(1), rows.max(1))
}

fn spawn_text_label_with_bg(
    universe: &mut engine::Universe,
    position: (f32, f32, f32),
    text: &str,
    bg_opacity: f32,
) {
    // T_root {
    //   T_bg { R_bg { Color black, Opacity } }
    //   T_scale { TXT { filtering } }
    // }

    let text_root = universe
        .world
        .add_component(TransformComponent::new().with_position(position.0, position.1, position.2));

    // Background quad (slightly behind the glyph quads).
    let (cols, rows) = text_block_dimensions(text);
    let text_scale = 0.18_f32;
    let pad_x = 0.55_f32;
    let pad_y = 0.45_f32;
    let bg_w = cols as f32 * text_scale + pad_x;
    let bg_h = rows as f32 * text_scale + pad_y;

    let bg_t = universe.world.add_component(
        TransformComponent::new()
            .with_position(1.5, 0.0, -0.02)
            .with_scale(bg_w, bg_h, 1.0),
    );
    let bg_r = universe.world.add_component(RenderableComponent::square());
    let _ = universe.attach(text_root, bg_t);
    let _ = universe.attach(bg_t, bg_r);

    let bg_c = universe
        .world
        .add_component(ColorComponent::rgba(0.0, 0.0, 0.0, 1.0));
    let _ = universe.attach(bg_r, bg_c);

    let bg_o = universe
        .world
        .add_component(OpacityComponent::new().with_opacity(bg_opacity));
    let _ = universe.attach(bg_r, bg_o);

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

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

    // Keep it crisp.
    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest());
    let _ = universe.attach(text_c, filtering);

    // Force the label into the transparent pass so it layers correctly with the background.
    // (Pass selection currently does not consider texture alpha.)
    let color = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 0.998));
    let _ = universe.attach(text_c, color);

    universe.add(text_root);
}

fn spawn_demo_spot(
    universe: &mut engine::Universe,
    spot_pos: (f32, f32, f32),
    opacity: f32,
    multiple_layers: bool,
    grid_n: i32,
) {
    let spot = universe
        .world
        .add_component(TransformComponent::new().with_position(spot_pos.0, spot_pos.1, spot_pos.2));

    // All cubes inherit this color.
    let white = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let _ = universe.attach(spot, white);

    // All cubes inherit this opacity (no per-cube OpacityComponent needed).
    let mut oc = OpacityComponent::new().with_opacity(opacity);
    if multiple_layers {
        oc = oc.with_multiple_layers();
    }
    let oc = universe.world.add_component(oc);
    let _ = universe.attach(spot, oc);

    universe.add(spot);

    // Cube grid.
    let n = grid_n.max(1);
    let spacing = if n <= 2 { 1.0 } else { 0.6 };
    let cube_scale = if n <= 2 { 0.8 } else { 0.45 };
    let half = (n as f32 - 1.0) * spacing * 0.5;

    for z in 0..n {
        for y in 0..n {
            for x in 0..n {
                let px = x as f32 * spacing - half;
                let py = y as f32 * spacing;
                let pz = z as f32 * spacing - half;

                spawn_cube(
                    universe,
                    spot,
                    (px, py, pz),
                    (cube_scale, cube_scale, cube_scale),
                    None,
                    None,
                );
            }
        }
    }

    // Label above.
    let label = format!(
        "opacity: {:.2}\nmulti-layer: {}",
        opacity,
        if multiple_layers { "true" } else { "false" }
    );
    // Keep labels away from the cube volume so they don't intersect.
    let label_y = spot_pos.1 + (n as f32 * spacing) + 1.8;
    let label_x = spot_pos.0 - (half + 0.6);
    let label_z = spot_pos.2 - (half + 1.0);
    spawn_text_label(universe, (label_x, label_y, label_z), &label);
}

fn spawn_demo_strip_pair(
    universe: &mut engine::Universe,
    spot_pos: (f32, f32, f32),
    transparent_multiple_layers: bool,
) {
    let n_z: i32 = 4;
    let spacing = 1.0;
    let cube_scale = 0.8;
    let half_z = (n_z as f32 - 1.0) * spacing * 0.5;

    // Transparent strip (1x4 along Z).
    let transparent_root = universe
        .world
        .add_component(TransformComponent::new().with_position(spot_pos.0, spot_pos.1, spot_pos.2));

    let white = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let _ = universe.attach(transparent_root, white);

    let mut oc = OpacityComponent::new().with_opacity(0.50);
    if transparent_multiple_layers {
        oc = oc.with_multiple_layers();
    }
    let oc = universe.world.add_component(oc);
    let _ = universe.attach(transparent_root, oc);

    universe.add(transparent_root);

    for z in 0..n_z {
        let pz = z as f32 * spacing - half_z;
        spawn_cube(
            universe,
            transparent_root,
            (0.0, 0.0, pz),
            (cube_scale, cube_scale, cube_scale),
            None,
            None,
        );
    }

    // Opaque strip to the left, same spacing/scale.
    let opaque_root = universe
        .world
        .add_component(TransformComponent::new().with_position(
            spot_pos.0 - spacing,
            spot_pos.1,
            spot_pos.2,
        ));
    let white = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let _ = universe.attach(opaque_root, white);
    universe.add(opaque_root);

    for z in 0..n_z {
        let pz = z as f32 * spacing - half_z;
        spawn_cube(
            universe,
            opaque_root,
            (0.0, 0.0, pz),
            (cube_scale, cube_scale, cube_scale),
            None,
            None,
        );
    }

    let label = format!(
        "mini: opaque + transparent strip\ntransparent opacity: 0.50\nmulti-layer: {}",
        if transparent_multiple_layers {
            "true"
        } else {
            "false"
        }
    );
    let label_y = spot_pos.1 + spacing + 1.8;
    let label_x = spot_pos.0 - (spacing * 2.6);
    let label_z = spot_pos.2 - (half_z + 1.0);
    spawn_text_label(universe, (label_x, label_y, label_z), &label);
}

fn spawn_demo_xy_plane(
    universe: &mut engine::Universe,
    spot_pos: (f32, f32, f32),
    opacity: f32,
    n_x: i32,
    n_y: i32,
    z: f32,
) {
    let spot = universe
        .world
        .add_component(TransformComponent::new().with_position(spot_pos.0, spot_pos.1, spot_pos.2));

    let white = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let _ = universe.attach(spot, white);

    let oc = universe
        .world
        .add_component(OpacityComponent::new().with_opacity(opacity));
    let _ = universe.attach(spot, oc);

    universe.add(spot);

    let nx = n_x.max(1);
    let ny = n_y.max(1);
    let spacing = 0.45;
    let cube_scale = 0.35;
    let half_x = (nx as f32 - 1.0) * spacing * 0.5;

    for y in 0..ny {
        for x in 0..nx {
            let px = x as f32 * spacing - half_x;
            let py = y as f32 * spacing;
            spawn_cube(
                universe,
                spot,
                (px, py, z),
                (cube_scale, cube_scale, cube_scale),
                None,
                None,
            );
        }
    }

    // Label in front of the plane.
    let label = format!(
        "XY plane: {}x{}\nopacity: {:.2}\nmulti-layer: false",
        nx, ny, opacity
    );
    let label_x = spot_pos.0 - (half_x + 0.6);
    let label_y = spot_pos.1 + (ny as f32 * spacing) + 1.2;
    let label_z = spot_pos.2 - 2.5;
    spawn_text_label_with_bg(universe, (label_x, label_y, label_z), &label, 0.50);
}

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

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

    // Dark brown / pink background.
    let bg = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let bg_c = universe
        .world
        .add_component(ColorComponent::rgba(0.22, 0.08, 0.10, 1.0));
    let _ = universe.world.add_child(bg, bg_c);
    universe.add(bg);

    // Ambient so unlit areas aren't black.
    let ambient = universe
        .world
        .add_component(AmbientLightComponent::rgb(0.35, 0.35, 0.40));
    universe.add(ambient);

    // A bright overhead light.
    let light_t = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, 18.0, 10.0)
            .with_scale(0.2, 0.2, 0.2),
    );
    let light = universe.world.add_component(
        PointLightComponent::new()
            .with_color(1.0, 1.0, 1.0)
            .with_intensity(1.6)
            .with_distance(80.0),
    );
    let _ = universe.attach(light_t, light);
    universe.add(light_t);

    // --- Camera rig ---
    // I { T { C3D { with_fps_rotation with_roll_axis_y } } }
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(3.0));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_roll_axis_y()
            .with_fps_rotation(),
    );
    let _ = universe.attach(input, input_mode);

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

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

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

    // --- Ground ---
    let ground = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, -0.6, 0.0)
            .with_scale(60.0, 1.0, 60.0),
    );
    let ground_r = universe.world.add_component(RenderableComponent::cube());
    let ground_c = universe
        .world
        .add_component(ColorComponent::rgba(0.95, 0.95, 0.95, 1.0));
    let _ = universe.attach(ground, ground_r);
    let _ = universe.attach(ground_r, ground_c);
    universe.add(ground);

    // --- Opaque yellow cubes behind (contrast reference) ---
    for i in 0..6 {
        let x = -10.0 + i as f32 * 4.0;
        spawn_cube(
            &mut universe,
            ground,
            (x, 1.2, -18.0),
            (2.0, 2.0, 2.0),
            Some((1.0, 0.92, 0.15, 1.0)),
            None,
        );
    }

    // --- Demo spots ---
    // Left of the left big spot: a single-layer transparent XY plane (16x16).
    spawn_demo_xy_plane(&mut universe, (-14.0, 0.0, 0.0), 0.50, 16, 16, 0.0);

    // Big spots: 8x8x8
    // Left: single-layer transparent (instanced)
    spawn_demo_spot(&mut universe, (-4.0, 0.0, 0.0), 0.50, false, 8);

    // Right: multi-layer transparent (sorted)
    spawn_demo_spot(&mut universe, (4.0, 0.0, 0.0), 0.50, true, 8);

    // Small spots: opaque 1x4 strip + transparent 1x4 strip (along Z).
    spawn_demo_strip_pair(&mut universe, (-4.0, 0.0, 10.0), false);
    spawn_demo_strip_pair(&mut universe, (4.0, 0.0, 10.0), true);

    // Process init-time registrations.
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

    universe.enable_repl();

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

examples/animation-for-topology.rs (lines 27-31)

fn spawn_emissive_marker_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    local_pos: (f32, f32, f32),
    scale: f32,
    rgba: [f32; 4],
) {
    let tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new()
            .with_position(local_pos.0, local_pos.1, local_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);
}

/// Create a cube subtree ahead-of-time (not attached to the scene).
///
/// Returns the root `TransformComponent` id.
fn spawn_detached_cube_prefab(
    universe: &mut engine::Universe,
    scale: f32,
    rgba: [f32; 4],
) -> engine::ecs::ComponentId {
    let tx = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().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(tx, r);
    let _ = universe.attach(r, c);
    let _ = universe.attach(r, e);

    tx
}

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/router.rs (line 32)

fn spawn_runtime_text(
    universe: &mut engine::Universe,
    owner: engine::ecs::ComponentId,
    label: &str,
) {
    use engine::ecs::component::{
        ColorComponent, EdgeInsets, SizeDimension, StyleComponent, TextComponent,
        TransformComponent,
    };

    let root = universe
        .world
        .add_component_boxed_named(label, Box::new(TransformComponent::new()));
    let style = universe.world.add_component_boxed_named(
        format!("{label}_style"),
        Box::new({
            let mut style = StyleComponent::new();
            style.margin = EdgeInsets::all(0.5);
            style.padding = EdgeInsets::axes(0.75, 0.5);
            style.width = SizeDimension::Auto;
            style.background_color = Some([0.93, 0.88, 0.98, 1.0]);
            style
        }),
    );
    let text = universe
        .world
        .add_component_boxed_named(format!("{label}_text"), Box::new(TextComponent::new(label)));
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.38, 0.14, 0.62, 1.0));

    let _ = universe.world.add_child(root, style);
    let _ = universe.world.add_child(root, text);
    let _ = universe.world.add_child(text, color);

    universe.attach(owner, root).expect("attach routed child");
}

examples/example_util/mod.rs (line 27)

pub fn spawn_mms_demo_rig(
    universe: &mut engine::Universe,
    cam_pos: [f32; 3],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        BackgroundColorComponent, Camera3DComponent, InputComponent, InputTransformModeComponent,
        TransformComponent,
    };

    // Dark blue clear colour.
    let bg_color = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let bg_color_c = universe
        .world
        .add_component(ColorComponent::rgba(0.02, 0.03, 0.10, 1.0));
    let _ = universe.world.add_child(bg_color, bg_color_c);
    universe.add(bg_color);

    // Camera rig: Input → Transform → Camera3D.
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(3.0));
    let input_mode = universe
        .world
        .add_component(InputTransformModeComponent::forward_z().with_roll_axis_y());
    let _ = universe.attach(input, input_mode);

    let cam_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(cam_pos[0], cam_pos[1], cam_pos[2]));
    let _ = universe.attach(input, cam_transform);

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

    universe.add(input);

    spawn_desktop_camera_controls_hint(universe, cam_transform);

    cam_transform
}

fn hash_u32(mut x: u32) -> u32 {
    x ^= x >> 16;
    x = x.wrapping_mul(0x7feb_352d);
    x ^= x >> 15;
    x = x.wrapping_mul(0x846c_a68b);
    x ^= x >> 16;
    x
}

fn rand01(seed: u32) -> f32 {
    (hash_u32(seed) as f32) / (u32::MAX as f32)
}

#[derive(Debug, Clone, Copy)]
pub struct CloudRingParams {
    pub cloud_count: u32,
    pub radius: f32,
    pub center_y: f32,
    pub puffs_per_cloud: u32,
    /// 0.0 = perfectly evenly spaced, 1.0 = up to one full step of jitter.
    pub angle_jitter: f32,
    /// Probability a given cluster is placed higher than `center_y`.
    pub high_y_probability: f32,
    /// Multiplier applied to `center_y` when a cluster is chosen to be high.
    pub high_y_multiplier: f32,
    /// Seed used for deterministic layout variation.
    pub seed: u32,
}

impl Default for CloudRingParams {
    fn default() -> Self {
        Self {
            cloud_count: 5,
            radius: 26.0,
            center_y: 2.0,
            puffs_per_cloud: 28,
            angle_jitter: 0.0,
            high_y_probability: 0.0,
            high_y_multiplier: 1.0,
            seed: 0xC10u32,
        }
    }
}

/// Spawns a ring of "cloud" puff clusters under an existing background root.
///
/// Assumes `bg_root` is a `BackgroundComponent` (usually `with_occlusion_and_lighting()`).
pub fn spawn_cloud_ring(
    universe: &mut engine::Universe,
    bg_root: engine::ecs::ComponentId,
    p: CloudRingParams,
) {
    if p.cloud_count == 0 || p.radius == 0.0 {
        return;
    }

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

    let step = std::f32::consts::TAU / (p.cloud_count as f32);
    let angle_jitter = p.angle_jitter.clamp(0.0, 1.0);
    let high_y_probability = p.high_y_probability.clamp(0.0, 1.0);

    for i in 0..p.cloud_count {
        let seed_i = p.seed ^ i.wrapping_mul(0x9E37_79B9);
        let jitter = (rand01(seed_i ^ 0xa53a_9d2d) - 0.5) * step * angle_jitter;
        let a = (i as f32) * step + jitter;
        let cx = p.radius * a.cos();
        let cz = p.radius * a.sin();

        let cy = if rand01(seed_i ^ 0x7f4a_7c15) < high_y_probability {
            p.center_y * p.high_y_multiplier
        } else {
            p.center_y
        };

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

        let base_seed = seed_i ^ 0x243f_6a88;
        for puff_i in 0..p.puffs_per_cloud {
            let seed = base_seed ^ puff_i.wrapping_mul(1_103_515_245);

            let ox = (rand01(seed ^ 0x68bc_21eb) - 0.5) * 9.0;
            let oy = (rand01(seed ^ 0x02e5_be93) - 0.5) * 4.0;
            let oz = (rand01(seed ^ 0xa1d3_4f2b) - 0.5) * 9.0;

            let base = 0.7 + rand01(seed ^ 0x9e37_79b9) * 2.8;
            let sx = base * (0.7 + rand01(seed ^ 0x243f_6a88) * 0.9);
            let sy = base * (0.6 + rand01(seed ^ 0x85a3_08d3) * 1.0);
            let sz = base * (0.7 + rand01(seed ^ 0x1319_8a2e) * 0.9);

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

            let t = rand01(seed ^ 0x7f4a_7c15);
            let r = 0.70 + 0.10 * t;
            let g = 0.72 + 0.10 * t;
            let b = 0.80 + 0.12 * t;
            let color = universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(r, g, b, 1.0));

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

/// Spawn a small camera-attached help text for desktop controls.
///
/// The returned component is the hint root `TransformComponent`.
///
/// This is intended for examples that use the common topology:
///
/// `I { T { C3D } }` (InputComponent → TransformComponent → Camera3DComponent)
pub fn spawn_desktop_camera_controls_hint(
    universe: &mut engine::Universe,
    camera_transform: engine::ecs::ComponentId,
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, EditorComponent, EmissiveComponent, RaycastableComponent, TextComponent,
        TextureFilteringComponent, TransformComponent,
    };

    // We intentionally do NOT parent the hint under the camera rig.
    // This keeps it out of the camera subtree (and avoids inheriting camera motion/rotation).
    //
    // Instead, we place it in world space based on the camera rig's current pose.
    // That makes it start out “in front-right of the camera” without being attached.
    let (cam_pos, cam_rot) = universe
        .world
        .get_component_by_id_as::<TransformComponent>(camera_transform)
        .map(|t| (t.transform.translation, t.transform.rotation))
        .unwrap_or(([0.0, 0.0, 0.0], [0.0, 0.0, 0.0, 1.0]));

    // Camera convention in examples: forward is -Z.
    // Local-space offset from the camera rig at spawn time.
    let local_offset = [0.65, 0.25, -1.7];

    // Rotate the offset by the camera rig's rotation so it appears in front-right of the view.
    let world_offset = mittens_engine::utils::math::quat_rotate_vec3(cam_rot, local_offset);
    let world_pos = [
        cam_pos[0] + world_offset[0],
        cam_pos[1] + world_offset[1],
        cam_pos[2] + world_offset[2],
    ];

    let hint_root = universe.world.add_component(
        TransformComponent::new()
            .with_position(world_pos[0], world_pos[1], world_pos[2])
            .with_scale(0.055, 0.055, 1.0),
    );

    // Put the hint into an editor subtree so clicking it attaches gizmos.
    let editor_root = universe.world.add_component(EditorComponent::new());
    let _ = universe.attach(hint_root, editor_root);

    let text = universe.world.add_component(TextComponent::new(
        "use wasd/rf/qe\nand right-mouse\nclick and drag\nto move/look",
    ));

    // Make glyph renderables raycastable so the hint can be clicked without adding a
    // large invisible pick plane (clicking is per-glyph / per-text-quad).
    let raycastable = universe
        .world
        .add_component(RaycastableComponent::enabled());
    let _ = universe.attach(text, raycastable);

    // Text color should be an immediate child of the TextComponent root.
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.0, 0.0, 0.0, 1.0));
    let _ = universe.attach(text, color);

    // TextSystem looks for these as immediate children of the TextComponent root.
    let emissive = universe.world.add_component(EmissiveComponent::on());
    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest_magnification());

    let cutout = universe
        .world
        .add_component(TransparentCutoutComponent::new());
    let _ = universe.attach(text, cutout);

    let _ = universe.attach(editor_root, text);
    let _ = universe.attach(text, emissive);
    let _ = universe.attach(text, filtering);

    // Ensure the text is initialized even if the caller only adds the camera rig.
    universe.add(hint_root);

    hint_root
}

examples/simple-demo.rs (lines 33-38)

fn build_demo_scene_7_shapes(universe: &mut engine::Universe) {
    use engine::ecs::component::{
        Camera3DComponent, ColorComponent, EmissiveComponent, GLTFComponent, InputComponent,
        InputTransformModeComponent, PointLightComponent, RenderableComponent, TextureComponent,
        TransformComponent,
    };
    use engine::graphics::BuiltinMeshType;
    use engine::graphics::primitives::MaterialHandle;

    // Built-in CPU meshes are pre-registered; just fetch stable handles.
    let tri_mesh = universe.render_assets.get_mesh(BuiltinMeshType::Triangle2D);
    let square_mesh = universe.render_assets.get_mesh(BuiltinMeshType::Quad2D);
    let tetra_mesh = universe
        .render_assets
        .get_mesh(BuiltinMeshType::Tetrahedron);

    fn spawn(
        universe: &mut engine::Universe,
        mesh: engine::graphics::primitives::CpuMeshHandle,
        x: f32,
        y: f32,
        s: f32,
        r: f32,
        color: [f32; 4],
        input_driven: bool,
        emissive: bool,
    ) -> engine::ecs::ComponentId {
        let transform = universe.world.add_component(
            TransformComponent::new()
                .with_position(x, y, 0.0)
                .with_scale(s, s, 1.0)
                .with_rotation_euler(0.0, 0.0, r),
        );
        let renderable = universe.world.add_component(RenderableComponent::new(
            engine::graphics::primitives::Renderable::new(mesh, MaterialHandle::TOON_MESH),
        ));
        let color_c = universe.world.add_component(ColorComponent { rgba: color });

        if emissive {
            let emissive_c = universe.world.add_component(EmissiveComponent::on());
            let _ = universe.attach(renderable, emissive_c);
        }

        // Topology: (optional Input) -> Transform -> Renderable
        let _ = universe.attach(transform, renderable);
        let _ = universe.attach(renderable, color_c);

        if input_driven {
            let input = universe
                .world
                .add_component(InputComponent::new().with_speed(0.5));
            let _ = universe.attach(input, transform);
            universe.add(input);
        } else {
            universe.add(transform);
        }

        transform
    }

    fn spawn_3d(
        universe: &mut engine::Universe,
        mesh: engine::graphics::primitives::CpuMeshHandle,
        x: f32,
        y: f32,
        z: f32,
        s: f32,
        rx: f32,
        ry: f32,
        rz: f32,
        color: [f32; 4],
    ) -> engine::ecs::ComponentId {
        let transform = universe.world.add_component(
            TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(s, s, s)
                .with_rotation_euler(rx, ry, rz),
        );
        let renderable = universe.world.add_component(RenderableComponent::new(
            engine::graphics::primitives::Renderable::new(mesh, MaterialHandle::TOON_MESH),
        ));
        let color_c = universe.world.add_component(ColorComponent { rgba: color });

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

        transform
    }

    // Spawn shapes.
    // One triangle is input-driven (WASD/QE). Build a small "rig" so both the triangle
    // and the camera can be driven by the same InputComponent.

    // Topology: Input -> (InputTransformMode) -> RigTransform -> (CameraTransform -> Camera3D), (TriRootTransform -> ...)
    let tri_input = universe
        .world
        .add_component(InputComponent::new().with_speed(0.5));
    let input_mode = universe
        .world
        .add_component(InputTransformModeComponent::forward_z().with_roll_axis_y());
    let _ = universe.attach(tri_input, input_mode);

    // Start pulled back so the demo meshes at z=0 are in view.
    // The camera will be attached directly under this transform, so there is no local
    // camera offset that would cause orbiting when yawing.
    let rig_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 2.5));
    let _ = universe.attach(tri_input, rig_transform);

    // Camera: attached directly to the rig transform.
    let camera3d = universe.world.add_component(Camera3DComponent::new());
    let _ = universe.attach(rig_transform, camera3d);

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

    let tri_root_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(0.5, 0.50, 0.0));

    // Visual transform under the root; this is where we apply rotation/scale.
    let tri_visual_transform = universe.world.add_component(
        TransformComponent::new()
            .with_scale(0.30, 0.30, 1.0)
            .with_rotation_euler(0.0, 0.0, (2.0 * 3.14159 / 3.0) + 3.14159),
    );
    let tri_renderable = universe.world.add_component(RenderableComponent::new(
        engine::graphics::primitives::Renderable::new(tri_mesh, MaterialHandle::TOON_MESH),
    ));
    let tri_color = universe
        .world
        .add_component(ColorComponent::rgba(0.2, 1.0, 0.2, 1.0));

    let _ = universe.attach(rig_transform, tri_root_transform);
    let _ = universe.attach(tri_root_transform, tri_visual_transform);
    let _ = universe.attach(tri_visual_transform, tri_renderable);
    let _ = universe.attach(tri_renderable, tri_color);

    let tri_light = universe.world.add_component(
        PointLightComponent::new()
            .with_distance(10.0)
            .with_color(1.0, 1.0, 1.0),
    );

    let light_transform = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.5, 0.50, 1.0)
            .with_scale(0.1, 0.1, 0.1),
    );

    let _ = universe.attach(light_transform, tri_light);

    universe.add(tri_input);
    universe.add(light_transform);

    spawn(
        universe,
        square_mesh,
        -0.80,
        -0.30,
        0.25,
        0.0,
        [1.0, 0.2, 0.2, 1.0],
        false,
        true,
    );
    spawn(
        universe,
        square_mesh,
        -0.40,
        -0.30,
        0.25,
        0.0,
        [1.0, 0.6, 0.2, 1.0],
        false,
        true,
    );

    // 3D primitive: tetrahedron.
    spawn_3d(
        universe,
        tetra_mesh,
        0.55,
        -0.15,
        0.0,
        0.35,
        0.75,
        0.55,
        0.0,
        [0.2, 0.7, 1.0, 1.0],
    );
    spawn(
        universe,
        square_mesh,
        0.00,
        -0.30,
        0.25,
        0.0,
        [1.0, 1.0, 0.2, 1.0],
        false,
        true,
    );
    spawn(
        universe,
        square_mesh,
        0.40,
        -0.30,
        0.25,
        0.0,
        [0.2, 0.6, 1.0, 1.0],
        false,
        true,
    );
    spawn(
        universe,
        square_mesh,
        0.80,
        -0.30,
        0.25,
        0.0,
        [0.8, 0.2, 1.0, 1.0],
        false,
        true,
    );
    spawn(
        universe,
        tri_mesh,
        0.30,
        0.35,
        0.30,
        -3.14159,
        [1.0, 1.0, 1.0, 1.0],
        false,
        false,
    );

    // Textured square.
    let tex_transform = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, 0.1, 0.0)
            .with_scale(0.45, 0.45, 1.0),
    );
    let tex_renderable = universe.world.add_component(RenderableComponent::new(
        engine::graphics::primitives::Renderable::new(square_mesh, MaterialHandle::TOON_MESH),
    ));
    let tex_color = universe
        .world
        .add_component(ColorComponent::rgba(1.0, 1.0, 1.0, 1.0));
    let tex = universe.world.add_component(TextureComponent::from_dds(
        "assets/textures/cat-face-amused.dds",
    ));

    let _ = universe.attach(tex_transform, tex_renderable);
    let _ = universe.attach(tex_renderable, tex_color);
    let _ = universe.attach(tex_renderable, tex);
    universe.add(tex_transform);

    // glTF: color-cat
    // Attach GLTFComponent under a Transform so GLTFSystem can use it as an anchor.
    let cat_anchor = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, -0.10, -4.0)
            .with_scale(0.50, 0.50, 0.50)
            .with_rotation_euler(0.0, 0.0, 0.0),
    );
    let cat_gltf = universe
        .world
        .add_component(GLTFComponent::new("assets/models/color-cat.2.glb"));
    let _ = universe.attach(cat_anchor, cat_gltf);
    universe.add(cat_anchor);
}

Additional examples can be found in:

• examples/pointer-events.rs
• examples/diy-panel.rs
• examples/util/mod.rs
• examples/vr-input.rs
• examples/vtuber-mirror-example.rs
• examples/vtuber-editor-example.rs
• examples/triage/panel-pierce.rs
• examples/scrolling.rs
• examples/audio-clip-instance-demo.rs
• examples/audio-music-demo.rs
• examples/button-press.rs
• examples/text-animation.rs
• examples/vtuber-example.rs
• examples/openxr.rs
• examples/text-example.rs
• examples/gestures-and-gizmos.rs
• examples/background-example.rs
• examples/mesh-factory-example.rs
• examples/bisket-vr-demo.rs
• examples/background-occlusion-example.rs
• examples/raycast-topology-animation.rs
• examples/font-example.rs
• examples/vtuber-joints-example.rs
• examples/animation-example.rs
• examples/folder-text.rs
• examples/collision-perimeter.rs
• examples/audio-graph-example.rs
• examples/gravity-fields.rs

pub fn register<T: Component>(&mut self, c: T) -> ComponentId

Register a new component in the world and return its id.

This is intentionally a storage/identity operation only: it does not call Component::init.

Examples found in repository

examples/raycast-topology-animation.rs (line 49)

fn ensure_emissive_on(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
) {
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::EmissiveComponent>(ch)
                .is_some()
        });

    if existing.is_some() {
        return;
    }

    let emissive_cid = world.register(engine::ecs::component::EmissiveComponent::on());
    let _ = world.add_child(renderable_cid, emissive_cid);
    emit.push_intent_now(
        emissive_cid,
        engine::ecs::IntentValue::RegisterEmissive {
            component_ids: vec![emissive_cid],
        },
    );
}

examples/gravity-fields.rs (lines 60-62)

fn set_renderable_color_rgba(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
    rgba: [f32; 4],
) {
    // Prefer existing ColorComponent.
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::ColorComponent>(ch)
                .is_some()
        });

    if let Some(color_cid) = existing {
        if let Some(c) =
            world.get_component_by_id_as_mut::<engine::ecs::component::ColorComponent>(color_cid)
        {
            c.rgba = rgba;
            emit.push_intent_now(
                color_cid,
                engine::ecs::IntentValue::RegisterColor {
                    component_ids: vec![color_cid],
                },
            );
        }
        return;
    }

    // Fallback: add a ColorComponent child if missing.
    let color_cid = world.register(engine::ecs::component::ColorComponent::rgba(
        rgba[0], rgba[1], rgba[2], rgba[3],
    ));
    let _ = world.add_child(renderable_cid, color_cid);
    emit.push_intent_now(
        color_cid,
        engine::ecs::IntentValue::RegisterColor {
            component_ids: vec![color_cid],
        },
    );
}

pub fn is_initialized(&self, c: ComponentId) -> bool

Whether this component has had Component::init invoked.

pub fn add_component_boxed(&mut self, c: Box<dyn Component>) -> ComponentId

Add a new component to the world (no parent). Returns its global id.

pub fn add_component_boxed_named( &mut self, name: impl Into<String>, c: Box<dyn Component>, ) -> ComponentId

Add a new boxed component with an explicit stored name.

Examples found in repository

examples/router.rs (line 15)

fn spawn_runtime_text(
    universe: &mut engine::Universe,
    owner: engine::ecs::ComponentId,
    label: &str,
) {
    use engine::ecs::component::{
        ColorComponent, EdgeInsets, SizeDimension, StyleComponent, TextComponent,
        TransformComponent,
    };

    let root = universe
        .world
        .add_component_boxed_named(label, Box::new(TransformComponent::new()));
    let style = universe.world.add_component_boxed_named(
        format!("{label}_style"),
        Box::new({
            let mut style = StyleComponent::new();
            style.margin = EdgeInsets::all(0.5);
            style.padding = EdgeInsets::axes(0.75, 0.5);
            style.width = SizeDimension::Auto;
            style.background_color = Some([0.93, 0.88, 0.98, 1.0]);
            style
        }),
    );
    let text = universe
        .world
        .add_component_boxed_named(format!("{label}_text"), Box::new(TextComponent::new(label)));
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.38, 0.14, 0.62, 1.0));

    let _ = universe.world.add_child(root, style);
    let _ = universe.world.add_child(root, text);
    let _ = universe.world.add_child(text, color);

    universe.attach(owner, root).expect("attach routed child");
}

examples/diy-panel.rs (lines 15-18)

fn spawn_runtime_text(
    universe: &mut engine::Universe,
    owner: engine::ecs::ComponentId,
    label: &str,
) {
    use engine::ecs::component::{
        ColorComponent, EdgeInsets, SizeDimension, StyleComponent, TextComponent,
        TransformComponent,
    };

    let root = universe.world.add_component_boxed_named(
        label,
        Box::new(TransformComponent::new().with_position(0.0, 0.0, 0.2)),
    );
    let style = universe.world.add_component_boxed_named(
        format!("{label}_style"),
        Box::new({
            let mut style = StyleComponent::new();
            style.margin = EdgeInsets::axes(0.25, 0.25);
            style.padding = EdgeInsets::axes(0.5, 0.5);
            style.height = SizeDimension::GlyphUnits(2.5);
            style.width = SizeDimension::Auto;
            style.background_color = Some([1.0, 0.80, 0.80, 1.0]);
            style
        }),
    );
    let text_root = universe.world.add_component_boxed_named(
        format!("{label}_text_root"),
        Box::new(TransformComponent::new().with_position(0.0, 0.0, 0.2)),
    );
    let text = universe
        .world
        .add_component_boxed_named(format!("{label}_text"), Box::new(TextComponent::new(label)));
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.40, 0.05, 0.05, 1.0));

    let _ = universe.world.add_child(root, style);
    let _ = universe.world.add_child(root, text_root);
    let _ = universe.world.add_child(text_root, text);
    let _ = universe.world.add_child(text, color);

    universe.attach(owner, root).expect("attach routed child");
}

examples/triage/panel-pierce.rs (lines 26-29)

fn spawn_row(
    universe: &mut engine::Universe,
    scrolling: engine::ecs::ComponentId,
    index: usize,
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, RenderableComponent, TextComponent, TransformComponent,
    };

    let label = format!("row_{index:02}");
    let row = universe.world.add_component_boxed_named(
        label.clone(),
        Box::new(TransformComponent::new().with_position(0.0, -(index as f32) * 1.15, 0.05)),
    );
    let panel = universe.world.add_component_boxed_named(
        format!("{label}_panel"),
        Box::new(
            TransformComponent::new()
                .with_position(2.3, -0.45, 0.0)
                .with_scale(4.6, 0.9, 1.0),
        ),
    );
    let panel_renderable = universe.world.add_component_boxed_named(
        format!("{label}_rend"),
        Box::new(RenderableComponent::square()),
    );
    let panel_color = universe
        .world
        .add_component(ColorComponent::rgba(0.98, 0.94, 0.78, 1.0));

    let text_anchor = universe.world.add_component_boxed_named(
        format!("{label}_text_anchor"),
        Box::new(
            TransformComponent::new()
                .with_position(0.35, -0.38, 0.02)
                .with_scale(0.11, 0.11, 0.11),
        ),
    );
    let text = universe.world.add_component_boxed_named(
        format!("{label}_text"),
        Box::new(TextComponent::new(label.clone())),
    );
    let text_color = universe
        .world
        .add_component(ColorComponent::rgba(0.20, 0.16, 0.08, 1.0));

    let _ = universe.world.add_child(row, panel);
    let _ = universe.world.add_child(panel, panel_renderable);
    let _ = universe.world.add_child(panel_renderable, panel_color);
    let _ = universe.world.add_child(row, text_anchor);
    let _ = universe.world.add_child(text_anchor, text);
    let _ = universe.world.add_child(text, text_color);

    universe.attach(scrolling, row).expect("attach scroll row");
    row
}

examples/scrolling.rs (lines 43-46)

fn spawn_scroll_item(
    universe: &mut engine::Universe,
    scrolling: engine::ecs::ComponentId,
    prefix: &str,
    index: usize,
    panel_rgba: [f32; 4],
    text_rgba: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, RenderableComponent, TextComponent, TransformComponent,
    };

    let label = format!("{prefix}_item_{index:02}");
    let root = universe.world.add_component_boxed_named(
        label.clone(),
        Box::new(TransformComponent::new().with_position(0.0, -(index as f32) * 1.15, 0.05)),
    );
    let panel = universe.world.add_component_boxed_named(
        format!("{label}_panel"),
        Box::new(
            TransformComponent::new()
                .with_position(2.3, -0.45, 0.0)
                .with_scale(4.6, 0.9, 1.0),
        ),
    );
    let panel_renderable = universe.world.add_component_boxed_named(
        format!("{label}_renderable"),
        Box::new(RenderableComponent::square()),
    );
    let panel_color = universe.world.add_component(ColorComponent::rgba(
        panel_rgba[0],
        panel_rgba[1],
        panel_rgba[2],
        panel_rgba[3],
    ));

    let text_anchor = universe.world.add_component_boxed_named(
        format!("{label}_text_anchor"),
        Box::new(
            TransformComponent::new()
                .with_position(0.35, -0.38, 0.02)
                .with_scale(0.11, 0.11, 0.11),
        ),
    );
    let text = universe.world.add_component_boxed_named(
        format!("{label}_text"),
        Box::new(TextComponent::new(label.clone())),
    );
    let text_color = universe.world.add_component(ColorComponent::rgba(
        text_rgba[0],
        text_rgba[1],
        text_rgba[2],
        text_rgba[3],
    ));

    let _ = universe.world.add_child(root, panel);
    let _ = universe.world.add_child(panel, panel_renderable);
    let _ = universe.world.add_child(panel_renderable, panel_color);
    let _ = universe.world.add_child(root, text_anchor);
    let _ = universe.world.add_child(text_anchor, text);
    let _ = universe.world.add_child(text, text_color);

    universe
        .attach(scrolling, root)
        .expect("attach scroll item");
    root
}

examples/vtuber-joints-example.rs (lines 198-205)

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

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

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    let print_transform_updates: bool = false;

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

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

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

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

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

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

pub fn add_component_boxed_with_guid_named( &mut self, guid: Uuid, name: impl Into<String>, c: Box<dyn Component>, ) -> ComponentId

Add a new boxed component with a restored GUID and explicit stored name.

This is intended for deserialization.

pub fn spawn_component_boxed(&mut self, c: Box<dyn Component>) -> ComponentId

Temporary alias during migration.

pub fn get_component_record(&self, id: ComponentId) -> Option<&ComponentNode>

Examples found in repository

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

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

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

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    let print_transform_updates: bool = false;

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

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

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

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

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

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

fn select_named_joints(
    world: &engine::ecs::World,
    all_joints: &[(usize, engine::ecs::ComponentId)],
    names: &[String],
) -> Option<Vec<(usize, engine::ecs::ComponentId)>> {
    if names.is_empty() {
        return None;
    }

    let mut out: Vec<(usize, engine::ecs::ComponentId)> = Vec::new();
    for wanted in names {
        let mut found: Option<(usize, engine::ecs::ComponentId)> = None;
        for &(node_index, joint_tx) in all_joints.iter() {
            let name = world
                .get_component_record(joint_tx)
                .map(|r| r.name.as_str())
                .unwrap_or("");
            if name == wanted {
                found = Some((node_index, joint_tx));
                break;
            }
        }

        if let Some(v) = found {
            out.push(v);
        } else {
            println!(
                "[vtuber-joints-example] warning: target joint '{}' not found (check names via REPL tree)",
                wanted
            );
        }
    }

    if out.is_empty() { None } else { Some(out) }
}

fn debug_print_selected_joint_influence(
    universe: &engine::Universe,
    mesh_key: &str,
    model_root: engine::ecs::ComponentId,
    selected: &[(usize, engine::ecs::ComponentId)],
) {
    let Some(renderable) = find_renderable_by_mesh_key(&universe.world, model_root, mesh_key)
    else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' renderable not found",
            mesh_key
        );
        return;
    };

    let renderable_handle = universe
        .world
        .get_component_by_id_as::<RenderableComponent>(renderable)
        .and_then(|r| r.get_handle());
    println!(
        "[vtuber-joints-example] influence: mesh_key='{}' renderable={:?} instance_handle={:?}",
        mesh_key, renderable, renderable_handle
    );
    let Some(skin_id) = find_skin_id_for_renderable(&universe.world, renderable) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' has no skin_id",
            mesh_key
        );
        return;
    };
    let Some(skin) = universe.visuals.skin(skin_id) else {
        println!(
            "[vtuber-joints-example] influence: skin_id={:?} missing in visuals",
            skin_id
        );
        return;
    };
    let Some(cpu_h) = universe.render_assets.imported_mesh(mesh_key) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' missing in RenderAssets (did meshes register?)",
            mesh_key
        );
        return;
    };
    let Some(cpu) = universe.render_assets.cpu_mesh(cpu_h) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' cpu mesh handle invalid",
            mesh_key
        );
        return;
    };
    let (Some(joints0), Some(weights0)) = (cpu.joints0.as_ref(), cpu.weights0.as_ref()) else {
        println!(
            "[vtuber-joints-example] influence: mesh_key='{}' has no skin attributes",
            mesh_key
        );
        return;
    };

    let joint_count = skin.joint_count();
    let totals = compute_total_weight_per_joint(joints0, weights0, joint_count);

    println!(
        "[vtuber-joints-example] influence: mesh_key='{}' verts={} joints={}",
        mesh_key,
        cpu.vertices.len(),
        joint_count
    );

    for &(node_index, joint_tx) in selected.iter() {
        // Find the skin joint index that maps to this node.
        let skin_joint_index = skin
            .joint_node_indices
            .iter()
            .position(|&ni| ni == node_index);

        let name = universe
            .world
            .get_component_record(joint_tx)
            .map(|r| r.name.as_str())
            .unwrap_or("<unknown>");

        match skin_joint_index {
            Some(j) => {
                let total = totals.get(j).copied().unwrap_or(0.0);
                println!(
                    "  influence: name='{}' node_index={} skin_joint_index={} total_weight={:.3}",
                    name, node_index, j, total
                );
            }
            None => {
                println!(
                    "  influence: name='{}' node_index={} skin_joint_index=<none>",
                    name, node_index
                );
            }
        }
    }
}

fn compute_total_weight_per_joint(
    joints0: &[[u16; 4]],
    weights0: &[[f32; 4]],
    joint_count: usize,
) -> Vec<f32> {
    let mut totals = vec![0.0f32; joint_count];
    if joint_count == 0 {
        return totals;
    }
    for (jv, wv) in joints0.iter().zip(weights0.iter()) {
        for lane in 0..4 {
            let j = jv[lane] as usize;
            if j >= joint_count {
                continue;
            }
            let w = wv[lane];
            if w > 0.0 {
                totals[j] += w;
            }
        }
    }
    totals
}

fn select_body_prim0_influencers(
    universe: &engine::Universe,
    model_root: engine::ecs::ComponentId,
    mesh_key: &str,
    count: usize,
    node_index_to_transform: &HashMap<usize, engine::ecs::ComponentId>,
) -> Option<Vec<(usize, engine::ecs::ComponentId)>> {
    if count == 0 {
        return Some(Vec::new());
    }

    let renderable = find_renderable_by_mesh_key(&universe.world, model_root, mesh_key)?;
    let skin_id = find_skin_id_for_renderable(&universe.world, renderable)?;
    let skin = universe.visuals.skin(skin_id)?;

    let cpu_h = universe.render_assets.imported_mesh(mesh_key)?;
    let cpu = universe.render_assets.cpu_mesh(cpu_h)?;
    let joints0 = cpu.joints0.as_ref()?;
    let weights0 = cpu.weights0.as_ref()?;

    let joint_count = skin.joint_count();
    if joint_count == 0 {
        return None;
    }

    let mut total_weight_per_joint: Vec<f32> = vec![0.0; joint_count];
    for (jv, wv) in joints0.iter().zip(weights0.iter()) {
        for lane in 0..4 {
            let j = jv[lane] as usize;
            if j >= joint_count {
                continue;
            }
            let w = wv[lane];
            if w > 0.0 {
                total_weight_per_joint[j] += w;
            }
        }
    }

    let mut ranked: Vec<(usize, f32)> =
        total_weight_per_joint.iter().copied().enumerate().collect();
    ranked.sort_by(|a, b| b.1.partial_cmp(&a.1).unwrap_or(std::cmp::Ordering::Equal));

    let min_total: f32 = 10.0;

    println!(
        "[vtuber-joints-example] auto joints for mesh_key='{}': verts={} joint_count={} min_total={}",
        mesh_key,
        cpu.vertices.len(),
        joint_count,
        min_total
    );

    let mut out: Vec<(usize, engine::ecs::ComponentId)> = Vec::with_capacity(count);
    let mut seen: HashSet<engine::ecs::ComponentId> = HashSet::new();

    for (joint_index, total) in ranked.into_iter() {
        if out.len() >= count {
            break;
        }
        if total < min_total {
            continue;
        }

        let node_index = *skin.joint_node_indices.get(joint_index)?;
        let Some(&joint_tx) = node_index_to_transform.get(&node_index) else {
            continue;
        };
        if !seen.insert(joint_tx) {
            continue;
        }

        let name = universe
            .world
            .get_component_record(joint_tx)
            .map(|n| n.name.clone())
            .unwrap_or_else(|| "<unknown>".to_string());

        println!(
            "  auto[{:<2}] joint_index={:<3} total_weight={:<10.3} node_index={:<3} name={} tx={:?}",
            out.len(),
            joint_index,
            total,
            node_index,
            name,
            joint_tx
        );

        out.push((node_index, joint_tx));
    }

    if out.is_empty() { None } else { Some(out) }
}

pub fn get_component_node(&self, id: ComponentId) -> Option<&ComponentNode>

Alias for get_component_record.

pub fn get_component_record_mut( &mut self, id: ComponentId, ) -> Option<&mut ComponentNode>

pub fn component_name(&self, id: ComponentId) -> Option<&str>

Returns the engine type identifier for this component (e.g. "transform").

Examples found in repository

examples/bisket-vr-demo.rs (line 77)

fn component_label(world: &World, id: ComponentId) -> String {
    world.component_name(id).unwrap_or("?").to_string()
}

examples/vtuber-editor-example.rs (line 11)

fn component_label(world: &World, id: ComponentId) -> String {
    world.component_name(id).unwrap_or("?").to_string()
}

examples/vtuber-mirror-example.rs (line 11)

fn component_label(world: &World, id: ComponentId) -> String {
    world.component_name(id).unwrap_or("?").to_string()
}

examples/bisket-vr-debug.rs (line 1013)

fn describe_component(world: &World, id: ComponentId) -> String {
    let label = world
        .component_label(id)
        .or_else(|| world.component_name(id));
    format!("{}({id:?})", label.unwrap_or("?"))
}

examples/qdebug.rs (line 24)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();
    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);
    let src = include_str!("qdebug.mms");
    let out = scripting::MeowMeowRunner::eval_with_world(
        src,
        &mut universe.world,
        &mut universe.systems.rx,
        &mut universe.command_queue,
    );
    for e in &out.errors {
        eprintln!("[mms-err] {e}");
    }
    println!("intents: {}", out.intents.len());
    for c in universe.world.all_components() {
        if let Some(label) = universe.world.component_label(c) {
            {
                println!(
                    "  comp {:?} type={:?} name={:?}",
                    c,
                    universe.world.component_name(c),
                    label
                );
            }
        }
    }
}

pub fn component_label(&self, id: ComponentId) -> Option<&str>

Returns the user-assigned label for this component (empty string if unset).

Examples found in repository

examples/bisket-vr-debug.rs (line 1012)

fn describe_component(world: &World, id: ComponentId) -> String {
    let label = world
        .component_label(id)
        .or_else(|| world.component_name(id));
    format!("{}({id:?})", label.unwrap_or("?"))
}

fn set_local_transform(
    emit: &mut dyn SignalEmitter,
    id: ComponentId,
    translation: [f32; 3],
    rotation_quat_xyzw: [f32; 4],
    scale: [f32; 3],
) {
    emit.push_intent_now(
        id,
        IntentValue::UpdateTransform {
            component_ids: vec![id],
            translation,
            rotation_quat_xyzw,
            scale,
        },
    );
}

fn world_pose_to_local(
    world: &World,
    id: ComponentId,
    desired_world_pos: [f32; 3],
    desired_world_rot: [f32; 4],
) -> ([f32; 3], [f32; 4], [f32; 3]) {
    let scale = world
        .get_component_by_id_as::<TransformComponent>(id)
        .map(|t| t.transform.scale)
        .unwrap_or([1.0, 1.0, 1.0]);

    let parent_world_mat = parent_world_matrix(world, id).unwrap_or(mat4_identity());
    let parent_world_rot = parent_world_rotation(world, id).unwrap_or(ident_quat());
    let inv_parent = mat4_inverse(parent_world_mat).unwrap_or(mat4_identity());
    let local_pos4 = mat4_mul_vec4(
        inv_parent,
        [
            desired_world_pos[0],
            desired_world_pos[1],
            desired_world_pos[2],
            1.0,
        ],
    );
    let local_rot = quat_mul(quat_conjugate(parent_world_rot), desired_world_rot);
    (
        [local_pos4[0], local_pos4[1], local_pos4[2]],
        local_rot,
        scale,
    )
}

fn parent_world_matrix(world: &World, id: ComponentId) -> Option<[[f32; 4]; 4]> {
    let parent = world.parent_of(id)?;
    world
        .get_component_by_id_as::<TransformComponent>(parent)
        .map(|t| t.transform.matrix_world)
}

fn parent_world_rotation(world: &World, id: ComponentId) -> Option<[f32; 4]> {
    let parent = world.parent_of(id)?;
    world
        .get_component_by_id_as::<TransformComponent>(parent)
        .map(|t| mat_to_quat(t.transform.matrix_world))
}

fn forearm_axis_world(world: &World, lower_arm: ComponentId, hand: ComponentId) -> [f32; 3] {
    let axis = vec3_sub(world_pos(world, hand), world_pos(world, lower_arm));
    if vec3_len(axis) > 1e-6 {
        vec3_normalize(axis)
    } else {
        [0.0, 0.0, 1.0]
    }
}

fn quat_delta_deg(from: [f32; 4], to: [f32; 4]) -> f32 {
    let (_, angle) = quat_to_axis_angle(quat_mul(quat_conjugate(from), to));
    angle.abs().to_degrees()
}

fn fmt_quat(q: [f32; 4]) -> String {
    format!("[{:+.3},{:+.3},{:+.3},{:+.3}]", q[0], q[1], q[2], q[3])
}

fn ident_quat() -> [f32; 4] {
    [0.0, 0.0, 0.0, 1.0]
}

fn drain(universe: &mut engine::Universe) {
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );
}

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

fn settle_world(universe: &mut engine::Universe, ticks: usize) {
    let input = InputState::default();
    for _ in 0..ticks {
        universe.systems.tick(
            &mut universe.world,
            &mut universe.visuals,
            &mut universe.render_assets,
            &input,
            &mut universe.command_queue,
            1.0 / 60.0,
        );
        drain(universe);
    }
}

fn find_components_by_name(world: &World, name: &str) -> Vec<ComponentId> {
    world
        .all_components()
        .filter(|&id| world.component_label(id).map_or(false, |n| n == name))
        .collect()
}

examples/scrolling.rs (line 6)

fn find_named(world: &engine::ecs::World, label: &str) -> engine::ecs::ComponentId {
    world
        .all_components()
        .find(|&cid| world.component_label(cid) == Some(label))
        .unwrap_or_else(|| panic!("missing component {label:?}"))
}

examples/triage/panel-pierce.rs (line 12)

fn find_named(world: &engine::ecs::World, label: &str) -> engine::ecs::ComponentId {
    world
        .all_components()
        .find(|&cid| world.component_label(cid) == Some(label))
        .unwrap_or_else(|| panic!("missing component {label:?}"))
}

examples/diy-panel.rs (line 65)

fn collect_container_items(
    world: &engine::ecs::World,
    container: engine::ecs::ComponentId,
) -> Vec<engine::ecs::ComponentId> {
    use engine::ecs::component::TransformComponent;

    world
        .children_of(container)
        .iter()
        .copied()
        .filter(|&child| {
            world
                .get_component_by_id_as::<TransformComponent>(child)
                .is_some()
                && !world
                    .component_label(child)
                    .map(|label| label.starts_with("__"))
                    .unwrap_or(false)
        })
        .collect()
}

fn decompose_world_trs(matrix_world: [[f32; 4]; 4]) -> ([f32; 3], [f32; 4], [f32; 3]) {
    let translation = [matrix_world[3][0], matrix_world[3][1], matrix_world[3][2]];
    let scale = [
        (matrix_world[0][0] * matrix_world[0][0]
            + matrix_world[0][1] * matrix_world[0][1]
            + matrix_world[0][2] * matrix_world[0][2])
            .sqrt(),
        (matrix_world[1][0] * matrix_world[1][0]
            + matrix_world[1][1] * matrix_world[1][1]
            + matrix_world[1][2] * matrix_world[1][2])
            .sqrt(),
        (matrix_world[2][0] * matrix_world[2][0]
            + matrix_world[2][1] * matrix_world[2][1]
            + matrix_world[2][2] * matrix_world[2][2])
            .sqrt(),
    ];
    let rotation = mittens_engine::utils::math::mat_to_quat(matrix_world);
    (translation, rotation, scale)
}

fn spawn_container_item_debug_clones(
    universe: &mut engine::Universe,
    container: engine::ecs::ComponentId,
) {
    use engine::ecs::IntentValue;
    use engine::ecs::system::TransformSystem;
    use mittens_engine::scripting::component_registry::{
        ce_ast_to_materialized, spawn_tree, subtree_to_ce_ast,
    };

    let items = collect_container_items(&universe.world, container);
    for (index, item) in items.into_iter().enumerate() {
        let Some(matrix_world) = TransformSystem::world_model(&universe.world, item) else {
            println!("[diy-panel-debug] skip {:?}: no world matrix", item);
            continue;
        };

        let item_label = universe
            .world
            .component_label(item)
            .unwrap_or("")
            .to_string();
        println!(
            "[diy-panel-debug] item={} label={:?} matrix_world={:?}",
            index, item_label, matrix_world,
        );

        // Subtree → MMS AST → MaterializedCE → fresh spawn.
        // Same path attach_clone uses; gives the clone fresh GUIDs and
        // routes everything through the standard component registry.
        let Ok(ce_ast) = subtree_to_ce_ast(&universe.world, item) else {
            println!(
                "[diy-panel-debug] skip {:?}: failed to encode subtree",
                item
            );
            continue;
        };
        let Ok(materialized) = ce_ast_to_materialized(&ce_ast) else {
            println!(
                "[diy-panel-debug] skip {:?}: failed to materialize CE",
                item
            );
            continue;
        };
        let Ok(clone_root) = spawn_tree(
            &materialized,
            None,
            &mut universe.world,
            &mut universe.command_queue,
        ) else {
            println!("[diy-panel-debug] skip {:?}: failed to spawn clone", item);
            continue;
        };

        universe.add(clone_root);

        let (mut clone_translation, clone_rotation, clone_scale) =
            decompose_world_trs(matrix_world);
        clone_translation[0] += DEBUG_CLONE_WORLD_OFFSET[0];
        clone_translation[1] += DEBUG_CLONE_WORLD_OFFSET[1];
        clone_translation[2] += DEBUG_CLONE_WORLD_OFFSET[2];

        universe.command_queue.push_intent_now(
            clone_root,
            IntentValue::UpdateTransform {
                component_ids: vec![clone_root],
                translation: clone_translation,
                rotation_quat_xyzw: clone_rotation,
                scale: clone_scale,
            },
        );

        let label = if item_label.is_empty() {
            format!("item_{index}")
        } else {
            format!("{}_{}", item_label, index)
        };
        println!(
            "[diy-panel-debug] cloned item={} label={:?} clone_root={:?} offset_translation={:?}",
            index, label, clone_root, clone_translation,
        );
    }
}

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

    let output = scripting::MeowMeowRunner::eval(include_str!("diy-panel.mms"));

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

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

    universe.enable_repl();

    let demo_root = universe
        .world
        .all_components()
        .find(|&cid| universe.world.component_label(cid) == Some("diy_panel_demo"))
        .expect("diy panel demo root");
    let container = universe
        .find_component(demo_root, "[name='container']")
        .expect("container target");
    let authored_child = universe
        .find_component(demo_root, "[name='authored_child']")
        .expect("authored child");

    assert_eq!(universe.parent_of(authored_child), Some(container));

    spawn_runtime_text(&mut universe, demo_root, "late child routed on attach");

    let late_child = universe
        .find_component(demo_root, "[name='late child routed on attach']")
        .expect("late child");
    assert_eq!(universe.parent_of(late_child), Some(container));

    let input = engine::user_input::InputState::default();
    universe.systems.tick(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &input,
        &mut universe.command_queue,
        0.0,
    );
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

    let scroll = universe
        .world
        .children_of(container)
        .iter()
        .copied()
        .find(|&child| {
            universe.world.component_label(child) == Some("__scroll")
                && universe
                    .world
                    .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(child)
                    .is_some()
        })
        .expect("layout-owned scroll wrapper");
    let track = universe
        .world
        .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(scroll)
        .and_then(|sc| sc.track)
        .expect("layout-owned scroll track");

    assert_eq!(universe.parent_of(authored_child), Some(track));
    assert_eq!(universe.parent_of(late_child), Some(track));

    println!(
        "[diy-panel] init-time routing verified, then layout-owned scrolling moved content into __scroll_track"
    );

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

examples/qdebug.rs (line 19)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();
    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);
    let src = include_str!("qdebug.mms");
    let out = scripting::MeowMeowRunner::eval_with_world(
        src,
        &mut universe.world,
        &mut universe.systems.rx,
        &mut universe.command_queue,
    );
    for e in &out.errors {
        eprintln!("[mms-err] {e}");
    }
    println!("intents: {}", out.intents.len());
    for c in universe.world.all_components() {
        if let Some(label) = universe.world.component_label(c) {
            {
                println!(
                    "  comp {:?} type={:?} name={:?}",
                    c,
                    universe.world.component_name(c),
                    label
                );
            }
        }
    }
}

examples/router.rs (line 82)

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

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

    let output = scripting::MeowMeowRunner::eval_with_world_at_path(
        include_str!("router.mms"),
        Some("examples/router.mms"),
        &mut universe.world,
        &mut universe.systems.rx,
        &mut universe.command_queue,
    );

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

    universe.enable_repl();

    let demo_root = universe
        .world
        .all_components()
        .find(|&cid| universe.world.component_label(cid) == Some("router_demo"))
        .expect("router demo root");
    let container = universe
        .find_component(demo_root, "[name='container']")
        .expect("container target");
    let authored_child = universe
        .find_component(demo_root, "[name='authored_child']")
        .expect("authored child");

    assert_eq!(universe.parent_of(authored_child), Some(container));

    spawn_runtime_text(&mut universe, demo_root, "late child routed on attach");

    let late_child = universe
        .find_component(demo_root, "[name='late child routed on attach']")
        .expect("late child");
    assert_eq!(universe.parent_of(late_child), Some(container));

    println!("[router-demo] init-time and attach-time routing verified");

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

pub fn parent_of(&self, c: ComponentId) -> Option<ComponentId>

Examples found in repository

examples/bisket-vr-demo.rs (line 86)

fn controller_hand_for_component(world: &World, start: ComponentId) -> Option<ControllerHand> {
    let mut cur = start;
    loop {
        if let Some(ctrl) = world.get_component_by_id_as::<ControllerXRComponent>(cur) {
            return Some(ctrl.hand);
        }
        cur = world.parent_of(cur)?;
    }
}

fn on_xr_pointer_event(world: &mut World, _emit: &mut dyn SignalEmitter, env: &Signal) {
    let Some(event) = env.event.as_ref() else {
        return;
    };
    let (kind, raycaster, renderable, hit_point) = match event {
        EventSignal::DragStart {
            raycaster,
            renderable,
            hit_point,
            ..
        } => ("DragStart", *raycaster, *renderable, Some(*hit_point)),
        EventSignal::DragMove {
            raycaster,
            renderable,
            hit_point,
            ..
        } => ("DragMove", *raycaster, *renderable, Some(*hit_point)),
        EventSignal::DragEnd {
            raycaster,
            renderable,
            hit_point,
        } => ("DragEnd", *raycaster, *renderable, *hit_point),
        EventSignal::Click {
            raycaster,
            renderable,
            hit_point,
            ..
        } => ("Click", *raycaster, *renderable, Some(*hit_point)),
        _ => return,
    };

    let Some(hand) = controller_hand_for_component(world, raycaster) else {
        return;
    };
    let hand_label = match hand {
        ControllerHand::Left => "Left",
        ControllerHand::Right => "Right",
    };
    let renderable_name = component_label(world, renderable);
    let ray_name = component_label(world, raycaster);
    if let Some(p) = hit_point {
        println!(
            "[xr-pointer] hand={} kind={} raycaster={} renderable={} hit=[{:+.3},{:+.3},{:+.3}]",
            hand_label, kind, ray_name, renderable_name, p[0], p[1], p[2]
        );
    } else {
        println!(
            "[xr-pointer] hand={} kind={} raycaster={} renderable={}",
            hand_label, kind, ray_name, renderable_name
        );
    }
}

fn on_dump_click(world: &mut World, _emit: &mut dyn SignalEmitter, env: &Signal) {
    if !matches!(env.event.as_ref(), Some(EventSignal::Click { .. })) {
        return;
    }
    let Some(targets) = DUMP_TARGETS.get() else {
        return;
    };

    let driven_p = world_pos(world, targets.driven_t);
    let driven_q = world_rot_quat(world, targets.driven_t);
    let splice_p = world_pos(world, targets.splice_head);
    let head_p = world_pos(world, targets.head_bone);
    let head_q = world_rot_quat(world, targets.head_bone);

    // Expected head pivot from HMD pose + authored eye offset convention.
    let neg_eye = [
        -targets.authored_eye_offset_head_local[0],
        -targets.authored_eye_offset_head_local[1],
        -targets.authored_eye_offset_head_local[2],
    ];
    let head_target_offset_local =
        quat_rotate_vec3(quat_rotation_y(targets.head_ik_offset_yaw), neg_eye);
    let head_target_offset_world = quat_rotate_vec3(driven_q, head_target_offset_local);
    let expected_splice = [
        driven_p[0] + head_target_offset_world[0],
        driven_p[1] + head_target_offset_world[1],
        driven_p[2] + head_target_offset_world[2],
    ];
    let splice_err = [
        splice_p[0] - expected_splice[0],
        splice_p[1] - expected_splice[1],
        splice_p[2] - expected_splice[2],
    ];

    // Camera-wrapper vs head local-offset consistency check.
    let mut cam_rel_report = String::from("camera_wrapper: <none>");
    if let Some(cam_t) = targets.camera_wrapper_t {
        let cam_p = world_pos(world, cam_t);
        let expected_cam_world_off =
            quat_rotate_vec3(head_q, targets.authored_eye_offset_head_local);
        let expected_cam = [
            head_p[0] + expected_cam_world_off[0],
            head_p[1] + expected_cam_world_off[1],
            head_p[2] + expected_cam_world_off[2],
        ];
        let cam_err = [
            cam_p[0] - expected_cam[0],
            cam_p[1] - expected_cam[1],
            cam_p[2] - expected_cam[2],
        ];
        cam_rel_report = format!(
            "camera_wrapper  pos=[{:+.3},{:+.3},{:+.3}]  expected_from_head=[{:+.3},{:+.3},{:+.3}]  err=[{:+.3},{:+.3},{:+.3}] |err|={:.4}m",
            cam_p[0],
            cam_p[1],
            cam_p[2],
            expected_cam[0],
            expected_cam[1],
            expected_cam[2],
            cam_err[0],
            cam_err[1],
            cam_err[2],
            v3_len(cam_err)
        );
    }

    // Torso tilt diagnostic (forward pitch of upper chest).
    let mut torso_report = String::from("upper_chest_tilt: <not found>");
    if let Some(upper_chest) = targets.upper_chest {
        let chest_q = world_rot_quat(world, upper_chest);
        let fwd = quat_rotate_vec3(chest_q, [0.0, 0.0, 1.0]);
        let pitch_deg = deg(fwd[1].atan2((fwd[0] * fwd[0] + fwd[2] * fwd[2]).sqrt()));
        torso_report = format!(
            "upper_chest_fwd=[{:+.3},{:+.3},{:+.3}] pitch={:+.2}deg",
            fwd[0], fwd[1], fwd[2], pitch_deg
        );
    }

    println!("\n================ BONE DUMP (click) ================");
    println!(
        "driven_t  pos=[{:+.3},{:+.3},{:+.3}]  rot_xyzw=[{:+.3},{:+.3},{:+.3},{:+.3}]",
        driven_p[0], driven_p[1], driven_p[2], driven_q[0], driven_q[1], driven_q[2], driven_q[3],
    );
    println!(
        "splice_head  pos=[{:+.3},{:+.3},{:+.3}]  expected=[{:+.3},{:+.3},{:+.3}]  err=[{:+.3},{:+.3},{:+.3}] |err|={:.4}m",
        splice_p[0],
        splice_p[1],
        splice_p[2],
        expected_splice[0],
        expected_splice[1],
        expected_splice[2],
        splice_err[0],
        splice_err[1],
        splice_err[2],
        v3_len(splice_err),
    );
    println!("{}", cam_rel_report);
    println!("{}", torso_report);
    println!(
        "\n  {:<22}  {:>7}  {:>7}  {:>7}     {:>+7}  {:>+7}  {:>+7}",
        "bone", "x", "y", "z", "Δx_to_drv", "Δy_to_drv", "Δz_to_drv"
    );
    let mut prev_pos: Option<[f32; 3]> = None;
    for (i, (label, bone_id)) in targets.bones.iter().enumerate() {
        let p = world_pos(world, *bone_id);
        println!(
            "  {:<22}  {:>+7.3}  {:>+7.3}  {:>+7.3}     {:>+7.3}  {:>+7.3}  {:>+7.3}",
            label,
            p[0],
            p[1],
            p[2],
            p[0] - driven_p[0],
            p[1] - driven_p[1],
            p[2] - driven_p[2],
        );
        // Segment length to previous bone (only meaningful within a chain —
        // spine bones are contiguous; arm bones are split per side, so we
        // insert a blank gap when the chain breaks).
        if let Some(prev) = prev_pos {
            let is_spine = label.starts_with("J_Bip_C_");
            let prev_was_spine = targets.bones[i - 1].0.starts_with("J_Bip_C_");
            let is_left_arm_step =
                label.starts_with("J_Bip_L_") && targets.bones[i - 1].0.starts_with("J_Bip_L_");
            let is_right_arm_step =
                label.starts_with("J_Bip_R_") && targets.bones[i - 1].0.starts_with("J_Bip_R_");
            if (is_spine && prev_was_spine) || is_left_arm_step || is_right_arm_step {
                let d = [(p[0] - prev[0]), (p[1] - prev[1]), (p[2] - prev[2])];
                let len = (d[0] * d[0] + d[1] * d[1] + d[2] * d[2]).sqrt();
                println!("    └─ segment from prev: len={:.4}m", len);
            }
        }
        prev_pos = Some(p);
    }
    println!("====================================================\n");
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

examples/vtuber-editor-example.rs (line 20)

fn controller_hand_for_component(world: &World, start: ComponentId) -> Option<ControllerHand> {
    let mut cur = start;
    loop {
        if let Some(ctrl) = world.get_component_by_id_as::<ControllerXRComponent>(cur) {
            return Some(ctrl.hand);
        }
        cur = world.parent_of(cur)?;
    }
}

examples/vtuber-mirror-example.rs (line 20)

fn controller_hand_for_component(world: &World, start: ComponentId) -> Option<ControllerHand> {
    let mut cur = start;
    loop {
        if let Some(ctrl) = world.get_component_by_id_as::<ControllerXRComponent>(cur) {
            return Some(ctrl.hand);
        }
        cur = world.parent_of(cur)?;
    }
}

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

fn find_parent_renderable(
    world: &engine::ecs::World,
    mut cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    while let Some(parent) = world.parent_of(cid) {
        if world
            .get_component_by_id_as::<RenderableComponent>(parent)
            .is_some()
        {
            return Some(parent);
        }
        cid = parent;
    }
    None
}

examples/gravity-fields.rs (line 10)

fn cube_renderable_sibling_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    let t = world.parent_of(collider_cid)?;
    for &sib in world.children_of(t).iter() {
        if sib == collider_cid {
            continue;
        }
        let Some(r) =
            world.get_component_by_id_as::<engine::ecs::component::RenderableComponent>(sib)
        else {
            continue;
        };
        if r.renderable.base_mesh == engine::graphics::primitives::CpuMeshHandle::CUBE {
            return Some(sib);
        }
    }
    None
}

examples/pointer-events.rs (line 64)

fn on_click_cube(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    env: &engine::ecs::Signal,
) {
    if !matches!(
        env.event.as_ref(),
        Some(engine::ecs::EventSignal::Click { .. })
    ) {
        return;
    }

    // env.scope is the hit renderable; walk up to find the cube root in the map.
    let map = CLICK_CUBES.get_or_init(|| Mutex::new(Default::default()));
    let mut guard = map.lock().unwrap();
    let mut cur = Some(env.scope);
    let mut found_root = None;
    while let Some(id) = cur {
        if guard.contains_key(&id) {
            found_root = Some(id);
            break;
        }
        cur = world.parent_of(id);
    }
    let Some(root) = found_root else { return };
    let Some(state) = guard.get_mut(&root) else {
        return;
    };

    state.click_count += 1;
    let colors = click_cube_colors();
    let rgba = colors[state.click_count as usize % colors.len()];

    emit.push_intent_now(
        root,
        engine::ecs::IntentValue::SetColor {
            component_ids: vec![state.color_node],
            rgba,
        },
    );
}

fn spawn_click_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    pos: [f32; 3],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, RaycastableComponent, RenderableComponent, TransformComponent,
    };

    let root = universe.world.add_component(
        TransformComponent::new()
            .with_position(pos[0], pos[1], pos[2])
            .with_scale(0.40, 0.40, 0.40),
    );
    let color_node = universe
        .world
        .add_component(ColorComponent::rgba(0.25, 0.55, 1.0, 1.0));
    let r = universe.world.add_component(RenderableComponent::cube());
    let rc = universe
        .world
        .add_component(RaycastableComponent::enabled());

    // Build the subtree before connecting to the live parent so that
    // RaycastableComponent is already a child of RenderableComponent when
    // RegisterRenderable is processed (renderable_is_raycastable checks children).
    let _ = universe.attach(root, color_node);
    let _ = universe.attach(color_node, r);
    let _ = universe.attach(r, rc);
    let _ = universe.attach(parent, root);

    CLICK_CUBES
        .get_or_init(|| Mutex::new(Default::default()))
        .lock()
        .unwrap()
        .insert(
            root,
            ClickCubeState {
                color_node,
                click_count: 0,
            },
        );

    universe.add_signal_handler(engine::ecs::SignalKind::Click, root, on_click_cube);

    root
}

// ---------------------------------------------------------------------------
// Drag cube — follows pointer while held
// ---------------------------------------------------------------------------

fn on_drag_move(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    env: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::DragMove { delta_world, .. }) = env.event.as_ref() else {
        return;
    };
    let delta = *delta_world;

    // Walk up from the hit renderable to find the TransformComponent to move.
    let mut cur = Some(env.scope);
    while let Some(id) = cur {
        if world
            .get_component_by_id_as::<engine::ecs::component::TransformComponent>(id)
            .is_some()
        {
            let [x, y, z] = world
                .get_component_by_id_as::<engine::ecs::component::TransformComponent>(id)
                .map(|t| t.transform.translation)
                .unwrap_or([0.0; 3]);

            emit.push_intent_now(
                id,
                engine::ecs::IntentValue::SetPosition {
                    component_ids: vec![id],
                    position: [x + delta[0], y + delta[1], z + delta[2]],
                },
            );
            return;
        }
        cur = world.parent_of(id);
    }
}

fn spawn_drag_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    pos: [f32; 3],
    color: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, RaycastableComponent, RenderableComponent, TransformComponent,
    };

    let root = universe.world.add_component(
        TransformComponent::new()
            .with_position(pos[0], pos[1], pos[2])
            .with_scale(0.45, 0.45, 0.45),
    );
    let color_node = universe
        .world
        .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
    let r = universe.world.add_component(RenderableComponent::cube());
    let rc = universe
        .world
        .add_component(RaycastableComponent::enabled());

    let _ = universe.attach(root, color_node);
    let _ = universe.attach(color_node, r);
    let _ = universe.attach(r, rc);
    let _ = universe.attach(parent, root);

    universe.add_signal_handler(engine::ecs::SignalKind::DragMove, r, on_drag_move);

    root
}

// ---------------------------------------------------------------------------
// "Both" cube — drag to move, click to cycle color
// ---------------------------------------------------------------------------

#[derive(Debug)]
struct BothCubeState {
    color_node: engine::ecs::ComponentId,
    click_count: u32,
}

static BOTH_CUBES: OnceLock<
    Mutex<std::collections::HashMap<engine::ecs::ComponentId, BothCubeState>>,
> = OnceLock::new();

fn on_both_cube(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    env: &engine::ecs::Signal,
) {
    match env.event.as_ref() {
        Some(engine::ecs::EventSignal::DragMove { delta_world, .. }) => {
            on_drag_move(world, emit, env);
            let _ = delta_world;
        }
        Some(engine::ecs::EventSignal::Click { .. }) => {
            let map = BOTH_CUBES.get_or_init(|| Mutex::new(Default::default()));
            let mut guard = map.lock().unwrap();
            // scope is the renderable; walk up to find the cube root registered in the map
            let mut cur = Some(env.scope);
            let mut found_root = None;
            while let Some(id) = cur {
                if guard.contains_key(&id) {
                    found_root = Some(id);
                    break;
                }
                cur = world.parent_of(id);
            }
            let Some(root) = found_root else { return };
            let Some(state) = guard.get_mut(&root) else {
                return;
            };

            state.click_count += 1;
            let colors = click_cube_colors();
            let rgba = colors[state.click_count as usize % colors.len()];
            emit.push_intent_now(
                root,
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![state.color_node],
                    rgba,
                },
            );
        }
        _ => {}
    }
}

Additional examples can be found in:

• examples/bisket-vr-debug.rs
• examples/button-press.rs

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

Iterator over all component IDs in the world.

Examples found in repository

examples/scrolling.rs (line 5)

fn find_named(world: &engine::ecs::World, label: &str) -> engine::ecs::ComponentId {
    world
        .all_components()
        .find(|&cid| world.component_label(cid) == Some(label))
        .unwrap_or_else(|| panic!("missing component {label:?}"))
}

examples/triage/panel-pierce.rs (line 11)

fn find_named(world: &engine::ecs::World, label: &str) -> engine::ecs::ComponentId {
    world
        .all_components()
        .find(|&cid| world.component_label(cid) == Some(label))
        .unwrap_or_else(|| panic!("missing component {label:?}"))
}

examples/qdebug.rs (line 18)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();
    let world = engine::ecs::World::default();
    let mut universe = engine::Universe::new(world);
    let src = include_str!("qdebug.mms");
    let out = scripting::MeowMeowRunner::eval_with_world(
        src,
        &mut universe.world,
        &mut universe.systems.rx,
        &mut universe.command_queue,
    );
    for e in &out.errors {
        eprintln!("[mms-err] {e}");
    }
    println!("intents: {}", out.intents.len());
    for c in universe.world.all_components() {
        if let Some(label) = universe.world.component_label(c) {
            {
                println!(
                    "  comp {:?} type={:?} name={:?}",
                    c,
                    universe.world.component_name(c),
                    label
                );
            }
        }
    }
}

examples/router.rs (line 81)

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

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

    let output = scripting::MeowMeowRunner::eval_with_world_at_path(
        include_str!("router.mms"),
        Some("examples/router.mms"),
        &mut universe.world,
        &mut universe.systems.rx,
        &mut universe.command_queue,
    );

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

    universe.enable_repl();

    let demo_root = universe
        .world
        .all_components()
        .find(|&cid| universe.world.component_label(cid) == Some("router_demo"))
        .expect("router demo root");
    let container = universe
        .find_component(demo_root, "[name='container']")
        .expect("container target");
    let authored_child = universe
        .find_component(demo_root, "[name='authored_child']")
        .expect("authored child");

    assert_eq!(universe.parent_of(authored_child), Some(container));

    spawn_runtime_text(&mut universe, demo_root, "late child routed on attach");

    let late_child = universe
        .find_component(demo_root, "[name='late child routed on attach']")
        .expect("late child");
    assert_eq!(universe.parent_of(late_child), Some(container));

    println!("[router-demo] init-time and attach-time routing verified");

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

examples/bisket-vr-debug.rs (line 195)

fn main() {
    mittens_engine::example_support::ensure_model_assets();
    utils::logger::init();
    let opts = parse_args();

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

    let source = include_str!("bisket-vr-debug.mms");
    let output = scripting::MeowMeowRunner::eval_with_world_at_path(
        source,
        Some("examples/bisket-vr-debug.mms"),
        &mut universe.world,
        &mut universe.systems.rx,
        &mut universe.command_queue,
    );
    for e in &output.errors {
        eprintln!("[mms] {e}");
    }
    println!("[mms] {} intent(s)", output.intents.len());
    for intent in output.intents {
        universe
            .command_queue
            .push_intent_now(ComponentId::default(), intent);
    }
    drain(&mut universe);
    tick_gltf(&mut universe);
    drain(&mut universe);

    let avc_id = universe
        .world
        .all_components()
        .find(|&id| {
            universe
                .world
                .get_component_by_id_as::<AvatarControlComponent>(id)
                .is_some()
        })
        .expect("AvatarControlComponent not found — scene didn't load?");
    let driven_t = universe
        .world
        .parent_of(avc_id)
        .expect("AVC has no parent (driven_t)");

    println!("[debug] avc_id={:?} driven_t={:?}", avc_id, driven_t);
    println!(
        "[debug] options: compare_copy_end_rotation={} compare_hand_offsets={} neutralize_hand_offsets={}",
        opts.compare_copy_end_rotation, opts.compare_hand_offsets, opts.neutralize_hand_offsets
    );

    let head_target_offset_world = head_target_offset_in_target_local(&universe.world, avc_id);
    println!(
        "[debug] head_target_offset (target-local) = {:?}",
        head_target_offset_world
    );

    settle_world(&mut universe, 10);

    let (ref_bones, avc_bones) = resolve_spine_bones(&universe.world, avc_id);
    println!(
        "[debug] resolved {} spine bones in both subtrees",
        SPINE_BONES.len()
    );

    let avc_head_bone = avc_bones[SPINE_BONES
        .iter()
        .position(|n| *n == "J_Bip_C_Head")
        .unwrap()];
    let splice_head = universe
        .world
        .parent_of(avc_head_bone)
        .expect("head_bone has no parent — splice didn't run?");

    run_spine_probes(
        &mut universe,
        driven_t,
        splice_head,
        &ref_bones,
        &avc_bones,
        head_target_offset_world,
    );

    let arms = resolve_arm_chains(&universe.world, avc_id);
    print_arm_startup_report(&universe.world, &arms);
    run_arm_probes(&mut universe, driven_t, &arms, opts);

    println!("\n[debug] done. Exiting (no window loop).");
}

fn parse_args() -> HarnessOptions {
    let mut opts = HarnessOptions {
        compare_copy_end_rotation: false,
        compare_hand_offsets: false,
        neutralize_hand_offsets: false,
    };
    for arg in env::args().skip(1) {
        match arg.as_str() {
            "--compare-copy-end-rotation" => opts.compare_copy_end_rotation = true,
            "--compare-hand-offsets" => opts.compare_hand_offsets = true,
            "--neutralize-hand-offsets" => opts.neutralize_hand_offsets = true,
            other => {
                eprintln!("[debug] ignoring unknown arg: {other}");
            }
        }
    }
    opts
}

fn run_spine_probes(
    universe: &mut engine::Universe,
    driven_t: ComponentId,
    splice_head: ComponentId,
    ref_bones: &[ComponentId],
    avc_bones: &[ComponentId],
    head_target_offset_world: [f32; 3],
) {
    let poses = [
        Pose {
            name: "rest",
            description: "driven_t at HMD height (1.55m), identity rotation",
            t: [0.0, 1.55, 0.0],
            rot: ident_quat(),
        },
        Pose {
            name: "pitch_up_30",
            description: "head pitched up 30° around X",
            t: [0.0, 1.55, 0.0],
            rot: quat_from_axis_angle([1.0, 0.0, 0.0], 0.5236),
        },
        Pose {
            name: "pitch_dn_30",
            description: "head pitched down 30° around X",
            t: [0.0, 1.55, 0.0],
            rot: quat_from_axis_angle([1.0, 0.0, 0.0], -0.5236),
        },
        Pose {
            name: "yaw_right_45",
            description: "head yawed right 45° around Y",
            t: [0.0, 1.55, 0.0],
            rot: quat_from_axis_angle([0.0, 1.0, 0.0], 0.7854),
        },
        Pose {
            name: "lean_forward",
            description: "driven_t translated +0.2m on Z (head leans forward over toes)",
            t: [0.0, 1.45, 0.20],
            rot: ident_quat(),
        },
        Pose {
            name: "crouch",
            description: "driven_t lowered to 1.10m (player crouches)",
            t: [0.0, 1.10, 0.0],
            rot: ident_quat(),
        },
        Pose {
            name: "walk_forward_0.5m",
            description: "driven_t walks +0.5m on -Z (OpenXR forward = -Z)",
            t: [0.0, 1.55, -0.5],
            rot: ident_quat(),
        },
        Pose {
            name: "walk_strafe_right_0.3m",
            description: "driven_t side-step +0.3m on X",
            t: [0.3, 1.55, 0.0],
            rot: ident_quat(),
        },
    ];

    let ref_y_z: Vec<[f32; 2]> = ref_bones
        .iter()
        .map(|&id| world_yz(&universe.world, id))
        .collect();

    for pose in &poses {
        set_local_transform(
            &mut universe.command_queue,
            driven_t,
            pose.t,
            pose.rot,
            [1.0, 1.0, 1.0],
        );
        settle_world(universe, SETTLE_TICKS_PER_POSE);

        let avc_y_z: Vec<[f32; 2]> = avc_bones
            .iter()
            .map(|&id| world_yz(&universe.world, id))
            .collect();
        let avc_pos: Vec<[f32; 3]> = avc_bones
            .iter()
            .map(|&id| world_pos(&universe.world, id))
            .collect();
        let splice_pos = world_pos(&universe.world, splice_head);
        let driven_pos = world_pos(&universe.world, driven_t);
        let driven_rot = world_rot(&universe.world, driven_t);

        println!("\n================================================================");
        println!("spine pose: {}", pose.name);
        println!("  {}", pose.description);
        println!(
            "  driven_t world pos: [{:+.3}, {:+.3}, {:+.3}] (model offset +1.2 on X)",
            driven_pos[0], driven_pos[1], driven_pos[2]
        );

        println!("\nspine bones — model-local Y/Z (REF vs AVC)");
        println!(
            "  {:<22}  {:>7}  {:>7}    {:>7}  {:>7}     {:>+7}  {:>+7}",
            "bone", "ref_y", "ref_z", "avc_y", "avc_z", "Δy", "Δz",
        );
        for (i, name) in SPINE_BONES.iter().enumerate() {
            let r = ref_y_z[i];
            let a = avc_y_z[i];
            println!(
                "  {:<22}  {:>+7.3}  {:>+7.3}    {:>+7.3}  {:>+7.3}     {:>+7.3}  {:>+7.3}",
                name,
                r[0],
                r[1],
                a[0],
                a[1],
                a[0] - r[0],
                a[1] - r[1],
            );
        }

        println!("\ninvariants");

        let ref_seg_lens = segment_lengths(ref_bones, &universe.world);
        let avc_seg_lens = segment_lengths(avc_bones, &universe.world);
        let mut bone_length_ok = true;
        for i in 0..ref_seg_lens.len() {
            let drift = (avc_seg_lens[i] - ref_seg_lens[i]).abs();
            let tag = if drift <= BONE_LENGTH_TOL {
                "ok"
            } else {
                "FAIL"
            };
            if drift > BONE_LENGTH_TOL {
                bone_length_ok = false;
            }
            println!(
                "  bone_length  {:<14}→{:<14}  ref={:.4}  avc={:.4}  drift={:+.4}  {}",
                SPINE_BONES[i],
                SPINE_BONES[i + 1],
                ref_seg_lens[i],
                avc_seg_lens[i],
                avc_seg_lens[i] - ref_seg_lens[i],
                tag,
            );
        }
        if bone_length_ok {
            println!(
                "  → all spine bone-lengths preserved within {:.0}mm",
                BONE_LENGTH_TOL * 1000.0
            );
        }

        let mut mono_ok = true;
        let mut prev_y = f32::NEG_INFINITY;
        for (i, name) in SPINE_BONES.iter().enumerate() {
            if *name == "J_Bip_C_Head" {
                break;
            }
            let y = avc_pos[i][1];
            if y + MONOTONIC_Y_TOL < prev_y {
                println!(
                    "  monotonic_y  FAIL at {}: y={:+.3} drops below prev {:+.3}",
                    name, y, prev_y
                );
                mono_ok = false;
            }
            prev_y = y;
        }
        if mono_ok {
            println!(
                "  monotonic_y  ok (hips → neck all non-decreasing within {:.0}mm)",
                MONOTONIC_Y_TOL * 1000.0
            );
        }

        let hips_idx = SPINE_BONES
            .iter()
            .position(|n| *n == "J_Bip_C_Hips")
            .unwrap();
        let hips_xz = [avc_pos[hips_idx][0], avc_pos[hips_idx][2]];
        let dx = hips_xz[0] - splice_pos[0];
        let dz = hips_xz[1] - splice_pos[2];
        let xz_drift = (dx * dx + dz * dz).sqrt();
        const HIPS_UNDER_HEAD_TOL: f32 = 0.050;
        println!(
            "  hips_under_head  splice_xz=[{:+.3},{:+.3}]  hips_xz=[{:+.3},{:+.3}]  drift={:.4}m  {}",
            splice_pos[0],
            splice_pos[2],
            hips_xz[0],
            hips_xz[1],
            xz_drift,
            if xz_drift <= HIPS_UNDER_HEAD_TOL {
                "ok"
            } else {
                "FAIL"
            },
        );

        let predicted_splice_world = {
            let off_world = quat_rotate_vec3(driven_rot, head_target_offset_world);
            [
                driven_pos[0] + off_world[0],
                driven_pos[1] + off_world[1],
                driven_pos[2] + off_world[2],
            ]
        };
        let splice_drift = vec3_dist(splice_pos, predicted_splice_world);
        println!(
            "  splice_head  expected=[{:+.3},{:+.3},{:+.3}]  actual=[{:+.3},{:+.3},{:+.3}]  drift={:.4}m  {}",
            predicted_splice_world[0],
            predicted_splice_world[1],
            predicted_splice_world[2],
            splice_pos[0],
            splice_pos[1],
            splice_pos[2],
            splice_drift,
            if splice_drift <= SPLICE_TARGET_TOL {
                "ok"
            } else {
                "FAIL"
            },
        );
    }
}

fn resolve_spine_bones(
    world: &World,
    _avc_id: ComponentId,
) -> (Vec<ComponentId>, Vec<ComponentId>) {
    let mut ref_bones = Vec::with_capacity(SPINE_BONES.len());
    let mut avc_bones = Vec::with_capacity(SPINE_BONES.len());
    for name in SPINE_BONES {
        let all = find_components_by_name(world, name);
        let (avc_side, ref_side): (Vec<_>, Vec<_>) = all
            .into_iter()
            .partition(|&id| world_pos(world, id)[0] > 0.0);
        let avc = avc_side
            .first()
            .copied()
            .unwrap_or_else(|| panic!("bone {} not found on +X AVC side", name));
        let reference = ref_side
            .first()
            .copied()
            .unwrap_or_else(|| panic!("bone {} not found on -X reference side", name));
        ref_bones.push(reference);
        avc_bones.push(avc);
    }
    (ref_bones, avc_bones)
}

fn resolve_arm_chains(world: &World, avc_id: ComponentId) -> Vec<ArmChainRuntime> {
    let avc = world
        .get_component_by_id_as::<AvatarControlComponent>(avc_id)
        .expect("avc missing");
    let hand_map = [
        (
            ArmSide::Left,
            avc.left_hand_bone
                .as_deref()
                .expect("left_hand_bone config missing"),
        ),
        (
            ArmSide::Right,
            avc.right_hand_bone
                .as_deref()
                .expect("right_hand_bone config missing"),
        ),
    ];

    hand_map
        .into_iter()
        .map(|(side, hand_name)| {
            let hand_id = find_components_by_name(world, hand_name)
                .into_iter()
                .find(|&id| is_descendant_of(world, id, avc_id))
                .unwrap_or_else(|| panic!("{} bone not found under AVC subtree", hand_name));
            let (ik_chain_id, solver, target_id) = world
                .all_components()
                .find_map(|id| {
                    let ik = world.get_component_by_id_as::<IKChainComponent>(id)?;
                    if !is_descendant_of(world, id, avc_id) {
                        return None;
                    }
                    if ik.end_effector_id != hand_id {
                        return None;
                    }
                    Some((id, ik.solver, ik.target_id))
                })
                .unwrap_or_else(|| panic!("{} arm IK chain not found", side.as_str()));
            let (upper_arm, lower_arm, copy_end_rotation) = match solver {
                IKSolver::TwoBoneIK {
                    root_joint_id,
                    mid_joint_id,
                    copy_end_rotation,
                    ..
                } => (root_joint_id, mid_joint_id, copy_end_rotation),
                _ => panic!("{} arm chain resolved to non-TwoBoneIK", side.as_str()),
            };
            let authored_target_local_rotation = local_rot(world, target_id);
            let rest_hand_world_pos = world_pos(world, hand_id);

            ArmChainRuntime {
                side,
                ik_chain_id,
                upper_arm,
                lower_arm,
                hand: hand_id,
                target: target_id,
                authored_target_local_rotation,
                rest_hand_world_pos,
                original_copy_end_rotation: copy_end_rotation,
            }
        })
        .collect()
}

fn print_arm_startup_report(world: &World, arms: &[ArmChainRuntime]) {
    println!("\n================================================================");
    println!("arm chain startup");
    for arm in arms {
        let upward = upward_chain_labels(world, arm.hand, Some(arm.upper_arm), 8);
        let skipped = skipped_chain_labels(world, arm.hand, arm.lower_arm, arm.upper_arm);
        println!(
            "  [{}] ik_chain={} target={} upper={} lower={} hand={}",
            arm.side.as_str(),
            describe_component(world, arm.ik_chain_id),
            describe_component(world, arm.target),
            describe_component(world, arm.upper_arm),
            describe_component(world, arm.lower_arm),
            describe_component(world, arm.hand),
        );
        println!("    hand→upper chain: {}", upward.join(" <- "));
        if skipped.is_empty() {
            println!("    skipped between hand and upper: none (direct upper->lower->hand)");
        } else {
            println!(
                "    skipped between hand and upper: {}",
                skipped.join(" <- ")
            );
        }
        println!(
            "    target parent chain: {}",
            upward_chain_labels(world, arm.target, None, 4).join(" <- ")
        );
    }
}

fn run_arm_probes(
    universe: &mut engine::Universe,
    driven_t: ComponentId,
    arms: &[ArmChainRuntime],
    opts: HarnessOptions,
) {
    let hand_offset_modes: Vec<HandOffsetMode> = if opts.compare_hand_offsets {
        vec![HandOffsetMode::Authored, HandOffsetMode::Neutralized]
    } else if opts.neutralize_hand_offsets {
        vec![HandOffsetMode::Neutralized]
    } else {
        vec![HandOffsetMode::Authored]
    };
    let copy_modes: Vec<CopyEndRotationMode> = if opts.compare_copy_end_rotation {
        vec![
            CopyEndRotationMode::SolverDefault,
            CopyEndRotationMode::ForcedOff,
        ]
    } else {
        vec![CopyEndRotationMode::SolverDefault]
    };

    let poses = [
        ArmProbePose {
            name: "neutral_rest",
            description: "both hand targets at rest hand position and pass baseline rotation",
            left_twist_rad: 0.0,
            right_twist_rad: 0.0,
        },
        ArmProbePose {
            name: "left_palm_down",
            description: "left hand target pronated around the current forearm axis",
            left_twist_rad: -WRIST_TWIST_RAD,
            right_twist_rad: 0.0,
        },
        ArmProbePose {
            name: "left_palm_up",
            description: "left hand target supinated around the current forearm axis",
            left_twist_rad: WRIST_TWIST_RAD,
            right_twist_rad: 0.0,
        },
        ArmProbePose {
            name: "right_palm_down",
            description: "right hand target pronated around the current forearm axis",
            left_twist_rad: 0.0,
            right_twist_rad: WRIST_TWIST_RAD,
        },
        ArmProbePose {
            name: "right_palm_up",
            description: "right hand target supinated around the current forearm axis",
            left_twist_rad: 0.0,
            right_twist_rad: -WRIST_TWIST_RAD,
        },
    ];

    set_local_transform(
        &mut universe.command_queue,
        driven_t,
        [0.0, 1.55, 0.0],
        ident_quat(),
        [1.0, 1.0, 1.0],
    );
    settle_world(universe, SETTLE_TICKS_PER_POSE);

    for hand_mode in hand_offset_modes {
        for copy_mode in &copy_modes {
            println!("\n================================================================");
            println!("arm pass: {} | {}", hand_mode.as_str(), copy_mode.as_str());

            apply_pass_settings(&mut universe.world, arms, hand_mode, *copy_mode);
            for arm in arms {
                reset_arm_target_to_pass_baseline(universe, *arm, hand_mode);
            }
            settle_world(universe, SETTLE_TICKS_PER_POSE);

            let baselines: Vec<(ArmSide, ArmPassBaseline)> = arms
                .iter()
                .map(|arm| {
                    (
                        arm.side,
                        ArmPassBaseline {
                            hand_world_pos: arm.rest_hand_world_pos,
                            target_world_rot: world_rot(&universe.world, arm.target),
                            forearm_axis_world: forearm_axis_world(
                                &universe.world,
                                arm.lower_arm,
                                arm.hand,
                            ),
                        },
                    )
                })
                .collect();

            for pose in &poses {
                for arm in arms {
                    let baseline = baselines
                        .iter()
                        .find(|(side, _)| *side == arm.side)
                        .map(|(_, b)| *b)
                        .unwrap();
                    let twist_rad = match arm.side {
                        ArmSide::Left => pose.left_twist_rad,
                        ArmSide::Right => pose.right_twist_rad,
                    };
                    set_arm_target_world_pose(
                        universe,
                        *arm,
                        baseline.hand_world_pos,
                        quat_mul(
                            quat_from_axis_angle(baseline.forearm_axis_world, twist_rad),
                            baseline.target_world_rot,
                        ),
                    );
                }
                settle_world(universe, SETTLE_TICKS_PER_POSE);

                let left = arms
                    .iter()
                    .find(|arm| matches!(arm.side, ArmSide::Left))
                    .copied()
                    .map(|arm| sample_arm_pose(&universe.world, arm))
                    .expect("left arm sample missing");
                let right = arms
                    .iter()
                    .find(|arm| matches!(arm.side, ArmSide::Right))
                    .copied()
                    .map(|arm| sample_arm_pose(&universe.world, arm))
                    .expect("right arm sample missing");

                println!("\npose: {}", pose.name);
                println!("  {}", pose.description);
                print_arm_pose_sample(&universe.world, ArmSide::Left, &left);
                print_arm_pose_sample(&universe.world, ArmSide::Right, &right);

                if pose.name == "left_palm_down" || pose.name == "right_palm_down" {
                    continue;
                }
            }

            let left_down = sample_signature_for_pose(
                universe,
                arms,
                &baselines,
                "left_palm_down",
                -WRIST_TWIST_RAD,
                0.0,
            );
            let right_down = sample_signature_for_pose(
                universe,
                arms,
                &baselines,
                "right_palm_down",
                0.0,
                WRIST_TWIST_RAD,
            );
            let left_up = sample_signature_for_pose(
                universe,
                arms,
                &baselines,
                "left_palm_up",
                WRIST_TWIST_RAD,
                0.0,
            );
            let right_up = sample_signature_for_pose(
                universe,
                arms,
                &baselines,
                "right_palm_up",
                0.0,
                -WRIST_TWIST_RAD,
            );

            println!("\nmirror summary");
            print_mirror_compare("palm_down", left_down, right_down);
            print_mirror_compare("palm_up", left_up, right_up);
        }
    }
}

fn sample_signature_for_pose(
    universe: &mut engine::Universe,
    arms: &[ArmChainRuntime],
    baselines: &[(ArmSide, ArmPassBaseline)],
    _pose_name: &str,
    left_twist_rad: f32,
    right_twist_rad: f32,
) -> MirrorSignature {
    for arm in arms {
        let baseline = baselines
            .iter()
            .find(|(side, _)| *side == arm.side)
            .map(|(_, b)| *b)
            .unwrap();
        let twist = match arm.side {
            ArmSide::Left => left_twist_rad,
            ArmSide::Right => right_twist_rad,
        };
        set_arm_target_world_pose(
            universe,
            *arm,
            baseline.hand_world_pos,
            quat_mul(
                quat_from_axis_angle(baseline.forearm_axis_world, twist),
                baseline.target_world_rot,
            ),
        );
    }
    settle_world(universe, SETTLE_TICKS_PER_POSE);

    let active_arm = if left_twist_rad.abs() > right_twist_rad.abs() {
        arms.iter()
            .find(|arm| matches!(arm.side, ArmSide::Left))
            .copied()
            .unwrap()
    } else {
        arms.iter()
            .find(|arm| matches!(arm.side, ArmSide::Right))
            .copied()
            .unwrap()
    };
    let sample = sample_arm_pose(&universe.world, active_arm);
    MirrorSignature {
        lower_to_hand_deg: sample.lower_to_hand_deg,
        lower_to_target_deg: sample.lower_to_target_deg,
        hand_to_target_deg: sample.hand_to_target_deg,
    }
}

fn apply_pass_settings(
    world: &mut World,
    arms: &[ArmChainRuntime],
    hand_mode: HandOffsetMode,
    copy_mode: CopyEndRotationMode,
) {
    for arm in arms {
        if let Some(tc) = world.get_component_by_id_as_mut::<TransformComponent>(arm.target) {
            tc.transform.rotation = match hand_mode {
                HandOffsetMode::Authored => arm.authored_target_local_rotation,
                HandOffsetMode::Neutralized => ident_quat(),
            };
            tc.transform.recompute_model();
        }
        if let Some(ik) = world.get_component_by_id_as_mut::<IKChainComponent>(arm.ik_chain_id) {
            if let IKSolver::TwoBoneIK {
                root_joint_id,
                mid_joint_id,
                pole_direction,
                copy_end_rotation: enabled,
            } = &mut ik.solver
            {
                let _ = (root_joint_id, mid_joint_id, pole_direction);
                *enabled = match copy_mode {
                    CopyEndRotationMode::SolverDefault => arm.original_copy_end_rotation,
                    CopyEndRotationMode::ForcedOff => false,
                };
            }
        }
    }
}

fn reset_arm_target_to_pass_baseline(
    universe: &mut engine::Universe,
    arm: ArmChainRuntime,
    hand_mode: HandOffsetMode,
) {
    let world_rot = match hand_mode {
        HandOffsetMode::Authored => world_rot(&universe.world, arm.target),
        HandOffsetMode::Neutralized => world_rot(&universe.world, arm.target),
    };
    set_arm_target_world_pose(universe, arm, arm.rest_hand_world_pos, world_rot);
}

fn set_arm_target_world_pose(
    universe: &mut engine::Universe,
    arm: ArmChainRuntime,
    desired_world_pos: [f32; 3],
    desired_world_rot: [f32; 4],
) {
    let (local_translation, local_rotation, local_scale) = world_pose_to_local(
        &universe.world,
        arm.target,
        desired_world_pos,
        desired_world_rot,
    );
    set_local_transform(
        &mut universe.command_queue,
        arm.target,
        local_translation,
        local_rotation,
        local_scale,
    );
}

fn sample_arm_pose(world: &World, arm: ArmChainRuntime) -> ArmPoseSample {
    let upper_arm = sample_node_rotation(world, arm.upper_arm);
    let lower_arm = sample_node_rotation(world, arm.lower_arm);
    let hand = sample_node_rotation(world, arm.hand);
    let target = sample_node_rotation(world, arm.target);
    ArmPoseSample {
        upper_arm,
        lower_arm,
        hand,
        target,
        lower_to_hand_deg: quat_delta_deg(lower_arm.world, hand.world),
        lower_to_target_deg: quat_delta_deg(lower_arm.world, target.world),
        hand_to_target_deg: quat_delta_deg(hand.world, target.world),
    }
}

fn sample_node_rotation(world: &World, id: ComponentId) -> NodeRotationSample {
    NodeRotationSample {
        world: world_rot(world, id),
        local: local_rot(world, id),
    }
}

fn print_arm_pose_sample(world: &World, side: ArmSide, sample: &ArmPoseSample) {
    println!("  [{}]", side.as_str());
    print_node_rot("upper_arm", sample.upper_arm);
    print_node_rot("lower_arm", sample.lower_arm);
    print_node_rot("hand", sample.hand);
    print_node_rot("target", sample.target);
    println!(
        "    deltas: lower→hand={:>6.2}°  lower→target={:>6.2}°  hand→target={:>6.2}°",
        sample.lower_to_hand_deg, sample.lower_to_target_deg, sample.hand_to_target_deg
    );
    let _ = world;
}

fn print_node_rot(label: &str, sample: NodeRotationSample) {
    println!(
        "    {:<9} world={}  local={}",
        label,
        fmt_quat(sample.world),
        fmt_quat(sample.local)
    );
}

fn print_mirror_compare(name: &str, left: MirrorSignature, right: MirrorSignature) {
    println!(
        "  {:<10} lower→hand L/R={:>6.2}°/{:>6.2}°  lower→target L/R={:>6.2}°/{:>6.2}°  hand→target L/R={:>6.2}°/{:>6.2}°",
        name,
        left.lower_to_hand_deg,
        right.lower_to_hand_deg,
        left.lower_to_target_deg,
        right.lower_to_target_deg,
        left.hand_to_target_deg,
        right.hand_to_target_deg,
    );
}

fn upward_chain_labels(
    world: &World,
    start: ComponentId,
    stop_at: Option<ComponentId>,
    max_hops: usize,
) -> Vec<String> {
    let mut out = vec![describe_component(world, start)];
    let mut cur = start;
    for _ in 0..max_hops {
        let Some(parent) = world.parent_of(cur) else {
            break;
        };
        out.push(describe_component(world, parent));
        if Some(parent) == stop_at {
            break;
        }
        cur = parent;
    }
    out
}

fn skipped_chain_labels(
    world: &World,
    hand: ComponentId,
    lower: ComponentId,
    upper: ComponentId,
) -> Vec<String> {
    let mut skipped = Vec::new();
    let mut cur = hand;
    let mut seen_lower = false;
    for _ in 0..8 {
        let Some(parent) = world.parent_of(cur) else {
            break;
        };
        if parent == lower {
            seen_lower = true;
        } else if parent == upper {
            break;
        } else if seen_lower {
            skipped.push(describe_component(world, parent));
        }
        cur = parent;
    }
    skipped
}

fn describe_component(world: &World, id: ComponentId) -> String {
    let label = world
        .component_label(id)
        .or_else(|| world.component_name(id));
    format!("{}({id:?})", label.unwrap_or("?"))
}

fn set_local_transform(
    emit: &mut dyn SignalEmitter,
    id: ComponentId,
    translation: [f32; 3],
    rotation_quat_xyzw: [f32; 4],
    scale: [f32; 3],
) {
    emit.push_intent_now(
        id,
        IntentValue::UpdateTransform {
            component_ids: vec![id],
            translation,
            rotation_quat_xyzw,
            scale,
        },
    );
}

fn world_pose_to_local(
    world: &World,
    id: ComponentId,
    desired_world_pos: [f32; 3],
    desired_world_rot: [f32; 4],
) -> ([f32; 3], [f32; 4], [f32; 3]) {
    let scale = world
        .get_component_by_id_as::<TransformComponent>(id)
        .map(|t| t.transform.scale)
        .unwrap_or([1.0, 1.0, 1.0]);

    let parent_world_mat = parent_world_matrix(world, id).unwrap_or(mat4_identity());
    let parent_world_rot = parent_world_rotation(world, id).unwrap_or(ident_quat());
    let inv_parent = mat4_inverse(parent_world_mat).unwrap_or(mat4_identity());
    let local_pos4 = mat4_mul_vec4(
        inv_parent,
        [
            desired_world_pos[0],
            desired_world_pos[1],
            desired_world_pos[2],
            1.0,
        ],
    );
    let local_rot = quat_mul(quat_conjugate(parent_world_rot), desired_world_rot);
    (
        [local_pos4[0], local_pos4[1], local_pos4[2]],
        local_rot,
        scale,
    )
}

fn parent_world_matrix(world: &World, id: ComponentId) -> Option<[[f32; 4]; 4]> {
    let parent = world.parent_of(id)?;
    world
        .get_component_by_id_as::<TransformComponent>(parent)
        .map(|t| t.transform.matrix_world)
}

fn parent_world_rotation(world: &World, id: ComponentId) -> Option<[f32; 4]> {
    let parent = world.parent_of(id)?;
    world
        .get_component_by_id_as::<TransformComponent>(parent)
        .map(|t| mat_to_quat(t.transform.matrix_world))
}

fn forearm_axis_world(world: &World, lower_arm: ComponentId, hand: ComponentId) -> [f32; 3] {
    let axis = vec3_sub(world_pos(world, hand), world_pos(world, lower_arm));
    if vec3_len(axis) > 1e-6 {
        vec3_normalize(axis)
    } else {
        [0.0, 0.0, 1.0]
    }
}

fn quat_delta_deg(from: [f32; 4], to: [f32; 4]) -> f32 {
    let (_, angle) = quat_to_axis_angle(quat_mul(quat_conjugate(from), to));
    angle.abs().to_degrees()
}

fn fmt_quat(q: [f32; 4]) -> String {
    format!("[{:+.3},{:+.3},{:+.3},{:+.3}]", q[0], q[1], q[2], q[3])
}

fn ident_quat() -> [f32; 4] {
    [0.0, 0.0, 0.0, 1.0]
}

fn drain(universe: &mut engine::Universe) {
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );
}

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

fn settle_world(universe: &mut engine::Universe, ticks: usize) {
    let input = InputState::default();
    for _ in 0..ticks {
        universe.systems.tick(
            &mut universe.world,
            &mut universe.visuals,
            &mut universe.render_assets,
            &input,
            &mut universe.command_queue,
            1.0 / 60.0,
        );
        drain(universe);
    }
}

fn find_components_by_name(world: &World, name: &str) -> Vec<ComponentId> {
    world
        .all_components()
        .filter(|&id| world.component_label(id).map_or(false, |n| n == name))
        .collect()
}

examples/diy-panel.rs (line 213)

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

    let output = scripting::MeowMeowRunner::eval(include_str!("diy-panel.mms"));

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

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

    universe.enable_repl();

    let demo_root = universe
        .world
        .all_components()
        .find(|&cid| universe.world.component_label(cid) == Some("diy_panel_demo"))
        .expect("diy panel demo root");
    let container = universe
        .find_component(demo_root, "[name='container']")
        .expect("container target");
    let authored_child = universe
        .find_component(demo_root, "[name='authored_child']")
        .expect("authored child");

    assert_eq!(universe.parent_of(authored_child), Some(container));

    spawn_runtime_text(&mut universe, demo_root, "late child routed on attach");

    let late_child = universe
        .find_component(demo_root, "[name='late child routed on attach']")
        .expect("late child");
    assert_eq!(universe.parent_of(late_child), Some(container));

    let input = engine::user_input::InputState::default();
    universe.systems.tick(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &input,
        &mut universe.command_queue,
        0.0,
    );
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

    let scroll = universe
        .world
        .children_of(container)
        .iter()
        .copied()
        .find(|&child| {
            universe.world.component_label(child) == Some("__scroll")
                && universe
                    .world
                    .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(child)
                    .is_some()
        })
        .expect("layout-owned scroll wrapper");
    let track = universe
        .world
        .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(scroll)
        .and_then(|sc| sc.track)
        .expect("layout-owned scroll track");

    assert_eq!(universe.parent_of(authored_child), Some(track));
    assert_eq!(universe.parent_of(late_child), Some(track));

    println!(
        "[diy-panel] init-time routing verified, then layout-owned scrolling moved content into __scroll_track"
    );

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

Additional examples can be found in:

• examples/bisket-vr-demo.rs

pub fn component_count(&self) -> usize

pub fn children_of(&self, c: ComponentId) -> &[ComponentId]

Examples found in repository

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

fn find_renderable_by_mesh_key(
    world: &engine::ecs::World,
    root: engine::ecs::ComponentId,
    mesh_key: &str,
) -> Option<engine::ecs::ComponentId> {
    let mut stack = vec![root];
    while let Some(node) = stack.pop() {
        if let Some(m) = world.get_component_by_id_as::<MeshComponent>(node) {
            if m.key == mesh_key {
                return find_parent_renderable(world, node);
            }
        }
        for &ch in world.children_of(node) {
            stack.push(ch);
        }
    }
    None
}

fn find_parent_renderable(
    world: &engine::ecs::World,
    mut cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    while let Some(parent) = world.parent_of(cid) {
        if world
            .get_component_by_id_as::<RenderableComponent>(parent)
            .is_some()
        {
            return Some(parent);
        }
        cid = parent;
    }
    None
}

fn find_skin_id_for_renderable(
    world: &engine::ecs::World,
    renderable: engine::ecs::ComponentId,
) -> Option<engine::graphics::SkinId> {
    let mut stack = vec![renderable];
    while let Some(node) = stack.pop() {
        if let Some(sm) = world.get_component_by_id_as::<SkinnedMeshComponent>(node) {
            if let Some(id) = sm.skin_id {
                return Some(id);
            }
        }
        for &ch in world.children_of(node) {
            stack.push(ch);
        }
    }
    None
}

fn collect_joint_transforms(
    world: &engine::ecs::World,
    skinned_mesh: &engine::ecs::system::SkinnedMeshSystem,
    visuals: &engine::graphics::VisualWorld,
    gltf_component: engine::ecs::ComponentId,
    root: engine::ecs::ComponentId,
) -> Vec<(usize, engine::ecs::ComponentId)> {
    fn find_first_skin_id_in_subtree(
        world: &engine::ecs::World,
        root: engine::ecs::ComponentId,
    ) -> Option<engine::graphics::SkinId> {
        let mut stack = vec![root];
        while let Some(node) = stack.pop() {
            if let Some(sm) = world.get_component_by_id_as::<SkinnedMeshComponent>(node) {
                if let Some(id) = sm.skin_id {
                    return Some(id);
                }
            }
            for &ch in world.children_of(node) {
                stack.push(ch);
            }
        }
        None
    }

examples/scrolling.rs (line 22)

fn first_renderable_in_subtree(
    world: &engine::ecs::World,
    root: engine::ecs::ComponentId,
) -> engine::ecs::ComponentId {
    let mut stack = vec![root];
    while let Some(node) = stack.pop() {
        if world
            .get_component_by_id_as::<engine::ecs::component::RenderableComponent>(node)
            .is_some()
        {
            return node;
        }
        for &child in world.children_of(node).iter().rev() {
            stack.push(child);
        }
    }

    panic!("missing renderable under subtree {:?}", root);
}

examples/diy-panel.rs (line 57)

fn collect_container_items(
    world: &engine::ecs::World,
    container: engine::ecs::ComponentId,
) -> Vec<engine::ecs::ComponentId> {
    use engine::ecs::component::TransformComponent;

    world
        .children_of(container)
        .iter()
        .copied()
        .filter(|&child| {
            world
                .get_component_by_id_as::<TransformComponent>(child)
                .is_some()
                && !world
                    .component_label(child)
                    .map(|label| label.starts_with("__"))
                    .unwrap_or(false)
        })
        .collect()
}

fn decompose_world_trs(matrix_world: [[f32; 4]; 4]) -> ([f32; 3], [f32; 4], [f32; 3]) {
    let translation = [matrix_world[3][0], matrix_world[3][1], matrix_world[3][2]];
    let scale = [
        (matrix_world[0][0] * matrix_world[0][0]
            + matrix_world[0][1] * matrix_world[0][1]
            + matrix_world[0][2] * matrix_world[0][2])
            .sqrt(),
        (matrix_world[1][0] * matrix_world[1][0]
            + matrix_world[1][1] * matrix_world[1][1]
            + matrix_world[1][2] * matrix_world[1][2])
            .sqrt(),
        (matrix_world[2][0] * matrix_world[2][0]
            + matrix_world[2][1] * matrix_world[2][1]
            + matrix_world[2][2] * matrix_world[2][2])
            .sqrt(),
    ];
    let rotation = mittens_engine::utils::math::mat_to_quat(matrix_world);
    (translation, rotation, scale)
}

fn spawn_container_item_debug_clones(
    universe: &mut engine::Universe,
    container: engine::ecs::ComponentId,
) {
    use engine::ecs::IntentValue;
    use engine::ecs::system::TransformSystem;
    use mittens_engine::scripting::component_registry::{
        ce_ast_to_materialized, spawn_tree, subtree_to_ce_ast,
    };

    let items = collect_container_items(&universe.world, container);
    for (index, item) in items.into_iter().enumerate() {
        let Some(matrix_world) = TransformSystem::world_model(&universe.world, item) else {
            println!("[diy-panel-debug] skip {:?}: no world matrix", item);
            continue;
        };

        let item_label = universe
            .world
            .component_label(item)
            .unwrap_or("")
            .to_string();
        println!(
            "[diy-panel-debug] item={} label={:?} matrix_world={:?}",
            index, item_label, matrix_world,
        );

        // Subtree → MMS AST → MaterializedCE → fresh spawn.
        // Same path attach_clone uses; gives the clone fresh GUIDs and
        // routes everything through the standard component registry.
        let Ok(ce_ast) = subtree_to_ce_ast(&universe.world, item) else {
            println!(
                "[diy-panel-debug] skip {:?}: failed to encode subtree",
                item
            );
            continue;
        };
        let Ok(materialized) = ce_ast_to_materialized(&ce_ast) else {
            println!(
                "[diy-panel-debug] skip {:?}: failed to materialize CE",
                item
            );
            continue;
        };
        let Ok(clone_root) = spawn_tree(
            &materialized,
            None,
            &mut universe.world,
            &mut universe.command_queue,
        ) else {
            println!("[diy-panel-debug] skip {:?}: failed to spawn clone", item);
            continue;
        };

        universe.add(clone_root);

        let (mut clone_translation, clone_rotation, clone_scale) =
            decompose_world_trs(matrix_world);
        clone_translation[0] += DEBUG_CLONE_WORLD_OFFSET[0];
        clone_translation[1] += DEBUG_CLONE_WORLD_OFFSET[1];
        clone_translation[2] += DEBUG_CLONE_WORLD_OFFSET[2];

        universe.command_queue.push_intent_now(
            clone_root,
            IntentValue::UpdateTransform {
                component_ids: vec![clone_root],
                translation: clone_translation,
                rotation_quat_xyzw: clone_rotation,
                scale: clone_scale,
            },
        );

        let label = if item_label.is_empty() {
            format!("item_{index}")
        } else {
            format!("{}_{}", item_label, index)
        };
        println!(
            "[diy-panel-debug] cloned item={} label={:?} clone_root={:?} offset_translation={:?}",
            index, label, clone_root, clone_translation,
        );
    }
}

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

    let output = scripting::MeowMeowRunner::eval(include_str!("diy-panel.mms"));

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

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

    universe.enable_repl();

    let demo_root = universe
        .world
        .all_components()
        .find(|&cid| universe.world.component_label(cid) == Some("diy_panel_demo"))
        .expect("diy panel demo root");
    let container = universe
        .find_component(demo_root, "[name='container']")
        .expect("container target");
    let authored_child = universe
        .find_component(demo_root, "[name='authored_child']")
        .expect("authored child");

    assert_eq!(universe.parent_of(authored_child), Some(container));

    spawn_runtime_text(&mut universe, demo_root, "late child routed on attach");

    let late_child = universe
        .find_component(demo_root, "[name='late child routed on attach']")
        .expect("late child");
    assert_eq!(universe.parent_of(late_child), Some(container));

    let input = engine::user_input::InputState::default();
    universe.systems.tick(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &input,
        &mut universe.command_queue,
        0.0,
    );
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

    let scroll = universe
        .world
        .children_of(container)
        .iter()
        .copied()
        .find(|&child| {
            universe.world.component_label(child) == Some("__scroll")
                && universe
                    .world
                    .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(child)
                    .is_some()
        })
        .expect("layout-owned scroll wrapper");
    let track = universe
        .world
        .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(scroll)
        .and_then(|sc| sc.track)
        .expect("layout-owned scroll track");

    assert_eq!(universe.parent_of(authored_child), Some(track));
    assert_eq!(universe.parent_of(late_child), Some(track));

    println!(
        "[diy-panel] init-time routing verified, then layout-owned scrolling moved content into __scroll_track"
    );

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

examples/gravity-fields.rs (line 11)

fn cube_renderable_sibling_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    let t = world.parent_of(collider_cid)?;
    for &sib in world.children_of(t).iter() {
        if sib == collider_cid {
            continue;
        }
        let Some(r) =
            world.get_component_by_id_as::<engine::ecs::component::RenderableComponent>(sib)
        else {
            continue;
        };
        if r.renderable.base_mesh == engine::graphics::primitives::CpuMeshHandle::CUBE {
            return Some(sib);
        }
    }
    None
}

fn set_renderable_color_rgba(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
    rgba: [f32; 4],
) {
    // Prefer existing ColorComponent.
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::ColorComponent>(ch)
                .is_some()
        });

    if let Some(color_cid) = existing {
        if let Some(c) =
            world.get_component_by_id_as_mut::<engine::ecs::component::ColorComponent>(color_cid)
        {
            c.rgba = rgba;
            emit.push_intent_now(
                color_cid,
                engine::ecs::IntentValue::RegisterColor {
                    component_ids: vec![color_cid],
                },
            );
        }
        return;
    }

    // Fallback: add a ColorComponent child if missing.
    let color_cid = world.register(engine::ecs::component::ColorComponent::rgba(
        rgba[0], rgba[1], rgba[2], rgba[3],
    ));
    let _ = world.add_child(renderable_cid, color_cid);
    emit.push_intent_now(
        color_cid,
        engine::ecs::IntentValue::RegisterColor {
            component_ids: vec![color_cid],
        },
    );
}

fn kinetic_response_child_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    for &ch in world.children_of(collider_cid).iter() {
        if world
            .get_component_by_id_as::<engine::ecs::component::KineticResponseComponent>(ch)
            .is_some()
        {
            return Some(ch);
        }
    }
    None
}

examples/raycast-topology-animation.rs (line 36)

fn ensure_emissive_on(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
) {
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::EmissiveComponent>(ch)
                .is_some()
        });

    if existing.is_some() {
        return;
    }

    let emissive_cid = world.register(engine::ecs::component::EmissiveComponent::on());
    let _ = world.add_child(renderable_cid, emissive_cid);
    emit.push_intent_now(
        emissive_cid,
        engine::ecs::IntentValue::RegisterEmissive {
            component_ids: vec![emissive_cid],
        },
    );
}

examples/bisket-vr-debug.rs (line 1204)

fn head_target_offset_in_target_local(world: &World, avc_id: ComponentId) -> [f32; 3] {
    let avc = world
        .get_component_by_id_as::<AvatarControlComponent>(avc_id)
        .expect("avc missing");
    let mut eye_offset = [0.0, 0.0, 0.0];
    for &ch in world.children_of(avc_id) {
        let is_t = world
            .get_component_by_id_as::<TransformComponent>(ch)
            .is_some();
        if !is_t {
            continue;
        }
        let wraps_cam = world.children_of(ch).iter().any(|&gc| {
            world
                .get_component_by_id_as::<mittens_engine::engine::ecs::component::Camera3DComponent>(gc)
                .is_some()
                || world
                    .get_component_by_id_as::<mittens_engine::engine::ecs::component::CameraXRComponent>(gc)
                    .is_some()
        });
        if wraps_cam {
            eye_offset = world
                .get_component_by_id_as::<TransformComponent>(ch)
                .unwrap()
                .transform
                .translation;
            break;
        }
    }
    let offset_yaw = if avc.forward_plus_z {
        0.0
    } else {
        std::f32::consts::PI
    };
    let neg_eye = [-eye_offset[0], -eye_offset[1], -eye_offset[2]];
    quat_rotate_vec3(quat_rotation_y(offset_yaw), neg_eye)
}

Additional examples can be found in:

• examples/bisket-vr-demo.rs

pub fn get_component_by_id_as<T: 'static>(&self, c: ComponentId) -> Option<&T>

Examples found in repository

examples/bisket-vr-demo.rs (line 53)

fn world_pos(world: &World, id: ComponentId) -> [f32; 3] {
    world
        .get_component_by_id_as::<TransformComponent>(id)
        .map(|t| {
            let m = t.transform.matrix_world;
            [m[3][0], m[3][1], m[3][2]]
        })
        .unwrap_or([0.0; 3])
}

fn world_rot_quat(world: &World, id: ComponentId) -> [f32; 4] {
    world
        .get_component_by_id_as::<TransformComponent>(id)
        .map(|t| mat_to_quat(t.transform.matrix_world))
        .unwrap_or([0.0, 0.0, 0.0, 1.0])
}

fn v3_len(v: [f32; 3]) -> f32 {
    (v[0] * v[0] + v[1] * v[1] + v[2] * v[2]).sqrt()
}

fn deg(rad: f32) -> f32 {
    rad * (180.0 / std::f32::consts::PI)
}

fn component_label(world: &World, id: ComponentId) -> String {
    world.component_name(id).unwrap_or("?").to_string()
}

fn controller_hand_for_component(world: &World, start: ComponentId) -> Option<ControllerHand> {
    let mut cur = start;
    loop {
        if let Some(ctrl) = world.get_component_by_id_as::<ControllerXRComponent>(cur) {
            return Some(ctrl.hand);
        }
        cur = world.parent_of(cur)?;
    }
}

fn on_xr_pointer_event(world: &mut World, _emit: &mut dyn SignalEmitter, env: &Signal) {
    let Some(event) = env.event.as_ref() else {
        return;
    };
    let (kind, raycaster, renderable, hit_point) = match event {
        EventSignal::DragStart {
            raycaster,
            renderable,
            hit_point,
            ..
        } => ("DragStart", *raycaster, *renderable, Some(*hit_point)),
        EventSignal::DragMove {
            raycaster,
            renderable,
            hit_point,
            ..
        } => ("DragMove", *raycaster, *renderable, Some(*hit_point)),
        EventSignal::DragEnd {
            raycaster,
            renderable,
            hit_point,
        } => ("DragEnd", *raycaster, *renderable, *hit_point),
        EventSignal::Click {
            raycaster,
            renderable,
            hit_point,
            ..
        } => ("Click", *raycaster, *renderable, Some(*hit_point)),
        _ => return,
    };

    let Some(hand) = controller_hand_for_component(world, raycaster) else {
        return;
    };
    let hand_label = match hand {
        ControllerHand::Left => "Left",
        ControllerHand::Right => "Right",
    };
    let renderable_name = component_label(world, renderable);
    let ray_name = component_label(world, raycaster);
    if let Some(p) = hit_point {
        println!(
            "[xr-pointer] hand={} kind={} raycaster={} renderable={} hit=[{:+.3},{:+.3},{:+.3}]",
            hand_label, kind, ray_name, renderable_name, p[0], p[1], p[2]
        );
    } else {
        println!(
            "[xr-pointer] hand={} kind={} raycaster={} renderable={}",
            hand_label, kind, ray_name, renderable_name
        );
    }
}

fn on_dump_click(world: &mut World, _emit: &mut dyn SignalEmitter, env: &Signal) {
    if !matches!(env.event.as_ref(), Some(EventSignal::Click { .. })) {
        return;
    }
    let Some(targets) = DUMP_TARGETS.get() else {
        return;
    };

    let driven_p = world_pos(world, targets.driven_t);
    let driven_q = world_rot_quat(world, targets.driven_t);
    let splice_p = world_pos(world, targets.splice_head);
    let head_p = world_pos(world, targets.head_bone);
    let head_q = world_rot_quat(world, targets.head_bone);

    // Expected head pivot from HMD pose + authored eye offset convention.
    let neg_eye = [
        -targets.authored_eye_offset_head_local[0],
        -targets.authored_eye_offset_head_local[1],
        -targets.authored_eye_offset_head_local[2],
    ];
    let head_target_offset_local =
        quat_rotate_vec3(quat_rotation_y(targets.head_ik_offset_yaw), neg_eye);
    let head_target_offset_world = quat_rotate_vec3(driven_q, head_target_offset_local);
    let expected_splice = [
        driven_p[0] + head_target_offset_world[0],
        driven_p[1] + head_target_offset_world[1],
        driven_p[2] + head_target_offset_world[2],
    ];
    let splice_err = [
        splice_p[0] - expected_splice[0],
        splice_p[1] - expected_splice[1],
        splice_p[2] - expected_splice[2],
    ];

    // Camera-wrapper vs head local-offset consistency check.
    let mut cam_rel_report = String::from("camera_wrapper: <none>");
    if let Some(cam_t) = targets.camera_wrapper_t {
        let cam_p = world_pos(world, cam_t);
        let expected_cam_world_off =
            quat_rotate_vec3(head_q, targets.authored_eye_offset_head_local);
        let expected_cam = [
            head_p[0] + expected_cam_world_off[0],
            head_p[1] + expected_cam_world_off[1],
            head_p[2] + expected_cam_world_off[2],
        ];
        let cam_err = [
            cam_p[0] - expected_cam[0],
            cam_p[1] - expected_cam[1],
            cam_p[2] - expected_cam[2],
        ];
        cam_rel_report = format!(
            "camera_wrapper  pos=[{:+.3},{:+.3},{:+.3}]  expected_from_head=[{:+.3},{:+.3},{:+.3}]  err=[{:+.3},{:+.3},{:+.3}] |err|={:.4}m",
            cam_p[0],
            cam_p[1],
            cam_p[2],
            expected_cam[0],
            expected_cam[1],
            expected_cam[2],
            cam_err[0],
            cam_err[1],
            cam_err[2],
            v3_len(cam_err)
        );
    }

    // Torso tilt diagnostic (forward pitch of upper chest).
    let mut torso_report = String::from("upper_chest_tilt: <not found>");
    if let Some(upper_chest) = targets.upper_chest {
        let chest_q = world_rot_quat(world, upper_chest);
        let fwd = quat_rotate_vec3(chest_q, [0.0, 0.0, 1.0]);
        let pitch_deg = deg(fwd[1].atan2((fwd[0] * fwd[0] + fwd[2] * fwd[2]).sqrt()));
        torso_report = format!(
            "upper_chest_fwd=[{:+.3},{:+.3},{:+.3}] pitch={:+.2}deg",
            fwd[0], fwd[1], fwd[2], pitch_deg
        );
    }

    println!("\n================ BONE DUMP (click) ================");
    println!(
        "driven_t  pos=[{:+.3},{:+.3},{:+.3}]  rot_xyzw=[{:+.3},{:+.3},{:+.3},{:+.3}]",
        driven_p[0], driven_p[1], driven_p[2], driven_q[0], driven_q[1], driven_q[2], driven_q[3],
    );
    println!(
        "splice_head  pos=[{:+.3},{:+.3},{:+.3}]  expected=[{:+.3},{:+.3},{:+.3}]  err=[{:+.3},{:+.3},{:+.3}] |err|={:.4}m",
        splice_p[0],
        splice_p[1],
        splice_p[2],
        expected_splice[0],
        expected_splice[1],
        expected_splice[2],
        splice_err[0],
        splice_err[1],
        splice_err[2],
        v3_len(splice_err),
    );
    println!("{}", cam_rel_report);
    println!("{}", torso_report);
    println!(
        "\n  {:<22}  {:>7}  {:>7}  {:>7}     {:>+7}  {:>+7}  {:>+7}",
        "bone", "x", "y", "z", "Δx_to_drv", "Δy_to_drv", "Δz_to_drv"
    );
    let mut prev_pos: Option<[f32; 3]> = None;
    for (i, (label, bone_id)) in targets.bones.iter().enumerate() {
        let p = world_pos(world, *bone_id);
        println!(
            "  {:<22}  {:>+7.3}  {:>+7.3}  {:>+7.3}     {:>+7.3}  {:>+7.3}  {:>+7.3}",
            label,
            p[0],
            p[1],
            p[2],
            p[0] - driven_p[0],
            p[1] - driven_p[1],
            p[2] - driven_p[2],
        );
        // Segment length to previous bone (only meaningful within a chain —
        // spine bones are contiguous; arm bones are split per side, so we
        // insert a blank gap when the chain breaks).
        if let Some(prev) = prev_pos {
            let is_spine = label.starts_with("J_Bip_C_");
            let prev_was_spine = targets.bones[i - 1].0.starts_with("J_Bip_C_");
            let is_left_arm_step =
                label.starts_with("J_Bip_L_") && targets.bones[i - 1].0.starts_with("J_Bip_L_");
            let is_right_arm_step =
                label.starts_with("J_Bip_R_") && targets.bones[i - 1].0.starts_with("J_Bip_R_");
            if (is_spine && prev_was_spine) || is_left_arm_step || is_right_arm_step {
                let d = [(p[0] - prev[0]), (p[1] - prev[1]), (p[2] - prev[2])];
                let len = (d[0] * d[0] + d[1] * d[1] + d[2] * d[2]).sqrt();
                println!("    └─ segment from prev: len={:.4}m", len);
            }
        }
        prev_pos = Some(p);
    }
    println!("====================================================\n");
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

examples/vtuber-editor-example.rs (line 17)

fn controller_hand_for_component(world: &World, start: ComponentId) -> Option<ControllerHand> {
    let mut cur = start;
    loop {
        if let Some(ctrl) = world.get_component_by_id_as::<ControllerXRComponent>(cur) {
            return Some(ctrl.hand);
        }
        cur = world.parent_of(cur)?;
    }
}

examples/vtuber-mirror-example.rs (line 17)

fn controller_hand_for_component(world: &World, start: ComponentId) -> Option<ControllerHand> {
    let mut cur = start;
    loop {
        if let Some(ctrl) = world.get_component_by_id_as::<ControllerXRComponent>(cur) {
            return Some(ctrl.hand);
        }
        cur = world.parent_of(cur)?;
    }
}

examples/scrolling.rs (line 17)

fn first_renderable_in_subtree(
    world: &engine::ecs::World,
    root: engine::ecs::ComponentId,
) -> engine::ecs::ComponentId {
    let mut stack = vec![root];
    while let Some(node) = stack.pop() {
        if world
            .get_component_by_id_as::<engine::ecs::component::RenderableComponent>(node)
            .is_some()
        {
            return node;
        }
        for &child in world.children_of(node).iter().rev() {
            stack.push(child);
        }
    }

    panic!("missing renderable under subtree {:?}", root);
}

fn spawn_scroll_item(
    universe: &mut engine::Universe,
    scrolling: engine::ecs::ComponentId,
    prefix: &str,
    index: usize,
    panel_rgba: [f32; 4],
    text_rgba: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, RenderableComponent, TextComponent, TransformComponent,
    };

    let label = format!("{prefix}_item_{index:02}");
    let root = universe.world.add_component_boxed_named(
        label.clone(),
        Box::new(TransformComponent::new().with_position(0.0, -(index as f32) * 1.15, 0.05)),
    );
    let panel = universe.world.add_component_boxed_named(
        format!("{label}_panel"),
        Box::new(
            TransformComponent::new()
                .with_position(2.3, -0.45, 0.0)
                .with_scale(4.6, 0.9, 1.0),
        ),
    );
    let panel_renderable = universe.world.add_component_boxed_named(
        format!("{label}_renderable"),
        Box::new(RenderableComponent::square()),
    );
    let panel_color = universe.world.add_component(ColorComponent::rgba(
        panel_rgba[0],
        panel_rgba[1],
        panel_rgba[2],
        panel_rgba[3],
    ));

    let text_anchor = universe.world.add_component_boxed_named(
        format!("{label}_text_anchor"),
        Box::new(
            TransformComponent::new()
                .with_position(0.35, -0.38, 0.02)
                .with_scale(0.11, 0.11, 0.11),
        ),
    );
    let text = universe.world.add_component_boxed_named(
        format!("{label}_text"),
        Box::new(TextComponent::new(label.clone())),
    );
    let text_color = universe.world.add_component(ColorComponent::rgba(
        text_rgba[0],
        text_rgba[1],
        text_rgba[2],
        text_rgba[3],
    ));

    let _ = universe.world.add_child(root, panel);
    let _ = universe.world.add_child(panel, panel_renderable);
    let _ = universe.world.add_child(panel_renderable, panel_color);
    let _ = universe.world.add_child(root, text_anchor);
    let _ = universe.world.add_child(text_anchor, text);
    let _ = universe.world.add_child(text, text_color);

    universe
        .attach(scrolling, root)
        .expect("attach scroll item");
    root
}

fn populate_scrolling(
    universe: &mut engine::Universe,
    scrolling: engine::ecs::ComponentId,
    prefix: &str,
    panel_rgba: [f32; 4],
    text_rgba: [f32; 4],
    count: usize,
) {
    for index in 0..count {
        let root = spawn_scroll_item(universe, scrolling, prefix, index, panel_rgba, text_rgba);
        let track = universe
            .world
            .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(scrolling)
            .and_then(|sc| sc.track)
            .expect("owned scroll track");
        assert_eq!(universe.parent_of(root), Some(track));
    }
}

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

    let output = scripting::MeowMeowRunner::eval(include_str!("scrolling.mms"));

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

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

    let manual_scroll = find_named(&universe.world, "manual_scroll");
    let layout_scroll = find_named(&universe.world, "layout_scroll");
    let layout_bg = find_named(&universe.world, "__bg");

    let layout_bg_renderable = first_renderable_in_subtree(&universe.world, layout_bg);

    let manual_drag_scope = universe
        .world
        .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(manual_scroll)
        .and_then(|sc| sc.drag_scope)
        .expect("manual drag scope");
    let layout_drag_scope = universe
        .world
        .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(layout_scroll)
        .and_then(|sc| sc.drag_scope)
        .expect("layout drag scope");

    assert_ne!(manual_drag_scope, layout_bg_renderable);
    assert_eq!(layout_drag_scope, layout_bg_renderable);

    populate_scrolling(
        &mut universe,
        manual_scroll,
        "manual",
        [0.78, 0.87, 0.98, 1.0],
        [0.08, 0.16, 0.28, 1.0],
        18,
    );
    populate_scrolling(
        &mut universe,
        layout_scroll,
        "layout",
        [0.98, 0.87, 0.74, 1.0],
        [0.30, 0.14, 0.05, 1.0],
        18,
    );

    println!(
        "[scrolling-demo] manual drag_scope={:?} layout drag_scope={:?} late attach routing verified",
        manual_drag_scope, layout_drag_scope
    );

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

examples/diy-panel.rs (line 62)

fn collect_container_items(
    world: &engine::ecs::World,
    container: engine::ecs::ComponentId,
) -> Vec<engine::ecs::ComponentId> {
    use engine::ecs::component::TransformComponent;

    world
        .children_of(container)
        .iter()
        .copied()
        .filter(|&child| {
            world
                .get_component_by_id_as::<TransformComponent>(child)
                .is_some()
                && !world
                    .component_label(child)
                    .map(|label| label.starts_with("__"))
                    .unwrap_or(false)
        })
        .collect()
}

fn decompose_world_trs(matrix_world: [[f32; 4]; 4]) -> ([f32; 3], [f32; 4], [f32; 3]) {
    let translation = [matrix_world[3][0], matrix_world[3][1], matrix_world[3][2]];
    let scale = [
        (matrix_world[0][0] * matrix_world[0][0]
            + matrix_world[0][1] * matrix_world[0][1]
            + matrix_world[0][2] * matrix_world[0][2])
            .sqrt(),
        (matrix_world[1][0] * matrix_world[1][0]
            + matrix_world[1][1] * matrix_world[1][1]
            + matrix_world[1][2] * matrix_world[1][2])
            .sqrt(),
        (matrix_world[2][0] * matrix_world[2][0]
            + matrix_world[2][1] * matrix_world[2][1]
            + matrix_world[2][2] * matrix_world[2][2])
            .sqrt(),
    ];
    let rotation = mittens_engine::utils::math::mat_to_quat(matrix_world);
    (translation, rotation, scale)
}

fn spawn_container_item_debug_clones(
    universe: &mut engine::Universe,
    container: engine::ecs::ComponentId,
) {
    use engine::ecs::IntentValue;
    use engine::ecs::system::TransformSystem;
    use mittens_engine::scripting::component_registry::{
        ce_ast_to_materialized, spawn_tree, subtree_to_ce_ast,
    };

    let items = collect_container_items(&universe.world, container);
    for (index, item) in items.into_iter().enumerate() {
        let Some(matrix_world) = TransformSystem::world_model(&universe.world, item) else {
            println!("[diy-panel-debug] skip {:?}: no world matrix", item);
            continue;
        };

        let item_label = universe
            .world
            .component_label(item)
            .unwrap_or("")
            .to_string();
        println!(
            "[diy-panel-debug] item={} label={:?} matrix_world={:?}",
            index, item_label, matrix_world,
        );

        // Subtree → MMS AST → MaterializedCE → fresh spawn.
        // Same path attach_clone uses; gives the clone fresh GUIDs and
        // routes everything through the standard component registry.
        let Ok(ce_ast) = subtree_to_ce_ast(&universe.world, item) else {
            println!(
                "[diy-panel-debug] skip {:?}: failed to encode subtree",
                item
            );
            continue;
        };
        let Ok(materialized) = ce_ast_to_materialized(&ce_ast) else {
            println!(
                "[diy-panel-debug] skip {:?}: failed to materialize CE",
                item
            );
            continue;
        };
        let Ok(clone_root) = spawn_tree(
            &materialized,
            None,
            &mut universe.world,
            &mut universe.command_queue,
        ) else {
            println!("[diy-panel-debug] skip {:?}: failed to spawn clone", item);
            continue;
        };

        universe.add(clone_root);

        let (mut clone_translation, clone_rotation, clone_scale) =
            decompose_world_trs(matrix_world);
        clone_translation[0] += DEBUG_CLONE_WORLD_OFFSET[0];
        clone_translation[1] += DEBUG_CLONE_WORLD_OFFSET[1];
        clone_translation[2] += DEBUG_CLONE_WORLD_OFFSET[2];

        universe.command_queue.push_intent_now(
            clone_root,
            IntentValue::UpdateTransform {
                component_ids: vec![clone_root],
                translation: clone_translation,
                rotation_quat_xyzw: clone_rotation,
                scale: clone_scale,
            },
        );

        let label = if item_label.is_empty() {
            format!("item_{index}")
        } else {
            format!("{}_{}", item_label, index)
        };
        println!(
            "[diy-panel-debug] cloned item={} label={:?} clone_root={:?} offset_translation={:?}",
            index, label, clone_root, clone_translation,
        );
    }
}

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

    let output = scripting::MeowMeowRunner::eval(include_str!("diy-panel.mms"));

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

    if !output.errors.is_empty() {
        std::process::exit(1);
    }

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

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

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

    universe.enable_repl();

    let demo_root = universe
        .world
        .all_components()
        .find(|&cid| universe.world.component_label(cid) == Some("diy_panel_demo"))
        .expect("diy panel demo root");
    let container = universe
        .find_component(demo_root, "[name='container']")
        .expect("container target");
    let authored_child = universe
        .find_component(demo_root, "[name='authored_child']")
        .expect("authored child");

    assert_eq!(universe.parent_of(authored_child), Some(container));

    spawn_runtime_text(&mut universe, demo_root, "late child routed on attach");

    let late_child = universe
        .find_component(demo_root, "[name='late child routed on attach']")
        .expect("late child");
    assert_eq!(universe.parent_of(late_child), Some(container));

    let input = engine::user_input::InputState::default();
    universe.systems.tick(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &input,
        &mut universe.command_queue,
        0.0,
    );
    universe.systems.process_commands(
        &mut universe.world,
        &mut universe.visuals,
        &mut universe.render_assets,
        &mut universe.command_queue,
    );

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

    let scroll = universe
        .world
        .children_of(container)
        .iter()
        .copied()
        .find(|&child| {
            universe.world.component_label(child) == Some("__scroll")
                && universe
                    .world
                    .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(child)
                    .is_some()
        })
        .expect("layout-owned scroll wrapper");
    let track = universe
        .world
        .get_component_by_id_as::<engine::ecs::component::ScrollingComponent>(scroll)
        .and_then(|sc| sc.track)
        .expect("layout-owned scroll track");

    assert_eq!(universe.parent_of(authored_child), Some(track));
    assert_eq!(universe.parent_of(late_child), Some(track));

    println!(
        "[diy-panel] init-time routing verified, then layout-owned scrolling moved content into __scroll_track"
    );

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

examples/gravity-fields.rs (line 16)

fn cube_renderable_sibling_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    let t = world.parent_of(collider_cid)?;
    for &sib in world.children_of(t).iter() {
        if sib == collider_cid {
            continue;
        }
        let Some(r) =
            world.get_component_by_id_as::<engine::ecs::component::RenderableComponent>(sib)
        else {
            continue;
        };
        if r.renderable.base_mesh == engine::graphics::primitives::CpuMeshHandle::CUBE {
            return Some(sib);
        }
    }
    None
}

fn set_renderable_color_rgba(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
    rgba: [f32; 4],
) {
    // Prefer existing ColorComponent.
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::ColorComponent>(ch)
                .is_some()
        });

    if let Some(color_cid) = existing {
        if let Some(c) =
            world.get_component_by_id_as_mut::<engine::ecs::component::ColorComponent>(color_cid)
        {
            c.rgba = rgba;
            emit.push_intent_now(
                color_cid,
                engine::ecs::IntentValue::RegisterColor {
                    component_ids: vec![color_cid],
                },
            );
        }
        return;
    }

    // Fallback: add a ColorComponent child if missing.
    let color_cid = world.register(engine::ecs::component::ColorComponent::rgba(
        rgba[0], rgba[1], rgba[2], rgba[3],
    ));
    let _ = world.add_child(renderable_cid, color_cid);
    emit.push_intent_now(
        color_cid,
        engine::ecs::IntentValue::RegisterColor {
            component_ids: vec![color_cid],
        },
    );
}

fn kinetic_response_child_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    for &ch in world.children_of(collider_cid).iter() {
        if world
            .get_component_by_id_as::<engine::ecs::component::KineticResponseComponent>(ch)
            .is_some()
        {
            return Some(ch);
        }
    }
    None
}

fn on_collision_turn_white(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    signal: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::CollisionStarted { a, b, .. }) = signal.event.as_ref()
    else {
        return;
    };

    let self_collider = signal.scope;
    let other = if self_collider == *a {
        *b
    } else if self_collider == *b {
        *a
    } else {
        return;
    };

    // Only react to cube-vs-cube touches (ignore static walls/floor and non-renderable colliders like camera).
    let Some(other_cn) =
        world.get_component_by_id_as::<engine::ecs::component::CollisionComponent>(other)
    else {
        return;
    };
    if other_cn.mode == engine::ecs::component::CollisionMode::Static {
        return;
    }
    if cube_renderable_sibling_of_collider(world, other).is_none() {
        return;
    }

    let Some(self_renderable) = cube_renderable_sibling_of_collider(world, self_collider) else {
        return;
    };
    set_renderable_color_rgba(world, emit, self_renderable, [1.0, 1.0, 1.0, 1.0]);
}

fn on_collision_freeze_gravity(
    world: &mut engine::ecs::World,
    _emit: &mut dyn engine::ecs::SignalEmitter,
    signal: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::CollisionStarted { a, b, .. }) = signal.event.as_ref()
    else {
        return;
    };

    let self_collider = signal.scope;
    let other = if self_collider == *a {
        *b
    } else if self_collider == *b {
        *a
    } else {
        return;
    };

    // Only react to cube-vs-cube touches.
    let Some(other_cn) =
        world.get_component_by_id_as::<engine::ecs::component::CollisionComponent>(other)
    else {
        return;
    };
    if other_cn.mode == engine::ecs::component::CollisionMode::Static {
        return;
    }
    if cube_renderable_sibling_of_collider(world, other).is_none() {
        return;
    }

    let Some(response_cid) = kinetic_response_child_of_collider(world, self_collider) else {
        return;
    };
    if let Some(r) = world
        .get_component_by_id_as_mut::<engine::ecs::component::KineticResponseComponent>(
            response_cid,
        )
    {
        // Gravity is a cached per-responder coefficient; set it to 0 once touched.
        r.gravity_coefficient = 0.0;
    }
}

Additional examples can be found in:

• examples/raycast-topology-animation.rs
• examples/pointer-events.rs
• examples/triage/panel-pierce.rs
• examples/bisket-vr-debug.rs
• examples/example_util/mod.rs
• examples/vtuber-joints-example.rs

pub fn get_component_by_id_as_mut<T: 'static>( &mut self, c: ComponentId, ) -> Option<&mut T>

Examples found in repository

examples/bisket-vr-debug.rs (line 848)

fn apply_pass_settings(
    world: &mut World,
    arms: &[ArmChainRuntime],
    hand_mode: HandOffsetMode,
    copy_mode: CopyEndRotationMode,
) {
    for arm in arms {
        if let Some(tc) = world.get_component_by_id_as_mut::<TransformComponent>(arm.target) {
            tc.transform.rotation = match hand_mode {
                HandOffsetMode::Authored => arm.authored_target_local_rotation,
                HandOffsetMode::Neutralized => ident_quat(),
            };
            tc.transform.recompute_model();
        }
        if let Some(ik) = world.get_component_by_id_as_mut::<IKChainComponent>(arm.ik_chain_id) {
            if let IKSolver::TwoBoneIK {
                root_joint_id,
                mid_joint_id,
                pole_direction,
                copy_end_rotation: enabled,
            } = &mut ik.solver
            {
                let _ = (root_joint_id, mid_joint_id, pole_direction);
                *enabled = match copy_mode {
                    CopyEndRotationMode::SolverDefault => arm.original_copy_end_rotation,
                    CopyEndRotationMode::ForcedOff => false,
                };
            }
        }
    }
}

examples/gravity-fields.rs (line 46)

fn set_renderable_color_rgba(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
    rgba: [f32; 4],
) {
    // Prefer existing ColorComponent.
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::ColorComponent>(ch)
                .is_some()
        });

    if let Some(color_cid) = existing {
        if let Some(c) =
            world.get_component_by_id_as_mut::<engine::ecs::component::ColorComponent>(color_cid)
        {
            c.rgba = rgba;
            emit.push_intent_now(
                color_cid,
                engine::ecs::IntentValue::RegisterColor {
                    component_ids: vec![color_cid],
                },
            );
        }
        return;
    }

    // Fallback: add a ColorComponent child if missing.
    let color_cid = world.register(engine::ecs::component::ColorComponent::rgba(
        rgba[0], rgba[1], rgba[2], rgba[3],
    ));
    let _ = world.add_child(renderable_cid, color_cid);
    emit.push_intent_now(
        color_cid,
        engine::ecs::IntentValue::RegisterColor {
            component_ids: vec![color_cid],
        },
    );
}

fn kinetic_response_child_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    for &ch in world.children_of(collider_cid).iter() {
        if world
            .get_component_by_id_as::<engine::ecs::component::KineticResponseComponent>(ch)
            .is_some()
        {
            return Some(ch);
        }
    }
    None
}

fn on_collision_turn_white(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    signal: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::CollisionStarted { a, b, .. }) = signal.event.as_ref()
    else {
        return;
    };

    let self_collider = signal.scope;
    let other = if self_collider == *a {
        *b
    } else if self_collider == *b {
        *a
    } else {
        return;
    };

    // Only react to cube-vs-cube touches (ignore static walls/floor and non-renderable colliders like camera).
    let Some(other_cn) =
        world.get_component_by_id_as::<engine::ecs::component::CollisionComponent>(other)
    else {
        return;
    };
    if other_cn.mode == engine::ecs::component::CollisionMode::Static {
        return;
    }
    if cube_renderable_sibling_of_collider(world, other).is_none() {
        return;
    }

    let Some(self_renderable) = cube_renderable_sibling_of_collider(world, self_collider) else {
        return;
    };
    set_renderable_color_rgba(world, emit, self_renderable, [1.0, 1.0, 1.0, 1.0]);
}

fn on_collision_freeze_gravity(
    world: &mut engine::ecs::World,
    _emit: &mut dyn engine::ecs::SignalEmitter,
    signal: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::CollisionStarted { a, b, .. }) = signal.event.as_ref()
    else {
        return;
    };

    let self_collider = signal.scope;
    let other = if self_collider == *a {
        *b
    } else if self_collider == *b {
        *a
    } else {
        return;
    };

    // Only react to cube-vs-cube touches.
    let Some(other_cn) =
        world.get_component_by_id_as::<engine::ecs::component::CollisionComponent>(other)
    else {
        return;
    };
    if other_cn.mode == engine::ecs::component::CollisionMode::Static {
        return;
    }
    if cube_renderable_sibling_of_collider(world, other).is_none() {
        return;
    }

    let Some(response_cid) = kinetic_response_child_of_collider(world, self_collider) else {
        return;
    };
    if let Some(r) = world
        .get_component_by_id_as_mut::<engine::ecs::component::KineticResponseComponent>(
            response_cid,
        )
    {
        // Gravity is a cached per-responder coefficient; set it to 0 once touched.
        r.gravity_coefficient = 0.0;
    }
}

pub fn find_component( &self, root: ComponentId, selector: &str, ) -> Option<ComponentId>

Find the first component under root matching selector.

selector is parsed as MMQ — #name, Type, Type#name, [name='...'], etc. See crates/mittens-query/src/mmq/parser.rs.

pub fn find_all_components( &self, root: ComponentId, selector: &str, ) -> Vec<ComponentId>

Find all components under root matching selector (DFS pre-order).

pub fn component_matches_selector( &self, component: ComponentId, selector: &str, ) -> bool

pub fn world_roots(&self) -> Vec<ComponentId>

pub fn get_parent_as<T: 'static>( &self, c: ComponentId, ) -> Option<(ComponentId, &T)>

pub fn get_parent_as_mut<T: 'static>( &mut self, c: ComponentId, ) -> Option<(ComponentId, &mut T)>

pub fn add_child( &mut self, parent: ComponentId, child: ComponentId, ) -> Result<(), &'static str>

Attach child under parent.

This is a lower-level graph mutation API.

It updates only the parent/child links in the world graph. It does not emit ParentChanged, does not refresh topology-dependent systems, and does not route through runtime helpers like routers/scroll ownership.

Prefer IntentValue::Attach or Universe::attach(...) when attaching a subtree into an already-live parent and you expect normal runtime side effects.

add_child(...) is appropriate for offline subtree assembly before init, tests, and internal structural building where the caller intentionally manages any needed follow-up work.

Safety rules:

• Both ids must exist.
• child is detached from its current parent first.
• Cycles are rejected.

Examples found in repository

examples/raycast-topology-animation.rs (line 50)

fn ensure_emissive_on(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
) {
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::EmissiveComponent>(ch)
                .is_some()
        });

    if existing.is_some() {
        return;
    }

    let emissive_cid = world.register(engine::ecs::component::EmissiveComponent::on());
    let _ = world.add_child(renderable_cid, emissive_cid);
    emit.push_intent_now(
        emissive_cid,
        engine::ecs::IntentValue::RegisterEmissive {
            component_ids: vec![emissive_cid],
        },
    );
}

fn ring_a_handler(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    env: &engine::ecs::Signal,
) {
    match env.event.as_ref() {
        Some(engine::ecs::EventSignal::RayIntersected { renderable, .. }) => {
            println!(
                "[ring_a_handler] fired scope={:?} renderable={:?}",
                env.scope, renderable
            );

            ensure_emissive_on(world, emit, *renderable);

            emit.push_intent_now(
                env.scope,
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![*renderable],
                    rgba: [1.0, 1.0, 0.0, 1.0],
                },
            );
        }
        _ => {}
    }
}

fn ring_b_handler(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    env: &engine::ecs::Signal,
) {
    match env.event.as_ref() {
        Some(engine::ecs::EventSignal::RayIntersected { renderable, .. }) => {
            println!(
                "[ring_b_handler] fired scope={:?} renderable={:?}",
                env.scope, renderable
            );

            ensure_emissive_on(world, emit, *renderable);

            emit.push_intent_now(
                env.scope,
                engine::ecs::IntentValue::SetColor {
                    component_ids: vec![*renderable],
                    rgba: [0.0, 1.0, 1.0, 1.0],
                },
            );
        }
        _ => {}
    }
}

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/router.rs (line 34)

fn spawn_runtime_text(
    universe: &mut engine::Universe,
    owner: engine::ecs::ComponentId,
    label: &str,
) {
    use engine::ecs::component::{
        ColorComponent, EdgeInsets, SizeDimension, StyleComponent, TextComponent,
        TransformComponent,
    };

    let root = universe
        .world
        .add_component_boxed_named(label, Box::new(TransformComponent::new()));
    let style = universe.world.add_component_boxed_named(
        format!("{label}_style"),
        Box::new({
            let mut style = StyleComponent::new();
            style.margin = EdgeInsets::all(0.5);
            style.padding = EdgeInsets::axes(0.75, 0.5);
            style.width = SizeDimension::Auto;
            style.background_color = Some([0.93, 0.88, 0.98, 1.0]);
            style
        }),
    );
    let text = universe
        .world
        .add_component_boxed_named(format!("{label}_text"), Box::new(TextComponent::new(label)));
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.38, 0.14, 0.62, 1.0));

    let _ = universe.world.add_child(root, style);
    let _ = universe.world.add_child(root, text);
    let _ = universe.world.add_child(text, color);

    universe.attach(owner, root).expect("attach routed child");
}

examples/gravity-fields.rs (line 63)

fn set_renderable_color_rgba(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    renderable_cid: engine::ecs::ComponentId,
    rgba: [f32; 4],
) {
    // Prefer existing ColorComponent.
    let existing = world
        .children_of(renderable_cid)
        .iter()
        .copied()
        .find(|&ch| {
            world
                .get_component_by_id_as::<engine::ecs::component::ColorComponent>(ch)
                .is_some()
        });

    if let Some(color_cid) = existing {
        if let Some(c) =
            world.get_component_by_id_as_mut::<engine::ecs::component::ColorComponent>(color_cid)
        {
            c.rgba = rgba;
            emit.push_intent_now(
                color_cid,
                engine::ecs::IntentValue::RegisterColor {
                    component_ids: vec![color_cid],
                },
            );
        }
        return;
    }

    // Fallback: add a ColorComponent child if missing.
    let color_cid = world.register(engine::ecs::component::ColorComponent::rgba(
        rgba[0], rgba[1], rgba[2], rgba[3],
    ));
    let _ = world.add_child(renderable_cid, color_cid);
    emit.push_intent_now(
        color_cid,
        engine::ecs::IntentValue::RegisterColor {
            component_ids: vec![color_cid],
        },
    );
}

fn kinetic_response_child_of_collider(
    world: &engine::ecs::World,
    collider_cid: engine::ecs::ComponentId,
) -> Option<engine::ecs::ComponentId> {
    for &ch in world.children_of(collider_cid).iter() {
        if world
            .get_component_by_id_as::<engine::ecs::component::KineticResponseComponent>(ch)
            .is_some()
        {
            return Some(ch);
        }
    }
    None
}

fn on_collision_turn_white(
    world: &mut engine::ecs::World,
    emit: &mut dyn engine::ecs::SignalEmitter,
    signal: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::CollisionStarted { a, b, .. }) = signal.event.as_ref()
    else {
        return;
    };

    let self_collider = signal.scope;
    let other = if self_collider == *a {
        *b
    } else if self_collider == *b {
        *a
    } else {
        return;
    };

    // Only react to cube-vs-cube touches (ignore static walls/floor and non-renderable colliders like camera).
    let Some(other_cn) =
        world.get_component_by_id_as::<engine::ecs::component::CollisionComponent>(other)
    else {
        return;
    };
    if other_cn.mode == engine::ecs::component::CollisionMode::Static {
        return;
    }
    if cube_renderable_sibling_of_collider(world, other).is_none() {
        return;
    }

    let Some(self_renderable) = cube_renderable_sibling_of_collider(world, self_collider) else {
        return;
    };
    set_renderable_color_rgba(world, emit, self_renderable, [1.0, 1.0, 1.0, 1.0]);
}

fn on_collision_freeze_gravity(
    world: &mut engine::ecs::World,
    _emit: &mut dyn engine::ecs::SignalEmitter,
    signal: &engine::ecs::Signal,
) {
    let Some(engine::ecs::EventSignal::CollisionStarted { a, b, .. }) = signal.event.as_ref()
    else {
        return;
    };

    let self_collider = signal.scope;
    let other = if self_collider == *a {
        *b
    } else if self_collider == *b {
        *a
    } else {
        return;
    };

    // Only react to cube-vs-cube touches.
    let Some(other_cn) =
        world.get_component_by_id_as::<engine::ecs::component::CollisionComponent>(other)
    else {
        return;
    };
    if other_cn.mode == engine::ecs::component::CollisionMode::Static {
        return;
    }
    if cube_renderable_sibling_of_collider(world, other).is_none() {
        return;
    }

    let Some(response_cid) = kinetic_response_child_of_collider(world, self_collider) else {
        return;
    };
    if let Some(r) = world
        .get_component_by_id_as_mut::<engine::ecs::component::KineticResponseComponent>(
            response_cid,
        )
    {
        // Gravity is a cached per-responder coefficient; set it to 0 once touched.
        r.gravity_coefficient = 0.0;
    }
}

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

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

    let 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.06, 0.04, 0.07, 1.0,
        ));
    let _ = universe.world.add_child(bg_color, bg_color_c);
    universe.add(bg_color);

    // overhead directional light
    let directional_light = universe.world.add_component(
        engine::ecs::component::DirectionalLightComponent::new()
            .with_color(0.16, 0.14, 0.12)
            .with_intensity(0.7),
    );
    let directional_light_t = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 1.0, 0.0),
    );
    let _ = universe.attach(directional_light_t, directional_light);
    universe.add(directional_light_t);

    // Simple input-driven camera.
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(2.0));

    let cam_t = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 4.0, 10.0),
    );
    let cam = universe.world.add_component(
        engine::ecs::component::Camera3DComponent::new()
            // The default (150) clips background dressing (city + clouds).
            .with_far(600.0)
            .with_fov(70.0),
    );

    // Make the camera affect the collision system (same pattern as collision-perimeter).
    let cam_collision = universe
        .world
        .add_component(engine::ecs::component::CollisionComponent::RIGGED());
    let cam_response = universe
        .world
        .add_component(engine::ecs::component::KineticResponseComponent::slide());
    let cam_shape =
        universe
            .world
            .add_component(engine::ecs::component::CollisionShapeComponent::new(
                engine::ecs::component::CollisionShape::sphere_radius(0.25),
            ));

    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, cam_t);
    let _ = universe.attach(cam_t, cam);
    let _ = universe.attach(cam_t, cam_collision);
    let _ = universe.attach(cam_collision, cam_response);
    let _ = universe.attach(cam_collision, cam_shape);

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

    let arena_half = 30.0;

    // --- Background world (occluded + lit) ---
    // Buildings are scene dressing and should not occlude foreground cubes.
    let bg_root = universe.world.add_component(
        engine::ecs::component::BackgroundComponent::new().with_occlusion_and_lighting(),
    );
    universe.add(bg_root);

    // Background ground plane (rendered in background pass) with top surface at y=0.
    // This should not occlude foreground due to depth clear between passes.
    let bg_ground_thickness = 0.20;
    let bg_ground_root_t = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    let bg_ground_geom_t = universe.world.add_component(
        engine::ecs::component::TransformComponent::new()
            .with_position(0.0, -bg_ground_thickness, 0.0)
            .with_scale(
                arena_half * 10.0,
                bg_ground_thickness * 2.0,
                arena_half * 10.0,
            ),
    );
    let bg_ground_r = universe
        .world
        .add_component(engine::ecs::component::RenderableComponent::cube());
    let bg_ground_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.03, 0.03, 0.035, 1.0,
        ));
    let _ = universe.attach(bg_root, bg_ground_root_t);
    let _ = universe.attach(bg_ground_root_t, bg_ground_geom_t);
    let _ = universe.attach(bg_ground_geom_t, bg_ground_r);
    let _ = universe.attach(bg_ground_r, bg_ground_c);

    // Background clouds (occluded + lit) using the shared example helper.
    // NOTE: `spawn_cloud_ring` places a ring centered at the parent transform's origin.
    // If we attach directly to `bg_root`, the ring can end up mostly out of view.
    // So we offset a cloud root forward along -Z and keep the radius within the camera far clip.
    let bg_cloud_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(
            0.0,
            0.0,
            -arena_half * 2.8,
        ),
    );
    let _ = universe.attach(bg_root, bg_cloud_root);

    let mut cloud_params = example_util::CloudRingParams::default();
    cloud_params.cloud_count = 9;
    cloud_params.radius = arena_half * 1.9;
    cloud_params.center_y = 18.0;
    cloud_params.puffs_per_cloud = 26;
    cloud_params.angle_jitter = 0.35;
    cloud_params.high_y_probability = 0.35;
    cloud_params.high_y_multiplier = 1.35;
    cloud_params.seed = 0xC10_71A5u32;
    example_util::spawn_cloud_ring(&mut universe, bg_cloud_root, cloud_params);

    // Foreground city: NOT background-layer.
    let fg_city_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    universe.add(fg_city_root);

    // Background city: nested under the BackgroundComponent.
    let bg_city_root = universe
        .world
        .add_component(engine::ecs::component::TransformComponent::new());
    let _ = universe.attach(bg_root, bg_city_root);

    fn hash_u32(mut x: u32) -> u32 {
        // Small, deterministic integer hash (no external RNG dependency).
        x ^= x >> 16;
        x = x.wrapping_mul(0x7FEB_352D);
        x ^= x >> 15;
        x = x.wrapping_mul(0x846C_A68B);
        x ^= x >> 16;
        x
    }

    fn rand01(seed: u32) -> f32 {
        let x = hash_u32(seed);
        (x as f32) / (u32::MAX as f32)
    }

    fn spawn_floor(
        universe: &mut engine::Universe,
        building_root: engine::ecs::ComponentId,
        floor_center_y: f32,
        footprint_x: f32,
        footprint_z: f32,
        floor_h: f32,
        floor_rgb: [f32; 4],
        building_scale: f32,
        window_mask: &[bool],
        window_height_coeff: f32,
        seed: u32,
    ) {
        // Floor geometry.
        // IMPORTANT: don't put non-uniform scale on the node that windows attach to,
        // otherwise child window meshes inherit the scale and look stretched.
        let floor_root_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(
                0.0,
                floor_center_y,
                0.0,
            ),
        );
        let floor_geom_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_scale(
                footprint_x,
                floor_h,
                footprint_z,
            ),
        );
        let floor_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let floor_c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                floor_rgb[0],
                floor_rgb[1],
                floor_rgb[2],
                floor_rgb[3],
            ));

        let _ = universe.attach(building_root, floor_root_t);
        let _ = universe.attach(floor_root_t, floor_geom_t);
        let _ = universe.attach(floor_geom_t, floor_r);
        let _ = universe.attach(floor_r, floor_c);

        // Windows: a single clean row per floor.
        // Each floor receives a Vec<bool> (window_mask) that indicates which window slots are present.
        let slots = window_mask.len().max(1);
        let building_scale = building_scale.max(0.01);
        let window_height_coeff = window_height_coeff.clamp(0.05, 2.0);

        // Keep window size independent from floor height; floor height is already controlled by height_scale.
        let nominal_window = 0.32 * building_scale;
        let window_d = 0.06 * building_scale;

        // Compute per-side spacing and clamp window size to fit.
        let margin_x = (0.65 * nominal_window).min(0.18 * footprint_x);
        let margin_z = (0.65 * nominal_window).min(0.18 * footprint_z);
        let available_x = (footprint_x - 2.0 * margin_x).max(nominal_window);
        let available_z = (footprint_z - 2.0 * margin_z).max(nominal_window);
        let step_x = available_x / (slots as f32);
        let step_z = available_z / (slots as f32);

        let window_wx = nominal_window.min(step_x * 0.85);
        let window_wz = nominal_window.min(step_z * 0.85);
        let window_h = (nominal_window * window_height_coeff).min(floor_h * 0.80);

        let warm = 0.70 + 0.25 * rand01(seed ^ 0x1F12_6A77);
        let window_rgb = [1.0, 0.78 * warm, 0.48 * warm, 1.0];

        let mut spawn_window = |local_pos: (f32, f32, f32), local_scale: (f32, f32, f32)| {
            let window_t = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(local_pos.0, local_pos.1, local_pos.2)
                    .with_scale(local_scale.0, local_scale.1, local_scale.2),
            );
            let window_r = universe
                .world
                .add_component(engine::ecs::component::RenderableComponent::cube());
            let window_c =
                universe
                    .world
                    .add_component(engine::ecs::component::ColorComponent::rgba(
                        window_rgb[0],
                        window_rgb[1],
                        window_rgb[2],
                        window_rgb[3],
                    ));
            let window_e = universe
                .world
                .add_component(engine::ecs::component::EmissiveComponent::on());

            let _ = universe.attach(floor_root_t, window_t);
            let _ = universe.attach(window_t, window_r);
            let _ = universe.attach(window_r, window_c);
            let _ = universe.attach(window_r, window_e);
        };

        // Place the row at the center of the floor segment.
        let wy = 0.0;

        for i in 0..slots {
            if !window_mask[i] {
                continue;
            }
            let tx = -0.5 * footprint_x + margin_x + (i as f32 + 0.5) * step_x;
            let tz = -0.5 * footprint_z + margin_z + (i as f32 + 0.5) * step_z;

            // +Z/-Z faces: windows laid out along X.
            for z_sign in [1.0_f32, -1.0_f32] {
                spawn_window(
                    (tx, wy, z_sign * (footprint_z * 0.5 + window_d * 0.6)),
                    (window_wx, window_h, window_d),
                );
            }

            // +X/-X faces: windows laid out along Z.
            for x_sign in [1.0_f32, -1.0_f32] {
                spawn_window(
                    (x_sign * (footprint_x * 0.5 + window_d * 0.6), wy, tz),
                    (window_d, window_h, window_wz),
                );
            }
        }
    }

    fn spawn_building(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        x: f32,
        y_offset: f32,
        z: f32,
        floors: u32,
        seed: u32,
        building_scale: f32,
        height_scale: f32,
        total_windows_per_floor_per_building_side: u32,
        window_height_coeff: f32,
    ) {
        let building_scale = building_scale.max(0.01);
        let height_scale = height_scale.max(0.01);

        let floors = floors.max(1);
        let windows_per_side = total_windows_per_floor_per_building_side.max(1) as usize;

        let footprint_x = 3.2 * building_scale;
        let footprint_z = 3.2 * building_scale;
        let floor_h = 1.15 * building_scale * height_scale;

        let base_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(x, y_offset, z),
        );
        let _ = universe.attach(parent, base_t);

        // Slight per-building tint.
        let tint = 0.03 * (rand01(seed ^ 0xA511_E9B3) - 0.5);
        let base_rgb = [0.08 + tint, 0.085 + tint, 0.095 + tint, 1.0];

        // Probability that a given window slot exists.
        // (False means no window cube at that slot.)
        let window_fill_probability = 0.80_f32;

        for floor_i in 0..floors {
            let floor_seed = seed ^ floor_i.wrapping_mul(0x9E37_79B9) ^ 0xB17D_1E55;

            let mut window_mask = Vec::with_capacity(windows_per_side);
            for i in 0..windows_per_side {
                let s = floor_seed ^ (i as u32).wrapping_mul(0x85EB_CA6B) ^ 0x243F_6A88;
                window_mask.push(rand01(s) < window_fill_probability);
            }

            let floor_center_y = floor_h * (floor_i as f32) + floor_h * 0.5;
            spawn_floor(
                universe,
                base_t,
                floor_center_y,
                footprint_x,
                footprint_z,
                floor_h,
                base_rgb,
                building_scale,
                &window_mask,
                window_height_coeff,
                floor_seed,
            );
        }
    }

    fn spawn_city(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        columns: u32,
        spacing: f32,
        position_scale: f32,
        building_scale: f32,
        height_scale: f32,
        seed_base: u32,
        y_offset: f32,
        total_windows_per_floor_per_building_side: u32,
        window_height_coeff: f32,
    ) {
        let columns = columns.max(1);
        let half = (columns as i32) / 2;

        for gz in -half..=half {
            for gx in -half..=half {
                // Hole in the middle.
                if gx == 0 && gz == 0 {
                    continue;
                }

                let seed = seed_base
                    ^ ((gx + half) as u32).wrapping_mul(0x9E37_79B9)
                    ^ ((gz + half) as u32).wrapping_mul(0x85EB_CA6B)
                    ^ 0xB17D_1E55;

                let floors = 3 + (hash_u32(seed) % 10); // 3..=12 floors

                // Centered around the origin.
                // - position_scale controls how far out the city sits (positions only)
                // - building_scale controls building footprint/window sizes
                let x = (gx as f32) * spacing * position_scale;
                let z = (gz as f32) * spacing * position_scale;

                spawn_building(
                    universe,
                    parent,
                    x,
                    y_offset,
                    z,
                    floors,
                    seed,
                    building_scale,
                    height_scale,
                    total_windows_per_floor_per_building_side,
                    window_height_coeff,
                );
            }
        }
    }

    // // Foreground city: 5x5 (hole in center), scaled out to sit around the floor.
    // spawn_city(
    //     &mut universe,
    //     fg_city_root,
    //     5,
    //     7.0,
    //     2.0,
    //     1.0,
    //     1.0,
    //     0xC170_0001u32,
    //     3,
    //     2,
    //     -0.0
    // );

    // Background city: larger grid, farther out, taller buildings.
    spawn_city(
        &mut universe,
        bg_city_root,
        11,
        3.0,
        3.0,
        0.45,
        1.0,
        0xC170_0002u32,
        -2.0,
        6,
        0.75,
    );

    fn spawn_street_light(universe: &mut engine::Universe) -> engine::ecs::ComponentId {
        // Dimensions (world units).
        let shaft_height = 6.0;
        let shaft_thickness = 0.22;
        let arm_length = shaft_height / 3.0;
        let arm_thickness = 0.18;

        // Colors.
        let pole_color = [0.35, 0.35, 0.38, 1.0];
        let housing_color = [0.18, 0.18, 0.20, 1.0];
        let diffuser_color = [1.0, 1.0, 1.0, 1.0];

        // Model root at origin.
        // The caller is expected to position + rotate this model using an external placement transform.
        // Street light is authored facing +X (arm extends toward +X).
        let root_t = universe
            .world
            .add_component(engine::ecs::component::TransformComponent::new());

        // Vertical shaft (split root/geom so scaling doesn't affect the arm).
        let shaft_root_t = universe
            .world
            .add_component(engine::ecs::component::TransformComponent::new());
        let shaft_geom_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(0.0, shaft_height * 0.5, 0.0)
                .with_scale(shaft_thickness, shaft_height, shaft_thickness),
        );
        let shaft_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let shaft_c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                pole_color[0],
                pole_color[1],
                pole_color[2],
                pole_color[3],
            ));

        let _ = universe.attach(root_t, shaft_root_t);
        let _ = universe.attach(shaft_root_t, shaft_geom_t);
        let _ = universe.attach(shaft_geom_t, shaft_r);
        let _ = universe.attach(shaft_r, shaft_c);

        // Horizontal arm at the top; starts at the pole and extends toward +X.
        let arm_root_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(0.0, shaft_height, 0.0),
        );
        let arm_geom_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(arm_length * 0.5, -arm_thickness * 0.5, 0.0)
                .with_scale(arm_length, arm_thickness, arm_thickness),
        );
        let arm_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let arm_c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                pole_color[0],
                pole_color[1],
                pole_color[2],
                pole_color[3],
            ));

        let _ = universe.attach(shaft_root_t, arm_root_t);
        let _ = universe.attach(arm_root_t, arm_geom_t);
        let _ = universe.attach(arm_geom_t, arm_r);
        let _ = universe.attach(arm_r, arm_c);

        // Light housing at the end of the arm (+X end).
        let housing_root_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(arm_length, 0.0, 0.0),
        );
        let housing_geom_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(0.5, 0.0, 0.0)
                // 2x1x1 box in (z, x, y) -> (x, y, z) = (1, 1, 2)
                .with_scale(2.0, 1.0, 1.0),
        );
        let housing_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let housing_c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                housing_color[0],
                housing_color[1],
                housing_color[2],
                housing_color[3],
            ));

        let _ = universe.attach(arm_root_t, housing_root_t);
        let _ = universe.attach(housing_root_t, housing_geom_t);
        let _ = universe.attach(housing_geom_t, housing_r);
        let _ = universe.attach(housing_r, housing_c);

        // White diffuser cube (slightly smaller, slightly lower).
        let diffuser_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(0.5, -0.35, 0.0)
                .with_scale(1.85, 0.55, 0.70),
        );
        let diffuser_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let diffuser_c =
            universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    diffuser_color[0],
                    diffuser_color[1],
                    diffuser_color[2],
                    diffuser_color[3],
                ));

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

        let _ = universe.attach(housing_root_t, diffuser_t);
        let _ = universe.attach(diffuser_t, diffuser_r);
        let _ = universe.attach(diffuser_r, diffuser_c);

        // Yellow (slightly red) point light.
        let light = universe.world.add_component(
            engine::ecs::component::PointLightComponent::new()
                .with_color(1.0, 0.82, 0.55)
                .with_intensity(5.0)
                .with_distance(40.0),
        );
        let _ = universe.attach(diffuser_t, light);

        root_t
    }

    // Spawn 6 street lights around the arena.
    // Arms point inward from each side.
    let light_x = arena_half - 2.0;
    for z in [-10.0, 0.0, 10.0] {
        // Left side: street light model faces +X by default, so it points inward.
        let left_place = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(-light_x, 0.0, z),
        );
        let left_model = spawn_street_light(&mut universe);
        let _ = universe.attach(left_place, left_model);
        universe.add(left_place);

        // Right side: rotate 180° around Y so the arm points toward -X (inward).
        let right_place = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(light_x, 0.0, z)
                .with_rotation_euler(0.0, std::f32::consts::PI, 0.0),
        );
        let right_model = spawn_street_light(&mut universe);
        let _ = universe.attach(right_place, right_model);
        universe.add(right_place);
    }

    // Big floor.
    {
        let floor_half = arena_half;
        let thickness = 0.20;

        // Split transforms so scaling the floor does not scale any potential children.
        // Top surface at y=0.
        let floor_root_t = universe
            .world
            .add_component(engine::ecs::component::TransformComponent::new());
        let floor_geom_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(0.0, -thickness, 0.0)
                .with_scale(floor_half * 2.0, thickness * 2.0, floor_half * 2.0),
        );
        let floor_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let floor_color =
            universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    0.08, 0.08, 0.09, 1.0,
                ));

        let floor_cn = universe
            .world
            .add_component(engine::ecs::component::CollisionComponent::STATIC());
        let floor_shape =
            universe
                .world
                .add_component(engine::ecs::component::CollisionShapeComponent::new(
                    engine::ecs::component::CollisionShape::cube_half_extents([
                        floor_half, thickness, floor_half,
                    ]),
                ));

        let _ = universe.attach(floor_root_t, floor_geom_t);
        let _ = universe.attach(floor_geom_t, floor_r);
        let _ = universe.attach(floor_r, floor_color);
        let _ = universe.attach(floor_geom_t, floor_cn);
        let _ = universe.attach(floor_cn, floor_shape);
        universe.add(floor_root_t);
    }

    // Square boundary walls around the floor edges.
    // Note: STATIC colliders don't need KineticResponse; they still collide with kinematic/rigged.
    fn spawn_boundary_wall(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        z: f32,
        half_extents: [f32; 3],
        color: [f32; 4],
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(
                    half_extents[0] * 2.0,
                    half_extents[1] * 2.0,
                    half_extents[2] * 2.0,
                ),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                color[0], color[1], color[2], color[3],
            ));

        let cn = universe
            .world
            .add_component(engine::ecs::component::CollisionComponent::STATIC());
        let shape =
            universe
                .world
                .add_component(engine::ecs::component::CollisionShapeComponent::new(
                    engine::ecs::component::CollisionShape::cube_half_extents(half_extents),
                ));

        let _ = universe.attach(t, r);
        let _ = universe.attach(r, c);
        let _ = universe.attach(t, cn);
        let _ = universe.attach(cn, shape);
        universe.add(t);
    }

    {
        let wall_half_height = 2.5;
        let wall_half_thickness = 0.30;
        let wall_center_y = wall_half_height; // bottom at y=0
        let wall_half_len = arena_half;

        // Subtle visible walls.
        let wall_color = [0.10, 0.10, 0.12, 0.30];

        // +Z / -Z
        spawn_boundary_wall(
            &mut universe,
            0.0,
            wall_center_y,
            arena_half,
            [wall_half_len, wall_half_height, wall_half_thickness],
            wall_color,
        );
        spawn_boundary_wall(
            &mut universe,
            0.0,
            wall_center_y,
            -arena_half,
            [wall_half_len, wall_half_height, wall_half_thickness],
            wall_color,
        );

        // +X / -X
        spawn_boundary_wall(
            &mut universe,
            arena_half,
            wall_center_y,
            0.0,
            [wall_half_thickness, wall_half_height, wall_half_len],
            wall_color,
        );
        spawn_boundary_wall(
            &mut universe,
            -arena_half,
            wall_center_y,
            0.0,
            [wall_half_thickness, wall_half_height, wall_half_len],
            wall_color,
        );
    }

    fn spawn_falling_cube(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        x: f32,
        y: f32,
        z: f32,
        s: f32,
        r: f32,
        g: f32,
        b: f32,
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(s, s, s),
        );

        let renderable = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let color = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(r, g, b, 1.0));

        let cn = universe
            .world
            .add_component(engine::ecs::component::CollisionComponent::KINEMATIC());

        let response = universe.world.add_component({
            let mut r = engine::ecs::component::KineticResponseComponent::push()
                .with_push_strength(3.0)
                .with_friction_y(18.0);
            // Allow higher fall speeds so gravity coefficients are visible.
            r.max_speed = 80.0;
            r
        });

        let shape =
            universe
                .world
                .add_component(engine::ecs::component::CollisionShapeComponent::new(
                    engine::ecs::component::CollisionShape::cube_half_extents([
                        0.5 * s,
                        0.5 * s,
                        0.5 * s,
                    ]),
                ));

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

        let _ = universe.attach(t, cn);
        let _ = universe.attach(cn, response);
        let _ = universe.attach(cn, shape);

        let _ = universe.attach(parent, t);
    }

    // Three gravity fields, each with 20 cubes.
    let field_low = universe
        .world
        .add_component(engine::ecs::component::GravityComponent::new().with_coefficient(0.125));
    let field_mid = universe
        .world
        .add_component(engine::ecs::component::GravityComponent::new().with_coefficient(0.5));
    let field_high = universe
        .world
        .add_component(engine::ecs::component::GravityComponent::new().with_coefficient(1.0));

    universe.add(field_low);
    universe.add(field_mid);
    universe.add(field_high);

    fn spawn_field(
        universe: &mut engine::Universe,
        field: engine::ecs::ComponentId,
        base_x: f32,
        base_z: f32,
        cube_color: [f32; 3],
    ) {
        let spacing = 0.7;
        let start_x = base_x - 2.0 * spacing;
        let start_z = base_z - 1.5 * spacing;

        for i in 0..20 {
            let ix = (i % 5) as f32;
            let iz = (i / 5) as f32;

            let x = start_x + ix * spacing;
            let z = start_z + iz * spacing;
            let y = 2.0 + iz * 0.6 + ix * 0.1;

            spawn_falling_cube(
                universe,
                field,
                x,
                y,
                z,
                0.5,
                cube_color[0],
                cube_color[1],
                cube_color[2],
            );
        }

        // Visual marker for the field center.
        let marker_t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(base_x, 0.1, base_z)
                .with_scale(0.3, 0.02, 0.3),
        );
        let marker_r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let marker_c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                cube_color[0],
                cube_color[1],
                cube_color[2],
                1.0,
            ));
        let _ = universe.attach(marker_t, marker_r);
        let _ = universe.attach(marker_r, marker_c);
        universe.add(marker_t);
    }

    spawn_field(&mut universe, field_low, -8.0, 0.0, [0.3, 0.6, 1.0]);
    spawn_field(&mut universe, field_mid, 0.0, 0.0, [0.4, 1.0, 0.4]);
    spawn_field(&mut universe, field_high, 8.0, 0.0, [1.0, 0.5, 0.2]);

    // Group-scoped collision behaviors.
    // - Low + High fields: cubes turn white after colliding with another cube.
    // - Mid field: cubes lose gravity after colliding with another cube.
    universe.add_signal_handler(
        engine::ecs::SignalKind::CollisionStarted,
        field_low,
        on_collision_turn_white,
    );
    universe.add_signal_handler(
        engine::ecs::SignalKind::CollisionStarted,
        field_high,
        on_collision_turn_white,
    );
    universe.add_signal_handler(
        engine::ecs::SignalKind::CollisionStarted,
        field_mid,
        on_collision_freeze_gravity,
    );

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

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

examples/example_util/mod.rs (line 31)

pub fn spawn_mms_demo_rig(
    universe: &mut engine::Universe,
    cam_pos: [f32; 3],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        BackgroundColorComponent, Camera3DComponent, InputComponent, InputTransformModeComponent,
        TransformComponent,
    };

    // Dark blue clear colour.
    let bg_color = universe
        .world
        .add_component(BackgroundColorComponent::new());
    let bg_color_c = universe
        .world
        .add_component(ColorComponent::rgba(0.02, 0.03, 0.10, 1.0));
    let _ = universe.world.add_child(bg_color, bg_color_c);
    universe.add(bg_color);

    // Camera rig: Input → Transform → Camera3D.
    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(3.0));
    let input_mode = universe
        .world
        .add_component(InputTransformModeComponent::forward_z().with_roll_axis_y());
    let _ = universe.attach(input, input_mode);

    let cam_transform = universe
        .world
        .add_component(TransformComponent::new().with_position(cam_pos[0], cam_pos[1], cam_pos[2]));
    let _ = universe.attach(input, cam_transform);

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

    universe.add(input);

    spawn_desktop_camera_controls_hint(universe, cam_transform);

    cam_transform
}

examples/diy-panel.rs (line 42)

fn spawn_runtime_text(
    universe: &mut engine::Universe,
    owner: engine::ecs::ComponentId,
    label: &str,
) {
    use engine::ecs::component::{
        ColorComponent, EdgeInsets, SizeDimension, StyleComponent, TextComponent,
        TransformComponent,
    };

    let root = universe.world.add_component_boxed_named(
        label,
        Box::new(TransformComponent::new().with_position(0.0, 0.0, 0.2)),
    );
    let style = universe.world.add_component_boxed_named(
        format!("{label}_style"),
        Box::new({
            let mut style = StyleComponent::new();
            style.margin = EdgeInsets::axes(0.25, 0.25);
            style.padding = EdgeInsets::axes(0.5, 0.5);
            style.height = SizeDimension::GlyphUnits(2.5);
            style.width = SizeDimension::Auto;
            style.background_color = Some([1.0, 0.80, 0.80, 1.0]);
            style
        }),
    );
    let text_root = universe.world.add_component_boxed_named(
        format!("{label}_text_root"),
        Box::new(TransformComponent::new().with_position(0.0, 0.0, 0.2)),
    );
    let text = universe
        .world
        .add_component_boxed_named(format!("{label}_text"), Box::new(TextComponent::new(label)));
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.40, 0.05, 0.05, 1.0));

    let _ = universe.world.add_child(root, style);
    let _ = universe.world.add_child(root, text_root);
    let _ = universe.world.add_child(text_root, text);
    let _ = universe.world.add_child(text, color);

    universe.attach(owner, root).expect("attach routed child");
}

examples/triage/panel-pierce.rs (line 62)

fn spawn_row(
    universe: &mut engine::Universe,
    scrolling: engine::ecs::ComponentId,
    index: usize,
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, RenderableComponent, TextComponent, TransformComponent,
    };

    let label = format!("row_{index:02}");
    let row = universe.world.add_component_boxed_named(
        label.clone(),
        Box::new(TransformComponent::new().with_position(0.0, -(index as f32) * 1.15, 0.05)),
    );
    let panel = universe.world.add_component_boxed_named(
        format!("{label}_panel"),
        Box::new(
            TransformComponent::new()
                .with_position(2.3, -0.45, 0.0)
                .with_scale(4.6, 0.9, 1.0),
        ),
    );
    let panel_renderable = universe.world.add_component_boxed_named(
        format!("{label}_rend"),
        Box::new(RenderableComponent::square()),
    );
    let panel_color = universe
        .world
        .add_component(ColorComponent::rgba(0.98, 0.94, 0.78, 1.0));

    let text_anchor = universe.world.add_component_boxed_named(
        format!("{label}_text_anchor"),
        Box::new(
            TransformComponent::new()
                .with_position(0.35, -0.38, 0.02)
                .with_scale(0.11, 0.11, 0.11),
        ),
    );
    let text = universe.world.add_component_boxed_named(
        format!("{label}_text"),
        Box::new(TextComponent::new(label.clone())),
    );
    let text_color = universe
        .world
        .add_component(ColorComponent::rgba(0.20, 0.16, 0.08, 1.0));

    let _ = universe.world.add_child(row, panel);
    let _ = universe.world.add_child(panel, panel_renderable);
    let _ = universe.world.add_child(panel_renderable, panel_color);
    let _ = universe.world.add_child(row, text_anchor);
    let _ = universe.world.add_child(text_anchor, text);
    let _ = universe.world.add_child(text, text_color);

    universe.attach(scrolling, row).expect("attach scroll row");
    row
}

Additional examples can be found in:

• examples/scrolling.rs
• examples/audio-clip-instance-demo.rs
• examples/audio-music-demo.rs
• examples/opacity-example.rs
• examples/pointer-events.rs
• examples/button-press.rs
• examples/vtuber-example.rs
• examples/openxr.rs
• examples/transparent-cutout-example.rs
• examples/gestures-and-gizmos.rs
• examples/background-example.rs
• examples/bisket-vr-demo.rs
• examples/background-occlusion-example.rs
• examples/animation-for-topology.rs
• examples/vr-input.rs
• examples/font-example.rs
• examples/vtuber-joints-example.rs
• examples/animation-example.rs
• examples/folder-text.rs
• examples/collision-perimeter.rs
• examples/audio-graph-example.rs

pub fn set_parent( &mut self, child: ComponentId, new_parent: Option<ComponentId>, ) -> Result<(), &'static str>

Change a component’s parent.

Equivalent to detach_from_parent(child) when new_parent is None.

pub fn detach_from_parent(&mut self, child: ComponentId)

Detach child from its current parent.

This does not delete anything.

pub fn remove_component_leaf( &mut self, c: ComponentId, ) -> Result<(), &'static str>

Remove a component from the world.

This is a leaf-only removal: it fails if the component still has children. Use remove_component_subtree when you want to delete a whole branch.

pub fn remove_component_subtree( &mut self, root: ComponentId, ) -> Result<(), &'static str>

Remove a component and all its descendants.

pub fn init_component_tree( &mut self, root: ComponentId, emit: &mut dyn SignalEmitter, )

Initialize a component tree starting from the given root component.

This recursively initializes the root component and all its descendants by calling Component::init on each component in the tree.

Trait Implementations

impl Default for World

fn default() -> World

Returns the “default value” for a type.