bow.gd

# BOW!
# ====
# The Arrow runtime in GDScript
# M. H. Golkar [2025, MIT]

## Bow the Arrow runtime in GDScript
## 
## [b]Bow[/b] is the GDScript [b]Arrow[/b] runtime (and minimal dev kit / demo game)
## which can be used to develop narrative software, specially story focused games
## such as Visual Novels, Text & Graphic Adventures, etc. using Godot Engine (v4). [br]
##
## This module provides the core runtime, which is developed as a custom node for Godot. [br][br]
##
## For more information please check [url=https://github.com/mhgolkar/Bow]Bow[/url]
## and [url=https://github.com/mhgolkar/Arrow]Arrow[/url] repositories.

@tool
@icon("res://addons/bow/icon.svg")
extends Node
class_name Bow

## Signals change in the current [member chapter] being in the run.
signal chapter_opened
## Signals change in the [member state] of this runtime.
signal state_updated
## Signals new blocks of view being added to the [member queue] of this runtime.
signal queue_updated
## Signals a recommendation to the terminal/console to skip currently playing segment and try to pull freshly from the queue.
signal force_forward
## Signals end of an instruction chain where no further change has happened.
## In other words this is emitted after a set of instructions being run not ending in other signals.
## It [i]does not[/i] indicate whether the [member queue] is empty or not.
signal eol

@export_group("Chapters")
# ...
@export_subgroup("Listing")
## This property defines chapters list used by this runtime to jump between multiple Arrow documents. [br][br]
## NOTE: It is more common or convenient to provide a [member listing_file]
## and let the runtime to [method relist] chapters on [method begin] call.
@export var chapters_list: ChaptersList
## A file listing the chapters that this runtime should use. [br]
## Expected format is the same as a [i]projects[/i] file generated by Arrow editor. [br][br]
## CAUTION! Changing this property does not automatically update the [member chapters_list].
## You may call [method relist] if the [method begin] is already called.
@export_file("*.project", "*.json", "*.list") var listing_file: String;
## Path to the resource directory where chapter files are placed, that is used to find and read chapters on demand.
@export_dir var documents_dir: String
# ...
@export_subgroup("Entry")
## The first chapter (ID) to be loaded from which we may [method begin] our play. [br]
## Negative values mean to start from the first chapter (i.e. smallest ID) in the list.
## Undefined or wrong chapter IDs would result in error.
@export var entry_chapter: int = -1
## First node to start from when we [method begin] a run from [member entry_chapter] froward.
## Negative values mean to start from the default [code]entry[/code] point of the chapter.
@export var entry_node: int = -1
## Incoming slot of the [member entry_node] to be run. [br][br]
## NOTE: Unless you are using a modified project structure or custom nodes,
## it is just fine to leave it as is, to the `default = [constant DEFAULT_INCOMING_SLOT]`.
@export var entry_slot: int = DEFAULT_INCOMING_SLOT

@export_group("Runtime")
# ...
@export_subgroup("Play")
## Forces state of the game including [member variables] and [member characters] to be cleaned up
## every time we [method begin] a run. It is default behavior, because you are better to use
## Arrow jumps or to [method run] [code]FORWARD[/code] [Bow.Instruction]s
## to move between scenes and nodes even in case of in-game resets if state shall be kept.
@export var reset_state_on_begin: bool = true
# ...
@export_subgroup("Context and Translation")
## The way Bow creates view from chapters, which can be:[br]
## + TEXT where the original (text) content is used in the creation of view controls and voice alts, [br]
## + ID (default) where instead of the original text an identification key respecting the Arrow node's [code]UUID-kind-parameter[/code] is used.[br]
## They both go through the translation (and then exposure) system, and may be used as the keys, but if you plan not to add any translation at all,
## you may prefer [enum Ctx.TEXT] as it would work without any added i18n files.[br]
enum Ctx { ID, TEXT }
## Defines the way content is handled to create views from node,
## whether by using the original TEXT, or by addressing content with a [code]UUID-kind-parameter[/code] ID (for cleaner i18n).
@export var ctx: Ctx = Ctx.ID
## Bow tries to load respective translation files from this path for each one of the [member translation_locales] (or auto-detected ones).
## The placeholders "{lang}" (replaced by each local) and "{chapter}" (replaced by the filename of each chapter) may be used in the path.
## Default value would be fetched from [code]bow/chapters/i18n/path_format[/code] project setting.
@export var translations_path: StringName = ProjectSettings.get_setting_with_override("bow/chapters/i18n/path_format")
## Bow tries to load chapters translation files using [member translations_path] chapter file names and these locale identifiers.
## Leave it empty so the locales be auto-detected from [TranslationServer] respective to your project settings and Preferences.
@export var translation_locales: Array[StringName] = []

## Current loaded chapter ID or Title from the [member chapters_list]
var loaded = null
## Current [member loaded] chapter filename from [member chapters_list] used for asset management, etc.
var loaded_filename = null
## Current loaded chapter
var chapter: Chapter
## Currently open scopes (nested scenes/macros)
var scopes: Array[Scope]
## Current state of the runtime
var state: State
## The queue of [Block]s of [Element]s waiting to be shown to the player
var queue: Queue

## Default slot index used for incoming forwards when no specific value is defined.
const DEFAULT_INCOMING_SLOT: int = 0
## An invalid (non-existent) ID for a next node to which we may forward, resulting in EOL.
const INVALID_NODE_ID: int = -1;

## Extension of the Arrow documents used to create paths from chapter file names.
const ARROW_DOC_EXTENSION := ".arrow"

