fix: Optimized ESC command docs (#450)

Co-authored-by: Dennis Ploeger <develop@dieploegers.de>
Co-authored-by: Duncan Brown <duncan@bhs-consultants.com>

addons/escoria-core/game/core-scripts/esc/commands/accept_input.gd

@@ -1,13 +1,20 @@
-# `accept_input [ALL|NONE|SKIP]`
+# `accept_input [type]`
 #
-# What type of input does the game accept. ALL is the default, SKIP allows 
+# Sets how much input the game is to accept, allowing for cut scenes
-# skipping of dialog but nothing else, NONE denies all input. Including opening 
+# in which dialog can be skipped (if [type] is set to SKIP).
-# the menu etc. SKIP and NONE also disable autosaves.
+# Also allows for cut scenes that can be completely locked down.
 #
-# *Note* that SKIP gets reset to ALL when the event is done, but NONE persists. 
+# **Parameters**
-# This allows you to create cut scenes with SKIP where the dialog can be 
+#
-# skipped, but also initiate locked#### down cutscenes with accept_input 
+# - *type*: Type of inputs to accept (ALL)
-# NONE in :setup and accept_input ALL later in :ready.
+#   `ALL`: Accept all types of input
+#   `SKIP`: Accept skipping dialogs but nothing else
+#   `NONE`: Deny all inputs (including opening menus)
+#
+# **Warning**: `SKIP` and `NONE` also disable autosaves.
+#
+# **Note**: If `SKIP` is specified, it will be reset to `ALL` when the event has
+# finished. `NONE` persists even after the event.
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/anim.gd

@@ -1,10 +1,14 @@
 # `anim object name [reverse]`
 #
-# Executes the animation specificed with the "name" parameter on the object, 
+# Executes the animation specified in "name" on "object", 
 # without blocking. The next command in the event will be executed immediately 
-# after. Optional parameters:
+# after.
 #
-# * `reverse`: plays the animation in reverse when true
+# **Parameters**
+#
+# * *object*: Global ID of the object with the animation
+# * *name*: Name of the animation to play
+# * *reverse*: Plays the animation in reverse when true
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/anim_block.gd

@@ -1,10 +1,14 @@
 # `anim_block object name [reverse]`
 #
-# Executes the animation specificed with the "name" parameter on the object, 
+# Executes the animation specified in "name" on "object", 
-# blocking. The next command in the event will be executed when the animation 
+# while blocking. The next command in the event will be executed when the animation 
-# is finished playing. Optional parameters:
+# is finished playing.
 #
-# * `reverse`: plays the animation in reverse when true
+# **Parameters**
+#
+# * *object*: Global ID of the object with the animation
+# * *name*: Name of the animation to play
+# * *reverse*: Plays the animation in reverse when true
 # 
 # @ESC
 extends ESCBaseCommand
@@ -44,6 +48,8 @@ func run(command_params: Array) -> int:
 		animator.play_backwards(anim_id)
 	else:
 		animator.play(anim_id)
+	if animator.get_length(anim_id) < 1.0:
+		return ESCExecution.RC_OK
 	var animation_finished = yield(animator, "animation_finished")
 	while animation_finished != anim_id:
 		animation_finished = yield(animator, "animation_finished")

addons/escoria-core/game/core-scripts/esc/commands/camera_push.gd

@@ -1,9 +1,21 @@
 # `camera_push target [time] [type]`
 #
-# Push camera to `target`. Target must have camera_pos set. If it's of type 
+# Pushes the camera to point at a specific `target`.
-# Camera2D, its zoom will be used as well as position. `type` is any of the 
+#
-# Tween.TransitionType values without the prefix, eg. LINEAR, QUART or CIRC; 
+# **Parameters**
-# defaults to QUART. A `time` value of 0 will set the camera immediately.
+#
+# - *target*: Global ID of the `ESCItem` to push the camera to. If the target 
+#   has a child node called `camera_node`, its location will be used. If not,
+#   the location of the target will be used
+# - *time*: Number of seconds the transition should take (default: `1`)
+# - *type*: Transition type to use (default: `QUAD`)
+#
+# Supported transitions include the names of the values used 
+# in the "TransitionType" enum of the "Tween" type (without the "TRANS_" prefix):
+#
+# https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/camera_set_limits.gd

@@ -1,9 +1,13 @@
 # `camera_set_limits camlimits_id`
 #
-# Sets the camera limits to the one defined under `camlimits_id` in ESCRoom's 
+# Activates the current camera's limits
-# camera_limits array.
+#
-# - camlimits_id: int: id of the camera limits to apply (defined in ESCRoom's 
+# **Parameters**
-#   camera_limits array)
+#
+# - *camlimits_id*: Index of the camera limit in the `camera limits` 
+#   list of the current `ESCRoom`
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/camera_set_pos.gd

@@ -1,8 +1,14 @@
 # `camera_set_pos speed x y`
 #
-# Moves the camera to a position defined by "x" and "y", at the speed defined 
+# Moves the camera to the given position.
-# by "speed" in pixels per second. If speed is 0, camera is teleported to the 
+#
-# position.
+# **Parameters**
+#
+# - *speed*: Number of seconds the transition should take
+# - *x*: Target X coordinate
+# - "y*: Target Y coordinate
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/camera_set_target.gd

@@ -1,8 +1,13 @@
 # `camera_set_target speed object`
 #
-# Configures the camera to set the target to the given `object`using `speed`
+# Configures the camera to follow the specified target `object`
-# as speed limit. 
+#
-# This is the default behavior (default follow object is "player"). 
+# **Parameters**
+#
+# - *speed*: Number of seconds the transition should take
+# - *object*: Global ID of the target object
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand
@@ -22,7 +27,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[1]):
 		escoria.logger.report_errors(
-			"camera_set_pos: invalid object",
+			"camera_set_target: invalid object",
 			[
 				"Object with global id %s not found" % arguments[1]
 			]

addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom.gd

@@ -1,9 +1,16 @@
 # `camera_set_zoom magnitude [time]`
 #
-# Zooms the camera in/out to the desired `magnitude`. Values larger than 1 zooms 
+# Zooms the camera in/out to the desired `magnitude`. Values larger than 1 zoom 
-# the camera out, and smaller values zooms in, relative to the default value 
+# the camera out while smaller values zoom in, relative to the default value 
-# of 1. An optional `time` in seconds controls how long it takes for the camera 
+# of 1.
-# to zoom into position.
+#
+# **Parameters**
+#
+# - *magnitude*: Magnitude of zoom
+# - *time*: Number of seconds the transition should take, with a value of `0`
+#   meaning the zoom should happen instantly (default: `0`)
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom_height.gd

@@ -1,8 +1,14 @@
 # `camera_set_zoom_height pixels [time]`
 #
-# Zooms the camera in/out to the desired `pixels` height. 
+# Zooms the camera in/out so it occupies the given height in pixels
-# An optional `time` in seconds controls how long it takes for the camera 
+#
-# to zoom into position.
+# **Parameters**
+#
+# - *pixels*: Target height in pixels
+# - *time*: Number of seconds the transition should take, with a value of `0`
+#   meaning the zoom should happen instantly (default: `0`)
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/camera_shift.gd

@@ -1,8 +1,21 @@
 # `camera_shift x y [time] [type]`
 #
-# Shift camera by `x` and `y` pixels over `time` seconds. `type` is any of the 
+# Shifts the camera by the given horizontal and vertical amounts.
-# Tween.TransitionType values without the prefix, eg. LINEAR, QUART or CIRC; 
+#
-# defaults to QUART.
+# **Parameters**
+#
+# - *x*: Shift by x pixels along the x-axis
+# - *y*: Shift by y pixels along the y-axis
+# - *time*: Number of seconds the transition should take, with a value of `0`
+#   meaning the zoom should happen instantly (default: `1`)
+# - *type*: Transition type to use (default: `QUAD`)
+#
+# Supported transitions include the names of the values used 
+# in the "TransitionType" enum of the "Tween" type (without the "TRANS_" prefix):
+#
+# https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
+#
+# For more details see: https://docs.escoria-framework.org/camera
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/change_scene.gd

@@ -1,12 +1,13 @@
-# `change_scene path [enable_automatic_transition=true] [run_events=true]`
+# `change_scene path [enable_automatic_transition] [run_events]`
 #
-# Loads a new scene, specified by "path". 
+# Switches the current scene to another scene
-# The `enable_automatic_transition` is a boolean (default true) can be set 
+#
-# to false to disable automatic transitions between scenes, to allow you
+# **Parameters**
-# to control your transitions manually using the `transition` command.
+#
-# The `run_events` variable is a boolean (default true) which you never want 
+# - *path*: Path of the new scene
-# to set manually! It's there only to benefit save games, so they don't
+# - *enable_automatic_transition*: Automatically transition to the new scene 
-# conflict with the scene's events.
+#   (default: `true`)
+# - *run_events*: Run the standard ESC events of the new scene (default: `true`)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/custom.gd

@@ -1,8 +1,15 @@
 # `custom object node func_name [params]`
 # 
-# Calls the function `func_name` of the node `node` of object `object` with 
+# Calls the given Godot function on a (child) node of a registered `ESCitem`.
-# the optional `params`. This is a blocking function
+#
-# 
+# **Parameters**
+#
+# - *object*: Global ID of the target `ESCItem`
+# - *node*: Name of the child node of the target `ESCItem`
+# - *func_name*: Name of the function to be called
+# - *params*: Any primitive, non-array arguments for the function. Multiple
+#   parameters can be passed by using comma-separated values inside a string
+#
 # @ESC
 extends ESCBaseCommand
 class_name CustomCommand

addons/escoria-core/game/core-scripts/esc/commands/debug.gd

@@ -1,6 +1,10 @@
 # `debug string [string2 ...]`
 #
-# Takes 1 or more strings, prints them to the console.
+# Prints a DEBUG-level message to the log.
+#
+# **Parameters**
+#
+# - *string*: One or more strings to log
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/dec_global.gd

@@ -1,8 +1,12 @@
 # `dec_global name value`
 # 
-# Subtracts the value from global with given "name". Value and global must 
+# Subtract the given value from the specified global.
-# both be integers.
+#
-# 
+# **Parameters**
+#
+# - *name*: Name of the global to be changed
+# - *value*: Value to be subtracted
+#
 # @ESC
 extends ESCBaseCommand
 class_name DecGlobalCommand
@@ -19,7 +23,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 
 # Validate wether the given arguments match the command descriptor
 func validate(arguments: Array):
-	if not escoria.globals_manager.get(arguments[0]) is int:
+	if not escoria.globals_manager.get_global(arguments[0]) is int:
 		escoria.logger.report_errors(
 			"dec_global: invalid global",
 			[

addons/escoria-core/game/core-scripts/esc/commands/enable_terrain.gd

@@ -1,7 +1,11 @@
 # `enable_terrain node_name`
 #
-# Enable the ESCTerrain's NavigationPolygonInstance defined by given node name. 
+# Enables the `ESCTerrain`'s `NavigationPolygonInstance` defined by the given node name.
-# Disables previously activated NavigationPolygonInstance.
+# Disables previously-activated `NavigationPolygonInstance`.
+#
+# **Parameters**
+#
+# - *node_name*: Name of the `NavigationPolygonInstance` node to activate
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/hide_menu.gd

@@ -1,9 +1,11 @@
-# `hide_menu main|pause=main [enable_automatic_transition: true|false=false]`
+# `hide_menu menu_type [enable_automatic_transition]`
 #
-# Hides the main or pause menu. 
+# Hides either the main menu or the pause menu. 
-# The `enable_automatic_transition` is a boolean (default false) can be set 
+#
-# to false to disable automatic transitions between scenes, to allow you
+# **Parameters**
-# to control your transitions manually using the `transition` command.
+#
+# - *menu_type*: Type of menu to hide. Can be either `main` or `pause` (default: `main`)
+# - *enable_automatic_transition*: Whether to automatically transition from the menu (default: `false`)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/inc_global.gd

@@ -1,7 +1,11 @@
 # `inc_global name value`
+# 
+# Adds the given value to the specified global.
 #
-# Adds the value to global with given "name". Value and global must both be 
+# **Parameters**
-# integers.
+#
+# - *name*: Name of the global to be changed
+# - *value*: Value to be added
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/inventory_add.gd

@@ -1,6 +1,10 @@
 # `inventory_add item`
 #
-# Add an item to the inventory
+# Adds an item to the inventory.
+#
+# **Parameters**
+#
+# - *item*: Global ID of the `ESCItem` to add to the inventory
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/inventory_remove.gd

@@ -1,6 +1,10 @@
 # `inventory_remove item`
 #
-# Remove an item from the inventory.
+# Removes an item from the inventory
+#
+# **Parameters**
+#
+# - *item*: Global ID of the `ESCItem` to remove from the inventory
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/play_snd.gd

@@ -1,7 +1,13 @@
 # `play_snd file [player]`
 # 
-# Plays the sound specificed with the "file" parameter on the sound player
+# Plays the specified sound without blocking the event.
-# `player`, without blocking. (player defaults to _sound)
+#
+# **Parameters**
+#
+# - *file*: Sound file to play
+# - *player*: Sound player to use. Can either be `_sound`, which is used to play non-
+#   looping sound effects; `_music`, which plays looping music; or `_speech`, which
+#   plays non-looping voice files (default: `_sound`)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/queue_resource.gd

@@ -1,11 +1,12 @@
 # `queue_resource path [front_of_queue]`
 #
-# Queues the load of a resource in a background thread. The `path` must be a 
+# Queues the loading of the given resource into the resource cache.
-# full path inside your game, for example "res://scenes/next_scene.tscn". The 
+#
-# "front_of_queue" parameter is optional (default value false), to put the 
+# **Parameters**
-# resource in the front of the queue. Queued resources are cleared when a 
+# 
-# change scene happens (but after the scene is loaded, meaning you can queue 
+# - *path*: Path of the resource to cache
-# resources that belong to the next scene).
+# - *front_of_queue*: Whether to put the resource at the front of the
+#   queue in order to load it as soon as possible (default: `false`)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/rand_global.gd

@@ -1,6 +1,11 @@
 # `rand_global name max_value`
 #
-# Fills the "name" global with a random value between 0 and max-value-1.
+# Sets the given global to a random integer between 0 and `max_value` (inclusive).
+#
+# **Parameters**
+#
+# - *name*: Name of the global to set
+# - *max_value*: Maximum possible integer value (exclusive)
 #
 # @ESC
 extends ESCBaseCommand
@@ -20,15 +25,15 @@ func configure() -> ESCCommandArgumentDescriptor:
 func validate(arguments: Array):
 	if not escoria.globals_manager.has(arguments[0]):
 		escoria.logger.report_errors(
-			"inc_global: invalid global",
+			"rand_global: invalid global",
 			[
 				"Global %s does not exist." % arguments[0]
 			]
 		)
 		return false
-	if not escoria.globals_manager.get(arguments[0]) is int:
+	if not escoria.globals_manager.get_global(arguments[0]) is int:
 		escoria.logger.report_errors(
-			"inc_global: invalid global",
+			"rand_global: invalid global",
 			[
 				"Global %s didn't have an integer value." % arguments[0]
 			]

addons/escoria-core/game/core-scripts/esc/commands/say.gd

@@ -1,17 +1,20 @@
 # `say player text [type]`
 #
-# Runs the specified string as a dialog said by the player. Blocks execution 
+# Displays the specified string as dialog spoken by the player. Blocks execution 
-# until the dialog finishes playing. 
+# until the dialog has finished playing.
 #
-# The text supports translation keys by prepending the key and separating
+# **Parameters**
-# it with a `:` from the text.
+#
+# - *player*: Global ID of the `ESCPlayer` or `ESCItem` object that is active
+# - *text*: Text to display
+# - *type*: Dialog type to use. One of `floating` or `avatar` 
+#   (default: the value set in the setting "Escoria/UI/Default Dialog Type")
+#
+# The text supports translation keys by prepending the key followed by
+# a colon (`:`) to the text.
 # 
 # Example: `say player ROOM1_PICTURE:"Picture's looking good."`
 #
-# Optional parameters:
-# 
-# * "type" determines the type of dialog UI to use. Default value is "default"
-#
 # @ESC
 extends ESCBaseCommand
 class_name SayCommand

addons/escoria-core/game/core-scripts/esc/commands/sched_event.gd

@@ -1,8 +1,16 @@
 # `sched_event time object event`
 # 
-# Schedules the execution of an "event" found in "object" in a time in seconds. 
+# Schedules the execution to run at a later time.
-# If another event is running at the time, execution starts when the running 
+#
-# event ends.
+# If another event is already running when the scheduled
+# event is to start, execution of the scheduled event 
+# begins when the already-running event ends.
+#
+# **Parameters**
+#
+# - *time*: Time in seconds until the scheduled event starts
+# - *object*: Global ID of the ESCItem that holds the ESC script
+# - *event*: Name of the event to schedule
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_active.gd

@@ -1,7 +1,12 @@
-# `set_active object value`
+# `set_active object active`
 # 
-# Changes the "active" state of the object, value can be true or false. 
+# Changes the "active" state of the object. `active` can be `true` or `false`. 
-# Inactive objects are hidden in the scene.
+# Inactive objects are invisible in the room.
+#
+# **Parameters**
+#
+# - *object* Global ID of the object
+# - *active* Whether `object` should be active.
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_angle.gd

@@ -1,14 +1,14 @@
 # `set_angle object degrees [wait]`
 #
-# Turns object to a degrees angle without animations. 0 sets object facing 
+# Turns a movable `ESCItem` or `ESCPlayer`.
-# forward, 90 sets it 90 degrees clockwise ("east") etc. When turning to the 
-# destination angle, animations are played if they're defined in animations.
 #
-# object must be player or interactive. degrees must be between [0, 360] or an 
+# **Parameters**
-# error is reported.
 #
-# The wait parameter sets how long to wait for each intermediate angle. It
+# - *object*: Global ID of the object to turn
-# defaults to 0, meaning the turnaround is immediate.
+# - *degrees*: Number of degrees by which `object` is to be turned
+# - *wait*: Number of seconds to wait for each animation occurring between the
+#   current angle of `object` and the angle specified. A value of `0` will 
+#   complete the turn immediately (default: `0`)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_animations.gd

@@ -1,6 +1,11 @@
 # `set_animations object animations`
 #
-# Set the animation resource for the given ESCPlayer
+# Sets the animation resource for the given `ESCPlayer` or movable `ESCItem`.
+#
+# **Parameters**
+#
+# - *object*: Global ID of the object whose animation resource is to be updated
+# - *animations*: The path of the animation resource to use
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_global.gd

@@ -1,7 +1,11 @@
 # `set_global name value`
 #
-# Changes the value of the global "name" with the value. Value can be "true", 
+# Changes the value of a global.
-# "false" or an integer.
+#
+# **Parameters**
+#
+# - *name*: Name of the global
+# - *value*: Value to set (can be of type string, boolean, integer or float)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_globals.gd

@@ -1,9 +1,14 @@
 # `set_globals pattern value`
 #
-# Changes the value of multiple globals using a wildcard pattern, where "*" 
+# Changes the value of multiple globals using a wildcard pattern, where `*`
-# matches zero or more arbitrary characters and "?" matches any single 
+# matches zero or more arbitrary characters and `?` matches any single 
 # character except a period (".").
 #
+# **Parameters**
+#
+# - *pattern*: Pattern to use to match the names of the globals to change
+# - *value*: Value to set (can be of type string, boolean, integer or float)
+#
 # @ESC
 extends ESCBaseCommand
 class_name SetGlobalsCommand

addons/escoria-core/game/core-scripts/esc/commands/set_gui_visible.gd

@@ -1,13 +1,14 @@
-# `set_hud_visible visible`
+# `set_gui_visible visible`
 #
-# If you have a cutscene like sequence where the player doesn't have control, 
+# Shows or hide the GUI.
-# and you also have HUD elements visible, use this to hide the HUD. You want 
+#
-# to do that because it explicitly signals the player that there is no control 
+# **Parameters**
-# over the game at the moment. "visible" is true or false.
+#
+# - *visible*: Whether the GUI should be visible
 #
 # @ESC
 extends ESCBaseCommand
-class_name SetHudVisibleCommand
+class_name SetGuiVisibleCommand
 
 
 # Return the descriptor of the arguments of this command

addons/escoria-core/game/core-scripts/esc/commands/set_interactive.gd

@@ -1,6 +1,11 @@
-# `set_interactive object value`
+# `set_interactive object interactive`
 #
-# Sets whether or not an object should be interactive.
+# Sets whether an object should be interactive.
+#
+# **Parameters**
+#
+# - *object*: Global ID of the object to change
+# - *interactive*: Whether the object should be interactive
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_sound_state.gd

@@ -1,50 +0,0 @@
-# `set_sound_state player sound loop`
-#
-# Change the sound playing on `player` to `sound` with optional looping if 
-# `loop` is true.
-# Valid players are "_music" and "_sound".
-# Aside from paths to sound or music files, the values *off* and *default*.
-# *default* is the default value.
-# are also valid for `sound`
-#
-# @ESC
-extends ESCBaseCommand
-class_name SetSoundStateCommand
-
-
-# Return the descriptor of the arguments of this command
-func configure() -> ESCCommandArgumentDescriptor:
-	return ESCCommandArgumentDescriptor.new(
-		1, 
-		[TYPE_STRING, TYPE_STRING, TYPE_BOOL],
-		[null, "default", false]
-	)
-
-
-# Validate wether the given arguments match the command descriptor
-func validate(arguments: Array):
-	if not arguments[0] in ["_music", "_sound", "_speech"]:
-		escoria.logger.report_errors(
-			"SetSoundStateCommand.validate: invalid player",
-			[
-				"Player %s is invalid found" % arguments[0]
-			]
-		)
-		return false
-	if not arguments[1] in ["default", "off"] \
-			and not ResourceLoader.exists(arguments[1]):
-		escoria.logger.report_errors(
-			"SetSoundStateCommand.validate: invalid sound",
-			[
-				"Sound %s is invalid or not found" % arguments[1]
-			]
-		)
-		return false
-	return .validate(arguments)
-
-
-# Run the command
-func run(command_params: Array) -> int:
-	escoria.object_manager.get_object(command_params[0]).node\
-			.set_state(command_params[1], command_params[2])
-	return ESCExecution.RC_OK

addons/escoria-core/game/core-scripts/esc/commands/set_speed.gd

@@ -1,6 +1,11 @@
 # `set_speed object speed`
 #
-# Sets how fast object moves. Speed is an integer.
+# Sets the speed of a `ESCPlayer` or movable `ESCItem`.
+#
+# **Parameters**
+#
+# - *object*: Global ID of the `ESCPlayer` or movable `ESCItem`
+# - *speed*: Speed value for `object`
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/set_state.gd

@@ -1,15 +1,18 @@
 # `set_state object state [immediate]`
 #
-# Changes the state of an object to the given state.
+# Changes the state of `object` to the one specified.
 #
-# If the associated animation player has an animation with the same name,
+# If the specified object's associated animation player has an animation 
-# it also plays that animation.
+# with the same name, that that animation is also played.
 #
-# The command can be used to change the appearance of an item or a player 
+# Can be used to change the appearance of an item or player 
 # character. See https://docs.escoria-framework.org/states for details.
 #
-# If `immediate` is set to true, the animation is directly skipped to the last 
+# **Parameters**
-# frame
+#
+# - *object*: Global ID of the object whose state is to be changed
+# - *immediate*: If an animation for the state exists, specifies
+#   whether it is to skip to the last frame. Can be `true` or `false`.
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/show_menu.gd

@@ -1,9 +1,11 @@
-# `show_menu main|pause=main [enable_automatic_transition: true|false=false]`
+# `show_menu menu_type [enable_automatic_transition]`
 #
-# Shows the main or pause menu. 
+# Shows either the main menu or the pause menu. 
-# The `enable_automatic_transition` is a boolean (default false) can be set 
+#
-# to false to disable automatic transitions between scenes, to allow you
+# **Parameters**
-# to control your transitions manually using the `transition` command. 
+#
+# - *menu_type*: Type of menu to hide. Can be either `main` or `pause` (default: `main`)
+# - *enable_automatic_transition*: Whether to automatically transition to the menu (default: `false`)
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/slide.gd

@@ -1,9 +1,14 @@
-# `slide object1 object2 [speed]`
+# `slide object target [speed]`
 #
-# Moves object1 towards the position of object2, at the speed determined by 
+# Moves `object` towards the position of `target`. This command is
-# object1's "speed" property, unless overridden. This command is non-blocking. 
+# non-blocking. 
-# It does not respect the room's navigation polygons, so you can move items 
+#
-# where the player can't walk.
+# - *object*: Global ID of the object to move
+# - *target*: Global ID of the target object
+# - *speed*: Movement speed (default: the default speed of `object`)
+#
+# **Warning** This command does not respect the room's navigation polygons, so
+# `object` can be moved even when outside walkable areas.
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/slide_block.gd

@@ -1,9 +1,14 @@
-# `slide_block object1 object2 [speed]`
+# `slide_block object target [speed]`
 #
-# Moves object1 towards the position of object2, at the speed determined by 
+# Moves `object` towards the position of `target`. This command is
-# object1's "speed" property, unless overridden. This command is blocking. 
+# blocking. 
-# It does not respect the room's navigation polygons, so you can move items 
+#
-# where the player can't walk.
+# - *object*: Global ID of the object to move
+# - *target*: Global ID of the target object
+# - *speed*: Movement speed (default: the default speed of `object`)
+#
+# **Warning** This command does not respect the room's navigation polygons, so
+# `object` can be moved even when outside walkable areas.
 #
 # @ESC
 extends SlideCommand

addons/escoria-core/game/core-scripts/esc/commands/spawn.gd

@@ -1,7 +1,14 @@
-# `spawn identifier path [is_active=true] [object2] `
+# `spawn identifier path [is_active] [position_target]`
 #
-# Instances a scene determined by "path", and places in the position of 
+# Programmatically adds a new item to the scene.
-# object2 (object2 is optional)
+#
+# **Parameters**
+#
+# - *identifier*: Global ID to use for the new object
+# - *path*: Path to the scene file of the object
+# - *is_active*: Whether the new object should be set to active (default: `true`)
+# - *position_target*: Global ID of another object that will be used to
+#   position the new object (when omitted, the new objet's position is not specified)
 #
 # @ESC
 extends ESCBaseCommand
@@ -36,11 +43,11 @@ func validate(arguments: Array):
 			]
 		)
 		return false
-	if arguments[3] and not escoria.object_manager.objects.has(arguments[2]):
+	if arguments[3] and not escoria.object_manager.objects.has(arguments[3]):
 		escoria.logger.report_errors(
 			"spawn: invalid object",
 			[
-				"Object with global id %s not found" % arguments[2]
+				"Object with global id %s not found" % arguments[3]
 			]
 		)
 		return false

addons/escoria-core/game/core-scripts/esc/commands/stop.gd

@@ -1,6 +1,6 @@
 # `stop`
 #
-# Stops the event's execution.
+# Stops the current event's execution.
 # 
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd

@@ -0,0 +1,41 @@
+# `stop_snd [player]`
+# 
+# Stops the given sound player's stream.
+#
+# **Parameters**
+#
+# - *player*: Sound player to use. Either `_sound`, which is used to play non-
+#   looping sound effects; `_music`, which plays looping music; or `_speech`, which
+#   plays non-looping voice files (default: `_music`)
+#
+# @ESC
+extends ESCBaseCommand
+class_name StopSndCommand
+
+
+# Return the descriptor of the arguments of this command
+func configure() -> ESCCommandArgumentDescriptor:
+	return ESCCommandArgumentDescriptor.new(
+		0, 
+		[TYPE_STRING],
+		["_music"]
+	)
+	
+
+# Validate wether the given arguments match the command descriptor
+func validate(arguments: Array):
+	if not escoria.object_manager.has(arguments[0]):
+		escoria.logger.report_errors(
+			"stop_snd: invalid sound player",
+			["Sound player %s not registered" % arguments[1]]
+		)
+		return false
+	return .validate(arguments)
+	
+
+# Run the command
+func run(command_params: Array) -> int:
+	escoria.object_manager.get_object(command_params[1]).node.set_state(
+		"off"
+	)
+	return ESCExecution.RC_OK

addons/escoria-core/game/core-scripts/esc/commands/teleport.gd

@@ -1,6 +1,11 @@
-# `teleport object1 object2`
+# `teleport object target`
 #
-# Sets the position of object1 to the position of object2.
+# Instantly moves an object to a new position
+#
+# **Parameters**
+#
+# - *object*: Global ID of the object to move
+# - *target*: Global ID of the target object to use as the destination
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/teleport_pos.gd

@@ -1,6 +1,12 @@
-# `teleport_pos object1 x y`
+# `teleport_pos object x y`
 #
-# Sets the position of object1 to the position (x,y).
+# Instantly moves an object to the specified position
+#
+# **Parameters**
+#
+# - *object*: Global ID of the object to move
+# - *x*: X-coordinate of destination position
+# - *y*: Y-coordinate of destination position
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/transition.gd

@@ -1,12 +1,13 @@
-# `transition transition_name in|out [delay]`
+# `transition transition_name mode [delay]`
 #
-# Performs a transition in our out manually.
+# Performs a transition into or out of a room programmatically.
 # 
-# Parameters:
+# **Parameters**
-# - transition_name: Name of the transition shader from one of the transition
+#
+# - *transition_name*: Name of the transition shader from one of the transition
 #   directories
-# - in|out: Wether to play the transition in IN- or OUT-mode
+# - *mode*: Set to `in` to transition into or `out` to transition out of the room
-# - delay: Delay for the transition to take. Defaults to 1 second
+# - *delay*: Delay in seconds before starting the transition (default: `1`)
 # 
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/turn_to.gd

@@ -1,10 +1,14 @@
 # `turn_to object object_to_face [wait]`
 # 
-# Turns object to face another object. 
+# Turns `object` to face another object. 
 #
-# The wait parameter sets how long to wait for each intermediate angle. It
+# **Parameters**
-# defaults to 0, meaning the turnaround is immediate.
+#
-#  
+# - *object*: Global ID of the object to be turned
+# - *object_to_face*: Global ID of the object to turn towards
+# - *wait*: Length of time to wait in seconds for each intermediate angle. 
+#   If set to 0, the turnaround is immediate (default: `0`)
+##  
 # @ESC
 extends ESCBaseCommand
 class_name TurnToCommand

addons/escoria-core/game/core-scripts/esc/commands/wait.gd

@@ -1,8 +1,10 @@
 # `wait seconds`
 #
-# Blocks execution of the current script for a number of seconds specified by 
+# Blocks execution of the current event.
-# the "seconds" parameter. 
+#
-# - seconds can be either and integer or a floating value
+# **Parameters**
+#
+# - *seconds*: Number of seconds to block
 #
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/walk.gd

@@ -1,8 +1,13 @@
-# `walk object1 object2 [speed]`
+# `walk object target [speed]`
 #
-# Walks, using the walk animation, object1 towards the position of object2, 
+# Moves the specified `ESCPlayer` or movable `ESCItem` to `target` w
-# at the speed determined by object1's "speed" property, 
+# hile playing `object`'s walking animation. This command is non-blocking.
-# unless overridden. This command is non-blocking.
+#
+# **Parameters**
+#
+# - *object*: Global ID of the object to move
+# - *target*: Global ID of the target object
+# - *speed*: Walking speed to use (default: `object`'s default speed)
 # 
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/walk_block.gd

@@ -1,8 +1,13 @@
-# `walk_block object1 object2 [speed]`
+# `walk_block object target [speed]`
 #
-# Walks, using the walk animation, object1 towards the position of object2, 
+# Moves the specified `ESCPlayer` or movable `ESCItem` to `target` 
-# at the speed determined by object1's "speed" property, 
+# while playing `object`'s walking animation. This command is blocking.
-# unless overridden. This command is blocking.
+#
+# **Parameters**
+#
+# - *object*: Global ID of the object to move
+# - *target*: Global ID of the target object
+# - *speed*: Walking speed to use (default: `object`'s default speed)
 # 
 # @ESC
 extends ESCBaseCommand

addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos.gd

@@ -1,7 +1,15 @@
-# `walk_to_pos player x y`
+# `walk_to_pos object x y`
 #
-# Makes the `player` walk to the position `x`/`y`.
+# Moves the specified `ESCPlayer` or movable `ESCItem` to the target 
+# position while playing `object`'s walking animation. 
+# This command is non-blocking.
 #
+# **Parameters**
+#
+# - *object*: Global ID of the object to move
+# - *x*: X-coordinate of target position
+# - *y*: Y-coordinate of target position
+# 
 # @ESC
 extends ESCBaseCommand
 class_name WalkToPosCommand

addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos_block.gd

@@ -1,7 +1,15 @@
-# `walk_to_pos_block player x y`
+# `walk_to_pos_block object x y`
 #
-# Makes the `player` walk to the position `x`/`y`. This is a blocking command.
+# Moves the specified `ESCPlayer` or movable `ESCItem` to the target 
+# position while playing `object`'s walking animation. 
+# This command is blocking.
 #
+# **Parameters**
+#
+# - *object*: Global ID of the object to move
+# - *x*: X-coordinate of target position
+# - *y*: Y-coordinate of target position
+# 
 # @ESC
 extends ESCBaseCommand
 class_name WalkToPosBlockCommand

addons/escoria-core/game/core-scripts/esc_animation_player.gd

@@ -130,6 +130,20 @@ func seek_end(name: String):
 		_animated_sprite.frame = _animated_sprite.frames.get_frame_count(name)
 
 
+# Get the length of the specified animation
+#
+# #### Parameters
+#
+# - name: Name of the animation
+# **Returns** The length of the animation in seconds
+func get_length(name: String) -> float:
+	if _is_animation_player:
+		return _animation_player.get_animation(name).length
+	else:
+		return _animated_sprite.frames.get_frame_count(name) - 1 * \
+				_animated_sprite.frames.get_animation_speed(name)
+
+
 # Transport the animation_finished signal
 #
 # #### Parameters

addons/escoria-core/game/core-scripts/save_data/esc_save_manager.gd

@@ -229,10 +229,12 @@ func load_game(id: int):
 				save_game.objects[object_global_id]["last_deg"]])
 			)
 		
