How yarnspinnertool/yarnspinner-unity works
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: DialogueRunner.cs Dialogue Runner · YarnSpinnerTests.asmdef Runtime Tests · YarnSpinnerEditorTests.asmdef Editor Tests · YarnImporter.cs Importers
Components 17
Runtime
Play-mode dialogue execution, presentation, localization, and state storage.
- Dialogue Runner · Coordinates conversation flow, options, commands, and dialogue state at runtime.
Runtime/DialogueRunner/DialogueRunner.cs - Line Providers · Resolves line IDs into localized display text from built-in or Unity localization sources.
Runtime/LineProviders - Yarn Project · Compiled dialogue project asset plus line metadata and string table entries.
Runtime/YarnProject/YarnProject.cs - Variable Storage · Stores and exposes Yarn variables, including in-memory and component-backed storage.
Runtime/Storage/InMemoryVariableStorage.cs - Commands API · Attributes, dispatch interfaces, and default actions for bridging Yarn commands to game code.
Runtime/Commands - Dialogue Views · Presentation layer for lines, options, markup, pauses, typewriter effects, and voice-over.
Runtime/Views/DialoguePresenterBase.cs - Localisation · Culture definitions and localization helpers used by dialogue content and line lookup.
Runtime/Localisation/Localization.cs - Yarn Task · Awaitable/task abstractions used by asynchronous dialogue presentation code.
Runtime/YarnTask/YarnTask.cs
Editor
Importers, authoring tools, analyzers, and Unity editor integration.
- Importers · Transforms .yarn and .yarnproject source files into Unity assets and keeps metadata in sync.
Editor/Importers/YarnImporter.cs - Analysis · Analyzes user code for actions/functions and supports source generation and diagnostics.
Editor/Analysis/Analyser.cs - Editor Tools · Custom inspectors, editor windows, settings, and authoring helpers for Yarn content.
Editor/Editors/YarnSpinnerEditorWindow.cs - Unity Localization · 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 · Runtime validation for dialogue runner, command dispatch, storage, and views.
Tests/Runtime/YarnSpinnerTests.asmdef - Editor Tests · Validation of importers, analysis, dialogue references, and localization import.
Tests/Editor/YarnSpinnerEditorTests.asmdef - Test Assets · 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 · GitHub workflows for testing, versioning, release publishing, and DLL/package updates.
.github/workflows/test.yml - Package Metadata · Unity package descriptor, assembly boundaries, notices, and release-facing metadata.
package.json
Connections 24
- 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.