From 6ea0c2923421f8b2d088aa942a346a7d5ee1e697 Mon Sep 17 00:00:00 2001
From: Balloonpopper <balloonpopper@git.com>
Date: Tue, 25 Oct 2022 08:47:48 +1100
Subject: [PATCH] fix: Documentation clarifications

---
 .../core-scripts/esc/commands/queue_event.gd  |  9 +++++-
 .../game/core-scripts/esc/commands/repeat.gd  |  5 +--
 .../core-scripts/esc/commands/set_angle.gd    | 32 +++++++++++++++----
 .../core-scripts/esc/commands/set_state.gd    | 12 ++++---
 .../core-scripts/esc/commands/show_menu.gd    |  9 ++++--
 .../game/core-scripts/esc/commands/stop.gd    |  4 ++-
 .../core-scripts/esc/commands/stop_snd.gd     | 17 +++++++---
 .../core-scripts/esc/commands/transition.gd   |  5 ++-
 .../game/core-scripts/esc/commands/turn_to.gd | 10 ++++++
 .../game/core-scripts/esc/commands/walk.gd    |  7 ++--
 .../core-scripts/esc/commands/walk_block.gd   |  7 ++--
 .../rooms/room16/esc/current_scene_button.esc |  2 ++
 game/rooms/room16/esc/room16.esc              |  3 +-
 game/rooms/room16/esc/worker_script.esc       |  5 +++
 game/rooms/room16/room16.tscn                 | 31 +++++++++++++++---
 15 files changed, 124 insertions(+), 34 deletions(-)
 create mode 100644 game/rooms/room16/esc/worker_script.esc

diff --git a/addons/escoria-core/game/core-scripts/esc/commands/queue_event.gd b/addons/escoria-core/game/core-scripts/esc/commands/queue_event.gd
index 2fc1cfd9..1c060e7a 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/queue_event.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/queue_event.gd
@@ -2,11 +2,18 @@
 #
 # Queue an event to run.
 #
+# If you queue multiple events on a channel and none of them are blocking
+# events, all events will effectively run at the same time. As the events are
+# placed on the channel's queue, if one event contains a blocking command, the
+# next event on that channel's queue won't be processed until the blocking
+# command finishes.
+#
 # **Parameters**
 #
 # - object: Object that holds the ESC script with the event
 # - event: Name of the event to queue
-# - channel: Channel to run the event on (default: `_front`)
+# - channel: Channel to run the event on (default: `_front`). Using a 
+#   previously unused channel name will create a new channel.
 # - block: Whether to wait for the queue to finish. This is only possible, if
 #   the queued event is not to be run on the same event as this command
 #   (default: `false`)
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/repeat.gd b/addons/escoria-core/game/core-scripts/esc/commands/repeat.gd
index 26990be3..47fbacd9 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/repeat.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/repeat.gd
@@ -1,7 +1,8 @@
 # `repeat`
 #
-# Restarts the execution of the current scope at the start. A scope can be a
-# group or an event.
+# Makes the current script loop back to the start. Currently the only way to
+# exit the loop is via the `stop` command which will stop the script 
+# completely.
 #
 # @ESC
 extends ESCBaseCommand
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_angle.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_angle.gd
index 4b407994..e68d375f 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/set_angle.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/set_angle.gd
@@ -1,17 +1,35 @@
-# `set_angle object degrees [wait]`
+# `set_angle object target_degrees [wait]`
+#
+# Turns a movable `ESCItem` or `ESCPlayer` to face a given target direction.
 #
-# 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.
+# The rotation direction will be determined by the shortest path - e.g.
+# rotating from facing up (0 degrees) to left (270) will be a 90 degree turn
+# anti-clockwise rather than a 270 degree clockwise turn.
+#
+# The final animation used is determined by the directions which have
+# been configured for the object. If the item has a direction configured which
+# has been drawn to show it facing to the right, and this direction has been
+# defined to cover the angle from 45 to 135 degrees, setting the target angle
+# to 120 degrees will result in the right-facing animation being used.
+#
+# The number of intermediate animations shown while turning the 
+# item will depend on the directions specified in the item's definition. A 16
+# direction character will turn through 8 different directions to turn 180 
+# degrees, a 4 direction character only 2. The wait time will determine how
+# long the idle animation for each direction is played before using the next
+# direction's animation. As such, if wait was set to 1 second, a 16 direction
+# character would take 8 seconds to turn 180 degrees, a 4 direction character
+# would take 2 seconds.
 #
 # **Parameters**
 #
 # - *object*: Global ID of the object to turn
