Class TMPUtil

Provides utility methods for TextMeshPro (TMP) operations including component creation, text measurement, line-count calculation, and configuration helpers.

Inheritance

object

TMPUtil

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.UI

Assembly: ScyllaCore.dll

Syntax

public static class TMPUtil

Remarks

The measurement methods (GetWrappedLineCount(TMP_Text, string, float), GetTextHeight(TMP_Text, string, float), GetWrappedLineSegments(TMP_Text, string, float)) work by temporarily modifying a dedicated measurement component's state, calling TMP's layout engine, then restoring the original state. This avoids allocating a new TMP component on every measurement.

A lightweight re-entrance guard is maintained via _activeMeasurementComponent. Only re-entrant calls that use the exact same component instance are blocked; different components (e.g. from different ScrollTextArea instances) can measure concurrently without interference.

Use CreateMeasurementComponent(Transform, TMP_FontAsset, float) to create a dedicated hidden TMP component for use with the measurement methods.

Methods

Attach(GameObject, TMP_FontAsset, float, Color?)

Gets or adds a TextMeshProUGUI component on the specified GameObject (via Require(GameObject)), then configures it with the given font, size, and color.

Declaration

public static TextMeshProUGUI Attach(GameObject gameObject, TMP_FontAsset font, float fontSize, Color? color = null)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to configure.
TMP_FontAsset	font	The TMP_FontAsset to assign. When null, the component's existing font is left unchanged.
float	fontSize	The font size in points.
Color?	color	Optional text color. Defaults to Color.white when not provided.

Returns

Type	Description
TextMeshProUGUI	The configured TextMeshProUGUI component; null if gameObject is null.

Clear(TMP_Text)

Sets the text content of the given TMP_Text component to an empty string. Null-safe: does nothing if text is null.

Declaration

