TMPEffects

TMPEffects allows you to apply visual effects to TextMeshPro text using custom tags. It operates through three main pillars:

• Animations: Used to animate text blocks continuously (e.g., waving text) or to animate the sequence of showing/hiding text.
• Commands: Used to raise events or trigger specific logic at a given character index.
• Tags: The interface used within the text string to trigger animations and commands (e.g., <wave amp=12>).

You can use built-in animations/commands or create your own via scripts or the Unity Inspector/Timeline.

To begin using TMPEffects, follow these steps:

1. Add the TMPAnimator and/or TMPWriter component to a GameObject that also has a TextMeshPro(UI) component.
2. In the inspector for both components, select "use default database".
3. A prompt will appear to import the required resources. Click the button in the prompt to complete the setup.

TMPEffects works out of the box with YarnSpinner.

Setup Requirements:

• You must disable YarnSpinner's built-in typewriter effects.
• Once disabled, you can use TMPEffects tags in your Yarn scripts.
• You can even use variables defined in YarnSpinner scripts as tag parameters within your TMPEffects tags.

You can install TMPEffects using the OpenUPM registry or directly through the Unity Package Manager using a Git URL.

Via Git URL: In the Unity Package Manager, add a new package from git URL using: https://github.com/Luca3317/TMPEffects.git?path=/Package

Via OpenUPM: Available at https://openupm.com/packages/com.luca3317.tmpeffects/.

Manual Installation: If you clone the repository manually, you must import the required resources located under Assets > TMPEffects > Resources.

When writing custom animations or commands in C#, you can easily expose variables to be controlled via text tags using the [AutoParameter] attribute. This allows you to pass values directly from the tag into your logic.

Supported types include float, Vector3, AnimationCurve, and more. You can also define custom keywords using Keyword databases.

```csharp
[AutoParameter("ampltiude", "amp"), SerializeField]
private float amplitude;

Usage in text: <wave amp=12> will set the amplitude field to 12.*

The DelayCommand allows you to inject delays into the text rendering process. It can be used to set a global delay for all subsequent effects, or to target specific text elements like whitespace, line breaks, punctuation, or visible characters.

When configuring the command, you can specify a delay value and a type (either raw or percentage). If the delay value is set to default, the command reverts to the default delays defined in the TMPWriter.

// Example conceptual usage in a TMP keyword string:
[delay=0.5]This text has a 0.5s delay.
[delay=50%, for=whitespace]This affects whitespace delays.

The ShowCommand is a built-in TMP command used to make text visible within a sequence. It operates on a Block tag type and is designed to execute instantly. This command is repeatable, meaning it can be called multiple times within the same sequence if needed. In the Unity Editor, it also supports previewing.

// Note: As a TMP command, this is typically invoked via a tag in a text string
// e.g., <show>Your Text Content</show>

The DelayCommand accepts parameters to define what is being delayed, the amount of delay, and the unit of measurement.

Parameters

• "" (Empty Key): The delay value. Accepts a float, an empty string "", or the literal "default".
• for: Specifies the target element type. Valid values include:
  • whitespace or ws
  • linebreak, linebr, or br
  • punctuation or punct
  • visible or vis
• type: Specifies the unit of the delay value. Valid values include:
  • raw (default)
  • percentage, pct, or %

// Parameter structure for DelayCommand:
// [delay=<value>, for=<target>, type=<unit>]

// Target options (for):
whitespace | ws
linebreak | linebr | br
punctuation | punct
visible | vis

// Unit options (type):
raw
percentage | pct | %

The SkippableCommand uses an auto-parameter to define its behavior.

This command is decorated with [AutoParameters], meaning it can be configured via text tags or automated data injection.

// The internal parameter used by the command:
[AutoParameter(true, "")] private bool skippable = false;

The WaitCommand uses a single parameter to define the delay duration:

Note: This parameter is automatically handled via the [AutoParameter] attribute.

// Parameter definition:
[AutoParameter(true, "")] private float waitTime;