Quests, story content and persistent systems from mods

Maturity: Draft. How mods add quests, phone conversations, objectives, map pins, scenes and long-lived systems to Cyberpunk 2077 without replacing the game's own quests; how script and quest graphs talk through facts; how braindances are built; what can be generated at run time; and what can be reloaded live. Consolidated on 29 September 2026 from six installed story mods (the B1 deep dive), their quest, scene and journal resources serialised with WolvenKit CLI 9.0.1 into a private scratch folder, the decompiled 2.31 script bundle (redscript-cli 0.5.31), and the source of ArchiveXL, Red Hot Tools and RED4ext.SDK. Nothing here has been seen in a game session. Grades follow the knowledge rules; resource includes a mod resource read as serialised JSON.

This page answers: what is a mod quest made of, how do the parts connect, how could XF Studio author, generate and live-test one, and how are braindances and persistent world systems built?

Sources

Installed-mod citations give paths inside each mod's folder in the mod manager. Who made each mod and what it taught us is in the community credits.

1. The short answers

2. The parts of a mod quest

2.1 Attaching a phase

• Declaration. quest: phases: takes path (the mod phase) and parent (a .quest or .questphase), and optionally input/connection and output as a node-id path plus socket, and intercept to cut an existing link source ArchiveXL QuestPhase/Config.cpp:10-60.
• Default wiring. With no input, the phase node is connected from the parent graph's start node (Out → In1) source QuestPhase/Extension.cpp:178-238, 240-275. With output, both Out and Out1 of the mod phase connect to the named node's In (or In1 for a phase node) source same.
• Started once per save. For phases merged into a .quest, ArchiveXL sets a fact keyed by the new node's path when a quest starts and, when a save is restored, force-starts the node (socket In1) if that fact is unset, then sets it. So a mod added mid-playthrough starts on the next load, and never twice source Extension.cpp:97-176.
• Node ids are CRC-16. The injected node's id is a 16-bit CRC of "<phase path>:<parent node id>"; if a node with that id already exists in the parent graph, the phase is skipped with a log warning source Extension.cpp:354-392. Collisions are rare but possible as more phases target the same quest hypothesis.
• New Game+ in one line. An ArchiveXL resource scope (resource: scope: df_combined_scope.quest: [cyberpunk2077.quest, mod\quest\newgameplus.quest, …]) used as the parent expands to every listed quest resource Dark Future and Eviction Notice .xl; source Extension.cpp:35-78 (ExpandList). Phantom Liberty's standalone start needs ep1\quest\ep1_standalone.quest as well resource Lizzie's Braindances .xl.
• Sub-phases. A root phase starts further mod phases with questPhaseNodeDefinition (phaseResource), entered through named questInputNodeDefinition sockets (SystemStart, DeliveryStart) and left through questOutputNodeDefinition (Terminating). Only root phases need listing in the .xl resource Eviction Notice (30 phases, 21 listed).

2.2 Node vocabulary seen in mod phases

resource the serialised phases of Dark Future, Eviction Notice and Lizzie's Braindances.

2.3 The journal

resource darkfuture.journal, eviction_notice.journal; source Dark Future Main/DFMainSystem.reds (UpdateCodexEntries).

• Text keys. Journal text fields hold plain string keys (DarkFutureTextMsg_…); ArchiveXL converts each to LocKey#<FNV1a64 of the key> when it merges the journal, and the mod's localization: onscreens: JSON supplies the strings under the same keys source ArchiveXL Journal/Extension.cpp:478-501.
• Script can read and change entry states, not create entries (JournalManager offers reads and ChangeEntryState; the entry classes are importonly) source (terminals §3.3).

2.4 Facts

• What they are. Named 32-bit integers in the save's FactsDB, keyed by the FNV-1a 32-bit hash of the name source ArchiveXL src/Red/QuestsSystem.hpp:69-94; source save layout in save files. A fact never set reads 0.
• Script API. QuestsSystem.GetFact(n"name"), SetFact(n"name", value), RegisterListener(n"name", object, n"callback") → id, UnregisterListener(name, id); CET uses GetFactStr/SetFactStr source Dark Future Utils/DFFactListenerUtils.reds; Stock Market questManager.lua.
• Facts are the story's public interface. Mods read vanilla quest facts to react to the story: prologue done (q001_01_go_to_sleep_done, q101_enable_activities_flat), Phantom Liberty start (q301_00_done), point of no return (q115_point_of_no_return), apartments owned (dlc6_apart_*_purchased), story choices (sq021_randy_saved, sq028_kerry_relationship, sq030_romance, q305_medal_given_away), Dogtown open (q302_done), wanted_level source Dark Future Services/DFGameStateService.reds, Conditions/DFConditionSystemHumanityLoss.reds:508-528; NightlyNow Utils/Quest.reds; resource Eviction Notice new_game_experience.questphase.
• Facts are also an inter-mod bus. Idle Anywhere, Immersive Food Vendors and Immersive Bartenders publish what V consumed as dec_dark_* fact values (-1 ready, ≥ 0 an item index), and Dark Future listens source Gameplay/DFModCompatSystem.reds.
• Namespacing matters: a fact is a global name; every mod here prefixes its own (df_fact_…, en_fact_…, lizzies_bds_…).

