From 012d978d668b8f5322d16532220a4e014176361c Mon Sep 17 00:00:00 2001 From: Dennis Ploeger Date: Sun, 21 Nov 2021 21:10:56 +0100 Subject: [PATCH] fix: Optimized ESC command docs (#450) Co-authored-by: Dennis Ploeger Co-authored-by: Duncan Brown --- .../core-scripts/esc/commands/accept_input.gd | 23 ++++++--- .../game/core-scripts/esc/commands/anim.gd | 10 ++-- .../core-scripts/esc/commands/anim_block.gd | 14 ++++-- .../core-scripts/esc/commands/camera_push.gd | 20 ++++++-- .../esc/commands/camera_set_limits.gd | 12 +++-- .../esc/commands/camera_set_pos.gd | 12 +++-- .../esc/commands/camera_set_target.gd | 13 +++-- .../esc/commands/camera_set_zoom.gd | 15 ++++-- .../esc/commands/camera_set_zoom_height.gd | 12 +++-- .../core-scripts/esc/commands/camera_shift.gd | 19 +++++-- .../core-scripts/esc/commands/change_scene.gd | 17 ++++--- .../game/core-scripts/esc/commands/custom.gd | 13 +++-- .../game/core-scripts/esc/commands/debug.gd | 6 ++- .../core-scripts/esc/commands/dec_global.gd | 12 +++-- .../esc/commands/enable_terrain.gd | 8 ++- .../core-scripts/esc/commands/hide_menu.gd | 12 +++-- .../core-scripts/esc/commands/inc_global.gd | 8 ++- .../esc/commands/inventory_add.gd | 6 ++- .../esc/commands/inventory_remove.gd | 6 ++- .../core-scripts/esc/commands/play_snd.gd | 10 +++- .../esc/commands/queue_resource.gd | 13 ++--- .../core-scripts/esc/commands/rand_global.gd | 13 +++-- .../game/core-scripts/esc/commands/say.gd | 19 ++++--- .../core-scripts/esc/commands/sched_event.gd | 14 ++++-- .../core-scripts/esc/commands/set_active.gd | 11 ++-- .../core-scripts/esc/commands/set_angle.gd | 14 +++--- .../esc/commands/set_animations.gd | 7 ++- .../core-scripts/esc/commands/set_global.gd | 8 ++- .../core-scripts/esc/commands/set_globals.gd | 9 +++- ...{set_hud_visible.gd => set_gui_visible.gd} | 13 ++--- .../esc/commands/set_interactive.gd | 9 +++- .../esc/commands/set_sound_state.gd | 50 ------------------- .../core-scripts/esc/commands/set_speed.gd | 7 ++- .../core-scripts/esc/commands/set_state.gd | 15 +++--- .../core-scripts/esc/commands/show_menu.gd | 12 +++-- .../game/core-scripts/esc/commands/slide.gd | 15 ++++-- .../core-scripts/esc/commands/slide_block.gd | 15 ++++-- .../game/core-scripts/esc/commands/spawn.gd | 17 +++++-- .../game/core-scripts/esc/commands/stop.gd | 2 +- .../core-scripts/esc/commands/stop_snd.gd | 41 +++++++++++++++ .../core-scripts/esc/commands/teleport.gd | 9 +++- .../core-scripts/esc/commands/teleport_pos.gd | 10 +++- .../core-scripts/esc/commands/transition.gd | 13 ++--- .../game/core-scripts/esc/commands/turn_to.gd | 12 +++-- .../game/core-scripts/esc/commands/wait.gd | 8 +-- .../game/core-scripts/esc/commands/walk.gd | 13 +++-- .../core-scripts/esc/commands/walk_block.gd | 13 +++-- .../core-scripts/esc/commands/walk_to_pos.gd | 12 ++++- .../esc/commands/walk_to_pos_block.gd | 12 ++++- .../game/core-scripts/esc_animation_player.gd | 14 ++++++ .../save_data/esc_save_manager.gd | 10 ++-- .../game/core-scripts/utils/esc_utils.gd | 2 + .../escoria-dialog-simple/chooser/simple.gd | 17 ++++--- game/rooms/room01/esc/right_exit.esc | 2 +- game/rooms/room01/esc/room01.esc | 2 +- game/rooms/room02/esc/left_exit.esc | 2 +- game/rooms/room02/esc/right_exit.esc | 2 +- game/rooms/room06/esc/worker.esc | 4 +- .../rooms/room10/esc/button_play_bg_music.esc | 2 +- .../rooms/room10/esc/button_stop_bg_music.esc | 2 +- game/rooms/room10/esc/left_exit.esc | 2 +- game/rooms/room10/esc/right_exit.esc | 2 +- game/rooms/room11/esc/left_exit.esc | 2 +- game/rooms/room11/esc/right_exit.esc | 2 +- game/rooms/room12/esc/left_exit.esc | 2 +- game/rooms/room12/esc/right_exit.esc | 2 +- game/rooms/room13/esc/left_exit.esc | 2 +- game/rooms/room13/esc/right_exit.esc | 1 - game/rooms/room14/esc/left_exit.esc | 2 +- game/rooms/room14/esc/right_exit.esc | 2 +- game/rooms/room15/esc/left_exit.esc | 2 +- game/start_game.esc | 2 +- project.godot | 18 +++---- 73 files changed, 494 insertions(+), 260 deletions(-) rename addons/escoria-core/game/core-scripts/esc/commands/{set_hud_visible.gd => set_gui_visible.gd} (54%) delete mode 100644 addons/escoria-core/game/core-scripts/esc/commands/set_sound_state.gd create mode 100644 addons/escoria-core/game/core-scripts/esc/commands/stop_snd.gd diff --git a/addons/escoria-core/game/core-scripts/esc/commands/accept_input.gd b/addons/escoria-core/game/core-scripts/esc/commands/accept_input.gd index 3f2e909d..c6691276 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/accept_input.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/anim.gd b/addons/escoria-core/game/core-scripts/esc/commands/anim.gd index 1f755f11..6c0df595 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/anim.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/anim_block.gd b/addons/escoria-core/game/core-scripts/esc/commands/anim_block.gd index 7f923e19..6c49c8f4 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/anim_block.gd +++ b/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") diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_push.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_push.gd index 28598c9a..fc60ca5b 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_push.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_limits.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_set_limits.gd index 50f9a48b..4eafc09b 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_limits.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_pos.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_set_pos.gd index b979e482..8b8cfd4f 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_pos.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_target.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_set_target.gd index d2bb0a61..ed51ac08 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_target.gd +++ b/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] ] diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom.gd index 507b4dd0..72377d19 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom_height.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom_height.gd index 0292a27f..9203adb5 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_set_zoom_height.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/camera_shift.gd b/addons/escoria-core/game/core-scripts/esc/commands/camera_shift.gd index 87fda100..b93b0764 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/camera_shift.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/change_scene.gd b/addons/escoria-core/game/core-scripts/esc/commands/change_scene.gd index 6b272bd1..a5a3c260 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/change_scene.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/custom.gd b/addons/escoria-core/game/core-scripts/esc/commands/custom.gd index 93a9941f..29ca4dc1 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/custom.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/debug.gd b/addons/escoria-core/game/core-scripts/esc/commands/debug.gd index b65466d5..873fe80a 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/debug.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/dec_global.gd b/addons/escoria-core/game/core-scripts/esc/commands/dec_global.gd index e9503ecc..abea76d9 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/dec_global.gd +++ b/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", [ diff --git a/addons/escoria-core/game/core-scripts/esc/commands/enable_terrain.gd b/addons/escoria-core/game/core-scripts/esc/commands/enable_terrain.gd index fc790aec..4b0f6082 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/enable_terrain.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/hide_menu.gd b/addons/escoria-core/game/core-scripts/esc/commands/hide_menu.gd index 216bdf44..fb9fbe30 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/hide_menu.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/inc_global.gd b/addons/escoria-core/game/core-scripts/esc/commands/inc_global.gd index d409dfa8..ea364f5e 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/inc_global.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/inventory_add.gd b/addons/escoria-core/game/core-scripts/esc/commands/inventory_add.gd index ce6e3066..48c953f5 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/inventory_add.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/inventory_remove.gd b/addons/escoria-core/game/core-scripts/esc/commands/inventory_remove.gd index 0bfee535..9d2477ad 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/inventory_remove.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/play_snd.gd b/addons/escoria-core/game/core-scripts/esc/commands/play_snd.gd index e7a199fe..b454be25 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/play_snd.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/queue_resource.gd b/addons/escoria-core/game/core-scripts/esc/commands/queue_resource.gd index 971234ee..be0ee6a0 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/queue_resource.gd +++ b/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 -# 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 -# 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 -# resources that belong to the next scene). +# Queues the loading of the given resource into the resource cache. +# +# **Parameters** +# +# - *path*: Path of the resource to cache +# - *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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/rand_global.gd b/addons/escoria-core/game/core-scripts/esc/commands/rand_global.gd index 14bc9555..59108b42 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/rand_global.gd +++ b/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] ] diff --git a/addons/escoria-core/game/core-scripts/esc/commands/say.gd b/addons/escoria-core/game/core-scripts/esc/commands/say.gd index 6d35a4c4..1684e331 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/say.gd +++ b/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 -# until the dialog finishes playing. +# Displays the specified string as dialog spoken by the player. Blocks execution +# until the dialog has finished playing. # -# The text supports translation keys by prepending the key and separating -# it with a `:` from the text. +# **Parameters** +# +# - *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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/sched_event.gd b/addons/escoria-core/game/core-scripts/esc/commands/sched_event.gd index 2fded216..c21f8778 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/sched_event.gd +++ b/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. -# If another event is running at the time, execution starts when the running -# event ends. +# Schedules the execution to run at a later time. +# +# 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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_active.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_active.gd index 6c9d3c80..e4630335 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_active.gd +++ b/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. -# Inactive objects are hidden in the scene. +# Changes the "active" state of the object. `active` can be `true` or `false`. +# Inactive objects are invisible in the room. +# +# **Parameters** +# +# - *object* Global ID of the object +# - *active* Whether `object` should be active. # # @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 507c88d4..c254a99c 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,14 +1,14 @@ # `set_angle object degrees [wait]` # -# Turns object to a degrees angle without animations. 0 sets object facing -# forward, 90 sets it 90 degrees clockwise ("east") etc. When turning to the -# destination angle, animations are played if they're defined in animations. +# Turns a movable `ESCItem` or `ESCPlayer`. # -# object must be player or interactive. degrees must be between [0, 360] or an -# error is reported. +# **Parameters** # -# The wait parameter sets how long to wait for each intermediate angle. It -# defaults to 0, meaning the turnaround is immediate. +# - *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`) # # @ESC extends ESCBaseCommand diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_animations.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_animations.gd index 648b6464..554e40f4 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_animations.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_global.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_global.gd index a08225fe..8b931aeb 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_global.gd +++ b/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", -# "false" or an integer. +# Changes the value of a global. +# +# **Parameters** +# +# - *name*: Name of the global +# - *value*: Value to set (can be of type string, boolean, integer or float) # # @ESC extends ESCBaseCommand diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_globals.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_globals.gd index c50a67bb..0bf6177e 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_globals.gd +++ b/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 "*" -# matches zero or more arbitrary characters and "?" matches any single +# Changes the value of multiple globals using a wildcard pattern, where `*` +# 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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_hud_visible.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_gui_visible.gd similarity index 54% rename from addons/escoria-core/game/core-scripts/esc/commands/set_hud_visible.gd rename to addons/escoria-core/game/core-scripts/esc/commands/set_gui_visible.gd index 5db05d5e..11715073 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_hud_visible.gd +++ b/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, -# 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 -# over the game at the moment. "visible" is true or false. +# Shows or hide the GUI. +# +# **Parameters** +# +# - *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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_interactive.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_interactive.gd index 237ab7b8..062659fa 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_interactive.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_sound_state.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_sound_state.gd deleted file mode 100644 index 50886815..00000000 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_sound_state.gd +++ /dev/null @@ -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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/set_speed.gd b/addons/escoria-core/game/core-scripts/esc/commands/set_speed.gd index f6840e31..102618a6 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/set_speed.gd +++ b/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 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 a5a11f35..6fc57975 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,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, -# it also plays that animation. +# If the specified object's associated animation player has an 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 -# frame +# **Parameters** +# +# - *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 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 1a3580bf..49ad67de 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 @@ -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. -# 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. +# Shows 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 to the menu (default: `false`) # # @ESC extends ESCBaseCommand diff --git a/addons/escoria-core/game/core-scripts/esc/commands/slide.gd b/addons/escoria-core/game/core-scripts/esc/commands/slide.gd index 71889656..ccfcc3d8 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/slide.gd +++ b/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 -# object1's "speed" property, unless overridden. This command is non-blocking. -# It does not respect the room's navigation polygons, so you can move items -# where the player can't walk. +# Moves `object` towards the position of `target`. This command is +# non-blocking. +# +# - *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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/slide_block.gd b/addons/escoria-core/game/core-scripts/esc/commands/slide_block.gd index d07d8789..23ca4ce7 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/slide_block.gd +++ b/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 -# object1's "speed" property, unless overridden. This command is blocking. -# It does not respect the room's navigation polygons, so you can move items -# where the player can't walk. +# Moves `object` towards the position of `target`. This command is +# blocking. +# +# - *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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/spawn.gd b/addons/escoria-core/game/core-scripts/esc/commands/spawn.gd index 054729d5..9f598bf2 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/spawn.gd +++ b/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 -# object2 (object2 is optional) +# Programmatically adds a new item to the scene. +# +# **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 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 a389c099..f4a5320d 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,6 @@ # `stop` # -# Stops the event's execution. +# Stops the current event's execution. # # @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 new file mode 100644 index 00000000..42affa1b --- /dev/null +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/teleport.gd b/addons/escoria-core/game/core-scripts/esc/commands/teleport.gd index fd3edda1..7451da94 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/teleport.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/teleport_pos.gd b/addons/escoria-core/game/core-scripts/esc/commands/teleport_pos.gd index 65333259..4bc83f61 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/teleport_pos.gd +++ b/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 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 9d8a09c3..00c34481 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/transition.gd +++ b/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: -# - transition_name: Name of the transition shader from one of the transition +# **Parameters** +# +# - *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 -# - delay: Delay for the transition to take. Defaults to 1 second +# - *mode*: Set to `in` to transition into or `out` to transition out of the room +# - *delay*: Delay in seconds before starting the transition (default: `1`) # # @ESC extends ESCBaseCommand 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 34cd0774..32978e83 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 @@ -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 -# defaults to 0, meaning the turnaround is immediate. -# +# **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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/wait.gd b/addons/escoria-core/game/core-scripts/esc/commands/wait.gd index 3901bd42..afc7075e 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/wait.gd +++ b/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 -# the "seconds" parameter. -# - seconds can be either and integer or a floating value +# Blocks execution of the current event. +# +# **Parameters** +# +# - *seconds*: Number of seconds to block # # @ESC extends ESCBaseCommand 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 0ecc75c6..fd56c387 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,13 @@ -# `walk object1 object2 [speed]` +# `walk object target [speed]` # -# Walks, using the walk animation, object1 towards the position of object2, -# at the speed determined by object1's "speed" property, -# unless overridden. This command is non-blocking. +# Moves the specified `ESCPlayer` or movable `ESCItem` to `target` w +# hile playing `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) # # @ESC extends ESCBaseCommand 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 35dea689..e1dc6764 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,13 @@ -# `walk_block object1 object2 [speed]` +# `walk_block object target [speed]` # -# Walks, using the walk animation, object1 towards the position of object2, -# at the speed determined by object1's "speed" property, -# unless overridden. This command is blocking. +# Moves the specified `ESCPlayer` or movable `ESCItem` to `target` +# while playing `object`'s walking animation. 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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos.gd b/addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos.gd index 8634fc51..2779fced 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos_block.gd b/addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos_block.gd index c21492ae..821d9efd 100644 --- a/addons/escoria-core/game/core-scripts/esc/commands/walk_to_pos_block.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/esc_animation_player.gd b/addons/escoria-core/game/core-scripts/esc_animation_player.gd index 3c612075..6aa748fe 100644 --- a/addons/escoria-core/game/core-scripts/esc_animation_player.gd +++ b/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 diff --git a/addons/escoria-core/game/core-scripts/save_data/esc_save_manager.gd b/addons/escoria-core/game/core-scripts/save_data/esc_save_manager.gd index e3cb9d25..9789525c 100644 --- a/addons/escoria-core/game/core-scripts/save_data/esc_save_manager.gd +++ b/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": - load_statements.append(ESCCommand.new("set_sound_state %s %s true" \ - % [object_global_id, - save_game.objects[object_global_id]["state"]]) + if object_global_id in ["_music", "_sound", "_speech"]: + load_statements.append( + ESCCommand.new("play_snd %s %s" % [ + save_game.objects[object_global_id]["state"], + object_global_id, + ]) ) load_statements.append( diff --git a/addons/escoria-core/game/core-scripts/utils/esc_utils.gd b/addons/escoria-core/game/core-scripts/utils/esc_utils.gd index 515dddbf..6fa09c95 100644 --- a/addons/escoria-core/game/core-scripts/utils/esc_utils.gd +++ b/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) diff --git a/addons/escoria-dialog-simple/chooser/simple.gd b/addons/escoria-dialog-simple/chooser/simple.gd index 903c2612..6bf3b062 100644 --- a/addons/escoria-dialog-simple/chooser/simple.gd +++ b/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() - _option_node.text = (option as ESCDialogOption).option - _option_node.flat = true - _option_node.add_color_override("font_color", color_normal) - _option_node.add_color_override("font_color_hover", color_hover) - _vbox.add_child(_option_node) - _option_node.connect("pressed", self, "_on_answer_selected", [option]) + if option.is_valid(): + var _option_node = Button.new() + _option_node.text = (option as ESCDialogOption).option + _option_node.flat = true + _option_node.add_color_override("font_color", color_normal) + _option_node.add_color_override("font_color_hover", color_hover) + _vbox.add_child(_option_node) + _option_node.connect("pressed", self, "_on_answer_selected", [ + option + ]) if self.dialog.avatar != "-": $AvatarContainer.add_child( diff --git a/game/rooms/room01/esc/right_exit.esc b/game/rooms/room01/esc/right_exit.esc index 4128b8bc..f7d53f2c 100644 --- a/game/rooms/room01/esc/right_exit.esc +++ b/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" diff --git a/game/rooms/room01/esc/room01.esc b/game/rooms/room01/esc/room01.esc index 2d8e0d40..5042d5ef 100644 --- a/game/rooms/room01/esc/room01.esc +++ b/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 diff --git a/game/rooms/room02/esc/left_exit.esc b/game/rooms/room02/esc/left_exit.esc index feabc671..9091136a 100644 --- a/game/rooms/room02/esc/left_exit.esc +++ b/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" diff --git a/game/rooms/room02/esc/right_exit.esc b/game/rooms/room02/esc/right_exit.esc index b5ff0423..1f0b52de 100644 --- a/game/rooms/room02/esc/right_exit.esc +++ b/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" diff --git a/game/rooms/room06/esc/worker.esc b/game/rooms/room06/esc/worker.esc index 808b7566..6d257955 100644 --- a/game/rooms/room06/esc/worker.esc +++ b/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 diff --git a/game/rooms/room10/esc/button_play_bg_music.esc b/game/rooms/room10/esc/button_play_bg_music.esc index 4559c7cb..d6e5bdf2 100644 --- a/game/rooms/room10/esc/button_play_bg_music.esc +++ b/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 diff --git a/game/rooms/room10/esc/button_stop_bg_music.esc b/game/rooms/room10/esc/button_stop_bg_music.esc index c57ffecc..72d161bd 100644 --- a/game/rooms/room10/esc/button_stop_bg_music.esc +++ b/game/rooms/room10/esc/button_stop_bg_music.esc @@ -1,2 +1,2 @@ :use -set_sound_state _music off true +stop_snd diff --git a/game/rooms/room10/esc/left_exit.esc b/game/rooms/room10/esc/left_exit.esc index 339599ea..a3ec3539 100644 --- a/game/rooms/room10/esc/left_exit.esc +++ b/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" diff --git a/game/rooms/room10/esc/right_exit.esc b/game/rooms/room10/esc/right_exit.esc index 9153a73f..23b91ea8 100755 --- a/game/rooms/room10/esc/right_exit.esc +++ b/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" diff --git a/game/rooms/room11/esc/left_exit.esc b/game/rooms/room11/esc/left_exit.esc index 8d75e752..e8dba92e 100755 --- a/game/rooms/room11/esc/left_exit.esc +++ b/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" diff --git a/game/rooms/room11/esc/right_exit.esc b/game/rooms/room11/esc/right_exit.esc index 00b5360f..a3ed9590 100644 --- a/game/rooms/room11/esc/right_exit.esc +++ b/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 diff --git a/game/rooms/room12/esc/left_exit.esc b/game/rooms/room12/esc/left_exit.esc index 46e92c11..94cb2c5e 100644 --- a/game/rooms/room12/esc/left_exit.esc +++ b/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" diff --git a/game/rooms/room12/esc/right_exit.esc b/game/rooms/room12/esc/right_exit.esc index a74e22ad..52e29ac6 100644 --- a/game/rooms/room12/esc/right_exit.esc +++ b/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" diff --git a/game/rooms/room13/esc/left_exit.esc b/game/rooms/room13/esc/left_exit.esc index 765f972e..181aa0fa 100644 --- a/game/rooms/room13/esc/left_exit.esc +++ b/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" diff --git a/game/rooms/room13/esc/right_exit.esc b/game/rooms/room13/esc/right_exit.esc index cf038e01..9d053531 100644 --- a/game/rooms/room13/esc/right_exit.esc +++ b/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" diff --git a/game/rooms/room14/esc/left_exit.esc b/game/rooms/room14/esc/left_exit.esc index ccd7945a..9d531190 100644 --- a/game/rooms/room14/esc/left_exit.esc +++ b/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" diff --git a/game/rooms/room14/esc/right_exit.esc b/game/rooms/room14/esc/right_exit.esc index a347e3af..3c0f8d6c 100644 --- a/game/rooms/room14/esc/right_exit.esc +++ b/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" diff --git a/game/rooms/room15/esc/left_exit.esc b/game/rooms/room15/esc/left_exit.esc index c1fcf214..6f193025 100644 --- a/game/rooms/room15/esc/left_exit.esc +++ b/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" diff --git a/game/start_game.esc b/game/start_game.esc index 35e9208c..aa12e03b 100644 --- a/game/start_game.esc +++ b/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 diff --git a/project.godot b/project.godot index 525fa468..44f6e409 100644 --- a/project.godot +++ b/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": "",