Yarn Spinner for Unity

You can register C# methods as commands that can be called directly from Yarn scripts. Yarn Spinner supports several types of method signatures:

1. Static Methods: Registered as global commands.
2. Instance Methods on Components: If the method is an instance method on a class inheriting from UnityEngine.Component, the first argument of the command in the Yarn script must be the name of a GameObject. Yarn Spinner will then find that GameObject and call the method on the component of the correct type attached to it.
3. Delegates/Funcs: You can pass a Delegate or Func<object> to register a handler.

Constraints:

• Command names cannot contain spaces.
• For instance methods on Components, the method must be declared on a class that inherits from Component.
• If a method uses an array as a parameter, that array must be the last parameter in the method signature.

// Example: Registering a static command
// Yarn: <<add_score 10>>
public static void AddScore(int amount) { ... }
actions.AddCommandHandler("add_score", (Action)AddScore);

// Example: Registering a component command
// Yarn: <<play_sound MyPlayer SoundEffect>>
// (Where 'MyPlayer' is a GameObject name and 'SoundEffect' is a parameter)
public void PlaySound(string effectName) { ... }
actions.AddCommandHandler("play_sound", (Action)PlaySound);

To make a C# method callable from a Yarn dialogue script as a command, decorate the method with a class that inherits from YarnActionAttribute.

By default, the command name used in Yarn will match the C# method name. However, you can provide a custom name via the constructor to allow for different naming conventions (e.g., using snake_case in Yarn while keeping PascalCase in C#).

using Yarn.Unity;

public class MyGameCommands
{
    // This will be callable in Yarn as 'walk_to_point'
    [YarnAction("walk_to_point")]
    public void WalkToPoint(float x, float y)
    {
        // Implementation
    }

    // This will be callable in Yarn as 'say_hello'
    [YarnAction("say_hello")]
    public void SayHello()
    {
        // Implementation
    }

    // This will be callable in Yarn as 'Jump' (uses method name)
    [YarnAction]
    public void Jump()
    {
        // Implementation
    }
}

To allow a DialogueRunner to execute a C# method as a command from your Yarn dialogue, decorate the method with the [YarnCommand] attribute.

Command Resolution Logic

When a DialogueRunner encounters a command (e.g., <<move player fast>>):

1. It splits the command by spaces.
2. It checks if the second word is the name of an active GameObject in the scene.
3. If a GameObject is found, it searches its attached MonoBehaviour components for a method marked with [YarnCommand] where the Name matches the first word of the command.
4. If the method is static, it does not attempt to resolve a GameObject and is called directly.

Parameter Mapping Rules

Once a method is identified, the DialogueRunner maps the remaining words in the command to the method's parameters:

Note: If parameters cannot be matched or converted, the method will not be called and a warning will be issued.

Async and Coroutines

You can attach [YarnCommand] to IEnumerator (coroutines), Coroutine returning methods, or Task returning methods. The DialogueRunner will automatically pause dialogue execution until the coroutine or task completes.

using UnityEngine;
using Yarn.Unity;
using System.Collections;

public class PlayerController : MonoBehaviour
{
    // Simple command: <<move player fast>>
    [YarnCommand("move")]
    public void MovePlayer(GameObject target, string speed)
    {
        Debug.Log($"Moving {target.name} at speed {speed}");
    }

    // Boolean command with self-documenting parameter: <<wait true>> or <<wait>>
    [YarnCommand("wait")]
    public void Wait(bool wait)
    {
        if (wait) StartCoroutine(WaitRoutine());
    }

    private IEnumerator WaitRoutine()
    {
        yield return new WaitForSeconds(1f);
    }

    // Static command (no GameObject required): <<set_score 10>>
    [YarnCommand("set_score")]
    public static void SetScore(int score)
    {
        Debug.Log($"Score set to: {score}");
    }
}