### Yarn Spinner Dialogue Syntax Example

Source: https://docs.febucci.com/text-animator-unity/integrations/integrated-plugins-and-dialogues-systems/yarn-spinner

Demonstrates the basic syntax for writing dialogues in Yarn Spinner, including conditional lines and one-time execution tags. This format allows for structured conversations within game development.

```yarnspinner
-> What's going on? <<once>>
    Guard: The kingdom is under seige!
-> Where can I park my horse? <<once if $has_horse>>
    Guard: Over by the tavern.
-> Lovely day today!
    Guard: Uh huh.
-> I should go.
    Guard: Please do.
```

--------------------------------

### Implement Action Logic using Coroutine (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-actions-c

Shows how to implement the core logic of a custom text animator action using a coroutine by overriding the PerformAction method. This example demonstrates playing an audio source and waiting for its clip to finish before proceeding.

```csharp
[SerializeField] AudioSource source;

protected override IEnumerator PerformAction(TypingInfo typingInfo)
{
    if (source != null && source.clip != null)
    {
        source.Play();
        yield return new WaitForSeconds(source.clip.length);
    }
}
```

--------------------------------

### Create Custom Action as Scriptable Object (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-actions-c

Illustrates the creation of a custom text animator action as a ScriptableObject. This method enables actions to be reused and referenced without requiring a scene to be loaded. The example shows overriding methods for stateless or coroutine-based logic.

```csharp
[System.Serializable]
[CreateAssetMenu(menuName = "Create Example Action")]
class ExampleActionScriptable : TypewriterActionScriptable
{
    [SerializeField] float timeToWait;
    
    // main logic here...
    
    // ...either stateless
    protected override IActionState CreateCustomState(ActionMarker marker, object typewriter)
        => new ExampleState(timeToWait);
        
    // ...or as a Coroutine
    protected override IEnumerator PerformAction(TypingInfo typingInfo)
    {
        // yield return ...
    }
}
```

--------------------------------

### Show Text with TypewriterComponent (Unity C#)

Source: https://docs.febucci.com/text-animator-unity/typewriter/show-and-hide-letters-dynamically

Demonstrates how to programmatically initiate text display using the TypewriterComponent in Unity. This method is recommended for precise control over text animations, ensuring proper timing and integration with other script functionalities. It requires referencing the TypewriterComponent and calling its ShowText method.

```csharp
using Febucci.TextAnimator.Typewriter;

public class TextAnimatorController : MonoBehaviour
{
    public TypewriterComponent typewriter;
    public string textToShow = "Hello, World!";

    void Start()
    {
        if (typewriter != null)
        {
            typewriter.ShowText(textToShow);
        }
    }
}
```

--------------------------------

### C# Dynamic Dialogue Construction for Text Animator

Source: https://docs.febucci.com/text-animator-unity/effects/setting-up-texts

This C# snippet demonstrates how to construct a dynamic dialogue string before setting it to the Text Animator. It first defines variables for game state and player name, then uses string interpolation to build the complete dialogue line. Finally, it calls `typewriter.ShowText()` to display the constructed dialogue.

```csharp
int apples = 5; //later taken from the game state
string playerName = "Bob";

// build the entire dialogue line first
string dialogue = $"Hello {playerName}, you've got {apples} apples";

// then set the text once
typewriter.ShowText(dialogue);
```

--------------------------------

### Import Namespaces for Text Animator Actions (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-actions-c

Provides the necessary 'using' statements to import the required namespaces for working with Text Animator actions in Unity. These namespaces include those for actions and core typing functionalities.

```csharp
using Febucci.TextAnimatorForUnity.Actions;
using Febucci.TextAnimatorCore.Typing;
using UnityEngine;
```

--------------------------------

### Create Custom Action as Component (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-actions-c

Demonstrates how to create a custom text animator action by inheriting from TypewriterActionScriptable and implementing it as a Component. This approach allows for easier referencing of scene objects. It shows overriding methods to define custom state or coroutine logic.

```csharp
[System.Serializable]
class ExampleActionComponent : TypewriterActionScriptable
{
    [SerializeField] float timeToWait;
    
    // main logic here, 
    
    // ...either stateless
    protected override IActionState CreateCustomState(ActionMarker marker, object typewriter)
        => new ExampleState(timeToWait);
        
    // ...or as a Coroutine
    protected override IEnumerator PerformAction(TypingInfo typingInfo)
    {
        // yield return ...
    }
}
```

--------------------------------

### Set TextMeshPro Text via Text Animator Component (C#)

Source: https://docs.febucci.com/text-animator-unity/effects/setting-up-texts

Illustrates the recommended way to set text for TextMeshPro objects when using Text Animator in Unity. It emphasizes using the Text Animator's script (TextAnimator_TMP) instead of the native TMP_Text for better integration and control. This approach ensures proper animation application.

