Struct TransformComponent 

pub struct TransformComponent {
    pub transform: Transform,
    pub pending_look_at_target_world: Option<[f32; 3]>,
    /* private fields */
}

Fields

transform: Transform

Engine-wide transform type (also used by renderer/VisualWorld).

pending_look_at_target_world: Option<[f32; 3]>

Implementations

impl TransformComponent

pub fn new() -> Self

Examples found in repository

examples/transparent-cutout-example.rs (line 20)

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/button-press.rs (line 185)

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

    let t = universe.world.add_component(
        TransformComponent::new()
            .with_position(pos[0], pos[1], pos[2])
            .with_scale(scale[0], scale[1], scale[2]),
    );
    let r = universe.world.add_component(RenderableComponent::cube());
    let rc = universe
        .world
        .add_component(RaycastableComponent::enabled());

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

    r
}

fn spawn_raycastable_colored_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    pos: [f32; 3],
    scale: [f32; 3],
    rgba: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::ColorComponent;

    let r = spawn_raycastable_cube(universe, parent, pos, scale);
    let c = universe
        .world
        .add_component(ColorComponent::rgba(rgba[0], rgba[1], rgba[2], rgba[3]));
    let _ = universe.attach(r, c);
    r
}

fn wrap_at_for_button_middle_width(middle_w: f32, text_scale: f32) -> usize {
    // TextSystem layout: each glyph advances by 1.0 in local X.
    // With `text_root` scaled by `text_scale`, each glyph is ~`text_scale` world units wide.
    // Reserve some horizontal padding so letters don't collide with the face border.
    let padding_world = (middle_w * 0.10).clamp(0.02, 0.25);
    let usable_world = (middle_w - padding_world).max(0.05);
    let glyph_w_world = text_scale.abs().max(1e-4);

    let chars_per_line = (usable_world / glyph_w_world).floor() as isize;
    (chars_per_line.max(1) as usize).min(200)
}

fn measure_word_wrapped_block(text: &str, wrap_at: usize) -> (usize, usize) {
    // Approximate the block size (max columns, rows) for word-wrap-at-space behavior.
    // This is used only for centering the text root visually.
    if text.is_empty() {
        return (0, 0);
    }

    let wrap_at = wrap_at.max(1);

    let mut rows = 1usize;
    let mut col = 0usize;
    let mut max_col = 0usize;

    for (wi, word) in text.split_whitespace().enumerate() {
        let wlen = word.chars().count();
        if wlen == 0 {
            continue;
        }

        // If this isn't the first word on the line, account for a space.
        let needs_space = col > 0;
        let add = wlen + if needs_space { 1 } else { 0 };

        if col > 0 && col + add > wrap_at {
            // Wrap at the previous whitespace opportunity.
            max_col = max_col.max(col);
            rows += 1;
            col = 0;
        }

        // Place the word (and preceding space if any).
        col += add;

        // If a single word exceeds wrap_at, we don't break it (matching TextSystem word_wrap).
        max_col = max_col.max(col);

        // Preserve explicit newlines in the input.
        if wi == 0 {
            // no-op
        }
    }

    max_col = max_col.max(col);
    (max_col, rows)
}

