References Links for Data Parser Schema

Story Structures[edit | edit source]

The structure of all stories in Cyber Knights is created by moving between story nodes, Legwork and missions.

A Story Node represents a key state in a story, a moment where you can pause and say "the story is right here for now until time runs out or I make a decision." As a story progresses, its Story Nodes are made active (added to the database) and removed when completed in some form. Generally, one Story Node will one or more additional Story Nodes, Missions or Legworks before it is removed until the end of the story when a cleanup Story Node is the final node.

While a Story Node is active, Blocks that link to it are shown on the timeline, merc roster page or contact page. So, if we are in this moment of the story, we can see which Blocks (conversations you can start / actions you can take) are available by looking for Blocks which have a StoryNodeId matches the active StoryNodeId.

For a storyline, the the flow is generally like this:

The starting Story Node is added by a Vignette, ProcGenLegwork or ProcGenMission Block.
The Story Node either expires (forcing an action) or the player interacts with one of its Blocks manually
The resulting Block executes, which usually runs a Dialog and presents a Choice to the player.
The final result of this Block execution is the addition of a Mission, Story Node or Legwork (or more than one), which moves the story forward, perhaps to a period of waiting, to a tactical mission or to another decision point.
Eventually the story concludes and a cleanup Story Node is added.Note that all stories are responsible for their own cleanup. If a storyline tagged contacts and players with a TempStoryId, created temporary characters, or any other temporary changes, the cleanup StoryNode is responsible for cleaning those up and removing TempStoryIds. All exits - early, late or anywhere in between - from the storyline need to lead to a cleanup node (there might be multiple, depending on story complexity)

Story and Dialog[edit | edit source]

Block[edit | edit source]

A Block is the fundamental unit of story execution. Every story event, dialog choice, mission trigger, and state change is driven by a Block. Blocks are grouped under a GroupId and evaluated by the story engine when conditions are met. The engine selects and fires eligible Blocks based on PreState conditions, StoryNode presence, and other filters.

{
    "Block": [
        {
            "GroupId": "B_MyStory_Start",
            "Items": [
                {
                    "Actor": "NCT_MyStory",
                    "Dialog": "D_MyStory_Intro",
                    "EventId": "B_MyStory_Choices",
                    "EventType": "Choice"
                }
            ]
        }
    ]
}

Fields