```csharp
using UnityEngine;
using TMPro;
using Febucci.TextAnimatorForUnity.TextMeshPro; // <- import Text Animator's namespace

public class ExampleScript : MonoBehaviour
{
    [SerializeField] TMP_Text textMeshPro;
    [SerializeField] TextAnimator_TMP textAnimator;

    void Start()
    {
        // 🚫 Don't: set text through TMPro
        textMeshPro.SetText("<wave>hello");

        // ✅ Do: set text through Text Animator directly
        textAnimator.SetText("<wave>hello");
    }

}
```

--------------------------------

### Apply Text Effects with Rich Text Tags

Source: https://docs.febucci.com/text-animator-unity/quick-start/install-and-quick-start

Illustrates how to embed rich text tags within strings to apply various text animations provided by the Febucci Text Animator. These tags, such as `<shake>`, `<wave>`, and `<wiggle>`, are interpreted by the animator to create dynamic text effects. This method is applicable across different text rendering systems supported by the animator.

```plaintext
I'm <shake>freezing</shake>
```

```plaintext
<wiggle>I'm joking</wiggle> hehe now <shake>I'm scared</shake>
```

--------------------------------

### Instantiate Stateless Action State (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-actions-c

Demonstrates how to instantiate a custom stateless action (an IActionState struct) by overriding the CreateCustomState method within your custom action class. This links the stateless logic to the action definition.

```csharp
protected override IActionState CreateCustomState(ActionMarker marker, object typewriter)
        => new ExampleState(timeToWait);
```

--------------------------------

### Add AnimatedLabel to UI Document via Code (C#)

Source: https://docs.febucci.com/text-animator-unity/effects/setting-up-texts

Demonstrates how to programmatically create and add an 'AnimatedLabel' component to a UI Document in Unity using the UI Toolkit. This involves importing the Text Animator namespace and manipulating the UI's root visual element. It's useful for dynamic UI generation.

```csharp
using UnityEngine;
using UnityEngine.UIElements;
using Febucci.TextAnimatorForUnity; // <- import Text Animator's namespace

public class ExampleScript : MonoBehaviour
{
    [SerializeField] UIDocument document;

    void Start()
    {
        var container = document.rootVisualElement.contentContainer;
        var animatedLabel = new AnimatedLabel(); // <- create an animated label
        container.Add(animatedLabel); // <- add it to the content container
        // [..]
        animatedLabel.SetText("<wave>hello"); // <- set the text
    }
}
```

--------------------------------

### Implement Stateless Action Logic (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-actions-c

Details the implementation of a stateless custom text animator action by creating a struct that inherits from IActionState. This custom state manages its progress over time and returns an ActionStatus to indicate whether it is still running or has finished.

```csharp
struct ExampleState : IActionState // <--- must inherit from this
{
    float timePassed;
    readonly float timeToWait;
    public ExampleState(float timeToWait)
    {
        timePassed = 0;
        this.timeToWait = timeToWait;
    }
    
    public ActionStatus Progress(float deltaTime, ref TypingInfo typingInfo)
    {
        // increases time passed
        timePassed += deltaTime;
        
        // tells to continue or to stop based on time
        return timePassed >= timeToWait
            ? ActionStatus.Finished
            : ActionStatus.Running;
    }
    
    public void Cancel()
    {
        // use this for modifying 
    }
}
```

--------------------------------

### Import Namespaces for Text Animator Effects (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-effects-c

This snippet shows the necessary using directives to import the Text Animator namespaces required for creating custom effects in Unity. These include core functionalities and effect-specific modules.

```csharp
using UnityEngine;

// import Text Animator's namespaces
using Febucci.TextAnimatorCore;
using Febucci.TextAnimatorCore.Text;
using Febucci.Parsing;
using Febucci.TextAnimatorForUnity.Effects;
```

--------------------------------

### Listening to Text Animator Events in Unity C#

Source: https://docs.febucci.com/text-animator-unity/typewriter/trigger-events-when-typing

This C# script demonstrates how to subscribe to and handle messages sent from Text Animator's event tags. It requires a reference to a TypewriterComponent and uses the onMessage callback to process incoming event markers, allowing for custom logic based on event names.

```csharp
using UnityEngine;
using Febucci.UI.Core;

public class EventListener : MonoBehaviour
{
    [SerializeField] TypewriterComponent typewriter;

    void OnEnable()
    {
        if (typewriter != null)
        {
            typewriter.onMessage.AddListener(OnMessage);
        }
    }

    void OnDisable()
    {
        if (typewriter != null)
        {
            typewriter.onMessage.RemoveListener(OnMessage);
        }
    }

    void OnMessage(EventMarker marker)
    {
        Debug.Log("Received event: " + marker.name + " with parameters: " + string.Join(", ", marker.parameters));

        switch (marker.name)
        {
            case "shakeCamera":
                // Call a camera shake function
                Debug.Log("Shaking camera!");
                break;
            case "playSound":
                if (marker.parameters.Length > 0)
                {
                    // Play sound based on marker.parameters[0]
                    Debug.Log("Playing sound: " + marker.parameters[0]);
                }
                break;
            default:
                Debug.LogWarning("Unknown event received: " + marker.name);
                break;
        }
    }
}
```

