Starting a session

A session is the one object a game holds to play a story. It is not a widget and ships none: bind its On Step Presented event, draw what it hands you, and call its verbs when the player acts. There are two ways to get one, and the difference is who owns it.

The component route

Add a TaleShard Player component to an actor and fill in its Details panel:

The component owns its session for as long as the actor lives and releases it when the actor ends play. Every event of the session is re-raised on the component, and every verb and read of the session is forwarded from it under the same name — so a Blueprint that drives a story from the actor never touches the session object directly, and it can bind before a story exists.

#pragma once

#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "TaleShardStepTypes.h"
#include "DocStoryActor.generated.h"

class UTaleShardPlayerComponent;
class UTaleShardSession;

// An actor that plays a story: the component owns the session, the actor draws what it presents.
UCLASS()
class ADocStoryActor : public AActor
{
  GENERATED_BODY()

public:
  ADocStoryActor();

protected:
  virtual void BeginPlay() override;

private:
  UFUNCTION()
  void HandleStepPresented(UTaleShardSession* Session, const FTaleShardPlayStep& Step);

  UPROPERTY(VisibleAnywhere, Category = "TaleShard")
  TObjectPtr<UTaleShardPlayerComponent> Player;
};

#include "DocStoryActor.h"

#include "Support/DocFictions.h"
#include "TaleShardPlayerComponent.h"
#include "TaleShardStepLibrary.h"

ADocStoryActor::ADocStoryActor()
{
  // The payload, the policy asset, the command handler class and the node handlers are set
  // on the component in the Details panel. Play On Attach is off here only so that this
  // actor can bind before the first step; with it on, the component plays the moment the
  // actor begins play.
  Player = CreateDefaultSubobject<UTaleShardPlayerComponent>(TEXT("Player"));
  Player->bPlayOnAttach = false;
}

void ADocStoryActor::BeginPlay()
{
  Super::BeginPlay();

  // Bind to the component, not to the session: these bindings can be made before a story
  // exists, which removes the ordering trap of waiting for the session to be built.
  Player->OnStepPresented.AddDynamic(this, &ADocStoryActor::HandleStepPresented);

  // Play the author's start, or name a board and node. Every verb answers false with a
  // reason instead of failing quietly.
  FText Reason;
  if (!Player->Play(FGameplayTag(), NAME_None, Reason))
  {
    FDocGameLog::Note(Reason.ToString());
  }
}

void ADocStoryActor::HandleStepPresented(UTaleShardSession* Session, const FTaleShardPlayStep& Step)
{
  // Presented, not Fields: the engine has already decided what belongs on screen.
  FDocSpeechBubble::Show(UTaleShardStepLibrary::GetPlainText(Step).ToString());
}

FDocGameLog and FDocSpeechBubble are not plugin API. They stand in for your own game code, and they are declared in a shim header on this site so that is visible rather than implied.

The code route

A session can also be built without a component, from the TaleShard game-instance subsystem:

A session built this way is owned by whoever built it. A component can still take it over with Adopt, which is how a story that outlives a scene gets a new presenter: build the session on the subsystem, adopt it from each actor that draws it, and let Release drop the actor’s hold without stopping the story.

Both routes take a policy at construction, and it freezes there. One policy setting can only be honoured at that moment: the one that asks the engine to offer a board’s remaining ways in when a path ends. The engine takes it as a construction argument and never re-reads it, which is why a policy cannot be swapped on a live session.

The verbs

Every verb answers true when it ran and false with a reason when it was refused, and a refusal is also reported on the diagnostics channel. A mistimed press is different: Advance while nothing is presenting, or Choose while nothing is awaited, is ignored silently, because a player mashing Continue during a fade is normal.

The events

The one ending On Ended does not announce is a playthrough abandoned by starting another: Restart replaces the story without the old one ever leaving a playing state.

Five things that are easy to get wrong

• Play is not Restart. Play keeps the world; Restart throws it away. A “new game” button that calls Play plays the new game with the old game’s variables.
• Start at the author’s start node, not just the board. Leaving Start Node empty does this. Naming only a board falls back to that board’s derived way in, which is a root with an outgoing edge — a real board is full of isolated strays and every one of them is a root.
• A transfer node produces no step. A node that carries the playthrough into another board is traversal, not presentation, so it looks like nothing happened. That is correct.
• Read the step’s Awaiting rather than guessing from the verb. Advance on a step awaiting a choice does nothing, and so does Choose on a step awaiting an advance.
• Back past the first step still rewinds the variables. The state as of before the first step is captured, so navigation and rollback cannot disagree.

Language

A host deals in language codes. The engine’s storage key stops at this boundary: a project whose master language is English keys that content under a default key rather than under en, so the engine’s language is that key while the player is reading English.

Get Language is empty when the project never named a master language. That is a real answer rather than a gap to paper over — inventing en would put the wrong language on a story not written in it.

Next

Reading a step — what the engine hands you, and how to read it.