Struct TextComponent 

pub struct TextComponent {
    pub text: String,
    pub font_size: f32,
    pub authored_font_size: f32,
    pub wrap_at: usize,
    pub authored_wrap_at: usize,
    pub word_wrap: bool,
    pub authored_word_wrap: bool,
    pub word_wrap_tokens: Vec<String>,
    pub authored_word_wrap_tokens: Vec<String>,
    /* private fields */
}

Text component.

On registration, TextSystem expands this into per-glyph component trees.

Fields

text: String

font_size: f32

Effective visual scale applied to spawned glyph quads.

This affects glyph rendering only; layout still measures text in glyph columns. Style.font_size may temporarily override this value during layout, while authored_font_size preserves the authored/default size.

authored_font_size: f32

Author-provided font size. Preserved when layout applies or removes a style-driven override so the effective font_size can be restored.

wrap_at: usize

Wrap after this many characters. This is the effective value used by TextSystem for glyph layout. The layout pass may narrow it to fit the containing block, but it never exceeds Self::authored_wrap_at.

authored_wrap_at: usize

Author-provided wrap cap. Captured at construction (and on decode) and never modified by the layout pass. Layout uses this as the upper bound when re-deriving wrap_at from the current container width — so when the container grows again, wrap_at can be widened back up to (but not past) authored_wrap_at.

Invariant: any future “set the wrap cap” mutation path (an MMS wrap_at(N) setter, a Rust set_wrap helper, etc.) MUST update both wrap_at and authored_wrap_at. Updating only wrap_at will be silently undone by the next layout pass.

word_wrap: bool

If true, wrap only at whitespace boundaries (avoid breaking words). When false, wraps strictly by character count.

The layout pass may override this when the containing styled TC has a word_wrap style — see Self::authored_word_wrap for the authored/default value.

authored_word_wrap: bool

Author-provided word-wrap mode. Preserved when layout applies or removes a style-driven override so the effective word_wrap can be restored.

word_wrap_tokens: Vec<String>

Tokens after which wrapping is allowed when word_wrap == true.

This always includes whitespace tokens (space + tab) by default. The layout pass may override this when the containing styled TC has a word_wrap_tokens style — see Self::authored_word_wrap_tokens.

authored_word_wrap_tokens: Vec<String>

Author-provided word-wrap tokens. Preserved alongside Self::authored_word_wrap for the same reason.

Implementations

impl TextComponent

pub const DEFAULT_FONT_SIZE: f32 = 1.0

pub const DEFAULT_WRAP_AT: usize = 0

Default authored wrap cap: 0 = no author cap. Layout still wraps to fit the containing block; this default just means the author didn’t impose an additional column limit. To set an explicit cap, use with_wrap / with_word_wrap.

pub const DEFAULT_WORD_WRAP_TOKENS: [&'static str; 2]

pub fn new(text: impl Into<String>) -> Self

Examples found in repository

examples/opacity-example.rs (line 54)

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

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

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

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

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

    universe.add(text_root);
}

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(text_root);
}

examples/pointer-events.rs (line 325)

fn spawn_label(
    universe: &mut engine::Universe,
    parent: engine::ecs::ComponentId,
    pos: [f32; 3],
    text: &str,
) {
    use engine::ecs::component::{
        ColorComponent, EmissiveComponent, TextComponent, TextureFilteringComponent,
        TransformComponent, TransparentCutoutComponent,
    };

    let root = universe.world.add_component(
        TransformComponent::new()
            .with_position(pos[0], pos[1], pos[2])
            .with_scale(0.055, 0.055, 1.0),
    );
    let txt = universe.world.add_component(TextComponent::new(text));
    let color = universe
        .world
        .add_component(ColorComponent::rgba(0.05, 0.05, 0.08, 1.0));
    let emissive = universe.world.add_component(EmissiveComponent::on());
    let filtering = universe
        .world
        .add_component(TextureFilteringComponent::nearest_magnification());
    let cutout = universe
        .world
        .add_component(TransparentCutoutComponent::new());

    let _ = universe.attach(parent, root);
    let _ = universe.attach(root, txt);
    let _ = universe.attach(txt, color);
    let _ = universe.attach(txt, emissive);
    let _ = universe.attach(txt, filtering);
    let _ = universe.attach(txt, cutout);
}

