Pardon our dust! Docs for Yarn Spinner for Unity 3.2 and Yarn Spinner for Godot C# are on docs.yarnspinner.dev (the old docs site). Docs for Yarn Spinner for Unity 3.3 (pre-release, out ASAP), Yarn Spinner for Godot GDScript and Yarn Spinner for Unreal Engine (work in progress) are on /docs/ (the new docs site).

Action

Represents the concept of a yarn action, so either a command or a function
(no declaration available)

Inherits from System.Object

Implements System.IEquatable{Yarn.Shared.Action}

#Constructors

#Action(string, string, string, ActionType, bool, ReturnType, NamedType, Parameter[])

Creates a new action representing a command or a function.
public Action(string Name, string FullMethodName, string ShortMethodName, ActionType Type, bool HasTarget, ReturnType ReturnType, NamedType Container, Parameter[] Parameters)

Parameters

  • Namestring
    The name of the action itself. it's Yarn Name
  • FullMethodNamestring
    The fully qualified name of the method that is being used to define this action
  • ShortMethodNamestring
    A shorter convenience form of the full method name
  • Is the action a command or function?
  • HasTargetbool
    Is the action an instance action or not?
  • What type the action returns
  • The type that the method lives within. This is necessary for other parts to verify and double check if the method can be called and how
  • The parameters of the action. The order of this array must reflect the order of both the yarn and c# side

Returns Void

Actions are a common shared type across numerous different parts of Yarn Spinner and it's not expected that you would be creating one yourself. They are made by the source generator and analysers and used as part of the diagnostic system, the command and function invocation system, ysls generation, and compilation.

This class should be always kept in a form where it cache and comparison friendly as this type is a common output of a lot of other elements of the analysis pipeline which do caching. Types contained within should always be either a basic type or a record basically.

#Fields

#containingNamedType

The type that the method lives within. This is necessary for other parts to verify and double check if the method can be called and how.
public NamedType containingNamedType;

Type NamedType

#Parameters

The parameters of the action. The order of this array must reflect the expected order of both the yarn and c# sides of the action.
public Parameter[] Parameters;

#Properties

#containingTypeFullName

Convenience wrapper around containingNamedType
public string containingTypeFullName { get; }

Type String

#containingTypeShortName

Convenience wrapper around containingNamedType
public string containingTypeShortName { get; }

Type String

#DeclarationType

The declaration type of the action.
public DeclarationType DeclarationType { get; internal set; }

Type DeclarationType

#HasDefaultParameters

Returns true if any parameter in the action has a default value
public bool HasDefaultParameters { get; }

Type Boolean

#HasParameterArray

Returns true if any parameter in the action is an array
public bool HasParameterArray { get; }

Type Boolean

#IsAsync

An action is async if it returns an awaitable type. In Unity coroutines and ienumerator are not async.
public bool IsAsync { get; }

Type Boolean

#IsInstance

Whether this action requires a target upon which to be invoked.
public bool IsInstance { get; internal set; }

Type Boolean

This is not the same as being not static, as lambdas and local functions aren't static but aren't called on an instance.

#MethodName

The fully-qualified name for this method, including the global prefix.
public string? MethodName { get; set; }

Type Nullable

#Name

The name of this action.
public string Name { get; internal set; }

Type String

#NumberOfParameters

Calculates and returns the number of parameters that we should expect to see in the Yarn for this action.
public (int min, int max) NumberOfParameters { get; }

Type ValueTuple

This property understands and handles:
  • commands are always one parameter more than functions due to the name of the command being a part of the invocation.
  • instance methods have an additional parameter which is the lookup of the target of the action.
  • optional parameters and array parameters can change the minimum and maximum number of parameters to a minimum of 0 and maximum of 8196.
  • cancellation tokens aren't a parameter as far as yarn is concerned.

#Return

public ReturnType Return { get; internal set; }

Type ReturnType

#ShortMethodName

The short calling form of the method, this is also captured by MethodName but is more convenient as it doesn't have the little global:: bits.
public string? ShortMethodName { get; set; }

Type Nullable

#Type

The type of the action.
public ActionType Type { get; internal set; }

Type ActionType

#Usage

Returns a string of the appropriate usage of the action, understanding the parameters and the differences between calling a command or function in Yarn Spinner.
public string Usage { get; }

Type String

#Methods

#ConverterCallingString(string, IReadOnlyList<YarnConverter>, ILogger?)

Given a fully qualified type name finds the appropriate calling string of the converter for this type. Essentially can be thought of as knows that for type Blah you need to call Blah.MakeBlah(input, output) and returns that method as a string so it can be used in the source generator.
public static string? ConverterCallingString(string paramType, IReadOnlyList<YarnConverter> converters, ILogger? logger)

Parameters

  • paramTypestring
    The fully qualified type name, it MUST be the fully qualified name!
  • convertersIReadOnlyList<Yarn.Shared.YarnConverter>
    The list of converters, one of which hopefully know about the type
  • The logger, will likely be null

Returns Nullable: The string representation of a method call for the converter of the requested type, or null if it couldn't find one.

#DetermineParameterTypeFromNamedTypeForUnity(NamedType, IReadOnlyList<YarnConverter>, ILogger?)

Given a named type and list of converters determines what type of parameter the named type is to be according to the needs of Unity.
public static ParameterTypes DetermineParameterTypeFromNamedTypeForUnity(NamedType namedType, IReadOnlyList<YarnConverter> converters, ILogger? logger = null)

Parameters

  • The type to be converted and validated
  • convertersIReadOnlyList<Yarn.Shared.YarnConverter>
    The list of converters available to help determine the type
  • A logger, will almost certainly be null

Returns ParameterTypes: The type of the parameter of the named type depending on the whims and needs of Unity.

Each engine has their own specific quirks which means a parameter type that is perfectly fine for one engine may not be the case in another. This method given a named type converts this into the Unity specific parameter form, or invalid if that isn't possible for this named type. This is necessary because being able to detect something that is flagged as an action in code isn't the same thing as being able to bind it to an action in Yarn and then also be able to go the other way around.

#TryValidateAction(Action, IReadOnlyList<YarnConverter>, ILogger?, bool)

Attempts to validate if an action is valid. This means all it's parameters and returns are of a type that is expected and possible to be called.
public static bool TryValidateAction(Action action, IReadOnlyList<YarnConverter> converters, ILogger? logger = null, bool isUnknownParameterInvalid = true)

Parameters

  • The action seeking validation
  • convertersIReadOnlyList<Yarn.Shared.YarnConverter>
    List of converters needed to validate any unknown parameters
  • The logger, most likely will be null
  • isUnknownParameterInvalidbool
    If this is true an unknown parameter that doesn't eventually find a converter in the converters list will cause validation to fail. If set to false the opposite is true, an unresolved param doesn't prevent validation. This is needed because of runtime actions in Unity, we won't be able to guarantee they have a converter (because it might live in a different assembly) for them at compile time so have to trust that there will be one a runtime.

Returns Boolean: True if the action passed validation

This realistically should probably do more checking as all it currently does is validate that we have a finalised type for each parameter and the containing type is one that is possible to be constructed for instance methods. This is mostly fine because other steps have done their own checking but it's probably worth having a single all encompassing validator. A problem for later.

Generated from Yarn Spinner for Unity 3.3.