Story Model
Every story in Stalker PDA is built as a three-level hierarchy. Understanding this hierarchy is the key to the rest of this documentation.
Story
└─ Chapter 1
├─ Stage A
├─ Stage B
└─ Stage C
└─ Chapter 2
└─ ...
- Story — the top-level entity the player sees in the quest list (for example, "Loot from the Cordon" or "Sidorovich's Trader Job").
- Chapter — a major narrative block of the story (for example "Arrival" / "Negotiations" / "Resolution"). A chapter has its own graph of stages, its own music, and its own points and squads on the map.
- Stage — the smallest unit of the plot: a single scene, a single line, or a single dialogue choice.
Stages are connected to each other by transfers (
transfers), forming a branching graph — this is exactly how a story looks in the story editor: nodes on a canvas connected by links.
Story description (info.json)
Every story is described by a common passport:
| Field | Purpose |
|---|---|
id | Unique story identifier |
title | The title the player sees |
desc | Short description/blurb |
icon | The story's icon in the quest list |
access | The minimum player role that can access the story: USER, TESTER, MODERATOR, ADMIN |
The access field is a convenient way to roll out a story gradually: first make it visible only to testers,
then publish it for all players (USER). More details in Publishing and Access.
Chapter
id, title?, music?: string[],
stages: [...], // all of the chapter's stages — the plot graph itself
points?: { [map]: [...] }, // points the chapter adds to the map
spawns?: { [map]: [...] }, // NPC squads the chapter adds to the map
missions?: [...] // journal quests tied to the chapter
A chapter isn't just dialogue. It can also add content to the game world map: new points of interest (quest markers, stashes, traders, transitions) and NPC squads on specific locations. More details in Points on the Map and Squads and Territories.
music is a list of tracks that play during the chapter (the scene's background music).
Stage
A stage is the "atom" of a story. It has a type, text (or several text variants depending on conditions), transfers to other stages, and actions that run when the player enters it.
id, type_stage, title?, background?,
message?, type_message?,
texts?: [{ text, condition }],
transfers?: [{ text, stage, condition }],
actions?: { command: [arguments] },
data?: { map, pos }, // for stages that transfer to the map
editor?: { x, y } // the node's position on the editor canvas — has no effect on gameplay
Stage types (type_stage)
| Value | Meaning |
|---|---|
0 | Regular scene — shows text/a message |
1 | Conversation scene (dialogue) — rendered as a character's line |
4 | Map transition — opens the game map at a given point (data.map, data.pos) |
5 | Load another chapter — a technical stage that hands control to another chapter of the story |
6 | Transfer to a trader — opens the trading window |
Message types (type_message)
| Value | Meaning |
|---|---|
0 | Regular message (neutral, system-style) |
1 | Dialogue message — visually rendered as a character's line in a dialogue |
A detailed breakdown of texts, transfers, and conditional line visibility is in
Stages and Dialogues.
Where to go next
- Stages and Dialogues — how a branching dialogue is built.
- Conditions — the condition language shared by stages, points, and squads.
- Actions — what a story can do to the player and the world.
- Variables and Placeholders — how to store progress and interpolate text.
- Missions and Checkpoints — the quest journal.