TextMeshProMax

<img src="Documentation~/Images/logo.png" alt="How to enable xml comments" width="700" />

TextMeshProMax is a utility library that extends TextMesh Pro, making it easier to perform advanced text-related tasks in Unity projects. It supports standard TextMesh Pro functionalities and optional RubyTextMeshPro integration.

---

Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update --> <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

Details

• Roadmap
• How to Install
  • 1. Install via OpenUPM
    • 1.1. Install via Package Manager
    • 1.2. Alternatively, merge the snippet to Packages/manifest.json
    • 1.3. Install via command-line interface
  • 2. Install via Git URL
• Features
  • Helper Features
    • 1. GetStringRects
      • Code Example
    • 1.1 TryGetStringRects
      • Code Example
    • 2. GetRubyStringRects (Requires RubyTextMeshPro)
      • Parameters
      • Returns
      • Code Example
    • 2.1 TryGetRubyStringRects (Requires RubyTextMeshPro)
    • 3. Multi-Line Support
      • Example:
• Tools
  • TMP Font Batch Changer
    • How to Use
    • Key Features
  • CJK Font Atlas Generator
    • How to Use
    • Why Use This Tool?
    • Language Options
    • CJK Options
    • Detailed Options and Usage
      • Korean
      • Japanese
      • Chinese
    • CJK Options
• Contributing
  • Requesting New Features
• License

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Roadmap

You can find the roadmap for this project in the Roadmap section.

How to Install

1. Install via OpenUPM

1.1. Install via Package Manager

Please follow the instrustions:

• open Edit/Project Settings/Package Manager
• add a new Scoped Registry (or edit the existing OpenUPM entry)
  • Name: package.openupm.com
  • URL: https://package.openupm.com
• click Save or Apply
• open Window/Package Manager
• click +
• select Add package by name... or Add package from git URL...
• paste com.kwanjoong.textmeshpromax into name
• paste version (e.g.0.5.2) into version
• click Add

---

1.2. Alternatively, merge the snippet to Packages/manifest.json

{
  "scopedRegistries": [
    {
      "name": "package.openupm.com",
      "url": "https://package.openupm.com",
      "scopes": []
    }
  ],
  "dependencies": {
    "com.kwanjoong.textmeshpromax": "0.5.2" // Please use the latest version
  }
}

1.3. Install via command-line interface

openupm add com.kwanjoong.textmeshpromax

2. Install via Git URL

1. Open package manager from Unity Editor

• Window -> Package Manager -> + button on top left -> Add package from git URL

2. Copy and paste this url

• https://github.com/kwan3854/TextMeshProMax.git
• If you need specific version, you can specify like this https://github.com/kwan3854/TextMeshProMax.git#v0.6.0

[!TIP] You can see inline comments in the code editor by enabling this option in the Unity Editor: Edit -> Preferences -> External Tools -> Generate .csproj files <img src="Documentation~/Images/xml_settings.png" alt="How to enable xml comments" width="700" />

Features

Helper Features

1. GetStringRects

Retrieve the Rect information for specific strings rendered by a TMP_Text object.

<img src="Documentation~/Images/GetStringRects.png" alt="How to enable xml comments" width="700" /> <img src="Documentation~/Images/GetStringRectsResult.png" alt="How to enable xml comments" width="700" />

• Parameters:
  • text (TMP_Text): The target TextMesh Pro object.
  • targetString (string): The string you want to locate in the text.
  • findMode (TextFindMode):
    • TextFindMode.First: Returns the first occurrence.
    • TextFindMode.All: Returns all occurrences.
• Returns:
  • A list of TextRectInfo containing Rects and the TargetString.

[!IMPORTANT] Coordinate System The returned Rect values are in the local space of the text object's transform.

Breaking Change Notice: In versions prior to 0.6.0, the Rect for TextMeshProUGUI was returned in the Canvas's local space. This has been changed to consistently use the text object's local space for all TMP_Text types. Please update your implementation accordingly.

Code Example

using Runtime.Helper;
using TMPro;
using UnityEngine;

public class TMPExample : MonoBehaviour
{
    private TMP_Text _text;