Field	Type	Default	Notes
`BlockId`	INTEGER	Auto	Unique numeric ID for this Block Auto-assigned from `StartingId` if omitted. Hand-author to reserve a specific ID. Used as the WHERE key for UPDATE/DELETE.
`GroupId`	TEXT	required	The group this Block belongs to. All Items under the same group object share this value. Must follow the naming convention `B_StoryKey_Name` Inherited automatically from the parent group object. All Items in a group share the same value.
`StoryNodeId`	TEXT	""	If set, this Block can appear on the timeline or on a contact or character page if the named StoryNode is currently active
`Actor`	TEXT	""	The character or contact who appears on the timeline with this block and who will say the first line if it is activated as a dialog Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` `STATE` `ENO` `EMY` `MO_` SQL column: `ActorId`
`Target`	TEXT	""	The actor whose name and pronouns are substituted into the Block's text using tokens {1}, {3}, {4}, {5}. IF set, this field also triggers gender-split of the `Text` field. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` `ENO` `EMY` SQL column: `InterpolateActorId`
`InterpolateId`	TEXT	""	A GameStateLink reference (e.g. `#FactionLink`) used to substitute a stored text value into dialog tokens {9} and {10}.
`Quip`	TEXT	""	References a DialogQuip GroupId. The engine selects one quip from the group at runtime. Use `{11}` in the `Text` field to render the selected quip. SQL column: `QuipType`
`InterpolateType`	INTEGER	0	Controls how interpolation is resolved. Leave at 0 for standard behavior.
`Side`	INTEGER	0	Controls which side of the dialog UI this character will speak on when this block is displayed as part of a dialog See Value Mappings: Side. SQL column: `DialogSide`
`ChoiceMeta`	INTEGER	0	Controls any helpful meta label on a choice button to help players know when they are making an important decision. This is only shown when the player is displayed a Choice list during a dialog See Value Mappings: ChoiceMeta.
`Weight`	INTEGER	0	Selection weight when if a Block will be picked randomly, where higher weight makes the Block more likely to be selected.
`PreAlternativePath`	INTEGER	0	For use within missions only. If set, this Block only evaluates as true if this value matches the current mission stage's AltPath value (such as 100, 101, 102, etc)
`PreState1`	TEXT	""	GameState condition that must be true for this Block to be eligible. Must start with one of: `HAS_` `NOT_` `GTE_` `LTE_` `EQL_` `NEQ_`
`PreState2`	TEXT	""	Second GameState condition. Both PreState conditions must be true simultaneously. Must start with one of: `HAS_` `NOT_` `GTE_` `LTE_` `EQL_` `NEQ_`
`PreConditionGroup`	TEXT	""	References a BlockCondition group for additional pre-checks beyond the two PreStates Must start with one of: `Pre_`
`PreDialogPostCondition`	TEXT	""	If the Block has a Dialog associated with it, this PostCondition will execute before the dialog is displayed Must start with one of: `Post_`
`PostConditionGroup`	TEXT	""	References a BlockCondition group for additional post-actions. If a Dialog is associated with this Block, its PostConditionGroup will only be executed after the Dialog is completed by the player Must start with one of: `Post_`
`PostState1`	TEXT	""	GameState write action fired when this Block executes its post-actions Must start with one of: `ADD_` `DEL_` `INC_` `DEC_` `TRN_` `SET_` `RND_` `PLS_`
`PostState2`	TEXT	""	Second GameState write action fired when this Block executes its post-actions Must start with one of: `ADD_` `DEL_` `INC_` `DEC_` `TRN_` `SET_` `RND_` `PLS_`
`PostState3`	TEXT	""	Third GameState write action fired when this Block executes its post-actions Must start with one of: `ADD_` `DEL_` `INC_` `DEC_` `TRN_` `SET_` `RND_` `PLS_` `TRT_`
`StoryNode1`	TEXT	""	Adds or removes a StoryNode when this Block executes its post-actions Must start with one of: `ADD_` `DEL_`
`StoryNode2`	TEXT	""	Second StoryNode add/remove fired when this Block executes its post-actions Must start with one of: `ADD_` `DEL_`
`StoryNode3`	TEXT	""	Third StoryNode add/remove fired when this Block executes its post-actions Must start with one of: `ADD_` `DEL_`
`Dialog`	TEXT	""	A reference to a Dialog GroupId that should be started when this Block executes
`OnlyRunOnce`	INTEGER	0	A convenience method to limit a Block to evaluate as true only one time See Value Mappings: OnlyRunOnce. SQL column: `Singleton`
`Duration`	INTEGER	0	TODO: Describe `Duration`.
`EventOption`	TEXT	""	TODO: Describe `EventOption`.
`EventId`	TEXT	""	The target ID paired with this Blocks' EventType â€” a StoryMatch GroupId, a Block GroupId (for Choice/GroupFirst routing), or a StoryNodeId (for Legwork launch).
`EventType`	TEXT	"Event"	Controls what major action the Block might execute. Defaults to `Event` if omitted, which takes no action. See Value Mappings: EventType.
`Text`	TEXT	""	The display text for this Block if it is shown in the Timeline and the text used by the Block if it is display as the first line of a Dialog. If a `Quip` is set, use `{11}` as the entire Text value to render the selected quip. Written to localization JSON as `BlockDesc.{BlockId}`. Gender-split into `_Male` and `_Female` keys when `InterpolateActorId` is non-empty, with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.

Value Mappings

Side[edit | edit source]

Controls which side of the dialog UI this character will speak on when this block is displayed as part of a dialog.

Authored Value	SQL Value	Meaning
`L`	0	Default value - speak on the left side which is typically reserved for your Knight (PCP_Knight) and sometimes Face (PCP_Face)
`R`	1	Speak on the right side, which is appropriate for all other contacts, NPCs, and other characters

ChoiceMeta[edit | edit source]

Controls any helpful meta label on a choice button to help players know when they are making an important decision. This is only shown when the player is displayed a Choice list during a dialog

Authored Value	SQL Value	Meaning
`Mission`	4	Displays a (Mission) label on a choice - indicating a mission will be created
`Legwork`	4	Displays a (Legwork) label on the choice - indicating you will have the option to start a Legwork
`Dismiss`	-2	Displays a (Dismiss) label - indicating that this choice will permanently dismiss a merc from the team
`End`	-1	Displays an (End) label - indicating this choice will end the conversation
`No`	1	Displays a (Reject) label on the choice button
`Delay`	2	Displays a (Delay) label â€” asks for more time before committing
`Yes`	3	Displays an (Agree) label
`Chatter`	4	Appears only on the contact or character's own page, not the global timeline
`ChatterOnTimeline`	5	Appears on the contact or character's own page and the global timeline
`Recruit`	6	Recruit offer â€” appears with a (Recruit) label
`RecruitOnTimeline`	7	Recruit offer also surfaced on the global timeline
`RetirementNo`	-3	Displays an (Reject Retirement) label - incidating you will permanently decline this offer for retirement
`RetirementYes`	9	Displays an (Accept Retirement) label - indicating this will permanently retire your character
`Continue`	-4

