Documentation proposal: end-to-end questphase and scene authoring guides

[hlky]

Summary

cc @manavortex

The current quest documentation provides useful introductions to inspecting quest files, using the WolvenKit Quest Editor, and implementing individual features. However, there still seems to be room for an end-to-end guide covering how a new quest flow and dialogue scene fit together.

While developing a custom quest mod, we have accumulated practical, runtime-tested knowledge that could form the basis of new documentation for:

• authoring and registering .questphase resources;
• creating custom .scene resources;
• coordinating questphase, scene, journal, localization, world, and character resources;
• diagnosing structurally valid resources that nevertheless fail or behave incorrectly at runtime.

We would be interested in turning this work into one or more contributions to the documentation.

Proposed questphase guide

A questphase guide could follow a small playable quest from registration through completion, covering:

• registering a root questphase under base\quest\cyberpunk2077.quest with ArchiveXL;
• dividing a quest into root and child phases;
• input/output sockets and child-phase handoff;
• facts, conditions, branching, and completion states;
• journal objectives, descriptions, contacts, messages, and map pins;
• resolving journal paths and their fileEntryIndex values;
• trigger conditions and NodeRefs;
• activating communities and waiting for CharacterSpawned;
• starting a scene and handling its named exit sockets;
• ownership boundaries between the questphase and scene;
• validating graph connections and CR2W handle ordering;
• converting between packed CR2W resources and editable CR2W-JSON with WolvenKit.

A particularly useful topic would be lifecycle ordering. For example, our working flow activates the community, waits for the character to spawn, waits for a broad setup trigger, and only then starts the scene. The running scene handles the closer interaction gates. Getting this ownership or ordering wrong can produce failures that are difficult to distinguish from malformed scene data.

Proposed scene guide

A companion scene guide could cover:

• the high-level structure of a .scene;
• actors, performers, screenplay items, graph nodes, sections, and events;
• spoken dialogue sections and player choice nodes;
• padding and connecting choice nodes correctly;
• scene-local quest nodes and trigger conditions;
• declaring and reaching multiple scene exits;
• connecting scene exits back to questphase sockets;
• subtitle, VO-map, and embedded choice-localization responsibilities;
• resource references, animation sets, and lipsync slots;
• stable IDs and the different ID domains found in scenes;
• using vanilla scenes as structural references;
• serialization round trips and runtime validation.

We also encountered several non-obvious details that may be worth documenting explicitly:

• Scene event and localization-variant IDs need to retain their full unsigned 64-bit values. Masking them to 63 bits produced a runtime crash in our testing.
• Choice text is stored in the scene’s embedded localization store rather than in the subtitle or VO maps.
• Merely including the required localization variants is not sufficient. Descriptor ordering can affect runtime choice lookup; our tested resources required each locale block to be sorted numerically by localization string ID.
• WolvenKit serialization can preserve a structurally incorrect lookup order, so a successful serialize/deserialize round trip is necessary but not sufficient validation.
• Lipsync slot cardinality must agree with the scene’s distinct lipsync resource references. A mismatch caused scene initialization crashes in our test case.
• Starting a scene before its community and actor are ready can lead to difficult runtime failures.

Some of these findings are based on comparison with vanilla resources plus controlled in-game testing. We would clearly distinguish confirmed invariants from observations that may be specific to a particular scene structure or current tool/game version.

Possible tooling section

We have also built small tools that may be useful as examples or companion resources:

• focused explorers for .questphase, .scene, .journal, localization, entity/appearance, and world CR2W-JSON;
• Graphviz/DOT output for questphase and scene graphs;
• a compact JSON scene specification and deterministic scene generator;
• validation of handles, graph edges, resource references, IDs, localization ordering, and checked-in generated output;
• regression tests around known runtime-sensitive structures.

The guides would not need to prescribe code generation. The tools could instead demonstrate how to inspect large resources without manually searching raw JSON and how to add repeatable validation around WolvenKit workflows.

Character creation tooling

A separate guide or follow-up proposal could document the character pipeline developed alongside the quest:

• manifest-driven NPC generation;
• .ent and .app structure and their relationship;
• TweakXL character and faction records;
• assembling head, body, hair, clothing, and appearance resources;
• selecting compatible assets from installed game archives;
• extracting actual mesh appearance names;
• previewing morph-target heads in a local WebGL interface;
• applying facial shape selections in Blender;
• exporting GLB resources and rebuilding CR2W meshes with WolvenKit;
• validating generated resources against a known template;
• common packaging risks, especially accidental global base\... overrides.

This material is less mature than the core quest/scene work, so it may be better presented separately or initially as an advanced/tooling-oriented guide.

Suggested deliverables

Depending on the preferred documentation structure, this could become:

1. Creating a minimal custom questphase
2. Creating a custom dialogue scene
3. Connecting questphase, scene, journal, localization, and world resources
4. Debugging and validating custom quests and scenes
5. Advanced: a manifest-driven custom NPC pipeline

Each guide could use a minimal example rather than the full production quest, with diagrams, focused CR2W-JSON excerpts, WolvenKit screenshots, and explicit notes about what has been verified in game.

Would maintainers be interested in contributions along these lines? If so, guidance on the preferred scope, page structure, and whether the questphase and scene material should be one tutorial or separate guides would be appreciated.

About Ghostline

Ghostline is an open-source Cyberpunk 2077 quest-mod project.

Its broader goal is to develop a complete, reproducible workflow for creating original quests rather than modifying only isolated pieces of existing content. The first playable slice, gq000, follows the player from an initial message exchange through meeting a custom character named Patch, accepting a job, and transitioning to the next objective.

The project currently brings together:

• root and child questphases;
• custom dialogue scenes with choices and multiple exits;
• journal entries, objectives, contacts, messages, and map pins;
• world triggers, community spawning, AI spots, and scene markers;
• subtitles, voiceover maps, generated VO, and embedded choice localization;
• a custom NPC assembled from .ent, .app, mesh, texture, morphtarget, and TweakXL resources;
• deterministic generators, focused CR2W-JSON explorers, validators, and regression tests;
• documented runtime investigations into scene initialization, localization lookup, NodeRef resolution, and quest/scene lifecycle ordering.

The repository is both a quest mod and a research project: discoveries are checked against vanilla resources, encoded into tooling and tests where possible, and then validated in game. This provides a reasonably substantial worked example from which smaller documentation samples could be extracted.

Character creator preview

The project also includes a local, manifest-driven character creator. It can preview the real morph-target head, search an index built from installed-game assets, uncook selected meshes for browser preview, assign supported appearances, and drive an isolated Blender/WolvenKit build pipeline.

msedge_rTfl1s77gj.mp4

[manavortex]

we love us some documentation :) The tool's approach looks awesome, how do you feel about integrating it in WKit once you're done fucking around and reached the finding out phase?

[manavortex]

edited comment for clarity, was referring to FAFO and not trying to be mean, sorry :D

[hlky]

No worries I understood the intent :) WKit integration would cool, are you thinking more the character tooling, or the manifest driven questphase/scene/world creation?

The current character tooling is web based (well it uses WKit under the hood for some aspects) which does have the advantage of AI being able to easily control it. To demonstrate the end to end usage, here's a character designed by AI using the tooling then shipped in game.

And to expand a little on the overall goal of the Ghostline project:

My vision is that AI (or human) can generate the manifests that define the dialog, scene and world, characters and audio can be generated, I used qwen3-tts so far as it has both voice design (for new characters) and voice cloning (for V or other vanilla characters), and eventually there will be like "templates" for different parts of quests that can be fit together like building blocks, so one template would be like "meet a contact", another might be "hack a terminal" or "kill these enemies", and I would like to have a sort of database of in-game locations that the AI can choose itself to fit the theme of the quest, so the database would have descriptions, tags, etc. like "kabuki, alleyway".

[manavortex]

