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 your host game can read them through the runtime API.

This is bolt-on metadata for the host game. The storylet engine never reads these values, and they're 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. Some 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 keeping a separate spreadsheet or data file that pairs each storylet with, say, an audio track, that's a good sign the information belongs in Game Data.

Defining fields

Go to 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 can't).
  • 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 only affects 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 once at least one field is defined for that entity kind.

Values save 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 sees them as undefined.

How values reach your game

When you publish, every entity's Game Data values travel inside the .storyworld bundle. Your game or installation reads them back through the StoryletEngine plugin for its engine: each plugin offers a "get game data" call that you hand a storylet (or zone, site, or pin) and a field's Game ID, and it returns the value you authored.

The wiring on the game side is covered in the plugin docs (Unreal, Unity, JavaScript). As an author, you just define the fields and fill in the values; the people building the game take it from there.

Renaming and deleting fields

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

Renaming the Game ID changes the key your game uses to look up the value. Your own values are kept, but the next time you publish, anyone reading the old Game ID on the game side has to switch to the new one. The editor asks you to confirm the change 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. You can't undo this.

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

So 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.