Cyberpunk 2077 Quest Authoring

The RED Questbook

Quest modding in Cyberpunk 2077 is powerful, but the public documentation is still scattered across a small number of focused guides. This book provides a standalone path from opening your first quest resource to building quests with journal entries, world interactions, characters, scenes, combat, vehicles, and cleanup.

You do not need to understand REDengine internals before you begin. The early chapters introduce one idea at a time, and the downloadable WolvenKit projects give you something concrete to inspect whenever the resource model feels abstract.

The book complements the broader REDmodding quest and scene guides. It lives separately because native quest authoring is still developing quickly and benefits from executable examples, coordinated diagrams, and a learning path that can evolve as the tools improve.

Start small

Begin with Start here. You will install the tools, learn the shape of a WolvenKit project, inspect one vanilla questphase, and build First Signal: a quest with one objective, a short wait, and a one-shot completion fact.

Five incremental labs then add the major systems:

1. First Signal — questphase, journal, localization, and a persistent fact.
2. Signal Race — conditions, waits, Boolean trees, and parallel signal flow.
3. Boundary Check — streaming sectors, NodeRefs, triggers, and a map pin.
4. Handoff Point — root and child questphases with explicit input/output contracts.
5. First Contact — a community actor, readiness, a spoken scene, named handoff, and delayed cleanup.

Each lab includes an overview, a manual WolvenKit walkthrough, a completed project, and an in-game test procedure. You can follow them in order or use the lab overview to find the closest starting point for your own quest.

Think in cooperating resources

A Cyberpunk quest is rarely one file:

• .questphase graphs coordinate progression and persistent state;
• .journal resources define quests, objectives, messages, files, and map pins;
• localization resources provide UI text, subtitles, dialogue, and choices;
• streaming resources place triggers, markers, communities, AI spots, and devices in the world;
• .scene resources provide dialogue, choices, events, animations, and named exits;
• entity, appearance, and TweakDB resources provide custom characters and gameplay records.

Most difficult bugs occur where two of these owners disagree. The book therefore explains not only which properties to set, but which resource owns the behavior, how identities connect across files, and what to inspect when a graph looks valid but nothing happens in game.

What the examples prove

The downloadable projects are executable reference material, not magic templates. Their structure is checked with the version of WolvenKit listed in Tested versions, and every supplied node and resource is explained in the book.

All five labs are Structurally validated. Their in-game acceptance runs are still pending, so their intended runtime behavior remains Experimental. Use the test guides to check what happens in your game; the completed downloads are comparison projects, not a promise of a tested playthrough.

The system chapters explain the resource relationships, and the test guides show how to check their behavior in game.

Start here

This section takes you from a verified Windows game installation and no WolvenKit project to an installed, observable quest mod. It assumes no previous REDengine knowledge and no GitHub, Nexus Mods, or WolvenKit account.

The first result is deliberately small: First Signal activates one quest and one objective, waits ten real-time seconds, completes them, records a one-shot fact, and terminates. It has no world, scene, NPC, device, or audio dependency.

The supplied start and completed projects let you compare your work at each stage. The completed resources pass the book’s structural checks; the test guide shows you how to verify the player-facing result in your own game.

What a quest consists of

A .questphase is the coordinator, not the entire quest. Even this minimal example crosses four ownership boundaries:

The first three are native CR2W resources packed into a game archive. The last is a loose ArchiveXL framework file. Installing only one layer cannot produce the complete behavior.

Use this reading path

1. Install the pinned toolchain from a known starting state.
2. Create a project and understand its layers.
3. Extract and inspect one named vanilla questphase in a separate research project.
4. Read Foundations for ownership, graph execution, identifiers, save-backed state, composition, and lifecycle.
5. Build Lab 1: First Signal.
6. Install, test, and reset without confusing an old save with a clean test.

Use the tested version set throughout. Newer versions may work, but editor labels, serialization, or framework registration can change; note the versions you actually use when reporting a problem.

What you do not need

You do not need a quest generator, a manifest compiler, a pre-extracted copy of the game, or access to the research repository used to develop this book. You will author and inspect the game resource model with WolvenKit, package native resources in an archive, register them with ArchiveXL, and test them in the game.

You also do not need to edit raw CR2W-JSON. The serialized files supplied with the completed checkpoint exist for review, deterministic diagrams, and structural comparison; the beginner workflow stays in WolvenKit.

Install the pinned toolchain

This procedure establishes one reproducible Windows authoring environment. At the end, WolvenKit can browse your installed game and the framework logs can prove which runtime components loaded.

Version note: the version selection and file layouts below are supported by the linked upstream releases and project documentation. The Lab 1 resources are Structurally validated; installing the prerequisites does not make Lab 1 Runtime-proven.

The repository-wide baseline is recorded in Tested versions. ArchiveXL’s upstream documentation also lists redscript 0.5.31+ as a requirement, so this guide fixes the first compatible stable version, 0.5.31, rather than leaving a clean-install reader with a hidden dependency.

Start from a known game installation

You need:

• 64-bit Windows 10 or 11;
• a legally owned Windows copy of Cyberpunk 2077 and the store or launcher account that owns it;
• enough writable storage for WolvenKit, its asset cache, and projects outside the game directory;
• permission to copy the framework and built mod files into the game directory.

No GitHub account is needed to download public release assets. No Nexus Mods, WolvenKit, Discord, or other service account is required for this book.

Launch the unmodded game once and confirm the version shown by the game is the expected build. Then exit completely. If the installation may be damaged, use your storefront’s verification function; CD Projekt RED documents Verify/Repair for GOG and equivalent Steam/Epic checks.

Store verification repairs official files but may leave extra mod files in place. An installation is a controlled baseline only when you also know what is present under locations such as archive\pc\mod, red4ext, and r6\scripts. Preserve an inventory or use a dedicated test installation. Never delete the whole game directory as a troubleshooting shortcut.

This release was checked against the exact GOG suffix 2.31a. The public patch name and the labels shown by other storefronts may be 2.31; treat those as a separate environment until the example is repeated there.

Install WolvenKit 8.19.0

1. Install Microsoft’s .NET 8 runtime. The WolvenKit 8.19.0 release names .NET 8 as its prerequisite.

2. From that release, download WolvenKit-8.19.0.zip or WolvenKitSetup-8.19.0.exe. Do not download GitHub’s automatically generated “Source code” archives.

3. If you chose the ZIP, extract it into a dedicated, user-writable tools directory. WolvenKit’s project documentation treats the ZIP build as a portable application; it does not belong inside the Cyberpunk directory.

4. Start WolvenKit.exe. On first launch, set Game Executable Path to the actual Cyberpunk2077.exe:

   <Cyberpunk 2077>\bin\x64\Cyberpunk2077.exe
   

5. Set Depot Path to a writable cache directory outside both the game and your projects, for example C:\CyberpunkModding\WolvenKitDepot.

6. Confirm the status bar reports 8.19.0, then close WolvenKit before installing the runtime frameworks.

The upstream download and setup guide and settings reference explain these two paths. The setting called Depot Path is WolvenKit’s local asset cache. It is not a resource’s virtual depot path; that distinction is covered in Project and resource structure.

The separate WolvenKit Console download is not a reader prerequisite for these chapters.

Install the runtime dependencies

All release archives in this section are laid out relative to the Cyberpunk 2077 directory. Extract each archive so that its bin, red4ext, or r6 directory merges with the directory of the same name in the game installation. Do not create an extra wrapper such as Cyberpunk 2077\red4ext-1.30.0\red4ext.

1. Install the Microsoft Visual C++ 2015–2022 x64 Redistributable required by RED4ext.
2. Download red4ext-1.30.0.zip from the RED4ext 1.30.0 release and extract it into the Cyberpunk 2077 directory. Do not use the separate symbols archive.
3. Download redscript-v0.5.31-windows.zip from the redscript 0.5.31 release and extract it into the same directory.
4. Download ArchiveXL-1.27.0.zip from the ArchiveXL 1.27.0 release and extract it into the same directory.

The RED4ext installation guide and ArchiveXL repository are the authoritative upstream installation references.

At minimum, the merge should leave these files at these relative locations:

bin\x64\winmm.dll
red4ext\RED4ext.dll
red4ext\plugins\ArchiveXL\ArchiveXL.dll

ArchiveXL also supplies files below r6\config and its plugin directory. Their presence is expected; do not cherry-pick only the DLL.

Prove the frameworks start

Launch the game once, reach the main menu, and exit. Check for:

<Cyberpunk 2077>\red4ext\logs\red4ext.log
<Cyberpunk 2077>\red4ext\logs\game.log
<Cyberpunk 2077>\red4ext\plugins\ArchiveXL\ArchiveXL.log
<Cyberpunk 2077>\r6\logs\redscript_rCURRENT.log

The RED4ext documentation identifies red4ext.log and game.log as the loader/plugin checks, while the redscript repository identifies its r6\logs output. ArchiveXL writes its own plugin log after it loads.

Record the version banners and resolve errors before creating a quest. A file existing on disk proves only that it was copied; a clean framework log proves only that the loader reached that component. Neither proves a quest resource was registered or executed.

Setup checkpoint

Before continuing, you should be able to answer yes to all of these:

• Does the unmodded game reach the main menu on the target build?
• Does WolvenKit 8.19.0 point to the real game executable?
• Is the WolvenKit cache outside the game and project directories?
• Do RED4ext, redscript, and ArchiveXL create their expected logs without an unresolved dependency or compilation error?
• Have you recorded any unrelated mods still present in the test installation?

If not, stop here. Quest edits cannot repair a broken authoring or runtime baseline.

Project and resource structure

This chapter creates an empty WolvenKit project and establishes the path model used throughout the book. It also explains why a valid .archive is only one part of a quest installation.

Version note: the project layout is the WolvenKit 8.19.0 layout used by the supplied checkpoints. Lab 1’s CR2W resources are Structurally validated. This page makes no claim that an untested archive executes in game.

Create the Lab 1 project

Open WolvenKit and use either File > New Project or Create New Project on the home view. Enter:

Choose Finish. WolvenKit creates a project directory and a .cpmodproj file; the source subdirectories are created or populated as the project gains files. The upstream WolvenKit project guide documents the same fields and explicitly warns against creating a project inside the game directory.

If you prefer the book’s checkpoint, extract the Lab 1 start download into that projects directory and open CQA_Lab01_OneShot_Start.cpmodproj. Do not open a project directly inside the ZIP.

Keep four path domains separate

The word “path” refers to four different things in this workflow:

Only the last value belongs in a CR2W ResourcePath or an ArchiveXL registration. Never serialize a drive letter or your personal project directory as a resource address.

Understand the source layers

The completed Lab 1 checkpoint has this deliberate shape:

CQA_Lab01_OneShot.cpmodproj
source\
├── archive\
│   └── mod\cqa\cqa001\
│       ├── phases\cqa001.questphase
│       ├── journal\cqa001.journal
│       └── localization\en-us\onscreens\cqa001.json
├── raw\
│   └── mod\cqa\cqa001\...
└── resources\
    └── CQA_Lab01_OneShot.archive.xl

source\archive contains cooked REDengine resources. The folders beneath it are their depot paths, so the phase’s project path

source\archive\mod\cqa\cqa001\phases\cqa001.questphase

becomes this virtual address when packed:

mod\cqa\cqa001\phases\cqa001.questphase

source\resources contains loose control files that WolvenKit stages beside the packed archive. Lab 1’s .archive.xl tells ArchiveXL to attach the mod-owned questphase below base\quest\cyberpunk2077.quest and merge the mod-owned journal and localization resources.

source\raw is a working/review layer. The completed checkpoint includes WolvenKit CR2W-JSON there so the book can produce exact diffs and diagrams. Those files are not loaded by the game, and raw JSON editing is not the beginner authoring path.

WolvenKit generates packed as staging output. A normal Install rebuilds that output and copies its game-relative hierarchy. Do not author in packed: the tool may delete and recreate it.

CR2W is a container, not a quest language

CR2W is the binary resource container used by REDengine. The extension and root type tell the engine how to interpret a particular container:

The Lab 1 .questphase has a questQuestPhaseResource root containing a questGraphDefinition. Nodes inside that graph refer to other resources and identifiers; they do not embed everything the player sees.

A WolvenKit CR2W-JSON export is a text serialization of the same object model. It is useful for inspection and deterministic tooling, but its $type, handle, and buffer structure is not a separate runtime format. Saving JSON-shaped text with a .questphase extension does not create a cooked resource.

Archives and framework resources solve different problems

Packing turns source\archive into a .archive bundle. The archive preserves the internal depot paths so the engine can resolve the resources.

ArchiveXL’s loose file is not part of that CR2W bundle. For Lab 1 it contains:

quest:
  phases:
  - path: mod\cqa\cqa001\phases\cqa001.questphase
    parent: base\quest\cyberpunk2077.quest

journal:
- mod\cqa\cqa001\journal\cqa001.journal

localization:
  onscreens:
    en-us:
    - mod\cqa\cqa001\localization\en-us\onscreens\cqa001.json

The .archive answers “does the resource exist at this depot path?” The .archive.xl answers “under which game-owned root should this resource be registered or merged?” Both must reach the installation.

After a normal install of the completed checkpoint, expect these two top-level payloads:

<Cyberpunk 2077>\archive\pc\mod\CQA_Lab01_OneShot.archive
<Cyberpunk 2077>\archive\pc\mod\CQA_Lab01_OneShot.archive.xl

Their presence still proves only staging. The archive path list, framework log, game behavior, and save-state matrix are separate checks.

Project checkpoint

Before adding nodes, verify:

1. the .cpmodproj is outside the game directory;
2. the mod name is unique and stable;
3. every cooked resource will live below source\archive at its intended depot path;
4. loose .archive.xl configuration will live below source\resources;
5. nothing below source\raw is being mistaken for runtime input.

Continue with Inspect a vanilla questphase, then read Resources and ownership before authoring Lab 1.

Inspect a vanilla questphase

Here you will extract one named game resource into a disposable WolvenKit project, inspect its ownership and graph shape, and record observations without shipping CD Projekt RED’s file.

Vanilla reference: the depot path and focused behavior below are Observed in vanilla. A retained research extraction reported game version 2310, was extracted on 2026-07-24, and was serialized for inspection with WolvenKit 8.17.4. No extracted binary or complete serialization is included in this book. Re-extract it from the pinned 2.31a installation with WolvenKit 8.19.0 before relying on its current structure.

Why use a separate inspection project

Use a project such as CQA_Vanilla_Inspection, not the Lab 1 project. Adding a vanilla file to a WolvenKit project places the cooked resource beneath that project’s source\archive; packing the project would therefore copy the vanilla resource into a distributable archive.

A separate project creates a simple safety boundary:

• extracted game resources stay local;
• notes can cite their original depot paths;
• tutorial projects contain only mod-owned resources;
• the inspection project is never packaged or committed.

The reference is evidence, not a template. It contains quest-local facts, NodeRefs, journal paths, scenes, devices, and nested phases that will not become valid merely because the file was copied.

Extract the named resource

Create or open the disposable project, then enable the Asset Browser from WolvenKit’s View menu if it is hidden. Ensure Mod Browsing mode is off so the search covers the installed base-game archives.

Search for this exact depot path:

base\quest\side_quests\sq021\phases\sq021_randys_room.questphase

Select the exact result, open its context menu, and choose Add selected items to project. The official Asset Browser guide documents that action and explains that it extracts individual files from installed archives without uncooking the entire game.

Verify that the project now contains:

source\archive\base\quest\side_quests\sq021\phases\sq021_randys_room.questphase

The leading source\archive is project structure. The depot path begins at base. Do not rename the extracted file before recording its provenance.

If you only want to browse another reference without retaining it, Open without adding to project is the safer read-only route. It does not satisfy this extraction checkpoint because no project copy is retained. The upstream File Editor documentation describes both workflows.

Inspect ownership before graph layout

Open the project copy. Start with the resource tree/properties, then use the quest graph view as an index into exact nodes. Record these facts:

Do not take a graph screenshot as your structural record. Write down node ID, concrete type, decisive properties, input/output socket names, and connected node/socket pairs. That record survives editor zoom, layout, and theme changes.

The resource is intentionally large. Do not try to understand all of it on the first pass. The focused computer-document sequence is useful because it shows ownership crossing from a device/scene flow into a fact-backed quest wait:

These rows are Observed in vanilla, not a universal recipe. The important boundary is that the authored computer flow emits a dedicated fact and the questphase waits for it. The journal activation alone is not evidence that an arbitrary document-read condition exists.

Record provenance, not the asset

For a research note, retain:

• the exact depot path;
• game and WolvenKit versions;
• extraction date;
• the small node/property excerpt needed for the claim;
• optionally, a local SHA-256 of the extracted file;
• your interpretation and its evidence label.

Do not publish the cooked .questphase, a complete CR2W-JSON export, or a ZIP containing the inspection project. A hash identifies your local reference but does not grant redistribution permission.

When the game updates, extract again into a fresh disposable project and compare focused facts. Do not silently carry a previous-build observation forward.

Inspection checkpoint

You are ready to continue when you can explain why:

1. the Windows path and depot path are different;
2. adding the file to a project extracts a distributable cooked resource;
3. a vanilla phase’s external references do not become mod-owned dependencies;
4. node sockets, not visual placement, establish execution;
5. your notes can support a claim without redistributing the source asset.

Next, read Graph execution and the rest of Foundations.

Foundations

Native quests are not one file format. A questphase coordinates resources that have different owners, identifiers, loading rules, and persistence behavior. The foundations establish those boundaries before a tutorial asks you to edit a graph.

Read these chapters in order:

1. Resources and ownership
2. Graph execution
3. Identifier domains
4. Facts, journals, and saves
5. Root and child questphases
6. Lifecycle and cleanup

Afterward you should be able to answer:

• which resource owns a behavior;
• whether an identifier names an object, a world location, or a lookup key;
• whether a node evaluates now or waits;
• which state survives a save and reload;
• where a parent phase ends and a child phase begins;
• what serialization, packing, and runtime tests each prove.

The chapters use small excerpts from the mod-owned cqa001 example. They cite vanilla depot paths where useful but do not redistribute extracted game resources.

Resources and ownership

A questphase is a coordinator. It can change facts and journal state, wait on conditions, start scenes, refer to world objects, and run child phases. It does not make the referenced journal entry, scene, actor, trigger, or localized text exist.

That distinction is the first debugging tool: when a lookup fails, identify the resource that owns the missing thing before changing the graph that refers to it.

The resource layers

One player-facing beat can cross several rows. “Reach the marker and talk to a contact” needs at least a questphase, journal entries, localization, world markers and triggers, a community, and a scene. No one row silently supplies the others.

Depot paths

A depot path is the resource’s address inside the game’s virtual resource space:

mod\cqa\cqa001\phases\cqa001.questphase

The same address appears in several contexts:

• as a file beneath a WolvenKit project’s source\archive;
• as a ResourcePath value inside another CR2W resource;
• as an ArchiveXL registration path;
• as a path printed in packing or runtime logs.

Use the spelling and backslashes shown by WolvenKit. A Windows filesystem path such as H:\mods\... is not a depot path and must never be serialized as the resource address.

The mod\cqa\... prefix means that the example owns the resource. A reference to base\quest\cyberpunk2077.quest points to a vanilla resource; it does not copy that resource into the project.

Ownership versus reference

Owning and referring are different:

cqa001.questphase
    refers to journal path quests/minor_quest/cqa001

cqa001.journal
    owns the cqa001 journal entry

cqa001 journal entry
    refers to localization key cqa_cqa001_title

cqa001 onscreen localization
    owns the English text First Signal

Changing the questphase cannot repair a missing localization key. Changing the localization resource cannot activate an objective. Follow the lookup to its owner.

WolvenKit project layers

The examples use this source layout:

source/
├── archive/      CR2W resources at their intended depot paths
├── raw/          serialized review artifacts for mod-owned CR2W resources
└── resources/    loose ArchiveXL and other framework configuration

source\archive and source\resources have different installation destinations. Packing the CR2W tree does not automatically prove that the loose ArchiveXL file was staged, and seeing a valid .archive does not prove that the root questphase was registered.

The source\raw copies support review, round trips, and deterministic diagrams. They are documentation-author artifacts, not an instruction to make raw JSON editing the beginner workflow.

Lab 1 ownership map

Lab 1 deliberately stops at three native resources:

It has no world resource. That is why player position is irrelevant to Lab 1.

Diagnostic questions

When a feature is absent, ask in this order:

1. Does the owning resource exist at the exact depot path?
2. Was that resource packed or staged in the correct installation layer?
3. Was it registered or merged where required?
4. Does the referring resource use the correct identifier domain?
5. Does runtime state permit this resource to activate now?

A graph edit belongs at step five only when the first four answers are already known.