OnlyRunOnce[edit | edit source]

A convenience method to limit a Block to evaluate as true only one time (which could also be done with a GameState, but might require a lot of GameStates!)

Authored Value	SQL Value	Meaning
`Forever`	1	A convenience method to make a block only execute a single time. After first execution, its precondition will evaluate as false within the same game.
`Mission`	2	A convenience method to make a block only execute a single time within the current mission. After first execution, its precondition will evaluate as false. When the mission ends, the state is wiped and its precondition can once again evaluate as true in the next mission instance. This is most useful in repeated proc-gen missions.

EventType[edit | edit source]

Controls what the engine does when this Block executes

Authored Value	Meaning
`Event`	Default value - this block will execute its PostConditions and display any dialog but creates no other action
`Vignette`
`OriginStory`
`Recruit`	Opens a recruit conversation
`HeadHunter`
`ProcGenMission`	Procedurally generates a Mission
`ProcGenLegwork`	Procedurally generates a Legwork using the EventId StoryMatch
`PowerPlay`
`PowerPlayService`
`PowerPlayHeadHunters`
`InfluenceBreak`
`ExposureBreak`
`Compromised`
`RetirementA`
`RetirementB`
`RetirementC`
`StartGroup`
`ReloadGroup`
`FadeToBlack`	For use within missions only. If the EventId = 'ON' then immediately fades the entire screen to black. Any other EventId value fades the screen back to normal
`PreCurtain`
`TalkOn`	Fires immediately and routes to the EventId block group
`Choice`	Evaluates preconditions all Blocks with GroupId that match the EventId and presents them as choice list to the player
`Leaf`
`Quip`	For use within missions only. Plays a quip over the current character's head
`ObjectiveQuip`
`ForceDelay`
`Legwork`	Launches a Legwork using EventId as the StoryNodeId
`LegworkPurge`	Deletes a Legwork Launches a Legwork and purges it from the active list on completion
`Mission`	Creates a Mission using the EventId
`Death`	Fires on character death
`Trait`	Fires when a character Trait condition is met
`Tag`	Fires when a Tag condition is met
`Group`	Evaluates preconditions all Blocks with GroupId that match the EventId and executes all matching Blocks
`GroupFirst`	Evaluates preconditions all Blocks with GroupId that match the EventId and executes the first Block by insertion order
`Router`	Routes to one of several EventId targets based on conditions
`RandomOne`	Evaluates preconditions all Blocks with GroupId that match the EventId and executes one and only one random Block from that list
`DelayPost`	For use within missions only. Adds this Block to the queue to execute along side other mission events and prevent the PostConditions from running instantly
`Objective`	For use within missions only. Displayed in mission HUD as a currently ready-to-complete objective. Use a MapObjective or other target key (MO_Terminal, PCT_Escort_VIP) in the EventId to allow the player to click on the objective and pan the camera to the target
`ObjectiveRevealed`	For use within missions only. Fires when an objective is revealed to the player. Set the Weight=1 to list this as a secondary objective
`ObjectiveComplete`	For use within missions only. Displayed in mission HUD as a successfully completed objective. Set the Weight=1 to list this as a secondary objective
`ObjectivePending`
`ObjectiveFailed`	For use within missions only. Displayed in mission HUD as a failed objective. Set the Weight=1 to list this as a secondary objective
`ObjectiveUnlock`
`RefreshObjectives`
`DoorOpen`
`DoorClose`
`MapToken`
`SetAchievement`
`MonsterSpawn`	For use within missions only. Spawns a monster group at a map location
`MonsterSpawnClose`
`MonsterSpawnCount`
`MonsterSpawnHeadHunters`
`MonsterSpawnVIPHunters`
`MonsterSpawnBodyguards`
`DynamicSpawn`
`DynamicLoad`
`MonsterDelete`	For use within missions only. Removes a monster from the map
`MonsterDeleteBox`
`MonsterWake`
`SecurityEnable`	For use within missions only. Enables a security system
`SecurityDisable`	For use within missions only. Disables a security system
`AIScriptDebuff`
`AIScriptKill`
`AIScriptMiss`
`AIScriptSpecialRule`
`AIScriptEndTurn`
`AIScriptBodyguardTurn`
`Victory`	For use within missions only. Immediately ends the current mission stage in victory
`Defeat`	For use within missions only. Immediately ends the current mission stage in defeat
`Tutorial`
`Cinematic`	For use within missions only. Plays a cinematic sequence
`CinematicInstant`