Hey,
I think that adding agent support to WKit isn't really feasible, but adding compatiblity for those building blocks you generate sounds worthwhile? :)
The 3d stuff is handled by the Blender addon (the current 3d implementation sucks a lot ':))

[hlky]

Sure sounds good, and for the guides, what would you like to see in those?

[manavortex]

Probably the same way as the existing wiki guides - assume somebody has never used the tool (and also doesn't have accounts with anything), and walk them through the steps of using it? You could also host that documentation on your own github so that you don't have to wait for anyone to approve your pull requests, and we can put a link into the menu, same way it is for Audioware.

[hlky]

Yeah hosting the docs myself would probably work best, I'll keep you updated on the progress, I'm currently working on more "building blocks": reach_area, interact_device, acquire_item, combat_encounter, leave_area, read_shard, investigate_clues, optional_condition, choice_gate, escort_npc, carry_npc, deliver_vehicle

The demo quest follows this sequence, phone offer -> meet Patch -> hack relay -> meet Iris -> deliver cache, here's a playthrough video: https://www.youtube.com/watch?v=VnujnKM-Kmo

[manavortex]

Heh, that's pretty cool :)

[hlky]

Quick progress update: I took the suggestion to host the documentation separately and created:

• Documentation: https://hlky.github.io/cyberpunk-quest-authoring/
• Repository: https://github.com/hlky/cyberpunk-quest-authoring

The repository currently contains the book structure, writing and diagram standards, and a detailed implementation plan. The substantive tutorials and example projects are the next stage, so there is no need to add it to the documentation menu yet.

One important scope decision: this will document native Cyberpunk quest and scene authoring from first principles, rather than being documentation for Ghostline’s generators. Ghostline’s tools, vanilla references, tests, and runtime discoveries will provide research and validation, but readers will not need Ghostline or its manifest system to follow the guides.

Existing building blocks

Ghostline now supports 29 typed quest building blocks:

• Communication and contacts: phone_job_offer, phone_conversation, meet_contact
• World and devices: reach_area, interact_device, hack_access_point, read_terminal_document, leave_area
• Items, investigation, and delivery: acquire_item, read_shard, investigate_clues, plant_item, deliver_drop_point
• Combat, conditions, and flow control: combat_encounter, stealth_monitor, optional_condition, choice_gate, time_gate, defend_target
• NPC activities: escort_npc, carry_npc, release_or_rescue_npc
• Vehicles: enter_vehicle, ride_with_contact, drive_to, steal_vehicle, deliver_vehicle, vehicle_cleanup
• Specialized scenes: braindance_analysis

These are reusable typed contracts rather than arbitrary graph fragments. Simpler activities compile directly into questphase topology; more complex activities use reduced, validated templates.

Most are now instantiated in full quests or dedicated test manifests, although the strength of the evidence varies. Some are runtime-proven, some have structurally equivalent runtime coverage, and some have only passed generation and WolvenKit round-trip validation so far. The documentation will label those evidence levels explicitly.

The main remaining focused tests are:

• carry_npc, which still lacks a clear Ghostline runtime equivalent;
• deliver_vehicle, specifically its stopped-vehicle requirement;
• standalone uses of acquire_item and optional_condition, whose underlying mechanics are already exercised elsewhere; and
• full in-game acceptance of braindance_analysis.

The current contracts are documented here:

https://github.com/hlky/Ghostline/blob/main/tools/quest_spec.md

Braindance authoring

The most unusual recent development is an original braindance authoring pipeline.

As far as we are currently aware, there is no existing public workflow that takes newly authored Blender performances and cameras all the way into a custom rewindable Cyberpunk .scenerid, .scene, and questphase stack. I would be interested to hear if anyone knows of prior work in this area.

The original obstacle was .scenerid. WolvenKit could inspect and rebuild the resource, but the normal Blender animation workflow targets .anims; it did not provide a route for authoring synchronized rewindable actor and recording-camera data.

The current Ghostline pipeline can now:

• define a braindance performance using JSON;
• generate an inspectable Blender scene with a relocatable origin, environment proxies, actors, cameras, timeline markers, and clues;
• import compatible body, facial, and cyberware rigs;
• support manual Blender editing followed by a nondestructive bake;
• sample evaluated actor and camera animation frame by frame;
• encode new RED compressed body, facial, cyberware, and camera animation buffers;
• encode camera position, rotation, focal length, trajectory, and RED camera tracks;
• build a genuine .scenerid with deterministic tags, serials, timing, and actor placement;
• link the RID events into a rewindable .scene;
• author visual, audio, and thermal clue timing;
• connect the scene to a questphase with separate success, interruption, and cleanup paths;
• serialize and round-trip the RID, scene, and questphase through WolvenKit;
• stage the complete resource set at safe production depot paths with hash-bound audit manifests.

Most importantly, the current RID no longer reuses vanilla motion data. The actor poses, root motion, camera movement, and lens data are encoded from evaluated Blender animation. Vanilla RID resources are used only as compatible structural layouts for rig cardinality and resource shape; their animation bytes are discarded.

The concrete gqt005_braindance_analysis candidate is a twelve-second, two-actor recording with a custom recording camera and visual, audio, and thermal clues. It now has:

• an authored .scenerid;
• a reduced rewindable .scene;
• a typed braindance_analysis child phase;
• performer community lifecycle;
• journal and localization resources;
• world markers and supporting sectors;
• normal-end and interruption cleanup branches; and
• a packaged test quest.

The tooling, CR2W generation, curve audits, and WolvenKit round trips are complete. The remaining step is interactive in-game acceptance covering:

1. Forward seeking
2. Backward rewinding
3. Visual-layer clues
4. Audio-layer clues
5. Thermal-layer clues
6. Normal exit and cleanup
7. Mid-session interruption and cleanup
8. Replay without stale state

Until those cases pass, the documentation will describe the pipeline as structurally validated and packaged, not runtime-proven.

The implementation and current workflow are available here:

• https://github.com/hlky/Ghostline/blob/main/docs/braindance-authoring.md
• https://github.com/hlky/Ghostline/blob/main/tools/braindance_scene.py
• https://github.com/hlky/Ghostline/blob/main/tools/braindance_rid.py
• https://github.com/hlky/Ghostline/blob/main/tools/braindance_pipeline.py

The documentation project will eventually explain both the overall vanilla braindance resource stack and the lower-level .scenerid discoveries. A simpler non-interactive play_braindance block is also a possible companion to the current rewindable braindance_analysis block.

Planned building blocks

The strongest additional candidates identified from the local vanilla quest corpus are:

• conversation_scene — run a scene and handle named exits without assuming meet_contact’s spawning and approach lifecycle
• call_contact / holocall — native voiced-call lifecycle rather than text-message conversations
• wait_for_condition — wait for an actor, message, fact, objective, or world state
• use_workspot — sitting, leaning, operating equipment, and related objectives
• destroy_target — destruction conditions and configurable thresholds
• give_reward — expose rewards as a reusable stage
• stash_npc_in_vehicle — extend carrying with vehicle-trunk placement
• spawn_encounter_wave — ordered reinforcement waves
• vehicle_chase / vehicle_race — moving opposition, splines, and race/chase parameters
• toggle_door — force-open, close, lock, and unlock flows
• switch_gate — general n-way branching beyond the two-outcome choice_gate
• play_braindance — cinematic BD playback without analysis controls

Lower-priority, more asset-dependent candidates include purchase_item, equip_disguise, elevator_transit, and escape_pursuit.

“Gates” will be treated as a major documentation subject rather than a single block. That includes activating or advancing quests after combinations of facts, elapsed time, proximity, interactions, inventory state, actor state, world state, and logical AND/OR conditions. It will also distinguish checking a condition once from suspending the graph until a condition becomes true.

Documentation plan

The initial tutorial sequence is planned as:

1. A minimal one-shot questphase
2. Activating quests using facts, time, proximity, interactions, and compound gates
3. A world objective with triggers and NodeRefs
4. Root and child questphases with explicit lifecycle ownership
5. Starting a dialogue scene and handling its exit sockets

Each practical guide should include a small downloadable WolvenKit project. Graphs will primarily be explained through deterministic SVG/Mermaid-style node diagrams and focused tables rather than raw WolvenKit graph screenshots.

Potential WolvenKit compatibility for Ghostline-generated building blocks can remain a separate integration discussion. The documentation project will explain their underlying native structures independently of the generator.

I’ll post another update once the first complete tutorial and example project are ready, at which point a menu link would make sense. Feedback on the structure, proposed building blocks, or any prior custom braindance-authoring work is very welcome.

[manavortex]

Hey,
that's pretty cool, and I love that you're moving fast! This sounds like it'll give people amazing options to play with, can't wait to see what they'll come up with (sex. it will be sex)