Class TMPSettings

Immutable-by-convention configuration bag for creating and configuring TMP_Text components through the Scylla UI utilities.

Inheritance

object

TMPSettings

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Util.UI

Assembly: ScyllaCore.dll

Syntax

public sealed class TMPSettings

Remarks

A set of ready-to-use preset instances is available as static properties: Default, Header, Body, Caption, Button, Console, and InputField. Use these directly or derive from them with Clone() when you need a slightly customized variant without altering the shared preset.

Presets are shared instances. Mutating a preset property after it has been retrieved will affect every consumer of that preset. Always call Clone() before modifying a preset:

var settings = TMPSettings.Header.Clone();
settings.FontSize = 20f;
settings.ApplyTo(myText);

Call Validate() before ApplyTo(TMP_Text) when font size values are derived from external input (e.g. config files or user preferences) to catch out-of-range values early.

Constructors

TMPSettings()

Initializes a new TMPSettings with all default values.

Declaration

public TMPSettings()

Remarks

The resulting instance corresponds to a 16 pt, white, top-left aligned, word-wrapping, rich-text-enabled label with no font override. Use the static preset properties (Default, Header, etc.) when you want a named, semantically meaningful starting point.

TMPSettings(TMPSettings)

Initializes a new TMPSettings as a deep copy of an existing instance.

Declaration

public TMPSettings(TMPSettings other)

Parameters

Type	Name	Description
TMPSettings	other	The settings to copy. Must not be null.

Exceptions

Type	Condition
ArgumentNullException	Thrown when other is null.

Fields

DEFAULT_AUTO_SIZE_MAX

The default upper bound of the font size range used by TMP's automatic font-size fitting feature when EnableAutoSizing is true.

Declaration

public const float DEFAULT_AUTO_SIZE_MAX = 72

Field Value

Type	Description
float

DEFAULT_AUTO_SIZE_MIN

The default lower bound of the font size range used by TMP's automatic font-size fitting feature when EnableAutoSizing is true.

Declaration

public const float DEFAULT_AUTO_SIZE_MIN = 10

Field Value

Type	Description
float

DEFAULT_FONT_SIZE

The default font size in points used when constructing a TMPSettings instance without specifying a size.

Declaration

public const float DEFAULT_FONT_SIZE = 16

Field Value

Type	Description
float

DEFAULT_LINE_SPACING

