Class UITextBuilder

Fluent builder for creating and configuring TMPro.TextMeshProUGUI text elements at runtime. All configuration methods return the same builder instance, enabling chainable method calls. Call Build() or TryBuild(out TextMeshProUGUI) as the terminal step to construct the Unity GameObject and obtain the TMP component.

Inheritance
object
UITextBuilder
Inherited Members
Namespace: Scylla.Core.Util.UI
Assembly: ScyllaCore.dll
Syntax
public sealed class UITextBuilder
Remarks

The builder creates a new GameObject, attaches a RectTransform, and adds a TextMeshProUGUI component. The object is automatically assigned to the UI layer via UIUtil.AddToUILayer.

When no anchor is specified the element defaults to an upper-left anchor. When no explicit size is specified the RectTransform retains the Unity default size; only positive width and height values are applied.

Example usage: 

var label = new UITextBuilder()
    .WithParent(contentTransform)
    .WithText("Score: 0")
    .WithFontSize(18f)
    .WithColor(Color.yellow)
    .WithAlignment(UIAlignment.MiddleCenter)
    .WithSize(200f, 40f)
    .Build();

Methods

AtPosition(float, float)

Sets the anchored position offset of the text element.

Declaration
public UITextBuilder AtPosition(float x, float y)
Parameters
Type Name Description
float x

Horizontal offset in pixels from the anchor point.
float y

Vertical offset in pixels from the anchor point.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

AtPosition(Vector2)

Sets the anchored position offset of the text element.

Declaration
public UITextBuilder AtPosition(Vector2 position)
Parameters
Type Name Description
Vector2 position

Pixel offset from the anchor point applied to the RectTransform.anchoredPosition property.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

AutoSize(bool, float, float)

Enables or disables TMP auto-sizing, which automatically adjusts the font size to fit the text within the RectTransform.

Declaration
public UITextBuilder AutoSize(bool enabled = true, float min = 10, float max = 72)
Parameters
Type Name Description
bool enabled

true to activate auto-sizing; false to disable it (the default).
float min

Minimum font size in points when auto-sizing is active. Clamped so it is never smaller than MIN_FONT_SIZE. Defaults to 10.
float max

Maximum font size in points when auto-sizing is active. Clamped so it is never larger than MAX_FONT_SIZE. Defaults to 72.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

Build()

Builds and returns a fully configured TextMeshProUGUI component.

Declaration
public TextMeshProUGUI Build()
Returns
Type Description
TextMeshProUGUI

The newly created TextMeshProUGUI component. Never returns null under normal circumstances; use TryBuild(out TextMeshProUGUI) if you prefer exception-free handling.
Remarks

The method creates a new GameObject, adds a RectTransform, applies the configured anchor and size, then adds and configures a TextMeshProUGUI component. The object is automatically assigned to the UI layer.

If no anchor was specified, the element defaults to an upper-left anchor. If no explicit size was set, only axes with a positive value are resized.

Exceptions
Type Condition
ArgumentException

Thrown when the builder configuration is logically invalid (e.g. no valid parent hierarchy in some Unity contexts).

BuildAbstract()

Builds the text component and wraps it in an IUIText abstraction. Use this overload when consumers should interact with the element through the interface rather than the concrete TMP type.

Declaration
public IUIText BuildAbstract()
Returns
Type Description
IUIText

A UITextComponent wrapping the newly created TextMeshProUGUI, returned as IUIText.
Exceptions
Type Condition
ArgumentException

Thrown when the builder configuration is invalid. See Build().

RaycastTarget(bool)

Controls whether the text element acts as a raycast target for the Unity UI event system.

Declaration
public UITextBuilder RaycastTarget(bool enabled = true)
Parameters
Type Name Description
bool enabled

true to make the element receive pointer events; false to make it transparent to input (the default, which is appropriate for pure display labels).
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

RichText(bool)

Enables or disables TMP rich text parsing for the text element.

Declaration
public UITextBuilder RichText(bool enabled = true)
Parameters
Type Name Description
bool enabled

true to interpret TMP rich text tags such as <b>, <color=#FF0000>, and similar (the default); false to render all characters literally.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

TryBuild(out TextMeshProUGUI)

Attempts to build the TextMeshProUGUI component, suppressing any exception and reporting failure through the return value instead.

Declaration
public bool TryBuild(out TextMeshProUGUI text)
Parameters
Type Name Description
TextMeshProUGUI text

When this method returns true, contains the newly created TextMeshProUGUI component. When this method returns false this parameter is null.
Returns
Type Description
bool

true if the component was created successfully; false if an exception occurred during construction (the error is logged to the UI log category).

TryBuildAbstract(out IUIText)

Attempts to build the text component as an IUIText abstraction, suppressing any exception and reporting failure through the return value instead.

Declaration
public bool TryBuildAbstract(out IUIText text)
Parameters
Type Name Description
IUIText text

When this method returns true, contains the newly created element as an IUIText interface. When this method returns false this parameter is null.
Returns
Type Description
bool

true if the component was created successfully; false if an exception occurred during construction (the error is logged to the UI log category).

WithAlignment(UIAlignment)

Sets the text alignment using the Scylla UIAlignment enum, which is mapped to the corresponding TextAlignmentOptions value.

Declaration
public UITextBuilder WithAlignment(UIAlignment alignment)
Parameters
Type Name Description
UIAlignment alignment

A UIAlignment value representing one of the nine standard anchor positions. Unknown values fall back to top-left.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithAlignment(TextAlignmentOptions)

Sets the text alignment using the native TMP alignment options.