--------------------------------

### Create Custom Typewriter Waits Scriptable Object (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-typing-waits-c

This C# script defines a custom typewriter wait behavior for Text Animator in Unity. It inherits from `TypingsTimingsScriptableBase` and overrides `GetWaitAppearanceTimeOf` and `GetWaitDisappearanceTimeOf` to implement custom delays, such as skipping spaces. Ensure your scriptable object is serialized and assigned to the Text Animator component.

```csharp
using Febucci.TextAnimatorCore;
using Febucci.TextAnimatorCore.Text;
using Febucci.TextAnimatorForUnity;

using UnityEngine;

[System.Serializable]
[CreateAssetMenu(fileName = "Custom Typewriter Waits")]
class CustomTypingWaits : TypingsTimingsScriptableBase
{
    [SerializeField] float delay = .1f;
    
    public override float GetWaitAppearanceTimeOf(CharacterData character, TextAnimator animator)
    {
        if (char.IsWhiteSpace(character.info.character))
            return 0;

        return delay;
    }

    public override float GetWaitDisappearanceTimeOf(CharacterData character, TextAnimator animator)
    {
        return GetWaitAppearanceTimeOf(character, animator);
    }
}
```

--------------------------------

### Create Custom Effect Scriptable Object for Text Animator Unity

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-effects-c

This C# script defines a Scriptable Object wrapper for custom effects in Text Animator. It ensures the effect is serializable and can be created as an asset. The primary function is to create a new state for the custom effect, managed by Text Animator's parameters.

```csharp
using UnityEngine;

// Assuming ManagedEffectScriptable, CustomEffectState, and CustomEffectParameters are defined elsewhere in the Text Animator package.
// For demonstration purposes, placeholder definitions might be needed if not available.

// Placeholder for the base class if not provided by the package
// public abstract class ManagedEffectScriptable<TState, TParams> : ScriptableObject { protected abstract TState CreateState(TParams parameters); }
// public class CustomEffectState { public CustomEffectState(object parameters) {} }
// public class CustomEffectParameters {}

[System.Serializable]
[CreateAssetMenu(fileName = "Your Custom Effect", menuName = "Text Animator/Custom Effect")]
class CustomEffectScriptable : ManagedEffectScriptable<CustomEffectState, CustomEffectParameters>
{
    // simply creates a new State, given the Parameters (already managed by text animator)
    protected override CustomEffectState CreateState(CustomEffectParameters parameters)
        => new CustomEffectState(parameters);
}
```

--------------------------------

### Define Custom Effect Parameters (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-effects-c

This C# code defines a class to hold the customizable parameters for a custom text effect. It includes a public float variable 'amount' with a default value, which can be modified in the Unity Inspector.

```csharp
// can be either struct or class
// the latter allows you to have default values
[System.Serializable]
class CustomEffectParameters
{
    public float amount = 1.5f;
}
```

--------------------------------

### Implement Custom Effect State Logic (C#)

Source: https://docs.febucci.com/text-animator-unity/writing-custom-classes/writing-custom-effects-c

This C# struct implements the core logic for a custom text effect, inheriting from IEffectState. It handles parameter updates from rich text tags and applies transformations to character data over time, utilizing context information like progression and intensity.

```csharp
// must be struct!
struct CustomEffectState : IEffectState
{
    readonly float defaultAmount;
    float amount;


    public CustomEffectState(CustomEffectParameters data)
    {
        // gets the default amount from the parameters class
        this.defaultAmount = data.amount;
        this.amount = defaultAmount;
    }

    public void UpdateParameters(RegionParameters parameters)
    {
        // automatically handles cases where the user wrote 
        // modifiers in the rich text tag, "a" in this case
        // (e.g. <tagID a=5> will set "amount" to 5, while 
        // a*2 will make "amount" two times defaultAmount)
        amount = parameters.ModifyFloat("a", defaultAmount);
    }

    public void Apply(ref CharacterData character, in ManagedEffectContext context)
    {
        // uses "amount" to move the character up
        // with a clear and easy to use API
        character.MovePosition(
            Vector3.Up * amount * context.progressionRange * context.intensity,
            context.isUpPositive
            );
        // 1. note context.progressionRange -> it's the 
        //     curve you have assigned in the editor!
        //     allowing you for a step, a sine, bounce etc. result
        // 2. note also the context.intensity, needed to have 
        //     smooth transitions between stages.
        }
}
```