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. It receives the assets sections of global-variables.json and characters.json as well, so a global Image or Audio variable, a custom image or audio character variable and a character map value all resolve here. Note: a character's own portrait is also stored directly on its StoryFlowCharacterAsset.ResolvedImage.

Both pools, the project's and each script's, are emptied and repopulated on every import. An asset you remove or rename in the StoryFlow Editor therefore stops resolving in Unity on the next sync instead of lingering as a stale entry pointing at whatever it used to be.

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.

For character portraits, prefer GetCharacterPortrait(characterPath, assetKey) over ResolveAsset<Sprite>. It additionally checks the character asset's own resolved-assets pool before falling back to script and project pools, which is the correct lookup order for character-scoped portraits, and for the character's current portrait it falls back one last time to the sprite baked onto the character asset as ResolvedImage when no pool holds the key. Passing an empty assetKey resolves the character's current ImageAssetKey, which reflects any setCharacterVar mutations on the Image field.

StoryFlowComponent sf = GetComponent<StoryFlowComponent>();

// Current portrait for any character (not just the speaker)
Sprite portrait = sf.GetCharacterPortrait("characters/elder");

// Alternate pose stored on an image-typed character variable
Sprite cheering = sf.GetCharacterPortrait("characters/elder", "elder_cheer");

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.

What Gets Rewritten

Copying is skipped when nothing changed. Before a media file is written, the source and the destination are compared by length and then by content, and an identical destination is left alone. A routine sync therefore produces no rewrite, no ForceUpdate reimport, no texture recompression and no version control traffic for media you did not touch. A file referenced by several scripts is settled once per import rather than once per reference.

The skip check is safe against a deleted output folder. Resolved references are certified by GUID as well as by path, so deleting the imported media folder in the Project window and syncing again is not mistaken for "nothing changed": the assets come back with new GUIDs, the certification differs and the referencing assets are rewritten to match. A hash is recorded only after the save actually reaches disk, so a file that failed to write is retried on the next sync rather than skipped forever.