BlockCondition[edit | edit source]

A BlockCondition group defines a set of structured game actions â€” adding characters, modifying tags, changing relationships, granting items â€” that are too complex for the simple PostState fields on a Block. BlockCondition groups are referenced by Blocks via PreConditionGroup or PostConditionGroup.

Fields

Field	Type	Default	Notes
`GroupId`	TEXT	required	The BlockCondition group ID. Must follow the naming convention `Pre_StoryKey_Name` or `Post_StoryKey_Name`. Inherited automatically from the parent group object. All Items in a group share the same value.
`JsonId`	INTEGER	0	Auto-sequenced ID within this BlockCondition group.
`ConditionType`	TEXT	required	TODO: Describe `ConditionType`. See Value Mappings: ConditionType.
`Actor`	TEXT	""	The primary character this condition applies to. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_CHAR` `CUR_RAND` `CHAR_ALL` SQL column: `ActorId`
`Target`	TEXT	""	A secondary character, used for relationship conditions (e.g. tagging one character relative to another). Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` SQL column: `ActorId2`
`Value1`	INTEGER	0	Primary integer value parameter. SQL column: `ConditionValue`
`Value2`	INTEGER	0	Secondary integer value parameter. SQL column: `ConditionValue2`
`Value3`	INTEGER	0	Tertiary integer value parameter. SQL column: `ConditionValue3`
`Count`	INTEGER	0	A count parameter used for item quantities and similar. SQL column: `ConditionCount`
`OptionId`	INTEGER	0	An integer option parameter whose meaning depends on `Type`.
`ConditionKey`	TEXT	""	The primary string parameter â€” a tag ID, trait ID, or game state key depending on `Type`.
`ConditionKey2`	TEXT	""	TODO: Describe `ConditionKey2`.
`Name`	TEXT	""	Display name written to the localization JSON for this condition entry. Written to localization JSON as `BlockCondition.Name.{GroupId}.{JsonId}`. JSON output only — not written to SQL.
`Desc`	TEXT	""	Description text written to the localization JSON for this condition entry. Written to localization JSON as `BlockCondition.Desc.{GroupId}.{JsonId}`. Always gender-split into `_Male` and `_Female` keys with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.

Value Mappings

ConditionType[edit | edit source]

Authored Value	Meaning
`Tag`
`Trait`
`CharacterStatus`
`Hiding`
`Appearance`
`TempStoryId`
`LegworkStoryId`
`StoryId`
`GrantTeamXp`
`GrantXp`
`Turns`
`Money`
`AddCharacter`
`ConvertCharacter`
`CopyContactToCharacter`
`ActivateCyber`
`Job`
`Item`
`Equip`
`Service`
`Cosmetic`
`CopyTag`
`Purge`
`Retire`
`StoryNodeGroup`
`HeadHunter`
`StoryNode`
`Loyalty`
`Heat`
`Medical`
`ContactService`
`ContactServiceDelay`
`Favor`
`Obligation`
`ContactServiceGroup`
`ContactMeta`
`PayRate`
`Boost`
`Burn`
`DeveloperMode`
`AlternativePathId`
`Recruit`
`DoorKey`
`LootKey`
`NoMonsters`
`MissionId`
`CurrentCharacterId`
`HasCharacter`
`MissionActive`
`CurrentHackerId`
`CharAltStart`
`CharDefreeze`
`MoveCharacter`
`SwapEnemyToCharacter`
`GameState`
`GameStateLink`
`CopyGameStateLink`
`BlacksitePick`
`BlacksiteHostPick`
`StoryMatch`
`Mission`
`MissionPurge`
`MapObjective`
`LegworkPurge`
`MissionAltPath`
`MissionTurn`
`MissionFaction`
`MissionSecurityDeck`
`AddItem`
`AddTalent`
`EraDialog`
`ControllerMode`
`TallyPerTurn`
`SuppressReinforcements`
`TeamPower`
`RetirePower`
`SecLevel`
`MissionObjective`
`GameOption`
`OpenScreen`
`TutorialScript`
`EnemyUnaware`
`EnemyFullHealth`
`AlertLevel`
`RosterSpace`
`EventLog`
`HeadHunterDiesLog`
`HeadHunterExpiresLog`
`HeadHunterKillsLog`
`PowerPlayWin`
`PowerPlayLoss`
`SetAchievement`

