InkPlayer

Inherits: Node

Description

A convenience node to run inkgd. Additional information on how to use it is available in Using InkPlayer.

Properties

Exported Properties

Resource	ink_player
bool	loads_in_background	`true`

Read/Write Properties

bool	allow_external_function_fallbacks	`false`
bool	do_not_save_default_values	`false`
bool	stop_execution_on_exception	`false`
bool	stop_execution_on_error	`false`

Read Only Properties

bool	can_continue	`false`
bool	async_continue_complete	`false`
String	current_text	`""`
Array	current_choices	`[]`
Array	current_tags	`[]`
Array	global_tags	`[]`
bool	has_choices	`false`
bool	current_flow_name	`"DEFAULT_FLOW"`
bool	alive_flow_names	`[]`
bool	current_flow_is_default_flow	`true`
bool	current_current_path	`""`

Methods

Story Creation

void	create_story ( )
void	reset ( )
void	destroy ( )

Story Flow

String	continue_story ( )
String	continue_story_async ( float millisecs_limit_async )
String	continue_story_maximally ( )
void	choose_choice_index ( int index )
void	choose_path ( String path_string )
void	switch_flow ( String flow_name )
void	switch_to_default_flow ( )
void	remove_flow ( String flow_name )
Array	tags_for_content_at_path ( String path )
int	visit_count_at_path ( String path )

State Management

String	get_state ( )
String	copy_state_for_background_thread_save ( )
void	background_save_complete ( )
void	set_state ( String state )
void	save_state_to_path ( String path )
void	save_state_to_file ( File file )
void	load_state_from_path ( String path )
void	load_state_from_file ( File file )

Variables

Variant	get_variable ( String name )
void	set_variable ( String name, Variant value )
void	observe_variables ( Array variable_names, Object object, String method_name )
void	observe_variable ( String variable_name, Object object, String method_name )
void	remove_variable_observer ( Object object, String method_name, String specific_variable_name )
void	remove_variable_observer_for_all_variables ( Object object, String method_name )
void	remove_all_variable_observers ( String specific_variable_name )

Functions

void	bind_external_function ( String func_name, Object object, String method_name, bool lookahead_safe=false )
void	unbind_external_function ( String func_name )
InkFunctionResult	evaluate_function ( String function_name, Array arguments )
InkList	create_ink_list_with_origin ( String origin_list_name )
InkList	create_ink_list_from_item_name ( String item_name, )

Signals

exception ( String message, PoolStringArray stack_trace )

Emitted when the ink runtime encountered an exception. Exception are usually not recoverable as they corrupt the state. stack_trace is optional and contains each line of the stack trace leading to the exception for logging purposes.

loaded ( bool successfully )

Emitted with true when the runtime had loaded the JSON content and created the story. If an error was encountered, successfully will be false and error will appear in Godot’s output.

continued ( String text, Array tags )

Emitted with the text and tags of the current line when the story successfully continued.

interrupted ( )

Emitted when using continue_async, if the time spent evaluating the ink exceeded the alloted time.

prompt_choices ( Array choices )

Emitted when the player should pick a choice. The choices are string values.

choice_made ( String choice )

Emitted when a choice was reported back to the runtime.

function_evaluating ( String function_name, Array arguments )

Emitted when an external function is about to evaluate.

function_evaluated ( String function_name, Array arguments, InkFunctionResult function_result )

Emitted when an external function evaluated.

path_string_choosen ( String path, Array arguments )

Emitted when an external function evaluated.

ended ( )

Emitted when the story ended.

Property Descriptions

Resource ink_file

The compiled ink file (.json) to play. While you can set this property to any resource, it should be an instance of InkResource.

bool loads_in_background

Default

true

When true the story will be created in a separate threads, to prevent the UI from freezing if the story is too big. Note that on platforms where threads aren’t available, the value of this property is ignored.

bool allow_external_function_fallbacks

Default	`true`
Setter	set_aeff(value)
Getter	get_aeff()

true to allow external function fallbacks, false otherwise. If this property is false and the appropriate function hasn’t been binded, the story will output an error.

bool do_not_save_default_values

Default	`true`
Setter	set_dnsdv(value)
Getter	get_dnsdv()

When set to true, inkgd skips saving global values that remain equal to the initial values that were declared in ink. This property matches the static property declared in VariablesState.cs.

bool stop_execution_on_exception

Default	`true`
Setter	set_speoex(value)
Getter	get_speoex()

When set to true, inkgd uses assert() instead of push_error to report exceptions, thus making them more explicit during development.

bool stop_execution_on_error

Default	`true`
Setter	set_speoer(value)
Getter	get_speoer()

When set to true, inkgd uses assert() instead of push_error to report errors, thus making them more explicit during development.

bool story

Default	`null`
Getter	get_can_story()

The underlying story, exposed for convenience. For instance, you may want to create a new InkList, which in certain acses needs a reference to the story to be constructed.

bool can_continue

Default	`false`
Getter	get_can_continue()

true if the story can continue (i. e. is not expecting a choice to be choosen and hasn’t reached the end).