fn spawn_button(
    universe: &mut engine::Universe,
    pos: [f32; 3],
    middle_wh: [f32; 2],
    border: ButtonBorder,
    text: &str,
    text_scale: f32,
    color: [f32; 4],
    background_color: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, TextComponent, TextureFilteringComponent, TransformComponent,
        TransparentCutoutComponent,
    };

    let button_root = universe
        .world
        .add_component(TransformComponent::new().with_position(pos[0], pos[1], pos[2]));

    // Frame: static border around the button.
    let frame_root = universe.world.add_component(TransformComponent::new());
    let frame_color = universe
        .world
        .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
    let _ = universe.attach(button_root, frame_root);
    let _ = universe.attach(frame_root, frame_color);

    // Cap: pressable face + text.
    let cap_raised_z = 0.030;
    let cap_pressed_z = 0.000;
    let cap_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, cap_raised_z));
    let _ = universe.attach(button_root, cap_root);

    let face_color = universe.world.add_component(ColorComponent::rgba(
        background_color[0],
        background_color[1],
        background_color[2],
        background_color[3],
    ));
    let _ = universe.attach(cap_root, face_color);

    // Geometry.
    let depth = 0.025;
    let middle_w = middle_wh[0];
    let middle_h = middle_wh[1];

    // Border pieces.
    let full_w = middle_w + border.left + border.right;
    let full_h = middle_h + border.top + border.bottom;

    // Left / right.
    let _left = spawn_raycastable_cube(
        universe,
        frame_color,
        [-(middle_w * 0.5 + border.left * 0.5), 0.0, 0.0],
        [border.left, full_h, depth],
    );
    let _right = spawn_raycastable_cube(
        universe,
        frame_color,
        [(middle_w * 0.5 + border.right * 0.5), 0.0, 0.0],
        [border.right, full_h, depth],
    );

    // Top / bottom.
    let _top = spawn_raycastable_cube(
        universe,
        frame_color,
        [0.0, (middle_h * 0.5 + border.top * 0.5), 0.0],
        [full_w, border.top, depth],
    );
    let _bottom = spawn_raycastable_cube(
        universe,
        frame_color,
        [0.0, -(middle_h * 0.5 + border.bottom * 0.5), 0.0],
        [full_w, border.bottom, depth],
    );

    // Face (pressable center).
    let _face = spawn_raycastable_cube(
        universe,
        face_color,
        [0.0, 0.0, 0.0],
        [middle_w, middle_h, depth],
    );

    // Text. (Heuristic centering; TextComponent is top-left anchored today.)
    let text_root = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, 0.0, depth * 0.5 + 0.006)
            .with_scale(text_scale, text_scale, 1.0),
    );
    let _ = universe.attach(cap_root, text_root);

    let wrap_at = wrap_at_for_button_middle_width(middle_w, text_scale);
    let (cols, rows) = measure_word_wrapped_block(text, wrap_at);
    let cols_f = cols.max(1) as f32;
    let rows_f = rows.max(1) as f32;

    // Center the text block around (0,0) in glyph-local units.
    // X is left-to-right (0..cols-1), Y is down (0, -1, -2...).
    let x_center = -0.5 * (cols_f - 1.0);
    let y_center = 0.5 * (rows_f - 1.0);
    let text_offset = universe
        .world
        .add_component(TransformComponent::new().with_position(x_center, y_center, 0.0));
    let _ = universe.attach(text_root, text_offset);

    let text_id = universe
        .world
        .add_component(TextComponent::with_word_wrap(text, wrap_at));
    let _ = universe.attach(text_offset, text_id);

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

    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest_magnification());
    let _ = universe.attach(text_id, filtering);

    universe.add(button_root);

    // Attach text color *after* text has been built/initialized.
    // We intentionally initialize the ColorComponent before attachment so that its `init()` will
    // NOT re-run on attach; this exercises the TextSystem ParentChanged refresh behavior.
    let text_color = universe
        .world
        .add_component(ColorComponent::rgba(0.0, 0.0, 0.0, 1.0));
    universe.add(text_color);
    let _ = universe.attach(text_id, text_color);

    // Stash state for the signal handler.
    let state = ButtonState {
        pressed: false,
        cap_root,
        cap_raised_z,
        cap_pressed_z,
        frame_color,
        face_color,
        text_id,
        text_color,
        frame_color_up: color,
        face_color_up: background_color,
        text_color_up: [0.0, 0.0, 0.0, 1.0],
        frame_color_down: darken(color, 0.75),
        face_color_down: darken(background_color, 0.75),
        text_color_down: [1.0, 1.0, 1.0, 1.0],
    };

    BUTTONS
        .get_or_init(|| Mutex::new(HashMap::new()))
        .lock()
        .expect("button state lock")
        .insert(button_root, state);

    button_root
}

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

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

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

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

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

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

    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(2.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    let rig_t = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 2.5));
    let _ = universe.attach(input, rig_t);

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

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

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

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

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

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

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

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

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

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

        universe.add(editor_root);
    }

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

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

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

examples/opacity-example.rs (line 21)

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 (line 28)

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 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/example_util/mod.rs (line 45)

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
}

Additional examples can be found in:

• examples/simple-demo.rs
• examples/pointer-events.rs
• examples/diy-panel.rs
• examples/util/mod.rs
• examples/vr-input.rs
• examples/triage/panel-pierce.rs
• examples/scrolling.rs
• examples/audio-clip-instance-demo.rs
• examples/audio-music-demo.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 with_position(self, x: f32, y: f32, z: f32) -> Self

Examples found in repository

examples/transparent-cutout-example.rs (line 21)

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/button-press.rs (line 186)

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

    let t = universe.world.add_component(
        TransformComponent::new()
            .with_position(pos[0], pos[1], pos[2])
            .with_scale(scale[0], scale[1], scale[2]),
    );
    let r = universe.world.add_component(RenderableComponent::cube());
    let rc = universe
        .world
        .add_component(RaycastableComponent::enabled());

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

    r
}

fn spawn_raycastable_colored_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    pos: [f32; 3],
    scale: [f32; 3],
    rgba: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::ColorComponent;

    let r = spawn_raycastable_cube(universe, parent, pos, scale);
    let c = universe
        .world
        .add_component(ColorComponent::rgba(rgba[0], rgba[1], rgba[2], rgba[3]));
    let _ = universe.attach(r, c);
    r
}