Dialog[edit | edit source]

A Dialog is an ordered sequence of lines spoken by characters. Each line is one item in the group's Items array. Dialogs are referenced by Blocks via the Dialog field and play top-to-bottom when the Block fires.

{
    "Dialog": [
        {
            "GroupId": "D_MyStory_Intro",
            "Items": [
                { "Actor": "PCP_Knight", "Text": "Who are you?" },
                { "Actor": "NCT_MyContact", "Side": "R", "Text": "Someone who can help." }
            ]
        }
    ]
}

Fields

Field	Type	Default	Notes
`JsonId`	INTEGER	0	Auto-sequenced line number within this Dialog group. Used as the localization key suffix.
`GroupId`	TEXT	required	The Dialog group this line belongs to. Must follow the naming convention `D_StoryKey_Name`. Inherited automatically from the parent group object. All Items in a group share the same value.
`Actor`	TEXT	required	The character who speaks this line. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` `ENO` `EMY` SQL column: `ActorId`
`Target`	TEXT	""	The actor whose name and pronouns are substituted into the text using tokens {1}, {3}, {4}, {5}. Also triggers gender-split of the `Text` field. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` `ENO` `EMY` SQL column: `InterpolateActorId`
`Side`	INTEGER	0	Which side of the dialog UI this line displays on. See Value Mappings: Side. SQL column: `DisplaySide`
`InterpolateType`	INTEGER	0	TODO: Describe `InterpolateType`.
`InterpolateId`	TEXT	""	A GameStateLink reference used to substitute a stored text value into tokens {9} and {10}.
`Quip`	TEXT	""	References a DialogQuip GroupId. The engine selects one quip at runtime. Use `{11}` in Text to render it. SQL column: `QuipType`
`PreState1`	TEXT	""	TODO: Describe `PreState1`. SQL column: `State`
`Text`	TEXT	""	The spoken line. When a Quip is set, use `{11}` as the full Text value. Written to localization JSON as `Dialog.{GroupId}.{JsonId}`. Gender-split into `_Male` and `_Female` keys when `InterpolateActorId` is non-empty, with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.

Value Mappings

Side[edit | edit source]

Controls which side of the dialog UI this line appears on.

Authored Value	SQL Value	Meaning
`L`	0	Left side â€” the Knight speaking
`R`	1	Right side â€” contacts and NPCs

DialogQuip[edit | edit source]

A DialogQuip is a pool of interchangeable short lines. When a Block or Dialog references a QuipType, the engine selects one line at random from the group. Use {11} in the referencing Text field to render the selected quip.

{
    "DialogQuip": [
        {
            "GroupId": "Recruit_Global_Intro1",
            "Items": [
                { "Text": "Let's see what you've got." },
                { "Text": "Talk to me." }
            ]
        }
    ]
}

Fields

Field	Type	Default	Notes
`JsonId`	INTEGER	0	Auto-sequenced line number within this quip group.
`Priority`	INTEGER	0	TODO: Describe `Priority`.
`GroupId`	TEXT	required	The quip pool this line belongs to. Referenced by Blocks and Dialog items via the `Quip` field. Inherited automatically from the parent group object. All Items in a group share the same value.
`Tag`	TEXT	""	TODO: Describe `Tag`. SQL column: `TagTypeId`
`Text`	TEXT	""	The quip text. Rendered wherever `{11}` appears in the referencing line. Written to localization JSON as `DialogQuip.{GroupId}.{JsonId}`. Always gender-split into `_Male` and `_Female` keys with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.

Legwork[edit | edit source]

A Legwork is a multi-stage off-screen operation. The player assigns contacts and resources across one or more turns. Each Legwork has success and failure outcomes that drive story Blocks. Legworks are launched by Blocks with EventType: Legwork.

Fields

