Clue layers, cleanup, and acceptance

Layered clues are not decorations on recorded animation. Each clue has a timeline window, an analysis layer, a target entity, discovery behavior, and a quest-state handoff. Normal exit, interruption, and replay must agree about which of those results persist.

Research note: layered clue events, BD visibility events, scene-side discovery nodes, layer/perspective conditions, and support props are Observed in vanilla in the cited SQ012/Q004 resources. The retained mod-owned scene serializes these shapes and is Structurally validated. No custom package has a retained eight-case pass, so layer switching, discovery, cleanup, interruption, and replay remain Experimental.

The clue ownership chain

rewindable timeline interval
  -> scneventsClueEvent(layer, clueName, entity, time range)
       -> placed/acquired clue entity
       -> BD layer/perspective conditions
       -> questDiscoverBraindanceClue_NodeType or focused clue operation
       -> dedicated discovery fact
       -> questphase fact wait/join
       -> journal objective and terminal outcome

Do not skip from “the highlight was visible” to “the quest recorded the clue.” Those observations sit at different points in the chain.

What a clue event owns

The focused SQ012 scneventsClueEvent entries expose these properties:

One inspected visual clue addresses actor name holt through community #sq012_com_braindance; an audio clue addresses standalone NodeRef #sq012_ent_rqr_audio_clue. These are Observed in vanilla examples of two entity-reference shapes. They are not reusable identifiers.

The same SQ012 rewindable section contains six clue events: visual and audio examples, each with its own interval. The larger Q004 Yorinobu scene contains visual/audio/thermal analysis logic, 23 clue-toggle events, 27 questDiscoverBraindanceClue_NodeType nodes, and 112 scnBraindanceLayer_ConditionType values in the focused current extraction. Those counts describe that exact main-quest scene; they are not minimums.

Layer state and discovery state are different

Keep at least four state questions separate:

1. Which analysis layer is currently selected?
2. Is the playhead inside this clue’s time interval?
3. Is the clue entity available and focusable?
4. Has the clue’s discovery result already been committed?

A Boolean design should usually require the applicable layer and interval before enabling focus/discovery. A discovery fact may intentionally remain true after the playhead rewinds or the player switches layers. That persistence must be an explicit quest design decision.

Use one dedicated fact per independently required clue. Joining three clue facts with a logical AND makes completion readable and testable:

visual_clue_found > 0 ---\
audio_clue_found > 0 ----- AND -> update objective -> enable finish/exit
thermal_clue_found > 0 ---/

This graph records discovery; it does not enforce simultaneous layer state. See Boolean trees and Signal flow.

Inspect and author clues in WolvenKit

Start in a disposable inspection project with base\quest\side_quests\sq012\scenes\sq012_02a_braindance.scene and base\quest\main_quests\prologue\q004\scenes\q004_05_bd_yorinobu.scene. For one clue in each resource, record the event type, layer, clue name, start/duration, entity-reference shape, timeline-marker policy, discovery operation, fact, and downstream journal/finish route. Do not add either vanilla scene to a distributable project.

For a mod-owned candidate, compose one layer at a time:

1. Place or acquire one mod-owned clue entity and give it a fresh full NodeRef or actor/community reference.
2. Add one scneventsClueEvent to the rewindable section with an interval entirely inside the section duration.
3. Set the exact analysis layer and decide whether the clue is marked on the timeline.
4. Add the layer/interval/focus path and one discovery operation.
5. Write one dedicated fact and wait for that exact fact in the owning questphase before changing journal state.
6. Add the clue’s temporary focus/highlight state to both normal and interrupted cleanup ledgers.
7. Serialize the .scene to CR2W, reopen or serialize it back to JSON, and verify that event identity, layer, interval, entity reference, and fact survived.
8. Repeat for audio and thermal only after the visual clue passes structural inspection; do not duplicate scene-local IDs or facts.

WolvenKit round trips and a visible property graph support Structurally validated. They do not prove that the runtime switches layer, discovers the entity, writes the fact, or reconstructs the clue after a seek.

