Scenes
A native scene is not a self-contained quest. It owns performers, screenplay items, timed events, scene-graph flow, entry points, and named exits. Other resources must make its actors available, start it, consume its outcome, and clean up durable world and quest state.
world/community .scene .questphase
activate + spawn actor -> acquire + perform + named exit -> outcome + cleanup
| |
| +-> embedded choice locStore
v
subtitle map/entries + VO map/WEM
That ownership boundary is the central rule of this section:
| Owner | Responsibility in the First Contact example |
|---|---|
| Streaming sector and community | Register #cqa005_com_contact, materialize the contact, and provide the scene marker #cqa005_sm_contact |
.scene / scnSceneResource | Acquire actor 0 and V as actor 1, play one timed line, run a small PuppetAI branch, and expose contact_done |
.questphase / questSceneNodeDefinition | Resolve the soft scene path at the marker, enter through start, and receive contact_done |
| Journal and facts | Advance the meet/leave presentation after the scene returns, then record terminal completion after child cleanup |
| ArchiveXL localization | Merge the external subtitle and voiceover resources used by the spoken-line RUID |
| Save | Retain active quest, journal, fact, checkpoint, community, and scene state independently of a later archive edit |
Reading route
Read these pages in order:
- Scene resource anatomy — the v5 root, typed empty stores, resource references, debug data, and interruption scaffold.
- Actors and performers — community acquisition, player context lookup, performer symbols, actor behavior, and lipsync slot cardinality.
- Screenplay, sections, and events — the separate line, event, section, duration, and ID domains.
- Entry, exit, and quest handoff — the exact
four-node topology and the
questSceneNodeDefinitioninterface. - Author one spoken line — a bounded WolvenKit procedure
for
All clear. Keep moving.and its external subtitle/VO join. - Cleanup and save state — interruption versus completion, named-outcome handling, community teardown, and clean-save acceptance.
- Choices, outcomes, and scene-local localization — native choice items, padded socket observations, embedded locStore joins, and multi-exit quest handoff.
- External VO, WEM, and lipsync — the parallel subtitle, audio, and actor-slot chains plus cardinality-first diagnosis.
- Animation events and scene workspots — animation-set visibility, timed cinematic events, scene workspot identity, and cleanup boundaries.
- Lab 5: First Contact — the complete resource inventory, ownership model, exact graphs, and evidence boundary.
- Author First Contact in WolvenKit — the field-level construction and round-trip procedure.
- Test First Contact — clean-save playback, reload, streaming, handoff, and cleanup checks.
First Contact uses one spoken line, an empty embedded locStore, and no
cinematic-animation or scene-workspot payload. Continue to the advanced pages
when adding choices, animation, or workspots.
Vanilla references
Use WolvenKit to extract these resources from your own installed archives and inspect only the fields needed for comparison:
base\quest\minor_quests\mq003\scenes\mq003_01_homeless.scenebase\quest\minor_quests\mq003\scenes\mq003_03_orbital_pod.scenebase\quest\minor_quests\mq007\scenes\mq007_01_gun_found.scenebase\quest\minor_quests\mq010\scenes\mq010_02_barry_talk.scenebase\animations\quest\minor_quests\mq007\anim\body\mq007__talking_gun__male_fpp.animsbase\workspots\common\wall\generic__stand_wall_lean_left__stand_around__01.workspotbase\localization\en-us\lipsync\base\quest\minor_quests\mq007\scenes\mq007_01_gun_found\skippy.animsbase\localization\en-us\lipsync\base\quest\minor_quests\mq007\scenes\mq007_01_gun_found\v.anims
These paths are citations, not redistributable examples. Do not publish the extracted CR2W files or complete serialized exports. Record focused types, properties, IDs, and edges instead; the workflow is described in Inspect a vanilla questphase.
First-pass failure routing
| Symptom | Inspect first |
|---|---|
| Scene never begins | Community Activate, CharacterSpawned, world marker resolution, phase prefab scope, soft scene path, and start socket |
| Crash or failure during scene startup | Actor acquisition, readiness, lipsync ID-to-array cardinality, and missing referenced resources |
| Subtitle is absent | Scene line RUID, registered subtitle map, its subtitle-entry reference, and matching stringId |
| Subtitle works but audio is silent | VO-map registration, matching stringId, both gender paths, WEM depot path, and audio logs |
| Choice labels are blank or stale | Screenplay option locstring, unsigned locale-block ordering, descriptor/payload variantId, and vpeIndex |
| Choice takes the wrong branch | Option order, output ordinal, destination, and stale active-scene state |
| Line plays but the quest does not continue | Scene exit name and node, scene-node output socket name, and outgoing questphase connection |
| Animation does not play or deforms the actor | Performer mapping, actor-visible animation-set slot, animation name, component/mask, and rig compatibility |
| Scene workspot never succeeds | Actor reference, workspot data/instance IDs, transform, params, wrapper mapping, and output semantics |
| Contact remains after completion | Leave condition, community Deactivate, and any durable community/device state; reaching scnEndNode is not cleanup |
| A rebuild behaves like an older graph | Save history, active scene/checkpoint state, facts, and journal state before editing more resources |
Next: Scene resource anatomy.