Field	Type	Default	Notes
`JsonId`	INTEGER	Auto	Auto-assigned ID for this Legwork record. Used as the localization key suffix. Auto-assigned from `StartingId` if omitted. Hand-author to reserve a specific ID. Used as the WHERE key for UPDATE/DELETE.
`TagChance1`	INTEGER	0	TODO: Describe `TagChance1`.
`TagChance2`	INTEGER	0	TODO: Describe `TagChance2`.
`TagChance3`	INTEGER	0	TODO: Describe `TagChance3`.
`TagChance4`	INTEGER	0	TODO: Describe `TagChance4`.
`TagChance5`	INTEGER	0	TODO: Describe `TagChance5`.
`TagReq1`	TEXT	""	TODO: Describe `TagReq1`.
`TagReq2`	TEXT	""	TODO: Describe `TagReq2`.
`TagReq3`	TEXT	""	TODO: Describe `TagReq3`.
`TagReq4`	TEXT	""	TODO: Describe `TagReq4`.
`TagReq5`	TEXT	""	TODO: Describe `TagReq5`.
`TagNot1`	TEXT	""	TODO: Describe `TagNot1`.
`TagNot2`	TEXT	""	TODO: Describe `TagNot2`.
`TagNot3`	TEXT	""	TODO: Describe `TagNot3`.
`TagMatch`	TEXT	""	TODO: Describe `TagMatch`.
`Actor`	TEXT	required	TODO: Describe `Actor`. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` SQL column: `ActorId`
`StoryNodeId`	TEXT	required	The StoryNode that owns this Legwork. Used to associate results back to the parent story thread.
`WinType`	TEXT	required	The category of success outcome. See Value Mappings: WinType. SQL column: `SuccessType`
`FailType`	TEXT	required	The category of failure outcome. See Value Mappings: FailType.
`ContactOwner`	TEXT	""	TODO: Describe `ContactOwner`. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` SQL column: `ContactActorId`
`BlockTalkOn`	TEXT	""	TODO: Describe `BlockTalkOn`.
`BlockSuccess`	TEXT	""	TODO: Describe `BlockSuccess`.
`BlockFail`	TEXT	""	TODO: Describe `BlockFail`.
`BlockExpires`	TEXT	""	TODO: Describe `BlockExpires`.
`PostLink`	TEXT	""	TODO: Describe `PostLink`.
`PostState`	TEXT	""	TODO: Describe `PostState`.
`Quip`	TEXT	""	TODO: Describe `Quip`. SQL column: `QuipType`
`Target`	TEXT	""	TODO: Describe `Target`. Must start with one of: `NCT_` `PCT_` `NCP_` `PCP_` `PTG_` `PTX` `NTG_` `PLG_` `NAR_` `CUR_` SQL column: `InterpolateActorId`
`InterpolateId`	TEXT	""	TODO: Describe `InterpolateId`.
`Title`	TEXT	""	Display title shown in the legwork UI. Written to localization JSON as `Legwork.Name.{JsonId}`. JSON output only — not written to SQL.
`Desc`	TEXT	""	Description of what the legwork involves. Written to localization JSON as `Legwork.Desc.{JsonId}`. Gender-split into `_Male` and `_Female` keys when `InterpolateActorId` is non-empty, with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.
`Win`	TEXT	""	Text shown when the legwork succeeds. Written to localization JSON as `Legwork.Success.{JsonId}`. Gender-split into `_Male` and `_Female` keys when `InterpolateActorId` is non-empty, with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.
`Fail`	TEXT	""	Text shown when the legwork fails. Written to localization JSON as `Legwork.Fail.{JsonId}`. Gender-split into `_Male` and `_Female` keys when `InterpolateActorId` is non-empty, with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.

Value Mappings

WinType[edit | edit source]

Controls what kind of success result this legwork produces.

Authored Value	SQL Value	Meaning
`Story`
`Leverage`	PMA_ROOM
`Favor`	FAVOR
`InfluenceAndHype`	INFLUENCE_HYPE
`InfluenceAndFavor`	INFLUENCE_FAVOR

FailType[edit | edit source]

Controls what kind of failure result this legwork produces.

Authored Value	SQL Value	Meaning
`Exposure`	EXPOSURE
`Heat20`	HEAT_20
`Heat50`	HEAT_50
`OneFail`	FAIL
`FailRepeat`	TIME
`Leverage`	FAIL_PMA_ROOM
`Injury7`	INJURY_7
`None`

StoryMatch[edit | edit source]

A StoryMatch defines how the engine selects a contact to participate in a story event â€” a recruitment offer, a legwork introduction, or any event that requires a matching contact from the world. The engine evaluates tag requirements against available contacts and assigns a match when all conditions are met.

