/textmeshpro

name: textmeshpro
description: "TextMeshPro text rendering — font asset creation, material presets, rich text tags, dynamic font fallback, sprite assets in text. Use for all text rendering in Unity."
globs: ["**/TMP_*.cs", "**/TextMesh*.cs", "**/*Text*.cs", "**/*.asset"]

TextMeshPro — Advanced Text Rendering for Unity

TextMeshPro (TMP) is Unity's standard text solution, replacing the legacy Text component. It uses Signed Distance Field (SDF) rendering for resolution-independent, crisp text with support for rich text, outlines, shadows, and inline sprites.

Component Types

| Component | Use Case | Namespace | |-----------|----------|-----------| | `TextMeshProUGUI` | Canvas UI text (most common) | `TMPro` | | `TextMeshPro` | World-space 3D text (signs, name plates) | `TMPro` |

using TMPro;

[SerializeField] private TextMeshProUGUI _uiText;     // Canvas text
[SerializeField] private TextMeshPro _worldText;       // 3D world text

Font Asset Creation

Font assets are created from TTF/OTF font files via the Font Asset Creator window.

Steps

1. **Window > TextMeshPro > Font Asset Creator** 2. Set **Source Font File** to your TTF/OTF font 3. Configure settings:

• **Sampling Point Size**: Auto or specific (e.g., 64)
• **Padding**: 5-9 (higher = better outlines/shadows but larger atlas)
• **Packing Method**: Optimum
• **Atlas Resolution**: 512x512 for small character sets, 2048x2048+ for CJK
• **Character Set**: ASCII for English, Unicode Range for specific sets, Custom Characters for exact glyphs
• **Render Mode**: SDFAA (default, best quality)

4. Click **Generate Font Atlas**, then **Save**

SDF Rendering Modes

| Mode | Quality | Use Case | |------|---------|----------| | SDFAA | Best | Default for most fonts | | SDF | Good | Slightly faster rendering | | SDFAA_HINTED | Best + hinting | Small text sizes, pixel-perfect | | Raster | Bitmap | Pixel art fonts only |

Material Presets

Material presets add visual effects (outline, shadow, glow) without modifying the base font asset.

Creating a Material Preset

1. Select the font asset in Project window 2. In Inspector, click the material field to see the base material 3. Right-click the font asset > **Create > Material Preset** 4. Adjust properties on the new material:

• **Face**: Color, softness, dilate
• **Outline**: Color, thickness
• **Underlay** (shadow): Color, offset, dilate, softness
• **Lighting**: Bevel for 3D effect
• **Glow**: Inner/outer glow

Applying Material Presets in Code

[SerializeField] private Material _damageMaterial;  // Red outline preset
[SerializeField] private Material _defaultMaterial;

public void ShowDamageText()
{
    _uiText.fontSharedMaterial = _damageMaterial;
}

public void ResetTextAppearance()
{
    _uiText.fontSharedMaterial = _defaultMaterial;
}

**Important**: Use `fontSharedMaterial` (shared, no allocation) instead of `fontMaterial` (creates instance, allocates).

Rich Text Tags

TMP supports extensive rich text markup within text strings.

Basic Formatting

<b>Bold text</b>
<i>Italic text</i>
<u>Underline</u>
<s>Strikethrough</s>
<mark=#FFFF0044>Highlighted</mark>
<sup>Superscript</sup>
<sub>Subscript</sub>

Color and Size

<color=#FF0000>Red</color>
<color="red">Named red</color>
<color=#FF000088>Semi-transparent red</color>
<size=24>Larger text</size>
<size=+10>Relative larger</size>
<size=-4>Relative smaller</size>

Alignment and Spacing

<align="center">Centered text</align>
<align="left">Left aligned</align>
<align="right">Right aligned</align>
<cspace=5>Character spacing</cspace>
<line-height=150%>Taller lines</line-height>
<indent=20>Indented text</indent>
<margin=10>Text with margin</margin>
<mspace=0.5em>Monospaced</mspace>

Inline Sprites

Coins: <sprite name="coin"> x 100
Health: <sprite name="heart" tint=1>
<sprite index=0>  (by index in sprite asset)

Links

Click <link="store">here</link> to open the store.
Visit <link="https://example.com">our site</link>.

Other Tags

<font="OtherFontAsset">Different font</font>
<gradient="GradientPreset">Gradient text</gradient>
<rotate=15>Rotated</rotate>
<voffset=10>Vertical offset</voffset>
<width=50%>Constrained width</width>
<nobr>No line break here</nobr>
<page>Page break (for multi-page)</page>

Dynamic Font Fallback

Chain font assets so missing characters fall through to other fonts. Essential for multi-language support.

Setup

1. Select your primary font asset 2. In Inspector, expand **Fallback Font Asset List** 3. Add fallback fonts in priority order:

• Primary: LatinFont (English, European)
• Fallback 1: CJKFont (Chinese, Japanese, Korean)
• Fallback 2: ArabicFont
• Fallback 3: EmojiFont

TMP automatically searches fallback fonts when a glyph is not found in the primary font.

Global Fallback (TMP Settings)

1. **Edit > Project Settings > TextMesh Pro > Settings** 2. Add fonts to **Fallback Font Assets** list 3. These apply to ALL TMP text components as a last resort

Sprite Assets

Embed icons, emojis, or custom images inline with text.

Creating a Sprite Asset

1. Create a sprite sheet texture (atlas of icons) 2. **Right-click texture > Create > TextMeshPro > Sprite Asset** 3. Define sprite regions in the Sprite Asset inspector 4. Name each sprite for easy reference

Usage

// In text strings
_uiText.text = "Gold: <sprite name=\"coin\"> 500";

// With tinting (inherits text color)
_uiText.text = "<sprite name=\"heart\" tint=1>";

Code Access Patterns

Setting Text Efficiently

[SerializeField] private TextMeshProUGUI _scoreText;
[SerializeField] private TextMeshProUGUI _timerText;

// GOOD — SetText with format args avoids string allocation
_scoreText.SetText("Score: {0}", score);
_timerText.SetText("{0}:{1:00}", minutes, seconds);

// GOOD — SetText with float formatting
_scoreText.SetText("DPS: {0:2}