Yarn Spinner 3 Beta 1

Things To Know First About The Beta

• Yarn Spinner 3 for Unity requires Unity version 2022.3 and above.
• If upgrading an existing project, Yarn Project assets will automatically re-import. Compile errors should be reported to Discord.
• Upgrading from earlier versions requires modifying .yarnproject files by changing projectFileVersion from 2 to 3.
• Previous Yarn Spinner 2 samples have moved to a new repository; the beta includes only a “Characters” sample.
• Documentation for Yarn Spinner 3 is still in progress.
• Purchase the tool on Itch to support continued development.

How To Install Yarn Spinner 3 Beta

1. Open Window menu → Package Manager
2. Click + button → “Add package from Git URL”
3. Enter: https://github.com/YarnSpinnerTool/YarnSpinner-Unity.git#beta

For Visual Studio Code prerelease:

1. View → Extensions
2. Search “yarn spinner”
3. Click “Switch to Pre-Release Version”

Language Features

Once Statements

You can use a once statement to run content only one time. When the script reaches a once statement, it checks to see if it’s run before.

<<once>>
  Guard: Hail, traveller! Well met.
  Guard: I am Alys, the guard!
<<endonce>>

Supports else clauses and conditional execution with once if:

<<once if $player_is_adventurer>>
  Guard: I used to be an adventurer like you...
<<else>>
  Guard: Greetings.
<<endonce>>

Can be applied to individual lines and options for single-use appearance or selectability.

Detour Statement

Allows running content from a different node, then returning to the original location:

<<detour Guard_Backstory>>

When you reach the end of the node, or reach a return statement, Yarn Spinner will return to just after the detour statement.

The return statement exits a detoured node early and returns control.

Line Groups

Collections of lines where the system selects one to run. Marked with =>:

=> Guard: Halt!
=> Guard: No entry!
=> Guard: Stop!

Supports conditions and once keywords:

=> Guard: Hail, adventurer! <<if $player_is_adventurer>>
=> Guard: I used to be an adventurer... <<once if $player_is_adventurer>>

Node Groups

Multiple nodes sharing the same name with when: headers determining execution conditions:

title: Guard
when: once
---
Guard: You there, traveller!
===

title: Guard
when: $has_sword
---
Guard: No weapons allowed!
===

Useful for creating conditional dialogue branches based on game state.

Saliency

Controls how line and node groups select content. Built-in strategies:

• First: Selects first item with no failed conditions
• Best: Sorts by condition complexity score
• Best Least Recently Viewed: Sorts by score and selection frequency
• Random Best Least Recently Viewed: Randomly selects among highest-scoring options

Custom strategies implement IContentSaliencyStrategy interface with QueryBestContent and ContentWasSelected methods.

Enums

Variables constrained to predefined values:

<<enum Food>>
  <<case Apple>>
  <<case Orange>>
<<endenum>>

<<declare $favouriteFood = Food.Apple>>
<<set $favouriteFood to Food.Orange>>

Can be used in conditionals; enum names can be omitted when context is clear.

Smart Variables

Variables with runtime-determined values:

<<declare $player_can_afford_pie = $player_money > 10>>

Accessible wherever regular variables work, enabling expression reuse across projects.

Shadow Lines

Reuse lines without duplicating string table entries. Marked with #shadow: referencing a source line’s #line: tag:

title: Tavern
---
Ava: I should go. #line:departure

title: Kitchen
---
Ava: I should go. #shadow:departure

Shadow lines are required to have the same text in the Yarn script as their source line, but are allowed to have different hashtags.

Unity Features

Async Dialogue Views

Dialogue Views now use async/await, simplifying development with fewer callbacks and better cooperation between views.

Your existing (non-async) dialogue view code will automatically seamlessly work with Yarn Spinner 3, and you don’t need to change it if you don’t want to.

Async Systems

Yarn Spinner automatically uses the first available:

• UniTask (recommended): Free, lightweight, all Unity versions supporting Yarn Spinner 3
• Awaitables: Unity 2023.3+, lightweight with fewer features
• .NET Tasks: All versions, fallback option with potential performance trade-offs

Creating New Dialogue Views

Subclass AsyncDialogueViewBase and implement required methods.

RunLineAsync receives a line and presents it to the player:

public override async YarnTask RunLineAsync(LocalizedLine line, LineCancellationToken token)
{
    this.textView.text = line.Text.Text;
    await YarnTask.WaitUntilCanceled(token.NextLineToken);
    this.textView.text = "";
}

RunOptionsAsync presents options and returns selected choice:

public override async YarnTask<DialogueOption?> RunOptionsAsync(
    DialogueOption[] dialogueOptions,
    CancellationToken cancellationToken)
{
    while (cancellationToken.IsCancellationRequested == false) {
        if (Input.GetKeyDown(KeyCode.Num1)) { return dialogueOptions[0]; }
        await YarnTask.Yield();
    }
    return null;
}

OnDialogueStartedAsync and OnDialogueCompleteAsync handle dialogue lifecycle.

Async Line Providers

Line Providers convert line IDs to localized content, now supporting async/await patterns via GetLocalizedLineAsync returning YarnTask<LocalizedLine>.

Yarn Spinner includes Built-In Localisation and Unity Localisation providers covering most needs.

Codegen Variable Storage

Generates C# classes with properties for all Yarn Project variables and smart variables, providing compile-time checked access:

Enable “Generate Variables Source file” in Yarn Project Inspector, specifying class name, namespace, and parent storage class.

Generated classes create properties and enum declarations automatically.

Custom Markup Processing

Two markup types:

• Replacement markup affects line contents (e.g., [style])
• Temporal markup affects delivery pacing (e.g., [pause])

Line Providers pass content through replacement markup handlers; dialogue views handle temporal markup controlling delivery timing. Markup varies per-locale for language-specific needs.