{
    "StoryMatch": [
        {
            "GroupId": "SN_Recruit_Soldier_Match",
            "Items": [
                {
                    "Status": 1,
                    "Actor": "NCT_Recruit_Soldier_Match",
                    "TagReq1": "Faction_Syndicate",
                    "TagMatch": "UHUB_Recruit_Soldier",
                    "DebugName": "Soldier recruit syndicate contact"
                }
            ]
        }
    ]
}

Fields

Field	Type	Default	Notes
`Optional`	INTEGER	0	If set, this match is not required â€” the event can fire without a matched contact. See Value Mappings: Optional.
`Backstory`	INTEGER	0	TODO: Describe `Backstory`.
`Status`	INTEGER	0	Whether this match entry is active. Set to `1` to enable.
`PostStatus`	INTEGER	0	TODO: Describe `PostStatus`.
`Loyalty`	INTEGER	0	TODO: Describe `Loyalty`.
`TypeLimit`	INTEGER	0	TODO: Describe `TypeLimit`.
`DoNotSetActorId`	INTEGER	0	TODO: Describe `DoNotSetActorId`.
`RelTarget`	INTEGER	0	TODO: Describe `RelTarget`.
`PairRule`	INTEGER	0	Controls how this match is paired with other matches in the same group. See Value Mappings: PairRule.
`GroupId`	TEXT	required	The StoryMatch group ID. Referenced by Blocks via `EventId` when `EventType` is `Recruit` or `ProcGenLegwork`. Inherited automatically from the parent group object. All Items in a group share the same value.
`PreCond`	TEXT	""	TODO: Describe `PreCond`.
`TagReq1`	TEXT	""	Tag that the matched contact must have.
`TagReq2`	TEXT	""	Second required tag.
`TagReq3`	TEXT	""	Third required tag.
`TagNot1`	TEXT	""	Tag that the matched contact must NOT have.
`TagNot2`	TEXT	""	Second excluded tag.
`TagNot3`	TEXT	""	Third excluded tag.
`TagMatch`	TEXT	""	The Hidden tag used to find this match's pool of eligible contacts.
`Actor`	TEXT	required	The temp story ID assigned to the matched contact for this event. SQL column: `ActorId`
`Target`	TEXT	""	TODO: Describe `Target`. SQL column: `RelationshipActorId`
`TagMatchActor`	TEXT	""	TODO: Describe `TagMatchActor`.
`PostLink`	TEXT	""	TODO: Describe `PostLink`.
`PostLink2`	TEXT	""	TODO: Describe `PostLink2`.
`PostState`	TEXT	""	TODO: Describe `PostState`.
`PostState2`	TEXT	""	TODO: Describe `PostState2`.
`PostState3`	TEXT	""	TODO: Describe `PostState3`.
`DebugName`	TEXT	""	Human-readable label for debugging. Not shown in-game.

Value Mappings

PairRule[edit | edit source]

Controls pairing behavior when multiple StoryMatch entries exist in the same group.

Authored Value	SQL Value	Meaning
`OneOfMany`	2
`TraitMatched`	1
`TraitNotMatched`	-1

Optional[edit | edit source]

Whether this match entry must be satisfied for the event to fire.

Authored Value	SQL Value	Meaning
`CreateOrFind`	3
`Required`	0
`Optional`	1

StoryNode[edit | edit source]

A StoryNode represents an active story thread. Nodes are added and removed by Blocks via StoryNode1/2/3 fields. While a node is active it gates which Blocks are eligible to fire and can drive timed expiration events.

{
    "StoryNode": [
        {
            "GroupId": "SN_MyStory",
            "Items": [
                {
                    "StoryNodeId": "SN_MyStory",
                    "StoryNodeType": "Recruit",
                    "OnAddedBlock": "B_MyStory_Setup",
                    "ExpirationBlock": "B_MyStory_Expires",
                    "ExpirationTurns": 60
                }
            ]
        }
    ]
}

Fields

