Class: ChoicekitEngine<TEngineGenerics>

Defined in: engine/if-engine.ts:168

The main engine for Choicekit that provides headless interface to basic utilities required for Interactive Fiction

Dispatches custom events that can be listened to with “addEventListener”

Type Parameters

TEngineGenerics

TEngineGenerics extends ChoicekitEngineGenerics = ChoicekitEngineGenerics

Properties

$

$: MapPluginsToApiSurface<TEngineGenerics["plugins"]> = {}

Defined in: engine/if-engine.ts:176

name

readonly name: TEngineGenerics["name"]

Defined in: engine/if-engine.ts:173

Must be unique to prevent conflicts

Accessors

index

Get Signature

get index(): number

Defined in: engine/if-engine.ts:1113

The current position in the state history that the engine is playing.

This is used to determine the current state of the engine.

READONLY VERSION

Returns

number

passage

Get Signature

get passage(): TEngineGenerics["passages"] | null

Defined in: engine/if-engine.ts:1121

Returns the passage data for the current state.

If the passage does not exist, returns null.

Returns

TEngineGenerics["passages"] | null

passageId

Get Signature

get passageId(): TEngineGenerics["passages"]["name"]

Defined in: engine/if-engine.ts:1126

Returns the id to the appropriate passage for the current state

Returns

TEngineGenerics["passages"]["name"]

random

Get Signature

get random(): number

Defined in: engine/if-engine.ts:1131

Based off an internal PRNG, returns a random float between 0 and 1, inclusively

Returns

number

vars

Get Signature

get vars(): Readonly<typeof this._type.state.complete>

Defined in: engine/if-engine.ts:1151

Returns a readonly copy of the current state of stored variables.

May be expensive to calculate depending on the history of the story.

Returns

Readonly<typeof this._type.state.complete>

Methods

addPassages()

addPassages(…passageData): void

Defined in: engine/if-engine.ts:432

Adds new passages to the engine.

The passage id should be unique, and the data can be anything that you want to store for the passage.

If the passage already exists, it will be overwritten.

Parameters

passageData

…readonly TEngineGenerics["passages"][]

Returns

void

Throws

if a passage with the same name already exists

backward()

backward(step?): void

Defined in: engine/if-engine.ts:445

Moves at least one step backwards in the state history.

Does nothing if already at the first state snapshot.

Parameters

step?

number = 1

Returns

void

deleteAllSaveSlots()

deleteAllSaveSlots(): Promise<unknown>

Defined in: engine/if-engine.ts:1005

Returns

Promise<unknown>

deleteSaveSlot()

deleteSaveSlot(saveSlot?): Promise<unknown>

Defined in: engine/if-engine.ts:968

Deletes any save data associated with the provided save slot.

Parameters

saveSlot?

number

if not provided, defaults to the autosave slot

Returns

Promise<unknown>

Throws

if the save slot is invalid or if the persistence adapter is not available

forward()

forward(step?): void

Defined in: engine/if-engine.ts:459

Moves at least one step forward in the state history.

Does nothing if already at the most recent state snapshot.

Parameters

step?

number = 1

Returns

void

getPassages()

getPassages(query): readonly TEngineGenerics["passages"][]

Defined in: engine/if-engine.ts:509

Returns an array of passages that match the specified tags.

Parameters

query

{ tags: [...TEngineGenerics["passages"]["tags"][]]; type: "all"; } | { tags: [...TEngineGenerics["passages"]["tags"][]]; type: "any"; }

Type Literal

{ tags: [...TEngineGenerics["passages"]["tags"][]]; type: "all"; }

type

"all"

Matches any passage that has all of the given tags

Type Literal

{ tags: [...TEngineGenerics["passages"]["tags"][]]; type: "any"; }

type

"any"

Matches any passage that has at least one of the given tags

Returns

readonly TEngineGenerics["passages"][]

An array of passages that match the specified tags.

getSaves()

getSaves(): AsyncGenerator<{ type: "autosave"; } | { slot: number; type: "normal"; } & object>

Defined in: engine/if-engine.ts:577

Returns an async generator containing the data of all present saves.

Save data is a lazy callback to prevent wasteful deserialization and decompression of save data that may not be used.

Returns

AsyncGenerator<{ type: "autosave"; } | { slot: number; type: "normal"; } & object>

getVisitCount()

getVisitCount(passageId?): number

Defined in: engine/if-engine.ts:554

Gets all the times the passage has been visited by looping through each snapshot and initial state.

Use this in place of hasVisited(id), i.e getVisitCount(id) > 0

Parameters

passageId?

string = ...

TODO: benchmark this later to see if caching will be beneficial

Returns

number

loadFromExport()

loadFromExport(data): Promise<SaveOrLoadReturnType<void>>

Defined in: engine/if-engine.ts:643

Can be used when directly loading a save from an exported save on disk

Parameters

data

string

Returns

Promise<SaveOrLoadReturnType<void>>

loadFromObject()

loadFromObject(save): SaveOrLoadReturnType

Defined in: engine/if-engine.ts:743

