LSDE Dialog Engine / SceneHandle

Interface: SceneHandle

Defined in: types.ts:661

Public interface for controlling a running scene.

Remarks

Obtain a SceneHandle by calling engine.scene(sceneRef). 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(blockId, 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:665

Cancel the scene flow.

Returns

void

---

evaluateCondition()

evaluateCondition(condition): boolean

Defined in: types.ts:717

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

Parameters

condition

ConditionTest

Returns

boolean

---

getActiveTracks()

getActiveTracks(): number

Defined in: types.ts:707

Get the number of async tracks currently running in parallel.

Returns

number

---

getChoice()

getChoice(blockId): readonly string[] | undefined

Defined in: types.ts:714

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

Parameters

blockId

string

Returns

readonly string[] | undefined

---

getChoiceHistory()

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

Defined in: types.ts:712

Get the full choice history for this scene. Keys are block ids, values are the option ids the player picked there, in order.

Returns

ReadonlyMap<string, readonly string[]>

---

getCurrentBlock()

getCurrentBlock(): Block | null

Defined in: types.ts:701

Get the block currently being executed.

Returns

Block | null

---

getSceneId()

getSceneId(): string

Defined in: types.ts:697

The stable id of this scene (sc_u0vqg2g8). Store THIS one outside the payload — a save file, an asset — because it survives a rename.

engine.onSceneExit is global: with several scenes playing, this is how it tells which one ended.

Returns

string

---

getScenePath()

getScenePath(): string

Defined in: types.ts:699

The path of this scene (reactor_breach): what a writer reads, and what a rename changes.

Returns

string

---

getTrackInfos()

getTrackInfos(): readonly TrackInfo[]

Defined in: types.ts:709

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:703

The id of every block visited so far, in this scene.

Returns

ReadonlySet<string>

---

isRunning()

isRunning(): boolean

Defined in: types.ts:705

Check if the scene flow is currently active.

Returns

boolean

---

onAction()

onAction(handler): void

Defined in: types.ts:689

Override all ACTION blocks for this scene.

Parameters

handler

ActionHandler

Returns

void

---

onActionId()

onActionId(blockId, handler): void

Defined in: types.ts:681

Override one ACTION block by its id (type-safe).

Parameters

blockId

string

handler

ActionHandler

Returns

void

---

onBlock()

onBlock(blockId, handler): void

Defined in: types.ts:673

Override one block by its id (DIALOG-001).

Parameters

blockId

string

handler

BlockHandler<Block, BaseBlockContext>

Returns

void

---

onChoice()

onChoice(handler): void

Defined in: types.ts:685

Override all CHOICE blocks for this scene.

Parameters

handler

ChoiceHandler

Returns

void

---

onChoiceId()

onChoiceId(blockId, handler): void

Defined in: types.ts:677

Override one CHOICE block by its id (type-safe).

Parameters

blockId

string

handler

ChoiceHandler

Returns

void

---

onCondition()

onCondition(handler): void

Defined in: types.ts:687

Override all CONDITION blocks for this scene.

Parameters

handler

ConditionHandler

Returns

void

---

onConditionId()

onConditionId(blockId, handler): void

Defined in: types.ts:679

Override one CONDITION block by its id (type-safe).

Parameters

blockId

string

handler

ConditionHandler

Returns

void

---

onDialog()

onDialog(handler): void

Defined in: types.ts:683

Override all DIALOG blocks for this scene.

Parameters

handler

DialogHandler

Returns

void

---

onDialogId()

onDialogId(blockId, handler): void

Defined in: types.ts:675

Override one DIALOG block by its id (type-safe).

Parameters

blockId

string

handler

DialogHandler

Returns

void

---

onEnter()

onEnter(handler): void

Defined in: types.ts:668

Override the global onSceneEnter for this scene.

Parameters

handler

SceneLifecycleHandler

Returns

void

---

onExit()

onExit(handler): void

Defined in: types.ts:670

Override the global onSceneExit for this scene.

Parameters

handler

SceneLifecycleHandler

Returns

void

---

onResolveCharacter()

onResolveCharacter(fn): void

Defined in: types.ts:719

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

Parameters

fn

(characters) => Card | undefined

Returns

void

---

start()

start(): void

Defined in: types.ts:663

Start the scene flow from the entry block.

Returns

void