Field	Type	Default	Notes
`StoryNodeId`	TEXT	required	The unique string ID for this node. This is the value used in `ADD_SN_` and `DEL_SN_` game state references.
`GroupId`	TEXT	required	The StoryNode group. Must follow the naming convention `SN_StoryKey_Name`. Inherited automatically from the parent group object. All Items in a group share the same value.
`StoryNodeType`	TEXT	""	The category of story thread this node represents. See Value Mappings: StoryNodeType.
`Actor`	TEXT	""	TODO: Describe `Actor`. SQL column: `ActorId`
`Target`	TEXT	""	TODO: Describe `Target`. SQL column: `InterpolateActorId`
`OnAddedBlock`	TEXT	""	A Block GroupId fired immediately when this node is added to the active set.
`OnDeletedBlock`	TEXT	""	TODO: Describe `OnDeletedBlock`.
`ExpirationStoryNode`	TEXT	""	TODO: Describe `ExpirationStoryNode`.
`ExpirationBlock`	TEXT	""	A Block GroupId fired when this node's `ExpirationTurns` countdown reaches zero.
`LinkedMissionType`	TEXT	""	TODO: Describe `LinkedMissionType`.
`InterpolateId`	TEXT	""	TODO: Describe `InterpolateId`.
`DebugText`	TEXT	""	TODO: Describe `DebugText`.
`ExpirationTurns`	INTEGER	0	Number of turns before the node expires and fires `ExpirationBlock`. Set to 0 for no expiration.
`ExpirationRandom`	INTEGER	0	TODO: Describe `ExpirationRandom`.
`PauseMode`	INTEGER	0	Controls whether this node pauses turn progression while active. See Value Mappings: PauseMode.
`InterpolateType`	INTEGER	0	TODO: Describe `InterpolateType`.
`Text`	TEXT	""	Optional display text associated with this node. Written to localization JSON as `StoryNode.{StoryNodeId}`. JSON output only — not written to SQL.

Value Mappings

StoryNodeType[edit | edit source]

Categorizes the story thread for filtering and UI display.

Authored Value	Meaning
`Recruit`	A character recruitment offer
`Legwork`	An active legwork thread

PauseMode[edit | edit source]

Controls turn progression while this node is active.

Authored Value	SQL Value	Meaning
`Paused`	1
`Unpaused`	-1

Tag[edit | edit source]

A Tag is a label attached to characters, contacts, or the global world state. Tags are used to gate content (via TagReq fields in StoryMatch), to track relationships, and to classify characters for procedural generation. Tags are added and removed by BlockCondition entries.

Fields

Field	Type	Default	Notes
`JsonId`	INTEGER	Auto	Auto-assigned ID for this Tag record. Auto-assigned from `StartingId` if omitted. Hand-author to reserve a specific ID. Used as the WHERE key for UPDATE/DELETE.
`TagClass`	INTEGER	required	The category of this tag, controlling where and how it is displayed. See Value Mappings: TagClass.
`Hidden`	INTEGER	0	Controls the tag's visibility in the UI. See Value Mappings: Hidden. SQL column: `Hide`
`Retirement`	INTEGER	0	TODO: Describe `Retirement`.
`RelType`	INTEGER	0	TODO: Describe `RelType`.
`Score`	INTEGER	0	A numeric score associated with this tag, used for weighted selection. SQL column: `TagScore`
`TagId`	TEXT	required	The unique string identifier for this tag. This is the value used in `ADD_`/`DEL_` game state references.
`ExtraTag`	TEXT	""	TODO: Describe `ExtraTag`. SQL column: `TagMatch`
`Legwork`	TEXT	""	TODO: Describe `Legwork`. SQL column: `LegworkMatch`
`Name`	TEXT	""	Display name shown in the UI when this tag is visible. Written to localization JSON as `Tag.Name.{JsonId}`. Always gender-split into `_Male` and `_Female` keys with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.
`Desc`	TEXT	""	Description of what this tag represents. Written to localization JSON as `Tag.Desc.{JsonId}`. Always gender-split into `_Male` and `_Female` keys with pronoun substitution: {3}=he/she, {4}=him/her, {5}=his/her. JSON output only — not written to SQL.

Value Mappings

Hidden[edit | edit source]

Controls tag visibility.

Authored Value	SQL Value	Meaning
`Yes`	1

TagClass[edit | edit source]

The display category of this tag.

Authored Value	SQL Value	Meaning
`Hidden`	1	Not shown in any UI â€” used for internal logic only
`Regular`	2	Standard tag shown in character profiles
`PersonalRel`	3
`FactionOrigin`	4
`FactionRel`	5
`Trait`	6
`ContactType`	8
`CharacterJob`	11
`TeamStatus`	12
`LegworkBlocker`	18
`ContactTrait`	21
`Death`	22
`PersonalID`	23	Used to identify a specific character instance in story events
`HeadHunters`	24
`PowerPlay`	25
`RetirementA`	26
`RetirementB`	27
`RetirementC`	28
`RetirementPre`	29

Modding: Home · Quick Start Guide · Modkit Uploader · Example Project · Data Modding · Data Parser Schema · Use Cases · Download Modding Resources