Loads the save data from the provided save data object.

This is used to load saves from the getSaves() method.

Parameters

save

Readonly<{ data: SaveData<TChoicekitVariables>; meta: SaveMetadata; }>

The save data to load

Returns

SaveOrLoadReturnType

loadFromSaveSlot()

loadFromSaveSlot(saveSlot?): Promise<SaveOrLoadReturnType<void>>

Defined in: engine/if-engine.ts:671

Parameters

saveSlot?

number

if not provided, defaults to the autosave slot

Returns

Promise<SaveOrLoadReturnType<void>>

loadRecentSave()

loadRecentSave(): Promise<SaveOrLoadReturnType<void>>

Defined in: engine/if-engine.ts:717

Loads the most recent save, if any. Doesn’t throw

Returns

Promise<SaveOrLoadReturnType<void>>

navigateTo()

navigateTo(passageId?): Partial<TEngineGenerics["vars"] & SnapshotMetadata>

Defined in: engine/if-engine.ts:477

Creates and moves the index over to a new snapshot with the given passage id (or the previous one) and returns a reference to it.

This is essentially the way of linking between passages in the story.

Yes, you can navigate to the same passage multiple times, and it will create a new snapshot each time. It’s intended behavior.

Parameters

passageId?

TEngineGenerics["passages"]["name"] = ...

Returns

Partial<TEngineGenerics["vars"] & SnapshotMetadata>

Throws

if the passage id hasn’t been added to the engine

off()

off<TEventName>(eventName, listener): void

Defined in: engine/if-engine.ts:1040

Unsubscribe from an event

Type Parameters

TEventName

TEventName extends keyof ChoicekitEvents<TEngineGenerics["passages"], TEngineGenerics["vars"]>

Parameters

eventName

TEventName

listener

(payload) => void

Returns

void

on()

on<TEventName>(eventName, listener): () => void

Defined in: engine/if-engine.ts:1025

Subscribe to an event.

Type Parameters

TEventName

TEventName extends keyof ChoicekitEvents<TEngineGenerics["passages"], TEngineGenerics["vars"]>

Parameters

eventName

TEventName

listener

(payload) => void

Returns

a function that can be used to unsubscribe from the event.

() => void

once()

once<TEventName>(eventName, listener): () => void

Defined in: engine/if-engine.ts:1032

Type Parameters

TEventName

TEventName extends keyof ChoicekitEvents<TEngineGenerics["passages"], TEngineGenerics["vars"]>

Parameters

eventName

TEventName

listener

(payload) => void

Returns

() => void

registerClasses()

registerClasses(…customClasses): void

Defined in: engine/if-engine.ts:1048

Any custom classes stored in the story’s state must be registered with this

Parameters

customClasses

…ChoicekitClassConstructorWithValidSerialization[]

Returns

void

registerMigrators()

registerMigrators<TOldSaveStructure, TNewSaveStructure>(…migrators): void

Defined in: engine/if-engine.ts:1058

Use this to register custom callbacks for migrating outdated save data

Type Parameters

TOldSaveStructure

TOldSaveStructure

TNewSaveStructure

TNewSaveStructure = TEngineGenerics["vars"]

Parameters

migrators

…object[]

Returns

void

Throws

if a migration for the same version already exists

reset()

reset(resetSeed?): void

Defined in: engine/if-engine.ts:1088

Clears all snapshot data and reverts to the initial state.

Use this if you want the engine to essentially, start “afresh”

Parameters

resetSeed?

boolean = false

if true, the initial seed is randomised

Returns

void

saveToExport()

saveToExport(): Promise<SaveOrLoadReturnType<string>>

Defined in: engine/if-engine.ts:899

For exports that need to be stored or transferred outside the current engine instance

Returns

Promise<SaveOrLoadReturnType<string>>

saveToSaveSlot()

saveToSaveSlot(saveSlot?): Promise<SaveOrLoadReturnType<void>>

Defined in: engine/if-engine.ts:926

Using the provided persistence adapter, this saves all vital data for the combined state, metadata, and current index

Parameters

saveSlot?

number

if not provided, defaults to the autosave slot

Returns

Promise<SaveOrLoadReturnType<void>>

setVars()

setVars(producer, emitEvent?): void

Defined in: engine/if-engine.ts:367

Immer-style way of updating story variables

Use this solely for setting values. If you must read a value, use this.vars

If you need to replace the entire state, return a new object instead of directly assigning the value

Parameters

producer

((variables) => void) | ((variables) => TEngineGenerics["vars"])

emitEvent?

boolean = true

If true, a “stateChange” event will be emitted. Set this to false if you use it within a stateChange listener

Returns

void

init()

static init<TGenerics>(args): Promise<ChoicekitEngine<TGenerics>>

Defined in: engine/if-engine.ts:298

Type Parameters

TGenerics

TGenerics extends ChoicekitEngineGenerics

Parameters

args

Partial<ChoicekitEngineArguments<TGenerics>>

Returns

Promise<ChoicekitEngine<TGenerics>>