-# - *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`)
+# - *target_degrees*: Number of degrees by which `object` is to be turned
+# - *wait*: Number of seconds to wait for while playing each animation occurring 
+#   between the current angle of `object` and the target angle. A value of
+#   `0` will complete the turn immediately (default: `0`)
 #
 # @ESC
 extends ESCBaseCommand
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_state.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_state.gd
index d5b877d6..1a81ecaf 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/set_state.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/set_state.gd
@@ -1,12 +1,16 @@
 # `set_state object state [immediate]`
 #
 # Changes the state of `object` to the one specified.
-#
+# This command is primarily used to play animations. 
+# 
 # If the specified object's associated animation player has an animation
-# with the same name, that that animation is also played.
+# with the same name, that animation is also played.
 #
-# Can be used to change the appearance of an item or player
-# character. See https://docs.escoria-framework.org/states for details.
+# When the "state" of the object is set - for example, a door may be set
+# to a "closed" state - this plays the matching "close" animation if one exists
+# (to show the door closing in the game). When you re-enter the room (via a
+# different entry), or restore a saved game, the state of the door object 
+# will be restored - showing the door as a closed door.
 #
 # **Parameters**
 #
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/show_menu.gd b/addons/escoria-core/game/core-scripts/esc/commands/show_menu.gd
index 2a90315a..abd5ccc2 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/show_menu.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/show_menu.gd
@@ -2,9 +2,12 @@
 #
 # 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.
+# the menu or not. 
+# Setting `enable_automatic_transition` to false allows you to manage the
+# transition effect for your menu as it transitions in and out. Place a
+# `transition` command in the menu's `setup` event to manage the look of the
+# transition in, and in the menu's `exit_scene` event to manage the look of the
+# transition out.
 #
 # **Parameters**
 #
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/stop.gd b/addons/escoria-core/game/core-scripts/esc/commands/stop.gd
index c1264843..e621d106 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/stop.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/stop.gd
@@ -1,6 +1,8 @@
 # `stop`
 #
-# Stops the current event's execution.
+# Stops the current event's execution. Note that this will stop the current 
+# script entirely - if you're within a conditional block, the code after the
+# conditional block will not be executed.
 #
 # @ESC
 extends ESCBaseCommand
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd b/addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd
index 4b834cbc..ce34b92d 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd
@@ -1,12 +1,19 @@
-# `stop_snd [player]`
+# `stop_snd [audio_bus]`
 #
-# Stops the given sound player's stream.
+# Stops the given audio bus's stream.
 #
+# By default there are 3 audio buses set up by Escoria : `_sound`, which is
+# used to play non-looping sound effects; `_music`, which plays looping music; 
+# and `_speech`, which plays non-looping voice files (default: `_music`).
+#
+# Each simultaneous sound (e.g. multiple game sound effects) will require its 
+# own bus. To create additional buses, see the Godot sound documentation :
+# [Audio buses](https://docs.godotengine.org/en/stable/tutorials/audio/audio_buses.html#doc-audio-buses)
+# 
 # **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`)
+# - *audio_bus*: Bus to stop ("_sound", "_music", "_speech", or a custom
+#   audio bus you have created.) 
 #
 # @ESC
 extends ESCBaseCommand
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/transition.gd b/addons/escoria-core/game/core-scripts/esc/commands/transition.gd
index edfdd840..d67f2846 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/transition.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/transition.gd
@@ -1,6 +1,9 @@
 # `transition transition_name mode [delay]`
 #