Graph execution

A questphase graph is a set of node definitions connected through named sockets. Execution enters a node through an input socket, the node performs its operation or evaluates its condition, and execution continues through one or more output sockets.

The graph is not executed according to the order in which nodes happen to appear in serialized JSON or in a WolvenKit list.

Nodes, sockets, and connections

Every quest node has a graph-local numeric id and an array of socket handles. A socket has:

• a name such as In, Out, Active, Succeeded, True, or False;
• a direction or role such as Input, Output, or CutDestination;
• zero or more graph connections.

A connection joins one source output socket to one destination input socket:

node 12, Out  ──────────>  node 13, In

The socket names carry semantics. Sending execution into Active on a journal node activates an entry; sending it into Succeeded changes that same entry to a different state. The node type and path can be identical while the incoming socket changes the operation.

Entry and termination

A small child-compatible phase commonly exposes:

questInputNodeDefinition   socketName: In1
    ...
questOutputNodeDefinition  socketName: Out1
                           type: Terminating

In1 and Out1 are the phase interface. Internal node sockets can still be named In and Out.

A terminating output is an explicit lifecycle boundary. Reaching the last gameplay node is not the same as terminating the phase unless an edge reaches the output node.

Evaluate now versus wait

The two most important condition shapes have different control semantics.

questConditionNodeDefinition

This node evaluates when execution reaches it and immediately chooses a named output such as True or False.

Lab 1 uses it for:

cqa001_completed == 0
    True  -> activate the quest
    False -> terminate

It does not wait for a false condition to become true.

questPauseConditionNodeDefinition

This node holds its execution path until the condition becomes true, then emits Out.

Lab 1 uses a questRealtimeDelay_ConditionType for ten seconds. Later chapters use pause conditions for facts, triggers, actor readiness, inventory, and other wait-until gates.

Replacing one condition node type with the other changes the quest’s behavior even if their nested comparison data looks identical.

Fan-out, joins, and ordering

One output can connect to several inputs. That starts several paths; it does not establish a secret order among them.

arrival
  +-> update objective
  +-> start hostility setup

If later work requires both paths, use a node with explicit join semantics. If only the first signal should win, use a race/XOR shape. Do not use visual proximity or JSON array order as a substitute for control flow.

An ordered sequence needs edges:

activate community
  -> wait for spawn readiness
  -> start scene

Starting all three from one fan-out would permit the scene to begin before its actor is ready.

Ordinals are local semantics

Some scene and quest node types attach ordinals to ordered sockets or options. An ordinal belongs to that node type’s local contract; it is not the execution order of the entire graph.

For example, Observed in vanilla, scene choice nodes use option socket ordinals and additional padded sockets. That rule does not mean every quest output socket needs an ordinal or that node ID 12 executes before node ID 13.

Preserve ordinals when copying a verified node shape. Explain their purpose before generating or renumbering them.

Cut and interrupt sockets

Many graph nodes contain a CutDestination socket in addition to their normal inputs and outputs. It belongs to cancellation or interruption routing, not to ordinary success flow.

The presence of the socket does not mean every tutorial should wire it. Interruption policy must answer:

• what work is currently active;
• what journal or world state must be cleaned up;
• whether a scene or child phase must receive a cut;
• which output tells the parent that interruption is complete.

Until a guide proves those answers, an unwired cut socket should be described as a visible lifecycle obligation rather than filled with a guessed edge.

Reading the Lab 1 graph

Trace the exact Lab 1 figure by following socket labels:

1. In1 emits Out into the one-shot guard’s In.
2. True enters the quest journal node through Active.
3. Each ordinary Out advances the first-run sequence.
4. The delay’s Out enters the objective through Succeeded.
5. The final quest journal operation enters through Succeeded.
6. Both the guard’s False route and the successful route reach the same terminating output.

That trace explains behavior without relying on how WolvenKit arranged the boxes.

Identifier domains

Cyberpunk resources place many identifier types beside one another. Similar text or numbers do not make them interchangeable.

Domain map

Never derive one domain from another merely because the values can both be printed as strings or integers.

CR2W handles

A CR2W handle gives one serialized object an identity:

{
  "HandleId": "15",
  "Data": {
    "$type": "questFactsDBManagerNodeDefinition",
    "id": 15
  }
}

Another field can refer to that object:

{ "HandleRefId": "15" }

The graph node id and HandleId happen to both be 15 in this shortened example, but they serve different domains and are not required to match.

Handle rules:

• a HandleRefId must resolve to one compatible HandleId;
• handle identity is local to the serialized CR2W object graph;
• duplicating a handled object without repairing its internal references can create dangling or aliased structure;
• Structurally validated: WolvenKit round trips can normalize handle allocation while preserving the same node/socket graph.

For this reason, exact diagrams fingerprint semantic nodes, sockets, and edges, not the incidental handle numbers assigned by one serialization pass.

NodeRefs

A NodeRef identifies something registered in the world or beneath a quest-prefab root:

#cqa_example_trigger
$/mod/cqa/#cqa_example_prefab/#cqa_example_trigger

It is not a CR2W handle. A valid-looking NodeRef string still fails if no loaded streaming resource registers that reference or if the questphase does not declare the required prefab dependency.

Later world chapters explain:

• streaming-sector nodeRefs;
• QuestPrefabRefHash;
• streaming-block questPrefabNodeRef;
• questphase phasePrefabs;
• full versus local NodeRef paths.

Lab 1 contains no NodeRef, which is why it has no position or streaming requirement.

Journal paths

A journal path names a position in the merged journal tree:

quests/minor_quest/cqa001/cqa001_01/cqa001_01_obj_wait

The accompanying fileEntryIndex identifies the path component that belongs to the containing gameJournalFileEntry. For the Lab 1 path it is 2, the zero-based position of cqa001:

0: quests
1: minor_quest
2: cqa001

It is not the objective’s index, a graph node ID, or a CR2W handle.

Names are typed

Plain text in WolvenKit can represent several serialized types:

"Out1"                                  CName
"mod\cqa\...\cqa001.questphase"         ResourcePath
"#cqa_example_trigger"                  NodeRef
"Items.ExampleItem"                     TweakDBID
"cqa001_completed"                      fact name

Record the type beside a value when documenting it. “Set this field to cqa001” is incomplete if the reader cannot tell whether the field expects a path, CName, fact, journal ID, or record ID.

Scene IDs are not one pool

Scenes add several numeric domains: scene graph nodes, actors, performers, screenplay items, localization strings, localization variants, and timed events. Observed in vanilla patterns can constrain one of those domains, but they do not authorize reusing the same number across all of them.

The scene section will document each domain when the corresponding object is introduced. Until then, treat “scene ID” as an ambiguous phrase that needs a type.

Facts, journals, and saves

A quest graph does not start from a blank state every time an archive changes. Facts, journal state, active quest work, checkpoints, scenes, communities, and devices can outlive the game session that created them.

That makes the save part of the test input.

Facts are integer state

Quest facts are signed integer values addressed by name. In the tested quest fixtures, an unset fact reads as 0.

Common conventions:

The engine does not know that _completed means completion. The graph gives the value meaning by deciding when to read and write it.

Prefer event-specific names:

cqa001_completed
cqa002_offer_sent
cqa002_job_accepted

One overloaded quest_state fact makes re-entry and failure diagnosis harder because unrelated transitions erase one another.

Snapshot and wait semantics

The same fact comparison can support two behaviors:

Condition:
    evaluate cqa001_completed == 0 now
    choose True or False

PauseCondition:
    hold this path until cqa001_completed == 0

Choose the node according to control semantics, not according to the fact family.

One-shot protection

Lab 1 uses:

if cqa001_completed == 0:
    run quest
else:
    terminate

The fact is set before the quest reaches its successful terminating output. On the next root evaluation, the False branch terminates without reactivating the journal.

Runtime testing must still cover interruption between the fact write and quest completion. A graph that looks one-shot on the happy path can expose partial state after a save, crash, reload, or cut.

Journal state is also persistent

Journal entries can retain states such as inactive, active, succeeded, or failed. Some entry families also retain visited state.

These are separate questions:

• Is the entry active?
• Has the player visited or opened it?
• Has its objective succeeded?
• Is the quest currently tracked?

Do not substitute a visited condition for an objective state or assume that activating an entry proves the player saw its presentation.

Other save-backed systems

Research fixtures have demonstrated persistence involving:

• quest facts;
• journal activation and visited state;
• active questphase branches and checkpoints;
• scene state;
• community and actor lifecycle;
• device persistent state associated with a NodeRef.

A newly packed CR2W resource cannot erase the older state already stored in a save. Device tests may require both a clean save and a fresh NodeRef identity when deliberately invalidating a previous device instance.

What “clean save” means

For a focused quest start test, use a manual save created before any version of that quest mod was installed or registered.

Avoid:

• an autosave created after the quest first activated;
• a save made after a failed graph or scene probe;
• a save where the journal entry was already visited;
• a save that streamed an older version of a persistent device.

Resetting one fact is useful for diagnosis, but it does not clear every journal, checkpoint, scene, community, or device record. A console reset is therefore not equivalent to a clean save.

Minimum save test matrix

For a one-shot quest:

1. First load: start from the known pre-mod save and observe activation.
2. Mid-flow reload: save while the objective is active, reload, and record whether the intended node resumes.
3. Completed reload: save after completion, reload, and verify no reactivation.
4. Reinstall same build: prove that reinstalling does not change the result already stored in the save.
5. Clean replay: return to the original pre-mod save for another first-run pass.

Record which save was used with the archive filename and test result. “Works on my save” is not enough evidence to reproduce a lifecycle claim.

Root and child questphases

A root questphase is registered beneath the game’s quest root. An external child questphase is a separate archived resource invoked by a node in another phase. They use the same CR2W resource type, but registration, ownership, and interfaces differ.

Root registration

ArchiveXL attaches a mod-owned root:

quest:
  phases:
  - path: mod\cqa\cqa001\phases\cqa001.questphase
    parent: base\quest\cyberpunk2077.quest

The registration makes the resource reachable from the game’s root quest structure. It does not create journal or localization entries; those remain separate registrations.

Register only the root phase. An external child must be present at its depot path in the packed archive, but it is reached through the parent node’s phaseResource; it is not a second ArchiveXL root registration. Registering every child beneath base\quest\cyberpunk2077.quest changes the composition instead of satisfying the reference.

Lab 1 is a single root phase. Its input reaches the one-shot guard without a location gate, so it can activate independently of player position. Lab 4 keeps one registered root and resolves its boundary activity as an external child.

Child-phase interface

A parent uses questPhaseNodeDefinition to refer to another questphase through its soft phaseResource. Lab 4 uses this returning-child interface:

parent questPhaseNodeDefinition
    phaseResource: mod\cqa\...\child.questphase
    input socket:  In1
    output socket: Out1

child questphase
    questInputNodeDefinition.socketName:  In1
    questOutputNodeDefinition.socketName: Out1

Socket names form the contract for this arrangement. The parent’s In1 maps to the child’s exposed input, and the child’s Out1 maps back to the parent node’s output.

The path and the socket contract solve different problems. A returning child cannot hand control back through Out1 when that socket is absent, misspelled, or unconnected. Matching sockets cannot rescue a missing archived child resource. This is not a rule that every external phase needs an output: Observed in vanilla, the focused sts_wat_nid_03 root also contains an input-only external phase node. Its absence of Out1 is a different lifecycle, not an inherently defective resource.

Named outputs can represent distinct results, especially for scenes and later branching phases. An output named accepted is not interchangeable with failed merely because both terminate the child.

Why create a child phase?

Use a child when it creates a meaningful ownership boundary:

• a reusable or independently testable activity;
• a lifecycle with its own setup and cleanup;
• a graph large enough to obscure the parent orchestration;
• a resource that owns specific world-prefab dependencies;
• a stage with named outcomes the parent must consume.

Do not create a child merely to hide one unexplained node. The book explains the child’s complete graph and every required external resource.

Parent and child responsibilities

A useful split looks like:

root
  -> decide whether the quest should run
  -> activate top-level journal state
  -> run child activity
  -> consume child outcome
  -> complete or choose the next child

child activity
  -> acquire or activate its dependencies
  -> wait for readiness
  -> perform the focused work
  -> clean up what it owns
  -> emit a named result

The parent should not assume that starting a child automatically creates its community, scene, journal entries, or world objects. The child can coordinate those resources only after they have been authored and registered.

Registration here means registration appropriate to the resource: the quest root, journal tree, localization tables, and streaming block have their own merge points. An external child questphase itself is archived and referenced by phaseResource, not independently merged into the game quest root.

Inline and external phases

A phase node can point to an external phaseResource; CR2W also has structures for inline/inplace phase graphs. This book starts with external mod-owned resources because their depot paths, ownership, downloads, and round-trip inspection are explicit.

Do not generalize an inline vanilla shape into a reader template until its inheritance, prefab, and save behavior have been isolated.

Prefab dependencies

World-aware phases can declare quest-prefab dependencies:

• root phasePrefabs declares prefab roots owned by that phase composition; the usable scope can include external children invoked beneath the root;
• a phase node has a separate, node-local phaseInstancePrefabs array. Its presence is not evidence that a tool must duplicate the root declaration there.

Observed in vanilla: base\open_world\street_stories\watson\northside_industrial_district\sts_wat_nid_03\phases\sts_wat_nid_03.questphase declares a prefab while its external sts_wat_nid_03_openworld.questphase child has an empty declaration and uses references beneath that prefab. The observation supports root-owned scope; it does not replace a mod-owned runtime test.

Lab 4 declares #cqa004_pr_handoff on the root, leaves the child’s prefab list empty, and keeps phaseInstancePrefabs empty on the invoking node. Test NodeRef resolution while the child is active, then after streaming and reload.

Do not turn an authoring tool’s convenience switch into an engine rule. Research tooling may expose an inherit_phase_prefabs policy that copies or propagates declarations while producing test resources. That remains tool policy, not proof that native CR2W requires the copy. Inspect the emitted phasePrefabs, phaseInstancePrefabs, and phaseResource values and validate the resulting game-resource arrangement.

Lab 1 has empty prefab arrays because it contains no NodeRef. Lab 3 keeps its reach/leave world activity in one root. Lab 4 moves that activity pattern into an external child so the root-owned prefab scope and handoff are visible in a small graph.

Completion handoff

Completing the last internal action does not automatically advance the parent. The child must reach its output, and the parent node’s matching output must have an outgoing connection.

Review both sides:

1. Does every intended child route reach an output?
2. Do the output names match the parent phase node?
3. Does every parent output lead somewhere intentional?
4. Do cut or failure routes clean up before handoff?

An orphaned Out1 is a graph defect even when the child looks complete in isolation.

CutDestination sockets are structurally present on the focused external phase-node shape, but that does not establish their runtime interruption semantics. Lab 4 deliberately leaves them unconnected and labels cut behavior Experimental rather than inventing a safe cleanup recipe.

The Questphases section continues with the exact resource anatomy, interface properties, external-child fields, prefab dependencies, and interruption review. Lab 4: Handoff Point applies the model to downloadable start and completed checkpoints.

Lifecycle and cleanup

Quest authoring is lifecycle design. The happy path is only one transition through a system that can be saved, reloaded, interrupted, re-entered, or installed over older state.

A complete activity lifecycle

A focused activity usually has these responsibilities:

activation
  -> dependency readiness
  -> player-facing work
  -> outcome capture
  -> presentation completion
  -> cleanup
  -> handoff or termination

The owner of an activated dependency should also define when it is released. Examples include:

• deactivate a community after the player leaves a safe boundary;
• hide or inactivate a mappin when its objective ends;
• stop a parallel failure monitor after success;
• return a named scene outcome before terminating its child phase;
• leave persistent facts intact when they are the intended re-entry guard.

Cleanup is not synonymous with resetting everything. Completion facts and journal history may intentionally persist while transient actors, markers, and monitors stop.

Completion ordering

Ordering is observable:

succeed objective
  -> set completion fact
  -> succeed quest
  -> terminate

Moving the fact earlier may prevent recovery from a partial run. Moving it after termination may make it unreachable. Setting the quest succeeded before its objective can produce confusing presentation.

There is no universal ordering for every quest. State the intended invariant, then test interruption at the boundaries that matter.

Re-entry policy

Every root or repeatable activity needs an explicit policy:

“The graph starts at its input” does not answer what should happen when saved state says some of its work is already active.

Cut and interruption

A cut path is a different outcome, not a shortcut to the normal final node. Before wiring it, decide:

• which scenes or child phases receive interruption;
• which objectives fail, become inactive, or remain resumable;
• which communities, devices, or markers remain valid;
• which facts distinguish interruption from success;
• whether the parent terminates, retries, or chooses another branch.

Complex interruption is introduced only after the normal lifecycle is runtime-proven. A guessed cleanup route can be more destructive than leaving an experimental socket unwired.

The validation ladder

Each check proves a different claim:

“WolvenKit saved it” and “the archive packed” are therefore intermediate evidence, not completion.

Foundation checkpoint

Before proceeding to a lab, be able to explain:

1. which resource owns every referenced object or string;
2. how execution enters and leaves every node;
3. the type and domain of every identifier;
4. which state can already exist in the save;
5. who owns cleanup and termination;
6. how you will test completion, interruption, and reload.

If one answer is “the template handles it,” the resource has not yet been explained.

Lab 1: First Signal

Lab 1 establishes the smallest useful native quest loop: register a root questphase, show one objective, wait ten real-time seconds, complete the objective and quest, persist a one-shot guard, and terminate.

The supplied resources pass WolvenKit 8.19.0 deserialization and round-trip checks. Follow the test chapter to verify activation, timing, journal state, reload, reinstall, and clean replay in your game.

The complete manual WolvenKit authoring, installation, test, and reset walkthrough builds this design from the empty checkpoint. This page remains the concise resource and graph reference.

Outcome

On a clean save, the intended player-facing sequence is:

root quest starts
  -> already completed?
     +-> yes: terminate
     +-> no: show First Signal and Wait for the signal.
          -> wait 10 real-time seconds
          -> complete objective
          -> persist cqa001_completed = 1
          -> complete quest
          -> terminate

There is no trigger, marker, scene, character, device, combat encounter, or custom world resource. Those systems enter in later labs.

Prerequisites and tested baseline

Read Foundations first. The lab assumes you can distinguish resource ownership, socket semantics, identifier domains, and save-backed state.

Use the exact pinned version set: Cyberpunk 2077 2.31a, WolvenKit 8.19.0, ArchiveXL 1.27.0, RED4ext 1.30.0, and the pinned redscript 0.5.31 (ArchiveXL requires 0.5.31 or newer).

The example has two checkpoints:

• Download the start checkpoint, an empty WolvenKit project;
• Download the completed checkpoint, containing the mod-owned resource set and serialized review artifacts.

The source directories remain available on GitHub.

Use a dedicated test save. The completion fact is stored in the save and is deliberately not reset by the quest.

Follow the manual authoring walkthrough to create the resources, enter the property paths, wire every socket, install the project, and run the Experimental clean-save acceptance matrix.

Resource model

Three native resources and one framework file divide responsibility:

The questphase does not contain the text “First Signal.” It changes journal entry state. The journal contains localization keys, and the onscreen localization resource resolves those keys to text.

Journal tree

The journal resource supplies this exact tree:

quests
└── minor_quest
    └── cqa001                         gameJournalQuest
        └── cqa001_01                  gameJournalQuestPhase
            └── cqa001_01_obj_wait     gameJournalQuestObjective

Localization keys:

Questphase journal paths use fileEntryIndex: 2, the zero-based path component for the containing cqa001 file entry in quests/minor_quest/cqa001/.... This value is not the leaf index and is not a CR2W handle.

Exact questphase

The figure is generated from the supplied WolvenKit CR2W-JSON. Match its node IDs, socket names, and connections to your graph; editor layout can differ.

Condition and PauseCondition are not interchangeable. ID 10 snapshots a fact and immediately chooses one output. ID 13 keeps waiting until its time condition becomes true.

The completion fact is set after the objective succeeds but before the quest succeeds. If testing later exposes a save interruption between those nodes, the ordering must be revisited and recorded rather than silently called safe.

Registration

ArchiveXL registers the root and resource merges:

quest:
  phases:
  - path: mod\cqa\cqa001\phases\cqa001.questphase
    parent: base\quest\cyberpunk2077.quest

journal:
- mod\cqa\cqa001\journal\cqa001.journal

localization:
  onscreens:
    en-us:
    - mod\cqa\cqa001\localization\en-us\onscreens\cqa001.json

The parent path is a vanilla depot reference. The example cites it; it does not redistribute the base-game resource.

See Registering a root questphase for the difference between root reachability, location gates, resource merges, and runtime proof.

Verification plan

Structural checks already completed:

The supplied resources have been round-tripped with WolvenKit 8.19.0. Compare the node IDs, sockets, connections, journal tree, and localization keys with your authored project.

Runtime acceptance still required:

1. start from a save that has never loaded cqa001;
2. confirm the quest and objective activate once;
3. confirm completion occurs after ten seconds of real time;
4. confirm the objective and quest both show succeeded presentation;
5. save, reload, and confirm the quest does not reactivate;
6. inspect ArchiveXL and game logs for registration or lookup errors.

Until those checks pass, expected behavior is not runtime proof.

Common failure boundaries

• If nothing starts, inspect ArchiveXL root-phase registration and the depot path before changing graph logic.
• If text is blank, compare journal localization keys with onscreen secondary keys. Journal IDs are not localization IDs.
• If the objective remains active, verify that the edge enters ID 14 through Succeeded, not Active.
• If the quest repeats, check cqa001_completed on the exact save used for the second run.
• If a test appears fixed after editing a device, journal, scene, or fact, repeat it on a clean save before attributing the change to the resource edit.

Lab sequence: All labs · Next: Author First Signal in WolvenKit.

Lab 1: author First Signal

This walkthrough builds the complete First Signal checkpoint from the empty Lab 1 WolvenKit project. You will create three mod-owned CR2W resources, wire the quest graph, add the ArchiveXL registration, install the project, and run a save-aware acceptance pass.

The supplied checkpoint passes WolvenKit 8.19.0 structural checks. Follow the test procedure after authoring so you can compare the expected route with what actually happens in your game.

Use this exact baseline:

• Cyberpunk 2077 2.31a;
• WolvenKit 8.19.0;
• ArchiveXL 1.27.0;
• RED4ext 1.30.0;
• redscript 0.5.31 (ArchiveXL 1.27.0 requires 0.5.31 or newer).

Complete the pinned toolchain setup, review the project and resource structure, and read Lab 1’s design before starting. Keep the completed checkpoint extracted in a separate directory for comparison.

Editor boundary used in this guide

WolvenKit 8.19.0 exposes these named commands in the tested editor:

• File > New File for an empty CR2W or ArchiveXL file;
• Add Node on an empty part of a quest graph;
• Show Unused Sockets on a graph node;
• Node Properties beside the quest graph;
• Project > Scan for broken file references, Scan for broken files, and Run File Validation on the entire project;
• Build > Install.

The nested CR2W type chooser is contextual: its placement and visible rows depend on the selected property. Where that makes a click label ambiguous, this guide gives a RED property path instead. At that path, use the plus control whose tooltip is Add Handle for a null handle or Add New Element for an array, then choose the exact RED type named here. This is still an in-editor workflow. Do not edit the serialized files under source\raw.

1. Open the start checkpoint

1. Extract the start checkpoint to a writable working directory outside the game directory.

2. In WolvenKit, choose File > Open Project and open CQA_Lab01_OneShot_Start.cpmodproj.

3. Save a separate backup of that freshly extracted directory. WolvenKit’s quest editor has no general undo/redo safety net for this graph workflow.

4. In the Project Explorer, open the source\archive directory in Windows Explorer and create this directory tree:

   mod\cqa\cqa001\
   ├── journal\
   ├── localization\en-us\onscreens\
   └── phases\
   

The start checkpoint’s project ModName ends in _Start, so its packed archive will be named CQA_Lab01_OneShot_Start.archive. That external archive name can differ from the completed checkpoint’s archive name; the depot paths inside it must match exactly.

2. Create the three CR2W resources

Create each file through File > New File. Choose the CR2W Files category, select the listed root type, replace the proposed name with the relative path below, and select Create.

The last file has a .json depot extension but is a binary CR2W JsonResource. It is not the plain-text review file whose name ends in .json.json in the completed checkpoint.

Press Ctrl+S after creating each file. The empty questphase should already contain a non-null questGraphDefinition; this is the scratch-file behavior of WolvenKit 8.19.0.

3. Author the journal tree

Open cqa001.journal. Work in the CR2W property tree and build this handle chain:

RootChunk                                      gameJournalResource
└── entry                                      gameJournalRootFolderEntry
    └── entries[0]                             gameJournalPrimaryFolderEntry
        └── entries[0]                         gameJournalFolderEntry
            └── entries[0]                     gameJournalQuest
                └── entries[0]                 gameJournalQuestPhase
                    └── entries[0]             gameJournalQuestObjective

At RootChunk.entry, add a handle of type gameJournalRootFolderEntry. At every following entries array, add one element and select the type shown above. Do not add an extra wrapper folder.

Set these properties. Paths use RED property names and array indexes, not CR2W-JSON HandleId wrappers.

In the abbreviated paths, ...cqa001 means entry.entries[0].entries[0].entries[0]; each later name identifies its one child entry.

base\journal\descriptor.journaldesc is the game-owned journal descriptor that supplies the standard hierarchy contract. It is a reference only: do not extract it into, rename it for, or redistribute it with the tutorial project.

Leave every entry’s journalEntryOverrideDataList empty. Leave the quest’s districtID empty and recommendedLevelID at zero. Leave the phase’s locationPrefabRef at zero. Leave the objective’s districtID empty and its itemID and locationPrefabRef at zero. These values are deliberate: Lab 1 has no district, item, marker, or world reference.

Press Ctrl+S, close the tab, and reopen it. Confirm that the six-entry chain and both localization keys survived serialization.

4. Author the onscreen localization

Open the CR2W cqa001.json under source\archive. At RootChunk.root, add a handle of type localizationPersistenceOnScreenEntries. Add two elements to its entries array; both elements are localizationPersistenceOnScreenEntry.

Set the resource and entries exactly:

This reproduces the structurally validated checkpoint shape. Runtime fallback and presentation for this new arrangement remain part of the Lab 1 Experimental acceptance run.

Save, close, and reopen the resource. Confirm the secondary keys exactly match the journal’s title.value and description.value strings.

5. Add the quest nodes

Open cqa001.questphase. Its Phase Resources view should show empty inplacePhases and phasePrefabs arrays. Leave both empty.

On an empty area of the graph, right-click and choose Add Node, then add the following nodes in order. The menu uses the short editor label; the second column records the serialized RED type.

WolvenKit assigns fresh IDs as nodes are created. Select each node and use Node Properties to set its id to the target value. If you created all nine first, change them in the table’s order: moving the initial input from 1 to 0 frees 1 for the output, and the remaining IDs move to the unused 10–16 range.

Set the interface fields:

socketName is the phase interface. It is different from the input node’s internal Out socket and the output node’s internal In socket.

Press Ctrl+S, close the questphase tab, and reopen it now. WolvenKit’s canvas can retain the wrappers’ original display IDs after an in-place id edit. Before following the ID-addressed steps below, verify that the graph now shows exactly [0], [1], and [10] through [16]. Reopening also rebinds the connector owners to the serialized IDs.

6. Configure the node payloads

ID 10: one-shot guard

At the node’s condition property, add a questFactsDBCondition handle. At condition.type, add a questVarComparison_ConditionType handle, then set:

This node evaluates once on entry. It does not wait for the fact to change.

IDs 11, 12, 14, and 16: journal operations

For each journal node, add a questJournalQuestEntry_NodeType handle at type. Then select type.path, choose Add Handle, and create a gameJournalPath handle. New journal nodes do not create that nested path for you. Set the common fields on all four nodes:

Then set each typed path:

IDs 12 and 14 address the same entry. Their incoming sockets will request different states.

ID 13: ten-second realtime gate

At condition, add a questTimeCondition handle. At condition.type, add a questRealtimeDelay_ConditionType handle and set:

miliseconds is the RED property spelling. This pause condition holds its path until the realtime delay becomes true.

ID 15: persistent fact write

WolvenKit initializes a new FactsDBManager node with a questSetVar_NodeType. Verify and set:

This writes exactly 1; it does not increment the existing value.

7. Expose and connect every socket

Right-click each node and choose Show Unused Sockets. Drag from each source output to the destination input in this table:

Socket inventory matters even when a socket is unused:

For ID 11, Active is connected. For ID 12, Active is connected. For IDs 14 and 16, Succeeded is connected. An edge entering a journal node’s ordinary-looking but wrong state socket changes the requested journal state.

The unused CutDestination sockets are visible lifecycle obligations, not missing normal-flow edges. Lab 1 does not claim cut-safe behavior. Do not wire them to the terminating output as a guess.

Press Ctrl+S, close the questphase, and reopen it. Compare the graph against the exact generated figure. Node placement may differ; IDs, types, sockets, payloads, and edges must not.

8. Register the resources with ArchiveXL

Choose File > New File, select the ArchiveXL category and ArchiveXL file, name it CQA_Lab01_OneShot.archive.xl, and select Create. WolvenKit places it under source\resources.

Enter this YAML exactly:

quest:
  phases:
  - path: mod\cqa\cqa001\phases\cqa001.questphase
    parent: base\quest\cyberpunk2077.quest

journal:
- mod\cqa\cqa001\journal\cqa001.journal

localization:
  onscreens:
    en-us:
    - mod\cqa\cqa001\localization\en-us\onscreens\cqa001.json

Save the file. The three entries have separate jobs: attach the executable phase beneath the vanilla quest root, merge the journal, and register the English onscreen strings. The parent path is a reference; do not extract or add base\quest\cyberpunk2077.quest to the project.

Your authored source tree should now contain:

source\
├── archive\mod\cqa\cqa001\
│   ├── journal\cqa001.journal
│   ├── localization\en-us\onscreens\cqa001.json
│   └── phases\cqa001.questphase
└── resources\CQA_Lab01_OneShot.archive.xl

9. Compare with the completed checkpoint

Open the completed .cpmodproj in a second WolvenKit instance, or close the start project and open the completed project after saving. Compare semantic structure, not binary bytes or CR2W handle numbers.

Check all of the following:

1. the three depot paths and ArchiveXL filename match;
2. the journal has the six exact types and IDs in one chain;
3. both journal localization keys resolve to the two secondary keys;
4. the questphase has IDs 0, 1, and 10–16, with no extra nodes;
5. the nine connections match the socket table above;
6. both outer questphase arrays are empty;
7. the condition, delay, fact-write, journal path, notification, and tracking values match the property tables;
8. the ArchiveXL YAML matches by registration meaning and depot path.

If you need a text diff, Project Explorer can export a mod-owned CR2W file to JSON under the mirrored source\raw path. Use that export only as a review artifact. Do not repair the lab by editing raw JSON, and do not compare HandleId allocation as if it were graph identity.

10. Validate, install, and inspect the install

With all tabs saved:

1. run Project > Scan for broken file references;
2. run Project > Scan for broken files;
3. run Project > Run File Validation on the entire project;
4. resolve every validation error owned by this project before continuing;
5. close Cyberpunk 2077;
6. choose Build > Install and wait for packing and installation to finish;
7. read WolvenKit’s Log panel rather than treating the button press as proof.

Use the normal Install command for this ArchiveXL project. Do not choose Install as REDmod or a hot-reload command. The full install, launch, log, and test procedure is collected in Install, test, and reset.

The vanilla journal descriptor and root parent are deliberate references; they need not be copied into the project. Treat any other unresolved reference or validation error as a stop condition, even if it does not spell out one of the three mod depot paths.

For the start checkpoint, verify these exact installed files beneath the game directory:

archive\pc\mod\CQA_Lab01_OneShot_Start.archive
archive\pc\mod\CQA_Lab01_OneShot.archive.xl

If you install the completed checkpoint instead, the archive is named CQA_Lab01_OneShot.archive. The loose .archive.xl must be present beside the archive in either case. A packed archive alone cannot register the root, journal, or localization resources.

After launching the game once, inspect:

red4ext\plugins\ArchiveXL\ArchiveXL.log
red4ext\logs\red4ext.log
red4ext\logs\game.log
r6\logs\redscript_rCURRENT.log

Search the ArchiveXL log for CQA_Lab01_OneShot.archive.xl, cqa001, or an error naming one of the registered depot paths. Confirm that RED4ext loaded ArchiveXL and that redscript did not report a new dependency/load error. Registration without errors is evidence about registration, not proof that the quest route executed.

11. Test and reset

Continue with Install, test, and reset. Use the archive built from your start project, CQA_Lab01_OneShot_Start.archive, and the shared CQA_Lab01_OneShot.archive.xl registration file.

That guide covers the first load, mid-flow reload, completed reload, reinstallation, clean replay, logs, and removal. Begin from a manual save made before any version of cqa001 was installed. Changing its completion fact alone does not reset the journal or saved graph state.

The intended first run activates First Signal and Wait for the signal., then succeeds after about ten real-time seconds. This behavior remains Experimental until tested. The terminating output has no separate visible indicator; infer it from the graph, successful journal state, and absence of reactivation.

To compare your build with the supplied completed checkpoint, close the game, remove the _Start archive, install the completed project, and repeat from the same untouched baseline. Keep only one checkpoint’s archive installed.

Failure routing

Serialization, validation, packing, ArchiveXL registration, and runtime behavior are different evidence steps. Keep the Experimental label until the clean-save matrix—not merely the successful build—has been retained.

Lab sequence: All labs · Previous: Lab 1: First Signal · Next: Install, test, and reset.

Install, test, and reset

Install Lab 1, check that First Signal appears and completes, then test reload and replay from separate saves. This guide works with either your authored start project or the supplied completed checkpoint.

The expected results below remain Experimental until observed in game. Keep notes of what actually happens, including failures or cases you cannot run.

Prepare an untouched save

The completion fact, journal state, and active graph state live in the save. Create or identify a manual save made before any version of cqa001 was installed or registered. Keep that save as an immutable baseline and make new save slots for test cases.

A useful label in your test notes is:

cqa001-clean-baseline — manual save created before first cqa001 install

Removing the mod after it has run does not erase state from a save. Setting cqa001_completed back to 0 with an optional console may help diagnose one branch, but it does not clear journal entries, quest checkpoints, scene state, communities, or devices. A fact edit is therefore never a clean-save result, and no console mod is required by this guide.

See Facts, journals, and saves for the state model behind this rule.

Install the completed checkpoint

If you just installed your authored start project, keep that installation and continue with the file and log checks below. Its archive is CQA_Lab01_OneShot_Start.archive; the loose registration file is still CQA_Lab01_OneShot.archive.xl. Use the _Start archive name wherever this guide names the completed archive, including removal.

To test the supplied completed project instead:

1. Exit the game completely.
2. Download and extract the completed Lab 1 checkpoint into a writable projects directory outside the game.
3. Open CQA_Lab01_OneShot.cpmodproj in WolvenKit.
4. Confirm the project contains the three cooked resources under source\archive\mod\cqa\cqa001 and source\resources\CQA_Lab01_OneShot.archive.xl.
5. Use the normal Install action. Do not choose Install as REDmod and do not use hot reload for this acceptance run.
6. Read WolvenKit’s Log panel. Stop if packing reports an error or an expected depot path is missing.

WolvenKit documents normal Install as “pack the project, then copy the generated packed hierarchy into the game directory” in its menu reference.

Verify these installed files exist:

<Cyberpunk 2077>\archive\pc\mod\CQA_Lab01_OneShot.archive
<Cyberpunk 2077>\archive\pc\mod\CQA_Lab01_OneShot.archive.xl

Install only one checkpoint at a time. Before switching, close the game and remove the other checkpoint’s archive so it cannot supply the same depot paths.

Check startup and registration logs

Launch the game and reach the point where a save can be loaded. After each test, preserve the relevant portions of:

<Cyberpunk 2077>\red4ext\logs\red4ext.log
<Cyberpunk 2077>\red4ext\logs\game.log
<Cyberpunk 2077>\red4ext\plugins\ArchiveXL\ArchiveXL.log
<Cyberpunk 2077>\r6\logs\redscript_rCURRENT.log

Check that RED4ext loaded ArchiveXL, redscript compiled without errors, and ArchiveXL did not report a failure resolving CQA_Lab01_OneShot.archive.xl or these depot paths:

mod\cqa\cqa001\phases\cqa001.questphase
mod\cqa\cqa001\journal\cqa001.journal
mod\cqa\cqa001\localization\en-us\onscreens\cqa001.json

Do not require a guessed fixed “success” sentence: log wording can change. Record the relevant actual lines. An ArchiveXL registration without errors is framework evidence, not proof that the graph ran or the journal rendered.

Run the save matrix

Use separate manual save slots for each state. Keep the installed build unchanged.

The player-facing oracle for the first and clean-replay cases is:

First Signal
  -> objective: Wait for the signal.
  -> approximately 10 real-time seconds
  -> objective succeeded
  -> quest succeeded
  -> cqa001 does not activate again on the completed save

“Approximately” allows UI presentation and load scheduling; the authored pause value is ten seconds. Record the measured observation rather than rounding it into a claimed exact runtime duration.

If you cannot create a save during the short active window, record the mid-flow case as pending. Do not convert an unrun case into a pass and do not change the delay merely to make this test easier to run.

Reset safely between runs

There are three different resets:

1. Project-output reset: WolvenKit’s Clean All removes the generated project packed directory. It does not remove installed game files, source resources, or save state.
2. Installation reset: with the game closed, remove only CQA_Lab01_OneShot.archive and CQA_Lab01_OneShot.archive.xl from <Cyberpunk 2077>\archive\pc\mod. Preserve them with the test record first if you need to reproduce a problem. Do not delete the whole mod directory.
3. State reset: load the preserved manual save that predates the first cqa001 installation. Reinstall the intended build before the clean replay.

For a controlled rebuild, close the game, clean project output, install once, then load the untouched baseline. Changing source files, framework versions, installed bytes, and starting saves at the same time makes the result impossible to attribute.

Diagnose by layer

Stop after the first failing boundary. Repacking repeatedly cannot fix a missing framework, and editing the graph cannot clean an old save.

Lab sequence: All labs · Previous: Author First Signal in WolvenKit · Next lab: Lab 2: Signal Race.

Questphases

A questphase is an executable quest graph stored as a questQuestPhaseResource. It coordinates progression; it does not replace the resources that own journal content, localized text, scenes, communities, or world objects.

This section turns the root-and-child model into exact native resource contracts:

1. Resource anatomy identifies the CR2W root, graph, nodes, sockets, external references, and dependency lists.
2. Registering a root separates ArchiveXL root attachment from normal depot-resource resolution.
3. Inputs and outputs separates a phase interface from the sockets used inside its graph.
4. Calling child phases documents questPhaseNodeDefinition and the parent/child handoff.
5. Prefab dependencies explains root-owned prefab scope, phasePrefabs, and phaseInstancePrefabs without inventing a universal inheritance rule.
6. Completion and interruption reviews terminating outputs, parent continuation, re-entry, and cut obligations.
7. Complex cleanup, interruption, and cancellation expands those obligations into an owner ledger for scenes, communities, AI, devices, markers, vehicles, monitors, and durable state.
8. Lab 4: Handoff Point moves Lab 3’s world activity into an external child and makes the boundary inspectable.

The practical pages target the exact pinned version set: Cyberpunk 2077 2.31a for Windows (GOG; public patch 2.31), WolvenKit 8.19.0, ArchiveXL 1.27.0, RED4ext 1.30.0, and redscript 0.5.31.

What belongs in a questphase?

A questphase owns execution order and orchestration. Its nodes can change a fact, update a journal entry, wait for a condition, invoke a child phase, or coordinate another native resource.

The referenced resource remains authoritative:

That distinction is visible in Lab 1: the phase contains no title text and no location. Lab 4 adds an external child, but that child still does not contain trigger geometry or journal strings. It refers to the world and journal resources that own them.

The composition boundary

Lab 4 uses one registered root and one externally resolved child:

ArchiveXL quest.phases
  -> cqa004.questphase                         registered root
       phasePrefabs: [#cqa004_pr_handoff]
       questPhaseNodeDefinition
         phaseResource (Soft)
           -> cqa004_boundary.questphase       archived child, not registered
                phasePrefabs: []
                In1 ... Out1
       Out1 from child -> parent continuation

Registration answers how the root becomes reachable. phaseResource answers which child the parent loads. The archive must contain both files at their exact depot paths, but only the root appears under ArchiveXL quest.phases.

Questphase resource anatomy

A .questphase file is a CR2W resource whose root chunk is questQuestPhaseResource. Its executable graph is only one part of that root.

The outer resource

These focused excerpts show the two completed Lab 4 phase resources. Serialization metadata and handle details are omitted:

cqa004.questphase
questQuestPhaseResource
├── cookingPlatform: PLATFORM_PC
├── graph: questGraphDefinition
│   └── nodes: [12 nodes]
├── inplacePhases: []
└── phasePrefabs:
    └── questQuestPrefabEntry
        └── prefabNodeRef: #cqa004_pr_handoff

cqa004_boundary.questphase
questQuestPhaseResource
├── cookingPlatform: PLATFORM_PC
├── graph: questGraphDefinition
│   └── nodes: [10 nodes]
├── inplacePhases: []
└── phasePrefabs: []

Structurally validated: Lab 4’s root contains one prefab entry and its external child contains none. Empty arrays are meaningful serialized values, not omitted work and not a universal rule.

The graph

questGraphDefinition.nodes contains handles to node definitions. Each node definition has:

• a graph-local integer id;
• one or more questSocketDefinition objects;
• properties specific to its node type.

Connections are stored from a source socket to a destination socket. The corresponding socket objects retain the connection handle, so a valid serialized graph must be internally consistent in both directions.

source node
  output questSocketDefinition
    graphGraphConnectionDefinition
      source      -> that output socket
      destination -> input socket on destination node

The graph-local id is the useful identity when discussing behavior. HandleId and HandleRefId are CR2W serialization references and can change during a WolvenKit round trip. See Identifier domains before comparing raw exports.

Nodes are typed records

Common fields do not make all nodes interchangeable. A condition node has a condition payload and branch sockets; a journal node has a typed journal operation and path; a phase node has either an external resource reference or an inline graph arrangement.

Lab 4 uses these types across its two graphs:

The Lab 4 overview explains every supplied node. The raw WolvenKit JSON beside each completed project is a review artifact, not a second reader authoring format.

Anatomy of an external phase node

Lab 4’s parent node uses this focused shape:

questPhaseNodeDefinition
├── id: 13
├── phaseGraph: null
├── phaseInstancePrefabs: []
├── phaseResource:
│   ├── DepotPath: mod\cqa\cqa004\phases\cqa004_boundary.questphase
│   └── Flags: Soft
├── saveLock: 0
├── sockets: [CutDestination, In1, Out1]
└── unfreezingTriggerNodeRef: 0

phaseGraph: null distinguishes this focused external-child shape from an inline graph. The soft depot path is not ArchiveXL registration. It is the parent resource’s reference to another archived CR2W resource.

saveLock: 0 and a zero unfreezing ref are exact values in the inspected shape. Their broader behavior is not inferred here. Lab 4 also leaves CutDestination unwired because the runtime semantics of a complete cut and recovery route remain Experimental.

Sockets carry semantics

A socket is not merely a visual port. Its name and type tell the runtime how execution enters, branches, or leaves a node.

name: "Active"          type: Input
name: "True"            type: Output
name: "Out1"            type: Output
name: "CutDestination"  type: CutDestination

The layer matters. The child input node exposes interface name In1, then emits internal graph flow through Out. The child’s terminating output node accepts internal flow through In, then exposes interface name Out1 to its parent. The parent phase node has its own In1 and Out1 sockets to match.

CutDestination belongs to interruption routing and is not an ordinary success edge. Structural presence alone does not prove runtime cut behavior.

Inspect without over-reading

When reviewing a .questphase:

1. Confirm RootChunk.$type is questQuestPhaseResource.
2. Confirm graph.Data.$type is questGraphDefinition.
3. Inventory every node by graph-local id and RED type.
4. Record each connected source socket and destination socket.
5. Inspect only the properties decisive for that node’s behavior.
6. Review inplacePhases, root phasePrefabs, and every phase node’s phaseInstancePrefabs separately.
7. For an external child, confirm phaseGraph is null and the soft phaseResource path resolves to an archived CR2W file.
8. Match the parent phase-node interface to child input/output node names.
9. Round-trip each binary and compare semantics, not raw handle numbering.

A successful parse is Structurally validated evidence. It does not prove that the game resolves the path, preserves an active child through reload, or returns control to the parent.

Previous: Questphases. Next: Registering a root questphase.

Registering a root questphase

A mod-owned root questphase becomes reachable from the game’s root quest structure through ArchiveXL registration. An external child becomes reachable through the parent’s native phaseResource reference. Those are different mechanisms.

Register exactly one composition root

Lab 4 registers only its parent:

quest:
  phases:
  - path: mod\cqa\cqa004\phases\cqa004.questphase
    parent: base\quest\cyberpunk2077.quest

path is the depot path of the mod-owned root. parent is the vanilla root quest resource under which ArchiveXL attaches it. The base-game resource is a reference only; do not place an extracted copy in the project or archive.

The child does not receive a second registration entry:

mod\cqa\cqa004\phases\cqa004_boundary.questphase

It must still be packed at that exact depot path. Parent node 13 reaches it through a soft phaseResource. Registering it independently would turn the child into another root attachment instead of merely satisfying the parent reference.

Registration and resolution are different edges

ArchiveXL quest.phases
  -> cqa004.questphase
       questPhaseNodeDefinition.phaseResource (Soft)
         -> cqa004_boundary.questphase in archive

The archive manifest should list both phase resources. The ArchiveXL quest.phases list should contain only cqa004.questphase. Lab 4’s validator rejects an independently registered child so the teaching boundary cannot silently drift.

Registration is not content ownership

Lab 4 also registers its journal, onscreen localization, and streaming block:

journal:
- mod\cqa\cqa004\journal\cqa004.journal

localization:
  onscreens:
    en-us:
    - mod\cqa\cqa004\localization\en-us\onscreens\cqa004.json

streaming:
  blocks:
  - mod\cqa\cqa004\world\cqa004_handoff.streamingblock

These operations answer separate questions:

ArchiveXL registers the streaming block, not its sector files separately. A root phase can register successfully and still fail because its child path, journal path, localization key, sector descriptor, or nested NodeRef is wrong.

Root does not mean location

Registration has no coordinate, radius, or NodeRef. Lab 4’s root gains world scope through its phasePrefabs declaration, but the external child contains the trigger conditions that use that scope. The world resources own the actual trigger geometry and marker placement.

This separation is deliberate:

A root needs a re-entry policy

Being attached to the root makes re-entry a design concern. Lab 4 keeps one persistent fact, cqa004_completed:

root input
  -> cqa004_completed == 0?
       False -> terminating output
       True  -> activate quest -> run child -> confirm handoff
             -> set cqa004_completed = 1 -> terminate

The write happens after the child has returned and after the parent’s 30-second confirmation step. A save made while the child is active and a save made in that parent confirmation window exercise different recovery boundaries.

Use an untouched save created before any Lab 4 candidate was installed. A console reset of the fact does not remove save-backed journal, phase, mappin, world, or active-node state.

Verification ladder

Check root composition in this order:

1. Confirm the .archive.xl registers only the exact root depot path.
2. Confirm the packed archive contains both root and child at the manifest paths.
3. Confirm the parent phaseResource.DepotPath exactly matches the child.
4. Confirm the loose .archive.xl is installed beside the archive as required by ArchiveXL.
5. Inspect ArchiveXL and RED4ext logs for registration and resource errors.
6. Run from a save whose relevant facts and journal state are known.
7. Observe child entry, child Out1, and the first parent-only operation after the handoff.
8. Retain installed filenames and repeat the reload/streaming matrix.

Packing proves that both payloads exist. A clean ArchiveXL log proves the framework processed registration. Only the controlled game run proves native child resolution and the return route.

Previous: Questphase resource anatomy. Next: Inputs and outputs.

Inputs and outputs

Questphase inputs and outputs form an interface around a graph. They are implemented by nodes inside the child resource and matched by sockets on the parent’s questPhaseNodeDefinition.

Two socket layers

The names are easy to conflate:

parent phase node                 child graph boundary
-----------------                --------------------
input socket In1            ->   input socketName In1
                                  ordinary socket Out -> child work

output socket Out1          <-   output socketName Out1
                                  child work -> ordinary socket In

questInputNodeDefinition.socketName names the entry exposed by the child. Execution then leaves that node through its ordinary Out socket.

questOutputNodeDefinition.socketName names the result exposed by the child. Execution reaches that node through its ordinary In socket.

Lab 4’s focused terminating-child contract is:

Those names are CName values. They are not graph-local IDs and not CR2W handle IDs.

Entry is a contract, not an activation rule

The input node says where execution enters after a phase has been invoked. It does not decide why or when that invocation happens.

Activation policy belongs outside that boundary:

• ArchiveXL root attachment makes a root reachable;
• parent graph flow reaches the phase node’s In1;
• the parent node resolves its external child;
• the first child action begins only after the child enters through its matching socketName.

Lab 4’s child 0.Out activates the reach objective. The location behavior comes from later IsInside and IsOutside conditions, not from In1.

Terminating output returns one outcome

With type: Terminating, reaching child output node 1.In ends that child route. Its socketName: Out1 maps the result to parent node 13.Out1.

The parent resumes only through that matching phase-node output:

child 17.Out -> child 1.In
  child exposes Out1
    -> parent 13.Out1 -> parent 14.Active

The connection from 13.Out1 to the parent’s confirmation objective is essential. A child output does not automatically select the next parent node.

Termination does not:

• reset facts;
• remove journal history;
• deactivate world dependencies automatically;
• invent an outgoing parent connection;
• prove the root will never be evaluated again.

Those are separate lifecycle decisions.

In1 and Out1 are not universal

Lab 4 deliberately uses the smallest focused interface: one input and one terminating output. Do not infer that every native phase node has both.

Observed in vanilla: extract these files from your own game:

base\open_world\street_stories\watson\northside_industrial_district\
  sts_wat_nid_03\phases\sts_wat_nid_03.questphase

base\open_world\street_stories\watson\northside_industrial_district\
  sts_wat_nid_03\phases\sts_wat_nid_03_openworld.questphase

The inspected root contains an external phase node with In1, Out1, and CutDestination, and another external phase node with In1 and CutDestination but no Out1. That second shape is enough to reject “all phase nodes have In1/Out1” as an engine invariant.

Use In1/Out1 here because the parent must wait for one child activity and then continue. Copy the interface contract appropriate to the lifecycle you are implementing, not the nearest-looking graph.

Connect every named outcome

A child can expose several meaningful results only when the complete parent and child arrangement supports them:

child output "accepted" -> parent phase-node output "accepted" -> continuation
child output "declined" -> parent phase-node output "declined" -> cleanup

Every outcome requires:

1. a reachable child output node with the intended socketName;
2. a same-named output socket on the invoking phase node;
3. an intentional parent connection or documented terminal policy;
4. runtime evidence for the exact arrangement.

Lab 4 makes no multi-outcome claim. It returns only Out1.

Cut is a separate socket class

Lab 4’s input, output, and phase nodes retain structurally valid CutDestination sockets. None is connected. CutDestination is not an alias for Out1, and an unwired socket is not a tested interruption policy.

The presence and serialized type are Structurally validated. The runtime behavior of a wired cut, its propagation across the child boundary, and the required recovery state remain Experimental.

Review checklist

For each interface node, record:

A phase can serialize while an intended outcome remains unreachable. Review reachability, exact names, and both resources together.

Previous: Registering a root questphase. Next: Calling child phases.

Calling child phases

A parent invokes an external child questphase with questPhaseNodeDefinition. The node is both a depot-resource reference and the parent side of the child’s interface.

External child shape

Lab 4 uses this exact focused shape:

questPhaseNodeDefinition
├── id: 13
├── sockets
│   ├── CutDestination     unwired
│   ├── In1                parent enters here
│   └── Out1               child returns here
├── phaseGraph: null
├── phaseInstancePrefabs: []
├── phaseResource:
│   ├── DepotPath: mod\cqa\cqa004\phases\cqa004_boundary.questphase
│   └── Flags: Soft
├── saveLock: 0
└── unfreezingTriggerNodeRef: 0

Do not copy non-zero values for the final two fields from a large vanilla quest without isolating their activation and save semantics.

The child is archived, not independently registered

The root and child are separate CR2W files and both must appear in the packed archive:

mod\cqa\cqa004\phases\cqa004.questphase
mod\cqa\cqa004\phases\cqa004_boundary.questphase

Only the first appears under ArchiveXL quest.phases. The second is resolved when the parent phase node follows phaseResource.

This distinction prevents two different ownership models from being confused:

• root registration attaches a new composition root under base\quest\cyberpunk2077.quest;
• external resolution loads a child because an executing parent names its depot path.

If the child is missing from the archive, registration of the parent can still look correct. If the child is separately registered, the files may load while the intended one-root ownership model has already been changed.

The interface must match

The parent and child meet at names, not at graph IDs:

parent cqa004.questphase
  [13] questPhaseNodeDefinition
    In1  -> child questInputNodeDefinition.socketName "In1"
    Out1 <- child questOutputNodeDefinition.socketName "Out1"

child cqa004_boundary.questphase
  [0] Input socketName In1
    Out -> reach/leave activity -> In
  [1] Output socketName Out1, type Terminating

Matching only the file path is insufficient. The parent node, child input, and child output must agree on the interface names, and the child route must actually reach its output.

Parent and child ownership

Split at a lifecycle boundary, not an arbitrary node count. Lab 4 makes the division concrete:

The ownership table is a deliberate design, not a file-format restriction. It makes the active child interval and the parent-only continuation visible for save/reload testing.

Exact handoff sequence

parent [12] phase Active
  -> parent [13].In1
     -> child [0] socketName In1
        -> reach objective and pin
        -> IsInside reach
        -> retire pin, succeed reach, activate leave
        -> IsOutside leave
        -> succeed leave
        -> child [1] terminating socketName Out1
     -> parent [13].Out1
  -> parent [14] confirmation objective Active

The active confirmation objective is the visible proof that normal child return reached parent-only work. Thirty realtime seconds later, the parent succeeds that objective, phase, completion fact, and quest.

If the child never reaches output 1, parent node 13 never emits its normal Out1. If 13.Out1 is orphaned, the child can finish without advancing the larger quest. The diagram also keeps CutDestination visible but unwired; it is not a hidden normal-return edge.

Root-owned prefab scope can cross this boundary

Lab 4’s parent root declares #cqa004_pr_handoff. The child directly uses nested trigger NodeRefs while its own phasePrefabs and the parent node’s phaseInstancePrefabs are empty.

See Prefab dependencies for the root, child, and phase-instance declaration locations.

External before inline

CR2W supports phaseGraph and inplacePhases, but this book begins with external mod-owned child resources because they provide:

• an explicit depot path;
• an independently inspectable graph;
• a clear archive manifest entry;
• a focused parent/child diff;
• separate exact SVGs and structural fingerprints.

phaseGraph: null is therefore the documented external-child shape, not a claim that the field must always be null. Inline phase activation, dependency scope, save behavior, and interruption need their own isolated evidence.

Validation

Before runtime testing:

1. Confirm the parent phaseResource.DepotPath matches the archived child.
2. Confirm the child is absent from ArchiveXL quest.phases.
3. Confirm both roots are questQuestPhaseResource.
4. Confirm external parent node phaseGraph is null and phaseInstancePrefabs is empty.
5. Match every parent input and output name to a child interface node.
6. Confirm each intended child route reaches an output.
7. Confirm each returned parent output has a continuation.
8. Inventory root and child prefab declarations separately.
9. Confirm no ordinary edge uses CutDestination in the unwired lab.
10. Round-trip parent and child independently.

Then test entry, reload before and during the child, streaming away and back while it is active, reload after return, and completed re-entry. One normal handoff does not establish save or cut safety.

Previous: Inputs and outputs. Next: Prefab dependencies.

Prefab dependencies

Quest-prefab dependencies give quest graph NodeRefs a world-side scope. They are not required for graphs that never reference the world, and their native lifecycle cannot be reduced to “duplicate every direct use.”

Root-owned scope

questQuestPhaseResource.phasePrefabs contains questQuestPrefabEntry records:

phasePrefabs:
  - questQuestPrefabEntry
      prefabNodeRef: #cqa004_pr_handoff

Lab 4 declares that entry on the registered root only:

cqa004.questphase
  phasePrefabs: [#cqa004_pr_handoff]
  invokes cqa004_boundary.questphase

cqa004_boundary.questphase
  phasePrefabs: []
  uses #cqa004_tr_reach and #cqa004_tr_leave

The root declaration can own the world scope used by an active external child. It is therefore too narrow to define phasePrefabs as “only roots directly used by nodes in this file.”

The supported statement is more precise:

A prefab declared by a composition root can remain available to external children in tested native arrangements. The exact root, child, and activation lifetime are part of the evidence.

That supports Lab 4’s design without claiming universal transitive inheritance.

Compare root and child declarations

Vanilla comparison

Observed in vanilla: extract these resources from your own game:

base\open_world\street_stories\watson\northside_industrial_district\
  sts_wat_nid_03\phases\sts_wat_nid_03.questphase

base\open_world\street_stories\watson\northside_industrial_district\
  sts_wat_nid_03\phases\sts_wat_nid_03_openworld.questphase

The inspected parent declares #sts_wat_nid_03_streetstory. Its external open-world child has phasePrefabs: [], while the child graph uses nested refs under that prefab. The invoking phase node also has phaseInstancePrefabs: [].

This is comparative evidence for the serialized shape. Do not redistribute the extracted CR2W resources, and do not treat observation alone as a runtime test of Lab 4.

Lab 4 candidate

Structurally validated: the completed Lab 4 parent contains exactly one root entry, the child contains zero, and phase node 13 contains zero instance-prefab entries. Both phase resources cook and round-trip with WolvenKit 8.19.0.

Experimental: mounting, child-time NodeRef resolution, streaming away and back, save/reload, and the eventual parent handoff remain pending until every Lab 4 runtime case passes.

Inspect all three declaration locations

Duplication changes the candidate

An external child is a separate questQuestPhaseResource, so it can serialize its own phasePrefabs list. Adding the same root there is not a harmless annotation: it changes the activation arrangement that must be tested.

Use one deliberate shape:

• root-only declaration when evidence and desired lifetime match Lab 4;
• duplicated declaration only when the exact duplicate arrangement has an identified lifecycle reason and its own runtime evidence.

Do not copy every child dependency into every ancestor, and do not duplicate a root merely because the child graph contains a local #... NodeRef.

Phase-instance dependencies are separate

questPhaseNodeDefinition.phaseInstancePrefabs is a second native dependency location associated with the phase-node instance. It is not interchangeable with either resource root’s phasePrefabs array.

The focused external-child examples used by this section keep phaseInstancePrefabs: []. Other arrangements, including inline phases, need separate evidence. Do not infer a universal precedence or fallback order among the three lists.

A prefab entry does not create the world

Declaring a prefab root is one link in a longer reference chain. Lab 4 uses:

root phasePrefabs: #cqa004_pr_handoff
  -> world-side full root: $/mod/cqa/cqa004/#cqa004_pr_handoff
     -> Quest sector child refs:
          #cqa004_tr_reach
          #cqa004_tr_leave
     -> AlwaysLoaded sector child ref:
          #cqa004_mp_handoff

The streaming block and sectors still have to provide the binding, nodeRefs, placements, and descriptors. A valid root entry cannot repair a misspelled child ref, missing sector registration, or absent world resource. Conversely, a world object can exist while remaining unreachable from the phase.

Review procedure

For a composed phase tree:

1. Inventory every non-zero NodeRef used by every phase resource.
2. Group local #... refs by the full root that gives them context.
3. Inventory each resource root’s phasePrefabs and each invoking node’s phaseInstancePrefabs separately.
4. Identify the composition root and the intended prefab activation lifetime.
5. Confirm the world-side resources bind the same full root and child refs.
6. Record whether each external child declares, duplicates, or omits the root.
7. Cite runtime evidence for the exact arrangement; do not infer a general inheritance rule from one success.
8. Test active-child reload, stream-away/return, normal completion, and cleanup from a controlled save.

World-aware examples retain depot paths and hashes for mod-owned resources. Vanilla comparisons cite paths and teach extraction; they never redistribute extracted CR2W files.

Previous: Calling child phases. Next: Completion and interruption.

Completion and interruption

A phase is complete only when execution reaches the intended output and its owner has performed the required state transitions. The last visible objective update is not an implicit return.

Normal child completion

Lab 4’s child ends with:

[16] wait until player IsOutside leave volume
  -> [17] leave objective Succeeded
  -> [1] terminating output socketName Out1

Reaching output node 1 terminates that child route and exposes outcome Out1. It does not itself finish the root quest.

Parent continuation is the second half

The parent phase node must expose the same name and connect it onward:

child [1] socketName Out1
  -> parent [13].Out1
  -> parent [14] confirmation objective Active
  -> [15] wait 30 realtime seconds
  -> [16] confirmation objective Succeeded
  -> [17] phase Succeeded
  -> [18] set cqa004_completed = 1
  -> [19] quest Succeeded
  -> [1] terminating output

The confirmation window exists to make the ownership transition observable and saveable. If objective cqa004_01_obj_confirm becomes active, normal execution has returned to parent-only work. A reload during that 30-second window tests a different boundary from a reload while the child is waiting on a trigger.

Review both resources. A terminating child output with no matching parent socket cannot convey the intended result. A matching parent socket with no outgoing connection receives the result and then advances nowhere.

Termination is not cleanup

Reaching a questOutputNodeDefinition does not, by itself:

• inactivate objectives or mappins;
• deactivate a community;
• stop a scene or parallel monitor;
• reset a device’s persistent state;
• clear or set a completion fact;
• choose what a parent does next;
• unload every prefab declared by an ancestor.

Lab 4’s child performs its local presentation transitions before return: the checkpoint pin is retired, the reach objective is succeeded, and the leave objective is succeeded. The parent owns the remaining confirmation and final quest completion.

Every transient dependency needs an owner and release boundary. Persistent progress remains only because the re-entry design calls for it.

Write durable state before terminating

Lab 4 writes cqa004_completed = 1 after the child has returned and the confirmation objective and phase have succeeded, but before the quest succeeds and the root terminates:

phase Succeeded
  -> set completion fact exactly to 1
  -> quest Succeeded
  -> terminate root route

Moving the terminating output earlier would make later writes unreachable. Moving the fact earlier would change which incomplete save boundaries take the already-completed bypass. The exact order is part of the recovery policy and must be tested, not inferred from one uninterrupted run.

Cut sockets are structural interruption surfaces

Many quest nodes expose a CutDestination socket. Its presence identifies a distinct socket class; it does not supply a correct interruption policy.

Lab 4 retains the serialized cut sockets on its relevant nodes and connects none of them. Its validator rejects any ordinary or cut edge involving CutDestination.

Do not draw a cut edge merely to make the graph look complete. Before wiring one, define:

1. what work may be active when the cut arrives;
2. which child, scene, or monitor receives interruption;
3. which journal entries become inactive, failed, or resumable;
4. which communities, markers, devices, and monitors are released;
5. which durable fact distinguishes cut from normal completion;
6. which child output tells the parent cleanup has finished;
7. which save/reload cases prove the recovery policy.

That requires a separate fixture. Lab 4 teaches normal Out1 handoff only.

Re-entry across two active owners

Termination ends an execution route, not the lifetime of all save-backed state. A composed quest has more than one meaningful reload boundary:

The runtime protocol also streams away and returns while the child is active, then tests completed reload, identical reinstall, and a second untouched clean replay.

Use a save created before any Lab 4 candidate was installed. Changing files, uninstalling, or writing cqa004_completed = 0 in a console does not erase save-backed journal, graph, mappin, world, or persistent-state history.

Review before composition grows

Before adding another child or parallel branch, verify:

• every normal child route reaches an intentional output;
• every parent output has a continuation or deliberate terminal policy;
• all transient dependencies have cleanup owners;
• persistent writes occur before their route becomes unreachable;
• post-return parent work is distinguishable from active-child work;
• cut remains explicitly unsupported or has a tested policy;
• the exact version set, installed filenames, and clean starting save are recorded.

Previous: Prefab dependencies. Next: Complex cleanup, interruption, and cancellation.

Complex cleanup, interruption, and cancellation

Complex cleanup is not one final node. It is a protocol among graph routes and the resources they activated: scenes, communities, AI, workspots, devices, markers, vehicles, inventory, journal state, and save-backed progress.

Use this chapter when an activity has more than one live owner or more than one way to end. Its goal is a teardown design in which every outcome records its meaning, stops or neutralizes outstanding work, releases each resource through its actual owner, and returns through an explicit phase interface.

success / failure / player cancel / interruption
  -> choose and persist one outcome
  -> stop new state-changing work
  -> let active consumers reach a safe release boundary
  -> retire presentation
  -> run owner-specific teardown
  -> confirm cleanup handoff
  -> write terminal state and terminate the owning route

There is no established native “clean up everything” operation. A cut edge, phase output, scene end, community deactivation, or vehicle command handles only its own bounded contract.

Vanilla references

These focused base-game resources are useful comparisons. Extract them from your own installation; they are references, not files to copy into the project.

base\open_world\minor_activities\watson\northside\ma_wat_nid_15\ma_wat_nid_15_phase.questphase
base\quest\minor_quests\mq003\phases\mq003_homeless.questphase
base\quest\minor_quests\mq003\scenes\mq003_01_homeless.scene
base\quest\side_quests\sq031\phases\sq031_porsche.questphase
base\open_world\street_stories\watson\northside_industrial_district\sts_wat_nid_03\phases\sts_wat_nid_03_gameplay.questphase

Name the exit before choosing the cleanup

Different endings require different state and sometimes different release orders:

Do not converge these exits before recording their meaning. If success and cancel both reach cleanup with no discriminator, a save taken during teardown cannot know which presentation, retry, or terminal state to restore.

Build an owner ledger

Before drawing edges, list every resource that may be active and the exact operation that acquired it:

Give each row one cleanup owner. Shared responsibility is usually an unresolved handoff: the scene assumes the quest will retain an actor while the quest assumes scene End already released it.

Separate selection, quiescence, release, and finalization

A robust teardown has four boundaries.

1. Select one outcome

The winning branch records its outcome before it reaches shared teardown:

success signal -> set activity_outcome = success --+
failure signal -> set activity_outcome = failure --+-> cleanup entry
cancel signal  -> set activity_outcome = cancel  --+

Use facts, journal states, or explicit named outputs that the owning design can read after reload. Do not award, remove an item, or mark the whole quest complete merely to create a discriminator.

An XOR-shaped convergence is not proof that losing producers were cancelled. Every late route must either be harmless after the outcome write or be the target of a separately accepted cut topology.

2. Quiesce producers and consumers

Stop new state-changing work before removing the resources it addresses:

• make losing monitor outputs bypass journal, fact, reward, and world writes;
• wait for a scene’s intended named outcome rather than assuming section End released every performer;
• end or transfer follower, patrol, combat, workspot, carry, and seat roles;
• finish or explicitly interrupt device UI/personal-link/workspot ownership;
• stop spawning new waves before deactivating the encounter;
• decide how an active timer or delay behaves after the outcome is sealed.

Quiescence can be logical rather than destructive. A listener that remains active but cannot mutate state may be safer than an unproved cut operation.

3. Release owner-specific transients

Retire each resource through the system that owns it:

journal/mappin owner  -> outcome-specific state + pin inactive
scene owner           -> named exit / accepted interruption contract
AI/workspot owner     -> explicit handoff or release command
community owner       -> Spawn Manager Deactivate at safe boundary
device owner          -> evidenced final controller/disconnect policy
vehicle owner         -> source-specific deactivation or vehicle-system action
world owner           -> leave placement to streaming unless a resource-specific action exists

The order may differ by branch. A failed combat encounter may need to stop waves before actor deactivation; a successful meeting may need the named scene exit, journal write, outer-area exit, and only then community deactivation.

4. Confirm handoff and finalize

Return from a cleanup child through a named output such as cleanup_done, then let the parent write the terminal one-shot state and terminate. The output proves only that the graph issued its cleanup sequence. Runtime observation must still prove that actors, UI, vehicles, markers, and persistent state match the intended result.

child cleanup_done
  -> parent receives matching socket
  -> terminal journal state
  -> completion fact
  -> root output

Write no required state after a terminating output; that route is unreachable. Also avoid writing the parent’s terminal fact before the child can finish its teardown, unless re-entry intentionally bypasses cleanup and that policy is tested.

Cut stops a graph target, not its world consequences

questCutControlNodeDefinition exposes ordinary flow plus CutSource. Targets such as Pause Conditions expose CutDestination. The Cut Control also serializes a permanent field.

Observed in vanilla: in the cited ma_wat_nid_15_phase.questphase, Cut Control node 236 has a CutSource edge to character-killed listener node 225 at its CutDestination. Across the retained corpus, cut edges commonly target Pause Conditions. This establishes explicit target wiring.

It does not establish that a cut:

• rolls back a fact or journal write already emitted;
• deactivates a community or removes a marker;
• stops a scene, AI command, vehicle, or device unless that exact target and consequence are separately evidenced;
• emits the target’s ordinary output;
• survives reload or permits re-entry in a particular way;
• is reversible when permanent is false or irreversible when true.

Those semantics remain Experimental. If a late listener is cheap, make its post-outcome edge harmless. If it must be cut, isolate the listener and Cut Control in a mod-owned fixture and test both arrival orders, simultaneous signals, reload with both armed, and re-entry.

Resource-specific cleanup rules

Scenes

A scene section’s normal/cancel socket, an scnEndNode, a public named exit, the quest wrapper’s Default INT/Default RET, and a quest CutDestination are different interfaces. None implies community deactivation or quest completion.

For a normal route, wait for the exact named scene output before advancing the outcome and releasing actors. For interruption, decide whether the scene may return, terminates into a named failure/cancel outcome, or remains unsupported. Active-line interruption and cut behavior in the current lab remain Experimental; do not silently route their unwired sockets into success.

See Cleanup and save state for the scene boundary matrix.

Actors, communities, AI, and workspots

questSpawnManagerNodeDefinition can carry an action whose questCommunityTemplate_NodeType requests Deactivate. Its outgoing graph edge proves command issuance, not immediate disappearance.

Observed in vanilla: mq003_homeless.questphase changes named community phases and deactivates actors later in its lifecycle. Keep deactivation after the scene or gameplay owner has released those actors.

Deactivate only after scenes, AI, workspots, combat, carry, and vehicle seats no longer need the actor. A timer alone is not a safe-release proof. Use a measured outer boundary or another authoritative state, and test dead, unconscious, missing, combat-active, streamed-out, and reloaded variants when the design supports them.

Keep a follower role active while the next activity still needs it. Clearing it early can return the actor to the community AI spot.

See Cleanup and character safety for actor-specific acceptance cases.

World markers, triggers, and streamed placements

Retire a quest mappin through its journal or Mappin Manager owner. A trigger is world geometry observed by a condition; completing the condition does not delete the trigger, and streaming it out does not cancel every graph listener that referenced it.

Placed world objects normally remain owned by their sector/prefab and stream according to that owner. Do not invent a generic despawn step for a trigger, marker, or prop. Instead, disable the player-facing state the quest activated, make remaining observers harmless, and test stream-away/return after every supported outcome.

Devices

Device cleanup is an authored final-state policy, not a universal reset. The device may need to preserve an open/unlocked/completed state, restore an evidence-matched state, disconnect a personal link, or remain under its native world owner.

Changing the archive does not clear device persistent state already retained by the save. Use a fresh identity or a save that never streamed it when testing package or controller changes. See Advanced devices, interactions, and persistent state.

Vehicles

Choose cleanup from the vehicle’s acquisition owner:

The cited sq031_porsche.questphase is an Observed in vanilla context for questEnablePlayerVehicle_NodeType, whose serialized payload includes a vehicle record string and enable, despawn, and makePlayerActiveVehicle. It is not a generic world-entity despawner.

Avoid intermediate vehicle cleanup while later stages still need a live vehicle. Give the final owner an explicit cleanup route targeting that vehicle.

Both observations are Runtime-proven only for their own archive and route. They do not prove the cause of the failure or a generic vehicle-cleanup recipe.

Journal, inventory, facts, and rewards

These writes are not visual cleanup; they are the durable meaning of the outcome. Order them deliberately:

1. record the branch outcome;
2. update the objective, description, or pin whose promise is now resolved;
3. run safe resource teardown;
4. return through the cleanup owner’s output;
5. write the terminal one-shot fact and quest state at the owning parent;
6. grant or remove inventory exactly once at its commitment boundary.

Failure and cancellation branches should not inherit success rewards or item removal merely because they converge on common cleanup.

Design cleanup as an idempotent protocol

Reload can resume between any two reachable graph writes. A cleanup protocol should therefore distinguish at least:

outcome_chosen
cleanup_started
cleanup_finished
activity_terminal

These may be explicit facts, journal states, or graph checkpoints rather than four literal fact names. The distinction matters more than the storage form.

Do not assume a cleanup command is idempotent. If a save can occur after the command was issued but before cleanup_finished, test whether reload repeats it, skips it, or restores the graph after it. A guard can prevent a second quest-side emission, but it cannot prove what the device, actor, scene, or vehicle already persisted.

An upgrade/removal path is a separate policy. A completion fact can prevent new activation, but it cannot erase an active scene, old controller state, community phase, vehicle instance, or journal state retained in a save.

Author and inspect the teardown in WolvenKit

1. Duplicate a mod-owned test project and assign a fresh candidate identity. Do not edit an installed lab or copy a complete vanilla phase.
2. Draw the owner ledger before editing the graph. Include every parallel listener, delay, scene, actor, AI/workspot, marker, device, vehicle, inventory write, journal entry, and fact.
3. Give success, failure, cancel, timeout, and interruption distinct incoming routes. Write their discriminator before shared cleanup.
4. For every independent listener, either gate all late writes on the chosen outcome or add a Cut Control only after the exact target behavior has an acceptance plan.
5. Wire scene normal and supported interruption outputs explicitly. Leave unsupported Default INT, Default RET, and CutDestination routes visibly unwired and label them Experimental.
6. Release AI, workspot, carry, and seat ownership before community deactivation. Use a measured safe boundary where visible disappearance matters.
7. Retire objectives and mappins according to each outcome. Do not let common cleanup overwrite a deliberate Failed, Succeeded, or resumable state.
8. Apply device and vehicle operations only to the exact controller/record and owner class for which the experiment has evidence.
9. End a cleanup child with a named output and connect the matching parent socket. Put the parent’s terminal write before its output and after the child handoff.
10. Save, close, reopen, and serialize every affected CR2W. Review concrete node types, socket classes, edges, NodeRefs, controller/record values, action arrays, output names, and the order of all durable writes.
11. Cook, pack and inspect the exact mod-owned payload. Keep the archive inventory with your test notes.

The existing labs demonstrate smaller ownership boundaries. Combining their shapes into a mixed scene/actor/device/vehicle teardown creates a new Experimental candidate; structural validity does not inherit runtime results from its parts.

Clean-save, interruption, and reload matrix

Begin positive identity/topology testing from an untouched save created before the candidate was ever installed. Clone complete save slots only while the game is closed. Bind every row to the same archive filename unless the row is an explicit upgrade/removal case.

If the game forbids saving at a boundary, record that limitation and test the nearest supported checkpoint. An unexercised row remains Experimental.

Failure routing

Previous: Completion and interruption. Next: Lab 4: Handoff Point.

Lab 4: Handoff Point

Lab 4 moves Boundary Check’s reach/leave activity into an external child questphase. The registered root starts the child, waits for its Out1 return, then performs a visible parent-only confirmation before completing the quest.

Structurally validated: both seven-resource checkpoints round-trip with WolvenKit 8.19.0. Follow the test guide for child entry, return, streaming, and save/reload.

Follow Author Handoff Point in WolvenKit to expand the start checkpoint. Then use Test Handoff Point to bind the candidate, saves, observations, and logs.

What the lab demonstrates

registered root -> completed == 0?
  False -> terminate
  True  -> activate quest and phase
        -> enter external child through In1
             activate reach objective and pin
             wait IsInside reach volume
             retire pin; succeed reach; activate leave
             wait IsOutside leave volume
             succeed leave; terminate child through Out1
        <- parent phase node emits Out1
        -> activate confirmation objective
        -> wait 30 realtime seconds
        -> succeed confirmation and phase
        -> set completed = 1
        -> succeed quest; terminate root

The CutDestination socket exists on the external phase node and other relevant nodes, but every cut socket is deliberately unwired. Lab 4 teaches a normal terminating Out1 handoff only; cut behavior remains Experimental.

Required environment

Other versions may expose different editor wrappers or runtime behavior.

Prerequisites and downloads

Complete Lab 3, then read:

• Registering a root questphase;

• Inputs and outputs;

• Calling child phases;

• Prefab dependencies;

• Completion and interruption.

• Download the start checkpoint. It has the complete seven-resource scaffold, a three-node root, and a two-node pass-through child.

• Download the completed checkpoint. It has the same resources, the exact 12-node root, and the exact 10-node child.

Do not install the two checkpoints together. They register and pack the same depot paths. Use an untouched save created before any Lab 4 candidate was first installed. Uninstalling an earlier candidate or setting cqa004_completed = 0 does not remove save-backed journal, phase, mappin, world, or graph state.

Resource ownership

The loose ArchiveXL file is packaging metadata, not an eighth CR2W resource. ArchiveXL registers the streaming block, not its sectors separately.

Registration and child resolution

The ArchiveXL file registers only the root phase:

quest:
  phases:
  - path: mod\cqa\cqa004\phases\cqa004.questphase
    parent: base\quest\cyberpunk2077.quest

journal:
- mod\cqa\cqa004\journal\cqa004.journal

localization:
  onscreens:
    en-us:
    - mod\cqa\cqa004\localization\en-us\onscreens\cqa004.json

streaming:
  blocks:
  - mod\cqa\cqa004\world\cqa004_handoff.streamingblock

Parent phase node 13 resolves the child through:

phaseGraph: null
phaseResource:
  DepotPath: mod\cqa\cqa004\phases\cqa004_boundary.questphase
  Flags: Soft
phaseInstancePrefabs: []
saveLock: 0
unfreezingTriggerNodeRef: 0

The child is packed but not independently ArchiveXL-registered. The supplied validator rejects a child registration entry.

Prefab and NodeRef contract

The registered root declares one local prefab root:

#cqa004_pr_handoff

The external child declares:

phasePrefabs: []

The world-side full root and nested references are:

$/mod/cqa/cqa004/#cqa004_pr_handoff
  #cqa004_tr_reach
  #cqa004_tr_leave
  #cqa004_mp_handoff

The child directly uses the two local trigger refs. Its empty prefab list is intentional: Lab 4 tests root-owned scope across the child boundary. The arrangement is Structurally validated here, Observed in vanilla in the cited street-story pair, and Runtime-proven in the retained four-child GQT003 fixture. Lab 4’s own runtime result remains Experimental.

World and journal scaffold

The world resources reuse Lab 3’s checked geometry under the cqa004 namespace:

The typed journal tree is:

quests/minor_quest/cqa004
└── cqa004_01
    ├── cqa004_01_obj_reach
    │   └── cqa004_01_qmp_handoff -> #cqa004_mp_handoff
    ├── cqa004_01_obj_leave
    └── cqa004_01_obj_confirm

The child owns the first two objectives and map pin. The parent owns the confirmation objective. The only FactsDB name is cqa004_completed.

Start checkpoint contract

The start root already teaches external resolution without the completed behavior:

Its two edges are 0.Out -> 13.In1 and 13.Out1 -> 1.In.

The start child contains [0] Input and [1] Output, connected by 0.Out -> 1.In. Output 1 is Terminating. This pass-through is a checkpoint for inspecting both interface layers; it is not the completed player activity.

Exact root phase

Root edge contract

Exact boundary child phase

Child edge contract

No root edge reaches a child node directly. No child edge reaches a parent node directly. Phase node 13 and the matching interface names are the handoff.

Common failure modes

Lab sequence: All labs · Previous topic: Complex cleanup, interruption, and cancellation · Next: Author Handoff Point in WolvenKit.

Author Handoff Point in WolvenKit

This walkthrough expands the supplied Lab 4 start checkpoint into the exact 12-node parent and 10-node child. The start project already contains every world, journal, localization, registration, and phase resource so the work can focus on the native composition boundary.

Required environment

Use an untouched save created before any Lab 4 candidate was installed for runtime testing. A manually edited _Start project is useful for learning and comparison, but only the unmodified completed checkpoint is the canonical acceptance candidate.

1. Open and isolate the checkpoint

1. Download and extract the start ZIP.
2. Open CQA_Lab04_HandoffPoint_Start.cpmodproj with File > Open Project.
3. Make an untouched backup of the extracted directory.
4. Confirm source\archive and source\raw each contain the seven depot resources listed in the overview.
5. Confirm CQA_Lab04_HandoffPoint_Start.archive.xl is under source\resources.
6. Do not install the start and completed checkpoints together.

The start parent is [0] Input -> [13] Phase -> [1] Output. The start child is [0] Input -> [1] Output. Both output nodes use socketName: Out1 and type: Terminating.

2. Audit registration before graph work

Open the ArchiveXL file and retain these four sections:

quest:
  phases:
  - path: mod\cqa\cqa004\phases\cqa004.questphase
    parent: base\quest\cyberpunk2077.quest

journal:
- mod\cqa\cqa004\journal\cqa004.journal

localization:
  onscreens:
    en-us:
    - mod\cqa\cqa004\localization\en-us\onscreens\cqa004.json

streaming:
  blocks:
  - mod\cqa\cqa004\world\cqa004_handoff.streamingblock

Do not add cqa004_boundary.questphase to quest.phases. It is an archived child resolved by the parent, not a second root. Do not add the two sectors to a guessed top-level registration list; the block descriptors reach them.

3. Audit all seven native resources

Before changing either graph, identify each supplied owner:

The checkpoint includes cooked resources for direct WolvenKit editing and raw CR2W-JSON for focused review. Do not edit the JSON as the tutorial workflow.

4. Audit journal and localization ownership

Open cqa004.journal and confirm this typed tree:

gameJournalRootFolderEntry
└── quests                         gameJournalPrimaryFolderEntry
    └── minor_quest                gameJournalFolderEntry
        └── cqa004                 gameJournalQuest
            └── cqa004_01          gameJournalQuestPhase
                ├── cqa004_01_obj_reach
                │   └── cqa004_01_qmp_handoff
                ├── cqa004_01_obj_leave
                └── cqa004_01_obj_confirm

The map pin’s reference is #cqa004_mp_handoff. Open the localization resource and confirm:

The child later changes reach, pin, and leave state. The parent later changes quest, phase, and confirmation state. Neither phase owns the strings.

5. Audit prefab scope and world resources

Open the root phase’s top-level phasePrefabs and retain exactly one questQuestPrefabEntry:

#cqa004_pr_handoff

Open the child and confirm phasePrefabs: []. Open parent phase node 13 and confirm phaseInstancePrefabs: []. Do not duplicate the root into either empty list.

The streaming block’s Quest descriptor uses full root:

$/mod/cqa/cqa004/#cqa004_pr_handoff

The two sector resources supply these full child refs:

$/mod/cqa/cqa004/#cqa004_pr_handoff/#cqa004_tr_reach
$/mod/cqa/cqa004/#cqa004_pr_handoff/#cqa004_tr_leave
$/mod/cqa/cqa004/#cqa004_pr_handoff/#cqa004_mp_handoff

The trigger geometry and marker placement intentionally match Lab 3. Confirm their values against the Lab 4 overview instead of changing location and phase ownership in the same experiment.

6. Audit the existing external phase node

Open cqa004.questphase, select node 13, and inspect its serialized properties:

Open the child and confirm input node 0 exposes socketName: In1, output node 1 exposes socketName: Out1, and output type is Terminating.

The figure shows both interface layers and the present-but-unwired CutDestination. Do not connect cut to the terminating output as a shortcut.

7. Add and number parent nodes

Keep parent nodes 0, 1, and 13. Add these nine nodes:

WolvenKit may assign lower automatic IDs. Renumber safely in two passes: move new nodes to temporary IDs 100–108, then move them to the targets. Never overwrite an ID still owned by another node. Save, close, reopen, and confirm the inventory before wiring.

8. Configure the parent guard and fact write

At parent ID 10, add questFactsDBCondition, then questVarComparison_ConditionType:

At parent ID 18, choose questSetVar_NodeType:

The exact write occurs only after child return and confirmation. Do not add a second fact to the child.

9. Configure parent journal operations

For parent Journal nodes, add questJournalQuestEntry_NodeType and a typed gameJournalPath. Keep these common values:

Incoming state sockets choose the requested journal state. The repeated path does not make the nodes redundant.

10. Configure the parent confirmation delay

At parent ID 15, add questTimeCondition, then questRealtimeDelay_ConditionType:

The 30-second realtime window makes the returned parent owner observable and provides a dedicated post-return reload case. It is not child cleanup.

11. Wire the exact parent graph

Right-click nodes and use Show Unused Sockets, then create these twelve ordinary edges:

The decisive handoff edge is 13.Out1 -> 14.Active. Leave every CutDestination unwired.

Save, close, reopen, then compare against the exact parent graph. Canvas position and handle IDs are not behavior.

12. Add and number child nodes

Open cqa004_boundary.questphase. Keep nodes 0 and 1, then add:

Use temporary IDs 100–107 before assigning final IDs. Save and reopen the child before adding connections.

13. Configure child journal operations

Use the same common journal values as the parent. Configure:

Child node 17 succeeds its local objective before the terminating output. It does not succeed the parent phase or root quest.

14. Configure child map-pin operations

Both Mappin Manager nodes use:

Node 11 receives Active; node 13 receives Inactive. They address the same journal map pin. This isolated lab has no deliberate prior route to replace.

15. Configure child trigger waits

At each Pause Condition, add questTriggerCondition:

Set isPlayerActivator: 1. Leave activatorRef as the ordinary empty gameEntityReference. These are state-shaped waits, not Entered/Exited transition events.

The refs are local to #cqa004_pr_handoff, which is declared by the parent root. Keep child phasePrefabs empty for this lab.

16. Wire the exact child graph

Use Show Unused Sockets, then create these nine ordinary edges:

Leave every CutDestination unwired. Save, close, reopen, and compare with the exact child graph.

17. Review the two resources together

Confirm all of the following before building:

1. parent node 13.In1 matches child input socketName: In1;
2. child output socketName: Out1 is terminating;
3. parent node 13.Out1 connects only to parent 14.Active;
4. phaseResource is soft and matches the archived child path exactly;
5. phaseGraph is null;
6. parent phase-node instance prefabs and child root prefabs are empty;
7. only the root declares #cqa004_pr_handoff;
8. no edge uses CutDestination;
9. the child is absent from ArchiveXL quest.phases.

The exact contract figure should now match the resources:

18. Validate, build, and install

With every tab saved:

1. run Project > Scan for broken file references;
2. run Project > Scan for broken files;
3. run Project > Run File Validation on the entire project;
4. resolve all project-owned errors;
5. close Cyberpunk 2077;
6. choose Build > Install and wait for packing and installation;
7. inspect WolvenKit’s Log panel and both installed files.

Use the normal ArchiveXL project install, not Install as REDmod. A packed archive without its loose .archive.xl cannot attach the root, merge the journal/localization, or register the world block.

The authored start project installs _Start-named files. To test the supplied completed project, open CQA_Lab04_HandoffPoint.cpmodproj, remove the start project’s installed files, and install the following pair:

archive\pc\mod\CQA_Lab04_HandoffPoint.archive
archive\pc\mod\CQA_Lab04_HandoffPoint.archive.xl

Common authoring failures

Lab sequence: All labs · Previous: Lab 4: Handoff Point · Next: Test Handoff Point.

Test Handoff Point

Lab 4 crosses root registration, external child resolution, root-owned prefab scope, world streaming, journal/mappin state, and two saveable phase owners. A final quest screenshot cannot identify which boundary worked. This protocol binds the installed candidate, clean-save lineage, visible handoff, and fresh logs across eight executions.

Use the unmodified completed checkpoint for these tests and record each result separately. The procedure covers the normal Out1 handoff; CutDestination remains unwired and is not tested by this lab.

Required environment

Record observed versions on every run. Values printed in the template are requirements, not proof of the machine that executed it.

Establish the site before installation

Lab 4 uses the same Allen Street test site and trigger geometry as Lab 3. Its center is the outdoor recycling-station cabinet row in Watson/Kabuki at:

(-1000.02, 1497.2208, 8.3)

Before installing any Lab 4 candidate, follow Lab 3’s ordinary control-route procedure. It cites the vanilla fast-travel entity, linked marker, exact depot resources, and extraction steps. Do not use Lab 4’s own marker as the only way to find a marker that is under test.

Treat access to the route and the new cqa004 world resources as Experimental until performed on the pinned game build. If the ordinary route is inaccessible, record that result. Do not silently substitute a console teleport.

Prepare clean starting save

Before installing either checkpoint:

1. choose a manual save made at Allen Street with no history of any Lab 4 candidate;
2. confirm the player is outside the 25-metre reach volume and can approach the cabinet row by the verified ordinary route;
3. copy the complete save-slot directory into your test folder;
4. record its in-game label and slot-directory name;
5. confirm that this save predates the first Lab 4 install;
6. preserve that original byte-for-byte for both clean-walk and clean-replay;
7. derive separate active-child saves before reach and between boundaries;
8. derive a separate parent-active save during the 30-second confirmation;
9. preserve the completed save used by both completed-state cases.

Use a fresh working copy for each run. Preserve the same source save for clean-walk/clean-replay, pre-reach-reload/stream-away-return, and completed-reload/completed-reinstall. Keep separate between-boundaries and parent-confirmation saves.

Do not obtain “clean” evidence by writing cqa004_completed = 0, removing the mod after a prior load, or reusing a slot that saw the start checkpoint. FactsDB, journal, phase, mappin, and world state can all survive those actions.

Build and bind the canonical candidate

Use the unmodified completed checkpoint:

candidate id: canonical
project:      CQA_Lab04_HandoffPoint.cpmodproj

1. Close the game.

2. Build and install through WolvenKit.

3. Confirm only this candidate’s pair is installed:

   archive\pc\mod\CQA_Lab04_HandoffPoint.archive
   archive\pc\mod\CQA_Lab04_HandoffPoint.archive.xl
   

4. Confirm the archive contains all seven depot resources, including the child and both sectors reached through the block.

5. Preserve those installed files until all eight executions finish.

Preflight the ownership boundary

Before Run 1, inspect the installed .archive.xl and record:

• exactly one quest.phases entry, for cqa004.questphase;
• no independent entry for cqa004_boundary.questphase;
• the journal, onscreen localization, and streaming block entries;
• no cqa004 error in a fresh ArchiveXL startup log.

This preflight does not prove the child executes. It proves the candidate under test has the intended one-root registration shape.

Run 1: clean walk

Restore a working copy of the original untouched save, keep the canonical candidate installed, and start a fresh execution.

Before entering the reach volume

Record all of these visible and state observations:

• Handoff Point, its phase, and Reach the handoff point. become active once;
• the handoff map pin becomes active once and points to the marker;
• the leave and confirmation objectives are not active;
• no second root or duplicate child activation appears.

The active reach objective and pin show child-owned work, but do not by themselves prove the prefab scope is correct. The trigger crossing and logs are also required.

Cross the reach boundary

Walk to the cabinet row and cross into the 25-metre reach volume. Confirm:

• the pin becomes inactive;
• the reach objective succeeds once;
• Clear the handoff area. becomes active once;
• the quest does not yet show the confirmation objective;
• the quest does not take its completed-save bypass.

Remain inside the 110-metre leave volume long enough to confirm the leave gate does not immediately complete.

Cross the leave boundary and observe return

Leave the 110-metre volume by ordinary movement. As soon as the leave objective succeeds, observe the child-to-parent boundary:

1. Wait for handoff confirmation. becomes active once;
2. the reach and leave sequence does not restart;
3. after 30 realtime seconds, confirmation and phase succeed;
4. the completion-fact write is reached before final quest success;
5. the quest succeeds once.

The confirmation objective is the visible evidence that child Out1 reached parent node 13.Out1 -> 14.Active. Preserve a derived save during this window for Run 4 and the final completed save for Runs 6 and 7.

Copy all four fresh logs before another execution can replace them.

Run 2: pre-reach reload

Restore the derived save made after the child activated but before reaching the 25-metre volume.

1. Load without changing the installed candidate.
2. Confirm the reach objective and pin return once.
3. Confirm leave and confirmation are not yet active.
4. Enter reach, remain inside leave, then walk outside.
5. Confirm the child returns once and the parent completes once.
6. Retain the save name, observations, and four fresh logs.

Pass requires coherent active-child restoration. Restarting the root flow or duplicating the pin is a failure even if the quest eventually completes.

Run 3: between-boundaries reload

Restore the derived save made after reach succeeded while the player remained inside the leave volume.

1. Confirm reach remains succeeded and the handoff pin remains inactive.
2. Confirm leave is active and confirmation is not active.
3. Wait briefly without crossing; the child must not return yet.
4. Walk outside the leave volume.
5. Confirm leave succeeds, confirmation activates once, and completion follows once.
6. Retain the save name, observations, and four fresh logs.

Immediate completion on load is a failure unless the retained position is actually outside the authoritative leave volume.

Run 4: post-return reload

Restore the derived save made after the child returned and while the parent’s 30-second confirmation delay was active.

1. Confirm the confirmation objective is active.
2. Confirm reach and leave do not reactivate and no pin returns.
3. Observe whether the realtime delay resumes or restarts; record the measured result rather than assuming one.
4. Confirm the parent succeeds confirmation, phase, fact, and quest once.
5. Retain the save name, timing observation, and four fresh logs.

Pass requires a coherent parent-owned continuation. The matrix records timing semantics; the procedure does not pre-label resume versus restart.

Run 5: stream away and return while child is active

Restore a working copy of the active-before-reach child save.

1. Travel by ordinary movement beyond the finite Quest descriptor box; do not use fast travel for this case.
2. Remain away long enough to collect a clear before/away/return observation.
3. Return by ordinary movement to the site.
4. Confirm the reach objective and pin remain coherent.
5. Cross reach and leave, then confirm one child return and one parent completion.
6. Retain route notes, save name, observations, and four fresh logs.

This case tests active composition across world streaming. It does not test CutDestination and does not generalize to every prefab lifetime.

Run 6: completed reload

Restore the completed save made by Run 1 with the unchanged canonical candidate installed.

Confirm:

• Handoff Point remains completed;
• reach, leave, pin, and confirmation do not reactivate;
• the external child is not invoked again;
• fresh logs contain no cqa004 error.

This is the completed-route bypass, not a second successful playthrough.

Run 7: completed reinstall

1. Close the game.
2. Remove only the two installed canonical files.
3. Reinstall the preserved copies of the same two files.
4. Load the same completed save.
5. Confirm the quest remains completed and the child does not restart.
6. Confirm ArchiveXL registers the root without a separate child entry.
7. Retain four fresh logs.

Do not rebuild between removal and reinstall. A changed archive is a new candidate and invalidates the shared record.

Run 8: clean replay

Restore a fresh working copy of the original untouched pre-install save while the canonical candidate remains installed.

Repeat the ordinary walk and record the full sequence:

root first-run route
  -> child reach/pin
  -> child leave
  -> child Out1
  -> parent confirmation
  -> parent completion

Every transition must occur once with the same installed files and no cqa004 errors. This verifies reproducibility from a second clean derivation; it does not erase the need for the six boundary-specific runs.

Retain four logs per execution

After each of the eight runs, copy these files into a run-specific private test folder before starting the next execution:

red4ext\plugins\ArchiveXL\ArchiveXL.log
red4ext\logs\red4ext.log
red4ext\logs\game.log
r6\logs\redscript_rCURRENT.log

Keep the copied logs with that run’s test notes. Search all four for cqa004, the child depot path, NodeRef errors, streaming errors, journal/localization errors, and framework failures. “No visible crash” is not an adequate log result.

Common test failures

Lab sequence: All labs · Previous: Author Handoff Point in WolvenKit · Next lab: Lab 5: First Contact.

Conditions and gates

A condition answers a question about game state. A gate decides when that question is asked and what execution signal leaves afterward. Keeping those jobs separate is the foundation of reliable quest control flow.

“Continue when the player has arrived” can mean at least three different things:

• sample the arrival state now and choose True or False;
• hold this execution path until the arrival state is fulfilled;
• combine arrival with other predicates before either of those graph nodes acts.

Those are different native resource shapes. A visually similar graph can therefore have different runtime behavior.

Three layers, three questions

Trace a gate from the outside in:

execution signal
      |
      v
graph node: evaluate now or wait?
      |
      v
condition object: which state is being tested?
      |
      v
leaf payloads and Boolean composition

Then trace outward again through named sockets. The three layers answer different questions:

Graph-level logical nodes are a fourth, separate concern: they receive execution signals through sockets. A questLogicalCondition does not merge graph edges, and a graph-level AND or XOR does not inspect facts by itself. Using the same English words for both layers is convenient, but the serialized types reveal which contract actually applies.

Choose the native shape from the behavior

The table is a design router, not a copy-paste recipe. Every row still needs an explicit entry edge, exit edge, lifecycle owner, and evidence plan.

Read this section in order

Start with the node schedule. A perfectly authored fact comparison still behaves incorrectly if it sits under the wrong surrounding graph node.

Inspect vanilla conditions

Use a disposable WolvenKit project for vanilla research:

1. In the Asset Browser, locate the exact depot path named by a chapter.
2. Open it without adding it to a distributable project, or add it only to a separate local inspection project.
3. Record the graph-local node ID, concrete node class, condition payload, socket names, and focused connected edges.
4. Record the game version, WolvenKit version, extraction date, and optionally a local hash.
5. Keep the extracted .questphase and any complete CR2W-JSON serialization out of the book and downloadable examples.

Use the depot path to locate a reference. Adapt only the fields you need; vanilla facts, NodeRefs, and journal paths belong to the original quest.

State is not an event sequence

Many predicates describe state: a fact has a value, a journal entry has a state, or an actor is inside an area. Even when a payload enum contains words such as Entered or Exited, the enum name alone does not establish its exact edge timing, persistence, or replay behavior.

Ordered behavior comes from explicit execution edges:

wait for A
  -> wait for B
  -> perform C

Putting A and B in one AND tree asks whether both predicates are fulfilled for one condition evaluation. It does not record that A happened first. Starting two waiters in parallel likewise does not establish which will emit first or whether the losing path will stop.

Test timing-dependent behavior

When your quest depends on timing, test pause, loading, time skip, fast travel, and save/load. For parallel signals, test both arrival orders and simultaneous arrival. For reusable waits, test interruption and re-entry.

Immediate branches and waiting gates

questConditionNodeDefinition and questPauseConditionNodeDefinition both own a condition handle. Their surrounding graph contracts are different:

immediate                         waiting

In                               In
 |                                |
 evaluate now                     hold this path
 +-- True  -> route A              |
 `-- False -> route B              `-- Out -> continue when fulfilled

Choosing between them is a behavior decision, not an editor-layout choice.

Vanilla references

These focused base-game resources are useful comparisons. Extract them from your own installation; they are references, not files to copy into the project.

base\open_world\street_stories\westbrook\japantown\sts_wbr_jpn_03\phase\sts_wbr_jpn_03_streetstory.questphase

Immediate condition: answer on entry

Execution entering questConditionNodeDefinition causes its predicate to select a route. The focused vanilla shape has:

The decisive property is the node class. When the predicate is false, the node follows False; it does not remain active hoping that the value will change.

A startup prerequisite can therefore reject or bypass work immediately:

In
 -> is prerequisite ready?
      True  -> begin activity
      False -> unavailable route or termination

If the design instead says “start whenever the prerequisite becomes ready,” this graph is incomplete. The False route needs some explicit retry owner, or the predicate belongs under a waiting node.

Pause condition: retain one execution path

questPauseConditionNodeDefinition receives an execution signal and delays that path until its predicate is fulfilled. Its focused observed shape has:

There is no ordinary False continuation in this shape. A false predicate means that this execution path has not yet produced Out.

That makes the node suitable for state gates such as:

• a fact reaching an authored value;
• the player satisfying a trigger predicate;
• a journal entry reaching a state;
• a real-time or game-time delay completing.

The nested payload defines fulfilled. Condition payloads shows the focused property shapes. A Boolean condition tree can combine several payloads beneath either surrounding node.

The same predicate does not mean the same behavior

Suppose signal_ready currently equals 0 and later becomes 1.

questConditionNodeDefinition(signal_ready == 1)

selects False when the signal arrives at that moment. It has already made its decision.

questPauseConditionNodeDefinition(signal_ready == 1)

owns a waiting path whose intended release condition is the later fulfilled comparison. Do not turn that explanation into unsupported scheduling claims: the retained structure alone does not say how often the engine revisits the predicate, what happens during a load screen, or whether a terminated phase cleans up an active waiter.

Author the node in WolvenKit

Use WolvenKit 8.19.0 and a mod-owned .questphase. The following procedure describes the native resource shape; it does not require a generator or a published vanilla asset.

1. Decide the behavior in plain language: branch now or wait until.
2. Add questConditionNodeDefinition for the first behavior, or questPauseConditionNodeDefinition for the second.
3. In the node’s condition handle, create the wrapper that owns the intended state domain. For a fact comparison, that is questFactsDBCondition with a questVarComparison_ConditionType beneath type.
4. Set every decisive payload property. Do not leave a default fact name, journal path, NodeRef, comparison, or threshold unexplained.
5. Show unused sockets if necessary. Connect In, then both True and False for an immediate branch, or connect In and Out for a waiting gate.
6. Leave CutDestination unwired unless the activity has a designed and tested interruption owner.
7. Save the resource, reopen it, and verify the concrete node class, payload handle, socket names, and connected destination IDs.

For a structural record, serialize and round-trip the mod-owned resource, then compare the focused node and edge set. A successful save is not runtime proof.

One-shot activation is an immediate branch

A one-shot side effect needs persistent control state and an already-done route:

In
 -> started == 0?
      True  -> set started = 1 -> perform one-shot side effect
      False -> bypass the side effect

Facts are signed integers, even when 0 and 1 are used by convention. The fact writer is a separate graph operation; the comparison does not change the fact.

The book’s mod-owned First Signal checkpoint uses cqa001_completed == 0 in this shape and is Structurally validated with WolvenKit 8.19.0. Its clean-save runtime evidence remains Experimental — pending.

Place the write according to the invariant you need. If started means “do not send the opening presentation twice,” write it before or immediately with that presentation. If completed means “the whole activity finished,” write it only on the completed route. When restart and completion differ, use separate facts instead of overloading one value.

Writing a start guard early can suppress a retry after interruption; writing it late can repeat the guarded side effect. That is a lifecycle trade-off to test, not an ordering rule hidden inside the condition node.

Re-entry safety is Experimental. Test repeated entry, save/load, and reinstallation over a completed save.

A waiting monitor is still active work

A graph output can start a normal activity and a pause condition in parallel:

start
  +-> main activity
  `-> wait for failure fact -> fail optional objective

This is a monitor-shaped topology. It does not imply that success on the main path cancels the listener. The vanilla street-story resource cited above contains a parallel stealth-failure listener and later reads the stored result, but contains no CutSource for that listener. That is Observed in vanilla evidence for the shape, not automatic cleanup.

For every waiting path, name:

• who starts it;
• which predicate releases it;
• what output consumes the release signal;
• whether another route can make it irrelevant;
• how it is explicitly cut, completed, or made harmless;
• which save/reload and re-entry cases must be exercised.

An unwired CutDestination does not answer those questions.

Save-backed facts change the first entry

A fact used by either condition node may already exist in the save. Installing a new archive does not guarantee its authored comparison begins at zero.

Test at least these distinct cases for a one-shot or waiting fact gate:

1. an untouched save made before the mod was installed;
2. a save while the waiter is active;
3. a save after the releasing fact changed;
4. a completed save after reinstalling the identical build;
5. a replay from the original untouched save.

Record the archive and loose-file hashes with the save identity and logs. A console fact edit is useful diagnosis, but it does not clear journal state, active graph state, or other save-backed dependencies and therefore is not a clean-save result.

Diagnose the schedule before the payload

When a gate takes the wrong route or never releases:

1. Confirm the concrete node class: immediate Condition versus Pause Condition.
2. Trace the edge into In and every expected outgoing socket by node ID.
3. Inspect the concrete payload and its comparison instead of relying on the node caption.
4. Check the fact, journal path, NodeRef, or timer fields for the test save and installed build.
5. Determine whether the path was started once, more than once, or never.
6. Check whether a competing route completed without stopping this waiter.
7. Repeat the first-entry route from the original untouched save before changing the resource again.

That order separates a scheduling mistake from a malformed predicate, stale save state, missing dependency, and unowned cleanup.

Condition payloads

The surrounding graph node decides when a condition matters. Its condition object decides what counts as fulfilled. In serialized form, many predicates have two payload layers:

quest condition node
└── condition                    domain wrapper
    └── type                     concrete comparison or event payload

For example, questFactsDBCondition owns a questVarComparison_ConditionType, while questTimeCondition owns a real-time or game-time delay type. Do not replace one wrapper while leaving an incompatible nested type handle behind.

Read Immediate branches and waiting gates before this chapter. Both graph-node classes carry the same base-condition handle, but a concrete payload still needs evidence for its intended use. The retained fact comparison appears beneath both schedules; the delay recipes below appear beneath Pause nodes.

Fact comparison

The focused shape is:

questFactsDBCondition
└── type                         questVarComparison_ConditionType
    ├── factName                 string (`CString` in WolvenKit's RED type)
    ├── value                    signed integer
    └── comparisonType           comparison enum

The comparison enum provides:

Facts are integers. Authors often use 0 and 1 as a Boolean convention, but the resource does not turn the fact into a Boolean type. These predicates can express counters and stage values as well:

signal_ready == 1
guards_remaining <= 0
quest_stage >= 3

Choose the comparator that states the invariant. Equal 1 and Greater 0 are not interchangeable when another system can write 2.

The same vanilla street-story phase uses jpn_03_stealth_fail == 1 beneath both a Pause node and an immediate Condition node:

base\open_world\street_stories\westbrook\japantown\sts_wbr_jpn_03\phase\sts_wbr_jpn_03_streetstory.questphase

That is Observed in vanilla evidence that the fact payload is reusable under both schedules. It is not evidence that a fact is automatically reset when either node completes.

Author a fact predicate

In a mod-owned node’s condition property:

1. Create a questFactsDBCondition handle.
2. Create questVarComparison_ConditionType beneath its type property.
3. Set the exact factName, signed integer value, and comparisonType.
4. Reopen the resource and verify both handles are non-null and retain their concrete classes.
5. Test from a save whose prior fact state is known.

NotEqual is payload-specific negation. It does not prove that a generic NOT condition exists. Boolean condition trees develops that boundary.

Trigger condition

questTriggerCondition carries its decisive fields directly:

An Observed in vanilla player gate appears at root Pause node 20 in:

base\quest\main_quests\part1\q108\phases\q108_06b_tower_mainframe.questphase

It uses type: IsInside, the #q108_tr_mainframe triggerAreaRef, and isPlayerActivator: 1. The same phase also contains a nested AND tree that names several non-player activators and requires them inside a trigger.

This predicate crosses into world ownership. #q108_tr_mainframe resolves because that quest’s streamed resources provide it. Reusing the text in a new quest does not create a trigger. A mod-owned condition needs a NodeRef that resolves to its own loaded trigger area at the time the gate is active.

Enum names such as Entered, Exited, IsInside, and IsOutside must not be used as proof of exact temporal behavior. The retained serialization does not establish whether a form is edge-triggered or state-recovering through load, streaming changes, teleportation, or activation while the player is already inside. Treat those cases as Experimental until tested.

Author a trigger predicate

1. Establish ownership of the mod’s trigger and its NodeRef before editing the questphase.
2. Create questTriggerCondition beneath the graph node’s condition handle.
3. Set triggerAreaRef and the intended type explicitly.
4. For the player form, set isPlayerActivator deliberately and inspect the resulting activatorRef; for another actor, begin from a separately verified actor-reference shape.
5. Test activation from outside, inside, after streaming transition, and after save/load before claiming state or event semantics.

IsOutside is another payload-specific way to express a negative predicate. It is not a universal logical NOT wrapper.

Distance comparison

A distance predicate separates the comparison from its two operands:

questDistanceCondition
└── type                         questDistanceComparison_ConditionType
    ├── distanceDefinition1      questObjectDistance handle
    ├── distanceDefinition2      questValueDistance handle
    └── comparisonType           comparison enum

Two focused operand types are:

Root Pause node 251 provides an Observed in vanilla object-versus-value example in:

base\quest\side_quests\sq031\phases\sq031_rogue.questphase

Its first operand resolves the local player and #emmerick; its second operand is distanceValue: 4; its comparison is LessOrEqual.

Call 4 a numeric distance threshold. The retained resource does not prove that the authored unit is exactly one metre, which reference points on the two entities are measured, or how streaming and teleportation affect evaluation.

Before authoring a new distance gate, state both operands in plain language:

distance(local player, contact NodeRef) <= threshold

Then verify the nested concrete types after saving. A null operand handle, wrong NodeRef, wrong local-player selector, or unintended numeric value changes the predicate even when the graph caption still says “distance.”

Journal predicates

Three similarly named nested payloads represent different questions:

Every path is a typed gameJournalPath, not only a slash-separated string. Its realPath, className, and fileEntryIndex must identify the supplied journal entry together.

An immediate state example is Condition node 195 in:

base\quest\side_quests\sq011\phases\sq011_concert.questphase

It checks whether a phone choice group is Active with questJournalEntryState_ConditionType. The typed path records the exact leaf class and file-entry index.

The retained corpus’s single visited payload appears beneath Pause node 127 in:

base\open_world\street_stories\heywood\vista_del_rey\sts_hey_rey_09\phases\sts_hey_rey_09_openworld.questphase

It addresses phone message contacts/8ug8ear/sts_hey_rey_09/warning4 with questJournalEntryVisited_ConditionType and visited: 1.

That one example does not make “journal visited” a generic signal for reading an inventory shard, computer page, email, or unrelated UI item. Use the entry family and event source that actually own the interaction.

Author a journal predicate

1. Identify the exact journal entry and the state dimension being tested: lifecycle, user state, or visited.
2. Create questJournalCondition, then choose the matching concrete nested type.
3. Populate the full typed path. Verify className against the leaf resource, not against the surrounding quest or folder.
4. Set state, visited, or inverted only where that concrete type owns the property.
5. Test from separate untouched, active, visited, and completed saves as the design requires.

The inverted field belongs to the entry-state payload. It is not a generic property available on every condition family.

Time conditions

questTimeCondition wraps a concrete time payload. Two common retained forms are:

The native real-time property is spelled miliseconds. Preserve that exact property name when reviewing serialized data; “correcting” it creates a different, unknown field rather than configuring the resource.

Focused Observed in vanilla examples include:

• a two-second real-time delay at nested Pause node 71 in base\open_world\street_stories\westbrook\japantown\sts_wbr_jpn_03\phase\sts_wbr_jpn_03_streetstory.questphase;
• a 23-hour game-time delay at node 146 in base\quest\side_quests\sq011\phases\sq011_concert.questphase;
• a three-day delay at node 61 and a five-hour delay at node 87 in base\quest\side_quests\sq011\phases\sq011_follow_up.questphase.

Tick-delay and time-period payloads are also Observed in vanilla. Inspect a matching use before adapting those less common forms.

A delay owns only its gate. The downstream graph owns the call, message, journal update, or other presentation that follows. A 23-hour condition in a vanilla contact flow does not mean the delay itself schedules phone UI.

Author and test a delay

1. For the delay recipes covered here, put questTimeCondition beneath questPauseConditionNodeDefinition. The retained immediate time condition uses a different questTimePeriod_ConditionType inside an AND tree; that snapshot time-window shape is outside this recipe.
2. Create questTimeCondition and the intended real-time or game-time nested type.
3. Set every time component explicitly, including zero-valued components.
4. Verify the exact concrete type and native property spelling after save and round-trip.
5. Record normal-play elapsed behavior separately from pause menu, time skip, fast travel, save/load, restart, and loading-screen cases.

The cited files establish resource shapes, not clock policy. Every behavior in step 5 is Experimental until the exact mod-owned build is exercised and the observation is retained.

Validate the payload before runtime

For any condition family, record this focused resource view:

A non-null handle and successful WolvenKit save are necessary structural checks. They do not prove that an external reference resolves, that save state starts clean, or that the runtime schedule matches the design.

Boolean condition trees

questLogicalCondition combines child condition objects into one predicate. It is embedded beneath an immediate or waiting graph node; it is not itself a graph node and has no execution sockets.

questPauseConditionNodeDefinition
└── condition                    questLogicalCondition
    ├── operation                AND
    └── conditions
        ├── questTriggerCondition
        └── questLogicalCondition
            ├── operation        OR
            └── conditions       ...

The surrounding node still decides the schedule:

• beneath questConditionNodeDefinition, the combined predicate chooses an immediate True or False route;
• beneath questPauseConditionNodeDefinition, the combined predicate defines when the waiting path may continue through Out.

Review Immediate branches and waiting gates and Condition payloads before constructing a nested tree.

Condition tree versus signal-flow topology

Two native layers use similar names:

This distinction prevents a common category error. A predicate AND can ask whether the player is inside an area and a fact is set. It cannot wait for two independent execution branches to arrive. Conversely, a graph-level join does not read those state predicates merely because its type name contains And.

When inspecting CR2W-JSON, ask where the object lives. An object under condition.Data.conditions is predicate composition. An object in the graph’s nodes collection with sockets and an id is signal topology.

A nested vanilla tree

Pause node 28 in this resource provides a compact Observed in vanilla example:

base\open_world\minor_activities\watson\northside\ma_wat_nid_15\ma_wat_nid_15_phase.questphase

Its focused predicate is:

AND(
  player IsInside #ma_wat_nid_15_tr_area_vision,
  OR(
    signpost_start > 0,
    signpost_combat > 0,
    signpost_ended > 0
  )
)

The outer AND owns two child handles: one trigger condition and one nested logical condition. The inner OR owns three fact conditions. Parentheses are therefore resource ownership, not visual decoration:

inside AND (start OR combat OR ended)

is not the same tree as:

(inside AND start) OR combat OR ended

Record nesting explicitly whenever prose uses both AND and OR.

AND: every child predicate

Use an AND tree when the authored predicate requires every child state together:

AND(
  prerequisite_fact > 0,
  player IsInside #activity_area
)

The surrounding graph node decides whether that combined truth is sampled now or waited upon. AND does not establish the order in which the two states became true. If the quest requires “first set the prerequisite, then enter the area,” encode that sequence with graph edges and separate gates.

The q108 tower-mainframe phase contains another Observed in vanilla AND tree requiring the player and three named actors inside a trigger:

base\quest\main_quests\part1\q108\phases\q108_06b_tower_mainframe.questphase

That structure shows heterogeneous activator references beneath one logical tree. It does not prove which child is inspected first, whether inspection short-circuits, or how actor streaming affects a new mod-owned version.

OR: any represented alternative

Use an OR tree to represent alternative leaf predicates within one condition:

OR(
  quest_stage == 2,
  quest_stage == 3,
  quest_completed > 0
)

OR does not report which child was responsible. The surrounding condition node produces only its own result socket. If downstream work needs to know the winning reason, preserve that information in separate immediate branches or in authored state rather than expecting the OR payload to emit a named case.

Do not rely on child-array order for priority. The retained structures support membership and nesting; they do not establish short-circuit order or side effects during evaluation.

XOR is a bounded observation, not a general recipe

The only retained logical-condition XOR is a four-child tree beneath Pause node 127 in:

base\open_world\street_stories\heywood\vista_del_rey\sts_hey_rey_09\phases\sts_hey_rey_09_openworld.questphase

Its children are two scan predicates, one journal-visited predicate, and one fact predicate. This is Observed in vanilla evidence that the serialized four-child shape exists. It is not enough to claim whether multi-child XOR means exactly one fulfilled child, parity, a first-changing child, or another runtime policy. It also says nothing about cancellation because a condition tree owns no graph listener sockets to cancel.

For a new quest, keep XOR Experimental until a focused truth-table test covers every relevant child combination, including more than one child fulfilled together and state restored from a save.

There is no generic NOT condition

The logical-operation enum in the inspected WolvenKit classes contains AND, OR, XOR, NAND, NOR, and NXOR. It does not contain NOT, and the retained corpus contains no standalone generic negation node.

Express negation only through a payload that owns a verified negative form:

For example:

AND(
  alarm_state != 1,
  player IsOutside #restricted_area
)

uses two independently supported leaf forms. It does not prove a hypothetical NOT(AND(...)) resource shape.

NAND, NOR, and NXOR should not be offered as substitutes merely because their enum values exist. With no retained vanilla instance and no focused runtime acceptance, their precise multi-child behavior remains Experimental.

Author a nested tree in WolvenKit

Use a mod-owned .questphase in WolvenKit 8.19.0:

1. Choose the surrounding immediate or pause node from the intended schedule.
2. Set that node’s condition handle to questLogicalCondition.
3. Set operation to the supported operation required by the design; begin with AND or OR.
4. Add one handle per child to conditions. Each child must contain a concrete condition wrapper such as questFactsDBCondition or questTriggerCondition.
5. To nest another group, store another questLogicalCondition as that child handle’s concrete object, set its operation, and populate its own conditions array.
6. Inspect every leaf’s decisive properties and every nested handle before leaving the property editor.
7. Save, reopen, and verify the tree shape independently of the graph layout.

For the observed MA_WAT_NID_15 shape, the review record should be small and deterministic:

Do not paste the complete vanilla resource into notes or a chapter. This focused tree plus the depot path is enough to reproduce the inspection.

Structural checks

A Boolean tree is Structurally validated only after the mod-owned resource passes checks such as:

• the surrounding node’s condition handle resolves;
• every item in conditions is a non-null handle with the intended concrete class;
• nested group boundaries and child counts survive CR2W round-trip;
• every fact name, comparison, typed journal path, and NodeRef is exact;
• the graph node retains the expected In and result sockets;
• no graph-level logical node was substituted for an embedded condition tree.

Structural validation still does not prove runtime timing. For a waiting tree, exercise child states becoming true in different orders, states already true on activation, save/load during the wait, and exit while it is active. For an immediate tree, exercise each result route and combinations where several children are true together. Until those cases are retained against the exact build, the behavior beyond the observed resource shape is Experimental.

Return to the Conditions and gates overview when deciding whether the next requirement belongs to predicate composition or execution-signal topology.

Signal flow: joins, races, hubs, and switches

Graph-level logical nodes combine execution signals. They are not the Boolean condition trees stored inside a Condition or Pause Condition node. Keeping those layers separate prevents one of the easiest questphase mistakes: treating a socket arrival as though it were a true value.

Use Boolean condition trees when several observations must be evaluated as one predicate. Use the nodes in this chapter when several already-running graph routes must meet, compete, or choose an output.

A connection is an edge

A graph node owns sockets. Each socket has a name, a socket type, and a connections array. A connection points weakly to its source and destination sockets.

CR2W-JSON often exposes the same connection handle from both endpoints. That does not create two edges. Count the connection object once, then resolve both socket handles.

The native socket kinds relevant here are:

Socket arity and connection count are different. One Out socket can hold several outgoing connections, and one In socket can be the destination of several edges. An ordinary node output can therefore fan out without a Hub.

What vanilla actually contains

The retained corpus has these graph-level nodes:

For all 193 retained AND, XOR, and Hub nodes, inputSocketCount and outputSocketCount match the serialized ordinary socket arity. Each also owns one CutDestination socket. The separate Switch is the table’s 194th node and is not included in that 193-node statement.

That inventory supports property and topology claims. It does not, by itself, prove what happens after the first output, after a save/reload, or when inputs arrive on the same frame.

AND: join-shaped convergence

questLogicalAndNodeDefinition carries:

Observed in vanilla: root node 38 in base\quest\main_quests\part1\q108\phases\q108_06b_tower_mainframe.questphase has four inputs and one output. A Pause Condition and three Move Puppet routes converge on its four inputs, and Out1 continues to another Pause Condition.

This is safely described as a four-way, join-shaped topology. Raw structure alone does not prove that the node remembers every earlier arrival, fires only once, resets, or restores partial arrivals after loading a save. If your design depends on those details, make each one an explicit acceptance case.

XOR: race-shaped convergence

Observed in vanilla: root XOR node 17 in base\open_world\street_stories\watson\northside_industrial_district\sts_wat_nid_03\phases\sts_wat_nid_03_gameplay.questphase receives three independent wait routes:

• security system is in combat;
• an enemy attacks the player;
• the security system is alerted.

Its single output continues to a fact setter. This is a strong example of race-shaped convergence.

It is not evidence that XOR cancels the two losing listeners. Those waits have no CutSource wiring in this phase. It also does not prove deterministic resolution for simultaneous arrivals or that a later arrival cannot emit again. Treat all three claims as Experimental.

Lab 2 uses a two-input XOR-shaped convergence because that exact resource can be structurally inspected and given a focused runtime matrix. See Lab 2: Signal Race.

Hub: a structural routing node

Do not teach Hub as “the fan-out node.” Vanilla uses it in several shapes:

• Observed in vanilla: root Hub 70 in the Q108 phase above has one input and three outputs.
• Observed in vanilla: root Hub 302 in base\open_world\minor_activities\watson\northside\ma_wat_nid_15\ma_wat_nid_15_phase.questphase has two inputs and one output. Its Out1 itself has two outgoing edges.
• In the same phase, Hub 195 is formally one-input/one-output, while two edges target that single In1 socket.

These resources prove split- and merge-shaped wiring. They do not establish whether each input is passed through independently, whether a multi-input Hub waits, whether one arrival broadcasts to all outputs, or which edge runs first. Use a Hub only after the behavior you need has its own runtime test. For a simple split, an ordinary output with several connections is the smaller structure.

Switch: conditions mapped to case sockets

questSwitchNodeDefinition owns a behaviour and a list of questConditionItem values. Each item combines a condition handle with a numeric socketId. The corresponding output is named Case<socketId>.

The sole Switch in the retained corpus is nested beneath phase node 252 in:

base\open_world\minor_activities\watson\northside\
ma_wat_nid_15\ma_wat_nid_15_phase.questphase

Observed in vanilla: it uses First_Fulfilled, three fact conditions, one case output for each recorded socket ID, and an unconnected Otherwise socket.

The retained file does not establish evaluation order, short-circuiting, continuous monitoring, exact Otherwise behavior, or the meaning of All_Fulfilled. Those behaviors remain Experimental.

Author safely in WolvenKit

1. Decide whether you are combining predicates or execution routes. If they are predicates, return to Boolean condition trees.
2. Add the graph node with the smallest required arity.
3. Set inputSocketCount and outputSocketCount before wiring it.
4. Confirm that the visible ordinary sockets match those counts.
5. Connect each producer to the intended named input and the continuation to the intended output.
6. Save, reopen, and inspect both endpoints of every edge. Do not count reciprocal handle references as separate connections.
7. Export a focused review JSON and verify node IDs, socket names, arity, and resolved endpoints.
8. Test every arrival order, then repeat the relevant cases across save/load and clean-save replay.

Node IDs are local to a phase graph. A nested phase graph can reuse an ID from its parent, so record the graph scope whenever you cite or audit a node.

Design checklist

Before shipping a join, race, Hub, or Switch, answer these questions with evidence rather than names:

• Which route starts each input producer?
• Can two producers finish together?
• What records the winner or completed prerequisites durably?
• Can a losing listener still write journal state later?
• What stops, cuts, or makes that late write harmless?
• What happens when saving with only some inputs satisfied?
• Can the containing phase be entered again?
• Does the completed-save route bypass every one-shot side effect?

Test any timing-dependent route in game, including both input orders and reload.

Delays, facts, and persistence boundaries

A delay in a questphase is a condition payload, normally held by a Pause Condition node. It gates the route that entered it; it does not schedule a complete quest action by itself. The nodes after the delay still own the journal update, fact write, scene start, or other effect.

This distinction matters when saves, time skips, and re-entry are involved. The serialized resource describes the delay and its wiring, while only runtime tests can establish how its active state survives interruption.

Pinned acceptance environment

Runtime test date: not yet recorded.

The book-owned Lab 2 CR2W resources are Structurally validated by cooking and serializing them back with WolvenKit 8.19.0. The other values pin the environment required by the future runtime acceptance run; they have not yet been exercised together for Lab 2. Timing and reload behavior therefore remain Experimental until the dedicated record passes.

Realtime delay payload

questTimeCondition wraps a concrete time condition. The realtime form is questRealtimeDelay_ConditionType:

Keep the spelling miliseconds in the native property tree. Correcting it to English creates the wrong field in raw representations.

Observed in vanilla: nested Pause Condition node 71 in base\open_world\street_stories\westbrook\japantown\sts_wbr_jpn_03\phase\sts_wbr_jpn_03_streetstory.questphase holds a two-second realtime delay.

Lab 2 uses 30- and 120-second realtime waits so the intermediate objective state is observable and a tester can make a mid-flow save. The WolvenKit round-trip proves their resource shape; it does not yet prove what the clock does in a pause menu, loading screen, or save/reload.

Game-time delay payload

questGameTimeDelay_ConditionType stores game-world duration fields:

Observed in vanilla: the following depot resources contain long game-time waits:

Those observations establish the payloads, not every clock rule. The contact, message, or scene seen after an SQ011 delay is downstream behavior and should not be attributed to the time condition itself.

Delay a follow-up offer after completion

To offer a second quest twelve game hours after the first completes, use two sequential waits before activating any message or reply choice:

Input
  -> Pause(completed fact > 0)
  -> Pause(game-time delay: 0 days, 12 hours, 0 minutes, 0 seconds)
  -> activate offer message
  -> activate reply choices

In WolvenKit, give the first Pause Condition a questFactsDBCondition wrapping questVarComparison_ConditionType: your completion fact, comparisonType = Greater, value = 0. Give the second a questTimeCondition wrapping questGameTimeDelay_ConditionType with the duration above. Connect the first Out to the second In, then the second Out to the message’s Active socket. Keep reply activation downstream too.

This graph expresses a wait that becomes active after the prerequisite passes. Starting both waits in parallel expresses a different timing requirement: the delay can become active while the prerequisite is still pending. An immediate Condition is also unsuitable if this running route needs to wait for a completion fact that is currently zero.

This follow-up pattern is Experimental until tested in game.

A completion prerequisite and a delay do not replace a separate already-sent guard. Preserve that guard when composing a one-shot offer. Nor can the new gate retract an offer already delivered by an older build: repeat from an untouched pre-install save. Test initial suppression, completion, elapsed game time, reload during the wait, and duplicate prevention separately.

Choose the clock deliberately

Use a realtime delay when the authored meaning is a short wall-clock beat such as debouncing a transition or allowing a presentation step to breathe. Use a game-time delay when the fiction depends on Night City time passing.

Do not choose solely by duration. A ten-second game-time wait and a ten-second realtime wait ask different runtime questions:

All answers in that table are Experimental until tested on the pinned build. Enum names and vanilla serialization do not settle them.

Facts are durable design state, not Boolean variables

questFactsDBCondition compares a named fact’s signed integer value. Facts are often used as zero/nonzero flags, but their native model is an integer:

cqa002_completed Equal 0
cqa002_test_mode Equal 2
cqa002_signal_failed Greater 0

The comparison operators represented in retained resources include Equal, NotEqual, Greater, GreaterOrEqual, Less, and LessOrEqual.

A fact can make a delayed route re-entry-safe only if the graph checks and writes it at the right boundaries. The fact’s persistence does not magically cancel an active listener or undo a side effect that already ran.

One-shot entry guard

Place a completed guard before the first player-facing or save-backed effect:

Input
  -> Condition(completed == 0)
       False -> terminating Output
       True  -> first-run route

Write the completion fact before, or in a tightly controlled sequence with, the final visible completion transition. Then make the False route terminate without reactivating journal entries, starting scenes, or spawning world content.

Use different facts when “started” and “completed” have different meanings. One fact cannot distinguish a partially completed run from a never-started run.

The labs supply a Structurally validated guard. Test re-entry and reinstallation using a completed save to check its one-shot behavior.

Clean-save rule

Facts, journal state, active quest nodes, scene state, communities, and device persistent state can all be save-backed. A save made after an earlier build was installed is not a clean first-run test, even when the archive has since been removed.

For every practical delay or one-shot test, retain:

1. one untouched save created before the candidate was first installed;
2. one save made while the delay or listener is active;
3. one save made after completion;
4. the exact installed archive and registration file;
5. exact game/mod versions and fresh logs;
6. observations and fresh logs for each run.

Never reuse the mid-flow or completed save as the clean replay baseline.

Minimum timer acceptance matrix

Record what happened; do not normalize a surprising result into the behavior you expected. See Lab 2 test protocol for the concrete two-route version of this matrix.

Test pause-menu, process-restart, time-skip, and fast-travel behavior separately when your quest depends on them. For parallel waits, also test simultaneous arrival and a late second input.

Parallel monitors and cancellation

A monitor is a graph route that begins alongside the main route and waits for an event that may or may not occur. Typical uses include optional-objective failure, combat escalation, leaving an area, a device state change, or a timer expiring.

The pattern is powerful because questphase outputs can have several connections. It is also dangerous: the route you stop caring about may still be alive unless the resource explicitly makes a later signal harmless or cuts the target.

Start independent routes

An ordinary Out socket can connect to more than one destination:

Activate optional objective
  Out -> wait for failure fact
      -> wait for stop condition
      -> continue main route

The three connections represent three independent downstream routes. A Hub is not required merely to express the split.

Observed in vanilla: a nested graph in base\open_world\street_stories\westbrook\japantown\sts_wbr_jpn_03\phase\sts_wbr_jpn_03_streetstory.questphase starts a main trigger wait and a stealth-objective branch from a shared journal output. The objective branch starts a Pause Condition for jpn_03_stealth_fail == 1; later, an immediate Condition reads the same stored fact. The phase contains no CutSource wiring.

That proves a parallel-listener topology. It does not prove automatic cleanup when the objective succeeds, cleanup on phase exit, save/load restoration, or one-shot emission.

Store the outcome before converging

When two branches can decide one objective, keep their journal writes mutually exclusive and record the result explicitly:

failure listener -> optional Failed -----------------> race input 1
stop listener    -> optional Succeeded -> success fact -> race input 2

Do not let both branches write success and failure facts after they converge. The convergence node is a routing boundary, not proof that the losing producer has been destroyed.

Lab 2 follows this rule. Each branch owns one optional-objective outcome, and the main completion route begins only after their XOR-shaped convergence. Its default and source-edited variants exercise different producers without installing two competing test writers in the same graph.

XOR is not a cancellation instruction

Vanilla contains race-shaped XOR convergence, including three independent alert/combat waits in:

base\open_world\street_stories\watson\northside_industrial_district\
sts_wat_nid_03\phases\sts_wat_nid_03_gameplay.questphase

Observed in vanilla: all three waits enter one questLogicalXorNodeDefinition, then its single output reaches a fact setter. There are no cut edges from that XOR to the waits.

Therefore the safe statement is “these routes converge through an XOR-typed node.” The following claims remain Experimental:

• first arrival is always the only emitted result;
• losing listeners are cancelled;
• simultaneous arrivals have deterministic priority;
• a later signal cannot retrigger the output;
• race state survives or resets predictably across save/load.

If correctness depends on any of those claims, test it directly and retain the evidence.

Explicit cut topology

questCutControlNodeDefinition owns ordinary In/Out sockets plus a CutSource. Selected targets expose CutDestination. Vanilla resources wire the cut source directly to those destinations.

Observed in vanilla: the retained corpus contains 50 Cut Control nodes and 75 CutSource→CutDestination edges; 45 target Pause Condition nodes.

A compact example appears in:

base\open_world\minor_activities\watson\northside\
ma_wat_nid_15\ma_wat_nid_15_phase.questphase

Pause node 225 is a character-killed listener. Cut Control node 236 has a cut edge to that listener’s CutDestination.

A larger cross-targeted bank appears in:

base\open_world\street_stories\watson\northside_industrial_district\
sts_wat_nid_02\phases\sts_wat_nid_02_ow.questphase

There, four Cut Controls cross-target four active Pause Conditions.

These shapes establish explicit target wiring, not the complete runtime contract. Raw data and generated class definitions do not prove whether a cut rolls back state, emits the target’s ordinary output, propagates downstream, persists in a save, permits later re-entry, or how permanent changes the operation. Treat those effects as Experimental.

Two safe strategies

Make a late signal harmless

Prefer this when the listener can remain active without cost:

1. Store the authoritative outcome in a fact.
2. Gate every journal or world-state writer on that outcome.
3. Make repeated or losing signals bypass the writer.
4. Terminate the containing route cleanly.
5. Test the late-signal case explicitly.

This strategy does not assert cancellation. It makes correctness independent of cancellation.

Cut a named target deliberately

Use this only when runtime acceptance has established the required cut behavior:

1. Identify the exact listener nodes whose lifecycle must end.
2. Connect a Cut Control’s CutSource to each target’s CutDestination.
3. Decide and record the intended permanent setting.
4. Test both outcomes, both arrival orders, and simultaneous completion.
5. Save with every target active, then reload and repeat.
6. Re-enter the containing phase and verify whether the target can arm again.

Do not copy a large vanilla cut bank as a template. Extract the relevant phase, trace the focused socket edges, and recreate only the topology your own test can defend.

Phase exit is not evidence of cleanup

A terminating output proves that a route reaches the phase interface. It does not, by itself, prove that every independent listener, delay, scene, or world operation started earlier has been cancelled.

Before allowing a phase to terminate, inventory its outstanding work:

Later chapters add the resource-specific lifecycle rules. At the graph level, the principle is already fixed: every parallel route needs an owner and an end condition.

Monitor acceptance matrix

For each monitor/race pair, retain at least:

Keep the installed build and starting save consistent while comparing results.

Retained vanilla condition catalog

This page is a discovery index for condition shapes found in a focused vanilla research set. It answers, “Which concrete type names should I search for?” It does not answer, “Which fields should I copy into a new quest?”

Every positive inventory claim on this page is Observed in vanilla. A type name and an occurrence count establish that a serialized shape exists; they do not establish its truth policy, listener timing, external-reference rules, save/load behavior, or suitability as a reusable recipe.

For the condition families already reduced to focused property descriptions, start with Condition payloads. For predicate composition, see Boolean condition trees.

Corpus and counting method

The retained corpus contains 41 .questphase serializations. All 41 headers report:

• game resource version 2310;
• WolvenKit 8.17.4;
• WolvenKit JSON version 0.0.9.

Counts include concrete $type definitions. Wrapper-to-payload counts use the concrete type beneath type.Data; operation and trigger enums are counted separately.

A HandleRefId reference does not create another object definition, so it is not counted again. Conversely, nested predicates are counted even when they sit beneath one logical tree. These are corpus occurrence counts, not the number of distinct behaviors, quests, or game-wide uses.

The recursive scan also encounters scnCheck...InterruptCondition and scnCheck...ReturnCondition objects in scene-related data. Those belong to scene interruption/return contracts, not the quest gate wrapper layer, and are reserved for the scene condition index rather than mixed into the tables here.

The surrounding graph contains 262 questConditionNodeDefinition objects and 797 questPauseConditionNodeDefinition objects. Those node counts describe evaluation schedules. They must not be added to the payload counts or treated as condition-family popularity rankings. The corpus also contains three questConditionItem objects used as switch containers; the container name alone does not define its case-selection policy.

Reader-facing inspection targets Cyberpunk 2077 2.31a and WolvenKit 8.19.0. Re-extract each cited depot resource from your own installation when the game or serializer changes.

Core state and composition families

The 259 retained fact comparisons use these serialized comparator values: Greater 138 times, Equal 55, GreaterOrEqual 55, Less 9, and NotEqual 2. Absence of another enum value from this sample is not evidence that the engine cannot represent it.

The 87 logical wrappers contain AND 72 times, OR 14 times, and XOR once. This is a predicate-object inventory, not evidence for short-circuit order or multi-child XOR truth policy. In particular, the corpus contains no generic NOT wrapper. Do not invent one from prose shorthand.

The time and journal wrappers resolve to these concrete payloads:

Do not infer clock policy from the four time class names. Do not treat the single visited payload as a universal “the player read something” signal. Each shape still needs its decisive fields, owner, and event source inspected in context.

Spatial families

The retained trigger field values are IsInside 153 times, IsOutside 56, and Entered 5. These strings are search keys, not proof that one form is state-recovering and another is edge-triggered across activation, streaming, teleportation, or save/load.

Every retained distance wrapper uses a questDistanceComparison_ConditionType. Its 55 comparisons are Greater 33 times, LessOrEqual 11, GreaterOrEqual 10, and Less once. The corpus also contains 55 questObjectDistance and 55 questValueDistance objects, but that symmetry does not establish the only legal operand pairing or a universal measurement unit.

Object, inventory, device, scan, and destruction families

All four payload types below appear beneath questObjectCondition in this corpus. The wrapper occurs 60 times, exactly matching the nested payload total.

This shared wrapper is a structural relationship, not evidence that the four payloads share fields or runtime contracts. Before using any one of them, inspect the referenced object identity, the concrete operation/state values, who produces the observed change, and whether the condition represents a state, a transition, or an engine event.

Character, combat, and workspot families

The corpus contains 250 questCharacterCondition wrappers. Their nested payloads account for all 250 definitions:

Condtion in the two class names above is the spelling present in the serialization; do not silently “correct” native names while searching. The table does not prove what counts as spawned, killed, mounted, in combat, in a workspot, or quickhacked. Actor reference form, community ownership, streaming/readiness, state transitions, and cleanup remain separate evidence questions.

Scene, content, phone, and system families

The editorial grouping reflects the concrete wrapper relationships found in the files. It does not mean that a scene condition owns scene playback, that a content condition grants a token, or that all system payloads share phone lifecycle rules. Locate the corresponding producer and manager nodes before assigning a behavior to any payload.

Vehicle and spawning families

These rare families are especially poor candidates for copy-by-name recipes. A vehicle predicate still depends on how the vehicle is identified, loaded, spawned, occupied, and cleaned up. A spawner-ready predicate still needs the spawner owner, activation order, failure path, and save/load behavior made explicit.

Representative depot paths

Use these paths to locate focused examples in your own game archives. They are not templates, and their quest-local facts, NodeRefs, actors, devices, scenes, and journal paths are not reusable identifiers.

Extract a named resource with WolvenKit, serialize it for local inspection, and preserve only a focused excerpt or your own notes. Do not redistribute the extracted CR2W or a complete vanilla serialization.

Before treating a condition as reusable

For a family that this book has not yet reduced to a practical guide, record all of the following before presenting an authoring contract:

1. The exact immediate or waiting graph node, its socket route, and the concrete condition wrapper stored in its handle.
2. The nested payload class and every decisive field, including native enum values and exact spellings rather than inferred labels.
3. Ownership and resolution for every external identifier: facts, typed journal paths, NodeRefs, entity or community references, TweakDB records, scenes, devices, vehicles, spawners, and workspots as applicable.
4. The producer of the observed state or event and the required activation order. A consumer condition does not create its source system.
5. A reduced, mod-owned fixture that survives WolvenKit 8.19.0 save/reopen and CR2W round-trip checks with non-null handles and stable concrete types.
6. In-game cases for already-true activation, normal transition, false or failure state, save/load while waiting, streaming loss and return where relevant, cancellation or phase exit, completion, and re-entry/reset.
7. Exact tested Cyberpunk, WolvenKit, RED4ext, ArchiveXL, and dependency versions, plus build hashes, logs, clean starting save, and the result of every acceptance case.

Treat a newly adapted condition as Experimental until the intended activation, completion, interruption, and reload behavior has been tested.

Lab 2: Signal Race

Lab 2 turns a single linear quest into two independently observable routes. It uses an immediate selector, two fact-listening Pause Conditions, two realtime Pause Conditions, a nested Boolean AND, and an XOR-typed convergence without relying on an untested cancellation claim.

Structurally validated: both checkpoints round-trip with WolvenKit 8.19.0. Follow the test guide for timing, parallel waits, re-entry, and reload.

Follow Author Signal Race in WolvenKit to build the graph from the start checkpoint. Use Test both Signal Race routes to keep the canonical and source-edited candidates, saves, and logs separate.

What the lab demonstrates

The canonical project sets cqa002_test_mode to 2 and takes the stable route:

entry -> completed guard -> test_mode = 2 -> activate quest/objectives
  -> immediate selector chooses False
  -> wait 120 realtime seconds -> signal_stop = 1
  -> waiting AND observes signal_stop > 0 AND test_mode == 2
  -> optional objective succeeds -> XOR-shaped convergence
  -> required objective succeeds -> completed = 1 -> quest succeeds

A controlled source edit changes only node 11 from exact value 2 to 1:

entry -> completed guard -> test_mode = 1 -> activate quest/objectives
  -> immediate selector chooses True
  -> wait 30 realtime seconds -> signal_failed = 1
  -> failure listener continues
  -> optional objective fails -> XOR-shaped convergence
  -> required objective succeeds -> completed = 1 -> quest succeeds

Only the selected writer delay starts in either candidate. The other monitor is still a lifecycle obligation, but its reserved fact has no writer in that variant. The lab therefore does not need to claim that XOR cancels a losing timer. Phase-exit cleanup and arbitrary external fact writes remain Experimental.

Prerequisites and downloads

Complete Lab 1 and read:

• Immediate and waiting conditions;
• Boolean condition trees;
• Signal-flow nodes;
• Parallel monitors and cancellation.

Use Cyberpunk 2077 2.31a, WolvenKit 8.19.0, ArchiveXL 1.27.0, RED4ext 1.30.0, and redscript 0.5.31.

• Download the start checkpoint. It has the journal, localization, registration, and a two-node terminating phase.
• Download the completed checkpoint. It has the exact 21-node graph and its review sources.

Do not install the two checkpoints together. They register the same depot paths. Use separate untouched pre-Lab-2 saves for the mode-2 and mode-1 runtime variants; all five tutorial facts and the journal lifecycle are save-backed.

Resource model

The start checkpoint supplies the same journal and localization content as the completed checkpoint. Its questphase has only Input 0, terminating Output 1, and one ordinary edge. This makes it an executable authoring baseline, not an empty folder or a hidden generator input.

Journal and localization contract

quests
└── minor_quest
    └── cqa002                              gameJournalQuest
        └── cqa002_01                       gameJournalQuestPhase
            ├── cqa002_01_obj_wait          required objective
            └── cqa002_01_obj_stable        optional objective

The stable journal objective has optional: 1. The corresponding questphase journal-node payloads retain their normal type.optional: 0; do not copy the journal entry’s optional flag into that unrelated node field. Every typed path uses fileEntryIndex: 2 because cqa002 is the containing gameJournalQuest at path component two.

Exact questphase

The completed graph has 21 nodes and 22 edges. Compare its IDs, socket names, and connections with your WolvenKit graph.

Every supplied node has one job; no node is a magic template. In particular, ID 16 owns a Boolean condition tree, while ID 25 combines graph signals. They use similar logical vocabulary at different resource layers.

Exact edge contract