## Bow & Arrow Node
##
class ArwNode:
	extends Resource
	enum Kind {
		CONDITION, CONTENT, DIALOG, ENTRY, FRAME, GENERATOR, HUB, INTERACTION,
		JUMP, MACRO_USE, MARKER, MONOLOG, RANDOMIZER, SEQUENCER,
		TAG_EDIT, TAG_MATCH, TAG_PASS, USER_INPUT, VARIABLE_UPDATE,
	}
	## ID of the wrapped node
	var id: int
	## Name of the wrapped node
	var name: String
	## The wrapped node
	var node
	## Creates an Arrow node object from a [code]resources.node[id][/code] object of an arrow document dictionary.
	static func from_raw(id: int, node: Dictionary) -> ArwNode:
		var this = ArwNode.new()
		this.id = id
		this.name = node.name
		match node.type:
			"condition":
				this.node = Condition.from_raw(node.data)
			"content":
				this.node = Content.from_raw(node.data)
			"dialog":
				this.node = Dialog.from_raw(node.data)
			"entry":
				this.node = Entry.from_raw(node.data)
			"frame":
				this.node = Frame.from_raw(node.data)
			"generator":
				this.node = Generator.from_raw(node.data)
			"hub":
				this.node = Hub.from_raw(node.data)
			"interaction":
				this.node = Interaction.from_raw(node.data)
			"jump":
				this.node = Jump.from_raw(node.data)
			"macro_use":
				this.node = MacroUse.from_raw(node.data)
			"marker":
				this.node = Marker.from_raw(node.data)
			"monolog":
				this.node = Monolog.from_raw(node.data)
			"randomizer":
				this.node = Randomizer.from_raw(node.data)
			"sequencer":
				this.node = Sequencer.from_raw(node.data)
			"tag_edit":
				this.node = TagEdit.from_raw(node.data)
			"tag_match":
				this.node = TagMatch.from_raw(node.data)
			"tag_pass":
				this.node = TagPass.from_raw(node.data)
			"user_input":
				this.node = UserInput.from_raw(node.data)
			"variable_update":
				this.node = VariableUpdate.from_raw(node.data)
		return this
	## Helps printing the ArwNode resource.
	func _to_string():
		return "ArwNode #%s (%s): %s" % [id, name, node]
	## Plays the wrapped [member node] and returns its instruction.
	## NOTE: Playing a node does not change the runtime. The returned instructions should be used with [method Bow.run] to have an effect.
	func play(map: NodeMap, current: State, ctx: Ctx, slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
		print_debug("• Play { node = %s, map = %s }" % [self, map])
		return self.node.instruct(self.id, map, current, ctx, slot_in)
	# ...
	# ...
	## Arrow Condition Node
	class Condition:
		extends Resource
		const KIND := Kind.CONDITION
		enum PARAMETER_MODE { VALUE = 0, VARIABLE = 1 }
		enum SLOT { FALSE = 0, TRUE = 1 }
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Condition:
			var this = Condition.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Condition %s" % self.data
		# This is a helper used by `evaluate_str_comparison` used when comparing length of two strings,
		# returning parsed integer if the [code]string[/code] is a stringified int otherwise its length.
		static func _length_from(string: String) -> int:
			return int(string) if string == ("%s" % int(string)) else string.length()
		## Compares two values of STR kind with the provided operation.
		## Returns null if the evaluation is not possible (e.g. in case of bad inputs such as unknown operation).
		static func evaluate_str_comparison(left: String, operation: String, right: String):
			var result = null
			match operation:
				"rgx": # Matches RegEx Pattern
					var regex = RegEx.new()
					if ( regex.compile(right) == OK ):
						# RegEx.search() returns RegExMatch if found, otherwise `null`
						result = ( regex.search(left) != null )
				"ct": # Contains Substring
					result = (left.findn(right) >= 0)
				"cts": # Contains Substring (Case-Sensitive)
					result = (left.find(right) >= 0)
				"eql": # Has Equal Length
					result = (left.length() == _length_from(right))
				"lng": # Is Longer
					result = (left.length() > _length_from(right))
				"shr": # Is Shorter
					result = (left.length() < _length_from(right))
				"bgn": # Begins with
					result = left.begins_with(right)
				"end": # Ends with
					result = left.ends_with(right)
			return result
		## Compares two values of NUM kind with the provided operation.
		## Returns null if the evaluation is not possible (e.g. in case of bad inputs such as unknown operation).
		static func evaluate_num_comparison(left: int, operation: String, right: int):
			var result = null
			match operation:
				"eq": # is Equal
					result = ( left == right)
				"nq": # is Not Equal
					result = ( left != right)
				"gt": # is Greater
					result = ( left > right)
				"gte": # is Greater or Equal
					result = ( left >= right)
				"ls": # is Lesser
					result = ( left < right)
				"lse": # is Lesser or Equal
					result = ( left <= right)
			return result
		## Compares two values of BOOL kind with the provided operation.
		## Returns null if the evaluation is not possible (e.g. in case of bad inputs such as unknown operation).
		static func evaluate_bool_comparison(left: bool, operation: String, right: bool):
			var result = null
			match operation:
				"eq":
					result = (left == right)
				"nq":
					result = (left != right)
			return result
		## Returns bool on successful evaluation, otherwise null.
		## It is not supposed to fail for valid nodes and properly initialized state, but if it does, returns null.
		static func evaluate(data: Dictionary, current: Variables):
			var result = null
			if (
				data.has_all(["variable", "operator", "with"]) &&
				data.variable is int && data.variable >= 0 &&
				data.operator is String &&
				data.with is Array && data.with.size() >= 2
			):
				var left_var = current.fetch(data.variable)
				if left_var != null:
					var left = left_var.current_or_initial()
					var operator = data.operator
					var right = null
					match data.with[0]:
						PARAMETER_MODE.VALUE:
							right = data.with[1]
						PARAMETER_MODE.VARIABLE:
							var right_var_id = data.with[1]
							if right_var_id is int:
								if right_var_id == data.variable:
									# compared to itself (by convention the initial value)
									right = left_var.init
								else:
									var right_var = current.fetch(right_var_id)
									if right_var != null:
										right = right_var.current_or_initial()
									else:
										printerr("invalid rhs: variable with ID defined by `data.with[1] = %s` is not initialized")
							else:
								printerr("invalid rhs: `data.with[1] = %s` expected to be var id (int) for the mode `data.with[0] = %s`" % data.with)
						_:
							printerr("unknown parameter mode (i.e. `data.with[0]`)")
					# ...
					if right != null:
						match left_var.kind:
							Variable.Kind.BOOL:
								if left is bool && right is bool:
									result = evaluate_bool_comparison(left, operator, right)
								else:
									printerr("incompatible hands for bool condition operation: ", [left, operator, right])
							Variable.Kind.NUM:
								if (left is int || left is float) && (right is int || right is float):
									left = int(left)
									right = int(right)
									result = evaluate_num_comparison(left, operator, right)
								else:
									printerr("incompatible hands for num condition operation: ", [left, operator, right])
							Variable.Kind.STR:
								if left is String && right is String:
									result = evaluate_str_comparison(left, operator, right)
								else:
									printerr("incompatible hands for str condition operation: ", [left, operator, right])
				else:
					printerr("condition node's target variable is un-initialized: ", data)
			else:
				printerr("condition node does not have valid required properties `variable >= 0`, `operator: string` or `with[mode,rhs]`: ", data)
			return result
		## Runs the node and returns a set to instruct runtime's next steps.
		func instruct(_id: int, map: NodeMap, current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var next: int
			if map.skip:
				next = SLOT.FALSE if map.has_connection(SLOT.FALSE) else SLOT.TRUE
			else:
				next = SLOT.TRUE if evaluate(self.data, current.variables) == true else SLOT.FALSE # if false or null
			return [
				map.forward_with(next)
			]
	# ...
	## Arrow Content Node
	class Content:
		extends Resource
		const KIND := Kind.CONTENT
		const SINGULAR_SLOT_OUT := 0
		const DEFAULT := {
			"title": "", "content": "", # "brief": 0,
			"auto": false, "clear": false,
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Content:
			var this = Content.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Content %s" % self.data
		## Converts a content node to an article element.
		func process(node_id: int, ctx: Ctx) -> Dictionary:
			var content: String; var title: String
			match ctx:
				Ctx.TEXT:
					title = ("%s" % self.data.title) if self.data.has("title") else DEFAULT.title
					content = ("%s" % self.data.content) if self.data.has("content") else DEFAULT.content
				Ctx.ID:
					title = "%s-content-title" % node_id
					content = "%s-content-content" % node_id
			var elements: Array[Element] = [ Element.article(content, title) ]
			var voices: Array[Voice] = [ Voice.new(("%s" % node_id), [title, " ", content]) ]
			return { "elements": elements, "voices": voices }
		## Returns if this content is auto-play or not.
		func is_auto() -> bool:
			return self.data.auto if self.data.has("auto") && self.data.auto is bool else DEFAULT.auto
		## Returns if this content should hint clearing the console before being printed or not.
		func hints_clear() -> bool:
			return self.data.clear if self.data.has("clear") && self.data.clear is bool else DEFAULT.clear
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, _current: State, ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			if map.skip:
				return [next]
			else:
				var processed = self.process(id, ctx)
				var auto_play := self.is_auto()
				if auto_play == false:
					processed.elements.push_back(Element.next([ Instruction.ffw(), next ]))
				var print := Instruction.print([
					Block.new(id, processed.elements, processed.voices, null, self.hints_clear())
				])
				if auto_play:
					return [print, next]
				else:
					return [print]
	# ...
	## Arrow Dialog Node
	class Dialog:
		extends Resource
		const KIND := Kind.DIALOG
		const DEFAULT := {
			"character": -1, # ~ anonymous or unset (hardcoded convention)
			"lines": ["Hey there!"],
			# -- optional(s) --
			"playable": false,
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Dialog:
			var this = Dialog.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Dialog %s" % self.data
		## Returns if this dialog is playable or not (~ automatic for NPC).
		func is_playable() -> bool:
			return self.data.playable if self.data.has("playable") && self.data.playable is bool else DEFAULT.playable
		## Converts lines of dialog to Line elements with user interactivity.
		## NOTE: We extract the mood only from the original chapter lines, so you don't need to keep them in the translations.
		func as_playable(node_id: int, map: NodeMap, character: Character, ctx: Ctx) -> Array[Instruction]:
			var lines = self.data.lines if self.data.has("lines") && self.data.lines is Array else DEFAULT.lines
			var elements: Array[Element]
			for line_index in range(0, lines.size()):
				var line = lines[line_index]
				if line is String && line.length() > 0:
					var text: String
					match ctx:
						Ctx.TEXT:
							text = line
						Ctx.ID:
							text = "%s-dialog-line-%s" % [node_id, line_index]
					var interaction: Array[Instruction] = [ map.forward_with(line_index) ]
					var mood = Element.mood(line)
					var inter_elements: Array[Element]
					if mood != null:
						text = text.trim_prefix(mood.inner.parameters[3])
						inter_elements.push_back(mood)
					var inter_voices: Array[Voice] = [ Voice.new(("%s-%s" % [node_id, line_index]), [character.name, ": ", text]) ]
					interaction.push_front( Instruction.print([ Block.new(node_id, inter_elements, inter_voices, character) ]) )
					elements.push_back( Element.line(text, interaction) )
			var instructions: Array[Instruction] = [ Instruction.print([ Block.new(node_id, elements, [], character) ]) ]
			return instructions
		## Converts a automatically/randomly chosen line of dialog to a Line elements without interactivity, i.e. as if it is already played.
		## NOTE: We extract the mood only from the original chapter lines, so you don't need to keep them in the translations.
		func as_auto(node_id: int, map: NodeMap, character: Character, ctx: Ctx) -> Array[Instruction]:
			var lines = self.data.lines if self.data.has("lines") && self.data.lines is Array else DEFAULT.lines
			var chosen := randi_range(0, lines.size() - 1)
			var next = map.forward_with(chosen)
			var instructions: Array[Instruction] = [next]
			var line = lines[chosen]
			if line is String && line.length() > 0:
				var elements: Array[Element] = []
				var text: String
				match ctx:
					Ctx.TEXT:
						text = line
					Ctx.ID:
						text = "%s-dialog-line-%s" % [node_id, chosen]
				var mood = Element.mood(line)
				if mood != null:
					text = text.trim_prefix(mood.inner.parameters[3])
					elements.push_back(mood)
				elements.push_back( Element.line(text) )
				var voices: Array[Voice] = [ Voice.new(("%s-%s" % [node_id, chosen]), [character.name, ": ", text]) ]
				instructions.push_front( Instruction.print([ Block.new(node_id, elements, voices, character) ]) )
			return instructions
		## Returns character owner of this dialog or anonymous if it's not listed.
		func character(listed: Characters) -> Character:
			var character_id = self.data.character if self.data.has("character") && self.data.character is int else DEFAULT.character
			var found = listed.fetch(character_id)
			if found == null && character_id > -1:
				print_debug("WARN! dialog node with uninitialized character: ", self.data)
			return found if found != null else Character.anonymous()
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, current: State, ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			if map.skip:
				return [ map.forward_with_first() ]
			else:
				var character := self.character(current.characters)
				return as_playable(id, map, character, ctx) if is_playable() else as_auto(id, map, character, ctx)
	# ...
	## Arrow Entry Node
	class Entry:
		extends Resource
		const KIND := Kind.ENTRY
		const SINGULAR_SLOT_OUT := 0
		const DEFAULT := {
			"plaque": "",
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Entry:
			var this = Entry.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Entry %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Entries always forward to their next node, that's their existential duty!
			# If they have "plaque" string being set, they PRINT a Hook as well (before FORWARD),
			# telegraphing the final printer that we are passing a special point in the story.
			var plaque = self.data.plaque if self.data.has("plaque") && self.data.plaque is String else DEFAULT.plaque
			var hook = null if plaque.length() == 0 else Instruction.print([ Block.new(id, [ Element.hook("entry", [plaque]) ]) ])
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			return [next] if hook == null else [hook, next]
	# ...
	## Arrow Frame Node
	class Frame:
		extends Resource
		const KIND := Kind.FRAME
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Frame:
			var this = Frame.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "⚠ Frame %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, _map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Frames are Arrow editor's non-playable nodes designed for visual organization of nodes on its grid.
			printerr("frame nodes (including this one %s) are not supposed to be played! It happens if you have a invalid Jump or mistakenly edited connection." % id, self.data)
			# It is not supposed to be run! We just create an invalid forward to signal an EOL.
			return [ NodeMap.eol() ]
	# ...
	## Arrow Generator Node
	class Generator:
		extends Resource
		const KIND := Kind.GENERATOR
		const SINGULAR_SLOT_OUT := 0
		const VALID_METHODS_FOR_TYPE := {
			Variable.Kind.NUM : [ "randi" ],
			Variable.Kind.STR : [ "ascii", "strst" ],
			Variable.Kind.BOOL: [ "rnbln" ]
		}
		const STRING_SET_DELIMITER := "|"
		const DEFAULT_CHARACTER_POOL := "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUuVvWwXxYyZz123456789"
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Generator:
			var this = Generator.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Generator %s" % self.data
		## Returns an instruction to update the target if everything's fine otherwise null.
		func generate(current: Variables):
			if data.has_all(["variable", "method"]) && data.variable is int:
				var target = current.fetch(data.variable)
				if target is Variable:
					if VALID_METHODS_FOR_TYPE[target.kind].has(data.method):
						var new_value = self.call(
							("generate_%s" % data.method),
							( data.arguments if data.has("arguments") else null)
						)
						if new_value != null:
							return target.reset(new_value)
					else:
						print_debug("generator target is incompatible with the method: ", data)
				else:
					print_debug("generator target is not initialized: ", data)
			else:
				print_debug("generator has not required data fields variable and method: ", data)
			return null
		## Advance (pseudo-) random integer number generator.
		static func _advance_random_integer(from: int = 0, to: int = 0, negative: bool = false, even: bool = false, odd: bool = false) -> int:
			var result = null
			if from >= to:
				result = from
			if (to - from) <= 1:
				# we need at least one odd and one even number in the possibilities
				to += 1
			while result == null:
				result = randi_range(from, to)
				if even != odd : # to be either odd or even
					# (both true or both false means ignore)
					var is_even = (result % 2 == 0)
					if is_even && even == false:
						result = null
					if is_even == false && odd == false:
						result = null
			if negative is bool && negative == true: # negative
				result = (result * (-1))
			# print_debug("_advance_random_integer(", from, to, negative, even, odd, ") -> ", result)
			return result
		## Generates random integer using arguments expected from a Generator node of type [code]randi[/code].
		static func generate_randi(args) -> int:
			var result = null
			if args is Array && args.size() == 5:
				if (
					args[0] is int && args[0] >= 0 &&
					args[1] is int && args[1] >= 1
				):
					result = _advance_random_integer(
						args[0], args[1], # from, to,
						args[2], # negative,
						args[3], args[4] #  even, odd 
					)
				else:
					print_debug("unexpected behavior! bad range for `randi` generator: ", args)
			else:
				print_debug("unexpected behavior! wrong number of arguments for `randi` generator: ", args)
			if result == null:
				result = (randi() % 100) + 1 # so returns even on corrupt arguments
			return result
		## Generates random ASCII string using arguments expected from a Generator node of type [code]ascii[/code].
		static func generate_ascii(args) -> String:
			var result := ""
			if args.size() == 2:
				var char_pool = (args[0] if (args[0] is String && args[0].length() > 0) else DEFAULT_CHARACTER_POOL)
				var pool_size = char_pool.length()
				var desired_length = (args[1] if args[1] is int && args[1] > 0 else pool_size)
				while result.length() < desired_length:
					result = ( result + char_pool.substr( (randi() % pool_size), 1) )
			return result
		## Takes random string from a set using arguments expected from a Generator node of type [code]strst[/code].
		static func generate_strst(stringified_set) -> String:
			var result := ""
			if stringified_set is String && stringified_set.length() > 0:
				var string_set = stringified_set.split(STRING_SET_DELIMITER, false)
				if string_set.size() > 0 :
					result = string_set[ randi() % string_set.size() ]
			return result
		## Generates random boolean for a Generator node of type [code]rnbln[/code].
		static func generate_rnbln() -> bool:
			return ( randi() % 2 == 0 )
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Generator nodes forward to their next node anyway.
			# Of course they first try to update their target, unless skipped or having wrong arguments.
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			if map.skip:
				return [next]
			else:
				var update = self.generate(current.variables)
				if update == null:
					printerr("generator node %s ran to no result (~ due to invalid arguments)!" % id)
					return [next]
				else:
					return [update, next]
	# ...
	## Arrow Hub Node
	class Hub:
		extends Resource
		const KIND := Kind.HUB
		const SINGULAR_SLOT_OUT := 0
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Hub:
			var this = Hub.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Hub %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(_id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Hub nodes are very simple. They merge multiple incoming slots to their only outgoing one.
			# This is the normal behavior even if the node is skipped. No error is expected.
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			return [next]
	# ...
	## Arrow Interaction Node
	class Interaction:
		extends Resource
		const KIND := Kind.INTERACTION
		const DEFAULT := {
			"actions": ["Go ahead!"]
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Interaction:
			var this = Interaction.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Interaction %s" % self.data
		## Converts actions to Line elements.
		func action_elements(node_id: int, map: NodeMap, ctx: Ctx) -> Array[Element]:
			var actions = self.data.actions if self.data.has("actions") && self.data.actions is Array else DEFAULT.actions
			var elements: Array[Element]
			for action_index in range(0, actions.size()):
				var action = actions[action_index]
				if action is String && action.length() > 0:
					var text: String
					match ctx:
						Ctx.TEXT:
							text = action
						Ctx.ID:
							text = "%s-interaction-action-%s" % [node_id, action_index]
					elements.push_back( Element.line(text, [ map.forward_with(action_index) ]) )
			return elements
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, _current: State, ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			if map.skip:
				return [ map.forward_with_first() ]
			else:
				return [ Instruction.print([ Block.new(id, self.action_elements(id, map, ctx)) ])]
	# ...
	## Arrow Jump Node
	class Jump:
		extends Resource
		const KIND := Kind.JUMP
		const DEFAULT := {
			"target": INVALID_NODE_ID,
			"reason": ""
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Jump:
			var this = Jump.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Jump %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Conventionally, skipped and unset jumps are handled as EOL (~ forwarding to INVALID_NODE_ID).
			# Any other destination shall be handled by the runtime (even to non-existing target nodes).
			# If they have "reason" string being set, they PRINT a Hook as well (before FORWARD),
			# telegraphing the final printer that we are passing a special point in the story.
			var target = self.data.target if self.data.has("target") && self.data.target is int else DEFAULT.target
			if map.skip || target <= INVALID_NODE_ID:
				return [ NodeMap.eol() ]
			else:
				var reason = self.data.reason if self.data.has("reason") && self.data.reason is String else DEFAULT.reason
				var hook = null if reason.length() == 0 else Instruction.print([ Block.new(id, [ Element.hook("jump", [target, reason]) ]) ])
				var next := Instruction.forward(target, DEFAULT_INCOMING_SLOT)
				return [next] if hook == null else [hook, next]
	# ...
	## Arrow Macro-Use Node
	class MacroUse:
		extends Resource
		const KIND := Kind.MACRO_USE
		const SINGULAR_SLOT_OUT := 0
		const INVALID_MACRO_ID := -1
		const DEFAULT := {
			"macro": INVALID_MACRO_ID
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> MacroUse:
			var this = MacroUse.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Macro-Use %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(_id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Conventionally, skipped and unset Macro-Use nodes forward their only slot out, as if they immediately resume.
			# Seemingly valid macros will be tried as new scopes, with resume points that shall be handled by the runtime
			# whether valid or not, which may conventionally be treated as immediate closure (similar to skip)
			# for invalid/non-existent scopes or resumes.
			var macro = self.data.macro if self.data.has("macro") && self.data.macro is int else DEFAULT.macro
			if map.skip || macro <= INVALID_MACRO_ID:
				var next := map.forward_with(SINGULAR_SLOT_OUT)
				return [next]
			else:
				var resume_point = map.get_connection(SINGULAR_SLOT_OUT)
				var scope = Instruction.scope(macro, [], [] if resume_point == null else resume_point)
				return [scope]
	# ...
	## Arrow Marker Node
	class Marker:
		extends Resource
		const KIND := Kind.MARKER
		const SINGULAR_SLOT_OUT := 0
		const HOOK_FORMAT_REGEX := r"(.*)\W*\[(.*)\]"
		const HOOK_PARAMS_DELIMITER := "|"
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Marker:
			var this = Marker.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Marker %s" % self.data
		## Returns a Hook if the marker has [code]event[prams|...][/code] format, otherwise null.
		func as_hook():
			if self.data.has("label") && self.data.label is String && self.data.label.length() > 0:
				var regex = RegEx.new()
				var compiled = regex.compile(HOOK_FORMAT_REGEX)
				if compiled == OK:
					var matched = regex.search(self.data.label)
					if matched != null && matched.get_string(0) == self.data.label: # exact pattern found
						var event = matched.get_string(1)
						if event.length() == 0:
							print_debug("WARN! marker hook with blank event detected: ", self.data.label)
						var serialized_joint_params = matched.get_string(2)
						# We need to deserialize and parse non-text params as well:
						var parameters := []
						for param in serialized_joint_params.split(HOOK_PARAMS_DELIMITER):
							var parsed
							match param.to_lower():
								"true":
									parsed = true
								"false":
									parsed = false
								"null":
									parsed = null
								_:
									if param.is_valid_int():
										parsed = param.to_int()
									elif param.is_valid_float():
										parsed = param.to_float()
									else:
										parsed = param
							parameters.push_back(parsed)
						# Conventionally, we pass the marker color if defined as the last parameter as well:
						if self.data.has("color") && self.data.color.is_valid_html_color():
							parameters.push_back(Color.html(self.data.color))
						# ...
						return Element.hook(event, parameters)
				else:
					printerr("unexpected behavior! HOOK_FORMAT_REGEX is supposed to always compile to valid regex!")
			else:
				print_debug("NOTE! marker with no label (or blank) is running. skip it if color only")
			return null
		## Runs the node and returns a set to instruct runtime moving forward.[br]
		## Markers are commonly used to log info on the Arrow project's (editor) grid,
		## so in runtime they print a debug message and pass to their next node even skipped.[br]
		## Bow runtime has an additional behavior though, for an special kind of markers called Hook Markers.
		## Any marker with a label of [code]event[prams|...][/code], if not skipped, will PRINT a respective [Bow.Element.Hook].
		## This allows uses of marker nodes to call gameplay functions from dot-arrow documents by interpreting hooks as serialized method calls.[br]
		## Color of the marker if defined in the data will be passed as the last parameter.[br]
		## NOTE: Parameters are split by [code]|[/code] (pipe) and empty is also allowed, so your event (method) can accepts them,
		## which means you should be extra careful about double pipes. Note also that blank events may be supported but are not recommended.
		func instruct(id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var hook = null if map.skip else self.as_hook()
			var print = null if hook == null else Instruction.print([ Block.new(id, [hook]) ])
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			return [next] if print == null else [print, next]
	# ...
	## Arrow Monolog Node
	class Monolog:
		extends Resource
		const KIND := Kind.MONOLOG
		const SINGULAR_SLOT_OUT := 0
		const DEFAULT := {
			"character": -1, # ~ anonymous or unset (hardcoded convention)
			"monolog": "",
			# -- optional(s) --
			# "brief": 0,
			"auto": false,
			"clear": false,
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Monolog:
			var this = Monolog.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Monolog %s" % self.data
		## Converts a monolog node to the respective elements (including an article and a possible mood) and respective voices.
		## NOTE: We extract the mood only from the original chapter monolog, so you don't need to keep them in the translations.
		func process(node_id: int, character: Character, ctx: Ctx) -> Dictionary:
			var monolog: String = ("%s" % self.data.monolog) if self.data.has("monolog") else DEFAULT.monolog
			var text: String
			match ctx:
				Ctx.TEXT:
					text = monolog
				Ctx.ID:
					text = "%s-monolog-monolog" % node_id
			var mood = Element.mood(monolog)
			if mood != null:
				text = text.trim_prefix(mood.inner.parameters[3])
			var elements: Array[Element] = [ Element.article(text) ]
			if mood != null:
				elements.push_front(mood)
			var voices: Array[Voice] = [ Voice.new(("%s" % node_id), [character.name, ": ", text]) ]
			return { "elements": elements, "voices": voices }
		## Returns if this monolog is auto-play or not.
		func is_auto() -> bool:
			return self.data.auto if self.data.has("auto") && self.data.auto is bool else DEFAULT.auto
		## Returns if this monolog should hint clearing the console before being printed or not.
		func hints_clear() -> bool:
			return self.data.clear if self.data.has("clear") && self.data.clear is bool else DEFAULT.clear
		## Returns character owner of this monolog or anonymous if it's not listed.
		func character(listed: Characters) -> Character:
			var character_id = self.data.character if self.data.has("character") && self.data.character is int else DEFAULT.character
			var found = listed.fetch(character_id)
			if found == null && character_id > -1:
				print_debug("WARN! monolog node with uninitialized character: ", self.data)
			return found if found != null else Character.anonymous()
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, current: State, ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			if map.skip:
				return [next]
			else:
				var character := self.character(current.characters)
				var processed := self.process(id, character, ctx)
				var auto_play := self.is_auto()
				if auto_play == false:
					processed.elements.push_back(Element.next([ Instruction.ffw(), next ]))
				var print := Instruction.print([
					Block.new(
						id,
						processed.elements, processed.voices,
						character,
						self.hints_clear()
					)
				])
				if auto_play:
					return [print, next]
				else:
					return [print]
	# ...
	## Arrow Randomizer Node
	class Randomizer:
		extends Resource
		const KIND := Kind.RANDOMIZER
		const MINIMUM_ACCEPTABLE_OUT_SLOTS := 2
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Randomizer:
			var this = Randomizer.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Randomizer %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(_id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Randomizer nodes are very simple. They dispatch incoming connection(s) (slot or jump)
			# to one of their outgoing slots randomly chosen. This is the normal behavior even if the node is skipped.
			# It is their destiny! Even if there are disconnected slots, they may forward to them, so to an EOL.
			var slots = self.data.slots if self.data.has("slots") else MINIMUM_ACCEPTABLE_OUT_SLOTS
			var next = map.forward_with(randi_range(0, slots - 1))
			return [next]
	# ...
	## Arrow Sequencer Node
	class Sequencer:
		extends Resource
		const KIND := Kind.SEQUENCER
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> Sequencer:
			var this = Sequencer.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Sequencer %s" % self.data
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(_id: int, map: NodeMap, _current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			if map.skip:
				return [ map.forward_with_last() ]
			else:
				var sequence := map.forward_all()
				return sequence if sequence.size() > 0 else [ NodeMap.eol() ]
	# ...
	## Arrow Tag-Edit Node
	class TagEdit:
		extends Resource
		const KIND := Kind.TAG_EDIT
		const SINGULAR_SLOT_OUT := 0
		enum METHOD {
			INSET = 0,
			RESET = 1,
			OVERSET = 2,
			OUTSET = 3,
			UNSET = 4,
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> TagEdit:
			var this = TagEdit.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Tag-Edit %s" % self.data
		## Creates an updater respective to the inner value if valid, otherwise null.
		func update(current: Characters):
			if data.has_all(["character", "edit"]) && data.character is int && data.edit is Array && data.edit.size() == 3:
				var target = current.fetch(data.character)
				if target is Character:
					var method = data.edit[0]
					var name = data.edit[1] if data.edit[1] is String else ""
					var value = data.edit[2] if data.edit[2] is String else ""
					if name.length() > 0:
						match method:
							METHOD.INSET: # Adds a key:value tag, only if the key does not exist
								if target.tags.has(name) == false:
									return target.reset_tag(name, value)
							METHOD.RESET: # Resets value of a tag, only if the key exists
								if target.tags.has(name) == true:
									return target.reset_tag(name, value)
							METHOD.OVERSET: # Overwrites or adds a key:value tag, whether the key exists or not
								return target.reset_tag(name, value)
							METHOD.OUTSET: # Removes a tag if both key & value match
								if target.tags.has(name) == true && target.tags[name] == value:
									return target.drop_tag(name)
							METHOD.UNSET: # Removes a tag if just the key matches
								if target.tags.has(name) == true:
									return target.drop_tag(name)
							_:
								print_debug("tag-edit method (data.edit[0]) is unsupported: ", data)
					else:
						print_debug("tag-edit edit key (data.edit[1]) is blank or non-string: ", data)
				else:
					print_debug("tag-edit target is not initialized: ", data)
			else:
				print_debug("tag-edit has not required data fields character and edit: ", data)
			return null
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			# Tag-Edit nodes forward to their next node anyway.
			# Of course they first try to update their target, unless skipped or having wrong arguments.
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			if map.skip:
				return [next]
			else:
				var update = self.update(current.characters)
				if update == null:
					printerr("tag-edit node %s ran with no real update (~ due to invalid arguments)!" % id)
					return [next]
				else:
					return [update, next]
	# ...
	## Arrow Tag-Match Node
	class TagMatch:
		extends Resource
		const KIND := Kind.TAG_MATCH
		const DEFAULT := {
			"character": -1, # ~ anonymous or unset (hardcoded convention)
			"tag_key": "", # tag keys can not be blank
			"patterns": [""],
			# -- optional(s) --
			"regex": false,
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> TagMatch:
			var this = TagMatch.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Tag-Match %s" % self.data		
		## Returns index of the matching pattern or null.[br]
		## There will naturally be no matching, for keys that does not exist,
		## patterns that are not String, or any other unexpected value.
		static func _find_matching(tags: Dictionary, tag_key: String, patterns: Array, use_regex: bool):
			if tag_key.length() > 0:
				if tags.has(tag_key) && tags[tag_key] is String:
					var tag_value = tags[tag_key]
					for index in range(0, patterns.size()):
						var pattern = patterns[index]
						if pattern is String:
							if use_regex:
								var regex = RegEx.new()
								if ( regex.compile(pattern) == OK ):
									if regex.search(tag_value) != null:
										return index
							else:
								if tag_value == pattern:
									return index
						else:
							print_debug("tag-match `_find_matching` with non-string pattern %s in " % pattern, patterns)
			else:
				print_debug("tag-match trying to `_find_matching` with blank tag key!")
			return null
		## Returns slot index for the matching pattern or null.
		func matching(current: Characters):
			var character_id = self.data.character if self.data.has("character") && self.data.character is int else DEFAULT.character
			var character = current.fetch(character_id)
			if character is Character:
				return _find_matching(
					character.tags,
					self.data.tag_key if self.data.has("tag_key") && self.data.tag_key is String else DEFAULT.tag_key,
					self.data.patterns if self.data.has("patterns") && self.data.patterns is Array else DEFAULT.patterns,
					self.data.regex if self.data.has("regex") && self.data.regex is bool else DEFAULT.regex,
				)
			else:
				print_debug("tag-match character is not initialized: ", data)
			return null
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(_id: int, map: NodeMap, current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			if map.skip:
				return [ map.forward_with_first() ]
			else:
				var matching = self.matching(current.characters)
				return [ map.forward_with(matching) if matching is int else NodeMap.eol() ]
	# ...
	## Arrow Tag-Pass Node
	class TagPass:
		extends Resource
		const KIND := Kind.TAG_PASS
		enum SLOT { FALSE = 0, TRUE = 1 }
		enum METHOD {
			ANY = 0,
			ALL = 1,
		}
		const DEFAULT := {
			"character": -1, # ~ invalid anonymous unset (hardcoded convention)
			"pass": [ METHOD.ALL, [ ["", null] ] ], # (it's safe; invalid tags are ignored)
			# Note: Value of `null` means to check for key only; but blank value ("") means normal check for both key and value.
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> TagPass:
			var this = TagPass.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Tag-Pass %s" % self.data
		## Returns if a pass check entity is valid.		
		static func _is_valid(check) -> bool:
			return (
				check is Array && check.size() >= 1 && # at least a key
				check[0] is String && check[0].length() > 0 && # valid key
				(check.size() == 1 || check[1] == null || check[1] is String) # valid value (including unchecked)
			)
		## Evaluates this tag-pass against current state of characters.
		func evaluate(current: Characters) -> bool:
			var shall_pass := false
			if self.data.has_all(["character", "pass"]) && self.data.character is int && self.data.pass is Array && self.data.pass.size() == 2:
				var character = current.fetch(self.data.character)
				if character is Character:
					var method = self.data.pass[0]
					if method == METHOD.ANY || method == METHOD.ALL:
						var checks = self.data.pass[1]
						if checks is Array:
							for check in self.data.pass[1]:
								if _is_valid(check):
									shall_pass = (
										character.tags.has( check[0] ) &&
										( check.size() == 1 || check[1] == null || check[1] == character.tags[check[0]] )
									)
									if method == METHOD.ANY && shall_pass == true:
										break
									if method == METHOD.ALL && shall_pass == false:
										break
								else:
									print_debug("tag-pass includes invalid check: ", check)
						else:
							print_debug("tag-pass expects check array (data.pass[1]) but has: ", checks)
					else:
						print_debug("tag-pass method (data.pass[0] = %s) is not supported! " % method, data)
				else:
					print_debug("tag-pass character is not initialized: ", data)
			else:
				print_debug("tag-pass does not have expected character and pass data: ", data)
			return shall_pass
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(_id: int, map: NodeMap, current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var next: int
			if map.skip:
				next = SLOT.FALSE if map.has_connection(SLOT.FALSE) else SLOT.TRUE
			else:
				next = SLOT.TRUE if evaluate(current.characters) == true else SLOT.FALSE
			return [
				map.forward_with(next)
			]
	# ...
	## Arrow User-Input Node
	class UserInput:
		extends Resource
		const KIND := Kind.USER_INPUT
		const SINGULAR_SLOT_OUT := 0
		const DEFAULT := {
			"prompt": "",
			"variable": -1,
			"custom": [],
		}
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> UserInput:
			var this = UserInput.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "User-Input %s" % self.data
		## Creates and returns a Prompt element based on the inner [member data] or returns null if something is wrong.
		func process(node_id: int, with: State, ctx: Ctx, next: Instruction):
			var variable_id: int = self.data.variable if self.data.has("variable") && self.data.variable is int else DEFAULT.variable
			var variable = with.variables.fetch(variable_id)
			if variable is Variable:
				var def: Array = self.data.custom if self.data.has("custom") && self.data.custom is Array else DEFAULT.custom
				# Console & runtime codes may depend on the order of elements in `custom` property to run. That is per variable type:
				# + bool: [negative, positive, default-state] (two strings and a boolean)
				# + num: [min, max, step, default-value] (all integers)
				# + str: [pattern, default, extra-hint] (all strings)
				var input = null
				match variable.kind:
					Variable.Kind.BOOL:
						if def.size() == 3 && def[0] is String && def[1] is String && def[2] is bool:
							var negative = def[0] if ctx == Ctx.TEXT else "%s-user_input-custom-negative" % node_id
							var positive = def[1] if ctx == Ctx.TEXT else "%s-user_input-custom-positive" % node_id
							input = Element.Prompt.BooleanInput.new(negative, positive, def[2])
						else:
							print_debug("user-input `custom` definition is not compatible with the target variable %s of kind BOOL expecting [negative, positive, default-state] (two strings and a boolean) " % variable.id , data)
					Variable.Kind.NUM:
						if def.size() == 4 && ((def[0] is int || def[0] is float) && (def[1] is int || def[1] is float) && (def[2] is int || def[2] is float) && (def[3] is int || def[3] is float)):
							input = Element.Prompt.NumberInput.new(def[0], def[1], def[2], def[3])
						else:
							print_debug("user-input `custom` definition is not compatible with the target variable %s of kind NUM expecting [min, max, step, default-value] (all integers) " % variable.id , data)
					Variable.Kind.STR:
						if def.size() == 3 && def[0] is String && def[1] is String && def[2] is String:
							# DEV: Default values are not UI/UX info, so we don't translate them.
							# var default = def[1] if ctx == Ctx.TEXT else "%s-user_input-custom-default" % node_id
							var extra = def[2] if ctx == Ctx.TEXT else "%s-user_input-custom-extra" % node_id
							input = Element.Prompt.TextInput.new(def[0], def[1], extra)
						print_debug("user-input `custom` definition is not compatible with the target variable %s of kind STR expecting [pattern, default, extra-hint] (all strings) " % variable.id , data)
				if input != null:
					var prompt = self.data.prompt if self.data.has("prompt") && self.data.prompt is String else DEFAULT.prompt
					var question: String
					match ctx:
						Ctx.TEXT:
							question = prompt
						Ctx.ID:
							question = "%s-user_input-prompt" % node_id
					var voices: Array[Voice] = [ Voice.new(("%s" % node_id), [question]) ]
					var elements: Array[Element] = [ Element.prompt(input, variable.id, question, [next]) ]
					return { "elements": elements, "voices": voices }
			return null
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, current: State, ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			if map.skip:
				return [next]
			else:
				var processed = self.process(id, current, ctx, next)
				if processed == null:
					printerr("unable to create prompt for user input %s; the node skipped/ignored" % id)
					return [next]
				else:
					return [ Instruction.print([ Block.new(id, processed.elements, processed.voices) ]) ]
	# ...
	## Arrow Variable-Update Node
	class VariableUpdate:
		extends Resource
		const KIND := Kind.VARIABLE_UPDATE
		const SINGULAR_SLOT_OUT := 0
		enum PARAMETER_MODE { VALUE = 0, VARIABLE = 1 }
		## This node's raw data as defined in the Arrow document
		var data
		## Creates a node from raw [code]data[/code] of an Arrow node resource.
		static func from_raw(data: Dictionary) -> VariableUpdate:
			var this = VariableUpdate.new()
			this.data = data
			return this
		## Helps printing this built-in node resource.
		func _to_string():
			return "Variable-Update %s" % self.data
		## Evaluates a numeral operation to create a new value. Returns null if operation is not supported.
		static func evaluate_num_update(left: int, operation: String, right: int):
			var result = null # updates `left` by ...
			match operation:
				"set": # Set Equal (=)
					result = right
				"add": # Addition (+=)
					result = (left + right)
				"sub": # Subtraction (-=)
					result = (left - right)
				"div": # Division (/=)
					if right != 0: # no support for infinity
						# warning-ignore:integer_division
						result = int( floor(left / right) )
				"rem": # Remainder (%=)
					if right != 0: # no support for NAN
						result = (left % right)
				"mul": # Multiplication (*=)
					result = (left * right)
				"exp": # Exponentiation (^=)
					result = pow(left, right)
				"abs": # Absolute (=||)
					result = abs(right)
			return (
				# ... and rounds to the nearest whole number (e.g. 2.9 -> 3 not truncated 2)
				int ( round ( result ) )
				if result != null
				else null
			)
		## Evaluates a string operation to create a new value. Returns null if operation is not supported.
		static func evaluate_str_update(left: String, operation: String, right: String):
			var result = null # updates `left` by ...
			match operation:
				"set": # Set (=)
					result = right
				"stc": # Set Capitalized (C=)
					result = right.capitalize()
				"stl": # Set Lower-cased (l=)
					result = right.to_lower()
				"stu": # Set Upper-cased (u=)
					result = right.to_upper()
				"ins": # Insert Right (=+)
					result = ( left + right )
				"inb": # Insert Left (+=)
					result = ( right + left )
				"rmc": # Remove Left (-=)
					var rem_idx = left.find(right)
					if rem_idx >= 0:
						result = left.substr(0, rem_idx) + left.substr((rem_idx + right.length()), -1)
					else:
						result = left
				"rml": # Remove Left _Case Insensitive_ (-~)
					var rem_idx = left.findn(right)
					if rem_idx >= 0:
						result = left.substr(0, rem_idx) + left.substr((rem_idx + right.length()), -1)
					else:
						result = left
				"rmr": # Remove Right (=-)
					var rem_idx = left.rfind(right)
					if rem_idx >= 0:
						result = left.substr(0, rem_idx) + left.substr((rem_idx + right.length()), -1)
					else:
						result = left
				"rmi": # Remove Right _Case Insensitive_ (~-)
					var rem_idx = left.rfindn(right)
					if rem_idx >= 0:
						result = left.substr(0, rem_idx) + left.substr((rem_idx + right.length()), -1)
					else:
						result = left
				"rpl": # Replace (=*)	
					var replacement = right.split("|")
					if replacement.size() == 1: # consider it a replace with blank (ie. "" ~ remove all)
						replacement.append("")
					result = left.replace(replacement[0], replacement[1])
				"rpi": # Replace _Case Insensitive_ (~*)
					var replacement = right.split("|")
					if replacement.size() == 1: # consider it a replace with blank (ie. "" ~ remove all)
						replacement.append("")
					result = left.replacen(replacement[0], replacement[1])
			return result
		## Evaluates a boolean operation to create a new value. Returns null if operation is not supported.
		static func evaluate_bool_update(left: bool, operation: String, right: bool):
			var result = null # updates `left` by ...
			match operation:
				"set": # Set (=)
					result = right
				"neg": # Set Negative (=!)
					result = ( ! right )
			return result
		## Returns updater instruction on successful evaluation, otherwise null.
		## It is not supposed to fail for valid nodes and properly initialized state, but if it does, returns null.
		static func evaluate_update(data: Dictionary, current: Variables):
			if (
				data.has_all(["variable", "operator", "with"]) &&
				data.variable is int && data.variable >= 0 &&
				data.operator is String &&
				data.with is Array && data.with.size() >= 2
			):
				var left_var = current.fetch(data.variable)
				if left_var != null:
					var left = left_var.current_or_initial()
					var operator = data.operator
					var right = null
					match data.with[0]:
						PARAMETER_MODE.VALUE:
							right = data.with[1]
						PARAMETER_MODE.VARIABLE:
							var right_var_id = data.with[1]
							if right_var_id is int:
								if right_var_id == data.variable:
									# compared to itself (by convention the initial value)
									right = left_var.init
								else:
									var right_var = current.fetch(right_var_id)
									if right_var != null:
										right = right_var.current_or_initial()
									else:
										printerr("invalid rhs: variable with ID defined by `data.with[1] = %s` is not initialized")
							else:
								printerr("invalid rhs: `data.with[1] = %s` expected to be var id (int) for the mode `data.with[0] = %s`" % data.with)
						_:
							printerr("unknown parameter mode (i.e. `data.with[0]`)")
					# ...
					if right != null:
						var new_value = null
						match left_var.kind:
							Variable.Kind.BOOL:
								if left is bool && right is bool:
									new_value = evaluate_bool_update(left, operator, right)
								else:
									printerr("incompatible hands for bool variable update operation: ", [left, operator, right])
							Variable.Kind.NUM:
								if (left is int || left is float) && (right is int || right is float):
									left = int(left)
									right = int(right)
									new_value = evaluate_num_update(left, operator, right)
								else:
									printerr("incompatible hands for num variable update operation: ", [left, operator, right])
							Variable.Kind.STR:
								if left is String && right is String:
									new_value = evaluate_str_update(left, operator, right)
								else:
									printerr("incompatible hands for str variable update operation: ", [left, operator, right])
						if new_value != null:
							return left_var.reset(new_value)
				else:
					printerr("variable-update node's target variable is un-initialized: ", data)
			else:
				printerr("variable-update node does not have valid required properties `variable >= 0`, `operator: string` or `with[mode,rhs]`: ", data)
			return null
		## Runs the node and returns a set to instruct runtime moving forward.
		func instruct(id: int, map: NodeMap, current: State, _ctx: Ctx, _slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
			var next := map.forward_with(SINGULAR_SLOT_OUT)
			if map.skip:
				return [next]
			else:
				var update = self.evaluate_update(self.data, current.variables)
				if update == null:
					printerr("unable to evaluate new value and updater for variable-update %s; the node skipped/ignored with no update" % id)
					return [next]
				else:
					return [update, next]

## Bow & Arrow Nodes Collection
##
## This type is chiefly used to manage chapter nodes.
class ArwNodes:
	extends Resource
	var _collection: Dictionary
	## Creates Arrow Nodes resource collection from [code]resources.nodes[/code] part of an arrow document dictionary.
	static func from_raw(nodes: Dictionary) -> ArwNodes:
		var this = ArwNodes.new()
		for node_id in nodes:
			this._collection[node_id] = ArwNode.from_raw(node_id, nodes[node_id])
		return this
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "ArwNodes %s" % _collection
	## Returns node listed with the provided ID (int) or name (string), or null if not listed.
	## This method short-circuits, so in case there are duplicates the first one will be returned.
	## Note that nodes with identical IDs are not possible and duplicate names are not allowed by Arrow editor normally.
	func fetch(id_or_name):
		if id_or_name is int && self._collection.has(id_or_name):
			return self._collection[id_or_name]
		elif id_or_name is String:
			for id in self._collection:
				if self._collection[id].name == id_or_name:
					return self._collection[id]
		return null

## Bow & Arrow Node (IO) Map
##
class NodeMap:
	extends Resource
	## ID of the node to which this map belongs.
	var id: int
	## Defines if the respective node shall be played or skipped.
	var skip: bool
	## Represents connections of the respective nodes by the outgoing slot index mapped to an array of the next node ID and its incoming slot.
	var io: Dictionary # { outgoing-slot<int>: [next-node-id<int>, next-node-incoming slot<int>] }
	## Creates an Arrow node object from a [code]resources.scenes[scene-id].map[node-id][/code] part of an arrow document dictionary.
	static func from_raw(id: int, node_map: Dictionary) -> NodeMap:
		var this = NodeMap.new()
		this.id = id
		this.skip = node_map.skip if node_map.has("skip") else false
		if node_map.has("io") && node_map.io is Array:
			for io in node_map.io:
				var destination: Array[int] = [
					int(io[2]), # The next node's ID
					int(io[3]), # The next node's incoming slot
				]
				this.io[
					int(io[1]) # Outgoing slot of this node
				] = destination
		return this
	## Helps printing this NodeMap resource.
	func _to_string():
		return "NodeMap { for = %s, skip = %s, io = %s }" % [id, skip, io]
	## Returns if this node map has connection on the provided outgoing slot.
	## It *does not* check if the connection is to a valid destination or not; but in general,
	## for valid projects created using Arrow editor, existing connections are expected to be valid,
	## thanks to continuum safety measures of the editor.
	func has_connection(slot_out: int) -> bool:
		return io.has(slot_out)
	## Returns destination [node Id, and its slot in] for a slot out if connected, otherwise null.
	func get_connection(slot_out: int):
		return io[slot_out] if io.has(slot_out) else null
	## Creates a FORWARD [Instruction] but unlike [method forward_with] returns null if there is no such connection.
	func forward_if(slot_out: int):
		if io.has(slot_out):
			var connection = io[slot_out]
			return Instruction.forward(connection[0], connection[1])
		else:
			return null
	## Creates a FORWARD [Instruction] if there is such a connection or an invalid/null destination to result in EOL.
	func forward_with(slot_out: int) -> Instruction:
		var connection = io[slot_out] if io.has(slot_out) else [INVALID_NODE_ID, DEFAULT_INCOMING_SLOT]
		return Instruction.forward(connection[0], connection[1])
	## Creates a FORWARD [Instruction] with the first connection in order of slots, even to an invalid/null destination which may result in EOL.
	func forward_with_first() -> Instruction:
		if io.is_empty():
			return NodeMap.eol()
		else:
			var first = io[ io.keys().min() ]
			return Instruction.forward(first[0], first[1])
	## Creates a FORWARD [Instruction] with the last connection in order of slots, even to an invalid/null destination which may result in EOL.
	func forward_with_last() -> Instruction:
		if io.is_empty():
			return NodeMap.eol()
		else:
			var last = io[ io.keys().max() ]
			return Instruction.forward(last[0], last[1])
	## Creates a FORWARD [Instruction] with all the connections in order of slots.
	## Returns blank array if no connection exists.
	func forward_all() -> Array: # Array[Instruction]
		var all := [] # Array[Instruction]
		for slot in io:
			var connection = io[slot]
			all.push_back(Instruction.forward(connection[0], connection[1]))
		return all
	## Returns a FORWARD to invalid (non-existent) node and slot, so an EOL.
	static func eol() -> Instruction:
		return Instruction.forward(INVALID_NODE_ID, DEFAULT_INCOMING_SLOT)

## Bow & Arrow Scene
##
## Represents an Arrow scene (or macro).
class Scene:
	extends Resource
	## ID of this scene
	var id: int
	## Title of this scene
	var name: String
	## Defines entry point of this scene which is expected to be a node ID in the scene.
	var entry: int
	## Represents node mapping of this scene defining node connections and if they are active.
	var map: Dictionary # { node-id<int>: NodeMap }
	## Defines if the scene is a macro and may be played nested as a new scope.
	var macro: bool
	## Creates an Arrow scene object from a [code]resources.scenes[id][/code] part of an arrow document dictionary.
	static func from_raw(id: int, scene: Dictionary) -> Scene:
		var this = Scene.new()
		this.id = id
		this.name = scene.name
		this.entry = scene.entry
		this.macro = scene.macro if scene.has("macro") else false
		for node_id in scene.map:
			this.map[node_id] = NodeMap.from_raw(node_id, scene.map[node_id])
		return this
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "Scene { id = %s, name = %s, entry = %s, map = %s, macro = %s }" % [id, name, entry, map, macro]
	## Returns if this scene has any node with the provided ID.
	func has_node(id: int) -> bool:
		return self.map.has(id)
	## Returns connection map if there is such data charted for the node.
	func chart(node: int):
		if self.map.has(node):
			return self.map[node]
		return null

## Bow & Arrow Scenes Collection
##
## This type is chiefly used to manage chapter scenes.
class Scenes:
	extends Resource
	var _collection: Dictionary
	## Creates Scenes resource collection from [code]resources.scenes[/code] part of an arrow document dictionary.
	static func from_raw(scenes: Dictionary) -> Scenes:
		var this = Scenes.new()
		for scene_id in scenes:
			this._collection[scene_id] = Scene.from_raw(scene_id, scenes[scene_id])
		return this
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "Scenes %s" % _collection
	## Returns scene listed with the provided ID (int) or name (string), or null if not listed.
	## This method short-circuits, so in case there are duplicates the first one will be returned.
	## Note that scenes with identical IDs are not possible and duplicate names are not allowed by Arrow editor normally.
	func fetch(id_or_name):
		if id_or_name is int && self._collection.has(id_or_name):
			return self._collection[id_or_name]
		elif id_or_name is String:
			for id in self._collection:
				if self._collection[id].name == id_or_name:
					return self._collection[id]
		return null
	## Returns the scene that holds the node by ID, otherwise null.
	func locate(node: int):
		for scene_id in self._collection:
			if self._collection[scene_id].has_node(node):
				return self._collection[scene_id]
		return null

## Bow & Arrow Variable
##
## This class represents an Arrow variable and tracks its current value if it is loaded in the [member Bow.variables] state.
class Variable:
	extends Resource
	enum Kind { BOOL, NUM, STR }
	## ID of this variable
	var id: int
	## Defines type of the variable being boolean, number or string.
	var kind: Kind
	## Name of the variable as defined in the chapter (which first loaded this variable into the state)
	var name: String
	## Initial value of this variable which is not expected to be null.
	var init
	## Tracks current value of the variable if it is manipulated as part of the state otherwise null.
	var value
	## Creates an Arrow variable object from a [code]resources.variables[id][/code] part of an arrow document dictionary.
	## CAUTION: This function does not check if the value (current or initial) complies with the defined [enum Kind].
	static func from_raw(id: int, variable: Dictionary, with_current_value = null) -> Variable:
		var this = Variable.new()
		this.id = id
		this.name = variable.name
		this.init = variable.init
		this.value = with_current_value
		match variable.type:
			"bool":
				this.kind = Kind.BOOL
			"num":
				this.kind = Kind.NUM
			"str":
				this.kind = Kind.STR
		return this
	## Serializes the Variable to basic Godot types.
	func pack() -> Dictionary:
		return { "id": self.id, "name": self.name, "init": self.init, "value": self.value, "type": self.kind_str() }
	## Deserializes a Variable from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Variable:
		return Variable.from_raw(from.id, from, from.value)
	## Returns [member kind] as an string similar to the Arrow type definition for variables.
	func kind_str() -> String:
		var str = "invalid"
		match self.kind:
			Kind.BOOL:
				str = "bool"
			Kind.NUM:
				str = "num"
			Kind.STR:
				str = "str"
		return str
	## Helps printing the Variable resource.
	func _to_string():
		return "Variable { id = %s, name = %s, init = %s, value = %s, type = %s }" % [ id, name, init, value, kind_str() ]
	## Returns current value of the variable or its initial value if current is null.
	func current_or_initial() -> Variant:
		return self.init if self.value == null else self.value
	## Creates an instruction to reset value for this variable.
	func reset(new_value) -> Instruction:
		return Instruction.manage( State.Update.variable( Variables.Update.reset(self.id, new_value) ) )

## Bow & Arrow Variables Collection
##
## It is chiefly used to construct game [member Bow.variables] state or to represent chapter Resources.
class Variables:
	extends Resource
	var _collection: Dictionary # { id<int>: variable }
	## Creates Variables resource collection from [code]resources.variables[/code] part of an arrow document dictionary.
	## CAUTION: This function does not check if the values (current or initial) are complying with the defined kinds.
	static func from_raw(variables: Dictionary) -> Variables:
		var this = Variables.new()
		for variable_id in variables:
			this._collection[variable_id] = Variable.from_raw(variable_id, variables[variable_id])
		return this
	## Serializes Variables to basic Godot types.
	func pack() -> Dictionary:
		var packed = {}
		for var_id in self._collection:
			packed[var_id] = self._collection[var_id].pack()
		return packed
	## Deserializes Variables from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Variables:
		var new = Variables.new()
		for var_id in from:
			new._collection[var_id] = Variable.unpack(from[var_id])
		return new
	## Helps printing the Variables resource.
	func _to_string():
		return "Variables %s" % _collection
	## Enlists each Variable from the [code]other[/code] collection that is not initialized already.
	func refill_with(other: Variables) -> void:
		for id in other._collection:
			if self._collection.has(id) == false:
				self._collection[id] = other._collection[id]
	## Inserts a Variable into the collection if forced or not already initialized.
	## Returns the replaced variable or null (when not forced or totally new).
	func insert(id: int, variable: Variable, forced: bool = false):
		assert(id == variable.id)
		var replacing = self._collection[id] if self._collection.has(id) else null
		if forced || replacing == null:
			self._collection[id] = variable
			return replacing
		else:
			return null
	## Returns a listed variable or null by ID or name.
	## This method short-circuits, so in case there are duplicates the first one will be returned.
	## Note that variables with identical IDs are not possible and duplicate names are not allowed by Arrow editor normally.
	func fetch(id_or_name):
		if id_or_name is int && self._collection.has(id_or_name):
			return self._collection[id_or_name]
		elif id_or_name is String:
			for id in self._collection:
				if self._collection[id].name == id_or_name:
					return self._collection[id]
		return null
	## This is an internal method, specially used to sync Preferences as chapter variables.
	## It will immediately replace value of any variable known by the provided ID or name and works aggressively.
	## It returns updated Variables.
	func _force_reset_value(var_id_or_name, value) -> Array[Variable]:
		var updated: Array[Variable] = []
		if var_id_or_name is int && self._collection.has(var_id_or_name):
			updated.append(self._collection[var_id_or_name])
		elif var_id_or_name is String:
			for id in self._collection:
				if self._collection[id].name == var_id_or_name:
					updated.append(self._collection[id])
		for variable in updated:
			variable.value = value
		return updated
	## Updates a listed variable with the provided change.
	func update(change: Update) -> void:
		match change.kind:
			Update.Kind.DROP:
				var is_dropped = self._collection.erase(change.target)
				print_debug("dropping variable = %s (existed = %s)" % [change.target, is_dropped])
			Update.Kind.RESET:
				if self._collection.has(change.target):
					self._collection[change.target].value = change.value
				else:
					print_debug("trying to reset non-initialized variable (ignored): ", change)
	## Update object to modify variables
	class Update:
		extends Resource
		enum Kind { DROP, RESET }
		var target: int
		var kind: Kind
		var value
		func _init(target: int, kind: Kind, value) -> void:
			self.target = target
			self.kind = kind
			self.value = value
		## Helps printing the Variable.Update resource.
		func _to_string():
			return "Variable.%s: %s = %s" % ["Drop" if kind == Kind.DROP else "Reset", target, value]
		## Creates a variable reset update.
		static func reset(target: int, new_value) -> Update:
			return Update.new(target, Kind.RESET, new_value)
		## Creates a variable drop (removal) update.
		static func drop(target: int) -> Update:
			return Update.new(target, Kind.DROP, null)

## Bow & Arrow Character
##
## This class represents an Arrow character and tracks its current tags if it is loaded in the [member Bow.characters] state.
class Character:
	extends Resource
	## ID of this character
	var id: int
	## Name of this character
	var name: String
	## Color of this character (assigned by Arrow editor)
	var color: Color
	## Collection of this character's tags
	var tags: Dictionary # { tag-nam<String> : tag-value<String> }
	## Creates an Arrow character object from a [code]resources.characters[id][/code] part of an arrow document dictionary.
	static func from_raw(id: int, character: Dictionary) -> Character:
		var this = Character.new()
		this.id = id
		this.name = character.name
		this.color = Color.html(character.color)
		this.tags = character.tags if character.has("tags") else {}
		return this
	## Serializes the Character to basic Godot types.
	func pack() -> Dictionary:
		return { "id": self.id, "name": self.name, "color": self.color.to_html(), "tags": self.tags }
	## Deserializes a Character from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Character:
		return Character.from_raw(from.id, from)
	## Helps printing this Character.
	func _to_string() -> String:
		return "Character { id = %s, name = %s, color = %s, tags = %s }" % [id, name, color, tags]
	## Returns a character with no valid ID (-1) and complying with the Arrow's convention for built-in nodes that allow Anonymous characters.
	static func anonymous() -> Character:
		var anonymous = Character.new()
		anonymous.id = -1
		anonymous.name = "Anonymous"
		anonymous.color = Color.html("ffffff")
		anonymous.tags = {}
		return anonymous
	## Creates an instruction to reset a tag of this character with a new value.
	func reset_tag(name: String, value: String) -> Instruction:
		return Instruction.manage( State.Update.character_tag( Characters.TagUpdate.reset(self.id, name, value) ) )
	## Creates an instruction to erase/drop a tag of this character by name.
	func drop_tag(name: String) -> Instruction:
		return Instruction.manage( State.Update.character_tag( Characters.TagUpdate.drop(self.id, name) ) )

## Bow & Arrow Characters Collection
##
## It is chiefly used to construct game [member Bow.characters] state or to represent chapter Resources.
class Characters:
	extends Resource
	var _collection: Dictionary
	## Creates Characters resource collection from [code]resources.characters[/code] part of an arrow document dictionary.
	static func from_raw(characters: Dictionary) -> Characters:
		var this = Characters.new()
		for character_id in characters:
			this._collection[character_id] = Character.from_raw(character_id, characters[character_id])
		return this
	## Serializes Characters to basic Godot types.
	func pack() -> Dictionary:
		var packed = {}
		for char_id in self._collection:
			packed[char_id] = self._collection[char_id].pack()
		return packed
	## Deserializes Characters from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Characters:
		var new = Characters.new()
		for char_id in from:
			new._collection[char_id] = Character.unpack(from[char_id])
		return new
	## Helps printing Characters.
	func _to_string() -> String:
		return "Characters %s" % _collection
	## Enlists each character from the [code]other[/code] object that is not initialized already.
	func refill_with(other: Characters) -> void:
		for id in other._collection:
			if self._collection.has(id) == false:
				self._collection[id] = other._collection[id]
	## Inserts a Character into the collection if forced or not already initialized.
	## Returns the replaced character or null (when not forced or totally new).
	func insert(id: int, character: Character, forced: bool = false):
		assert(id == character.id)
		var replacing = self._collection[id] if self._collection.has(id) else null
		if forced || replacing == null:
			self._collection[id] = character
			return replacing
		else:
			return null
	## Returns a listed character by ID or name, or null if not found.
	## This method short-circuits, so in case there are duplicates the first one will be returned.
	## Note that characters with identical IDs are not possible and duplicate names are not allowed by Arrow editor normally.
	func fetch(id_or_name):
		if id_or_name is int && self._collection.has(id_or_name):
			return self._collection[id_or_name]
		elif id_or_name is String:
			for id in self._collection:
				if self._collection[id].name == id_or_name:
					return self._collection[id]
		return null
	## This is an internal method, specially used to sync Preferences as tags of a character.
	## It will fully replace tags of any character known by the provided ID or name and works aggressively.
	## It returns updated Characters.
	func _force_reset_tags(char_id_or_name, tags: Dictionary) -> Array[Character]:
		var updated: Array[Character] = []
		if char_id_or_name is int && self._collection.has(char_id_or_name):
			updated.append(self._collection[char_id_or_name])
		elif char_id_or_name is String:
			for id in self._collection:
				if self._collection[id].name == char_id_or_name:
					updated.append(self._collection[id])
		for character in updated:
			character.tags = tags
		return updated
	## Updates a tag for a listed character with the provided change.
	func update_tag(change: TagUpdate) -> void:
		if self._collection.has(change.character):
			var character = self._collection[change.character]
			match change.kind:
				TagUpdate.Kind.DROP:
					var is_dropped = character.tags.erase(change.name)
					print_debug(
						"dropping character %s - %s's tag = %s (existed = %s)" % [
							change.character, character.name, change.name, is_dropped
						]
					)
				TagUpdate.Kind.RESET:
					# Whether existent or not, we (re-)set the tag name pair:
					character.tags[change.name] = change.value
		else:
			print_debug("trying to update tag for a non-existent character: ", change)
	## Update object to modify characters
	class TagUpdate:
		extends Resource
		enum Kind { DROP, RESET }
		var character: int
		var kind: Kind
		var name: String
		var value: String
		func _init(character: int, kind: Kind, name: String, value: String = "") -> void:
			self.character = character
			self.kind = kind
			self.name = name
			self.value = value
		## Helps printing the Character.Update resource.
		func _to_string():
			return "Character.Tag.%s: #%s.%s = %s" % ["Drop" if kind == Kind.DROP else "Reset", character, name, value]
		## Creates an update to reset a target character's tag by name and with new value.
		static func reset(character: int, tag: String, with_value: String) -> TagUpdate:
			return TagUpdate.new(character, Kind.RESET, tag, with_value)
		## Creates an update to drop/erase a target character's tag by name.
		static func drop(character: int, tag_by_name: String) -> TagUpdate:
			return TagUpdate.new(character, Kind.DROP, tag_by_name, "")

## Bow & Arrow Resources Collection
##
## This type is chiefly used to work with chapter resources.
class Resources:
	extends Resource
	## Collection of a chapter's scenes as defined in the loaded Arrow document
	var scenes: Scenes
	## Collection of a chapter's nodes as defined in the loaded Arrow document
	var nodes: ArwNodes
	## Collection of a chapter's variables as defined in the loaded Arrow document
	var variables: Variables
	## Collection of a chapter's characters as defined in the loaded Arrow document
	var characters: Characters
	## Creates a Resources object from [code]resources[/code] part of an arrow document dictionary.
	static func from_raw(resources: Dictionary) -> Resources:
		var this = Resources.new()
		this.scenes = Scenes.from_raw(resources.scenes)
		this.nodes = ArwNodes.from_raw(resources.nodes)
		this.variables = Variables.from_raw(resources.variables)
		this.characters = Characters.from_raw(resources.characters)
		return this
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "Resources { scenes = %s, nodes = %s, variables = %s, characters = %s }" % [scenes, nodes, variables, characters]

## Bow & Arrow Chapter
##
## It is representation of an Arrow document.
class Chapter:
	extends Resource
	## Chapter's title as defined in the document
	var title: String
	## Entry point of the chapter which is expected to be a node ID in that chapter.
	var entry: int
	## Collections of Arrow resources (i.e. nodes, variables, etc.)
	var resources: Resources
	## Creates a chapter from an Arrow document dictionary.
	## If your dictionary is a JSON just parsed (not valid Godot) please use [method from_json_dictionary] instead.
	static func from_raw(doc: Dictionary) -> Chapter:
		var this = Chapter.new()
		this.title = doc.title
		this.entry = doc.entry
		this.resources = Resources.from_raw(doc.resources)
		return this
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "Chapter { title = %s, entry = %s, resources = %s }" % [title, entry, resources]
	## ...
	## This method converts all the numbers (e.g. JSON floats) to Godot integers recursively.
	static func _recursively_convert_numbers_to_int(data):
		if data is float:
			data = int(data)
		# DEV: stringified numbers in data may be a number-only title or str value, so let's keep them:
		# -- elif data is String && String(int(data)) == data:
		# --	data = int(data)
		elif data is Array:
			for index in range(0, data.size()):
				data[index] = _recursively_convert_numbers_to_int( data[index] )
		elif data is Dictionary:
			var data_with_converted_keys = {}
			for key in data:
				# well, the key itself might also be a stringified int
				if ("%s" % int(key)) == key:
					var key_int = int(key)
					var value = ( data[key].duplicate(true) if (data[key] is Dictionary || data[key] is Array) else data[key] )
					data_with_converted_keys[ key_int ]  = _recursively_convert_numbers_to_int( value )
				else:
					data_with_converted_keys[key] = _recursively_convert_numbers_to_int( data[key] )
			data = data_with_converted_keys
		return data
	## There are few things we should change in a project file read as JSON, most importantly:
	## the keys can only be strings in JSON, while our resource keys are integers, which may also be referenced in nodes' data
	## so we need to refactor all such numbers.
	static func _refactor_parsed_json(data: Dictionary) -> Dictionary:
		var refactored = _recursively_convert_numbers_to_int(data)
		# print_debug("Refactored JSON project: ", refactored)
		return refactored
	static func from_json_dictionary(data: Dictionary) -> Chapter:
		return Chapter.from_raw(_refactor_parsed_json(data))
	## Reads an arrow document/project (JSON) file from the path and constructs a proper chapter.
	static func from_file(path: String) -> Chapter:
		var json = FileAccess.get_file_as_string(path)
		var parsed_json_doc = JSON.parse_string(json)
		return Chapter.from_json_dictionary(parsed_json_doc)

## Bow & Arrow Chapters List
##
## Lists chapters (i.e. Arrow document files by name and chapter ID) to help with intra-chapter jumps and more.
## It is more or less like a purged arrow projects file, with an optional first-level [code]entry[/code] property,
## hinting the entry chapter for [method Bow.begin] if no overriding [member Bow.entry_chapter] is defined.
class ChaptersList:
	extends Resource
	var _list: Dictionary
	## A hint for ID of the preferred beginning chapter, which may be used
	## if no overriding [member Bow.entry_chapter] is defined for [method Bow.begin]. [br]
	## See also [method entry_or_least_id].
	var entry: int = -1
	## Creates a chapters list from an arrow projects dictionary. [br]
	## Use [method from_arrow_projects_file] for convenience.
	static func from_raw(list: Dictionary) -> ChaptersList:
		var this = ChaptersList.new()
		this.entry = list.entry if list.has("entry") else -1
		for chapter_id_str in list.projects:
			this._list[chapter_id_str.to_int()] = list.projects[chapter_id_str]
		return this
	## Reads an arrow projects file from the provided path and constructs the respective chapters list.
	static func from_arrow_projects_file(path: String) -> ChaptersList:
		var json = FileAccess.get_file_as_string(path)
		var list_dictionary = JSON.parse_string(json)
		return ChaptersList.from_raw(list_dictionary)
	## Serializes the ChaptersList to basic Godot types.
	func pack() -> Dictionary:
		return { "_list": self._list, "entry": self.entry }
	## Deserializes a ChaptersList from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> ChaptersList:
		var new = ChaptersList.new()
		new._list = from._list
		new.entry = from.entry
		return new
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "ChaptersList { entry = %s, list = %s }" % [entry, _list]
	## Returns if the chapters list is empty or not read/listed.
	func is_empty() -> bool:
		return self._list.is_empty()
	## Returns the [member entry] chapter ID if defined or the least chapter ID in the list.
	## It can be used to guess starting point of the story if no value is known.
	func entry_or_least_id() -> int:
		return self.entry if self.entry >= 0 else self._list.keys().min()
	## Returns chapter's filename respective to an ID (int) or title (string).
	## It returns null if no such chapter is listed.
	## This method short-circuits, so in case there are duplicates (i.e. two or more chapters with identical titles)
	## the first one will be returned. You can join the result (if not null) with [member Bow.documents_dir] to get a full resource path.
	func chapter_filename(id_or_title):
		if id_or_title is int:
			if self._list.has(id_or_title):
				return self._list[id_or_title].filename
		else:
			for id in self._list:
				if self._list[id].title == id_or_title:
					return self._list[id].filename
		return null

## Narrative Scope
##
## Defines a level of nested narrative, or in other words,
## identity of a nested (scene/) macro and the point to resume from when that nested scene is finished.
class Scope:
	extends Resource
	## ID of the scene (~ macro) being open currently as this scope
	var level: int
	## The [node and slot] to resume i.e. to be played next when the scope (playing [member level] macro) is finished.
	## An empty array indicates no resume point, which in case of scoping out means another level shall be dropped.
	var resume: Array[int]
	## Creates a new scope
	func _init(level: int, resume: Array[int]) -> void:
		self.level = level
		self.resume = resume
	## Serializes the Scope to basic Godot types.
	func pack() -> Dictionary:
		return { "level": self.level, "resume": self.resume }
	## Deserializes a Scope from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Scope:
		return Scope.new(from.level, from.resume)
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "Scope { level = %s, resume = %s }" % [level, resume]

## State of the runtime
##
class State:
	extends Resource
	## Initialized variables and their current values
	var variables: Variables
	## Participating characters and current state of their tags
	var characters: Characters
	## Creates a new all blank State object.
	func _init() -> void:
		self.variables = Variables.new()
		self.characters = Characters.new()
	## Creates a new State object with known inner states.
	static func from(vars: Variables, chars: Characters) -> State:
		var known = State.new()
		known.variables = vars
		known.characters = chars
		return known
	## Serializes the State to basic Godot types.
	func pack() -> Dictionary:
		return { "variables": self.variables.pack(), "characters": self.characters.pack() }
	## Deserializes a State from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> State:
		return State.from(Variables.unpack(from.variables), Characters.unpack(from.characters))
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "State { variables = %s, characters = %s }" % [variables, characters]
	## Cleans up states, by dropping all initialized [member variables] and [member characters]. [br][br]
	## CAUTION! This method is mainly for internal purposes. [br]
	## It is advised not to call this method at all, unless you want to make sure everything is forgotten
	## and only if your chapters have independent states. Also make sure to only call this method (if you need to)
	## just before a new chapter is getting open, otherwise your narrative may crash due to uninitialized state.
	func _blank() -> void:
		self.variables = Variables.new()
		self.characters = Characters.new()
	## Enlists each Variable and Character from the [code]chapter[/code] resources that is not initialized already.
	func refill_with(chapter: Chapter) -> void:
		self.variables.refill_with(chapter.resources.variables)
		self.characters.refill_with(chapter.resources.characters)
	func update(with: Update) -> void:
		if with.change is Variables.Update:
			self.variables.update(with.change)
		elif with.change is Characters.TagUpdate:
			self.characters.update_tag(with.change)
	## Replaces [code]{variable}[/code] and [code]{character.tag}[/code] placeholders
	## with their current respective values in a piece of string (a.k.a. exposure).
	## NOTE: Placeholders are considered case sensitive.
	func expose(text: String) -> String:
		if text.length() > 0:
			var exposed := text
			for cid in self.characters._collection:
				var character: Character = self.characters._collection[cid]
				for tag_name in character.tags:
					exposed = exposed.replace("{%s.%s}" % [character.name, tag_name], character.tags[tag_name])
			for vid in self.variables._collection:
				var variable: Variable = self.variables._collection[vid]
				exposed = exposed.replace("{%s}" % variable.name, "%s" % variable.current_or_initial())
			# ...
			return exposed
		else:
			return text
	## Update object to modify state (variable or character)
	class Update:
		extends Resource
		## Inner state (~ character tag or variable) update
		var change
		## Creates a new State.Update object.
		func _init(change) -> void:
			assert(change is Variables.Update || change is Characters.TagUpdate)
			self.change = change
		## Helps printing the State.Update resource.
		func _to_string():
			return "State.Update: %s" % change
		## Creates a variable update.
		static func variable(update: Variables.Update) -> Update:
			return Update.new(update)
		## Creates a character update.
		static func character_tag(update: Characters.TagUpdate) -> Update:
			return Update.new(update)

# DEV: The reason for following method is to use key in UI controls, where ever possible.
# This gives us one simple advantage: if you are not using exposure, you can change language of story at any time during the game;
# otherwise, we need to recreate the view, every time this happens. This method is preferred to recreating the story view,
# at the time, because both changing language mid-game and using exposures are really rarely used.
func _produce_responsive_text(from: String, force_processed: bool = false) -> String:
	var translated = self.tr(from)
	var and_exposed = self.state.expose(translated)
	# var has_translation = TranslationServer.get_translation_object(TranslationServer.get_locale()).get_message_list().has(from)
	if self.ctx == Ctx.ID && translated == from: # (~ meaning no translation or blank..
		return "" # ... which both being better handled as blank string)
	else:
		return and_exposed if force_processed || translated != and_exposed else from

## A View Element
##
## Bow has a special strategy of printing nodes outputs to simplify the view implementation.
## Instead of printing each node as a separate view, nodes create instances of [Bow.Block]
## which are groups of [Bow.Element]s each capable of producing view controls
## using their [method to_view] method. [br]
##
## [br][b]Styling![/b][br]
## Views that built-in elements produce all get distinguishable [member Control.theme_type_variation]
## values to allow easier styling. Please consult each element's [code]to_view[/code] method
## documentation for more information.
class Element:
	extends Resource
	## Inner element such as Article, Hook, Line, etc.
	var inner
	## Helps printing the Element resource.
	func _to_string():
		return "Element:%s" % inner
	## Creates an element from a bunch of allowed variants (/ sub-classes).
	func _init(inner) -> void:
		assert(inner is Custom || inner is Article || inner is Hook || inner is Line || inner is Prompt)
		self.inner = inner
	## Serializes the Element to basic Godot types.
	func pack() -> Dictionary:
		return { "inner": self.inner.pack(), "kind": inner_kind_str() }
	## Deserializes an Element from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Element:
		var new_inner = null
		match from.kind:
			"null":
				new_inner = null
			"custom":
				new_inner = Custom.unpack(from.inner)
			"article":
				new_inner = Article.unpack(from.inner)
			"hook":
				new_inner = Hook.unpack(from.inner)
			"line":
				new_inner = Line.unpack(from.inner)
			"prompt":
				new_inner = Prompt.unpack(from.inner)
		return Element.new(new_inner)
	## Returns the element's inner kind as string.
	func inner_kind_str() -> String:
		var str = "invalid"
		if inner == null:
			str = "null"
		elif inner is Custom:
			str = "custom"
		elif inner is Article:
			str = "article"
		elif inner is Hook:
			str = "hook"
		elif inner is Line:
			str = "line"
		elif inner is Prompt:
			str = "prompt"
		return str
	## Returns the element converted [code]to_view[/code] if the [member inner] value produces a vie control, otherwise null.
	func to_view(with_runtime: Bow = null):
		var view = null
		if inner == null:
			print_debug("Trying to convert blank element (inner == null) `to_view`!")
		elif inner is Custom:
			view = inner.to_view()
		elif inner is Article:
			view = inner.to_view(with_runtime)
		elif inner is Hook:
			view = inner.to_view()
		elif inner is Line:
			view = inner.to_view(with_runtime)
		elif inner is Prompt:
			view = inner.to_view(with_runtime)
		else:
			printerr("Unsupported inner value for Element! ", inner)
		return view
	# ...
	## Custom Element
	##
	## This is a custom general purpose element wrapping a pre-fabricated control.
	## It is designed for quick prototyping and is not used by the built-in Bow & Arrow nodes.[br]
	## Custom elements would not be saved at the time, so if you need to save your custom elements, developing dedicated ones would be an option.
	class Custom:
		extends Resource
		## Pre-fabricated view control
		var prefab: Control
		## Initializes a new Custom element
		func _init(prefab: Control) -> void:
			self.prefab = prefab
		# ...
		# NOTE:
		# Customs elements are not going to be serialized and saved by default,
		# if you need to save them, please create a dedicated element.
		# ...
		## Serializes the Custom element to basic Godot types.
		func pack() -> Dictionary:
			return {}
		## Deserializes a Custom element from a dictionary made by [method pack].
		static func unpack(from: Dictionary) -> Custom:
			return Custom.new(Node.new())
		# ...
		## Helps printing the Custom Element resource.
		func _to_string():
			return "Custom { prefab = %s }" % prefab
		## Returns the [member prefab] control
		func to_view() -> Control:
			return self.prefab
	## Creates a Custom Element.
	static func custom(prefab: Control) -> Element:
		return Element.new( Element.Custom.new(prefab) )
	# ...
	## Article Element
	class Article:
		extends Resource
		## Title of the article
		var title: String
		## Main content of the article
		var content: String
		## Initializes a new Article element.
		func _init(content: String, title: String = "") -> void:
			self.title = title
			self.content = content
		## Serializes the Article element to basic Godot types.
		func pack() -> Dictionary:
			return { "title": self.title, "content": self.content }
		## Deserializes an Article element from a dictionary made by [method pack].
		static func unpack(from: Dictionary) -> Article:
			return Article.new(from.content, from.title)
		## Helps printing the Article Element resource.
		func _to_string():
			return "Article { title = %s, content = %s }" % [title, content]
		## Creates a view control from the article.
		## It will be a (vertical by default) [BoxContainer]
		## wrapping a [RichTextLabel] for each of the text parts that is not blank.
		## [member Control.theme_type_variation] values would be
		## [code]BowArticle[/code] for the main container, and for the parts
		## [code]BowArticleTitle[/code] and [code]BowArticleContent[/code].
		## BBCode and fit-content properties are by default activated.
		## To handle translation and exposure properly you should call this [code]with_runtime[/code].
		func to_view(with_runtime: Bow = null) -> Control:
			var container := BoxContainer.new()
			container.set_vertical(true)
			container.set_theme_type_variation("BowArticle")
			for part in [
				[self.title, "BowArticleTitle"],
				[self.content, "BowArticleContent"]
			]:
				var text = part[0] if with_runtime == null else with_runtime._produce_responsive_text(part[0])
				if text.length() > 0:
					var rich := RichTextLabel.new()
					rich.set_text(text)
					rich.set_use_bbcode(true)
					rich.set_fit_content(true)
					rich.set_autowrap_mode(TextServer.AutowrapMode.AUTOWRAP_WORD_SMART)
					rich.set_text_direction(Control.TextDirection.TEXT_DIRECTION_INHERITED)
					rich.set_theme_type_variation(part[1])
					container.add_child(rich)
			return container
	## Creates an Article Element.
	static func article(content: String, title: String = "") -> Element:
		return Element.new( Element.Article.new(content, title) )
	# ...
	## Hook Element
	## 
	## This is a curious element with a double nature.
	## Although it is capable of producing view controls, it is [i]not really designed to display content[/i].
	## Its real purpose is to hint the renderer to carry a task. In a sense its like a signal or a serialized method call.
	## For example, you can create a hook if you want your Arrow content to hint your game where to play a cut-scene!
	## Something like [code]Bow.Element.Hook.new("animate", ["cut_scene_x"])[/code] that will be interpreted by the 
	## renderer as a call of `animate` method with parameter "cut_scene_x".[br]
	## See [Bow.ArwNode.Marker] and examples using it to hook into gameplay for more information.
	class Hook:
		extends Resource
		## Event of this hook
		var event: String
		## Parameters of this hook
		var parameters: Array
		## Initializes a new Hook element
		func _init(event: String, parameters: Array = []) -> void:
			self.event = event
			self.parameters = parameters
		## Serializes the Hook element to basic Godot types.
		func pack() -> Dictionary:
			return { "event": self.event, "parameters": self.parameters }
		## Deserializes a Hook element from a dictionary made by [method pack].
		static func unpack(from: Dictionary) -> Hook:
			return Hook.new(from.event, from.parameters)
		## Helps printing the Hook Element resource.
		func _to_string():
			return "Hook { event = %s, parameters = %s }" % [event, parameters]
		## Hooks are not designed to create view, but they can![br][br]
		## The result will be a (vertical by default) [BoxContainer] wrapping a [Label] representing the event
		## if its not blank, and a [FlowContainer] (horizontal by default) which contains one [Label] per parameter
		## if there is any parameter. With all empty values, it returns an empty container.[br]
		## [member Control.theme_type_variation] values would be [code]BowHook[/code], [code]BowHookEvent[/code],
		## [code]BowHookFlow[/code] and [code]BowHookParam[/code] for each parameter label.
		func to_view() -> Control:
			var container := BoxContainer.new()
			container.set_vertical(true)
			container.set_theme_type_variation("BowHook")
			if self.event.length() > 0:
				var ev_label := Label.new()
				ev_label.set_text(self.event)
				ev_label.set_theme_type_variation("BowHookEvent")
				container.add_child(ev_label)
			if self.parameters.size() > 0:
				var p_flow := FlowContainer.new()
				p_flow.set_vertical(false)
				p_flow.set_theme_type_variation("BowHookFlow")
				for param in self.parameters:
					var p_label := RichTextLabel.new()
					p_label.set_text("%s" % param)
					p_label.set_use_bbcode(true)
					p_label.set_fit_content(true)
					p_label.set_autowrap_mode(TextServer.AUTOWRAP_OFF)
					p_label.set_theme_type_variation("BowHookParam")
					p_flow.add_child(p_label)
				container.add_child(p_flow)
			return container
	## Creates a Hook Element.
	static func hook(event: String, parameters: Array = []) -> Element:
		return Element.new( Element.Hook.new(event, parameters) )
	## Regex pattern to detect mood snippets[br]
	## This patterns helps extracting mood snippets like [code]Happy,2,true[/code] (inside brackets) (i.e. mood-kind, level, auto-reset)
	## from beginning of a string. We should ignore similar snippets if they are not at the beginning.[br]
	## [br]
	## NOTE:[br]
	## + Non-word characters (e.g. whitespace) from the beginning of the string (before left-bracket) are ignored.[br]
	## + Kind can only include english alphabet (`a-zA-Z`), underscore (`_`) and hyphen (`-`).[br]
	## + A blank mood is valid and may be used to reset the view to an idle mood.[br]
	## [br]
	## In general, the extraction process is **very eager** to find a match,
	## so anything between a pair of brackets at the beginning of a string could potentially be a Mood.
	const _REGEX_MOOD_SNIPPET_PATTERN := r"^\s*\[([a-zA-z \-_]*)?\s*,?\s*(\-?\+?[0-9]*)?\s*,?\s*(false|keep|~|true|reset)?\]\s*"
	## Extracts a mood snippet and turns it into a Hook.[br]
	## This method tries to default for each segment (even for empty array) to `["", 0, true]`.
	## It also returns the snippet itself, added to the end of the array.[br]
	## This method accepts the sign `~` and "keep" as alternatives for `false` reset value, and every thing else for `true`.
	## For example, `[Excited,~]` is equal to `[Excited,false]`.[br]
	## It returns null if no mood is detected.
	static func mood(from: String):
		var regex = RegEx.new()
		var compiled = regex.compile(_REGEX_MOOD_SNIPPET_PATTERN)
		if compiled == OK:
			# RegEx.search() returns RegExMatch if found, otherwise `null`
			var matched = regex.search(from)
			if matched != null:
				var snippet = matched.get_string(0)
				var mood = matched.get_string(1).strip_edges()
				var level = int(matched.get_string(2).strip_edges())
				var auto_reset = false if ["false", "keep", "~"].has(matched.get_string(3).strip_edges().to_lower()) else true
				return Element.new( Element.Hook.new("mood", [mood, level, auto_reset, snippet]) )
		else:
			printerr("Unexpectedly unable to compile the Element.Hook._REGEX_MOOD_SNIPPET_PATTERN to extract moods")
		return null
	# ...
	## Line Element
	class Line:
		extends Resource
		## Text of the line
		var text: String
		## An instruction-set to be returned
		var interaction: Array[Instruction]
		## Makes the line to hide itself after being pressed.
		var auto_hide: bool
		## Disables and hides all the sibling buttons chiefly to avoid running multiple paths.
		var drop_siblings: bool
		## Horizontal alignment of the generated control
		var alignment_horizontal: Control.SizeFlags = Control.SizeFlags.SIZE_FILL
		## Wrap mode of the generated control
		var auto_wrap_mode: TextServer.AutowrapMode = TextServer.AutowrapMode.AUTOWRAP_WORD_SMART
		## Overrides theme type variation for the created view.
		var theme_type_override: StringName = ""
		## Interactive elements like this, need to keep their play state in order to (un-)pack properly when viewed.
		## This property shows if the Line is [b]already played[/b].
		var played: bool
		## Initializes a new Line element.
		func _init(
			text: String, interaction: Array[Instruction] = [], auto_hide: bool = false, drop_siblings: bool = true,
			alignment_horizontal:= Control.SizeFlags.SIZE_FILL, auto_wrap_mode:= TextServer.AutowrapMode.AUTOWRAP_WORD_SMART,
			theme_type_override: StringName = ""
		) -> void:
			self.text = text
			self.interaction = interaction
			self.auto_hide = auto_hide
			self.drop_siblings = drop_siblings
			self.alignment_horizontal = alignment_horizontal
			self.auto_wrap_mode = auto_wrap_mode
			self.theme_type_override = theme_type_override
			self.played = ( interaction.size() == 0 )
			# 🡦 Non-interactive line is considered already played (and likely viewed as a label).
		## Serializes the Line element to basic Godot types.
		func pack() -> Dictionary:
			return {
				"text": self.text,
				"interaction": self.interaction.map( func(i): return i.pack() ),
				"auto_hide": self.auto_hide,
				"drop_siblings": self.drop_siblings,
				"alignment_horizontal": self.alignment_horizontal,
				"auto_wrap_mode": self.auto_wrap_mode,
				"theme_type_override": self.theme_type_override,
				"played": self.played,
			}
		## Deserializes a Line element from a dictionary made by [method pack].
		static func unpack(from: Dictionary) -> Line:
			var unpacked_interaction: Array[Instruction] = []
			for instruction in from.interaction:
				unpacked_interaction.push_back(Instruction.unpack(instruction))
			var new = Line.new(
				from.text, unpacked_interaction,
				from.auto_hide, from.drop_siblings, from.alignment_horizontal, from.auto_wrap_mode, from.theme_type_override
			)
			new.played = from.played
			return new
		## Helps printing the Line Element resource.
		func _to_string():
			return "Line { text = %s, interaction = %s, ..., played = %s }" % [text, interaction, played]
		## Creates a view control from the line, if the line has [member interaction]
		## it will be a [ButtonExt] that will feed back the assigned instructions on [code]pressed[/code]
		## in case of [code]with_runtime:Bow[/code] being set, otherwise a [Label].
		## Respectively, the [member Control.theme_type_variation] value
		## will be either [code]BowLineButton[/code] or [code]BowLineLabel[/code].
		## In special cases, such as when line is used for custom or continue buttons,
		## the theme type variation value may be different such as [code]BowNextButton[/code].
		## Note also that to handle translation and exposure properly you should call this [code]with_runtime[/code].
		func to_view(with_runtime: Bow = null) -> Control:
			var control: Control
			var text = self.text if with_runtime == null else with_runtime._produce_responsive_text(self.text)
			if interaction.size() > 0:
				var button := ButtonExt.new()
				button.set_text(text)
				button.set_theme_type_variation("BowLineButton")
				button.set_autowrap_mode.call_deferred(self.auto_wrap_mode)
				button.set_text_direction(Control.TextDirection.TEXT_DIRECTION_INHERITED)
				# ...
				var _play_handler = func():
					button.set_disabled(true)
					button.release_focus()
					if auto_hide:
						button.set_visible(false)
					if drop_siblings:
						for sibling in button.get_parent().get_children():
							if sibling is Button && sibling != button:
								sibling.set_visible(false)
								sibling.set_disabled(true)
					if played == false && with_runtime != null:
						with_runtime.run(self.interaction)
					played = true
				# ...
				if with_runtime != null:
					button.pressed.connect(_play_handler)
				else:
					print_debug("WARN! interactive Line `with_runtime` being null preventing us to feedback the instructions: ", self)
				if played:
					_play_handler.call_deferred()
				control = button
			else:
				var label := Label.new()
				label.set_text(text)
				label.set_autowrap_mode(TextServer.AutowrapMode.AUTOWRAP_WORD_SMART)
				label.set_text_direction(Control.TextDirection.TEXT_DIRECTION_INHERITED)
				label.set_theme_type_variation("BowLineLabel")
				control = label
			if self.theme_type_override.length() > 0:
				control.set_theme_type_variation(self.theme_type_override)
			control.set_h_size_flags(self.alignment_horizontal)
			return control
	## Creates a Line Element.
	static func line(
		text: String, interaction: Array[Instruction] = [], auto_hide: bool = false, drop_siblings: bool = true,
		alignment_horizontal := Control.SizeFlags.SIZE_FILL, auto_wrap_mode := TextServer.AutowrapMode.AUTOWRAP_WORD_SMART,
		theme_type_override: StringName = ""
	) -> Element:
		return Element.new( Element.Line.new(text, interaction, auto_hide, drop_siblings, alignment_horizontal, auto_wrap_mode, theme_type_override) )
	## Creates a Line Element that is used commonly to make a next or "Continue" button
	## which shrinks end and has a default "BowNextButton" theme type override.
	static func next(
		interaction: Array[Instruction] = [], text: String = "BOW_LINE_NEXT", auto_hide: bool = true, drop_siblings: bool = true,
		alignment_horizontal := Control.SizeFlags.SIZE_SHRINK_END, auto_wrap_mode := TextServer.AutowrapMode.AUTOWRAP_OFF,
		theme_type_override: StringName = "BowNextButton"
	) -> Element:
		return Element.new( Element.Line.new(text, interaction, auto_hide, drop_siblings, alignment_horizontal, auto_wrap_mode, theme_type_override) )
	# ...
	## User Input Prompt Element
	class Prompt:
		extends Resource
		## The input can create [Bow.Instruction] sets to update this target variable
		var target: int
		## The question that will be asked from user
		var question: String
		## Inputs can feed back this [Bow.Instruction] set, **after** updating the state.
		## We can use this for example to forward to the next node after the input is received.
		var following: Array # Array[Instruction]
		## Defines system and view of the prompt
		var input
		## Text used for the submit button
		var submit: String = "BOW_PROMPT_SUBMIT"
		## Text used for the reset button
		var reset: String = "BOW_PROMPT_RESET"
		## Interactive elements like this, need to keep their play state in order to (un-)pack properly when viewed.
		## This property shows if the Prompt is [b]already played[/b]. The played value in kept by the inner [member input].
		var played := false
		## Creates a new Prompt element.
		func _init(input, target: int, question: String, following: Array, submit: String = "BOW_PROMPT_SUBMIT", reset: String = "BOW_PROMPT_RESET") -> void:
			assert(input is TextInput || input is NumberInput || input is BooleanInput)
			self.input = input
			self.target = target
			self.question = question
			self.following = following
			self.submit = submit
			self.reset = reset
		## Serializes the Prompt to basic Godot types.
		func pack() -> Dictionary:
			var packed_following = []
			for instruction in self.following:
				packed_following.push_back(instruction.pack())
			return {
				"target": self.target,
				"question": self.question,
				"following": packed_following,
				"input": self.input.pack(), "kind": input_kind_str(),
				"submit": self.submit,
				"reset": self.reset,
				"played": self.played,
			}
		## Deserializes a Prompt from a dictionary made by [method pack].
		static func unpack(from: Dictionary) -> Prompt:
			var unpacked_following = []
			for instruction in from.following:
				unpacked_following.push_back(Instruction.unpack(instruction))
			var new_input = null
			match from.kind:
				"boolean":
					new_input = BooleanInput.unpack(from.input)
				"number":
					new_input = NumberInput.unpack(from.input)
				"text":
					new_input = TextInput.unpack(from.input)
			var new = Prompt.new(new_input, from.target, from.question, unpacked_following, from.submit, from.reset)
			new.played = from.played
			return new
		## Returns the element's input kind as string.
		func input_kind_str() -> String:
			var str = "invalid"
			if input == null:
				str = "null"
			elif input is BooleanInput:
				str = "boolean"
			elif input is NumberInput:
				str = "number"
			elif input is TextInput:
				str = "text"
			return str
		## Helps printing the Prompt Element resource.
		func _to_string():
			return "Prompt { target = %s, question = %s, following = %s, input = %s, ..., played = %s }" % [target, question, following, input, played]
		## Creates a new Prompt to accept boolean inputs.
		static func boolean(
			target: int, question: String,
			negative: String, positive: String, default: bool,
			following: Array, submit: String = "BOW_PROMPT_SUBMIT", reset: String = "BOW_PROMPT_RESET"
		) -> Prompt:
			var input = BooleanInput.new(negative, positive, default)
			return Prompt.new(input, target, question, following, submit, reset)
		## Creates a new Prompt to accept number inputs.
		static func number(
			target: int, question: String,
			min: int, max: int, step: int, default: int,
			following: Array, submit: String = "BOW_PROMPT_SUBMIT", reset: String = "BOW_PROMPT_RESET"
		) -> Prompt:
			var input = NumberInput.new(min, max, step, default)
			return Prompt.new(input, target, question, following, submit, reset)
		## Creates a new Prompt to accept text inputs.
		static func text(
			target: int, question: String,
			pattern: String, default: String, hint: String,
			following: Array, submit: String = "BOW_PROMPT_SUBMIT", reset: String = "BOW_PROMPT_RESET"
		) -> Prompt:
			var input = TextInput.new(pattern, default, hint)
			return Prompt.new(input, target, question, following, submit, reset)
		## Creates view controls respecting to the inner input. The controls (resembling a form in a vertical by default
		## [BoxContainer]) would handle validation, target update and running [member following] instructions automatically
		## in case of [code]with_runtime:Bow[/code] being set to the proper runtime.[br]
		## The [member Control.theme_type_variation] values will be set as follows:
		## [code]BowPrompt[/code] for the main container,
		## [code]BowPromptQuestion[/code] for the question [Label] if existent (not blank),
		## [code]BowPromptButtons[/code] for container (by default horizontal) wrapping submit and reset buttons,
		## [code]BowPromptSubmit[/code] and [code]BowPromptReset[/code] for each respective [Button],
		## and for the input controls one of the [code]BowPromptInputText[/code] being [LineEditExt],
		## [code]BowPromptInputNumber[/code] being [SpinBoxExt] or [code]BowPromptInputBoolean[/code] being [StateButton].
		func to_view(with_runtime: Bow = null) -> Control:
			var container := BoxContainer.new()
			container.set_vertical(true)
			container.set_theme_type_variation("BowPrompt")
			var question = self.question if with_runtime == null else with_runtime._produce_responsive_text(self.question)
			if question.length() > 0:
				var rich_q := RichTextLabel.new()
				rich_q.set_text(question)
				rich_q.set_use_bbcode(true)
				rich_q.set_fit_content(true)
				rich_q.set_autowrap_mode(TextServer.AutowrapMode.AUTOWRAP_WORD_SMART)
				rich_q.set_theme_type_variation("BowPromptQuestion")
				container.add_child(rich_q)
			# ...
			var input_control = input.to_view()
			container.add_child(input_control)
			# ...
			var buttons := BoxContainer.new()
			buttons.set_vertical(false)
			buttons.set_theme_type_variation("BowPromptButtons")
			var reset := ButtonExt.new()
			reset.set_text(self.reset)
			reset.set_theme_type_variation("BowPromptReset")
			reset.pressed.connect(
				func():
					var valid_value = self.input.reset(input_control)
			)
			buttons.add_child(reset)
			var submit := ButtonExt.new()
			submit.set_text(self.submit)
			submit.set_theme_type_variation("BowPromptSubmit")
			# ...
			var _play_handler = func():
				var valid_value = self.input.validate(input_control)
				if valid_value != null:
					reset.set_disabled(true)
					reset.set_visible(false)
					submit.set_disabled(true)
					submit.set_visible(false)
					if played == false && with_runtime != null:
						var next = [ Instruction.manage( State.Update.variable( Variables.Update.reset(self.target, valid_value) ) ) ]
						for also in self.following:
							next.push_back(also)
						with_runtime.run(next)
					played = true
			# ...
			if with_runtime != null:
				submit.pressed.connect(_play_handler)
			else:
				print_debug("WARN! naturally interactive prompt `with_runtime` being null preventing us to feedback the instructions: ", self)
			buttons.add_child(submit)
			container.add_child(buttons)
			if played: # NOTE: If it is already marked played, the input must be played with valid value too.
				_play_handler.call_deferred()
			return container
		# ...
		# ...
		class BooleanInput:
			extends Resource
			## Negative message or option text to customize input appearance
			var negative: String
			## Positive message or option text to customize input appearance
			var positive: String
			## Default and/or preset value for the input (control)
			var default: bool
			## As a part of Prompt, an interactive element which should keep its play state,
			## this inner input type keeps the played (i.e. last validated) value to help with that.
			## Null means no input is validated yet (so probably not played).
			var played = null
			## Creates a new Boolean prompt input.
			func _init(negative: String, positive: String, default: bool) -> void:
				self.negative = negative
				self.positive = positive
				self.default = default
			## Serializes the BooleanInput to basic Godot types.
			func pack() -> Dictionary:
				return {
					"negative": self.negative, "positive": self.positive, "default": self.default,
					"played": self.played,
				}
			## Deserializes a BooleanInput from a dictionary made by [method pack].
			static func unpack(from: Dictionary) -> BooleanInput:
				var new = BooleanInput.new(from.negative, from.positive, from.default)
				new.played = from.played
				return new
			## Helps printing the BooleanInput resource.
			func _to_string():
				return "BooleanInput { negative = %s, positive = %s, default = %s, played = %s }" % [negative, positive, default, played]
			## Resets the input to the default value.
			func reset(input: StateButton):
				var fixed = played if played != null else self.default
				input.set_current(1 if fixed else 0)
			## Returns the valid user input or null.[br]
			## NOTE: Boolean inputs does not have any special quality to be validated.
			## We pass the negative selection as valid false and any other selection as valid true and default on no selection.
			func validate(input: StateButton, lock_on_valid: bool = true):
				var selected = input.get_current()
				input.set_disabled(lock_on_valid)
				input.set_focus_mode(Control.FocusMode.FOCUS_NONE if lock_on_valid else Control.FocusMode.FOCUS_ALL)
				played = played if played != null else (self.default if selected == -1 else selected != 0)
				return played
			## Creates control(s) to capture user input.
			func to_view() -> Control:
				var current = played if played != null else self.default
				var control := StateButton.new()
				control.set_states([self.negative, self.positive])
				control.set_current(1 if current else 0)
				control.set_theme_type_variation("BowPromptInputBoolean")
				return control
		# ...
		class NumberInput:
			extends Resource
			## *Inclusive* upper limit for the input
			var min: int
			## *Inclusive* lower limit for the input
			var max: int
			## Input distance from minimum limit, shall be a factor of this value.
			var step: int
			## Default and/or preset value for the input (control)
			var default: int
			## As a part of Prompt, an interactive element which should keep its play state,
			## this inner input type keeps the played (i.e. last validated) value to help with that.
			## Null means no input is validated yet (so probably not played).
			var played = null
			## Creates a new Number prompt input.
			func _init(min: int, max: int, step: int, default: int) -> void:
				self.min = min
				self.max = max
				self.step = step
				self.default = default
			## Serializes the NumberInput to basic Godot types.
			func pack() -> Dictionary:
				return {
					"min": self.min, "max": self.max, "step": self.step, "default": self.default,
					"played": self.played,
				}
			## Deserializes a NumberInput from a dictionary made by [method pack].
			static func unpack(from: Dictionary) -> NumberInput:
				var new = NumberInput.new(from.min, from.max, from.step, from.default)
				new.played = from.played
				return new
			## Helps printing the NumberInput resource.
			func _to_string():
				return "NumberInput { min = %s, max = %s, step = %s, default = %s, played = %s }" % [min, max, step, default, played]
			## Resets the input to the default value.
			func reset(input: SpinBoxExt):
				var fixed = played if played != null else self.default
				input.set_value(fixed)
			## Returns the valid user input or null.
			func validate(input: SpinBoxExt, lock_on_valid: bool = true):
				input.apply()
				var value = played if played != null else int(input.get_value())
				if self.min <= self.max:
					if self.min == self.max:
						# Although this is not allowed by the Arrow (editor) node's inspector anymore,
						# we still let singular values to pass for backward compatibility
						if value != self.min:
							value = null
					else: # ( self.min < self.max)
						if value < self.min || value > self.max:
							value = null
						else: # It is in range; but is it stepped properly?
							if (
								# (Conventionally invalid step parameters are ignored and any value in range can pass)
								self.step >= 1 && self.step <= abs(self.max - self.min) && abs(value - self.min) % self.step != 0
							):
								value = null
				else:
					printerr("invalid number input for prompt element: min > max! (default value used)")
					value = self.default
				if value != null:
					input.set_editable( ! lock_on_valid )
					input.get_line_edit().set_focus_mode(Control.FocusMode.FOCUS_NONE if lock_on_valid else Control.FocusMode.FOCUS_ALL)
				played = value
				return played
			## Creates control(s) to capture user input.
			func to_view() -> Control:
				var current = played if played != null else self.default
				var control := SpinBoxExt.new()
				control.set_min(self.min)
				control.set_allow_lesser(false)
				control.set_max(self.max)
				control.set_allow_greater(false)
				control.set_step(self.step)
				control.set_value(current)
				control.apply()
				control.set_theme_type_variation("BowPromptInputNumber")
				return control
		# ...
		class TextInput:
			extends Resource
			## Regular Expression (~ PCRE2 supported by Godot & Arrow) that valid input shall match.
			## NOTE: Blank patterns pass any value and invalid/non-compilable regexp would not allow any value returning default!
			var pattern: String
			## Default and/or preset value for the input (control)
			var default: String
			## Information, hit/tooltip, placeholder, etc. depending on the runtime implementation
			var hint: String
			## As a part of Prompt, an interactive element which should keep its play state,
			## this inner input type keeps the played (i.e. last validated) value to help with that.
			## Null means no input is validated yet (so probably not played).
			var played = null
			## Creates a new Text prompt input.
			func _init(pattern: String, default: String, hint: String) -> void:
				self.pattern = pattern
				self.default = default
				self.hint = hint
			## Serializes the TextInput to basic Godot types.
			func pack() -> Dictionary:
				return {
					"pattern": self.pattern, "default": self.default, "hint": self.hint,
					"played": self.played,
				}
			## Deserializes a TextInput from a dictionary made by [method pack].
			static func unpack(from: Dictionary) -> TextInput:
				var new = TextInput.new(from.pattern, from.default, from.hint)
				new.played = from.played
				return new
			## Helps printing the TextInput resource.
			func _to_string():
				return "TextInput { pattern = %s, default = %s, hint = %s, played = %s }" % [pattern, default, hint, played]
			## Resets the input to the default value.
			func reset(input: LineEditExt):
				var fixed = played if played != null else self.default
				input.set_text(fixed)
			## Returns the valid user input or null.
			func validate(input: LineEditExt, lock_on_valid: bool = true):
				var value = played if played != null else input.get_text()
				if self.pattern.length() > 0: # (Conventionally we pass any value for blank patterns)
					var regex = RegEx.new()
					var compiled = regex.compile(self.pattern)
					if compiled == OK:
						# RegEx.search() returns RegExMatch if found, otherwise `null`
						var matched = regex.search(value)
						if matched == null || matched.get_string(0) != value: # (i.e. no match or not exact)
							value = null # just invalid value (no structural error)
					else:
						printerr("invalid text input for prompt element: invalid RegEx! (default value used)")
						value = self.default
				if value != null:
					input.set_editable( ! lock_on_valid )
					input.set_focus_mode(Control.FocusMode.FOCUS_NONE if lock_on_valid else Control.FocusMode.FOCUS_ALL)
				played = value
				return played
			## Creates control(s) to capture user input.
			func to_view() -> Control:
				var current = played if played != null else self.default
				var control := LineEditExt.new()
				control.set_text(current)
				control.set_placeholder(self.hint)
				control.set_theme_type_variation("BowPromptInputText")
				return control
	## Creates a Prompt Element.
	static func prompt(input, target: int, question: String, following: Array, submit: String = "BOW_PROMPT_SUBMIT", reset: String = "BOW_PROMPT_RESET") -> Element:
		return Element.new( Element.Prompt.new(input, target, question, following, submit, reset) )

## A Voice Description Resource
##
class Voice:
	extends Resource
	## The voice pure filename without parent directory or extension
	var audio: String
	## Parent directory of the audio file optionally set
	## if this file should be fetched from another directory other than the Consoles's default
	var dir: String
	## Extension of the audio file (e.g. "mp3") again optional just like [member dir]
	var ext: String
	## Alternative text version of the audio for TTS or timer fallback according to the circumstances.
	## NOTE: This array of strings will be translated and exposed one by one, then merged to create a particular piece of text.
	var alt: Array[String]
	## Helps printing the Voice resource.
	func _to_string():
		return "Voice { audio = %s, dir = %s, ext = %s, alt = %s }" % [audio, dir, ext, alt]
	## Initializes a new Voice.
	func _init(audio: String, alt: Array[String], dir: String = "", ext: String = "") -> void:
		self.audio = audio
		self.dir = dir
		self.ext = ext
		self.alt = alt
	## Serializes the Voice to basic Godot types.
	func pack() -> Dictionary:
		return { "audio": self.audio, "dir": self.dir, "ext": self.ext, "alt": self.alt }
	## Deserializes a Voice from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Voice:
		return Voice.new(from.audio, from.alt, from.dir, from.ext)
	## Returns the expected audio file path, regarding the default arguments and the voice data.
	func file_path(default_dir: String, default_ext: String) -> String:
		var extension = self.ext if self.ext.length() > 0 else default_ext
		var directory = self.dir if self.dir.length() > 0 else default_dir
		var tuned_ext = (".%s" % extension) if (extension.begins_with(".") == false && extension.length() > 0) else extension
		return "%s%s" % [directory.path_join(self.audio), tuned_ext]
	## Creates a uniform piece of text from [member alt] strings after processing them with runtime if any.
	func process_alt(with_runtime: Bow = null, separator: StringName = "") -> String:
		var pieces = self.alt.map(with_runtime._produce_responsive_text.bind(true)) if with_runtime != null else self.alt
		return separator.join(pieces)

## A Group of View Elements
##
class Block:
	extends Resource
	## ID of the node producing this block
	var producer: int
	## Array of [Bow.Element]s in the order produced by the [Bow.ArwNode]
	var elements: Array[Element]
	## Array of [Bow.Voice]s in the order produced by the [Bow.ArwNode]
	var voices: Array[Voice]
	## A block may belong to a character (e.g. a dialog line) or not (e.g. an interaction line) hence the owner being a character or null.
	var owner: Character = null
	## Hints the final user of the block (view renderer) to print this block into a clear stack.
	var clear: bool = false
	## Helps printing the Block resource.
	func _to_string():
		return "Block { producer = %s, elements = %s, owner = %s, clear = %s }" % [producer, elements, owner, clear]
	## Initializes a new Block.
	func _init(producer: int, elements: Array[Element], voices: Array[Voice] = [], owner: Character = null, clear: bool = false) -> void:
		self.producer = producer
		self.elements = elements
		self.voices = voices
		self.owner = owner
		self.clear = clear
	## Serializes the Block to basic Godot types.
	func pack() -> Dictionary:
		return {
			"producer": self.producer,
			"elements": self.elements.map( func(e): return e.pack() ),
			"voices": self.voices.map( func(v): return v.pack() ),
			"owner": null if self.owner == null else self.owner.pack(),
			"clear": self.clear,
		}
	## Deserializes a Block from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Block:
		var unpacked_elements: Array[Element] = []
		for element in from.elements:
			unpacked_elements.push_back(Element.unpack(element))
		var unpacked_voices: Array[Voice] = []
		for voice in from.voices:
			unpacked_voices.push_back(Voice.unpack(voice))
		var packed_owner = Character.unpack(from.owner) if from.owner is Dictionary else null
		return Block.new(from.producer, unpacked_elements, unpacked_voices, packed_owner, from.clear)

## Queue of the Printed Blocks
##
class Queue:
	extends Resource
	## Deck of [Bow.Block]s in the order they've been printed
	var blocks: Array[Block] = []
	## Serializes the Queue to basic Godot types.
	func pack() -> Dictionary:
		var packed_blocks = []
		for block in self.blocks:
			packed_blocks.push_back(block.pack())
		return { "blocks": packed_blocks }
	## Deserializes a Queue from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Queue:
		var new = Queue.new()
		for block in from.blocks:
			new.blocks.push_back(Block.unpack(block))
		return new
	## Helps printing this custom resource in a more human readable form.
	func _to_string() -> String:
		return "Queue %s" % blocks
	## Appends new blocks to the back of the queue.
	func push(back: Array[Block]) -> void:
		for block in back:
			self.blocks.push_back(block)
	## Takes out the oldest printed block (front), or null if the queue is empty (all consumed).
	func pull():
		return self.blocks.pop_front()

## Runtime Instruction
##
## Instructions can be used with [method Bow.run] to push the narrative forward, manipulate its state, etc.
class Instruction:
	extends Resource
	enum Kind { OPEN, FORWARD, MANAGE, PRINT, SCOPE, FORCE_FORWARD }
	## Indicates of what type this instruction is, defining its purpose.
	var kind: Kind
	## Defines parameters of the instruction depending on what kind it is.
	var params
	## Initializes a new Instruction. [br]
	## NOTE: It is safer, more convenient and recommended to use this class's dedicated methods such as
	## [method open], [method forward], [method manage], [method print], etc. to create instructions.
	func _init(kind: Kind, params) -> void:
		self.kind = kind
		self.params = params
	## Serializes the Instruction to basic Godot types.
	func pack() -> Dictionary:
		# NOTE: Some parameters like a bunch of blocks, need special packing due to static array types, etc.
		var packed_params = []
		match self.kind:
			Kind.PRINT:
				packed_params = self.params.map( func(p): return p.pack() )
			_:
				packed_params = self.params
		return { "kind": self.kind, "params": packed_params }
	## Deserializes an Instruction from a dictionary made by [method pack].
	static func unpack(from: Dictionary) -> Instruction:
		var unpacked_params
		match from.kind:
			Kind.PRINT:
				var unpacked_blocks: Array[Block] = []
				for packed in from.params:
					unpacked_blocks.push_back(Block.unpack(packed))
				unpacked_params = unpacked_blocks
			_:
				unpacked_params = from.params
		return Instruction.new(from.kind, unpacked_params)
	## Helps printing an Instruction resource.
	func _to_string():
		match self.kind:
			Kind.OPEN:
				return "🡢 OPEN: chapter = %s, auto-run = %s" % params
			Kind.FORWARD:
				return "🡢 FORWARD: node = %s, slot = %s" % params
			Kind.SCOPE:
				return "🡢 SCOPE: level = %s, custom_entry = %s, resume = %s" % params
			Kind.MANAGE:
				return "🡢 MANAGE: %s" % params
			Kind.PRINT:
				return "🡢 PRINT: %s" % params
			Kind.FORCE_FORWARD:
				return "🡢 FORCE_FORWARD!"
			_ :
				return "🡢 Unknown: %s" % params
	## Creates an OPEN instruction to load a new chapter by integer ID or title string (first found) to the runtime.[br]
	## NOTE: If [code]auto_run: bool = true[/code] is set (default), we will immediately FORWARD to the chapter's defined entry.
	static func open(chapter, auto_run: bool = true) -> Instruction:
		return Instruction.new(Instruction.Kind.OPEN, [chapter, auto_run])
	## Creates a FORWARD instruction to move to the next node with the provided ID and incoming slot.
	static func forward(node: int, slot: int = DEFAULT_INCOMING_SLOT) -> Instruction:
		return Instruction.new(Instruction.Kind.FORWARD, [node, slot])
	## Creates a SCOPE instruction to move into a deeper nested scene/macro.
	static func scope(level: int, custom_entry: Array[int] = [], resume: Array[int] = []) -> Instruction:
		return Instruction.new(Instruction.Kind.SCOPE, [level, custom_entry, resume])
	## Creates a MANAGE instruction to update state of the runtime.
	static func manage(change: State.Update) -> Instruction:
		return Instruction.new(Instruction.Kind.MANAGE, change)
	## Creates a PRINT instruction to add a new block of view elements or more to the runtime queue.
	static func print(blocks: Array[Block]) -> Instruction:
		return Instruction.new(Instruction.Kind.PRINT, blocks)
	## Creates a FORCE_FORWARD instruction (with no params) that will signal/suggest the console to skip currently playing parts.
	static func ffw() -> Instruction:
		return Instruction.new(Instruction.Kind.FORCE_FORWARD, null)

func _reload_translation_resources() -> void:
	var locales = (
		self.translation_locales
		if self.translation_locales.size() > 0 else
		%Preferences.detect_available_tr_languages()[0]
	)
	for id in self.chapters_list._list:
		var path_chapter = self.translations_path.replacen("{chapter}", self.chapters_list._list[id].filename)
		for lang in locales:
			var path_chapter_lang = path_chapter.replacen("{lang}", lang)
			var translation: Translation = ResourceLoader.load(path_chapter_lang, "Translation", ResourceLoader.CacheMode.CACHE_MODE_REUSE)
			TranslationServer.add_translation(translation)

## Re-loads [member chapters_list] from the [member listing_file] if defined and existing.
## Unless called with [code]force = true[/code], it avoids refreshing already loaded [member chapters_list].
func relist(force: bool = false) -> void:
	if force || self.chapters_list == null || self.chapters_list.is_empty():
		self.chapters_list = ChaptersList.from_arrow_projects_file(listing_file)
		_reload_translation_resources()

func initialize() -> void:
	if self.reset_state_on_begin != false:
		self.scopes = []
		self.queue = Queue.new()
		self.state = State.new()
	else:
		if scopes == null:
			self.scopes = []
		if queue == null:
			self.queue = Queue.new()
		if self.state == null:
			self.state = State.new()

## Loads proper [member chapters] from the document defined by [member chapters_list]
## with [member entry_chapter] ID and runs it from [member entry_node] & [member entry_slot].
func begin() -> void:
	self.relist()
	self.initialize()
	self.run([
		Instruction.open(
			self.entry_chapter if self.entry_chapter > 0 else self.chapters_list.entry_or_least_id(),
			false # (~ We want to use the plugin's entry properties first, so manual forward is used. See lines below.)
		)
	])
	self.run([
		Instruction.forward(
			self.entry_node if self.entry_node > 0 else self.chapter.entry,
			self.entry_slot if self.entry_slot > 0 else DEFAULT_INCOMING_SLOT
		)
	])

## Plays a node with the provided parameters and current state of the variables, characters, etc. [br]
## NOTE: It is a method designed for internal purposes.
## Also note that playing a node does not change the runtime and only creates the node's desired instructions.
func _play_node(id: int, slot_in: int = DEFAULT_INCOMING_SLOT) -> Array: # Array[Instruction]
	var node_map = null
	var holder = self.chapter.resources.scenes.locate(id)
	if holder != null:
		node_map = holder.chart(id)
	if node_map == null:
		node_map = NodeMap.new()
		print_debug("node %s is not mapped in any of the scenes; an empty map will be used if the node exists" % id)
	# ...
	var node = self.chapter.resources.nodes.fetch(id)
	if node != null:
		return node.play(node_map, self.state, self.ctx, slot_in)
	else:
		print_debug("trying to play node %s which belongs to no scene (ignore if intentional EOL)" % id)
		return []

## Creates and adds a new level to the current [member scopes].
## Returns instruction set to go FORWARD with the scope's custom or default entry.
## Prints error and returns empty array if the scope is not valid.[br][br]
## Parameters include: a valid scene-ID as [code]level[/code],
## an array of [node-ID and optionally incoming slot index] or empty as [code]custom_entry[/code]
## and a similar array for the [code]resume[/code] point of the scope. [br]
## NOTE: We use custom entry and resume anyway even if they are not valid (which may result in EOL).
func _scope_in(level: int, custom_entry: Array[int] = [], resume: Array[int] = []) -> Array: # Array[Instruction]
	var scene = self.chapter.resources.scenes.fetch(level)
	if scene != null:
		if resume.size() > 0 && self.chapter.resources.scenes.locate(resume[0]) == null:
			print_debug("WARN! resume point used for the level %s does not seem valid: " % level, resume)
		# anyway ...
		# we should scope a level deeper:
		self.scopes.push_back( Scope.new(level, resume) )
		# and then instruct to enter/start that scope (nested macro) as well:
		if custom_entry.size() > 0:
			if scene.has_node(custom_entry[0]) == false:
				print_debug("WARN! custom entry used for the level %s does not seem valid: " % level, custom_entry)
			# anyway ...
			return [ Instruction.forward(custom_entry[0], custom_entry[1] if custom_entry.size() > 1 else DEFAULT_INCOMING_SLOT) ]
		else:
			return [ Instruction.forward(scene.entry, DEFAULT_INCOMING_SLOT) ]
	else:
		printerr("trying to `_scope_in` with a non-existent level %s (ignored)" % level)
		return []

## Pops one scope level (un-nesting) out or null if we are on the root already.
func _scope_out():
	var level_out = self.scopes.pop_back()
	if level_out != null:
		if level_out.resume.size() > 0:
			print_debug("scoped out of: ", level_out)
			return level_out
		else:
			return self._scope_out()
	else:
		print_debug("scoped out of nested scenes (macros) reaching root")
		return null

## Rearranges scopes until we get to the holder of the node with provided ID or root (no scope).
func _re_scope_for(node: int) -> void:
	while self.scopes.size() > 0:
		var deepest = self.scopes.back()
		var scene = self.chapter.resources.scenes.fetch(deepest.level);
		if scene != null:
			if scene.has_node(node):
				print_debug("re-scoped back up to holder of node %s : " % node, deepest)
				return;
			else:
				self.scopes.pop_back() # ~ `deepest` was on the `.back()`
				print_debug("scoped out of: ", deepest)
		else:
			print_debug("WARN! scopes anomaly! scope with level corresponding to no scene (dropped): ", deepest)
			self.scopes.pop_back()

## Runs a set of instructions to manipulate the runtime or push it forward.
func run(instructions: Array): # Array[Instruction]
	print_debug("Run: ", instructions)
	self.sync_with_preferences()
	for instruction in instructions:
		match instruction.kind:
			Instruction.Kind.OPEN:
				var chapter_id_or_title = instruction.params[0];
				var chapter_filename = self.chapters_list.chapter_filename(chapter_id_or_title)
				print_debug("Opening chapter ", chapter_id_or_title, " : ", chapter_filename)
				if chapter_filename != null:
					self.loaded = chapter_id_or_title
					self.loaded_filename = chapter_filename
					self.scopes = []
					self.chapter = Chapter.from_file(
						self.documents_dir.path_join(chapter_filename + ARROW_DOC_EXTENSION)
					)
					self.state.refill_with(self.chapter)
					self.chapter_opened.emit()
					# ...
					var auto_run = instruction.params[1];
					if auto_run == true:
						self.run([
							Instruction.forward(self.chapter.entry, DEFAULT_INCOMING_SLOT)
						])
				else:
					printerr("no chapter with such ID or name is listed: ", instruction.params)
					self.eol.emit()
			Instruction.Kind.FORWARD:
				var node = instruction.params[0]
				var slot_in = instruction.params[1]
				if node <= INVALID_NODE_ID: # EOL
					# Scope out and reset node and slot to the resume point
					# in order to continue from parent level
					var previous = self._scope_out()
					if previous != null && previous.resume.size() > 0:
						node =  previous.resume[0]
						slot_in = previous.resume[1] if previous.resume.size() > 1 else DEFAULT_INCOMING_SLOT
				else:
					# Re-scope to the holder of the node
					self._re_scope_for(node)
				# If we now what node should be finally played
				var next = self._play_node(node, slot_in)
				if next.size() > 0:
					self.run(next)
				else:
					print_debug("EOL")
					self.eol.emit()
			Instruction.Kind.MANAGE:
				self.state.update(instruction.params)
				self.state_updated.emit()
			Instruction.Kind.PRINT:
				self.queue.push(instruction.params)
				self.queue_updated.emit()
			Instruction.Kind.FORCE_FORWARD:
				self.force_forward.emit()
			Instruction.Kind.SCOPE:
				# We try to open the scope,
				# then we can continue with returned instructions playing custom or default scene's entry.
				var next = self._scope_in.callv(instruction.params)
				if next.size() > 0:
					self.run(next)
				else:
					self.eol.emit()

# DEV:
# Many pack and unpack methods are developed to workaround some of
# current limitations of GODOT when saving custom typed data;
# but they can be helpful in case you want to
# implement custom serialization as well.

func _pack_scopes() -> Array[Dictionary]:
	var packed: Array[Dictionary] = []
	for scope in self.scopes:
		packed.push_back(scope.pack())
	return packed

func _unpack_scopes(from: Array[Dictionary]) -> void:
	var unpacked: Array[Scope] = []
	for packed_scope in from:
		unpacked.push_back(Scope.unpack(packed_scope))
	self.scopes = unpacked

func _is_savable() -> bool:
	return self.loaded != null

## Packs current state of the runtime which can be used alongside your other gameplay states to save a game session. [br]
## NOTE: Remember that packing the runtime state is not enough for your game to be saved,
## you should store the gameplay, already consumed [member queue] blocks, and more.
func pack() -> Dictionary:
	var internals = {
		"chapters_list": self.chapters_list.pack(),
		"loaded": self.loaded,
		# DEV: We don't need to keep the whole chapter, when we can simply open it from the `loaded` address again.
		# "chapter": self.chapter,
		"scopes": _pack_scopes(),
		"state": self.state.pack(),
		"queue": self.queue.pack(),
	}
	return {
		"internals": internals,
		"checksum": internals.hash()
	}

## This method is for internal purposes. Please use [method unpack] instead.
## NOTE: This method ignores any packed data that is not of the expected type.
func _unpack_internals(from: Dictionary) -> void:
	self.chapters_list = ChaptersList.unpack(from.chapters_list)
	_reload_translation_resources()
	_unpack_scopes(from.scopes)
	self.state = State.unpack(from.state)
	self.queue = Queue.unpack(from.queue)
	# ...
	self.run([ Instruction.open(from.loaded, false) ])

## Reloads a saved state created with [method pack] method, into this runtime. Returns true if data is used. [br]
## CAUTION! This method only does a checksum validation (if provided with the package) and little to no other checks.
## That is suitable for most of the scenarios and in general to reduce risk of loading corrupt data.
## But if you really need to go beyond that you may develop your own advanced integrity check mechanisms. [br]
## NOTE: Remember that unpacking the runtime state is not enough for your game to be restored,
## you should restore the gameplay, already consumed [member queue] blocks, and more.
func unpack(from: Dictionary) -> bool:
	if from.has("internals"):
		if from.internals is Dictionary:
			if from.has("checksum"):
				if from.checksum is int:
					if from.internals.hash() == from.checksum:
						self._unpack_internals(from.internals)
						return true
					else:
						printerr("unpacking from corrupt data: `internals` didn't match `checksum`")
				else:
					printerr("unpacking from unsupported data: invalid `checksum` (expected int hash)")
			else:
				print_debug("WARN! unpacking `internals` with no `checksum` to test")
				self._unpack_internals(from.internals)
				return true
		else:
			printerr("unpacking from unsupported data: invalid `internals` (expected Dictionary)")
	else:
		printerr("unpacking from unsupported data: missing `internals`")
	return false

## This method is designed to be a bridge between your Preferences manager module and Bow.
## Every time a change in the user preferences is made, this should be called, maybe by propagation,
## to sync the preferences with the loaded Arrow chapters, via [member state].
## It should also be called at least when the state is being (re-)initialized,
## to make sure they are in sync, even if no further change (e.g. [member _on_preference]) is signalled or propagated.[br]
## NOTE: Currently we sync before each [member run], but if it is too many times for you, you need to edit the code.[br]
## Syncing allows preferences to be accessible by chapters (Arrow documents) via variables and character tags.
## Currently the following are bridged:[br]
## + [code]_debug[/code] (bool var) reflecting if the game is exported with debug flag. [br]
## + [code]_screen_reader[/code] (num var) showing the [code]accessibility.screen_reader_mode[/code]
## (0: Disabled, 1: UI, 2: UI & Fallback, 3<: Everywhere); which can be used to alter content if something is going to be read aloud. [br]
## + [code]_hint_level[/code] (num var) representing [code]accessibility.cognitive_hint_level[/code]. [br]
## + [code]_sensory_intensity_level[/code] (num var) representing [code]accessibility.cognitive_sensory_intensity_level[/code]
## to control intensity level of audio-visual and/or narrative sensory stimuli, such as jump-scares, etc. [br]
## + [code]_moderation_level[/code] (num var) [code]content.moderation_level[/code] as a general measure, although the [code]_restricted[/code] would be a better utility. [br]
## + [code]_locale[/code] (str var) reflecting [code]display.language[/code] useful for culture-sensitive narration, etc. [br]
## + [code]_restricted[/code] (character) reflecting the filtered out subjects (in snake_case) whether by [code]content.moderation_custom[/code] or presets of [code]content.moderation_level[/code]. [br]
## NOTE: The preferences are synced using their name, so the UUID does not matter, but it is always good hygiene
## to make sure shared variables and characters hold the same UUIDs and unique name among multiple chapters to avoid re-initialization and confusion.
func sync_with_preferences() -> void:
	if self.state != null:
		# Variables
		self.state.variables._force_reset_value("_debug", OS.is_debug_build())
		var updates = [
			["_screen_reader", "accessibility", "screen_reader_mode"],
			["_hint_level", "accessibility", "cognitive_hint_level"],
			["_sensory_intensity_level", "accessibility", "cognitive_sensory_intensity_level"],
			["_moderation_level", "content", "moderation_level"],
			["_locale", "display", "language"],
		]
		for update in updates:
			self.state.variables._force_reset_value(update[0], %Preferences.current(update[1], update[2]))
		# Characters
		# (_restricted: Moderation Filters)
		var filters_as_tags := {}
		for filter in %Preferences.get_moderation_filters():
			filters_as_tags[filter.to_snake_case()] = "" # Blank (key-only) tag is enough here to detect filtered subjects.
		print(self.state.characters._force_reset_tags("_restricted", filters_as_tags))
		# And finally signal the change.
		self.state_updated.emit()

# DEV: This is a propagated method by Preferences script.
func _on_preference(group, setting, _current_value) -> void:
	self.sync_with_preferences()