documentation: Fixes to command descriptions (#506)

Co-authored-by: Duncan Brown <duncan@prometheussoftware.ca>
Co-authored-by: Balloonpopper <balloonpopper@git.com>

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

@@ -1,20 +1,21 @@
 # `accept_input [type]`
 #
-# Sets how much input the game is to accept, allowing for cut scenes
+# Sets how much input the game is to accept. This allows for cut scenes
-# in which dialog can be skipped (if [type] is set to SKIP).
+# in which dialogue can be skipped (if [type] is set to SKIP), and ones where
-# Also allows for cut scenes that can be completely locked down.
+# it can't (if [type] is set to NONE).
 #
 # **Parameters**
 #
 # - *type*: Type of inputs to accept (ALL)
-#   `ALL`: Accept all types of input
+#   `ALL`: Accept all types of user input
-#   `SKIP`: Accept skipping dialogs but nothing else
+#   `SKIP`: Accept skipping dialogues but nothing else
 #   `NONE`: Deny all inputs (including opening menus)
 #
 # **Warning**: `SKIP` and `NONE` also disable autosaves.
 #
-# **Warning**: The type of input accepted will persist even after the current
+# **Warning**: The type of user input accepted will persist even after the 
-# event has ended.
+# current event has ended. Remember to reset the input type at the end of
+# cut-scenes!
 #
 # @ESC
 extends ESCBaseCommand
@@ -30,7 +31,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not arguments[0] in ["ALL", "NONE", "SKIP"]:
 		escoria.logger.report_errors(

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

@@ -1,8 +1,8 @@
 # `anim object name [reverse]`
 #
-# Executes the animation specified in "name" on "object",
+# Executes the animation specified in "name" on "object" without blocking.
-# without blocking. The next command in the event will be executed immediately
+# The next command in the event will be executed immediately after the 
-# after.
+# animation is started.
 #
 # **Parameters**
 #
@@ -24,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,8 +1,9 @@
 # `anim_block object name [reverse]`
 #
-# Executes the animation specified in "name" on "object",
+# Executes the animation specified in "name" on "object" while blocking other
-# while blocking. The next command in the event will be executed when the animation
+# events from starting. 
-# is finished playing.
+# The next command in the event will be executed when the animation is 
+# finished playing.
 #
 # **Parameters**
 #
@@ -24,7 +25,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,6 +1,8 @@
 # `camera_push target [time] [type]`
 #
-# Pushes the camera to point at a specific `target`.
+# Pushes (moves) the camera so it points at a specific `target`. If the camera 
+# was following a target (like the player) previously, it will no longer follow
+# this target. 
 #
 # **Parameters**
 #
@@ -13,7 +15,7 @@
 # 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
+# See https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
 #
 # For more details see: https://docs.escoria-framework.org/camera
 #
@@ -35,7 +37,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,10 +1,14 @@
 # `camera_set_limits camlimits_id`
 #
-# Activates the current camera's limits
+# Limits the current camera's movement to a limit defined in the `ESCRoom`'s 
+# definition. A limit is defined as an upper-left (x, y) coordinate, a width
+# and a height that the camera must stay within. Multiple limits can be
+# defined for a room, allowing for new areas to be seen once they have
+# been 'unlocked'.
 #
 # **Parameters**
 #
-# - *camlimits_id*: Index of the camera limit in the `camera limits`
+# - *camlimits_id*: Index of the camera limit defined in the `camera limits`
 #   list of the current `ESCRoom`
 #
 # For more details see: https://docs.escoria-framework.org/camera
@@ -23,7 +27,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if escoria.main.current_scene.camera_limits.size() < arguments[0]:
 		escoria.logger.report_errors(

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

@@ -1,6 +1,6 @@
 # `camera_set_pos time x y`
 #
-# Moves the camera to the given position.
+# Moves the camera to the given absolute position over a time period.
 #
 # **Parameters**
 #

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

@@ -1,10 +1,13 @@
 # `camera_set_target time object`
 #
-# Configures the camera to follow the specified target `object`
+# Configures the camera to follow the specified target `object` as it moves
+# around the current room. The transition to focus on the `object` will happen
+# over a time period.
 #
 # **Parameters**
 #
-# - *time*: Number of seconds the transition should take
+# - *time*: Number of seconds the transition should take to move the camera 
+#   to follow `object`
 # - *object*: Global ID of the target object
 #
 # For more details see: https://docs.escoria-framework.org/camera
@@ -23,7 +26,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[1]):
 		escoria.logger.report_errors(

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

@@ -1,8 +1,10 @@
 # `camera_set_zoom magnitude [time]`
 #
-# Zooms the camera in/out to the desired `magnitude`. Values larger than 1 zoom
+# 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
+# the camera out while smaller values zoom in. These values are relative to the 
-# of 1.
+# default zoom value of '1', not the current value. As such, while using a value 
+# of '0.5' would double the size of the graphics, running the same command again
+# would result in no change. The zoom will happen over the given time period.
 #
 # **Parameters**
 #

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

@@ -1,6 +1,6 @@
 # `camera_set_zoom_height pixels [time]`
 #
-# Zooms the camera in/out so it occupies the given height in pixels
+# Zooms the camera in/out so it occupies the given height in pixels.
 #
 # **Parameters**
 #
@@ -24,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if arguments[0] < 0:
 		escoria.logger.report_errors(

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

@@ -1,6 +1,7 @@
 # `camera_shift x y [time] [type]`
 #
-# Shifts the camera by the given horizontal and vertical amounts.
+# Shifts the camera by the given horizontal and vertical amounts relative to the 
+# current location.
 #
 # **Parameters**
 #

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

@@ -1,6 +1,8 @@
 # `change_scene path [enable_automatic_transition] [run_events]`
 #
-# Switches the current scene to another scene
+# Switches the game from the current scene to another scene. Use this to move
+# the player to a new room when they walk through an unlocked door, for 
+# example.
 #
 # **Parameters**
 #
@@ -23,7 +25,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array) -> bool:
 	if not ResourceLoader.exists(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,13 +1,15 @@
 # `custom object node func_name [params]`
 #
-# Calls the given Godot function on a (child) node of a registered `ESCitem`.
+# 
+# Executes the specified Godot function. This function must be in a script
+# attached to 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
+# - params: Any arguments to be passed to the function (array and object parameters are not supported). Multiple
 #   parameters can be passed by using comma-separated values inside a string
 #
 # @ESC
@@ -24,7 +26,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -21,7 +21,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.globals_manager.get_global(arguments[0]) is int:
 		escoria.logger.report_errors(

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

@@ -1,7 +1,10 @@
 # `enable_terrain node_name`
 #
-# Enables the `ESCTerrain`'s `NavigationPolygonInstance` defined by the given node name.
+# Enables the `ESCTerrain`'s `NavigationPolygonInstance` specified by the given 
-# Disables previously-activated `NavigationPolygonInstance`.
+# node name. It will also disable the previously-activated 
+# `NavigationPolygonInstance`.
+# Use this to change where the player can walk, allowing them to walk into the
+# next room once a door has been opened, for example.
 #
 # **Parameters**
 #

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

@@ -1,10 +1,17 @@
 # `hide_menu menu_type [enable_automatic_transition]`
 #
-# Hides either the main menu or the pause menu.
+# Hides either the main menu or the pause menu. The enable_automatic_transition
-#
+# parameter can be used to specify if Escoria manages the graphical transition
+# for you or not. 
+# Setting `enable_automatic_transition` to false allows you to manage the
+# transition effect for your room as it transitions in and out. Place a 
+# `transition` command in the room's `setup` event to manage the look of the 
+# transition in, and in the room's `exit_scene` event to manage the look of the
+# transition out.
+# 
 # **Parameters**
 #
-# - *menu_type*: Type of menu to hide. Can be either `main` or `pause` (default: `main`)
+# - *menu_type*: Which menu to hide. Can be either `main` or `pause` (default: `main`)
 # - *enable_automatic_transition*: Whether to automatically transition from the menu (default: `false`)
 #
 # @ESC
@@ -21,7 +28,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not arguments[0] in ["main", "pause"]:
 		escoria.logger.report_errors(

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

@@ -21,7 +21,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.globals_manager.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,6 +1,8 @@
 # `inventory_add item`
 #
-# Adds an item to the inventory.
+# Adds an item to the inventory. If the player is picking up an object, you may
+# want to use this command in conjunction with the `set_active` command so that 
+# the object 'disappears' from the scene as it's added to the inventory.
 #
 # **Parameters**
 #

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

@@ -1,6 +1,8 @@
 # `inventory_remove item`
 #
-# Removes an item from the inventory
+# Removes an item from the inventory. You may wish to use this command in
+# conjuction with the `set_active` command to show an item in the scene,
+# simulating placing the item somewhere, for example.
 #
 # **Parameters**
 #

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

@@ -1,6 +1,6 @@
 # `play_snd file [player]`
 #
-# Plays the specified sound without blocking the event.
+# Plays the specified sound without blocking the currently running event.
 #
 # **Parameters**
 #
@@ -23,7 +23,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.has(arguments[1]):
 		escoria.logger.report_errors(

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

@@ -1,6 +1,6 @@
 # `queue_event object event [channel] [block]`
 #
-# Queue another event to run
+# Queue an event to run.
 #
 # **Parameters**
 #
@@ -25,7 +25,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -22,7 +22,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array) -> bool:
 	if not ResourceLoader.exists(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -21,7 +21,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.globals_manager.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,7 +1,8 @@
 # `say player text [type]`
 #
-# Displays the specified string as dialog spoken by the player. Blocks execution
+# Displays the specified string as dialog spoken by the player. This command
-# until the dialog has finished playing.
+# blocks further event execution until the dialog has finished being 'said'
+# (either as displayed text or as audible speech from a file).
 #
 # **Parameters**
 #
@@ -38,7 +39,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,9 +1,9 @@
 # `sched_event time object event`
 #
-# Schedules the execution to run at a later time.
+# Schedules an event to run at a later time.
 #
 # If another event is already running when the scheduled
-# event is to start, execution of the scheduled event
+# event is supposed to start, execution of the scheduled event
 # begins when the already-running event ends.
 #
 # **Parameters**
@@ -26,7 +26,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.has(arguments[1]):
 		escoria.logger.report_errors(

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

@@ -1,12 +1,12 @@
 # `set_active object active`
 #
-# Changes the "active" state of the object. `active` can be `true` or `false`.
+# Changes the "active" state of the object.
 # Inactive objects are invisible in the room.
 #
 # **Parameters**
 #
 # - *object* Global ID of the object
-# - *active* Whether `object` should be active.
+# - *active* Whether `object` should be active. `active` can be `true` or `false`.
 #
 # @ESC
 extends ESCBaseCommand
@@ -22,7 +22,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,6 +1,9 @@
 # `set_angle object degrees [wait]`
 #
-# Turns a movable `ESCItem` or `ESCPlayer`.
+# Turns a movable `ESCItem` or `ESCPlayer` to face a given angle.
+
+# Angles 0 and 360 are the same and correspond to UP/NORTH,
+# 90 is RIGHT/EAST, 180 is DOWN/SOUTH, 270 is LEFT/WEST etc.
 #
 # **Parameters**
 #
@@ -24,7 +27,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -21,7 +21,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -5,7 +5,8 @@
 # **Parameters**
 #
 # - *name*: Name of the global
-# - *value*: Value to set (can be of type string, boolean, integer or float)
+# - *value*: Value to set the global to (can be of type string, boolean, integer
+#   or float)
 #
 # @ESC
 extends ESCBaseCommand

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

@@ -1,10 +1,10 @@
 # `set_gui_visible visible`
 #
-# Shows or hide the GUI.
+# Show or hide the GUI.
 #
 # **Parameters**
 #
-# - *visible*: Whether the GUI should be visible
+# - *visible*: Whether the GUI should be visible (`true` or `false`)
 #
 # @ESC
 extends ESCBaseCommand

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

@@ -1,6 +1,6 @@
 # `set_interactive object interactive`
 #
-# Sets whether an object should be interactive.
+# Sets whether an object is interactive.
 #
 # **Parameters**
 #
@@ -21,7 +21,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -5,7 +5,7 @@
 # **Parameters**
 #
 # - *object*: Global ID of the `ESCPlayer` or movable `ESCItem`
-# - *speed*: Speed value for `object`
+# - *speed*: Speed value for `object` in pixels per second.
 #
 # @ESC
 extends ESCBaseCommand
@@ -20,7 +20,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 		[null, null]
 	)
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -28,7 +28,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,10 +1,14 @@
 # `show_menu menu_type [enable_automatic_transition]`
 #
-# Shows either the main menu or the pause menu.
+# Shows either the main menu or the pause menu. The enable_automatic_transition
+# parameter can be used to specify if Escoria manages the graphical transition to 
+# the menu or not. If set to false, you can manage the transition yourself 
+# instead (if you want to change the transition type from the default for 
+# example) using the `transition` command.
 #
 # **Parameters**
 #
-# - *menu_type*: Type of menu to hide. Can be either `main` or `pause` (default: `main`)
+# - *menu_type*: Which menu to show. Can be either `main` or `pause` (default: `main`)
 # - *enable_automatic_transition*: Whether to automatically transition to the menu (default: `false`)
 #
 # @ESC
@@ -21,7 +25,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not arguments[0] in ["main", "pause"]:
 		escoria.logger.report_errors(

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

@@ -5,7 +5,8 @@
 #
 # - *object*: Global ID of the object to move
 # - *target*: Global ID of the target object
-# - *speed*: Movement speed (default: the default speed of `object`)
+# - *speed*: The speed at which to slide in pixels per second (will default to 
+#   the speed configured on the `object`)
 #
 # **Warning** This command does not respect the room's navigation polygons, so
 # `object` can be moved even when outside walkable areas.
@@ -28,7 +29,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(
@@ -53,9 +54,11 @@ func validate(arguments: Array):
 #
 # #### Parameters
 #
-# - source: The item to slide
+# - *source*: The item to slide
-# - destination: The destination item to slide to
+# - *destination*: The destination item to slide to
-# - speed: The speed at which to slide (will default to the
+# - *speed*: The speed at which to slide in pixels per second (will default to 
+#   the speed configured on the `object`)
+#   
 #
 # **Returns** The generated (and started) tween
 func _slide_object(

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

@@ -5,7 +5,8 @@
 #
 # - *object*: Global ID of the object to move
 # - *target*: Global ID of the target object
-# - *speed*: Movement speed (default: the default speed of `object`)
+# - *speed*: The speed at which to slide in pixels per second (will default to 
+#   the speed configured on the `object`)
 #
 # **Warning** This command does not respect the room's navigation polygons, so
 # `object` can be moved even when outside walkable areas.

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

@@ -8,7 +8,7 @@
 # - *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)
+#   position the new object (when omitted, the new object's position is not specified)
 #
 # @ESC
 extends ESCBaseCommand
@@ -24,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if arguments[0].empty() \
 		or arguments[0] in escoria.object_manager.RESERVED_OBJECTS:

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

@@ -22,7 +22,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,11 +1,12 @@
 # `teleport object target`
 #
-# Instantly moves an object to a new position
+# 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
+# - *target*: Global ID of the object to use as the destination coordinates 
+#   for `object`
 #
 # @ESC
 extends ESCBaseCommand
@@ -21,7 +22,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,6 +1,6 @@
 # `teleport_pos object x y`
 #
-# Instantly moves an object to the specified position
+# Instantly moves an object to the specified (absolute) coordinates.
 #
 # **Parameters**
 #
@@ -22,7 +22,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -23,7 +23,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.main.scene_transition.has_transition(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -2,13 +2,19 @@
 #
 # Turns `object` to face another object.
 #
+# Unlike movement commands, `turn_to` will not automatically reference an
+# `ESCLocation` that is a child of an `ESCItem.` 
+# To turn towards an `ESCLocation` that is a child of an `ESCItem`, give the
+# `ESCLocation` a `Global ID` and use this value as the `object_to_face`
+# parameter.
+#
 # **Parameters**
 #
 # - *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
@@ -23,7 +29,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,13 +1,14 @@
 # `walk object target [speed]`
 #
-# Moves the specified `ESCPlayer` or movable `ESCItem` to `target` w
+# Moves the specified `ESCPlayer` or movable `ESCItem` to `target` 
-# hile playing `object`'s walking animation. This command is non-blocking.
+# while playing the `object`'s walking animation. 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)
+# - *speed*: The speed the `object` will walk in pixels per second (will 
+#   default to the speed configured on the `object`)
 #
 # @ESC
 extends ESCBaseCommand
@@ -23,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -7,7 +7,8 @@
 #
 # - *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)
+# - *speed*: The speed the `object` will walk in pixels per second (will 
+#   default to the speed configured on the `object`)
 #
 # @ESC
 extends ESCBaseCommand
@@ -23,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,7 +1,7 @@
 # `walk_to_pos object x y`
 #
-# Moves the specified `ESCPlayer` or movable `ESCItem` to the target
+# Moves the specified `ESCPlayer` or movable `ESCItem` to the absolute
-# position while playing `object`'s walking animation.
+# coordinates provided while playing the `object`'s walking animation.
 # This command is non-blocking.
 #
 # **Parameters**
@@ -24,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

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

@@ -1,7 +1,7 @@
 # `walk_to_pos_block object x y`
 #
-# Moves the specified `ESCPlayer` or movable `ESCItem` to the target
+# Moves the specified `ESCPlayer` or movable `ESCItem` to the absolute
-# position while playing `object`'s walking animation.
+# coordinates provided while playing the `object`'s walking animation.
 # This command is blocking.
 #
 # **Parameters**
@@ -24,7 +24,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	)
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array):
 	if not escoria.object_manager.objects.has(arguments[0]):
 		escoria.logger.report_errors(

addons/escoria-core/game/core-scripts/esc/esc_event_manager.gd

@@ -215,7 +215,7 @@ func clear_event_queue():
 		events_queue[channel_name].clear()
 
 
-# Check wether a channel is free to run more events
+# Check whether a channel is free to run more events
 #
 # #### Parameters
 # - name: Name of the channel to test

addons/escoria-core/game/core-scripts/esc/esc_object_manager.gd

@@ -80,7 +80,7 @@ func register_object(object: ESCObject, force: bool = false) -> void:
 		objects[object.global_id] = object
 
 
-# Check wether an object was registered
+# Check whether an object was registered
 #
 # #### Parameters
 #

addons/escoria-core/game/core-scripts/esc/types/esc_base_command.gd

@@ -26,7 +26,7 @@ func configure() -> ESCCommandArgumentDescriptor:
 	return ESCCommandArgumentDescriptor.new()
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(arguments: Array) -> bool:
 	return self.configure().validate(get_class(), arguments)
 

addons/escoria-core/game/core-scripts/esc/types/esc_command_argument_descriptor.gd

@@ -62,7 +62,7 @@ func prepare_arguments(arguments: Array) -> Array:
 	return complete_arguments
 
 
-# Validate wether the given arguments match the command descriptor
+# Validate whether the given arguments match the command descriptor
 func validate(command: String, arguments: Array) -> bool:
 	if arguments.size() < self.min_args:
 		escoria.logger.report_errors(
@@ -106,7 +106,7 @@ func validate(command: String, arguments: Array) -> bool:
 	return true
 
 
-# Check wether the given argument is of the given type
+# Check whether the given argument is of the given type
 #
 # #### Parameters
 #

addons/escoria-core/game/core-scripts/esc/types/esc_statement.gd

@@ -19,7 +19,7 @@ var _is_interrupted: bool = false
 var is_finished: bool = false
 
 
-# Check wether the statement should be run based on its conditions
+# Check whether the statement should be run based on its conditions
 func is_valid() -> bool:
 	for condition in self.conditions:
 		if not (condition as ESCCondition).run():

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

@@ -424,7 +424,7 @@ func set_speed(speed_value: int) -> void:
 	speed = speed_value
 
 
-# Check wether this item moved
+# Check whether this item moved
 func has_moved() -> bool:
 	return _movable.moved if is_movable else false
 

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

@@ -1,5 +1,8 @@
 # A simple node extending Position2D with a global ID so that it can be
-# referenced in ESC Scripts.
+# referenced in ESC Scripts. Movement-based commands like `walk_to_pos` will
+# automatically use an `ESCLocation` that is a child of the destination node.
+# Commands like `turn_to`--which are not movement-based--will ignore child
+# `ESCLocation`s and refer to the parent node.
 extends Position2D
 class_name ESCLocation, "res://addons/escoria-core/design/esc_location.svg"
 

addons/escoria-core/game/core-scripts/resources/esc_animationresource.gd

@@ -8,8 +8,8 @@ class_name ESCAnimationResource
 # Array containing the different angles available for animations.
 # Each angle is defined by an array [start_angle, angle_size].
 # start_angle must be between 0 and 360.
-# Angle 0 and 360 are the same and correspond to UP/NORTH
+# Angles 0 and 360 are the same and correspond to UP/NORTH,
-# 90 is RIGHT/EAST, 180 is DOWN/SOUTH, etc
+# 90 is RIGHT/EAST, 180 is DOWN/SOUTH, 270 is LEFT/WEST etc.
 export(Array, Resource) var dir_angles: Array = []
 
 # Array of animations for each direction, from UP to RIGHT_UP clockwise

addons/escoria-core/game/scenes/dialogs/esc_dialog_manager.gd

@@ -10,7 +10,7 @@ signal say_finished
 signal option_chosen(option)
 
 
-# Check wether a specific type is supported by the
+# Check whether a specific type is supported by the
 # dialog plugin
 #
 # #### Parameters
@@ -20,7 +20,7 @@ func has_type(type: String) -> bool:
 	return false
 
 
-# Check wether a specific chooser type is supported by the
+# Check whether a specific chooser type is supported by the
 # dialog plugin
 #
 # #### Parameters

addons/escoria-core/ui_library/inventory/esc_inventory_container.gd

@@ -3,7 +3,7 @@ extends Control
 class_name ESCInventoryContainer
 
 
-# Get wether the inventory container currently is empty
+# Get whether the inventory container currently is empty
 # **Returns** Wether the container is empty or not
 func is_empty() -> bool:
 	return get_child_count() > 0

addons/escoria-dialog-simple/esc_dialog_simple.gd

@@ -10,7 +10,7 @@ var _type_player: Node = null
 var _dialog_player: Node = null
 
 
-# Check wether a specific type is supported by the
+# Check whether a specific type is supported by the
 # dialog plugin
 #
 # #### Parameters
@@ -20,7 +20,7 @@ func has_type(type: String) -> bool:
 	return true if type in ["floating", "avatar"] else false
 
 
-# Check wether a specific chooser type is supported by the
+# Check whether a specific chooser type is supported by the
 # dialog plugin
 #
 # #### Parameters