Storylet Studio

Game Data

Game Data lets you attach author-defined metadata to storylets, zones, sites, and pins — beyond the fields Storylet Studio itself uses. The values travel with the published .storyworld bundle and can be read by your host game through the runtime API.

This is bolt-on metadata for the host game. The storylet engine never reads these values, and they are not queryable from conditions or outcomes. If a value needs to drive narrative logic, use a Property instead.

When to use Game Data

Reach for Game Data when your host game needs to know something Storylet Studio itself doesn't care about. Typical cases:

  • A dialogue script ID to run when a particular storylet plays (e.g. village_arrival_inn).
  • An audio cue ID for the soundtrack track to play at a site.
  • A difficulty tier integer used by the game UI to badge cards.
  • A map-marker icon ID for pins.
  • Any per-entity flag, ID, or note your game needs at runtime.

If you find yourself maintaining a parallel data file keyed by gameId (e.g. storyletAudioMap.ts), that's a good signal to move it into Game Data.

Defining fields

Visit Management → Game Data in the left sidebar. The page has four tabs — one per entity kind:

  • Storylets
  • Zones
  • Sites
  • Pins

Click + Field to define a new field. Each field has:

  • Name — display label shown in the per-entity editor.
  • Game ID — the URL-safe identifier exposed to your host game (e.g. audio-cue, difficulty-tier). Auto-derived from the Name until you edit it. Must be unique within the entity kind (a Site field and a Storylet field can both use audio-cue, but two Storylet fields cannot).
  • Type — Number, Text (single line), TextArea (multi-line), or Boolean.
  • Purpose — author-facing help text shown alongside the input on each entity.

Use the ↑ / ↓ buttons to reorder fields; this affects only the order they appear in the per-entity editor.

Type cannot be changed once a field is created. If you need to change the type, delete the field and add a new one.

Setting values per entity

Once a field is defined, every entity of that kind grows a new Game Data tab in its editor:

  • Storylets — Game Data tab in the storylet editor (alongside Details / Condition / Content / Outcomes / Locations).
  • Zones / Sites / Pins — Game Data tab in the side panel on the Storymap Design canvas.

The tab only appears when at least one field is defined for that entity kind.

Values are saved automatically as you edit (on blur for text and number fields, immediately for booleans). Empty values for Number / Text / TextArea are stored as "not set" — the host game will see them as undefined.

How values flow to the host game

When you publish, every entity's Game Data values are bundled inline:

{
  "storylets": [
    {
      "id": "st_arr01x",
      "gameId": "arrival-inn",
      "title": "...",
      "gameData": { "audio-cue": "village_arrival_theme", "difficulty-tier": 1 }
    }
  ],
  "gameDataFields": {
    "storylet": [
      { "gameId": "audio-cue",      "name": "Audio Cue",   "kind": "text" },
      { "gameId": "difficulty-tier","name": "Difficulty",  "kind": "number" }
    ]
  }
}

In your host game, use the runtime helpers (or just read the property directly):

import { getGameDataFields, getGameDataValue } from "@storylets/engine";

// Discover the schema (e.g. for a debug inspector).
for (const field of getGameDataFields(world, "storylet")) { /* ... */ }

// Read a value off a drawn storylet.
const audioCue = getGameDataValue<string>(storylet, "audio-cue");
const tier     = storylet.gameData?.["difficulty-tier"];

The engine ships getGameDataFields() and getGameDataValue() helpers; the matching API on the Unreal plugin is Storylet Engine > Get Game Data Fields / Get Game Data Value on a session. A player shell calls one of these per storylet to pull the fields it cares about.

Renaming and deleting fields

Renaming the Name or editing the Purpose is harmless and saves automatically.

Renaming the Game ID changes the key your host game uses to look up the value. Internally, the rename is free — Storylet Studio keys values by a stable internal id, not the gameId — but the next time you publish, any host-game code referencing the old gameId will need to be updated. The editor shows a confirm button when you change the Game ID to make this explicit.

Deleting a field also clears the matching value from every entity that has one. Storylet Studio shows a confirm dialog with the count of affected entities before the deletion runs. This cannot be undone.

Lifecycle: copy and clear

Game Data plays nicely with the Management operations:

Action Field definitions Per-entity values
Duplicate Storyworld without content Copied Not copied
Duplicate Storyworld with content Copied Copied (remapped to the new field IDs)
Clear All Story Content Kept Cleared
Delete Storyworld Deleted Deleted

This means a duplicate without content gives you a blank narrative slate that already knows your custom-metadata schema, and Clear All Story Content gives you a clean canvas without throwing away your field definitions.