    void Start()
    {
        // Initialize TMP_Text
        _text = GetComponent<TMP_Text>();
        _text.text = "Hello World\nHello Universe";

        // Retrieve Rect information for all occurrences of "Hello"
        var rects = _text.GetStringRects("Hello", TextFindMode.All);

        foreach (var rectInfo in rects)
        {
            foreach (var rect in rectInfo.Rects)
            {
                Debug.Log($"BottomLeft: {rect.min}, TopRight: {rect.max}, String: {rectInfo.TargetString}");
            }
        }
    }
}

// Works on any tmp: TMP_Text, TextMeshPro, TextMeshProUGUI
TMP_Text text;
TextMeshPro text;
TextMeshProUGUI text;

text.text = "Hello World\nHello Universe";
var rects = text.GetStringRects(rubyString, TextFindMode.All);

1.1 TryGetStringRects

Attempt to retrieve the Rect information for specific strings rendered by a TMP_Text object. Returns true if successful, false otherwise.

• Parameters:
  • Same as GetStringRects.
  • Adds out results (List<TextRectInfo>).
• Returns:
  • bool: true if successful.

[!IMPORTANT] Coordinate System The returned Rect values are in the local space of the text object's transform.

Breaking Change Notice: In versions prior to 0.6.0, the Rect for TextMeshProUGUI was returned in the Canvas's local space. This has been changed to consistently use the text object's local space for all TMP_Text types. Please update your implementation accordingly.

Code Example

List<TextRectInfo> results;
if (text.TryGetStringRects("Hello", TextFindMode.All, out results))
{
    foreach (var rect in results)
    {
        Debug.Log("Rect Found: " + rect);
    }
}

2. GetRubyStringRects (Requires RubyTextMeshPro)

Retrieve Rect information for Ruby strings, including body and Ruby text.

Parameters

• rubyText (RubyTextMeshProUGUI or RubyTextMeshPro): The target RubyTextMeshProUGUI object.
• rubyString (RubyString): A collection of RubyElement entries combining Ruby, body, and plain text.
• findMode(TextFindMode):
  • TextFindMode.First: Returns the first occurrence of the Ruby string.
  • TextFindMode.All: Returns all occurrences of the Ruby string.

Returns

• A list of TextRectInfoobjects, each containing:
  • Rects: A list of Rect objects for the string or line.
  • TargetString: The concatenated plain text of the Ruby string.

[!IMPORTANT] Coordinate System The returned Rect values are in the local space of the text object's transform.

Breaking Change Notice: In versions prior to 0.6.0, the Rect for TextMeshProUGUI was returned in the Canvas's local space. This has been changed to consistently use the text object's local space for all TMP_Text types. Please update your implementation accordingly.

Code Example

using Runtime.Helper;
using TMPro;
using UnityEngine;

public class RubyTMPExample : MonoBehaviour
{
    private RubyTextMeshProUGUI _text;

    void Start()
    {
        // Initialize RubyTextMeshProUGUI
        _text = GetComponent<RubyTextMeshProUGUI>();
        _text.uneditedText = "<r=domo>Hello</r> <r=sekai>World</r> This is normal text!";

        // Parse RubyTextMeshPro's plain text
        Debug.Log($"PlainText: {_text.GetParsedText()}");

        // Create RubyString
        var rubyString = new RubyString(new List<RubyElement>
        {
            new RubyElement("Hello", "domo"),
            new RubyElement(" "), // Space
            new RubyElement("World", "sekai"),
            new RubyElement(" This is normal text!") // Plain text
        });

        // Retrieve Rect information
        var rects = _text.GetRubyStringRects(rubyString, TextFindMode.All);

        foreach (var rectInfo in rects)
        {
            foreach (var rect in rectInfo.Rects)
            {
                Debug.Log($"BottomLeft: {rect.min}, TopRight: {rect.max}, String: {rectInfo.TargetString}");
            }
        }
    }
}

// Works on both RubyTextMeshPro(3D text) and RubyTextMeshProUGUI(2D UI text)
RubyTextMeshProUGUI text;
RubyTextMeshPro text;

text.uneditedText = "<r=domo>Hello</r> <r=sekai>World</r> This is normal