Class: ChoicekitEngine<TEngineGenerics>
Class: ChoicekitEngine<TEngineGenerics>
Section titled “Class: ChoicekitEngine<TEngineGenerics>”Defined in: engine/if-engine.ts:162
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
Section titled “Type Parameters”TEngineGenerics
Section titled “TEngineGenerics”TEngineGenerics extends ChoicekitEngineGenerics = ChoicekitEngineGenerics
Properties
Section titled “Properties”$
$:
MapPluginsToApiSurface<TEngineGenerics["plugins"]> ={}
Defined in: engine/if-engine.ts:170
readonlyname:TEngineGenerics["name"]
Defined in: engine/if-engine.ts:167
Must be unique to prevent conflicts
Accessors
Section titled “Accessors”Get Signature
Section titled “Get Signature”get index():
number
Defined in: engine/if-engine.ts:1034
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
Section titled “Returns”number
passage
Section titled “passage”Get Signature
Section titled “Get Signature”get passage():
TEngineGenerics["passages"] |null
Defined in: engine/if-engine.ts:1042
Returns the passage data for the current state.
If the passage does not exist, returns null.
Returns
Section titled “Returns”TEngineGenerics["passages"] | null
passageId
Section titled “passageId”Get Signature
Section titled “Get Signature”get passageId():
TEngineGenerics["passages"]["name"]
Defined in: engine/if-engine.ts:1047
Returns the id to the appropriate passage for the current state
Returns
Section titled “Returns”TEngineGenerics["passages"]["name"]
random
Section titled “random”Get Signature
Section titled “Get Signature”get random():
number
Defined in: engine/if-engine.ts:1052
Based off an internal PRNG, returns a random float between 0 and 1, inclusively
Returns
Section titled “Returns”number
Get Signature
Section titled “Get Signature”get vars():
Readonly<typeofthis._type.state.complete>
Defined in: engine/if-engine.ts:1072
Returns a readonly copy of the current state of stored variables.
May be expensive to calculate depending on the history of the story.
Returns
Section titled “Returns”Readonly<typeof this._type.state.complete>
Methods
Section titled “Methods”addPassage()
Section titled “addPassage()”addPassage(
passageData):void
Defined in: engine/if-engine.ts:428
Adds a new passage 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
Section titled “Parameters”passageData
Section titled “passageData”TEngineGenerics["passages"]
Returns
Section titled “Returns”void
addPassages()
Section titled “addPassages()”addPassages(…
passageData):void
Defined in: engine/if-engine.ts:433
Like addPassage, but takes in a collection
Parameters
Section titled “Parameters”passageData
Section titled “passageData”…readonly TEngineGenerics["passages"][]
Returns
Section titled “Returns”void
backward()
Section titled “backward()”backward(
step?):void
Defined in: engine/if-engine.ts:443
Moves at least one step backwards in the state history.
Does nothing if already at the first state snapshot.
Parameters
Section titled “Parameters”number = 1
Returns
Section titled “Returns”void
deleteAllSaveSlots()
Section titled “deleteAllSaveSlots()”deleteAllSaveSlots():
Promise<unknown>
Defined in: engine/if-engine.ts:453
Returns
Section titled “Returns”Promise<unknown>
deleteSaveSlot()
Section titled “deleteSaveSlot()”deleteSaveSlot(
saveSlot?):Promise<unknown>
Defined in: engine/if-engine.ts:473
Deletes any save data associated with the provided save slot.
Parameters
Section titled “Parameters”saveSlot?
Section titled “saveSlot?”number
if not provided, defaults to the autosave slot
Returns
Section titled “Returns”Promise<unknown>
Throws
Section titled “Throws”if the save slot is invalid or if the persistence adapter is not available
forward()
Section titled “forward()”forward(
step?):void
Defined in: engine/if-engine.ts:506
Moves at least one step forward in the state history.
Does nothing if already at the most recent state snapshot.
Parameters
Section titled “Parameters”number = 1
Returns
Section titled “Returns”void
getPassages()
Section titled “getPassages()”getPassages(
query): readonlyTEngineGenerics["passages"][]
Defined in: engine/if-engine.ts:555
Returns an array of passages that match the specified tags.
Parameters
Section titled “Parameters”{ tags: [...TEngineGenerics["passages"]["tags"][]]; type: "all"; } | { tags: [...TEngineGenerics["passages"]["tags"][]]; type: "any"; }
Type Literal
Section titled “Type Literal”{ tags: [...TEngineGenerics["passages"]["tags"][]]; type: "all"; }
[...TEngineGenerics["passages"]["tags"][]]
"all"
Matches any passage that has all of the given tags
Type Literal
Section titled “Type Literal”{ tags: [...TEngineGenerics["passages"]["tags"][]]; type: "any"; }
[...TEngineGenerics["passages"]["tags"][]]
"any"
Matches any passage that has at least one of the given tags
Returns
Section titled “Returns”readonly TEngineGenerics["passages"][]
An array of passages that match the specified tags.
getSaves()
Section titled “getSaves()”getSaves():
AsyncGenerator<{data:SaveData<TEngineGenerics["vars"]>;type:"autosave"; } | {data:SaveData<TEngineGenerics["vars"]>;slot:number;type:"normal"; }>
Defined in: engine/if-engine.ts:517
Returns an object containing the data of all present saves
Returns
Section titled “Returns”AsyncGenerator<{ data: SaveData<TEngineGenerics["vars"]>; type: "autosave"; } | { data: SaveData<TEngineGenerics["vars"]>; slot: number; type: "normal"; }>
getVisitCount()
Section titled “getVisitCount()”getVisitCount(
passageId?):number
Defined in: engine/if-engine.ts:600
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
Section titled “Parameters”passageId?
Section titled “passageId?”string = ...
TODO: benchmark this later to see if caching will be beneficial
Returns
Section titled “Returns”number
loadFromExport()
Section titled “loadFromExport()”loadFromExport(
data):Promise<void>
Defined in: engine/if-engine.ts:621
Can be used when directly loading a save from an exported save on disk
Parameters
Section titled “Parameters”string
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”if the save was made on a later version than the engine or if a save migration throws
loadFromSaveSlot()
Section titled “loadFromSaveSlot()”loadFromSaveSlot(
saveSlot?):Promise<void>
Defined in: engine/if-engine.ts:647
Parameters
Section titled “Parameters”saveSlot?
Section titled “saveSlot?”number
if not provided, defaults to the autosave slot
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”if the save slot is invalid or if the persistence adapter is not available
loadRecentSave()
Section titled “loadRecentSave()”loadRecentSave():
Promise<void>
Defined in: engine/if-engine.ts:675
Loads the most recent save, if any. Doesn’t throw
Returns
Section titled “Returns”Promise<void>
loadSaveFromData()
Section titled “loadSaveFromData()”loadSaveFromData(
save):Promise<void>
Defined in: engine/if-engine.ts:695
Loads the save data from the provided save data object.
This is used to load saves from the getSaves() method.
Parameters
Section titled “Parameters”Readonly<{ intialState: TEngineGenerics["vars"] & SnapshotMetadata; lastPassageId: string; plugins: Record<string, ChoicekitPluginSaveStructure>; savedOn: Date; snapshots: Partial<TEngineGenerics["vars"] & SnapshotMetadata>[]; storyIndex: number; version: `${number}.${number}.${number}`; }>
The save data to load
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”if the save was made on a later version than the engine or if a save migration throws
navigateTo()
Section titled “navigateTo()”navigateTo(
passageId?):Partial<TEngineGenerics["vars"] &SnapshotMetadata>
Defined in: engine/if-engine.ts:857
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
Section titled “Parameters”passageId?
Section titled “passageId?”TEngineGenerics["passages"]["name"] = ...
Returns
Section titled “Returns”Partial<TEngineGenerics["vars"] & SnapshotMetadata>
Throws
Section titled “Throws”if the passage id hasn’t been added to the engine
off<
TEventName>(eventName,listener):void
Defined in: engine/if-engine.ts:902
Unsubscribe from an event
Type Parameters
Section titled “Type Parameters”TEventName
Section titled “TEventName”TEventName extends keyof ChoicekitEvents<TEngineGenerics["passages"], TEngineGenerics["vars"]>
Parameters
Section titled “Parameters”eventName
Section titled “eventName”TEventName
listener
Section titled “listener”(payload) => void
Returns
Section titled “Returns”void
on<
TEventName>(eventName,listener): () =>void
Defined in: engine/if-engine.ts:887
Subscribe to an event.
Type Parameters
Section titled “Type Parameters”TEventName
Section titled “TEventName”TEventName extends keyof ChoicekitEvents<TEngineGenerics["passages"], TEngineGenerics["vars"]>
Parameters
Section titled “Parameters”eventName
Section titled “eventName”TEventName
listener
Section titled “listener”(payload) => void
Returns
Section titled “Returns”a function that can be used to unsubscribe from the event.
() => void
once()
Section titled “once()”once<
TEventName>(eventName,listener): () =>void
Defined in: engine/if-engine.ts:894
Type Parameters
Section titled “Type Parameters”TEventName
Section titled “TEventName”TEventName extends keyof ChoicekitEvents<TEngineGenerics["passages"], TEngineGenerics["vars"]>
Parameters
Section titled “Parameters”eventName
Section titled “eventName”TEventName
listener
Section titled “listener”(payload) => void
Returns
Section titled “Returns”() => void
registerClasses()
Section titled “registerClasses()”registerClasses(…
customClasses):void
Defined in: engine/if-engine.ts:910
Any custom classes stored in the story’s state must be registered with this
Parameters
Section titled “Parameters”customClasses
Section titled “customClasses”…ChoicekitClassConstructorWithValidSerialization[]
Returns
Section titled “Returns”void
registerMigrators()
Section titled “registerMigrators()”registerMigrators<
TOldSaveStructure,TNewSaveStructure>(…migrators):void
Defined in: engine/if-engine.ts:922
Use this to register custom callbacks for migrating outdated save data
Type Parameters
Section titled “Type Parameters”TOldSaveStructure
Section titled “TOldSaveStructure”TOldSaveStructure
TNewSaveStructure
Section titled “TNewSaveStructure”TNewSaveStructure = TEngineGenerics["vars"]
Parameters
Section titled “Parameters”migrators
Section titled “migrators”…object[]
Returns
Section titled “Returns”void
Throws
Section titled “Throws”if a migration for the same version already exists
reset()
Section titled “reset()”reset(
resetSeed?):void
Defined in: engine/if-engine.ts:950
Clears all snapshot data and reverts to the initial state.
Use this if you want the engine to essentially, start “afresh”
Parameters
Section titled “Parameters”resetSeed?
Section titled “resetSeed?”boolean = false
if true, the initial seed is randomised
Returns
Section titled “Returns”void
saveToExport()
Section titled “saveToExport()”saveToExport():
Promise<string>
Defined in: engine/if-engine.ts:968
For saves the need to exported out of the browser
Returns
Section titled “Returns”Promise<string>
saveToSaveSlot()
Section titled “saveToSaveSlot()”saveToSaveSlot(
saveSlot?):Promise<void>
Defined in: engine/if-engine.ts:999
Using the provided persistence adapter, this saves all vital data for the combined state, metadata, and current index
Parameters
Section titled “Parameters”saveSlot?
Section titled “saveSlot?”number
if not provided, defaults to the autosave slot
Returns
Section titled “Returns”Promise<void>
Throws
Section titled “Throws”if the persistence adapter is not available
setVars()
Section titled “setVars()”setVars(
producer,emitEvent?):void
Defined in: engine/if-engine.ts:364
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
Section titled “Parameters”producer
Section titled “producer”((variables) => void) | ((variables) => TEngineGenerics["vars"])
emitEvent?
Section titled “emitEvent?”boolean = true
If true, a “stateChange” event will be emitted. Set this to false if you use it within a stateChange listener
Returns
Section titled “Returns”void
init()
Section titled “init()”
staticinit<TGenerics>(args):Promise<ChoicekitEngine<TGenerics>>
Defined in: engine/if-engine.ts:298
Type Parameters
Section titled “Type Parameters”TGenerics
Section titled “TGenerics”TGenerics extends ChoicekitEngineGenerics
Parameters
Section titled “Parameters”Partial<ChoicekitEngineArguments<TGenerics>>
Returns
Section titled “Returns”Promise<ChoicekitEngine<TGenerics>>