Unreal Engine integration

This page is a deep dive into using the exported Unreal plugin once it's compiled — the "no-code" Blueprint workflow. For the export step itself (what gets generated, first-time install, and the C++ API), see Game engine export → Unreal Engine. For release/test validation, use the Unreal export/import test manual.

Verified against UE 5.7

The generated plugin has been build-tested end to end (Editor + Game targets, Development + Shipping) against Unreal Engine 5.7.

The exported structure

Exporting to Unreal (left sidebar → Export to game engine → Unreal) writes a self-contained <Project>_Unreal/ folder next to your YarnDraft project:

<Project>_Unreal/
├── Plugins/
│   └── YarnDraft/
│       ├── YarnDraft.uplugin
│       ├── Source/YarnDraftRuntime/   ← C++ runtime module (story player, entity data asset)
│       ├── Source/YarnDraftEditor/    ← editor-only module (entity importer, Live Sync, toolbar)
│       └── Content/
│           ├── BP_YarnDraftPlayer.uasset   ← Blueprint Actor wrapper
│           ├── BPC_YarnDraft.uasset        ← Blueprint Actor Component wrapper
│           ├── WBP_YarnDraftDialogue.uasset
│           └── WBP_YarnDraftChoiceButton.uasset
├── Content/
│   └── YarnDraft/
│       ├── story.json      ← the exported, sanitized story graph
│       └── assets/         ← referenced .wav / .mp3 / .ogg audio files
└── Config/
    └── Tags/
        └── YarnDraftTags.ini   ← every unique Gameplay Tag used by your entities

• Plugins/YarnDraft is a code plugin — it ships C++ source, not prebuilt binaries, so Unreal compiles it as part of your project.
• Content/YarnDraft holds your story data — story.json plus any audio actually referenced by a Dialogue or Audio card. Live Sync refreshes story.json and copies referenced audio files into Content/YarnDraft/assets/.
• Config/Tags/YarnDraftTags.ini lists every Gameplay Tag referenced by a gameplayTagList entity field, in the standard GameplayTagsList format Unreal expects. Live Sync/import can refresh this file from story.json, but newly added tags still require an Unreal Editor restart before the Gameplay Tags manager sees them.

How to install

1. Copy the folders in. Merge Plugins/YarnDraft/, Content/YarnDraft/, and Config/Tags/YarnDraftTags.ini into your Unreal project's root, next to your own .uproject, Plugins/, Content/, and Config/ folders — don't overwrite your existing folders, just drop the YarnDraft subfolders/files into each.
2. Open or convert the project for C++. First double-click the .uproject and accept Unreal's missing-module rebuild prompt. If project-file generation says the project has no source code, open the project in Unreal Editor, create one empty C++ class (Tools → New C++ Class), close the editor, then right-click the .uproject → Generate Visual Studio project files (Windows) or generate Xcode project files (Mac).
3. Compile the module — open the generated solution and build (Development Editor config), or reopen the .uproject and accept Unreal's rebuild prompt.
4. Open the project and check Edit → Plugins → search "YarnDraft" to confirm it's enabled (project plugins are on by default — this is just a sanity check).

C++ toolchain required

Unreal always compiles code plugins from source, so you'll need Visual Studio with the "Game development with C++" workload (or Xcode on Mac) installed, even if your project has never had any other C++ code.

You only need to repeat steps 2–4 once per project. Later story-only re-exports just need the new Content/YarnDraft/story.json dropped in — no recompiling.

How to use it — the "no-code" way

Both BP_YarnDraftPlayer and BPC_YarnDraft live inside the plugin's own Content folder, which the Content Browser hides by default.

Show Plugin Content

In the Content Browser, open the Settings (gear icon, bottom-right) and enable Show Plugin Content. A new YarnDraft Content folder then appears in the Content Browser, containing BP_YarnDraftPlayer and BPC_YarnDraft.

Both Blueprints are meant as a starting point, not as a finished dialogue UI:

• Story File Name — on the YarnDraft dialogue component, a string selector populated from Content/YarnDraft/**/*.json files. The default is YarnDraft/story.json.
• Start Flow Name — on the YarnDraft dialogue component, an optional flow selector. Leave it empty for the root flow, or choose a flow name from the dropdown populated from the selected story file.
• Dialogue Widget Class — use the plugin-provided WBP_YarnDraftDialogue for a simple textbox + choice-button UI, or replace it with your own widget derived from UYarnDraftDialogueWidget.
• OnLine / OnChoices events drive the widget. Plain lines advance with Advance(), choices call Choose(Index).
• OnGameEvent is available on the YarnDraft Dialogue component for Game Event cards. Bind it in Blueprint when you want a node such as open_door to trigger game logic.
• OnInventoryChanged fires when an Inventory card gives or takes an item. Use the EntityId and current Quantity to update your own inventory/journal UI. Use GetInventoryQuantity(EntityId) when a Blueprint needs the current count on demand.
• ExportStateJson() / ImportStateJson(Json) save and restore YarnDraft variables, tasks, clues, and inventory counts for your game's SaveGame object. They do not save the current textbox or selected choice UI position.
• If keyboard input does not reach the actor, set Auto Receive Input to Player 0 or call Enable Input from BeginPlay.
• For a custom UI, bind line text to a Text widget, build dynamic buttons from choices, hide the choice panel during plain lines, and show it only when choices are present.

Method A — the Blueprint Actor (BP_YarnDraftPlayer)

The simplest way to try a story in-level, with no scripting at all:

1. Drag BP_YarnDraftPlayer from the YarnDraft Content folder into your level.
2. Select the placed actor and, in the Details panel, find Story File Name — change it if your story file isn't named story.json (e.g. if you export multiple stories side by side).
3. Press Play. The actor loads the story on BeginPlay and shows the first line/choices through the default widget. If input does not advance, give the actor input focus as described above or call Advance() from your own UI/input event.

Good for quick playtesting

This is the fastest way to sanity-check a fresh export in-engine before wiring any real UI — drop it in an empty test level and press Play.

Method B — the Actor Component (BPC_YarnDraft)

To drive the story from your existing player character (or any other actor) instead of a standalone actor:

1. Open your player character's Blueprint.
2. Add Component → search BPC_YarnDraft → add it.
3. Select the component and set its Story File Name in the Details panel, same as Method A.
4. The component loads the story and exposes the same line, choice, task, clue, and game-event hooks. Use the default widget for smoke tests, then replace it with your actual game UI when needed.

Game Event cards in Blueprint

To react to a YarnDraft Game Event card:

1. In your actor Blueprint, drag the YarnDraft Dialogue component into the graph.
2. From it, add Bind Event to On Game Event.
3. Run that bind once from BeginPlay.
4. Create a matching custom event, for example HandleGameEvent.
5. Use the Event string to switch on names such as open_door.
6. Break Params with Break Yarn Draft Trigger Params; read values from the Values map with Find, for example key doorId.

If YarnDraft has Event Name = open_door and doorId = test_door_01, Blueprint receives:

Event: open_door
doorId: test_door_01

Audio cards in Blueprint

Audio cards emit data; they do not play sound by themselves. To react in Blueprint:

1. Drag the YarnDraft Dialogue component into the graph.
2. Add Bind Event to On Audio Cue from that component.
3. Run the bind once from BeginPlay.
4. Create a matching custom event, for example HandleAudioCue.
5. Break the cue and use AudioType, AssetPath, Volume, and FadeSeconds to drive your own audio playback.

For a smoke test, print AudioType and AssetPath first. Wire real playback only after those values appear.

When to pick which method

Use Method A for a dedicated "story manager" actor per level, or Method B when the narrative should live and travel with a specific actor (e.g. the player pawn, or an NPC that only talks once triggered).

Beyond the Blueprint wrappers

For full control — custom save/load timing, multiple concurrent stories, or driving the player from C++ — construct UYarnDraftStoryPlayer directly instead of using either Blueprint wrapper. See Game engine export → Use it for the C++ snippet and the full delegate list (OnLine, OnChoices, OnTrigger, OnAudioCue, OnChoiceVoice, OnTaskChanged, OnClueDiscovered, OnFinished).

Entity Data Assets & Gameplay Tags

The editor module also turns your YarnDraft Entities into native UPrimaryDataAsset Data Assets, and can auto-populate registered Gameplay Tags — see Game engine export → Entity Data Assets for the importer workflow (Tools → Import YarnDraft Entity Data Assets, or the Live Sync toolbar button).