fn wrap_at_for_button_middle_width(middle_w: f32, text_scale: f32) -> usize {
    // TextSystem layout: each glyph advances by 1.0 in local X.
    // With `text_root` scaled by `text_scale`, each glyph is ~`text_scale` world units wide.
    // Reserve some horizontal padding so letters don't collide with the face border.
    let padding_world = (middle_w * 0.10).clamp(0.02, 0.25);
    let usable_world = (middle_w - padding_world).max(0.05);
    let glyph_w_world = text_scale.abs().max(1e-4);

    let chars_per_line = (usable_world / glyph_w_world).floor() as isize;
    (chars_per_line.max(1) as usize).min(200)
}

fn measure_word_wrapped_block(text: &str, wrap_at: usize) -> (usize, usize) {
    // Approximate the block size (max columns, rows) for word-wrap-at-space behavior.
    // This is used only for centering the text root visually.
    if text.is_empty() {
        return (0, 0);
    }

    let wrap_at = wrap_at.max(1);

    let mut rows = 1usize;
    let mut col = 0usize;
    let mut max_col = 0usize;

    for (wi, word) in text.split_whitespace().enumerate() {
        let wlen = word.chars().count();
        if wlen == 0 {
            continue;
        }

        // If this isn't the first word on the line, account for a space.
        let needs_space = col > 0;
        let add = wlen + if needs_space { 1 } else { 0 };

        if col > 0 && col + add > wrap_at {
            // Wrap at the previous whitespace opportunity.
            max_col = max_col.max(col);
            rows += 1;
            col = 0;
        }

        // Place the word (and preceding space if any).
        col += add;

        // If a single word exceeds wrap_at, we don't break it (matching TextSystem word_wrap).
        max_col = max_col.max(col);

        // Preserve explicit newlines in the input.
        if wi == 0 {
            // no-op
        }
    }

    max_col = max_col.max(col);
    (max_col, rows)
}

fn spawn_button(
    universe: &mut engine::Universe,
    pos: [f32; 3],
    middle_wh: [f32; 2],
    border: ButtonBorder,
    text: &str,
    text_scale: f32,
    color: [f32; 4],
    background_color: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, TextComponent, TextureFilteringComponent, TransformComponent,
        TransparentCutoutComponent,
    };

    let button_root = universe
        .world
        .add_component(TransformComponent::new().with_position(pos[0], pos[1], pos[2]));

    // Frame: static border around the button.
    let frame_root = universe.world.add_component(TransformComponent::new());
    let frame_color = universe
        .world
        .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
    let _ = universe.attach(button_root, frame_root);
    let _ = universe.attach(frame_root, frame_color);

    // Cap: pressable face + text.
    let cap_raised_z = 0.030;
    let cap_pressed_z = 0.000;
    let cap_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, cap_raised_z));
    let _ = universe.attach(button_root, cap_root);

    let face_color = universe.world.add_component(ColorComponent::rgba(
        background_color[0],
        background_color[1],
        background_color[2],
        background_color[3],
    ));
    let _ = universe.attach(cap_root, face_color);

    // Geometry.
    let depth = 0.025;
    let middle_w = middle_wh[0];
    let middle_h = middle_wh[1];

    // Border pieces.
    let full_w = middle_w + border.left + border.right;
    let full_h = middle_h + border.top + border.bottom;

    // Left / right.
    let _left = spawn_raycastable_cube(
        universe,
        frame_color,
        [-(middle_w * 0.5 + border.left * 0.5), 0.0, 0.0],
        [border.left, full_h, depth],
    );
    let _right = spawn_raycastable_cube(
        universe,
        frame_color,
        [(middle_w * 0.5 + border.right * 0.5), 0.0, 0.0],
        [border.right, full_h, depth],
    );

    // Top / bottom.
    let _top = spawn_raycastable_cube(
        universe,
        frame_color,
        [0.0, (middle_h * 0.5 + border.top * 0.5), 0.0],
        [full_w, border.top, depth],
    );
    let _bottom = spawn_raycastable_cube(
        universe,
        frame_color,
        [0.0, -(middle_h * 0.5 + border.bottom * 0.5), 0.0],
        [full_w, border.bottom, depth],
    );

    // Face (pressable center).
    let _face = spawn_raycastable_cube(
        universe,
        face_color,
        [0.0, 0.0, 0.0],
        [middle_w, middle_h, depth],
    );

    // Text. (Heuristic centering; TextComponent is top-left anchored today.)
    let text_root = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, 0.0, depth * 0.5 + 0.006)
            .with_scale(text_scale, text_scale, 1.0),
    );
    let _ = universe.attach(cap_root, text_root);

    let wrap_at = wrap_at_for_button_middle_width(middle_w, text_scale);
    let (cols, rows) = measure_word_wrapped_block(text, wrap_at);
    let cols_f = cols.max(1) as f32;
    let rows_f = rows.max(1) as f32;

    // Center the text block around (0,0) in glyph-local units.
    // X is left-to-right (0..cols-1), Y is down (0, -1, -2...).
    let x_center = -0.5 * (cols_f - 1.0);
    let y_center = 0.5 * (rows_f - 1.0);
    let text_offset = universe
        .world
        .add_component(TransformComponent::new().with_position(x_center, y_center, 0.0));
    let _ = universe.attach(text_root, text_offset);

    let text_id = universe
        .world
        .add_component(TextComponent::with_word_wrap(text, wrap_at));
    let _ = universe.attach(text_offset, text_id);

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

    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest_magnification());
    let _ = universe.attach(text_id, filtering);

    universe.add(button_root);

    // Attach text color *after* text has been built/initialized.
    // We intentionally initialize the ColorComponent before attachment so that its `init()` will
    // NOT re-run on attach; this exercises the TextSystem ParentChanged refresh behavior.
    let text_color = universe
        .world
        .add_component(ColorComponent::rgba(0.0, 0.0, 0.0, 1.0));
    universe.add(text_color);
    let _ = universe.attach(text_id, text_color);

    // Stash state for the signal handler.
    let state = ButtonState {
        pressed: false,
        cap_root,
        cap_raised_z,
        cap_pressed_z,
        frame_color,
        face_color,
        text_id,
        text_color,
        frame_color_up: color,
        face_color_up: background_color,
        text_color_up: [0.0, 0.0, 0.0, 1.0],
        frame_color_down: darken(color, 0.75),
        face_color_down: darken(background_color, 0.75),
        text_color_down: [1.0, 1.0, 1.0, 1.0],
    };

    BUTTONS
        .get_or_init(|| Mutex::new(HashMap::new()))
        .lock()
        .expect("button state lock")
        .insert(button_root, state);

    button_root
}

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

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

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

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

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

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

    let input = universe
        .world
        .add_component(InputComponent::new().with_speed(2.5));
    let input_mode = universe.world.add_component(
        InputTransformModeComponent::forward_z()
            .with_fps_rotation()
            .with_roll_axis_y(),
    );
    let _ = universe.attach(input, input_mode);

    let rig_t = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, 2.5));
    let _ = universe.attach(input, rig_t);

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

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

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

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

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

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

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

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

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

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

        universe.add(editor_root);
    }

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

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

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

