LSDE Dialog Engine / SceneHandle

Interface: SceneHandle

Defined in: types.ts:892

Public interface for controlling a running scene.

Remarks

Obtain a SceneHandle by calling engine.scene(sceneUuid). Use it to register scene-specific (Tier 2) handlers, then call start() to begin traversal from the scene's entry block.

Lifecycle:

1. start() → onSceneEnter fires → first block is dispatched
2. Blocks are dispatched sequentially, following connections via port resolution
3. Scene ends when: no more connections, or cancel() is called
4. All async tracks are cancelled → current block cleanup runs → onSceneExit fires

Scene-level handlers (onDialog, onChoice, etc.) are called before global handlers. Both tiers execute unless the scene handler calls context.preventGlobalHandler(). Use onBlock(uuid, handler) for a block-specific handler that takes highest priority.

Example

const handle = engine.scene(sceneId);
handle.onDialog(({ block, context, next }) => {
  showText(block.dialogueText?.['en']);
  next();
});
handle.onExit(({ scene }) => {
  console.log('Scene finished, visited:', scene.getVisitedBlocks().size);
});
handle.start();

See

• BlockHandlerArgs for handler arguments
• BlueprintScene for the scene data structure

Methods

cancel()

cancel(): void

Defined in: types.ts:896

Cancel the scene flow.

Returns

void

---

evaluateCondition()

evaluateCondition(condition): boolean

Defined in: types.ts:939

Evaluate a condition. Handles choice: conditions via internal choice history. Returns false for non-choice conditions.

Parameters

condition

ExportCondition

Returns

boolean

---

getActiveTracks()

getActiveTracks(): number

Defined in: types.ts:929

Get the number of async tracks currently running in parallel.

Returns

number

---

getChoice()

getChoice(blockUuid): readonly string[] | undefined

Defined in: types.ts:936

Get the choice(s) selected at a specific block. Returns undefined if block never visited as choice.

Parameters

blockUuid

string

Returns

readonly string[] | undefined

---

getChoiceHistory()

getChoiceHistory(): ReadonlyMap<string, readonly string[]>

Defined in: types.ts:934

Get the full choice history for this scene. Keys are block UUIDs, values are arrays of selected choice UUIDs.

Returns

ReadonlyMap<string, readonly string[]>

---

getCurrentBlock()

getCurrentBlock(): BlueprintBlock | null

Defined in: types.ts:923

Get the block currently being executed.

Returns

BlueprintBlock | null

---

getTrackInfos()

getTrackInfos(): readonly TrackInfo[]

Defined in: types.ts:931

Get detailed info for all currently running async tracks. Useful for debug, rendering, and validation.

Returns

readonly TrackInfo[]

---

getVisitedBlocks()

getVisitedBlocks(): ReadonlySet<string>

Defined in: types.ts:925

Get UUIDs of all blocks visited so far.

Returns

ReadonlySet<string>

---

isRunning()

isRunning(): boolean

Defined in: types.ts:927

Check if the scene flow is currently active.

Returns

boolean

---

onAction()

onAction(handler): void

Defined in: types.ts:920

Override all ACTION blocks for this scene.

Parameters

handler

ActionHandler

Returns

void

---

onActionId()

onActionId(blockUuid, handler): void

Defined in: types.ts:912

Override a specific ACTION block by UUID (type-safe).

Parameters

blockUuid

string

handler

ActionHandler

Returns

void

---

onBlock()

onBlock(blockUuid, handler): void

Defined in: types.ts:904

Override a specific block by UUID.

Parameters

blockUuid

string

handler

BlockHandler<BlueprintBlock, BaseBlockContext>

Returns

void

---

onChoice()

onChoice(handler): void

Defined in: types.ts:916

Override all CHOICE blocks for this scene.

Parameters

handler

ChoiceHandler

Returns

void

---

onChoiceId()

onChoiceId(blockUuid, handler): void

Defined in: types.ts:908

Override a specific CHOICE block by UUID (type-safe).

Parameters

blockUuid

string

handler

ChoiceHandler

Returns

void

---

onCondition()

onCondition(handler): void

Defined in: types.ts:918

Override all CONDITION blocks for this scene.

Parameters

handler

ConditionHandler

Returns

void

---

onConditionId()

onConditionId(blockUuid, handler): void

Defined in: types.ts:910

Override a specific CONDITION block by UUID (type-safe).

Parameters

blockUuid

string

handler

ConditionHandler

Returns

void

---

onDialog()

onDialog(handler): void

Defined in: types.ts:914

Override all DIALOG blocks for this scene.

Parameters

handler

DialogHandler

Returns

void

---

onDialogId()

onDialogId(blockUuid, handler): void

Defined in: types.ts:906

Override a specific DIALOG block by UUID (type-safe).

Parameters

blockUuid

string

handler

DialogHandler

Returns

void

---

onEnter()

onEnter(handler): void

Defined in: types.ts:899

Override the global onSceneEnter for this scene.

Parameters

handler

SceneLifecycleHandler

Returns

void

---

onExit()

onExit(handler): void

Defined in: types.ts:901

Override the global onSceneExit for this scene.

Parameters

handler

SceneLifecycleHandler

Returns

void

---

onResolveCharacter()

onResolveCharacter(fn): void

Defined in: types.ts:941

Override character resolution for this scene. Defaults to engine-level resolver.

Parameters

fn

(characters) => BlockCharacter | undefined

Returns

void

---

start()

start(): void

Defined in: types.ts:894

Start the scene flow from the entry block.

Returns

void