Declaration
public UITextBuilder WithAlignment(TextAlignmentOptions alignment)
Parameters
Type Name Description
TextAlignmentOptions alignment

A TextAlignmentOptions value specifying how text is positioned horizontally and vertically within its rect. Defaults to TextAlignmentOptions.TopLeft.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithAnchor(UIAlignment)

Sets the anchor and pivot configuration for the RectTransform by deriving a UIAnchor from the specified alignment.

Declaration
public UITextBuilder WithAnchor(UIAlignment alignment)
Parameters
Type Name Description
UIAlignment alignment

A UIAlignment value representing one of the nine standard anchor positions. Internally resolved via FromAlignment(UIAlignment).
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithAnchor(UIAnchor)

Sets the anchor and pivot configuration for the RectTransform using an explicit UIAnchor value.

Declaration
public UITextBuilder WithAnchor(UIAnchor anchor)
Parameters
Type Name Description
UIAnchor anchor

The UIAnchor describing the anchorMin, anchorMax, and pivot vectors applied to the RectTransform. Use UIAnchors for common presets.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithCharacterSpacing(float)

Sets the character spacing adjustment for the text element.

Declaration
public UITextBuilder WithCharacterSpacing(float spacing)
Parameters
Type Name Description
float spacing

A floating-point value added to the default advance width between each character. Positive values spread characters apart; negative values bring them closer together.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithColor(Color)

Sets the color of the rendered text.

Declaration
public UITextBuilder WithColor(Color color)
Parameters
Type Name Description
Color color

The RGBA color to apply. The alpha channel controls transparency. Defaults to Color.white.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithFont(TMP_FontAsset)

Sets the TMP font asset used to render the text.

Declaration
public UITextBuilder WithFont(TMP_FontAsset font)
Parameters
Type Name Description
TMP_FontAsset font

The TMP_FontAsset to apply. When null the TMP default font is used unchanged.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithFontSize(float)

Sets the font size in points.

Declaration
public UITextBuilder WithFontSize(float size)
Parameters
Type Name Description
float size

The desired font size. Values are clamped to the range [MIN_FONT_SIZE, MAX_FONT_SIZE] (1 to 500 points). This value is ignored when auto-sizing is enabled via AutoSize(bool, float, float).
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithFontStyle(FontStyles)

Sets the TMP font style flags applied to the text.

Declaration
public UITextBuilder WithFontStyle(FontStyles style)
Parameters
Type Name Description
FontStyles style

A FontStyles value or combination of flags (e.g. FontStyles.Bold | FontStyles.Italic). Use FontStyles.Normal for plain text with no additional styling.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithLineSpacing(float)

Sets the line spacing as a percentage adjustment relative to the font's base line height.

Declaration
public UITextBuilder WithLineSpacing(float spacing)
Parameters
Type Name Description
float spacing

A floating-point percentage delta applied to the default line height. A value of 0 produces normal line spacing. Positive values increase the gap between lines; negative values decrease it.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithName(string)

Sets the name of the text's GameObject.

Declaration
public UITextBuilder WithName(string name)
Parameters
Type Name Description
string name

The name to give the created GameObject. When null or empty the builder falls back to the default name "Text".
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithOverflow(TextOverflowModes)

Sets the overflow mode that controls how text is handled when it exceeds the bounds of the RectTransform.

Declaration
public UITextBuilder WithOverflow(TextOverflowModes overflow)
Parameters
Type Name Description
TextOverflowModes overflow

A TextOverflowModes value. Common choices are Truncate (the default), Ellipsis, Overflow, and ScrollRect.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithParent(Transform)

Sets the parent transform that the text object will be attached to.

Declaration
public UITextBuilder WithParent(Transform parent)
Parameters
Type Name Description
Transform parent

The transform to use as the parent. Pass null to create the object at the scene root with no parent.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WithSettings(TMPSettings)

Applies all configuration values from a TMPSettings preset, overwriting any previously set options on this builder.

Declaration
public UITextBuilder WithSettings(TMPSettings settings)
Parameters
Type Name Description
TMPSettings settings

The preset to apply. All font, color, alignment, overflow, wrapping, rich-text, raycast-target, spacing, and auto-size values are copied. When null this method is a no-op and returns the builder unchanged.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithSize(float, float)

Sets the explicit width and height of the RectTransform.

Declaration
public UITextBuilder WithSize(float width, float height)
Parameters
Type Name Description
float width

Width in pixels. Values less than or equal to zero leave the horizontal axis at the Unity default size.
float height

Height in pixels. Values less than or equal to zero leave the vertical axis at the Unity default size.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithSize(Vector2)

Sets the explicit width and height of the RectTransform.

Declaration
public UITextBuilder WithSize(Vector2 size)
Parameters
Type Name Description
Vector2 size

A Vector2 containing the width (x) and height (y) in pixels. Components less than or equal to zero leave the corresponding axis at the Unity default size.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.
See Also

WithText(string)

Sets the initial text content displayed by the element.

Declaration
public UITextBuilder WithText(string text)
Parameters
Type Name Description
string text

The string to show. TMP rich text tags are honored when rich text is enabled (the default). Pass null to clear the content; the builder will substitute an empty string.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

WordWrap(bool)

Enables or disables word wrapping for the text element.

Declaration
public UITextBuilder WordWrap(bool enabled = true)
Parameters
Type Name Description
bool enabled

true to allow text to wrap to a new line when it reaches the right edge of the rect (the default); false to force all text onto a single line.
Returns
Type Description
UITextBuilder

This builder instance, enabling fluent method chaining.

Extension Methods