Unity Text Tmp

Unity Text (TextMeshPro / TextCore)

Retrieval Sources

Confirmed gap, verified with multiple find globs on this pass: the local ScriptReference/ has zero pages under the TMPro namespace — no TMP_Text, TMP_FontAsset, TextMeshProUGUI, TextMeshPro (the 3D component), TMP_InputField, TMP_Dropdown, TMP_StyleSheet, etc. anywhere (checked TMPro*.html and a plain TextMeshPro*.html glob — zero hits for both). This mirrors the unity-ui skill's finding that UnityEngine.UI (uGUI) has no local API pages either: this documentation snapshot only ships the built-in-module ScriptReference, not the com.unity.textmeshpro/com.unity.ugui package API reference, which Unity hosts on a separate package-docs site. For TMP_Text/TMP_FontAsset/TextMeshProUGUI member-level API, state plainly that local docs don't cover them and fall back to general knowledge, flagged as unverified against local sources. What is fully covered locally, and verified against real files, is (1) UnityEngine.TextCore.* — the engine-level namespace TextMeshPro itself is built on, which Unity folded into the engine starting in 2021 — 133 ScriptReference pages; (2) UI Toolkit's own text system, which the docs state outright renders through TextCore and is explicitly "based on TextMesh Pro" (Manual/UIE-get-started-with-text.html); and (3) the legacy pre-TMP text APIs (Font, TextMesh, TextGenerator) that TMP superseded and that some projects/asset-store code still reference. Every path below was verified with find/grep against /media/artiq/FRESH_DRIVE/Books/Unity6/Documentation/en/ on this pass.

Key Guidelines

TMP_Text Component Basics — TextMeshPro vs TextMeshProUGUI vs UI Toolkit Text

TextMeshPro ships as three different entry points that all sit on top of the same TextCore rendering engine, and picking the right one depends entirely on which UI system the surrounding screen already uses. TextMeshPro (the component, not the package) is the world-space/3D flavor — it renders onto a MeshRenderer in the scene like the legacy TextMesh it replaces, and is the right choice for floating damage numbers, name tags, or signage. TextMeshProUGUI is the uGUI flavor — it derives from Graphic the same way Image/RawImage do, lives on a RectTransform inside a Canvas, and is what you drop into a uGUI-based HUD or menu in place of the legacy Text component. Neither of these two components has local ScriptReference coverage in this doc set (see Retrieval Sources gap note), so exact member names/signatures for TMP_Text, TMP_FontAsset, TMP_InputField, etc. should be treated as general knowledge, not doc-grounded fact. The third entry point is UI Toolkit's own text system — Label, TextField, and any custom TextElement subclass — which is not TextMeshPro at all as a component, but is built on the same underlying TextCore namespace and, per Manual/UIE-get-started-with-text.html, is explicitly described as "a technology based on TextMesh Pro." Practically: if the screen is uGUI, use TextMeshProUGUI; if it's UI Toolkit, use Label/TextField/TextElement; if it's world-space 3D, use the TextMeshPro component. Don't mix a uGUI TextMeshProUGUI and a UI Toolkit Label on the same screen expecting shared styling — their font-asset formats, rich-text tag sets, and USS-vs-Inspector styling pipelines are similar in spirit but are two separate implementations layered over TextCore, not one shared component.

using UnityEngine;
using UnityEngine.UIElements;

// UI Toolkit: TextElement-derived controls are the closest local-docs-grounded
// equivalent to configuring a TMP_Text instance from script.
public class UitkTextExample : MonoBehaviour
{
    void OnEnable()
    {
        var root = GetComponent<UIDocument>().rootVisualElement;

        var label = new Label("Hello World")
        {
            style =
            {
                fontSize = 14,
                unityFontStyleAndWeight = FontStyle.Bold,
                unityTextAlign = TextAnchor.MiddleCenter,
                color = Color.red,
            }
        };
        label.enableRichText = true; // TextElement property, ScriptReference/UIElements.TextElement-enableRichText.html

        root.Add(label);
    }
}

// uGUI/world-space TextMeshPro members below are NOT locally doc-grounded —
// shown for contrast only, per general TMP knowledge:
// TextMeshProUGUI tmp = GetComponent<TextMeshProUGUI>();
// tmp.text = "Hello World";
// tmp.fontSize = 36;
// tmp.color = Color.red;