examples/router.rs (line 29)

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

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

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

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

examples/text-example.rs (line 129)

    fn spawn_text_style(
        universe: &mut engine::Universe,
        pos: [f32; 3],
        scale: f32,
        text: &str,
        color: [f32; 4],
        shadow: TextShadowComponent,
        filtering: TextureFilteringComponent,
    ) {
        let root = universe.world.add_component(
            TransformComponent::new()
                .with_position(pos[0], pos[1], pos[2])
                .with_scale(scale, scale, 1.0),
        );

        // Color must be an ancestor of the glyph renderables.
        let color_id = universe
            .world
            .add_component(ColorComponent::rgba(color[0], color[1], color[2], color[3]));
        let _ = universe.attach(root, color_id);

        let text_id = universe.world.add_component(TextComponent::new(text));
        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);

        // Use the same atlas as the debug quad.
        let tex = universe
            .world
            .add_component(TextureComponent::with_uri("assets/textures/font.dds"));
        let _ = universe.attach(text_id, tex);

        let shadow_id = universe.world.add_component(shadow);
        let _ = universe.attach(text_id, shadow_id);

        let filtering_id = universe.world.add_component(filtering);
        let _ = universe.attach(text_id, filtering_id);

        universe.add(root);
    }

examples/diy-panel.rs (line 37)

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

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

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

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

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

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

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

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

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

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

Additional examples can be found in:

• examples/scrolling.rs
• examples/font-example.rs
• examples/example_util/mod.rs
• examples/text-animation.rs

pub fn with_wrap(text: impl Into<String>, wrap_at: usize) -> Self

Examples found in repository

examples/folder-text.rs (lines 398-401)

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

pub fn with_word_wrap(text: impl Into<String>, wrap_at: usize) -> Self

Word-wrap (prefer wrapping at whitespace) aiming for wrap_at characters.

If the line exceeds wrap_at and there was no whitespace to wrap at, the line will continue (words are not broken).

Examples found in repository

examples/animation-example.rs (lines 110-112)

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

