Entity display: name, colour, portrait

An entity reference on a step arrives already looked up. The session’s entity palette is the one place that turns it into the three things a game actually draws: a name, a colour, and a portrait.

#include "TaleShardEntityDisplay.h"
#include "TaleShardSession.h"
#include "TaleShardStepTypes.h"

namespace TaleShardDocSamples
{
  // The speaker's name and colour, as one line of text.
  FString DescribeSpeaker(UTaleShardSession* Session, const FTaleShardResolvedActor& Actor)
  {
    // The one place that decides what a speaker looks like, so a game never reads the raw
    // entity fields for this.
    const FTaleShardEntityDisplay Display = Session->GetEntityPalette()->Of(Actor);

    // Colour is user data: an author may leave it unset, and bHasColor is how you find out.
    // Color Or takes your own fallback rather than inventing one.
    const FLinearColor Tint = UTaleShardEntityPalette::ColorOr(Display, FLinearColor::White);

    return Display.Name + TEXT(" ") + Tint.ToFColor(true).ToHex();
  }
}

In Blueprint: Get Entity Palette on the session, then Of with an actor from Get Cast. Use it rather than reading the entity’s raw fields. Every entity carries a small set of intrinsics — name, code, colour, voice, description, portrait — under reserved keys, and those are what make a shipped preset possible: a binding to a custom field code binds one that may exist in no project, while a binding to an intrinsic works everywhere.

$voice is the code of the voice this character is cast to, and it is absent when they are uncast. It is what answers which voice speaks this line with no naming convention: the speaker is already resolved per step, so the voice for a line is the speaker’s — which is why a voice clip on a step carries that code rather than making you look it up. $description and $portrait are absent the same way, when nothing was written and when no picture is set.

Four ways in

What a display carries

An entity that is an input action

A project can declare its input actions as records — Crouch, Interact — whose definition says a mention of them draws as a keycap. Is Action tells you an entity is one, and its Code is the name your game maps to its own input action; the record’s Name is the action in the player’s language. Every read of the palette sets it — Of, Of Entity, By Code, By Id and Resolve Mention — because the palette reads it off the entity’s definition in the payload. FTaleShardEntityDisplay::Of called on its own cannot see the payload unless you pass it as the third argument, and answers false without it.

A mention of such a record is drawn by your own code: the palette marks it as an action and leaves the binding to you, so a rebind reaches every prompt. How to answer it, and how a glyph is treated, are on drawing a line of text.

Colour is user data

Inventing a colour is worse than it sounds. A game that substitutes its own accent for an unset entity colour will show two characters in the same colour and imply a relationship the author did not author.

Contrast

By default the palette hands you the author’s colour untouched and unmeasured. Tell it what it is drawing on with Set Readable On — a background hex and a minimum contrast — and every display it produces afterwards carries a colour adjusted to be readable there, with Color Outcome saying what was done. Set Contrast Off returns to the default.

The outcome is reported rather than hidden because a silently corrected colour is a colour the author did not pick, with nothing on screen saying so. Surface it in a debug view; leave it out of the game.

Portraits

The portrait arrives as a media reference, not as a loaded asset. Resolve it through the media library and load it with the Load Media action; loading is yours, and that is deliberate — when and whether to load is a game’s decision, and a plugin that loaded eagerly would make it for you at the worst possible moment.

Next

Implementing commands — how a story makes your game do something.