fix: Optimized ESC command docs (#450)

Co-authored-by: Dennis Ploeger <[email protected]>
Co-authored-by: Duncan Brown <[email protected]>

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 
-# skipping of dialog but nothing else, NONE denies all input. Including opening 
-# the menu etc. SKIP and NONE also disable autosaves.
+# Sets how much input the game is to accept, allowing for cut scenes
+# in which dialog can be skipped (if [type] is set to SKIP).
+# 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. 
-# This allows you to create cut scenes with SKIP where the dialog can be 
-# skipped, but also initiate locked#### down cutscenes with accept_input 
-# NONE in :setup and accept_input ALL later in :ready.
+# **Parameters**
+#
+# - *type*: Type of inputs to accept (ALL)
+#   `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, 
-# blocking. The next command in the event will be executed when the animation 
-# is finished playing. Optional parameters:
+# Executes the animation specified in "name" on "object", 
+# while blocking. The next command in the event will be executed when the animation 
+# 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 
-# 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; 
-# defaults to QUART. A `time` value of 0 will set the camera immediately.
+# Pushes the camera to point at a specific `target`.
+#
+# **Parameters**
+#
+# - *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 
-# camera_limits array.
-# - camlimits_id: int: id of the camera limits to apply (defined in ESCRoom's 
-#   camera_limits array)
+# Activates the current camera's limits
+#
+# **Parameters**
+#
+# - *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 
-# by "speed" in pixels per second. If speed is 0, camera is teleported to the 
-# position.
+# Moves the camera to the given 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`
-# as speed limit. 
-# This is the default behavior (default follow object is "player"). 
+# Configures the camera to follow the specified target `object`
+#
+# **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 
-# the camera out, and smaller values zooms in, relative to the default value 
-# of 1. An optional `time` in seconds controls how long it takes for the camera 
-# to zoom into position.
+# Zooms the camera in/out to the desired `magnitude`. Values larger than 1 zoom 
+# the camera out while smaller values zoom in, relative to the default value 
+# of 1.
+#
+# **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. 
-# An optional `time` in seconds controls how long it takes for the camera 
-# to zoom into position.
+# Zooms the camera in/out so it occupies the given height in pixels
+#
+# **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 
-# Tween.TransitionType values without the prefix, eg. LINEAR, QUART or CIRC; 
-# defaults to QUART.
+# Shifts the camera by the given horizontal and vertical amounts.
+#
+# **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". 
-# The `enable_automatic_transition` is a boolean (default true) can be set 
-# to false to disable automatic transitions between scenes, to allow you
-# to control your transitions manually using the `transition` command.
-# The `run_events` variable is a boolean (default true) which you never want 
-# to set manually! It's there only to benefit save games, so they don't
-# conflict with the scene's events.
+# Switches the current scene to another scene
+#
+# **Parameters**
+#
+# - *path*: Path of the new scene
+# - *enable_automatic_transition*: Automatically transition to the new scene 
+#   (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 
-# the optional `params`. This is a blocking function
-# 
+# Calls the given Godot function on a (child) node of a registered `ESCitem`.
+#
+# **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 
-# both be integers.
-# 
+# Subtract the given value from the specified global.
+#
+# **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. 
-# Disables previously activated NavigationPolygonInstance.
+# Enables the `ESCTerrain`'s `NavigationPolygonInstance` defined by the given node name.
+# 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. 
-# The `enable_automatic_transition` is a boolean (default false) can be set 
-# to false to disable automatic transitions between scenes, to allow you
-# to control your transitions manually using the `transition` command.
+# Hides either the main menu or the pause menu. 
+#
+# **Parameters**
+#
+# - *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 
-# integers.
+# **Parameters**
+#
+# - *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
-# `player`, without blocking. (player defaults to _sound)
+# Plays the specified sound without blocking the event.
+#
+# **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