public static void Clear(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component to clear.

Configure(TMP_Text, TMPSettings)

Applies a TMPSettings preset to an existing TMP_Text component. This is a null-safe wrapper around TMPSettings.ApplyTo.

Declaration

public static void Configure(TMP_Text text, TMPSettings settings)

Parameters

Type	Name	Description
TMP_Text	text	The text component to configure. When null the call is a no-op.
TMPSettings	settings	The settings to apply. When null the call is a no-op.

Create(GameObject)

Adds a new TextMeshProUGUI component to the specified GameObject using TMP's default settings. Use the overload that accepts TMPSettings to apply custom configuration in a single call.

Declaration

public static TextMeshProUGUI Create(GameObject gameObject)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to add the component to.

Returns

Type	Description
TextMeshProUGUI	The newly added TextMeshProUGUI component; null if gameObject is null.

Create(GameObject, TMPSettings)

Adds a new TextMeshProUGUI component to the specified GameObject and immediately applies the given TMPSettings via TMPSettings.ApplyTo.

Declaration

public static TextMeshProUGUI Create(GameObject gameObject, TMPSettings settings)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to add the component to.
TMPSettings	settings	The settings to apply. When null the component is still created but no settings are applied (TMP defaults are used).

Returns

Type	Description
TextMeshProUGUI	The newly added TextMeshProUGUI component; null if gameObject is null.

CreateMeasurementComponent(Transform, TMP_FontAsset, float)

Creates a hidden TextMeshProUGUI component suitable for use as a dedicated measurement target with GetWrappedLineCount(TMP_Text, string, float), GetTextHeight(TMP_Text, string, float), and GetWrappedLineSegments(TMP_Text, string, float).

Declaration

public static TextMeshProUGUI CreateMeasurementComponent(Transform parent, TMP_FontAsset font, float fontSize)

Parameters

Type	Name	Description
Transform	parent	The parent transform under which to create the hidden object.
TMP_FontAsset	font	The TMP_FontAsset to assign. Measurements are only accurate when this matches the font used by the display component.
float	fontSize	The font size in points. Must match the display component's font size.

Returns

Type	Description
TextMeshProUGUI	The newly created measurement component; null if parent is null.

Remarks

The GameObject is named "_TMPMeasurement" and created with HideFlags.HideAndDontSave so it does not appear in the hierarchy or persist across play-mode sessions.

The component is initialized with word wrap enabled, overflow set to Overflow, rich text enabled, and alpha set to 0 so it is invisible but still processed by TMP's layout engine. The rect height is pre-sized to Scylla.Core.Util.UI.TMPUtil.MEASUREMENT_HEIGHT to accommodate large wrapped content.

ForceUpdate(TMP_Text)

Forces an immediate mesh rebuild on the given TMP_Text component by calling ForceMeshUpdate. Use this after programmatically modifying text content or layout properties when the mesh must be up-to-date within the same frame. Null-safe: does nothing if text is null.

Declaration

public static void ForceUpdate(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component to update.

GetLineHeight(TMP_Text)

Returns the effective line height (in pixels) for the given TMP_Text component using the font-metric formula. This is a quick estimate; for sub-pixel accuracy prefer the measurement-based approach used internally by ScrollTextArea (two-text-height subtraction). Delegates to TryGetLineHeight(TMP_Text, out float).

Declaration

public static float GetLineHeight(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component whose font metrics to read.

Returns

Type	Description
float	The estimated line height in pixels; float.NaN if text is null, has no font, or the font's point size is zero or negative.

GetPreferredHeight(TMP_Text)

Returns the preferred render height for the current text content of the component, as reported by TMP_Text.GetPreferredValues. This accounts for line count and line spacing at the component's current font size.

Declaration

public static float GetPreferredHeight(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component to query.

Returns

Type	Description
float	The preferred content height in pixels; 0 if text is null.

GetPreferredSize(TMP_Text)

Returns the preferred render size (width and height) for the current text content of the component, as reported by TMP_Text.GetPreferredValues.

Declaration

public static Vector2 GetPreferredSize(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component to query.

Returns

Type	Description
Vector2	A Vector2 containing the preferred width (x) and height (y) in pixels; Vector2.zero if text is null.

GetPreferredWidth(TMP_Text)

Returns the preferred render width for the current text content of the component, as reported by TMP_Text.GetPreferredValues. This is the width TMP would use if left unconstrained by its RectTransform.

Declaration

public static float GetPreferredWidth(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component to query.

Returns

Type	Description
float	The preferred content width in pixels; 0 if text is null.

GetTextHeight(TMP_Text, string, float)

Returns the actual pixel height TMP would use to render the given text at a specific display width. Uses TMP_Text.GetPreferredValues for accurate height that correctly accounts for line wrapping and line spacing.

Declaration

public static float GetTextHeight(TMP_Text measurementComponent, string content, float constrainedWidth)

Parameters

Type	Name	Description
TMP_Text	measurementComponent	A dedicated TMP component to use as the measurement target. Its state will be temporarily modified and fully restored. Use CreateMeasurementComponent(Transform, TMP_FontAsset, float) to create a suitable hidden component.
string	content	The text content to measure. Empty or null content returns 0.
float	constrainedWidth	The available width in pixels for line wrapping. A value of zero or less returns 0.

Returns

Type	Description
float	The pixel height TMP would use to render the text (always >= 0); 0 if any input is invalid, the measurement component is null, the result is numerically invalid, or a re-entrant call is detected.

Remarks

Unlike GetWrappedLineCount(TMP_Text, string, float) (which calls ForceMeshUpdate), this method relies on GetPreferredValues(content, width, 0), which performs its own internal layout calculation and does not require a prior mesh update.

The component state is temporarily mutated and fully restored in a try/finally block. Re-entrant calls on the same component are blocked; a warning is logged and 0 is returned as a safe fallback.

Results that are NaN, infinity, or negative are treated as invalid and replaced with 0, with a warning logged.

GetVisibleCharacterCount(TMP_Text)

Returns the number of visible characters in the given TMP_Text component, excluding rich text tags. Calls ForceMeshUpdate before reading textInfo.characterCount to ensure the mesh is current.

Declaration

public static int GetVisibleCharacterCount(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component to query.

Returns

Type	Description
int	The visible character count after mesh update; 0 if text is null.

GetVisibleLineCount(TMP_Text)

Calculates how many text lines fit inside the visible rect of the given TMP_Text component using font-metric-based line-height estimation. Delegates to TryGetVisibleLineCount(TMP_Text, out int).

Declaration

public static int GetVisibleLineCount(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The text component whose rect and font metrics to query.

Returns

Type	Description
int	The number of whole lines that fit in the available vertical space; -1 if text is null, its rect height is zero, or the line height cannot be determined from font metrics.

GetWrappedLineCount(TMP_Text, string, float)

Calculates the exact number of visual lines TMP would render for the given text at a specific display width, using TMP's internal layout engine for accuracy.

Declaration

public static int GetWrappedLineCount(TMP_Text measurementComponent, string content, float constrainedWidth)

Parameters

Type	Name	Description
TMP_Text	measurementComponent	A dedicated TMP component to use as the measurement target. Its state will be temporarily modified and fully restored. Use CreateMeasurementComponent(Transform, TMP_FontAsset, float) to create a suitable hidden component.
string	content	The text content to measure. Empty or null content returns 1.
float	constrainedWidth	The available width in pixels for line wrapping. A value of zero or less returns 1.

Returns

Type	Description
int	The number of visual lines TMP would render (at least 1); 1 if any input is invalid, measurement fails, or a re-entrant call is detected.

Remarks

This method temporarily configures measurementComponent for measurement (word wrap enabled, overflow set to Overflow, rect height set to Scylla.Core.Util.UI.TMPUtil.MEASUREMENT_HEIGHT), calls ForceMeshUpdate to populate textInfo.lineCount, then restores the original component state.

If the same component is already being used for a measurement (re-entrant call), a warning is logged and 1 is returned immediately to prevent state corruption. Different components can be measured concurrently without interference.

GetWrappedLineSegments(TMP_Text, string, float)

Returns the individual line segments that TMP would render for the given text at a specific display width, derived from textInfo.lineInfo after a forced mesh update. Each element is a substring of content corresponding to one visual line.

Declaration

public static string[] GetWrappedLineSegments(TMP_Text measurementComponent, string content, float constrainedWidth)

Parameters

Type	Name	Description
TMP_Text	measurementComponent	A dedicated TMP component to use as the measurement target. Its state will be temporarily modified and fully restored. Use CreateMeasurementComponent(Transform, TMP_FontAsset, float) to create a suitable hidden component.
string	content	The text content to split into line segments.
float	constrainedWidth	The available width in pixels for line wrapping. A value of zero or less returns a single-element array with the full content.

Returns

Type	Description
string[]	An array of strings, one per visual line. Returns a single-element array containing the full content when any input is invalid, the measurement component is null, TMP reports zero lines, or a re-entrant call is detected.

Remarks

The component state is temporarily mutated and fully restored in a try/finally block. Re-entrant calls on the same component are blocked; a warning is logged and a single-element array containing the full content is returned as a fallback.

Character indices from lineInfo are clamped to the length of content to guard against stale TMP metadata.

Require(GameObject)

Returns the existing TextMeshProUGUI component on the specified GameObject, or adds and returns a new one if none exists. This is the TMP equivalent of a get-or-add pattern.

Declaration

public static TextMeshProUGUI Require(GameObject gameObject)

Parameters

Type	Name	Description
GameObject	gameObject	The GameObject to query or modify.

Returns

Type	Description
TextMeshProUGUI	The existing or newly added TextMeshProUGUI component; null if gameObject is null.

SetAlignment(TMP_Text, TextAlignmentOptions)

Sets the text alignment of a TMP_Text component. Null-safe: does nothing if text is null.

Declaration

public static void SetAlignment(TMP_Text text, TextAlignmentOptions alignment)

Parameters

Type	Name	Description
TMP_Text	text	The text component to configure.
TextAlignmentOptions	alignment	The TextAlignmentOptions value to apply.

SetAutoSize(TMP_Text, bool, float, float)

Enables or disables TMP font auto-sizing on the specified component. When enabling, the component will shrink or grow the font within the minSize to maxSize range to fit the available rect. The size range is only applied when enabled is true. Null-safe: does nothing if text is null.

Declaration

public static void SetAutoSize(TMP_Text text, bool enabled, float minSize = 10, float maxSize = 72)

Parameters

Type	Name	Description
TMP_Text	text	The text component to configure.
bool	enabled	true to enable auto-sizing; false to disable it.
float	minSize	Minimum font size in points when auto-sizing is active. Default is 10.
float	maxSize	Maximum font size in points when auto-sizing is active. Default is 72.

SetOverflow(TMP_Text, TextOverflowModes)

Sets the text overflow mode of a TMP_Text component. Null-safe: does nothing if text is null.

Declaration

public static void SetOverflow(TMP_Text text, TextOverflowModes overflow)

Parameters

Type	Name	Description
TMP_Text	text	The text component to configure.
TextOverflowModes	overflow	The TextOverflowModes value to apply.

SetWordWrapping(TMP_Text, bool)

Enables or disables word wrapping on a TMP_Text component by setting its textWrappingMode to either TextWrappingModes.Normal or TextWrappingModes.NoWrap. Null-safe: does nothing if text is null.

Declaration

public static void SetWordWrapping(TMP_Text text, bool enabled)

Parameters

Type	Name	Description
TMP_Text	text	The text component to configure.
bool	enabled	true to enable word wrapping (TextWrappingModes.Normal); false to disable it (TextWrappingModes.NoWrap).

TryGetLineHeight(TMP_Text, out float)

Attempts to compute the effective line height (in pixels) for the given TMP_Text component using font face metrics.

Declaration

public static bool TryGetLineHeight(TMP_Text text, out float lineHeight)

Parameters

Type	Name	Description
TMP_Text	text	The text component whose font metrics to read.
float	lineHeight	When this method returns true, receives the computed line height in pixels. When this method returns false, receives 0.

Returns

Type	Description
bool	true if the line height was successfully computed and is greater than zero; false if text is null, has no font, or the font's point size is non-positive.

Remarks

The formula scales the font's design-space lineHeight by the ratio of the current fontSize to the font's design pointSize, then applies the component's lineSpacing as a percentage multiplier (default 0 = 100% of base line height).

This formula-based approach may not exactly match TMP's internal layout engine. ScrollTextArea overrides this with a more accurate two-render approach (GetTextHeight("X\nX") - GetTextHeight("X")). Use this method for quick estimates and cases where sub-pixel accuracy is not required, such as TryGetVisibleLineCount(TMP_Text, out int).

TryGetVisibleLineCount(TMP_Text, out int)

Attempts to compute how many text lines fit inside the visible rect of the given TMP_Text component. Uses the font-metric approach from TryGetLineHeight(TMP_Text, out float) to estimate line height.

Declaration

public static bool TryGetVisibleLineCount(TMP_Text text, out int lineCount)

Parameters

Type	Name	Description
TMP_Text	text	The text component whose rect and font metrics to query.
int	lineCount	When this method returns true, receives the number of whole lines that fit in the rect's vertical space. When this method returns false, receives 0.

Returns

Type	Description
bool	true if the line count was successfully computed and is greater than zero; false if text is null, the rect height is non-positive, or line height could not be determined.