Reading a step

A step is a FTaleShardPlayStep. There is no Text pin on it and no Speaker: a project’s node types are authored by its own user, so there is no fixed set of keys to pre-extract — the reasoning is on node meaning is resolved once. A step carries resolved fields, and your game decides what they mean.

#include "TaleShardFieldLibrary.h"
#include "TaleShardStepLibrary.h"
#include "TaleShardStepTypes.h"

namespace TaleShardDocSamples
{
  // Describes a step as text, one line per presented field.
  TArray<FString> DescribeStep(const FTaleShardPlayStep& Step)
  {
    TArray<FString> Lines;

    // TypeCode is a dispatch key: it picks a card - a widget, a layout - or the handler that
    // owns this type's logic. What it must never do is decide what a field MEANS, which is
    // the decision the resolved payload has already made.
    Lines.Add(FString::Printf(TEXT("[%s] %s"), *Step.TypeCode, *UEnum::GetValueAsString(Step.Verb)));

    for (const FTaleShardResolvedField& Field : UTaleShardStepLibrary::GetPresented(Step))
    {
      // Kind is a closed enum, not a string.
      switch (Field.Kind)
      {
      case ETaleShardResolvedFieldKind::RichText:
      {
        // Rendered at sync time. There is no document model downstream.
        Lines.Add(Field.Label + TEXT(": ") + UTaleShardFieldLibrary::GetText(Field).ToString());
        break;
      }
      case ETaleShardResolvedFieldKind::Entity:
      {
        // Already looked up. False when the reference points at nothing.
        FTaleShardResolvedEntity Who;
        if (UTaleShardFieldLibrary::GetEntity(Field, Who))
        {
          Lines.Add(Field.Label + TEXT(": ") + Who.Name);
        }
        break;
      }
      case ETaleShardResolvedFieldKind::Asset:
      {
        // Get Media List is right for one reference and for five. Get Media takes the
        // first, which is correct for one picture and wrong for five. Url is where the
        // bytes are, never an asset path; Id is the id.
        for (const FTaleShardMediaRef& Media : UTaleShardFieldLibrary::GetMediaList(Field))
        {
          Lines.Add(Field.Label + TEXT(": ") + (Media.bHasUrl ? Media.Url : Media.Id));
        }
        break;
      }
      default:
      {
        // An unknown Kind is not an error: a newer producer can legitimately reach an
        // older plugin, and RawType still names the type.
        const FText Text = UTaleShardFieldLibrary::GetText(Field);
        Lines.Add(FString::Printf(TEXT("%s (%s): %s"), *Field.Label, *Field.RawType, Text.IsEmpty() ? TEXT("-") : *Text.ToString()));
        break;
      }
      }
    }

    return Lines;
  }
}

In Blueprint the same reads are nodes: Get Presented on the step, a switch on the field’s Kind, and the field library’s typed reads.

What a step carries

The step is a handle. Its scalars are pins; everything with a shape of its own is read through the TaleShard Step function library, so a Blueprint never copies a list it does not need.

Get Presented already accounts for a node type that declares itself silent, and for a field the author marked as not presentable. That is the “is there anything to show” rule, applied once — do not invent a second one.

What a resolved field carries

The field library

A read naming a shape checks only the value’s shape. One naming a vocabulary or a reference checks the kind as well. None of them fails loudly: a read whose question does not apply answers false, and every list is empty rather than absent.

Prefer the plural reads. Get Entities, Get Media List and Get Variable List are correct for one reference and for five; the singular ones take the first, which is right for one portrait and wrong for five.

A media reference carries Id, Url with Has Url, and Focal with Has Focal. Focal is where the picture’s face is — a 2D vector whose X and Y are each a fraction 0..1 of the picture’s box from its top-left corner, marked once per picture in the editor’s media tab. Read Has Focal first: when it is false, no face is marked and Focal is zero. A widget that crops the picture (a portrait frame, a banner) crops toward Focal, and about the centre when Has Focal is false. The same picture answers the same point wherever it is referenced: a node’s asset field, a character’s $portrait, an entity’s own asset field.

A command reference carries Code, Tag, Args and Arg Variables. An argument the author bound to a project variable holds that variable’s value as of the moment the step was composed, and Arg Variables names the variable at the same position (empty for every other argument). To fire the call later with the values the variables hold then, see firing a call a field holds.

Naming a field without a magic string

Find Field takes a gameplay tag, and the sync registers one per field code under TaleShard.Field. In Blueprint that is the tag picker: rename speaker in the editor, sync, and the tag the node held is gone from the tree — a visible break instead of a silent miss in a shipped build. In C++ the same tag is requested by name, as the samples on this site do.

A repeater’s fields are read through Get Blocks, one block per row, which is what tells two similarly-named fields apart: a node’s own condition field and a per-row condition field inside a repeater live in different places.

A row can hold a list of its own — a repeater declared inside another repeater’s block, one level. Get Blocks on the inner list’s tag answers every outer row’s inner rows, outer row by outer row; Get Blocks Within, with the outer block’s Instance Id, answers that one row’s own. The generated block struct of the outer list carries them already, as a member named after the inner list. An inner row is content, never a choice.