-# Performs a transition into or out of a room programmatically.
+# Runs a transition effect - generally used when entering or leaving a room.
+# Transitions are implemented as Godot shaders. Custom transitions can be made
+# by creating a shader in the `game/scenes/transitions/shaders/` folder within
+# the escoria-core plugin folder.
 #
 # **Parameters**
 #
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/turn_to.gd b/addons/escoria-core/game/core-scripts/esc/commands/turn_to.gd
index 63ace2f5..bbbc17b8 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/turn_to.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/turn_to.gd
@@ -8,6 +8,16 @@
 # `ESCLocation` a `Global ID` and use this value as the `object_to_face`
 # parameter.
 #
+# While turning, the number of directions the item faces will depend on
+# the number of `directions` defined for the object. A 16 direction character
+# for example will display 8 directions of animation while turning to face an
+# object that is 180 degrees away, a 4 direction character would only face 2
+# directions to make the same turn. As the idle animation will be played for
+# `wait` seconds for each direction the object faces, a 16 direction character
+# would take 8 seconds to rotate 180 degrees with a 1 second `wait` time,
+# whereas a 4 direction character would only take 2 seconds to make the same
+# rotation.
+#
 # **Parameters**
 #
 # - *object*: Global ID of the object to be turned
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/walk.gd b/addons/escoria-core/game/core-scripts/esc/commands/walk.gd
index a75eb1fa..f8f93ef7 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/walk.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/walk.gd
@@ -1,8 +1,11 @@
 # `walk object target [walk_fast]`
 #
-# Moves the specified `ESCPlayer` or movable `ESCItem` to `target`
-# while playing `object`'s walking animation. This command is non-blocking.
+# Moves the specified `ESCPlayer` or movable `ESCItem` to the `target` 
+# ESCItem's location while playing `object`'s walking animation. This command
+# is non-blocking.
 # This command will use the normal walk speed by default.
+# If the `target` ESCItem has a child ESCLocation node, the walk destination
+# will be the position of the ESCLocation.
 #
 # **Parameters**
 #
diff --git a/addons/escoria-core/game/core-scripts/esc/commands/walk_block.gd b/addons/escoria-core/game/core-scripts/esc/commands/walk_block.gd
index 2385c3b0..44870e33 100644
--- a/addons/escoria-core/game/core-scripts/esc/commands/walk_block.gd
+++ b/addons/escoria-core/game/core-scripts/esc/commands/walk_block.gd
@@ -1,8 +1,11 @@
 # `walk_block object target [walk_fast]`
 #
-# Moves the specified `ESCPlayer` or movable `ESCItem` to `target`
-# while playing `object`'s walking animation. This command is blocking.
+# Moves the specified `ESCPlayer` or movable `ESCItem` to the `target` 
+# ESCItem's location while playing `object`'s walking animation. This command
+# is blocking.
 # This command will use the normal walk speed by default.
+# If the `target` ESCItem has a child ESCLocation node, the walk destination
+# will be the position of the ESCLocation.
 #
 # **Parameters**
 #
diff --git a/game/rooms/room16/esc/current_scene_button.esc b/game/rooms/room16/esc/current_scene_button.esc
index 376a97aa..4bfd813b 100644
--- a/game/rooms/room16/esc/current_scene_button.esc
+++ b/game/rooms/room16/esc/current_scene_button.esc
@@ -2,6 +2,8 @@
 
 > [eq ESC_CURRENT_SCENE room16]
 	say player "This sure looks like room 16."
+	sched_event 1 worker1 r16_worker1_walk
+	sched_event 2 worker1 r16_worker2_walk
 	
 > [eq ESC_CURRENT_SCENE ESC_LAST_SCENE]
 	say player "I'll never say this."
diff --git a/game/rooms/room16/esc/room16.esc b/game/rooms/room16/esc/room16.esc
index 316c739e..35d391b1 100644
--- a/game/rooms/room16/esc/room16.esc
+++ b/game/rooms/room16/esc/room16.esc
@@ -12,5 +12,4 @@
 	teleport player r16_r_exit
 	# Set player look down
 	set_angle player 180