examples/audio-graph-example.rs (lines 214-216)

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

        // TextSystem looks for an immediate TextureFilteringComponent child.
        let filtering = universe
            .world
            .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
        let _ = universe.attach(t, filtering);

        // TextSystem also supports styling from immediate Emissive children.
        let emissive = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(t, emissive);

        universe.add(tx);
    }

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

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

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

        tx
    }

    // --- HUD / lane (single track) ---
    let lane_x = -2.6_f32;
    let lane_title_z = -0.4_f32;
    let lane_cfg_z = -0.4_f32;
    let lane_pat_z = -1.3_f32;
    let lane_graph_z = -1.15_f32;

    // Content for pattern/chain/graph starts at x=0; keep section labels aligned there.
    // This also keeps them from overlapping the config block (which is anchored at lane_x).
    let lane_labels_x = lane_x + 1.6_f32;

    let track_a_y = 0.9_f32;

    spawn_text(
        &mut universe,
        (lane_x, track_a_y + 0.55, lane_title_z),
        0.09,
        42,
        "Track A: AudioOscillator::square()",
    );
    spawn_text(
        &mut universe,
        (lane_x, track_a_y + 0.25, lane_cfg_z),
        0.07,
        48,
        "oscillators=1\nfrequency_hz=110.0\namplitude=0.12\nenabled=false\nlookahead=0.10s",
    );

    let viz_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    universe.add(viz_root);

    println!("[audio-graph-example] viz root added");

    // Small identifier cubes next to titles.
    spawn_emissive_cube(
        &mut universe,
        viz_root,
        (lane_x - 0.28, track_a_y + 0.55, lane_title_z),
        0.16,
        [0.85, 0.40, 1.00, 1.0],
    );

    // Pattern roots so we can reset via one SetColor action.
    let track_a_pattern_root = universe.world.add_component(
        engine::ecs::component::TransformComponent::new().with_position(0.0, 0.0, 0.0),
    );
    let _ = universe.attach(viz_root, track_a_pattern_root);

    // Labels for pattern/chain/graph sections.
    spawn_text(
        &mut universe,
        (lane_labels_x, track_a_y, lane_title_z),
        0.06,
        42,
        "pattern",
    );
    spawn_text(
        &mut universe,
        (lane_labels_x, track_a_y - 0.40, lane_title_z),
        0.06,
        42,
        "graph",
    );

    // --- Processing chain + graph visualization (compiled graph → cubes + labels) ---
    use engine::ecs::system::audio_graph_compiler::{
        AudioGraphCompiler, AudioGraphNode, AudioGraphNodeKind,
    };

    fn effect_grey_for_depth(depth: usize) -> f32 {
        // depth=1 => medium grey; deeper => lighter, capped.
        let base = 0.55;
        let step = 0.13;
        let d = depth.saturating_sub(1) as f32;
        (base + step * d).min(0.92)
    }

    fn node_rgba(node: &AudioGraphNode, depth: usize) -> [f32; 4] {
        match node.kind {
            AudioGraphNodeKind::OscillatorSource { .. } => [1.0, 0.78, 0.22, 1.0],
            _ => {
                let g = effect_grey_for_depth(depth);
                [g, g, g, 1.0]
            }
        }
    }

    fn node_label(node: &AudioGraphNode) -> String {
        match &node.kind {
            AudioGraphNodeKind::OscillatorSource { voices } => {
                format!("OscillatorSource voices={voices}")
            }
            AudioGraphNodeKind::Gain { gain } => {
                format!("Gain gain={gain:.3}")
            }
            AudioGraphNodeKind::LowPass {
                cutoff_hz,
                resonance,
            } => {
                format!("LowPass cutoff={cutoff_hz:.1}Hz res={resonance:.3}")
            }
            AudioGraphNodeKind::BandPass {
                center_hz,
                bandwidth_octaves,
                resonance,
            } => {
                format!(
                    "BandPass center={center_hz:.1}Hz bw={bandwidth_octaves:.3}oct res={resonance:.3}"
                )
            }
            AudioGraphNodeKind::HighPass {
                cutoff_hz,
                resonance,
            } => {
                format!("HighPass cutoff={cutoff_hz:.1}Hz res={resonance:.3}")
            }
            AudioGraphNodeKind::Limiter {
                attack_ms,
                release_ms,
                threshold,
            } => {
                format!("Limiter atk={attack_ms:.1}ms rel={release_ms:.1}ms thr={threshold:.3}")
            }
            AudioGraphNodeKind::ClipSource => "ClipSource".to_string(),
        }
    }

    fn compute_layout(
        node: &AudioGraphNode,
        depth: usize,
        x_cursor: &mut i32,
        out: &mut std::collections::HashMap<*const AudioGraphNode, (i32, usize)>,
    ) -> i32 {
        // Depth-only layout:
        // - keep children directly below their parent on X
        // - use Z sibling offsets (in spawn_graph_tree) to show branching
        let _ = x_cursor;
        for ch in node.children.iter() {
            let _ = compute_layout(ch, depth + 1, x_cursor, out);
        }

        let my_x = 0;
        out.insert(node as *const AudioGraphNode, (my_x, depth));
        my_x
    }

    fn spawn_graph_tree(
        universe: &mut engine::Universe,
        parent: engine::ecs::ComponentId,
        node: &AudioGraphNode,
        bp_component: Option<engine::ecs::ComponentId>,
        bp_label_out: &mut Option<engine::ecs::ComponentId>,
        origin: (f32, f32, f32),
        layout: &std::collections::HashMap<*const AudioGraphNode, (i32, usize)>,
        dx: f32,
        dy: f32,
        cube_scale: f32,
        sibling_index: usize,
        sibling_count: usize,
    ) {
        let Some((x_unit, depth)) = layout.get(&(node as *const AudioGraphNode)).copied() else {
            return;
        };

        let x = origin.0 + (x_unit as f32) * dx;
        let y = origin.1 - (depth as f32) * dy;

        // Push siblings “behind” each other along Z to reduce overlap between
        // a sibling's cube and another node's label.
        let dz_sibling = 0.18;
        let z = origin.2 - (sibling_index as f32) * dz_sibling;

        // Keep text slightly in front of its cube.
        let z_text = z + 0.03;

        let rgba = node_rgba(node, depth);
        let cube_tx = spawn_op_cube(universe, parent, (x, y, z), cube_scale, rgba);
        let _ = cube_tx;

        // Label next to the cube.
        let label = node_label(node);
        let tx = universe.world.add_component(
            engine::ecs::component::TransformComponent::new()
                .with_position(x + 0.14, y + 0.02, z_text)
                .with_scale(0.06, 0.06, 1.0),
        );
        let t =
            universe
                .world
                .add_component(engine::ecs::component::TextComponent::with_word_wrap(
                    &label, 25,
                ));
        let _ = universe.attach(parent, tx);
        let _ = universe.attach(tx, t);

        if bp_component == Some(node.component) {
            *bp_label_out = Some(t);
        }

        let filtering = universe
            .world
            .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
        let _ = universe.attach(t, filtering);

        let emissive = universe
            .world
            .add_component(engine::ecs::component::EmissiveComponent::on());
        let _ = universe.attach(t, emissive);

        universe.add(tx);

        // Mix/branch label if branching.
        if node.children.len() > 1 {
            let mut weights: Vec<f32> = Vec::with_capacity(node.children.len());
            for i in 0..node.children.len() {
                let w = node
                    .mix
                    .as_ref()
                    .map(|m| m.weights.get(i).copied().unwrap_or(1.0))
                    .unwrap_or(1.0);
                weights.push(w);
            }
            let mix_label = if node.mix.is_some() {
                format!("Mix weights={weights:?}")
            } else {
                format!("Mix <implicit> w={weights:?}")
            };
            let mix_tx = universe.world.add_component(
                engine::ecs::component::TransformComponent::new()
                    .with_position(x + 0.14, y - 0.11, z_text)
                    .with_scale(0.05, 0.05, 1.0),
            );
            let mix_t = universe.world.add_component(
                engine::ecs::component::TextComponent::with_word_wrap(&mix_label, 25),
            );
            let _ = universe.attach(parent, mix_tx);
            let _ = universe.attach(mix_tx, mix_t);

            let filtering = universe
                .world
                .add_component(engine::ecs::component::TextureFilteringComponent::nearest());
            let _ = universe.attach(mix_t, filtering);

            let emissive = universe
                .world
                .add_component(engine::ecs::component::EmissiveComponent::on());
            let _ = universe.attach(mix_t, emissive);

            universe.add(mix_tx);
        }

        let child_count = node.children.len().max(1);
        for (i, ch) in node.children.iter().enumerate() {
            // Each node's children form a sibling group; offset them in Z.
            // For the root node, sibling_index is 0.
            let _ = sibling_count;
            spawn_graph_tree(
                universe,
                parent,
                ch,
                bp_component,
                bp_label_out,
                origin,
                layout,
                dx,
                dy,
                cube_scale,
                i,
                child_count,
            );
        }
    }

