# yarnspinnertool/yarnspinner-unity architecture

> Architecture diagram of the GitHub repository yarnspinnertool/yarnspinner-unity, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yarnspinnertool/yarnspinner-unity
- Repository: https://github.com/yarnspinnertool/yarnspinner-unity

## Overview

1. **What this repository is**
   This is the Unity integration layer for Yarn Spinner, a dialogue system for games. It is not the compiler itself; the core Yarn Spinner compiler lives in a separate repository. This repo focuses on loading Yarn content in Unity, running dialogue at runtime, and providing editor tooling to author and import dialogue assets.

2. **Top-level architecture**
   The codebase is split into three main areas: **Runtime** for play-mode dialogue execution, **Editor** for importers and Unity editor UX, and **Tests** for editor/runtime validation. The package is built as a Unity package with assembly definitions for runtime and editor boundaries.

3. **Runtime dialogue execution**
   The central runtime subsystem is `DialogueRunner`. It orchestrates conversation flow by consuming compiled Yarn projects, requesting lines from a line provider, presenting options, and dispatching commands to game code. Supporting types like `DialogueOption` and utility classes live alongside it, indicating that `DialogueRunner` is the main runtime hub.

4. **Dialogue content and localization**
   Dialogue text is packaged into `YarnProject` assets and resolved at runtime through the **line provider** subsystem. `LocalizedLine`, `LineProviderBase`, `BuiltinLocalisedLineProvider`, and `UnityLocalisedLineProvider` show that line lookup can be backed either by Yarn’s built-in tables or Unity’s localization package when installed. This is the main data flow for turning line IDs into displayable text.

5. **Variable storage**
   Game state that Yarn reads and writes is handled by the storage subsystem under `Runtime/Storage`. `InMemoryVariableStorage` is the default runtime implementation, while `VariableStorageBehaviour` adapts it to Unity components. `IGeneratedVariableStorage` suggests support for generated strongly-typed storage, likely used when source generation is enabled.

6. **Commands and game-facing API**
   Yarn commands, functions, and parameters are represented by a set of runtime attributes and dispatch interfaces under `Runtime/Commands`. `ICommandDispatcher`, `IActionRegistration`, and `DefaultActions` define the contract between dialogue scripts and the host game. The command system is a key boundary: Yarn emits commands, and the Unity game decides how to execute them.

7. **Dialogue presentation layer**
   The `Runtime/Views` folder contains the UI-facing presentation stack: line presentation, options presentation, typewriter effects, voice-over playback, markup handling, and action/pause processing. This is the visual/output boundary between dialogue state and what the player sees or hears. Prefabs like `Dialogue System.prefab` and `Option Item.prefab` show the expected composition of these view components in a scene.

8. **Localisation and text metadata**
   Under `Runtime/Localisation` and `Runtime/YarnProject`, the package stores language/culture definitions, string table entries, and line metadata. This suggests a pipeline where imported Yarn content is enriched with IDs and metadata, then resolved per locale at runtime. The presence of `UnityLocalizationUpdater` in the editor side confirms integration with Unity localization tables.

9. **Editor import and asset generation**
   The editor layer contains importers for `.yarn` and `.yarnproject` files (`YarnImporter`, `YarnProjectImporter`) plus custom editors and property drawers. These components convert source dialogue files into Unity assets, keep metadata in sync, and provide authoring tools such as the commands window and project settings. The editor is where the raw narrative files become Unity-native assets used by runtime.

10. **Code analysis and source generation**
    `Editor/Analysis` includes analyzers, diagnostics, symbol helpers, and a source generator registration tool. On the runtime side, there is also a `SourceGenerator` directory and generated-action support files. This indicates a compile-time pipeline that inspects Yarn actions/functions in user code and generates registration glue, reducing manual wiring and enabling better validation.

11. **Optional dependencies and integration points**
    The repository is designed to adapt to Unity ecosystem packages rather than hard-require everything. Files like `UnityLocalisedLineProvider.Installed.cs` / `.NotInstalled.cs` and `TMPShim.cs` show conditional support for Unity Localization and TextMeshPro. The package also includes sample installers and dependency utilities, so integration behavior changes depending on what the host project has installed.

