Reading a step

using System.Collections.Generic;
using TaleShard.Runtime.Engine;

namespace TaleShard.Docs.Samples
{
    public static class ReadAStep
    {
        public static IReadOnlyList<string> Describe(PlayStep step)
        {
            var lines = new List<string>();

            // TypeId is a dispatch key: it picks a card — a prefab, 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("[" + step.Node.TypeId + "] " + step.Verb);

            foreach (ResolvedField field in step.Presented)
            {
                // Kind is a closed enum, not a string.
                switch (field.Kind)
                {
                    case FieldKind.RichText:
                        // Rendered at sync time. There is no document model downstream.
                        lines.Add(field.Label + ": " + field.Rich.Text);
                        break;

                    case FieldKind.Entity:
                        // Already looked up, and null-safe.
                        ResolvedEntity? who = field.Entity();
                        if (who != null) lines.Add(field.Label + ": " + who.Name);
                        break;

                    case FieldKind.Asset:
                        // MediaList() is right for one reference and for five. Media() takes the
                        // first, which is correct for one picture and wrong for five.
                        // Url is where the bytes are, never an asset key; Id is the id.
                        foreach (MediaRef media in field.MediaList())
                        {
                            lines.Add(field.Label + ": " + (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.
                        string text = field.Text();
                        lines.Add(field.Label + " (" + field.RawType + "): " + (text ?? "-"));
                        break;
                }
            }

            return lines;
        }
    }
}

using TaleShard.Docs.Fictions;
using TaleShard.Runtime.Engine;
using TaleShard.Unity;
using UnityEngine;
using UnityEngine.UI;

namespace TaleShard.Docs.Samples
{
    public sealed class LinePresenter : MonoBehaviour
    {
        [SerializeField] private Text _line;
        [SerializeField] private Text _speaker;

        public void Present(PlayStep step)
        {
            _line.text = "";

            // Presented, not Fields: the engine has already decided what belongs on screen.
            foreach (ResolvedField field in step.Presented)
            {
                string text = field.Text();
                if (text == null) continue;
                _line.text += text + "\n";
            }

            // Cast is already resolved, and it says who is speaking — so there is no need to
            // search the fields for an entity and guess.
            if (step.Cast.Count > 0)
            {
                EntityDisplay display = EntityDisplay.Of(step.Cast[0]);
                _speaker.text = display.Name;
                _speaker.color = display.ColorOr(Color.white);
            }

            // Your code, not the plugin's.
            SpeechBubble.Show(_line.text);
        }
    }
}

using TaleShard.Runtime.Engine;

namespace TaleShard.Docs.Samples
{
    public static class SpokenLine
    {
        /// <summary>
        /// The clip this step speaks, or false when it says nothing aloud — which is every step
        /// in a project with no voice-over.
        /// </summary>
        public static bool Find(PlayStep step, out ResolvedAudio spoken)
        {
            spoken = null;

            foreach (ResolvedAudio audio in step.Audio)
            {
                // Switch on the channel, never on the node type. Audio is a channel: sfx is the
                // 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 != "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.
                spoken = audio;
                return true;
            }

            return false;
        }

        /// <summary>Play it, or say why not. Audio never blocks a story.</summary>
        public static string Play(PlayStep step, IVoiceMixer mixer)
        {
            ResolvedAudio spoken;
            if (!Find(step, out spoken)) return null;

            // VoiceCode 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.VoiceCode != null && mixer.IsMuted(spoken.VoiceCode)) return null;

            // MediaId, never a path and never a filename. Resolve it the way you resolve a
            // portrait: MediaAddress.From(spoken.MediaId), then your media library.
            //
            // Line 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.
            mixer.Speak(spoken.MediaId, spoken.Line.ToString());
            return spoken.MediaId;
        }
    }

    /// <summary>Your game's audio, not the plugin's.</summary>
    public interface IVoiceMixer
    {
        bool IsMuted(string voiceCode);

        void Speak(string mediaId, string lineId);
    }
}