-	stop
-
+	stop
\ No newline at end of file
diff --git a/game/rooms/room16/esc/worker_script.esc b/game/rooms/room16/esc/worker_script.esc
new file mode 100644
index 00000000..c705cbfd
--- /dev/null
+++ b/game/rooms/room16/esc/worker_script.esc
@@ -0,0 +1,5 @@
+:r16_worker1_walk
+	walk worker1 worker1location
+
+:r16_worker2_walk
+	walk worker2 worker2location
diff --git a/game/rooms/room16/room16.tscn b/game/rooms/room16/room16.tscn
index 5f7b6bda..adf5e49b 100644
--- a/game/rooms/room16/room16.tscn
+++ b/game/rooms/room16/room16.tscn
@@ -1,4 +1,4 @@
-[gd_scene load_steps=11 format=2]
+[gd_scene load_steps=12 format=2]
 
 [ext_resource path="res://addons/escoria-core/game/core-scripts/esc_terrain.gd" type="Script" id=1]
 [ext_resource path="res://game/rooms/room14/background.tscn" type="PackedScene" id=2]
@@ -9,6 +9,7 @@
 [ext_resource path="res://addons/escoria-core/game/core-scripts/esc_item.gd" type="Script" id=7]
 [ext_resource path="res://game/rooms/room14/r_door.tscn" type="PackedScene" id=8]
 [ext_resource path="res://game/items/escitems/button.tscn" type="PackedScene" id=9]
+[ext_resource path="res://game/characters/worker/worker.tscn" type="PackedScene" id=10]
 
 [sub_resource type="NavigationPolygon" id=1]
 vertices = PoolVector2Array( 1168.92, 640.557, 1182.53, 588.863, 1269.59, 622.872, 1275.03, 799.721, 864.626, 613.518, 1143.08, 613.35, -9.16094, 803.802, 386.666, 618.012, 129.634, 615.792, 84.5821, 654.06, -6.44019, 711.297, 3.15687, 646.051, 59.2201, 628.698 )
@@ -56,6 +57,7 @@ esc_script = "res://game/rooms/room16/esc/left_exit.esc"
 is_exit = true
 tooltip_name = "Left exit"
 default_action = "walk"
+combine_when_selected_action_is_in = [  ]
 dialog_color = Color( 1, 1, 1, 1 )
 animations = null
 
@@ -70,6 +72,7 @@ global_id = "r12_l_exit"
 [node name="r_door" parent="Hotspots" instance=ExtResource( 8 )]
 global_id = "r16_r_exit"
 esc_script = "res://game/rooms/room16/esc/right_exit.esc"
+combine_when_selected_action_is_in = [  ]
 
 [node name="ESCLocation" type="Position2D" parent="Hotspots/r_door"]
 position = Vector2( 1231.78, 360.624 )
@@ -86,6 +89,7 @@ interaction_direction = 180
 position = Vector2( 30, 0 )
 global_id = "current_scene_button"
 esc_script = "res://game/rooms/room16/esc/current_scene_button.esc"
+combine_when_selected_action_is_in = [  ]
 
 [node name="Position2D" type="Position2D" parent="current_scene_button"]
 position = Vector2( 336, 384 )
@@ -97,6 +101,25 @@ margin_right = 398.887
 margin_bottom = 213.561
 text = "Is this room 16?"
 align = 1
-__meta__ = {
-"_edit_use_anchors_": false
-}
+
+[node name="worker" parent="." instance=ExtResource( 10 )]
+position = Vector2( 789, 362 )
+global_id = "worker1"
+esc_script = "res://game/rooms/room16/esc/worker_script.esc"
+combine_when_selected_action_is_in = [  ]
+
+[node name="worker2" parent="." instance=ExtResource( 10 )]
+position = Vector2( 988, 364 )
+global_id = "worker2"
+esc_script = ""
+combine_when_selected_action_is_in = [  ]
+
+[node name="ESCLocation" type="Position2D" parent="."]
+position = Vector2( 45, 513 )
+script = ExtResource( 5 )
+global_id = "worker1location"
+
+[node name="ESCLocation2" type="Position2D" parent="."]
+position = Vector2( 123, 512 )
+script = ExtResource( 5 )
+global_id = "worker2location"