Skip to Content
defold-typescript libraries
abadonna

abadonna/defold-ink/ink

The Ink language runtime implementation in Lua, an alternative to Narrator, based on parsing ink JSON files.

  • GitHub: abadonna/defold-ink — pinned to 5e871c4
    1. This repo publishes no releases or tags. Add a commit archive URL — for the pinned commit, https://github.com/abadonna/defold-ink/archive/5e871c42f645689e7263d85015fab2b2f2743907.zip — to game.project under [project] dependencies, then Fetch Libraries in the Defold editor.
    2. Run bunx @defold-typescript/cli resolve to materialize its types.
    3. Import it under a namespace alias of your choice:
      import * as ink from "ink.story"

Functions

create(s: string): Story

Parses a compiled ink story and returns a story instance.

Parameters

  • s: string — The ink JSON text, for example from sys.load_resource. It must be UTF-8.

Returns

  • Story — The story instance.

Types

type StoryOutput = LuaMultiReturn<[ Paragraph[], Answer[] ]>

Story

Story.variables: LuaTable<string, unknown>

A table of all global variables, to read and set. Use assign_value to notify observer functions about a change.

Story.continue: (answer?: number) => StoryOutput

Returns the next paragraphs and choices.

Story.add_observer: (name: string, f: (this: void, value: unknown) => void) => void

Assigns an observer function to a global variable. Each global variable can have multiple observers.

Story.remove_observer: (name: string, f?: (this: void, value: unknown) => void) => void

Removes an observer function.

Story.assign_value: (name: string, value: unknown) => void

Assigns a value to a global variable and calls all its observers.

Story.bind: (name: string, f: (this: void, ...args: any[]) => unknown) => void

Binds a Lua function to an ink external function, which the story then calls with the external function's arguments.

Story.jump: (path: string) => StoryOutput

Jumps to a named knot or stitch, and returns its paragraphs and choices.

Story.switch_flow: (name?: string) => void

Creates a new parallel flow or switches to an existing one.

Story.restore: (state: StoryState, with_bindings?: boolean, ignore_errors?: boolean) => StoryOutput

Restores the story from a state saved with get_state, by replaying it from the start, and returns its last paragraphs and choices. The story should be created from the same, or a similar, JSON.

Story.get_state: () => StoryState

Returns the current state of the story, to save and pass to restore later.

Story.eval: (expression: string) => unknown

Returns the result of evaluating a Lua expression, with the name of every global variable replaced by its value.

Story.serialize: () => SerializedStory

Returns the story's variables and visit counts, an alternative to get_state that survives script changes better. Pass it to deserialize, not to restore.

Story.deserialize: (data: SerializedStory, path: string, reset_observers?: boolean) => StoryOutput

Restores the story's variables and visit counts from serialize, then jumps to a path and returns its paragraphs and choices.

Paragraph

Paragraph.text: string

The paragraph text, trimmed. It is empty for a paragraph that only carries tags.

Paragraph.tags: string[]

The tags attached to the paragraph, empty when it has none.

Answer

Answer.text: string

The choice text.

Answer.tags: string[]

The tags attached to the choice, empty when it has none.

StoryState

StoryState.input: LuaTable[]

The player's inputs, in order: answers, jumps, flow switches and assigned values.

StoryState.randoms: number[]

The random values the story rolled, so a replay rolls the same ones.

SerializedStory

SerializedStory.globals: LuaTable<string, unknown>

The story's global variables.

SerializedStory.root: LuaTable

The visit counts of the story's containers.

On this page