examples/button-press.rs (line 388)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    universe.add(button_root);

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

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

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

    button_root
}

pub fn with_word_wrap_tokens<T, I>( text: impl Into<String>, wrap_at: usize, tokens: I, ) -> Self

where I: IntoIterator<Item = T>, T: Into<String>,

Word-wrap (prefer wrapping at whitespace / tokens) aiming for wrap_at characters.

tokens are additional “wrap-allowed-after” sequences (e.g. “::”, “.”, “,”). Whitespace tokens (space + tab) are always included.

Examples found in repository

examples/mesh-factory-example.rs (lines 130-134)

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

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

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

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

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

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

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

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

        universe.add(root);

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

pub fn with_font_size(self, font_size: f32) -> Self

pub fn set_font_size(&mut self, font_size: f32)

pub fn set_effective_font_size(&mut self, font_size: f32)

Trait Implementations

impl Clone for TextComponent

fn clone(&self) -> TextComponent

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Component for TextComponent

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

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

fn set_id(&mut self, component: ComponentId)

fn as_any(&self) -> &dyn Any

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

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

Called when component is added to the World

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

Encode this component as an MMS Component Expression AST node.

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

Called when component is removed from the World.

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

Encode component data to a HashMap for serialization.

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

Decode component data from a HashMap after deserialization.

impl Debug for TextComponent

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

Formats the value using the given formatter.