12. **Testing strategy**
    The `Tests` folder is broad and asset-heavy, with separate editor and runtime test suites. Tests cover importers, code analysis, dialogue runner behavior, line providers, command dispatch, variable storage, and UI/dialogue view behavior. The presence of test Yarn projects, voices, and Unity scenes indicates the repo validates both pure logic and Unity asset/runtime integration.

13. **Build and release infrastructure**
    GitHub workflows handle test runs, release publishing, version updates, and DLL updates. This matters architecturally because the package ships as a Unity distribution with bundled DLL metadata and generated docs, so releases are coordinated through automation rather than a standalone application build pipeline.

14. **How data typically flows through the system**
    The typical flow is: author writes Yarn scripts and a Yarn project → the editor importer turns them into Unity assets and metadata → `DialogueRunner` loads the project at runtime → the runner fetches localized lines from a line provider → views present the line and options → user input selects options or advances the dialogue → commands/functions are dispatched back into game-specific code → variable storage preserves state across the conversation.

Main entry points: [`Runtime/DialogueRunner/DialogueRunner.cs`](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/DialogueRunner/DialogueRunner.cs) (Dialogue Runner), [`Tests/Runtime/YarnSpinnerTests.asmdef`](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Runtime/YarnSpinnerTests.asmdef) (Runtime Tests), [`Tests/Editor/YarnSpinnerEditorTests.asmdef`](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Editor/YarnSpinnerEditorTests.asmdef) (Editor Tests), [`Editor/Importers/YarnImporter.cs`](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Importers/YarnImporter.cs) (Importers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_dialogue_runner["Dialogue Runner<br/>runtime hub<br/>[DialogueRunner.cs]"]
  node_line_providers["Line Providers<br/>runtime lines"]
  node_yarn_project["Yarn Project<br/>runtime asset<br/>[YarnProject.cs]"]
  node_variable_storage[("Variable Storage<br/>runtime state")]
  node_commands_api["Commands API<br/>runtime commands"]
  node_views["Dialogue Views<br/>runtime ui"]
  node_localisation["Localisation<br/>runtime locale<br/>[Localization.cs]"]
  node_yarn_task{{"Yarn Task<br/>runtime async<br/>[YarnTask.cs]"}}
end

subgraph group_editor["Editor"]
  node_editor_importers["Importers<br/>editor import<br/>[YarnImporter.cs]"]
  node_editor_analysis["Analysis<br/>editor codegen<br/>[Analyser.cs]"]
  node_editor_tools["Editor Tools<br/>editor ux"]
  node_editor_localization["Unity Localization<br/>editor integration"]
end

subgraph group_tests["Tests"]
  node_runtime_tests["Runtime Tests<br/>tests runtime"]
  node_editor_tests["Editor Tests<br/>tests editor"]
  node_test_assets["Test Assets<br/>test data"]
end

subgraph group_infra["Infra"]
  node_ci_release["CI & Release<br/>automation<br/>[test.yml]"]
  node_package_meta["Package Metadata<br/>[package.json]"]
end

node_yarn_project -->|"loads"| node_dialogue_runner
node_dialogue_runner -->|"requests lines"| node_line_providers
node_line_providers -->|"uses locale"| node_localisation
node_dialogue_runner -->|"presents"| node_views
node_views -.->|"reads state"| node_variable_storage
node_dialogue_runner -->|"reads/writes"| node_variable_storage
node_dialogue_runner -->|"dispatches"| node_commands_api
node_commands_api -.->|"validated by"| node_editor_analysis
node_editor_importers -->|"builds"| node_yarn_project
node_editor_importers -->|"updates tables"| node_editor_localization
node_editor_tools -->|"configures"| node_editor_importers
node_editor_tools -.->|"inspects"| node_dialogue_runner
node_editor_analysis -->|"generates glue"| node_commands_api
node_editor_analysis -.->|"feeds build"| node_package_meta
node_runtime_tests -->|"covers"| node_dialogue_runner
node_runtime_tests -->|"covers"| node_views
node_runtime_tests -->|"covers"| node_variable_storage
node_editor_tests -->|"covers"| node_editor_importers
node_editor_tests -->|"covers"| node_editor_analysis
node_editor_tests -->|"covers"| node_editor_localization
node_test_assets -->|"drives"| node_runtime_tests
node_ci_release -->|"runs"| node_runtime_tests
node_ci_release -->|"runs"| node_editor_tests
node_ci_release -->|"publishes"| node_package_meta

click node_dialogue_runner "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/DialogueRunner/DialogueRunner.cs"
click node_line_providers "https://github.com/yarnspinnertool/yarnspinner-unity/tree/main/Runtime/LineProviders"
click node_yarn_project "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/YarnProject/YarnProject.cs"
click node_variable_storage "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/Storage/InMemoryVariableStorage.cs"
click node_commands_api "https://github.com/yarnspinnertool/yarnspinner-unity/tree/main/Runtime/Commands"
click node_views "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/Views/DialoguePresenterBase.cs"
click node_localisation "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/Localisation/Localization.cs"
click node_yarn_task "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/YarnTask/YarnTask.cs"
click node_editor_importers "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Importers/YarnImporter.cs"
click node_editor_analysis "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Analysis/Analyser.cs"
click node_editor_tools "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Editors/YarnSpinnerEditorWindow.cs"
click node_editor_localization "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Importers/YarnProjectUnityLocalizationUpdater.cs"
click node_runtime_tests "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Runtime/YarnSpinnerTests.asmdef"
click node_editor_tests "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Editor/YarnSpinnerEditorTests.asmdef"
click node_test_assets "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Runtime/DialogueRunnerTests/DialogueRunnerTests.yarnproject"
click node_ci_release "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/.github/workflows/test.yml"
click node_package_meta "https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/package.json"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dialogue_runner,node_line_providers,node_yarn_project,node_variable_storage,node_commands_api,node_views,node_localisation,node_yarn_task toneBlue
class node_editor_importers,node_editor_analysis,node_editor_tools,node_editor_localization toneAmber
class node_runtime_tests,node_editor_tests,node_test_assets toneMint
class node_ci_release,node_package_meta toneRose
```

## Components

### Runtime

Play-mode dialogue execution, presentation, localization, and state storage.

- [Dialogue Runner](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/DialogueRunner/DialogueRunner.cs): runtime hub · Coordinates conversation flow, options, commands, and dialogue state at runtime. · `Runtime/DialogueRunner/DialogueRunner.cs`
- [Line Providers](https://github.com/yarnspinnertool/yarnspinner-unity/tree/main/Runtime/LineProviders): runtime lines · Resolves line IDs into localized display text from built-in or Unity localization sources. · `Runtime/LineProviders`
- [Yarn Project](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/YarnProject/YarnProject.cs): runtime asset · Compiled dialogue project asset plus line metadata and string table entries. · `Runtime/YarnProject/YarnProject.cs`
- [Variable Storage](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/Storage/InMemoryVariableStorage.cs): runtime state · Stores and exposes Yarn variables, including in-memory and component-backed storage. · `Runtime/Storage/InMemoryVariableStorage.cs`
- [Commands API](https://github.com/yarnspinnertool/yarnspinner-unity/tree/main/Runtime/Commands): runtime commands · Attributes, dispatch interfaces, and default actions for bridging Yarn commands to game code. · `Runtime/Commands`
- [Dialogue Views](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/Views/DialoguePresenterBase.cs): runtime ui · Presentation layer for lines, options, markup, pauses, typewriter effects, and voice-over. · `Runtime/Views/DialoguePresenterBase.cs`
- [Localisation](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/Localisation/Localization.cs): runtime locale · Culture definitions and localization helpers used by dialogue content and line lookup. · `Runtime/Localisation/Localization.cs`
- [Yarn Task](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Runtime/YarnTask/YarnTask.cs): runtime async · Awaitable/task abstractions used by asynchronous dialogue presentation code. · `Runtime/YarnTask/YarnTask.cs`

### Editor

Importers, authoring tools, analyzers, and Unity editor integration.

- [Importers](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Importers/YarnImporter.cs): editor import · Transforms .yarn and .yarnproject source files into Unity assets and keeps metadata in sync. · `Editor/Importers/YarnImporter.cs`
- [Analysis](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Analysis/Analyser.cs): editor codegen · Analyzes user code for actions/functions and supports source generation and diagnostics. · `Editor/Analysis/Analyser.cs`
- [Editor Tools](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Editors/YarnSpinnerEditorWindow.cs): editor ux · Custom inspectors, editor windows, settings, and authoring helpers for Yarn content. · `Editor/Editors/YarnSpinnerEditorWindow.cs`
- [Unity Localization](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Editor/Importers/YarnProjectUnityLocalizationUpdater.cs): editor integration · Editor-side synchronization between Yarn projects and Unity localization tables. · `Editor/Importers/YarnProjectUnityLocalizationUpdater.cs`

### Tests

Editor and runtime validation suites with asset-heavy integration cases.

- [Runtime Tests](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Runtime/YarnSpinnerTests.asmdef): tests runtime · Runtime validation for dialogue runner, command dispatch, storage, and views. · `Tests/Runtime/YarnSpinnerTests.asmdef`
- [Editor Tests](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Editor/YarnSpinnerEditorTests.asmdef): tests editor · Validation of importers, analysis, dialogue references, and localization import. · `Tests/Editor/YarnSpinnerEditorTests.asmdef`
- [Test Assets](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/Tests/Runtime/DialogueRunnerTests/DialogueRunnerTests.yarnproject): test data · Yarn scripts, projects, voice assets, and scenes used by integration tests. · `Tests/Runtime/DialogueRunnerTests/DialogueRunnerTests.yarnproject`

### Infra

Package metadata, CI, and release automation.

- [CI & Release](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/.github/workflows/test.yml): automation · GitHub workflows for testing, versioning, release publishing, and DLL/package updates. · `.github/workflows/test.yml`
- [Package Metadata](https://github.com/yarnspinnertool/yarnspinner-unity/blob/main/package.json): package · Unity package descriptor, assembly boundaries, notices, and release-facing metadata. · `package.json`

## Connections

- Yarn Project → Dialogue Runner: loads · The runner consumes dialogue project assets at runtime.
- Dialogue Runner → Line Providers: requests lines · Dialogue flow asks a provider to resolve localized text for line IDs.
- Line Providers → Localisation: uses locale · Line resolution is shaped by language and culture data.
- Dialogue Runner → Dialogue Views: presents · The runner sends lines, options, and events to presentation components.
- Dialogue Views → Variable Storage: reads state · Presentation and view logic can react to dialogue variables and state.
- Dialogue Runner → Variable Storage: reads/writes · Dialogue execution evaluates and mutates Yarn variables during conversation.
- Dialogue Runner → Commands API: dispatches · Commands emitted by dialogue scripts are routed to host-game actions.
- Commands API → Analysis: validated by · Analyzer and source-generation tooling inspect commands, actions, and functions.
- Importers → Yarn Project: builds · Importers turn source Yarn files into Unity assets and metadata.
- Importers → Unity Localization: updates tables · Project import can synchronize Unity localization content.
- Editor Tools → Importers: configures · Editor windows and inspectors support authoring and importer workflows.
- Editor Tools → Dialogue Runner: inspects · Custom editor UI helps configure the runtime runner and related components.
- Analysis → Commands API: generates glue · Code analysis supports action registration and strongly typed bindings.
- Analysis → Package Metadata: feeds build · Generated metadata and validation support packaged distribution.
- Runtime Tests → Dialogue Runner: covers · Runtime tests exercise runner behavior and integration points.
- Runtime Tests → Dialogue Views: covers · UI and presentation behavior is validated in scene-based tests.
- Runtime Tests → Variable Storage: covers · Variable storage behavior is checked by dedicated runtime tests.
- Editor Tests → Importers: covers · Editor tests validate import and asset generation workflows.
- Editor Tests → Analysis: covers · Analysis tests exercise diagnostics and code inspection logic.
- Editor Tests → Unity Localization: covers · Localization import behavior is validated from the editor side.
- Test Assets → Runtime Tests: drives · Yarn scripts, projects, audio, and scenes act as integration fixtures.
- CI & Release → Runtime Tests: runs · Automation executes runtime validation in CI.
- CI & Release → Editor Tests: runs · Automation executes editor validation in CI.
- CI & Release → Package Metadata: publishes · Release workflows update package/version metadata and ship artifacts.