Speaking the line

Get Audio is what this step plays rather than draws, one entry per channel. The engine fills two: sfx, one per field of the node holding a media reference whose file is a sound (a picture or video on the node is never here), and voice, one per line that has a voice-over recording in the language you are playing in. Switch on Channel, never on the node type — audio is a channel, not a node type — and give the switch a default, because Channel is a string so that a later channel breaks no reader.

Play Step Voice does the whole job in one node: it finds the spoken line, resolves it through the media index the sync wrote, plays it, and stops whatever the previous step was saying — so advancing early cuts the line off, which is what a reader expects. Is Speaking is how a game that advances on a timer waits for the line; it does not disable the advance affordance, because a player who wants to move on may. Stop Voice silences it.

The plugin’s dialogue screen does exactly that: it calls Play Step Voice for every step it draws, with no second event and nothing asking what kind of node is playing. The TaleShard Story actor hands it the Media Index the sync wrote — filled in for you when the project has one — and the lines are spoken; with no media index the story plays in silence rather than refusing, and Play Voices on the screen switches it off.

#include "TaleShardStepLibrary.h"
#include "TaleShardStepTypes.h"
#include "TaleShardVoiceLibrary.h"

namespace TaleShardDocSamples
{
  // The clip this step speaks, or false when it says nothing aloud - which is every step in a
  // project with no voice-over.
  bool FindSpokenLine(const FTaleShardPlayStep& Step, FTaleShardResolvedAudio& OutSpoken)
  {
    for (const FTaleShardResolvedAudio& Audio : UTaleShardStepLibrary::GetAudio(Step))
    {
      // Switch on the channel, never on the node type. Audio is a channel: sfx is a sound
      // a node's fields hold, voice is the recorded line. A channel is a string so a later
      // one breaks no reader, so anything else is skipped rather than guessed at.
      if (Audio.Channel != TEXT("voice")) continue;

      // The first one. Two voice entries on one step are two lines and belong one after the
      // other; queueing them is your game's pacing decision.
      OutSpoken = Audio;
      return true;
    }
    return false;
  }

  // Play it, or say why not. Audio never blocks a story.
  //
  // Play Step Voice does the whole job - it resolves the media id through the index, plays the
  // clip, and stops whatever the previous step was saying. This is what to write when you want
  // the parts yourself: a mixer of your own, a mute list, a subtitle keyed by line.
  void SpeakStep(
    UObject* WorldContextObject,
    const UTaleShardMediaIndex* MediaIndex,
    const FTaleShardPlayStep& Step,
    const TSet<FString>& MutedVoices)
  {
    FTaleShardResolvedAudio Spoken;
    if (!FindSpokenLine(Step, Spoken)) return;

    // Voice Code is the speaking character's voice, for a per-character mute. It is absent
    // when they are uncast, and that is not a reason to withhold the clip: a take exists, so
    // it plays.
    if (Spoken.bHasVoiceCode && MutedVoices.Contains(Spoken.VoiceCode)) return;

    // Line Id is the same identity a translation and a recording script use, so a caption or
    // a replay keys off it rather than off the field's position.
    UTaleShardVoiceLibrary::PlayStepVoice(WorldContextObject, MediaIndex, Step);
  }
}

A voice entry carries two things an sfx entry does not. Line Id is the line the clip belongs to — the same identity Get Line Id gives a field, and the one a translation and a recording script use — so a caption or a replay keys off it rather than off the field’s position. Voice Code is the speaking character’s voice, which is what a per-character mute keys off; it is absent when they are uncast, and that is not a reason to withhold the clip.

The clip is addressed by Media Id and resolves exactly as a portrait does. Step Media Plan already includes it, and Board Media Plan includes a board’s clips when you pass the language you are playing in.

Trace

A step carries a trace — which scripts ran, which gates were evaluated, and how many branches were discarded as unsupported. It is deliberately not documented in detail here: the trace’s gate records do not currently mean the same thing in this runtime as they do in the editor’s play mode, so a page describing them would be describing a divergence rather than a contract. Use those for debugging, not for logic, until that is closed.

The script runs are a contract, and one part of them is read for logic: each run’s Rolls lists every draw its script made — a roll(20) that came up 14, with its kind, its arguments and what came up — which is what a game that shows dice reads. A step’s runs include those of every silent node walked through on the way to it, before its own; each run’s Node Id says which node it belongs to.

The other part read for logic is Received: what the exits taken on the way to this step handed over — every entry of every itemCounts field on each fired exit’s row, in walk order, each an Item Count (the item, resolved like any entity when the step is composed — after the exit’s scripts and this node’s own have run, like the cast — and its count). A Loot roll’s drawn outcome reaches the player here, on the step after the roll, and only that outcome’s entries do; the plugin keeps no inventory and merges nothing, so an item written twice arrives twice. Empty on most steps. A language change redraws a step with the same entries; a restored save lists none. The items are never on a step’s Cast: they are the things a row hands over, not who is on stage.

Next

Choices, and why one is locked.