Font Assets & Atlas Generation

A font asset is a container wrapping a source font file (.ttf/.otf/.ttc, i.e. a UnityEngine.Font) plus a generated atlas texture holding rasterized glyph images and per-glyph metrics (TextCore.Glyph/TextCore.GlyphMetrics/TextCore.GlyphRect). Per Manual/UIE-font-asset.html, three Atlas Population Modes control when glyphs get baked in: Static pre-bakes a fixed character set at creation time (fast, no source font file needed at build time, but any missing character never appears — use for known/finite text like UI labels); Dynamic starts with an empty atlas and adds glyphs the first time each character is actually rendered (flexible for unpredictable text like chat/input fields, but the source font file must ship in the build and there's a first-use hitch as new atlas regions get baked); Dynamic OS is a dynamic asset that pulls glyphs from a font installed on the runtime operating system instead of a font file bundled in the project — lowest memory footprint, no font file to ship, but only works if the target OS actually has that font installed, which makes it a poor primary choice but a great fallback candidate. Separately, the Atlas Render Mode picks bitmap vs. SDF: bitmap modes (SMOOTH, SMOOTH_HINTED, RASTER, RASTER_HINTED, COLOR, COLOR_HINTED) bake fixed-resolution glyph images best suited to pixel art where 1:1 pixel alignment matters; SDF modes (SDF, SDF8/16/32, SDFAA, SDFAA_HINTED) bake a signed-distance-field gradient per glyph that stays crisp at any scale/rotation and unlocks shader-driven effects (outline, shadow, glow) without needing separate baked variants — SDF is the default choice for UI text that gets resized, animated, or viewed at varying camera distance. The actual atlas-baking work happens through TextCore.LowLevel.FontEngine (LoadFontFace, SetFaceSize, TryGetGlyphIndex, packed via GlyphPackingMode), which is the FreeType-backed engine the Font Asset Creator window calls into — you rarely call it directly, but its error enum (FontEngineError) is what surfaces as atlas-generation failures in the Inspector.

using UnityEngine;
using UnityEngine.TextCore.LowLevel;

// Illustrates the low-level TextCore.LowLevel.FontEngine API that backs the
// Font Asset Creator's "Generate Font Atlas" button — real, locally-documented API.
public static class FontAtlasProbe
{
    public static void PrintGlyphAvailability(Font sourceFont, string testCharacters)
    {
        FontEngineError initResult = FontEngine.InitializeFontEngine();
        if (initResult != FontEngineError.Success)
        {
            Debug.LogError($"FontEngine init failed: {initResult}");
            return;
        }

        FontEngine.LoadFontFace(sourceFont, 90); // 90pt sampling size
        foreach (char c in testCharacters)
        {
            bool found = FontEngine.TryGetGlyphWithUnicodeValue(
                c, GlyphLoadFlags.LOAD_NO_BITMAP, out Glyph glyph);
            Debug.Log(found
                ? $"'{c}' -> glyph index {glyph.index}, advance {glyph.metrics.horizontalAdvance}"
                : $"'{c}' missing from font face");
        }

        FontEngine.DestroyFontEngine();
    }
}

Rich Text Tags

Rich text tags style a substring within one text string using an HTML/XML-like syntax that Unity's text renderers parse at layout time — <b>bold</b>, <color="red">red text</color>, <size=150%>bigger</size>. Per Manual/ui-systems/introduction-to-rich-text-tags.html, a tag's scope by default runs from where it appears to the end of the string; an explicit closing tag (</color>) narrows that scope to just the enclosed text, and tags can nest without needing to close in the same order they opened. If the same tag type appears twice without a closing tag between them, the second instance overrides the first for everything after it — a common source of "why didn't my color change back" confusion. The full supported-tag table (Manual/UIE-supported-tags.html) covers formatting (<b>, <i>, <s> strikethrough equivalents), color/appearance (<color>, <alpha>, <gradient>, <mark>), layout (<align>, <indent>, <br>, <pos>), typography (<font>, <font-weight>, <cspace> character spacing), casing (<allcaps>), and interactive/embedded content (<a href="...">/<link=ID> for hyperlinks, <sprite index=N> for inline sprites/emoji). Attribute values accept several unit types in the same tag family — decimals, percentages, pixel values (5px), font-relative em units (1.5em), and hex color (#FFFFFF RGB or #FFFFFFFF RGBA) — so <cspace=1em> and <cspace=5px> are both valid but mean different things at different font sizes. Rich text is enabled by default on text elements that support it and can be disabled per-element (clear "Enable Rich Text" in the Inspector, or enable-rich-text="false" in UXML / enableRichText = false in C#) — disable it for any string built from untrusted/user-supplied input unless you've sanitized it, since an unescaped < from user text will otherwise be parsed as a tag.

using UnityEngine;
using UnityEngine.UIElements;

public class RichTextExample : MonoBehaviour
{
    void OnEnable()
    {
        var label = new Label();
        label.enableRichText = true;

        // Nested + closed scope: only "mostly" is green, rest of the line is red.
        label.text = "<color=red>This text is <color=green>mostly </color>red</color>";

        // Sprite + gradient + hyperlink combined in one string.
        label.text += "\n<gradient=\"Light to Dark Green - Vertical\">Gradient text</gradient> " +
                      "<sprite index=3> <a href=\"https://unity.com\">Visit Unity!</a>";

        GetComponent<UIDocument>().rootVisualElement.Add(label);
    }
}

Runtime Text Manipulation from Script

The UI Toolkit-side, locally-documented pattern for touching text at runtime is TextElement's text property plus MeasureTextSize/MarkDirtyText for layout queries and forced re-render (ScriptReference/UIElements.TextElement.html). For per-character/per-glyph effects — fading in letters, a wave animation, rainbow-cycling colors per character — the relevant API is TextElement.PostProcessTextVertices, an Action<GlyphsEnumerable> callback UI Toolkit invokes immediately before it renders each glyph's mesh; the callback receives a GlyphsEnumerable you iterate to reach individual Glyph structs and mutate their vertices (position/UV/tint) before the frame renders (Manual/ui-systems/create-custom-text-animation.html walks a complete fade example). This is analogous in spirit to TMP_Text's (not locally documented) textInfo.characterInfo[]/ForceMeshUpdate() per-character mesh access pattern that TextMeshPro is well known for in uGUI/3D contexts — same idea (grab per-character vertex data, mutate it, push it back before render), different concrete API surface depending on which text system you're in. For editable text (TextField/TextInputBaseField_1), script-driven changes to value/text should go through SetValueWithoutNotify when you don't want to re-trigger the field's own change-event listeners (e.g. syncing a display field from a data model), and cursor/selection state is scriptable via cursorIndex, selectIndex, and SelectRange/SelectAll/SelectNone.

using UnityEngine;
using UnityEngine.UIElements;

public class GlyphFadeAnimator : MonoBehaviour
{
    [SerializeField] private float fadeDuration = 1f;
    private TextElement target;
    private float elapsed;

    void OnEnable()
    {
        target = GetComponent<UIDocument>().rootVisualElement.Q<TextElement>("AnimatedLabel");
        target.experimental.animation.Start(); // schedule pattern per Manual/ui-systems/create-custom-text-animation.html
        target.generateVisualContent += _ => { }; // ensure repaint is scheduled elsewhere in real code
        target.RegisterCallback<AttachToPanelEvent>(_ =>
            target.schedule.Execute(Tick).Every(16));
    }

    void Tick()
    {
        elapsed += 0.016f;
        float t = Mathf.Clamp01(elapsed / fadeDuration);

        target.PostProcessTextVertices = glyphs =>
        {
            foreach (var glyph in glyphs)
            {
                var v = glyph.vertices;
                for (int i = 0; i < v.Length; i++)
                {
                    var c = v[i].tint;
                    c.a = t;
                    v[i].tint = c;
                }
            }
        };
        target.MarkDirtyText(); // force glyph rebuild so PostProcessTextVertices reruns
    }
}

Localization-Friendly Text Sizing & Overflow

Translated strings routinely run 30-200% longer than their English source (German UI labels are a classic example), so hard-coded font sizes and fixed-width containers that "just fit" the English string will clip or overflow once localized. Two complementary, locally-documented tools address this. Auto Sizing / Best Fit (ScriptReference/UIElements.TextAutoSize.html, -mode/-minSize/-maxSize, driven by TextAutoSizeMode.BestFit) lets a text element shrink its rendered font size within a defined range to keep a translated string on one line/within its box, combined with word wrap, ellipsis truncation, and left/center/right alignment support — set via UI Builder (Text > Auto Size), USS (-unity-text-auto-size: best-fit <min> <max>), or C#. Text Overflow (ScriptReference/UIElements.TextOverflow.html: Clip vs Ellipsis, paired with ScriptReference/UIElements.TextOverflowPosition.html: Start/Middle/End) controls what happens when a string still doesn't fit even at minimum auto-size — Clip hard-cuts at the box edge, Ellipsis truncates with … at the configured position. For right-to-left languages (Arabic, Hebrew), language-direction/LanguageDirection (Manual/ui-systems/language-direction.html) needs to be set explicitly per element or inherited from a root — the attribute only gives basic text-reversal RTL support on its own; full line-breaking, word-wrapping, and text-shaping correctness for RTL/complex scripts requires enabling the Advanced Text Generator (Manual/ui-systems/enable-and-use-atg.html), which is Harfbuzz/ICU/FreeType-backed and off by default. Never assume a font size or fixed pixel width tuned against English text will hold for German, Finnish, or Arabic without auto-size, overflow handling, and (for RTL) explicit direction plus ATG in the mix.

using UnityEngine;
using UnityEngine.UIElements;

public class LocalizedLabelSetup : MonoBehaviour
{
    void OnEnable()
    {
        var label = new Label("Hello") { name = "TitleLabel" };
        label.style.unityTextOverflowPosition = TextOverflowPosition.End;
        label.style.textOverflow = TextOverflow.Ellipsis;
        label.style.overflow = Overflow.Hidden; // required for textOverflow to take effect
        // Auto-size range is typically set via USS (-unity-text-auto-size: best-fit 12px 24px;)
        // rather than a single scriptable field on style directly.

        GetComponent<UIDocument>().rootVisualElement.Add(label);
    }
}

Performance: Text Rebuild Cost, Static vs. Dynamic Text

Every text mesh rebuild — triggered by changing .text, resizing the container, or a font-size auto-size pass — re-runs layout (line breaking, glyph positioning, rich-text tag parsing) and regenerates vertex/UV/color buffers for every visible character. For text that changes every frame (a live FPS counter, a countdown timer with sub-second precision), that's a real per-frame cost multiplied by however many glyphs are on screen; prefer changing only the substring that actually changed when the API allows it, or throttle updates (e.g. update a timer display at 10 Hz instead of 60 Hz) rather than reformatting the entire string every Update. Atlas population mode has its own performance profile: Static font assets have zero runtime atlas-mutation cost (everything is pre-baked) at the price of build-time inflexibility; Dynamic font assets pay a one-time cost the first time each new character is encountered (an atlas-texture upload + repack), which is invisible for pre-warmed common text but can cause a visible micro-stutter the first time an unusual/rare character (e.g. an uncommon CJK glyph or emoji) appears in unpredictable text like chat; Dynamic OS avoids shipping font data in the build but adds OS-font-lookup overhead and zero guarantee the glyph exists on every target device. Multiple sprite atlases referenced by the same text block increase draw calls (Manual/UIE-sprite.html explicitly recommends packing sprites used in text into one atlas), and a long fallback-font chain adds per-missing-glyph search cost plus additional draw calls each time a fallback font actually gets used (Manual/UIE-fallback-font.html) — both are classic "invisible until you profile it" costs that scale with how much text-with-mixed-fonts a screen actually shows. As a general rule: pre-warm Dynamic font asset atlases with the expected character set at load time (rendering an off-screen string containing likely characters once) rather than taking the hitch mid-gameplay the first time a player-typed or streamed string introduces a new glyph.

using UnityEngine;
using UnityEngine.UIElements;

public class TimerDisplay : MonoBehaviour
{
    [SerializeField] private float updateIntervalSeconds = 0.1f; // 10 Hz, not every frame
    private Label timerLabel;
    private float elapsed;
    private float remaining = 60f;

    void OnEnable() => timerLabel = GetComponent<UIDocument>().rootVisualElement.Q<Label>("Timer");

    void Update()
    {
        remaining -= Time.deltaTime;
        elapsed += Time.deltaTime;
        if (elapsed < updateIntervalSeconds) return; // throttle text rebuilds
        elapsed = 0f;
        timerLabel.text = Mathf.CeilToInt(Mathf.Max(0, remaining)).ToString(); // only rebuild when the displayed value actually changes
    }
}

Common Mistakes

Quick Reference

…(truncated)