bool async_continue_complete

Default	`false`
Getter	get_async_continue_complete()

If continue_async was called (with milliseconds limit > 0) then this property will return false if the ink evaluation isn’t yet finished, and you need to call it again in order for the continue to fully complete.

String current_text

Default	`""`
Getter	get_current_text()

The content of the current line.

Array current_choices

Default	`""`
Getter	get_current_choices()

The current choices. Empty is there are no choices for the current line.

Array current_tags

Default	`[]`
Getter	get_current_tags()

The current tags. Empty is there are no tags for the current line.

Array global_tags

Default	`[]`
Getter	get_global_tags()

The global tags for the story. Empty if none have been declared.

bool has_choices

Default	`false`
Getter	get_has_choices()

true if the story currently has choices, false otherwise.

bool current_flow_name

Default	`"DEFAULT_FLOW"`
Getter	get_current_flow_name()

The name of the current flow.

bool alive_flow_names

Default	`[]`
Getter	get_alive_flow_names()

The names of all flows currently alive.

bool current_flow_is_default_flow

Default	`true`
Getter	get_current_flow_is_default_flow()

true if the current flow is the default flow.

bool current_current_path

Default	`""`
Getter	get_current_path()

The current story path.

Method Descriptions

void create_story ( )

Creates the story, based on the value of ink_player. The result of this method is reported through loaded.

void reset ( )

Reset the story back to its initial state as it was when it was first constructed.

void destroy ( )

Destroys the current story. Always call this method first if you want to recreate the story.

String continue_story ( )

Continues the story.

String continue_story_async ( )

An “asynchronous” version of continue_story that only partially evaluates the ink, with a budget of a certain time limit. It will exit ink evaluation early if the evaluation isn’t complete within the time limit, with the async_continue_complete property being false. This is useful if the evaluation takes a long time, and you want to distribute it over multiple game frames for smoother animation. If you pass a limit of zero, then it will fully evaluate the ink in the same way as calling continue_story.

To get notified when the evaluation is exited early, you can connect to the interrupted signal.

String continue_story_maximally ( )

Continue the story until the next choice point or until it runs out of content. This is as opposed to continue which only evaluates one line of output at a time.

void choose_choice_index ( int index )

Chooses a choice. If the story is not currently expected choices or the index is out of bounds, this method does nothing.

void choose_path ( String path_string )

Moves the story to the specified knot/stitch/gather. This method will throw an error through exception if the path string does not match any known path.

void switch_flow ( String flow_name )

Switches the flow, creating a new flow if it doesn’t exist.

void switch_to_default_flow ( )

Switches the the default flow.

void remove_flow ( String flow_name )

Remove the given flow.

Array tags_for_content_at_path ( String path )

Returns the tags declared at the given path.

int visit_count_at_path ( String path )

Returns the visit count of the given path.

String get_state ( )

Gets the current state as a JSON string. It can then be saved somewhere.

String copy_state_for_background_thread_save ( )

If you have a large story, and saving state to JSON takes too long for your framerate, you can temporarily freeze a copy of the state for saving on a separate thread. Internally, the engine maintains a “diff patch”. When you’ve finished saving your state, call background_save_complete and that diff patch will be applied, allowing the story to continue in its usual mode.

void background_save_complete ( )

See copy_state_for_background_thread_save. This method releases the “frozen” save state, applying its patch that it was using internally.

void set_state ( String state )

Sets the state from a JSON string.

void save_state_to_path ( String path )

Saves the current state to the given path.

void save_state_to_file ( File file )

Saves the current state to the file.

void load_state_from_path ( String path )

Loads the state from the given path.

void load_state_from_file ( File file )

Loads the state from the given file.

Variant get_variable ( String name )

Returns the value of variable named ‘name’ or ‘null’ if it doesn’t exist.

void set_variable ( String name, Variant value )

Sets the value of variable named ‘name’.

void observe_variables ( Array variable_names, Object object, String method_name )

Registers an observer for the given variables.

void observe_variable ( String variable_name, Object object, String method_name )

Registers an observer for the given variable.

void remove_variable_observer ( Object object, String method_name, String specific_variable_name )

Removes an observer for the given variable name. This method is highly specific and will only remove one observer.

void remove_variable_observer_for_all_variables ( Object object, String method_name )

Removes all observers registered with the couple object/method_name, regardless of which variable they observed.

void remove_all_variable_observers ( String specific_variable_name )

Removes all observers observing the given variable.

void bind_external_function ( String func_name, Object object, String method_name, bool lookahead_safe=false )

Binds an external function.

void unbind_external_function ( String func_name )

Unbinds an external function.

InkFunctionResult evaluate_function ( String function_name, Array arguments )

Evaluate a given ink function, returning both its return value and its text output.

InkList create_ink_list_with_origin ( String origin_list_name, )

Creates a new empty InkList that’s intended to hold items from a particular origin list definition.

InkList create_ink_list_from_item_name ( String item_name, )

Creates a new InkList from the name of a preexisting item.