examples/opacity-example.rs (line 22)

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 (line 29)

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/example_util/mod.rs (line 45)

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 (line 35)

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/triage/panel-pierce.rs
• examples/scrolling.rs
• examples/audio-clip-instance-demo.rs
• examples/audio-music-demo.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 with_scale(self, x: f32, y: f32, z: f32) -> Self

Examples found in repository

examples/animation-example.rs (line 105)

    fn spawn_text(universe: &mut engine::Universe, pos: (f32, f32, f32), scale: f32, text: &str) {
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(pos.0, pos.1, pos.2)
                .with_scale(scale, scale, 1.0),
        );
        let t =
            universe
                .world
                .add_component(engine::ecs::component::TextComponent::with_word_wrap(
                    text, 38,
                ));
        let _ = universe.attach(tx, t);
        universe.add(tx);
    }

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

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

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

        tx
    }

examples/transparent-cutout-example.rs (line 22)

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/button-press.rs (line 187)

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

    let t = universe.world.add_component(
        TransformComponent::new()
            .with_position(pos[0], pos[1], pos[2])
            .with_scale(scale[0], scale[1], scale[2]),
    );
    let r = universe.world.add_component(RenderableComponent::cube());
    let rc = universe
        .world
        .add_component(RaycastableComponent::enabled());

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

    r
}

fn spawn_raycastable_colored_cube(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    pos: [f32; 3],
    scale: [f32; 3],
    rgba: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::ColorComponent;

    let r = spawn_raycastable_cube(universe, parent, pos, scale);
    let c = universe
        .world
        .add_component(ColorComponent::rgba(rgba[0], rgba[1], rgba[2], rgba[3]));
    let _ = universe.attach(r, c);
    r
}

fn wrap_at_for_button_middle_width(middle_w: f32, text_scale: f32) -> usize {
    // TextSystem layout: each glyph advances by 1.0 in local X.
    // With `text_root` scaled by `text_scale`, each glyph is ~`text_scale` world units wide.
    // Reserve some horizontal padding so letters don't collide with the face border.
    let padding_world = (middle_w * 0.10).clamp(0.02, 0.25);
    let usable_world = (middle_w - padding_world).max(0.05);
    let glyph_w_world = text_scale.abs().max(1e-4);

    let chars_per_line = (usable_world / glyph_w_world).floor() as isize;
    (chars_per_line.max(1) as usize).min(200)
}

fn measure_word_wrapped_block(text: &str, wrap_at: usize) -> (usize, usize) {
    // Approximate the block size (max columns, rows) for word-wrap-at-space behavior.
    // This is used only for centering the text root visually.
    if text.is_empty() {
        return (0, 0);
    }

    let wrap_at = wrap_at.max(1);

    let mut rows = 1usize;
    let mut col = 0usize;
    let mut max_col = 0usize;

    for (wi, word) in text.split_whitespace().enumerate() {
        let wlen = word.chars().count();
        if wlen == 0 {
            continue;
        }

        // If this isn't the first word on the line, account for a space.
        let needs_space = col > 0;
        let add = wlen + if needs_space { 1 } else { 0 };

        if col > 0 && col + add > wrap_at {
            // Wrap at the previous whitespace opportunity.
            max_col = max_col.max(col);
            rows += 1;
            col = 0;
        }

        // Place the word (and preceding space if any).
        col += add;

        // If a single word exceeds wrap_at, we don't break it (matching TextSystem word_wrap).
        max_col = max_col.max(col);

        // Preserve explicit newlines in the input.
        if wi == 0 {
            // no-op
        }
    }

    max_col = max_col.max(col);
    (max_col, rows)
}