2.5 Map pins

The pin shows while its objective is active and the quest is tracked [hypothesis: standard journal behaviour; not checked here].

2.6 Phone messages and contacts

2.7 Scenes

• A scene has named entry points and exit points; a quest scene node exposes them as input and output sockets resource every scene read.
• Actors and props: V as scnPlayerActorDef found in context; props as scnPropDef with entityAcquisitionPlan: spawnDespawn, so a scene can bring its own objects resource Dark Future darkfuture_item_consume_anim_drink_sip_righthand.scene (16 entry points, one per prop).
• Events seen: dialogue lines (scnDialogLineEvent, V's vanilla lines by string id), cinematic idle changes for V in a car seat (scnChangeIdleAnimEvent), skeletal animation (scnPlaySkAnimEvent), audio, VFX, camera parameters resource Dark Future scenes.
• Pickup interactions: a scene with a show_choice entry, a hide_choice entry driven by a trigger, and an item_taken exit makes a world pickup with a choice prompt resource Eviction Notice glen_delivery.questphase #23, #26, #34.
• Scenes may contain quest nodes (scnQuestNode wrapping fact, switch and condition nodes) resource Dark Future scenes.
• Voiced mod scenes get lip sync through ArchiveXL localization: lipmaps: (lip sync §5).

2.8 World pieces

A quest's places are ordinary World Builder sectors in the mod's own streaming block: static markers for scenes and pins, trigger areas, hidden props revealed by questShowWorldNode, and devices registered through a .devices patch; always-loaded sectors hold markers that scenes must find from afar resource Eviction Notice (22 sectors, custom_devices.devices), Dark Future (worldbuildergroup_df_consumableanim_alwaysloaded). The streaming side is in world and streaming.

3. A minimal quest recipe

The smallest complete quest built only from parts the installed mods prove, in the order a tool would emit them. XF names follow the naming contract (xfs_ identifiers, XF-branded titles).

1. Place the world. A World Builder sector in the mod's block: a static marker at the goal, a trigger area around it, optionally a hidden prop. Note their node refs ($/mod/<sector>/#<name>). resource Eviction Notice.
2. Write the journal (xfs_…\journal\….journal, listed under journal:):
   • contacts/xfs_fixer (gameJournalContact, Texter, an avatar record) with a conversation holding an intro message, a choice group with Accept and Decline, and a thanks message;
   • quests/minor_quest/xfs_job (gameJournalQuest, MinorQuest) with a description and one phase holding two objectives: Go to the drop (with a gameJournalQuestMapPin on the marker) and Text the fixer (with a gameJournalQuestCodexLink to the reply group). All texts are keys supplied by localization: onscreens: JSON. resource source
3. Write the phase (xfs_…\quest\xfs_job.questphase): In1 → pause until xfs_job_offer > 0 → message intro Active (with notification) → choice group Active → pause on Accept Succeeded (and a parallel pause on Decline into a cut-control node) → quest Active, objective 1 Active → pause until player IsInside the trigger → (optional) scene with a pickup choice → objective 1 Succeeded, add the reward item (questAddRemoveItem_NodeType) → objective 2 Active → reply group Active → pause on its choice Succeeded → objective 2 and quest Succeeded → set xfs_job_done = 1. resource Eviction Notice glen_delivery.questphase
4. Attach it: quest: phases: - path: …\xfs_job.questphase, parent: <a scope covering cyberpunk2077.quest and the New Game+ quests>; add ep1\quest\ep1_standalone.quest for Phantom Liberty starts. source
5. Start it. Either from the graph (a pause on vanilla facts such as q101_enable_activities_flat, then a game-time delay) or from script by setting xfs_job_offer = 1. Money rewards and anything computed go through a request fact answered by script (§4). resource source
6. Package the phase, journal and sectors in one archive, texts in a second (so translators replace only that), and the .xl beside them; version the facts, because saves keep them. resource Eviction Notice's split archives.

What this recipe does not yet cover: dialogue with voiced NPCs in the world (scenes with actors and lines), companions, and fail states; those need scene authoring, which the installed mods show only for V and props. Directing an NPC and offering V choices without a scene (runtime AI commands, text lines and a hub added to the game's dialogue widget) is on NPC direction.

4. How script and quest graphs work together

5. Braindances

5.1 The vanilla braindance

5.2 Staged braindances (Lizzie's Braindances)

The installed braindance mod plays ordinary scenes in real places and parametrises them:

1. The player picks a braindance and a cast in a menu; the menu writes facts for location, loops, music and each performer slot's character, appearance and flags source MenuUIController.reds:3286-3306.
2. Casting: six fixed Character.LizziesBDs_Performer* records are rewritten with TweakDBManager.SetFlat (entityTemplatePath, appearanceName, genders, names, attitude) and UpdateRecord, so the scene's spawn-by-record actors become the chosen vanilla NPCs, V's cutscene rig or another mod's character source MenuUIController.reds:3787-3848.
3. Dressing: named ActionEvents (sent, presumably, from its graphs hypothesis) tell each performer to switch appearance (ScheduleAppearanceChange) source NPCPuppet.reds:57-150; per-instance parts are set by editing mesh components in NPCPuppet.OnRequestComponents before the entity streams source NPCPuppet.reds:162-276.
4. Content packs register extra characters through a CustomCharacterLoaderEvent handler source Classes.reds:1081-1130.

5.3 What player-made or generated braindances would need

• A recording is a scene resource. Recording V's play as a braindance means writing a .scene (tracks of positions, animations and camera) from captured data, the same export problem as a quest editor hypothesis.
• Casting by record rewrite gives any number of variants of one authored scene [source, above]; a generator would vary cast, place and music through facts and flats.
• Investigation gigs would be a template scene plus generated AddBraindanceClue nodes over its timeline; whether clue nodes work on a mod scene in braindance mode is untested hypothesis.
• Entering braindance mode from a mod has no installed example; the first probe is to replay a vanilla braindance quest's node sequence against a mod scene hypothesis.

6. Persistent systems and generated content

6.1 Where long-lived state lives

More on save layout in save files §4.

6.2 A robust architecture (Dark Future)

A base system class with a fixed lifecycle (Init → systems, blackboards, data, listeners, timers → InitSpecific; Suspend, Resume, Stop); start only after RadialWheelController.OnLateInit (safe for status effects), in dependency order, suspend in reverse; a game-state gate before any story beat; Codeware callback-system events for death, time skip and settings; published lifecycle events for add-ons; a tiny save footprint; and an uninstall path (switch off in settings, save, then remove files) source Dark Future System/DFSystem.reds, Main/DFMainSystem.reds; resource upstream README.md. Clocks that pause when they should: Virtual Atelier Delivery stops its order clock during braindances, as Johnny and in the time-skip menu source VirtualAtelierDelivery.reds:566-595.

6.3 What is generated at run time

Random encounters from the district's gang (District_Record chain → faction character lists → Codeware DynamicEntitySystem) source Dark Future DFRandomEncounterSystem.reds; news from gameplay observers and from vanilla quest completions (JournalNotificationQueue.OnJournalUpdate, gameJournalQuest Succeeded) source Stock Market questManager.lua:24-48; orders and their messages source Delivery. No installed mod generates quest graphs or journal entries; dynamic content is either fixed data parametrised by facts and flats, or journal-free UI.

7. Hot reload

Under MO2, a hot-reloaded archive lands in MO2's overwrite folder, because the move targets the virtual archive/pc/mod source ArchiveLoader.cpp:150-176 [hypothesis for the VFS effect].

8. What this means for XF Studio

• A quest editor is feasible as a writer of .questphase, .journal, sector and .xl files in WolvenKit's JSON form, using only the node types in §2.2; start from the §3 recipe hypothesis.
• Live testing through the bridge needs fact read, write and watch, journal entry state, and a remote device event by node ref (the Eviction Notice route: CreateNodeRef → EntityID.FromHash(NodeRefToHash(…)) → CreatePersistentID(id, n"controller") → PersistencySystem.QueuePSEvent) source Eviction Notice ENRentSystemBase.reds:551-555, 756-774; bridge side hypothesis.
• Keep quest logic restartable: short phases started by facts can be retested after a hot reload without reloading the save hypothesis.
• An XF phone presence (session notices, a Studio contact) can be built journal-free in our own code, NightlyNow style [source, pattern].

Open questions

1. Does ArchiveXL's forced start run for a phase added to a save whose quest has already passed the start node, in every case (Act 2 saves, Phantom Liberty standalone)?
2. Does TimeSystem.RegisterListener with repeat = 0 fire once or repeat? (Eviction Notice depends on it.)
3. Do AddBraindanceClue_NodeType and braindance mode work with a mod scene?
4. After a Red Hot Tools reload, does a newly started scene node load the new scene file?
5. How often do 16-bit injected phase ids collide across the installed phase mods, and with vanilla node ids in cyberpunk2077.quest?
6. Does a quest map pin on a node ref in an unloaded mod sector show at the right place before the sector streams?

Related pages

Terminals and arcade · World and streaming · Save files · Lip sync · Player control · Runtime access · B1 deep dive · In-game possibilities