The default line spacing value (in TMP's em units) applied when constructing a TMPSettings instance. A value of 0 uses TMP's built-in line advance derived from the font metrics.

Declaration

public const float DEFAULT_LINE_SPACING = 0

Field Value

Type	Description
float

MAX_FONT_SIZE

The largest font size in points accepted by Validate(). Prevents excessively large text that would produce oversized mesh geometry.

Declaration

public const float MAX_FONT_SIZE = 500

Field Value

Type	Description
float

MIN_FONT_SIZE

The smallest font size in points accepted by Validate(). Matches TMP's practical minimum to prevent invisible or degenerate glyphs.

Declaration

public const float MIN_FONT_SIZE = 1

Field Value

Type	Description
float

Properties

Alignment

Gets or sets the horizontal and vertical text alignment within the element's RectTransform.

Declaration

public TextAlignmentOptions Alignment { get; set; }

Property Value

Type	Description
TextAlignmentOptions	Defaults to TextAlignmentOptions.TopLeft.

AutoSizeMax

Gets or sets the maximum font size in points used during automatic sizing.

Declaration

public float AutoSizeMax { get; set; }

Property Value

Type	Description
float	Defaults to DEFAULT_AUTO_SIZE_MAX (72 pt). Only evaluated by ApplyTo(TMP_Text) when EnableAutoSizing is true. Must satisfy AutoSizeMax >= AutoSizeMin to pass Validate().

AutoSizeMin

Gets or sets the minimum font size in points used during automatic sizing.

Declaration

public float AutoSizeMin { get; set; }

Property Value

Type	Description
float	Defaults to DEFAULT_AUTO_SIZE_MIN (10 pt). Only evaluated by ApplyTo(TMP_Text) when EnableAutoSizing is true. Must satisfy AutoSizeMin <= AutoSizeMax to pass Validate().

Body

Gets a preset optimized for body text: 14 pt, normal weight, top-justified, word wrap enabled, with a line spacing of 2 em units for improved readability.

Declaration

public static TMPSettings Body { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

Button

Gets a preset optimized for interactive button labels: 16 pt, bold, center aligned, word wrap disabled, overflow mode set to ellipsis, and RaycastTarget set to false so the label itself does not consume pointer events.

Declaration

public static TMPSettings Button { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

Caption

Gets a preset optimized for captions and small auxiliary text: 12 pt, italic, top-left aligned, rendered in a light gray (Color(0.7, 0.7, 0.7, 1)) to visually distinguish it from primary content.

Declaration

public static TMPSettings Caption { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

CharacterSpacing

Gets or sets the additional horizontal spacing between characters in TMP em units.

Declaration

public float CharacterSpacing { get; set; }

Property Value

Type	Description
float	Defaults to 0. Positive values spread characters apart.

Color

Gets or sets the text vertex color.

Declaration

public Color Color { get; set; }

Property Value

Type	Description
Color	Defaults to Color.white.

Console

Gets a preset optimized for monospace console output: 14 pt, normal weight, top-left aligned, word wrap enabled, overflow mode set to truncate, rich text enabled, rendered in near-white (Color(0.9, 0.9, 0.9, 1)).

Declaration

public static TMPSettings Console { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

Default

Gets the default text preset: 16 pt, white, normal weight, top-left aligned, word wrap enabled, rich text enabled.

Declaration

public static TMPSettings Default { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

EnableAutoSizing

Gets or sets whether TMP's automatic font-size fitting is enabled.

Declaration

public bool EnableAutoSizing { get; set; }

Property Value

Type	Description
bool	Defaults to false. When true, TMP scales the font between AutoSizeMin and AutoSizeMax to fill the available bounds. FontSize is ignored while auto-sizing is active.

EnableKerning

Gets or sets whether the TMP OpenType kerning feature is applied to adjust spacing between specific character pairs.

Declaration

public bool EnableKerning { get; set; }

Property Value

Type	Description
bool	Defaults to true. When applied via ApplyTo(TMP_Text), kerning is managed through TMP_Text.fontFeatures (the modern API that replaced the deprecated enableKerning property).

EnableRichText

Gets or sets whether TMP rich text tags (e.g. <b>, <color=red>) are interpreted rather than rendered literally.

Declaration

public bool EnableRichText { get; set; }

Property Value

Type	Description
bool	Defaults to true.

EnableWordWrapping

Gets or sets whether TMP automatically inserts line breaks at word boundaries when text exceeds the element's width.

Declaration

public bool EnableWordWrapping { get; set; }

Property Value

Type	Description
bool	Defaults to true.

Font

Gets or sets the TMP_FontAsset to apply.

Declaration

public TMP_FontAsset Font { get; set; }

Property Value

Type	Description
TMP_FontAsset	The font asset, or null to retain TMP's default font. When ApplyTo(TMP_Text) is called with a non-null font, it replaces the component's current font; a null value leaves the component font unchanged.

FontSize

Gets or sets the font size in points.

Declaration

public float FontSize { get; set; }

Property Value

Type	Description
float	Defaults to DEFAULT_FONT_SIZE (16 pt). Must be within [MIN_FONT_SIZE, MAX_FONT_SIZE] to pass Validate().

FontStyle

Gets or sets the TMP font style flags.

Declaration

public FontStyles FontStyle { get; set; }

Property Value

Type	Description
FontStyles	Defaults to FontStyles.Normal. Multiple flags can be combined, e.g. FontStyles.Bold | FontStyles.Italic.

Header

Gets a preset optimized for headings and titles: 24 pt, bold, center aligned, word wrap disabled.

Declaration

public static TMPSettings Header { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

InputField

Gets a preset optimized for text input field content: 16 pt, normal weight, left aligned, word wrap disabled, overflow mode set to overflow, black text, and RaycastTarget set to false so the text mesh does not intercept pointer events (the TMP input field itself handles those).

Declaration

public static TMPSettings InputField { get; }

Property Value

Type	Description
TMPSettings

Remarks

This is a shared instance. Call Clone() before mutating any property to avoid affecting other consumers.

LineSpacing

Gets or sets the line spacing in TMP em units added on top of the font's natural line advance.

Declaration

public float LineSpacing { get; set; }

Property Value

Type	Description
float	Defaults to DEFAULT_LINE_SPACING (0). Positive values increase the gap between lines; negative values tighten it.

OverflowMode

Gets or sets how text that overflows the bounding rectangle is handled.

Declaration

public TextOverflowModes OverflowMode { get; set; }

Property Value

Type	Description
TextOverflowModes	Defaults to TextOverflowModes.Truncate. Common alternatives include Overflow (clip to rect), Ellipsis (append "..."), and ScrollRect.

Padding

Gets or sets the internal padding applied inside the text bounding rectangle.

Declaration

public UIPadding Padding { get; set; }

Property Value

Type	Description
UIPadding	Defaults to Zero. The padding is written to TMP_Text.margin as a Vector4(left, top, right, bottom) when ApplyTo(TMP_Text) is called.

RaycastTarget

Gets or sets whether the TMP_Text component acts as a raycast target for pointer events in the Unity Event System.

Declaration

public bool RaycastTarget { get; set; }

Property Value

Type	Description
bool	Defaults to true. Set to false for decorative labels or text children of interactive controls (e.g. buttons) to avoid blocking their pointer events.

Methods

ApplyTo(TMP_Text)

Writes all settings in this instance to the given TMP_Text component, overwriting its current configuration.

Declaration

public void ApplyTo(TMP_Text text)

Parameters

Type	Name	Description
TMP_Text	text	The TMP_Text component to configure. Must not be null.

Remarks

The method applies every property to the component in a single call, which triggers one TMP mesh rebuild. The following fields are written: font (only when Font is non-null), fontSize, fontStyle, color, lineSpacing, characterSpacing, alignment, overflowMode, textWrappingMode, richText, raycastTarget, margin, kerning via fontFeatures, and auto-sizing parameters.

Exceptions

Type	Condition
ArgumentNullException	Thrown when text is null.

Clone()

Creates an independent deep copy of this TMPSettings instance.

Declaration

public TMPSettings Clone()

Returns

Type	Description
TMPSettings	A new TMPSettings with identical property values. Modifying the returned instance does not affect the original.

Remarks

Use this method before customizing a shared preset to avoid polluting the preset for other consumers:

var settings = TMPSettings.Header.Clone();
settings.Color = Color.yellow;
settings.ApplyTo(warningLabel);

ToString()

Returns a compact string representation showing the most identifying settings.

Declaration

public override string ToString()

Returns

Type	Description
string	A string in the format TMPSettings(Size:N, Style:S, Align:A) where N is FontSize, S is FontStyle, and A is Alignment.

Overrides

object.ToString()

Validate()

Validates the font size fields and throws ArgumentException if any value falls outside the permitted range.

Declaration

public void Validate()

Remarks

Call this method when font size values originate from external sources such as configuration files or user preferences. The method is a no-op when all values are in range and auto-sizing is disabled.

Exceptions

Type	Condition
ArgumentException	Thrown when FontSize is outside [MIN_FONT_SIZE, MAX_FONT_SIZE], or when EnableAutoSizing is true and either AutoSizeMin or AutoSizeMax is out of the same range, or when AutoSizeMin exceeds AutoSizeMax.

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)