fn spawn_button(
    universe: &mut engine::Universe,
    pos: [f32; 3],
    middle_wh: [f32; 2],
    border: ButtonBorder,
    text: &str,
    text_scale: f32,
    color: [f32; 4],
    background_color: [f32; 4],
) -> engine::ecs::ComponentId {
    use engine::ecs::component::{
        ColorComponent, TextComponent, TextureFilteringComponent, TransformComponent,
        TransparentCutoutComponent,
    };

    let button_root = universe
        .world
        .add_component(TransformComponent::new().with_position(pos[0], pos[1], pos[2]));

    // Frame: static border around the button.
    let frame_root = universe.world.add_component(TransformComponent::new());
    let frame_color = universe
        .world
        .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
    let _ = universe.attach(button_root, frame_root);
    let _ = universe.attach(frame_root, frame_color);

    // Cap: pressable face + text.
    let cap_raised_z = 0.030;
    let cap_pressed_z = 0.000;
    let cap_root = universe
        .world
        .add_component(TransformComponent::new().with_position(0.0, 0.0, cap_raised_z));
    let _ = universe.attach(button_root, cap_root);

    let face_color = universe.world.add_component(ColorComponent::rgba(
        background_color[0],
        background_color[1],
        background_color[2],
        background_color[3],
    ));
    let _ = universe.attach(cap_root, face_color);

    // Geometry.
    let depth = 0.025;
    let middle_w = middle_wh[0];
    let middle_h = middle_wh[1];

    // Border pieces.
    let full_w = middle_w + border.left + border.right;
    let full_h = middle_h + border.top + border.bottom;

    // Left / right.
    let _left = spawn_raycastable_cube(
        universe,
        frame_color,
        [-(middle_w * 0.5 + border.left * 0.5), 0.0, 0.0],
        [border.left, full_h, depth],
    );
    let _right = spawn_raycastable_cube(
        universe,
        frame_color,
        [(middle_w * 0.5 + border.right * 0.5), 0.0, 0.0],
        [border.right, full_h, depth],
    );

    // Top / bottom.
    let _top = spawn_raycastable_cube(
        universe,
        frame_color,
        [0.0, (middle_h * 0.5 + border.top * 0.5), 0.0],
        [full_w, border.top, depth],
    );
    let _bottom = spawn_raycastable_cube(
        universe,
        frame_color,
        [0.0, -(middle_h * 0.5 + border.bottom * 0.5), 0.0],
        [full_w, border.bottom, depth],
    );

    // Face (pressable center).
    let _face = spawn_raycastable_cube(
        universe,
        face_color,
        [0.0, 0.0, 0.0],
        [middle_w, middle_h, depth],
    );

    // Text. (Heuristic centering; TextComponent is top-left anchored today.)
    let text_root = universe.world.add_component(
        TransformComponent::new()
            .with_position(0.0, 0.0, depth * 0.5 + 0.006)
            .with_scale(text_scale, text_scale, 1.0),
    );
    let _ = universe.attach(cap_root, text_root);

    let wrap_at = wrap_at_for_button_middle_width(middle_w, text_scale);
    let (cols, rows) = measure_word_wrapped_block(text, wrap_at);
    let cols_f = cols.max(1) as f32;
    let rows_f = rows.max(1) as f32;

    // Center the text block around (0,0) in glyph-local units.
    // X is left-to-right (0..cols-1), Y is down (0, -1, -2...).
    let x_center = -0.5 * (cols_f - 1.0);
    let y_center = 0.5 * (rows_f - 1.0);
    let text_offset = universe
        .world
        .add_component(TransformComponent::new().with_position(x_center, y_center, 0.0));
    let _ = universe.attach(text_root, text_offset);

    let text_id = universe
        .world
        .add_component(TextComponent::with_word_wrap(text, wrap_at));
    let _ = universe.attach(text_offset, text_id);

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

    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest_magnification());
    let _ = universe.attach(text_id, filtering);

    universe.add(button_root);

    // Attach text color *after* text has been built/initialized.
    // We intentionally initialize the ColorComponent before attachment so that its `init()` will
    // NOT re-run on attach; this exercises the TextSystem ParentChanged refresh behavior.
    let text_color = universe
        .world
        .add_component(ColorComponent::rgba(0.0, 0.0, 0.0, 1.0));
    universe.add(text_color);
    let _ = universe.attach(text_id, text_color);

    // Stash state for the signal handler.
    let state = ButtonState {
        pressed: false,
        cap_root,
        cap_raised_z,
        cap_pressed_z,
        frame_color,
        face_color,
        text_id,
        text_color,
        frame_color_up: color,
        face_color_up: background_color,
        text_color_up: [0.0, 0.0, 0.0, 1.0],
        frame_color_down: darken(color, 0.75),
        face_color_down: darken(background_color, 0.75),
        text_color_down: [1.0, 1.0, 1.0, 1.0],
    };

    BUTTONS
        .get_or_init(|| Mutex::new(HashMap::new()))
        .lock()
        .expect("button state lock")
        .insert(button_root, state);

    button_root
}

