Images & Media

StoryFlow dialogue nodes can include images for character portraits, inline illustrations, and full-screen backgrounds. This guide covers how image assets are imported, resolved, and displayed in the Unity plugin.

How Images Work

Images in StoryFlow are referenced by dialogue nodes via asset keys. When a project is imported into Unity, the importer converts image files into Texture2D assets with proper sprite import settings, then stores references in ResolvedAssets dictionaries. At runtime, the execution context resolves these keys to Sprite objects that you can display in your UI.

There are two levels of asset storage:

• Character assets - Character portraits are stored directly on each StoryFlowCharacterAsset.ResolvedImage. They are defined in characters.json and shared across all scripts.
• Script-level assets - Defined per script file. Images used in a specific script's dialogue nodes (illustrations, background images, etc.) are stored on StoryFlowScriptAsset.ResolvedAssets.

Dialogue Images

The current dialogue image is available on StoryFlowDialogueState.Image as a Sprite. This field may be null if no image is assigned and the image was reset. Read it each time OnDialogueUpdated fires and apply it to a Unity UI Image component.

void OnDialogueUpdated(StoryFlowDialogueState state)
{
    if (state.Image != null)
    {
        dialogueImage.sprite = state.Image;
        dialogueImage.gameObject.SetActive(true);
    }
    else
    {
        dialogueImage.gameObject.SetActive(false);
    }
}

Character portrait images are separate from the dialogue Image field. They are accessed through StoryFlowDialogueState.Character.Image, which is also a Sprite. Character images are resolved from each StoryFlowCharacterAsset.ResolvedImage since characters are defined in characters.json and shared across all scripts.

void OnDialogueUpdated(StoryFlowDialogueState state)
{
    // Dialogue illustration
    if (state.Image != null)
    {
        sceneImage.sprite = state.Image;
        sceneImage.gameObject.SetActive(true);
    }
    else
    {
        sceneImage.gameObject.SetActive(false);
    }

    // Character portrait (separate from dialogue image)
    if (!string.IsNullOrEmpty(state.Character.Name) && state.Character.Image != null)
    {
        characterPortrait.sprite = state.Character.Image;
        characterPortrait.gameObject.SetActive(true);
    }
    else
    {
        characterPortrait.gameObject.SetActive(false);
    }
}

Background Images

Background images are set via dedicated SetBackgroundImage nodes rather than being attached to dialogue nodes. They are intended for full-screen visuals, scene transitions, or environment art that exist outside the dialogue box.

Background images are set via the SetBackgroundImage node in the StoryFlow Editor. When the runtime processes this node, it broadcasts the OnBackgroundImageChanged event with the resolved Sprite:

component.OnBackgroundImageChanged += (sprite) => {
    backgroundImage.sprite = sprite;
};

The background image persists until explicitly changed by another SetBackgroundImage node or cleared by passing an empty value. It is stored internally on the execution context as PersistentBackgroundImage and survives across dialogue node transitions.

Asset Resolution

The asset resolution system is the bridge between StoryFlow's string-based asset references and Unity's loaded asset objects. It operates at two levels:

• StoryFlowScriptAsset.ResolvedAssets - Per-script assets. Images used only within a specific script's nodes are resolved from this dictionary.
• StoryFlowProjectAsset.ResolvedAssets - Project-wide assets shared across all scripts. Note: character portrait images are stored on individual StoryFlowCharacterAsset objects, not in this dictionary.

The StoryFlowComponent provides a generic ResolveAsset<T> method that checks both levels automatically, prioritizing script-level assets:

// Resolves an asset by key, checking script assets first, then project assets
T asset = component.ResolveAsset<Sprite>("assetKey");

// Example: resolve a specific image
Sprite illustration = component.ResolveAsset<Sprite>("asset_image_forest");
if (illustration != null)
{
    myImage.sprite = illustration;
}

This two-level lookup means script-specific assets can override project-level assets with the same key, giving you fine-grained control over which asset is used in a given context.

Import Process

When you import a StoryFlow project via the editor importer, the following happens for image assets:

1. The importer reads asset references from each script's JSON data and from characters.json, then imports the referenced image files from the exported build/ directory.
2. Each image is imported as a Texture2D asset with sprite import settings applied (texture type set to Sprite, appropriate filter mode, etc.).
3. Script-specific image references are stored as ResolvedAssetEntry entries on the corresponding StoryFlowScriptAsset. Character portrait images are stored directly on each StoryFlowCharacterAsset.ResolvedImage.
4. At runtime, the ResolvedAssetEntries serialized list is lazily rebuilt into a Dictionary<string, Object> for fast lookup.

Character images from characters.json are stored on individual StoryFlowCharacterAsset ScriptableObjects. Script-specific images (dialogue illustrations, background images referenced only in that script) go into the corresponding script asset's ResolvedAssets.