Support props are lifecycle resources

BD view, fog, and setup are separate scene props in the inspected SQ012 scene. Their scnPropDef entries use a Props.* TweakDBID, a spawn/despawn acquisition plan, a unique dynamic entity name, and a global support-marker NodeRef.

The corresponding focused vanilla entity resources are:

base\quest\side_quests\sq012\entities\sq012_02a_braindance_bdview.ent
base\quest\side_quests\sq012\entities\sq012_02a_braindance_bdfog.ent
base\quest\side_quests\sq012\entities\sq012_02a_braindance_bdsetup.ent

The view/fog entities are mesh-bearing entEntityTemplate resources. The setup entity includes entRenderToTextureCameraComponent. Their scene definitions, TweakDB records, entity paths, spawn marker, visibility events, and cleanup policy must agree.

The camera is another prop/world entity and another RID binding. Do not use the BD setup prop as evidence that the recorded-perspective camera exists or that the gameplay camera was restored.

Separate temporary and durable state

Classify every mutation before building the exit routes.

If normal and interrupted cleanup disagree on temporary state, the second run is not a valid replay test.

Normal exit contract

A conservative quest-side route is:

prepare world and acquire performers
  -> place/hold player and set required UI/input state
  -> start rewindable scene at named input and origin
  -> receive named normal outcome
  -> restore camera/render/UI/input state
  -> return player to safe anchor
  -> release support props and transient owners
  -> commit discovery/journal outcome once
  -> complete child phase

The exact manager nodes depend on the candidate. Explain every changed state and its inverse. Delay only when the target system has an asynchronous lifecycle that requires it; a magic sleep is not a cleanup proof.

Interrupted exit contract

Interruption may arrive while an actor, camera, clue, or support effect is active. It therefore needs a first-class route, not a connection directly to the normal terminal node:

interruption / CutDestination / abort signal
  -> stop or cut scene ownership
  -> disable discovery interaction
  -> restore camera/render/UI/input state
  -> return player if relocation occurred
  -> release props, actors, and transient world operations
  -> preserve or roll back durable facts according to policy
  -> leave through a named, testable phase output

The inspected SQ012 scene includes one enabled distance-based scnInterruptionScenario with different interrupt and return thresholds. That is Observed in vanilla scene structure. It does not prove that an arbitrary custom questphase’s CutDestination or cleanup path is correct.

See Complex cleanup, interruption, and cancellation for the cross-system ownership ledger.

Save and replay boundary

Facts, journal state, quest checkpoints, active scene state, spawned communities, and some device/world state can survive archive replacement. Use the specified starting save and keep the installed build unchanged.

Prepare at least these save seeds:

• seed-before-install: created before any version of the candidate was installed;
• seed-before-entry: candidate installed, quest available, BD child not yet active;
• seed-in-playback-early: optional diagnostic only; never substitute it for the clean normal-entry case;
• seed-after-normal-cleanup: produced by the exact package under test and used only for the replay case.

Do not load a mid-scene save captured from an older archive to test a rebuilt RID or event table. The save may retain an active scene/checkpoint layout that no longer matches the package.

Mandatory eight-case runtime matrix

Run each case separately; seek, rewind, layer discovery, and cleanup can fail independently.

For every row, retain:

• case ID and pass/fail;
• installed archive and external asset paths;
• game, WolvenKit, ArchiveXL, RED4ext, redscript, and relevant audio/animation tool versions;
• starting-save identity and provenance;
• expected and observed facts/journal states before and after;
• expected and observed actor, prop, camera, UI/input, player-placement, and scene/phase ownership;
• timestamps or screenshots/log excerpts sufficient to audit the observation;
• unexpected behavior and whether the case was rerun from a fresh clone.

Check that all eight cases passed for the exact package you intend to distribute. Repeat the affected tests after changing its resources.

Failure routing

This is the final braindance page. Return to Braindance and specialized scenes or continue to Troubleshooting.