examples/opacity-example.rs (line 23)

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 (line 30)

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
}

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

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

Additional examples can be found in:

• examples/audio-graph-example.rs
• examples/collision-perimeter.rs
• examples/simple-demo.rs
• examples/pointer-events.rs
• examples/util/mod.rs
• examples/vr-input.rs
• examples/triage/panel-pierce.rs
• examples/scrolling.rs
• examples/font-example.rs
• examples/example_util/mod.rs
• examples/mesh-factory-example.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/bisket-vr-demo.rs
• examples/background-occlusion-example.rs
• examples/vtuber-joints-example.rs
• examples/folder-text.rs
• examples/gravity-fields.rs

pub fn with_rotation_euler(self, pitch_x: f32, yaw_y: f32, roll_z: f32) -> Self

Builder-style: set rotation from Euler angles (radians), returns Self.

Examples found in repository

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

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

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

        universe.add(t);
    }

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

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

        universe.add(t);
    }

examples/simple-demo.rs (line 37)

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

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

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/folder-text.rs (line 235)

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

    // Usage:
    //   cargo run --example folder-text -- [folder] [spacing]
    // Defaults:
    //   folder=src  spacing=0.3
    let mut args = std::env::args().skip(1);
    let folder = args.next().unwrap_or_else(|| "src".to_string());
    let spacing: f32 = args
        .next()
        .and_then(|s| s.parse::<f32>().ok())
        .unwrap_or(1.0);

    // Safety caps: this demo can explode the ECS if we load huge projects.
    const MAX_FILES: usize = 42;
    const MAX_CHARS_PER_FILE: usize = 10_000;
    const WRAP_AT: usize = 90;
    const TEXT_SCALE: f32 = 0.01;

    let cwd = std::env::current_dir().unwrap_or_else(|_| PathBuf::from("."));
    let manifest_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
    let scan_root = {
        let p = PathBuf::from(&folder);
        if p.is_absolute() {
            p
        } else {
            // Resolve relative paths from the crate root, not the process CWD.
            manifest_dir.join(p)
        }
    };
    eprintln!("[folder-text] cwd={:?}", cwd);
    eprintln!("[folder-text] manifest_dir={:?}", manifest_dir);
    eprintln!("[folder-text] scan_root={:?}", scan_root);

    let mut files = Vec::new();
    collect_rs_files(&scan_root, &mut files);
    files.sort();

    if files.is_empty() {
        eprintln!(
            "[folder-text] No .rs files found under folder={:?} (resolved={:?})",
            folder, scan_root
        );
    }

    let files: Vec<PathBuf> = files.into_iter().take(MAX_FILES).collect();
    eprintln!(
        "[folder-text] Loaded {} file(s) from {:?} (spacing={})",
        files.len(),
        folder,
        spacing
    );

    #[derive(Debug, Clone)]
    struct FileEntry {
        path: PathBuf,
        display_text: String,
        max_cols: usize,
        rows: usize,
    }

    // Group files by folder.
    // Layout:
    // - each folder becomes a column along +X
    // - within a folder, files stack along +Y (8 high)
    // - after 8, additional files start a new stack further along +Z
    let mut files_by_folder: BTreeMap<PathBuf, Vec<FileEntry>> = BTreeMap::new();
    for path in files {
        let Ok(content) = std::fs::read_to_string(&path) else {
            eprintln!("[folder-text] Failed to read {:?}", path);
            continue;
        };

        let mut display_text = format!(
            "// {}\n\n{}",
            path.strip_prefix(&manifest_dir).unwrap_or(&path).display(),
            content
        );

        if display_text.chars().count() > MAX_CHARS_PER_FILE {
            display_text = display_text
                .chars()
                .take(MAX_CHARS_PER_FILE)
                .collect::<String>();
            display_text.push_str("\n\n// ... truncated ...\n");
        }

        let (max_cols, rows) = measure_text_bounds(&display_text, WRAP_AT);

        let folder_key = path.parent().unwrap_or(&scan_root).to_path_buf();
        files_by_folder
            .entry(folder_key)
            .or_default()
            .push(FileEntry {
                path,
                display_text,
                max_cols,
                rows,
            });
    }

    let column_count = files_by_folder.len().max(1);

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

    let bg_r = 0.25;
    let bg_g = 0.25;
    let bg_b = 0.25;
    let background = universe
        .world
        .add_component(engine::ecs::component::BackgroundColorComponent::new());
    let background_c = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            bg_r, bg_g, bg_b, 1.00,
        ));
    let _ = universe.world.add_child(background, background_c);
    universe.add(background);

    let ambient = universe
        .world
        .add_component(engine::ecs::component::AmbientLightComponent::rgb(
            bg_r, bg_g, bg_b,
        ));
    universe.add(ambient);

    // Input-driven camera rig.
    // Topology: I { T { C3D } }
    let input = universe
        .world
        .add_component(engine::ecs::component::InputComponent::new().with_speed(1.5));

    // Center the camera horizontally over the spawned columns.
    let center_x = if column_count <= 1 {
        0.0
    } else {
        ((column_count - 1) as f32) * spacing * 0.5
    };

    // Bring camera closer: these text blocks are tiny.
    let rig_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(center_x, 0.0, 1.2),
    );
    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(),
    );
    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);

    // Big floor plane under everything.
    // RenderableComponent::square() is an XY quad facing +Z; rotate it to XZ facing +Y.
    let max_stacks = files_by_folder
        .values()
        .map(|v| (v.len() + 7) / 8)
        .max()
        .unwrap_or(1)
        .max(1);
    let total_width = (column_count as f32) * spacing;
    let total_depth = (max_stacks as f32) * spacing;
    let floor_w = total_width.max(10.0);
    let floor_h = total_depth.max(10.0);
    let floor_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new()
            .with_position(0.0, -2.0, 0.0)
            .with_rotation_euler(-std::f32::consts::FRAC_PI_2, 0.0, 0.0)
            .with_scale(floor_w, floor_h, 1.0),
    );
    let floor_renderable = universe
        .world
        .add_component(engine::ecs::component::RenderableComponent::square());
    let floor_color = universe
        .world
        .add_component(engine::ecs::component::ColorComponent::rgba(
            0.88, 0.88, 0.88, 1.0,
        ));
    let _ = universe.attach(floor_transform, floor_renderable);
    let _ = universe.attach(floor_renderable, floor_color);
    universe.add(floor_transform);

    // 4 red cubes around the perimeter of the world (easy visual anchors).
    fn spawn_red_cube(universe: &mut engine::Universe, x: f32, y: f32, z: f32, s: f32) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(s, s, s),
        );
        let r = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let c = universe
            .world
            .add_component(engine::ecs::component::ColorComponent::rgba(
                1.0, 0.0, 0.0, 1.0,
            ));

        let light_transform = universe.world.add_component(
            engine::ecs::component::TransformComponent::new().with_position(0.0, s * 0.75, 0.0),
        );
        let light = universe.world.add_component(
            engine::ecs::component::PointLightComponent::new()
                .with_intensity(1.5)
                .with_distance(20.0)
                .with_color(1.0, 0.0, 0.0),
        );

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

        universe.add(t);
    }

    let p = 1.5;
    let s = 0.25;
    spawn_red_cube(&mut universe, -p, -p, 0.0, s);
    spawn_red_cube(&mut universe, p, -p, 0.0, s);
    spawn_red_cube(&mut universe, -p, p, 0.0, s);
    spawn_red_cube(&mut universe, p, p, 0.0, s);

    let start_x = -center_x;
    let stack_depth = spacing;
    let row_gap_world = 0.35;

    // One global point light at the top of the overall text "tower".
    let pad_y = 4.0;
    let global_max_panel_h_world = files_by_folder
        .values()
        .flat_map(|v| v.iter())
        .map(|e| ((e.rows as f32) + pad_y) * TEXT_SCALE)
        .fold(0.0_f32, f32::max)
        .max(0.6);
    let global_slot_h_world = global_max_panel_h_world + row_gap_world;
    let tower_top_y = (7.0 * global_slot_h_world) + 4.0;
    let tower_center_z = total_depth * 0.5;

    let tower_light_transform = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(
            0.0,
            tower_top_y,
            tower_center_z,
        ),
    );
    let tower_light = universe.world.add_component(
        engine::ecs::component::PointLightComponent::new()
            .with_intensity(2.0)
            .with_distance(120.0)
            .with_color(1.0, 1.0, 1.0),
    );
    let _ = universe.attach(tower_light_transform, tower_light);
    universe.add(tower_light_transform);

    for (col_idx, (_folder, mut entries)) in files_by_folder.into_iter().enumerate() {
        entries.sort_by(|a, b| a.path.cmp(&b.path));

        // Slot height (world units) based on the tallest panel in this folder.
        let pad_y = 4.0;
        let max_panel_h_world = entries
            .iter()
            .map(|e| ((e.rows as f32) + pad_y) * TEXT_SCALE)
            .fold(0.0_f32, f32::max)
            .max(0.6);
        let slot_h_world = max_panel_h_world + row_gap_world;

        let col_x = start_x + (col_idx as f32) * spacing;

        for (i, entry) in entries.into_iter().enumerate() {
            let row = (i % 8) as f32;
            let stack = (i / 8) as f32;
            let file_y = row * slot_h_world;
            let file_z = stack * stack_depth;

            let file_group = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(col_x, file_y, file_z),
            );

            // Text subtree (tiny scale).
            let file_root = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(0.0, 1.0, 0.0)
                    .with_scale(TEXT_SCALE, TEXT_SCALE, 1.0)
                    .with_rotation_euler(0.0, std::f32::consts::PI / 6.0, 0.0),
            );
            let _ = universe.attach(file_group, file_root);

            // Background panel behind the text.
            // Size is based on wrapped line count (matches TextSystem's strict wrapping behavior).
            let (max_cols, rows) = (entry.max_cols, entry.rows);
            let pad_x = 4.0;
            let pad_y = 4.0;
            let w = (max_cols as f32) + pad_x;
            let h = (rows as f32) + pad_y;

            // Text glyph quads are centered at integer (col,row) positions and are 1x1, so the
            // text's AABB (in text-space) is roughly:
            //   x: [-0.5, max_cols-0.5]
            //   y: [-(rows-1)-0.5, 0.5]
            // Centering the background quad at those midpoints keeps it aligned as text grows.
            let bg_x = (max_cols as f32 - 1.0) * 0.5;
            let bg_y = -((rows as f32 - 1.0) * 0.5);

            let bg_transform = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(bg_x, bg_y, -0.05)
                    .with_scale(w, h, 1.0),
            );
            let bg_renderable = universe
                .world
                .add_component(engine::ecs::component::RenderableComponent::square());
            let bg_quant = universe.world.add_component(
                engine::ecs::component::LightQuantizationComponent::steps(5.0),
            );
            let bg_color =
                universe
                    .world
                    .add_component(engine::ecs::component::ColorComponent::rgba(
                        0.2, 0.2, 0.2, 1.0,
                    ));
            let _ = universe.attach(file_root, bg_transform);
            let _ = universe.attach(bg_transform, bg_renderable);
            let _ = universe.attach(bg_renderable, bg_quant);
            let _ = universe.attach(bg_renderable, bg_color);

            let text =
                universe
                    .world
                    .add_component(engine::ecs::component::TextComponent::with_wrap(
                        entry.display_text,
                        WRAP_AT,
                    ));
            let cutout = universe
                .world
                .add_component(engine::ecs::component::TransparentCutoutComponent::new());
            let filtering = universe.world.add_component(
                engine::ecs::component::TextureFilteringComponent::nearest_magnification(),
            );
            // let color = universe
            //     .world
            //     .add_component(engine::ecs::component::ColorComponent::rgba(0.7, 0.7, 1.0, 1.0));
            let emissive = universe
                .world
                .add_component(engine::ecs::component::EmissiveComponent::on());
            let _ = universe.attach(file_root, text);
            let _ = universe.attach(text, cutout);
            let _ = universe.attach(text, filtering);
            //let _ = universe.world.add_child(text, color);
            let _ = universe.attach(text, emissive);

            universe.add(file_group);
        }
    }

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

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

