Struct PointLightComponent 

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

Point light (local omnidirectional light).

This is purely an ECS representation for now; renderer integration will come later.

Fields

intensity: f32

distance: f32

color: [f32; 3]

Linear RGB color in 0..1.

Implementations

impl PointLightComponent

pub fn new() -> Self

Examples found in repository

examples/folder-text.rs (line 270)

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/collision-perimeter.rs (line 104)

    fn spawn_light(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        z: f32,
        r: f32,
        g: f32,
        b: f32,
        intensity: f32,
        distance: f32,
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(0.12, 0.12, 0.12),
        );

        let l = universe.world.add_component(
            engine::ecs::component::PointLightComponent::new()
                .with_color(r, g, b)
                .with_intensity(intensity)
                .with_distance(distance),
        );
        // Visual marker: a small white cube at the light position.
        // White ensures it mostly shows the light color.
        let marker = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let marker_color =
            universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

        let _ = universe.attach(t, l);
        let _ = universe.attach(t, marker);
        let _ = universe.attach(marker, marker_color);
        universe.add(t);
    }

examples/opacity-example.rs (line 389)

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/text-animation.rs (line 40)

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(text_root);

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

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

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

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

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

    universe.add(anim);

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

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

examples/gravity-fields.rs (line 735)

    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
    }

examples/vtuber-example.rs (line 79)

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

Additional examples can be found in:

• examples/openxr.rs
• examples/transparent-cutout-example.rs
• examples/text-example.rs
• examples/background-example.rs
• examples/mesh-factory-example.rs
• examples/simple-demo.rs
• examples/background-occlusion-example.rs
• examples/animation-for-topology.rs
• examples/vtuber-joints-example.rs
• examples/animation-example.rs

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

Examples found in repository

examples/folder-text.rs (line 271)

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/collision-perimeter.rs (line 106)

    fn spawn_light(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        z: f32,
        r: f32,
        g: f32,
        b: f32,
        intensity: f32,
        distance: f32,
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(0.12, 0.12, 0.12),
        );

        let l = universe.world.add_component(
            engine::ecs::component::PointLightComponent::new()
                .with_color(r, g, b)
                .with_intensity(intensity)
                .with_distance(distance),
        );
        // Visual marker: a small white cube at the light position.
        // White ensures it mostly shows the light color.
        let marker = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let marker_color =
            universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

        let _ = universe.attach(t, l);
        let _ = universe.attach(t, marker);
        let _ = universe.attach(marker, marker_color);
        universe.add(t);
    }

examples/opacity-example.rs (line 391)

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/gravity-fields.rs (line 737)

    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
    }

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

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/background-occlusion-example.rs (line 89)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

pub fn with_distance(self, distance: f32) -> Self

Examples found in repository

examples/folder-text.rs (line 272)

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/collision-perimeter.rs (line 107)

    fn spawn_light(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        z: f32,
        r: f32,
        g: f32,
        b: f32,
        intensity: f32,
        distance: f32,
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(0.12, 0.12, 0.12),
        );

        let l = universe.world.add_component(
            engine::ecs::component::PointLightComponent::new()
                .with_color(r, g, b)
                .with_intensity(intensity)
                .with_distance(distance),
        );
        // Visual marker: a small white cube at the light position.
        // White ensures it mostly shows the light color.
        let marker = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let marker_color =
            universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

        let _ = universe.attach(t, l);
        let _ = universe.attach(t, marker);
        let _ = universe.attach(marker, marker_color);
        universe.add(t);
    }

examples/opacity-example.rs (line 392)

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/text-animation.rs (line 41)

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(text_root);

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

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

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

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

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

    universe.add(anim);

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

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

examples/gravity-fields.rs (line 738)

    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
    }

examples/vtuber-example.rs (line 80)

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

Additional examples can be found in:

• examples/openxr.rs
• examples/transparent-cutout-example.rs
• examples/text-example.rs
• examples/background-example.rs
• examples/mesh-factory-example.rs
• examples/simple-demo.rs
• examples/background-occlusion-example.rs
• examples/animation-for-topology.rs
• examples/vtuber-joints-example.rs
• examples/animation-example.rs

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

Examples found in repository

examples/folder-text.rs (line 273)

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/collision-perimeter.rs (line 105)

    fn spawn_light(
        universe: &mut engine::Universe,
        x: f32,
        y: f32,
        z: f32,
        r: f32,
        g: f32,
        b: f32,
        intensity: f32,
        distance: f32,
    ) {
        let t = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x, y, z)
                .with_scale(0.12, 0.12, 0.12),
        );

        let l = universe.world.add_component(
            engine::ecs::component::PointLightComponent::new()
                .with_color(r, g, b)
                .with_intensity(intensity)
                .with_distance(distance),
        );
        // Visual marker: a small white cube at the light position.
        // White ensures it mostly shows the light color.
        let marker = universe
            .world
            .add_component(engine::ecs::component::RenderableComponent::cube());
        let marker_color =
            universe
                .world
                .add_component(engine::ecs::component::ColorComponent::rgba(
                    1.0, 1.0, 1.0, 1.0,
                ));

        let _ = universe.attach(t, l);
        let _ = universe.attach(t, marker);
        let _ = universe.attach(marker, marker_color);
        universe.add(t);
    }

examples/opacity-example.rs (line 390)

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/text-animation.rs (line 42)

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(text_root);

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

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

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

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

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

    universe.add(anim);

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

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

examples/gravity-fields.rs (line 736)

    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
    }

examples/vtuber-example.rs (line 81)

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

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

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

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

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

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

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

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

    universe.add(input);

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

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

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

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

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

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

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

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

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

        universe.add(transform);
    };

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

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

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

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

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

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

Additional examples can be found in:

• examples/openxr.rs
• examples/transparent-cutout-example.rs
• examples/text-example.rs
• examples/background-example.rs
• examples/mesh-factory-example.rs
• examples/simple-demo.rs
• examples/background-occlusion-example.rs
• examples/animation-for-topology.rs
• examples/vtuber-joints-example.rs
• examples/animation-example.rs

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

Trait Implementations

impl Clone for PointLightComponent

fn clone(&self) -> PointLightComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for PointLightComponent

fn set_id(&mut self, component: ComponentId)

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

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

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

Called when component is added to the World

fn as_any(&self) -> &dyn Any

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

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

Encode this component as an MMS Component Expression AST node.

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

Called when component is removed from the World.

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

Encode component data to a HashMap for serialization.

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

Decode component data from a HashMap after deserialization.

impl Copy for PointLightComponent

impl Debug for PointLightComponent

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

Formats the value using the given formatter.

impl Default for PointLightComponent

fn default() -> Self

Returns the “default value” for a type.