Data Assets

A Data Asset is a .sfd file containing named, typed values. Use one for shared game data such as item properties, quest settings or NPC attributes. Data Assets can inherit declarations and values from a parent asset. A child can override a value without changing its parent.

Importing Data Assets

Export your project from StoryFlow Editor, then import it into Godot or use Live Sync. The exported data-assets.json contains the Data Asset definitions. The plugin also imports image and audio files referenced by Data Asset values into the shared project asset pool. You do not need to import each .sfd file separately.

Reading and Writing Values

Call the accessors on a StoryFlowComponent or the StoryFlowRuntime autoload. Pass an asset ID or a unique display name, then the declared variable name. IDs remain stable when files are renamed. A typed getter returns its supplied default when the asset, variable or type does not match. A setter returns false if the write cannot be applied.

extends Node

@onready var storyflow: StoryFlowComponent = %StoryFlowComponent

func _ready() -> void:
    var price: int = storyflow.get_data_asset_int("shopItem", "price", 0)
    var changed: bool = storyflow.set_data_asset_int("shopItem", "price", 25)

    for variable_name in storyflow.get_data_asset_variable_names("shopItem"):
        print(variable_name)

    var any_value: StoryFlowVariant = storyflow.get_data_asset_variant("shopItem", "price")

The typed pairs are get_data_asset_bool() and set_data_asset_bool(), int, float, string and enum. The string pair also reads or writes image, audio and character values, which are stored as asset keys or character references. get_data_asset_variant() reads a scalar or container as a StoryFlowVariant.

Arrays and Maps

Use get_data_asset_variant() to read an array or map. Pass an array of StoryFlowVariant elements to set_data_asset_array(). For maps, pass parallel arrays of raw keys and StoryFlowVariant values to set_data_asset_map(). The asset's declared types determine which values are accepted. Both setters return bool.

var tags: StoryFlowVariant = storyflow.get_data_asset_variant("shopItem", "tags")
if tags != null:
    for tag in tags.get_array():
        print(tag.to_display_string())

storyflow.set_data_asset_array("shopItem", "tags", [
    StoryFlowVariant.from_string("rare"),
    StoryFlowVariant.from_string("tradable"),
])
storyflow.set_data_asset_map("shopItem", "stock", ["sword", "shield"], [
    StoryFlowVariant.from_int(2),
    StoryFlowVariant.from_int(1),
])

Lifetime and Saves

A runtime write changes the current session's value. It does not edit the .sfd file or the imported project definition. All components see the same session value. The plugin saves these changes with global variables, characters and once-only options. reset_all_state() restores Data Assets to their imported values.