examples/gravity-fields.rs (line 761)

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

pub fn with_rotation_quat(self, quat_xyzw: [f32; 4]) -> Self

Builder-style: set rotation from a quaternion (xyzw), returns Self.

pub fn with_looking_at(self, target_world: [f32; 3]) -> Self

pub fn look_at_world_rotation( world_position: [f32; 3], target_world: [f32; 3], ) -> Option<[f32; 4]>

pub fn set_rotation_euler( &mut self, emit: &mut dyn SignalEmitter, pitch_x: f32, yaw_y: f32, roll_z: f32, )

Set rotation from Euler angles (radians), XYZ order, and queue update.

pub fn set_rotation_quat( &mut self, emit: &mut dyn SignalEmitter, quat_xyzw: [f32; 4], )

Set rotation from a quaternion (xyzw) and queue update.

pub fn set_position( &mut self, emit: &mut dyn SignalEmitter, x: f32, y: f32, z: f32, )

Set translation and queue update.

pub fn set_scale( &mut self, emit: &mut dyn SignalEmitter, x: f32, y: f32, z: f32, )

Set non-uniform scale and queue update.

Trait Implementations

impl Clone for TransformComponent

fn clone(&self) -> TransformComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for TransformComponent

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

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

fn set_id(&mut self, component: ComponentId)

fn as_any(&self) -> &dyn Any

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

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

Called when component is added to the World

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

Encode this component as an MMS Component Expression AST node.

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

Called when component is removed from the World.

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

Encode component data to a HashMap for serialization.

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

Decode component data from a HashMap after deserialization.

impl Copy for TransformComponent

impl Debug for TransformComponent

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

Formats the value using the given formatter.

impl Default for TransformComponent

fn default() -> Self

Returns the “default value” for a type.