NPC story encounter data
Bind personal conversations, terminal outcomes and optional quests to a deployed character.
Encounter data is separate from placement coordinates. Moving a character preserves each player’s recorded outcomes.
Where the files live
Files live at data/<namespace>/npc_story_encounters/**/*.json. The path determines the encounter ID; ordinary pack priority resolves a shared path. A unique NPC marker binds that ID through Deployment.Encounter. The character type must match.
Minimal example
{
"character": "isekaiexpansion:mahoutsukai_evelina",
"locked_message": "message.isekaiexpansion.evelina_demo.await_body",
"steps": [
{
"dialogue": "isekaiexpansion:npc/unique/isekaiexpansion_mahoutsukai_evelina/quest/garden_demo/first_meeting",
"milestone": "isekaiexpansion:evelina_demo/introduced",
"requirements": {
"requires": [
"isekaiexpansion:chapter_01/body_built"
],
"excludes": []
},
"completion_ends": [
"end_intro"
],
"quest_after": "isekaiexpansion:evelina_demo/first_record"
},
{
"dialogue": "isekaiexpansion:npc/unique/isekaiexpansion_mahoutsukai_evelina/quest/garden_demo/first_record",
"milestone": "isekaiexpansion:evelina_demo/first_record",
"requirements": {
"requires": [
"isekaiexpansion:evelina_demo/introduced"
],
"excludes": []
},
"completion_ends": [
"end_complete"
]
}
]
}
Fields
| Field | Type | Default | What it does |
|---|---|---|---|
character | identifier | Required | Entity type that may use this encounter. |
locked_message | string | Required | Nonblank translation key shown when the next step requirements are unmet. |
steps | array<object> | Required | 1–32 ordered steps. |
steps[].dialogue | identifier | Required | Unique dialogue ID within this encounter. |
steps[].milestone | identifier | Required | Unique personal completion fact; an already recorded step is skipped. |
steps[].requirements | object | Required | Named requirements evaluated on selection and completion. |
steps[].requirements.requires | array<identifier> | [] | Up to 64 unique IDs, at most 256 characters each. Every step after the first must require its immediate predecessor’s milestone. |
steps[].requirements.excludes | array<identifier> | [] | Same limits; disjoint from requires. A step cannot require or exclude its own completion fact. |
steps[].completion_ends | array<string> | Required | 1–16 distinct terminal state keys using lowercase letters, digits and underscores. Natural closure at another end records nothing. |
steps[].quest_after | identifier | Absent | Optional side_story quest accepted after this step completes; ordinary eligibility still applies. |
Validation
Missing fields, invalid identifiers, unknown fields, duplicate step identities and out-of-range counts reject that file with an error. Identifiers require an explicit namespace. A missing dialogue refuses to start. Completion keys must name end_dialogue nodes in the graph. Credit requires natural closure, the same actor and session, and distance within 12 blocks. Forced closure or an unlisted terminal grants no completion. Encounters precede ordinary menus; opening and mainstory routes take precedence over encounters. Ordinary interaction resumes after all steps complete.
In Evelina’s garden side story, every natural introduction exit reaches end_intro, including saying goodbye after she gives her name. The follow-up reaches end_complete whether the player discusses the garden or their body, postpones the topic or declines it. These facts record the conversation, with no item submission or research result. Her ordinary menu then becomes available. Choosing to leave after the introduction does not make her repeat her name next time.
Reloading
/reload reloads encounters and clears pending session credit, without clearing saved personal milestones. Selection stays server-side; graphs use the existing dialogue protocol.
The current garden demo places Evelina at local block (-112, 24, 60), with feet (-111.5, 24, 60.5), south yaw 0, STAY, no home, and a ±40° idle gaze. Its separate remote_sky_garden_evelina/demo-v1 native layer binds isekaiexpansion:evelina_garden_demo. Moving her later requires a deployment/content revision; personal facts remain independent of coordinates. The five-layer prototype has a new fingerprint and requires a fresh test world. Existing saves are not rewritten.