-		if object_global_id == "_music" or object_global_id == "_sound":
+		if object_global_id in ["_music", "_sound", "_speech"]:
-			load_statements.append(ESCCommand.new("set_sound_state %s %s true" \
+			load_statements.append(
-					% [object_global_id,
+				ESCCommand.new("play_snd %s %s" % [
-				save_game.objects[object_global_id]["state"]])
+					save_game.objects[object_global_id]["state"],
+					object_global_id,
+				])
 			)
 	
 	load_statements.append(

addons/escoria-core/game/core-scripts/utils/esc_utils.gd

@@ -52,6 +52,8 @@ func get_typed_value(value: String):
 		return int(value)
 	elif regex_bool.search(value.to_lower()):
 		return true if value.to_lower() == "true" else false
+	elif "," in value:
+		return value.split(",")
 	else:
 		return str(value)
 

addons/escoria-dialog-simple/chooser/simple.gd

@@ -28,13 +28,16 @@ func show_chooser():
 	_remove_avatar()
 	
 	for option in self.dialog.options:
-		var _option_node = Button.new()
+		if option.is_valid():
-		_option_node.text = (option as ESCDialogOption).option
+			var _option_node = Button.new()
-		_option_node.flat = true
+			_option_node.text = (option as ESCDialogOption).option
-		_option_node.add_color_override("font_color", color_normal)
+			_option_node.flat = true
-		_option_node.add_color_override("font_color_hover", color_hover)
+			_option_node.add_color_override("font_color", color_normal)
-		_vbox.add_child(_option_node)
+			_option_node.add_color_override("font_color_hover", color_hover)
-		_option_node.connect("pressed", self, "_on_answer_selected", [option])
+			_vbox.add_child(_option_node)
+			_option_node.connect("pressed", self, "_on_answer_selected", [
+				option
+			])
 	
 	if self.dialog.avatar != "-":
 		$AvatarContainer.add_child(

game/rooms/room01/esc/right_exit.esc

@@ -1,3 +1,3 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room02/room02.tscn"

game/rooms/room01/esc/room01.esc

@@ -10,7 +10,7 @@
 
 :ready
 
-set_sound_state _music res://game/sfx/contemplation.ogg true
+play_snd res://game/sfx/contemplation.ogg _music
 
 > [!room1_visited]
 	set_global room1_visited true

game/rooms/room02/esc/left_exit.esc

@@ -1,3 +1,3 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room01/room01.tscn"

game/rooms/room02/esc/right_exit.esc

@@ -1,3 +1,3 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg 
 change_scene "res://game/rooms/room03/room03.tscn"

game/rooms/room06/esc/worker.esc

@@ -39,7 +39,7 @@ say player "I don't think he'd like that."
 
 ####################################################################################################
 :give r5_filled_sheet
-set_hud_visible false
+set_gui_visible false
 accept_input SKIP
 
 inventory_remove r5_filled_sheet
@@ -57,7 +57,7 @@ set_global r6_door_open true
 wait 1
 set_active worker false
 
-set_hud_visible true
+set_gui_visible true
 accept_input ALL
 
 

game/rooms/room10/esc/button_play_bg_music.esc

@@ -1,2 +1,2 @@
 :use
-set_sound_state _music res://game/sfx/contemplation.ogg true
+play_snd res://game/sfx/contemplation.ogg _music

game/rooms/room10/esc/button_stop_bg_music.esc

@@ -1,2 +1,2 @@
 :use
-set_sound_state _music off true
+stop_snd

game/rooms/room10/esc/left_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room09/room09.tscn"
 
 

game/rooms/room10/esc/right_exit.esc

@@ -1,3 +1,3 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room11/room11.tscn"

game/rooms/room11/esc/left_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room10/room10.tscn"
 
 

game/rooms/room11/esc/right_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 transition fade_black out
 change_scene "res://game/rooms/room12/room12.tscn" false
 

game/rooms/room12/esc/left_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room11/room11.tscn"
 
 

game/rooms/room12/esc/right_exit.esc

@@ -1,3 +1,3 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room13/room13.tscn"

game/rooms/room13/esc/left_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room12/room12.tscn"
 
 

game/rooms/room13/esc/right_exit.esc

@@ -1,3 +1,2 @@
 :exit_scene
-#set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
 change_scene "res://game/rooms/room14/room14.tscn"

game/rooms/room14/esc/left_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room13/room13.tscn"
 
 

game/rooms/room14/esc/right_exit.esc

@@ -1,3 +1,3 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room15/room15.tscn"

game/rooms/room15/esc/left_exit.esc

@@ -1,5 +1,5 @@
 :exit_scene
-set_sound_state _sound res://game/sfx/sounds/doorOpen_2.ogg false
+play_snd res://game/sfx/sounds/doorOpen_2.ogg
 change_scene "res://game/rooms/room14/room14.tscn"
 
 

game/start_game.esc

@@ -1,6 +1,6 @@
 :init
 
-set_sound_state _music res://game/sfx/Game-Menu_Looping.mp3 true
+play_snd res://game/sfx/Game-Menu_Looping.mp3 _music
 
 # Showing main menu with automatic transition DISABLED
 show_menu main

project.godot

@@ -440,9 +440,9 @@ _global_script_classes=[ {
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_globals.gd"
 }, {
 "base": "ESCBaseCommand",
-"class": "SetHudVisibleCommand",
+"class": "SetGuiVisibleCommand",
 "language": "GDScript",
-"path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_hud_visible.gd"
+"path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_gui_visible.gd"
 }, {
 "base": "ESCBaseCommand",
 "class": "SetInteractiveCommand",
@@ -450,11 +450,6 @@ _global_script_classes=[ {
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_interactive.gd"
 }, {
 "base": "ESCBaseCommand",
-"class": "SetSoundStateCommand",
-"language": "GDScript",
-"path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_sound_state.gd"
-}, {
-"base": "ESCBaseCommand",
 "class": "SetSpeedCommand",
 "language": "GDScript",
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/set_speed.gd"
@@ -490,6 +485,11 @@ _global_script_classes=[ {
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/stop.gd"
 }, {
 "base": "ESCBaseCommand",
+"class": "StopSndCommand",
+"language": "GDScript",
+"path": "res://addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd"
+}, {
+"base": "ESCBaseCommand",
 "class": "TeleportCommand",
 "language": "GDScript",
 "path": "res://addons/escoria-core/game/core-scripts/esc/commands/teleport.gd"
@@ -621,9 +621,8 @@ _global_script_class_icons={
 "SetAnimationsCommand": "",
 "SetGlobalCommand": "",
 "SetGlobalsCommand": "",
-"SetHudVisibleCommand": "",
+"SetGuiVisibleCommand": "",
 "SetInteractiveCommand": "",
-"SetSoundStateCommand": "",
 "SetSpeedCommand": "",
 "SetStateCommand": "",
 "ShowMenuCommand": "",
@@ -631,6 +630,7 @@ _global_script_class_icons={
 "SlideCommand": "",
 "SpawnCommand": "",
 "StopCommand": "",
+"StopSndCommand": "",
 "TeleportCommand": "",
 "TeleportPosCommand": "",
 "TransitionCommand": "",