See :ref:`global_flags`.
All objects in the game have a global ID which is used to identify them in commands. The ID is configured in the object's scene.
Each object can have a "state". This state is stored in the global state of the game and as part of a savegame. The object's state is set when the scene is instanced.
States are most commonly used to execute an animation. Where an animation in the object's scene has the same name as a state being set, the animation is run when that state is set.
An example for where you might want to use states might be: If your game has a blank canvas and you "use" some paint on it to paint a picture, setting the state to "painted" would play the corresponding animation which would set the canvas graphic to the "painted" version. When the game is saved, the "painted" state of the canvas would be stored, so on reload the "painted" rather than the blank image would be shown.
For :doc:`bg_sound <../api/EscSoundPlayer>` and :doc:`bg_music <../api/EscMusicPlayer>` objects, the state also represents the music or sound that is currently running.
Objects can be either active or inactive. Inactive objects are hidden and not clickable.
Item activity is also handled as a special case of global flags. If the
check starts with a/
, like a/elaine
, you're checking if "elaine" is
active.
:ready > [!a/elaine] say player player_no_elaine_yet:"It would appear Elaine hasn't arrived yet."
If you have an object that only blocks the terrain and is something you can
move behind, you probably don't want to bother with interaction areas
and tooltip texts. In this case, just set is_interactive
to
false
and the item will not be checked for interactions. Its mouse
events won't be connected, either.
Global flags (also known as game variables) define the state of the game and can be true/false, a number, or a string. All commands and groups can be conditionally set based on the value of a global flag.
Global flags are, as the name implies, global, and continue to survive after leaving the room where they are created/set. This means that a value set early in your game is still able to be queried many rooms later.
Global flags can be created anywhere in an Escoria script as needed using the set_global command. They don't need to be declared in advance.
set_global <global name> <global value> e.g. set_global number_of_keys_found 3
By default a flag will return false if you haven't declared or defined it. This feature allows for code like the below--that configures a room--to be executed the first time the room is visited, but won't be run again should the player return to the room.
:ready > [!room1_visited] # Set room1_visited variable so this code runs only once set_global room1_visited true # Play the window's sunrise animation anim window play_sunrise_effect
The inventory is handled as a special case of global flags. All flags
with a name starting with i/
are considered to be an inventory object with
the inventory object's global ID following. Example:
# Waits for 5 seconds if the player has the key in its inventory wait 5 [i/key]
All ESC scripts are divided into a series of events which in turn run commands or dialogs.
To use an event in your script, specify the name of the event preceded by a colon. All commands following the event identifier are considered part of that event until another event is defined in the same script file.
:push say player "I pushed the door." say player "It didn't do anything." # A new ("pull") event starts here :pull say player "The door is now open"
Some events are hard-coded into Escoria. The ones that are "internal engine use only" are
- load
- room_selector
- transition_in
- transition_out
Events that are considered "for game developer use" are
- init : Run first as part of your primary Escoria game script. This is where you would place the commands for a company logo cutscene.
- exit_scene : Will be called when "Is Exit" is enabled on an ESCItem and the player "uses" that item. You might play a closing door sound here for example.
- newgame : This is what is called when "Start Game" is chosen from your menu. The main use would be to have a change_scene command here to load your first game room.
- setup : This runs first as part of loading a room. Anything coded here will happen before the room is visible (i.e. before the "transition in").
- ready : These are commands that will run when a room loads, after it becomes visible (i.e. once ":setup" completes and after the "transition in").
An example of how you might initialize a room is:
:setup teleport player door1 [eq ESC_LAST_SCENE scene1] teleport player door2 [eq ESC_LAST_SCENE scene2]
This will teleport the player to the appropriate point in the scene
(the ESCLocation "door1" or "door2") depending on the last visited scene.
The last visited scene is stored in the special global state
ESC_LAST_SCENE
.
Any plugins you use may define their own events that you can script actions for. The sample user interfaces, for example, include events for look and use. If you are using the 9-verb interface and click the look button followed by an object, then any code inside the :look event in that object's script will be run.
You can create an event with any name you like (though avoiding event names Escoria already uses, e.g. init, is suggested to avoid bugs and/or confusion.)
Most of the time you'll define events as part of creating your UI (e.g. you might create a nose icon and attach it to a "sniff" event). See :doc:`https://docs.escoria-framework.org/en/devel/advanced/create_ui.html#verbs` for further details.
Events understand a series of flags. The flags that are currently implemented include the following:
TK
stands for "telekinetic": The player won't walk over to an item before saying a line of dialogNO_TT
stands for "No tooltip": The tooltip is hidden for the duration of the eventNO_UI
stands for "No User Interface": The UI is hidden for the duration of the event. Useful for when you want something to look like a cutscene but don't want to disable input for skipping dialog.NO_SAVE
disables saving: Use this in cutscenes and anywhere a badly-timed autosave would leave your game in a messed-up state.
Specify a flag using the event name, a pipe character, and then the flag. For example:
:look | TK say current_player "I don't see anything unusual about it."
Commands consist of a single word followed by some parameters. Parameters can be a single word or a string in quotes.
# one parameter "player", another parameter "hello world" say player "hello world"
In order to run a command depending on the value of a flag, use []
with a
list of comma-separated conditions. All conditions in this list must be true.
Placing the character !
before a flag can be used to negate that flag.
Example:
# runs the command only if the door_open flag is true say player "The door is open" [door_open]
# runs the group only if door_open is false and i/key is true > [!door_open,i/key] say player "The door is close, maybe I can try this key in my inventory"
Additionally, there is a set of comparison operators for use with global
integers: eq
, gt
and lt
, all of which can be negated.
Example:
# runs the command only if the value of pieces_of_eight is greater than 5 set_state inv_pieces_of_eight money_bag [gt pieces_of_eight 5]
Commands can be grouped using the character > to start a group and incrementing the indentation of the commands that belong to the group. Example:
> set_global door_open true anim player pick_up # end of group
Groups can also use conditions:
# Present the key if the player already has it > [i/key] say player "I got the key!" anim player show_key
Some commands will block execution of the event until they finish; others won't. See the command reference for details on which commands block.
accept_input [type]
API-Doc
Sets how much input the game is to accept. This allows for cut scenes in which dialogue can be skipped (if [type] is set to SKIP), and ones where it can't (if [type] is set to NONE).
Parameters
- type: Type of inputs to accept (ALL)
ALL
: Accept all types of user inputSKIP
: Accept skipping dialogues but nothing elseNONE
: Deny all inputs (including opening menus)
Warning: SKIP
and NONE
also disable autosaves.
Warning: The type of user input accepted will persist even after the current event has ended. Remember to reset the input type at the end of cut-scenes!
anim_block object name [reverse]
API-Doc
Executes the animation specified in "name" on "object" while blocking other events from starting. The next command in the event will be executed when the animation is finished playing.
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
anim object name [reverse]
API-Doc
Executes the animation specified in "name" on "object" without blocking. The next command in the event will be executed immediately after the animation is started.
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
block_say
API-Doc
say
commands called subsequent to using the block_say
command will reuse the
dialog box type of the previous say
command if both dialog box types between the two say
commands match.
Different dialog box types can be used across multiple say
commands, with the latest one
used being preserved for reuse by the next say
command should the dialog box type specified by
both say
commands match.
This reuse will continue until a call to end_block_say
is made.
Using block_say
more than once prior to calling end_block_say
is idempotent and has the
following behaviour:
- If no
say
command has yet been encountered since the first use ofblock_say
, the result of using this command will be as described above. - If a
say
command has been encountered since the previous use ofblock_say
, the dialog box used with thatsay
command will continue to be reused for subsequentsay
commands should the dialog box type requested match. Note that the dialog box used with the nextsay
command may be different than the one currently being reused.
Example:
block say
say player "Picture's looking good."
say player "And so am I."
end_block_say
This example will reuse the same dialog box type since they are the same between both say
calls.
camera_push_block target [time] [type]
API-Doc
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. Blocks until the command completes.
Make sure the target is reachable if camera limits have been configured.
Parameters
- target: Global ID of the
ESCItem
to push the camera to.ESCItem
s have a "camera_node" property that can be set to point to a node (usually anESCLocation
node). If the "camera_node" property is empty,camera_push_block
will point the camera at theESCItem
s location. If however, theESCItem
has its "camera_node" property set, the command will instead point the camera at the node referenced by theESCItem
s "camera_node" property. - 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).
See https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
For more details see: https://docs.escoria-framework.org/camera
camera_push target [time] [type]
API-Doc
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.
Make sure the target is reachable if camera limits have been configured.
Parameters
- target: Global ID of the
ESCItem
to push the camera to.ESCItem
s have a "camera_node" property that can be set to point to a node (usually anESCLocation
node). If the "camera_node" property is empty,camera_push
will point the camera at theESCItem
s location. If however, theESCItem
has its "camera_node" property set, the command will instead point the camera at the node referenced by theESCItem
s "camera_node" property. - 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):
See https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
For more details see: https://docs.escoria-framework.org/camera
camera_set_limits camlimits_id
API-Doc
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 defined in the
camera limits
list of the currentESCRoom
For more details see: https://docs.escoria-framework.org/camera
camera_set_pos_block time x y
API-Doc
Moves the camera to the given absolute position over a time period. Blocks until the command completes.
Make sure the coordinates are reachable if camera limits have been configured.
Parameters
- time: 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
camera_set_pos time x y
API-Doc
Moves the camera to the given absolute position over a time period.
Parameters
- time: 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
camera_set_target_block time object
API-Doc
Configures the camera to follow the specified target object
(ESCItem) as it moves
around the current room. The transition to focus on the object
will happen
over a time period. Blocks until the command completes.
The camera will move as close as it can if camera limits have been configured
and the object
is at coordinates that are not reachable.
Parameters
- 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
camera_set_target time object
API-Doc
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 to move the camera
to follow
object
- object: Global ID of the target object
For more details see: https://docs.escoria-framework.org/camera
camera_set_zoom_block magnitude [time]
API-Doc
Zooms the camera in/out to the desired magnitude
. Values larger than '1' zoom
the camera out while smaller values zoom in. These values are relative to the
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.
Blocks until the command completes.
Zoom operations might not be as smooth as desired if the requested zoom level results in an edge of the camera meeting any defined camera limits.
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
camera_set_zoom magnitude [time]
API-Doc
Zooms the camera in/out to the desired magnitude
. Values larger than '1' zoom
the camera out while smaller values zoom in. These values are relative to the
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
- 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
camera_set_zoom_height_block pixels [time]
API-Doc
Zooms the camera in/out so it occupies the given height in pixels. Blocks until the command completes.
Parameters
- pixels: Target height in pixels (integer values only)
- 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
camera_set_zoom_height pixels [time]
API-Doc
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
camera_shift_block x y [time] [type]
API-Doc
Shifts the camera by the given horizontal and vertical amounts relative to the current location. Blocks until the command completes.
Make sure the destination coordinates are reachable if camera limits have been configured.
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).
See https://docs.godotengine.org/en/stable/classes/class_tween.html?highlight=tween#enumerations
For more details see: https://docs.escoria-framework.org/camera
camera_shift x y [time] [type]
API-Doc
Shifts the camera by the given horizontal and vertical amounts relative to the current location.
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
change_scene path [enable_automatic_transition] [run_events]
API-Doc
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
- 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
)
custom object node func_name [params...]
API-Doc
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 arguments to be passed to the function (array and object parameters are not supported).
Multiple parameters can be passed by simply passing them in as additional arguments separated by
spaces, e.g.
custom the_object the_node the_function arg1 arg2 arg3
dec_global name value
API-Doc
Subtract the given value from the specified global.
Parameters
- name: Name of the global to be changed
- value: Value to be subtracted (default: 1)
enable_terrain node_name
API-Doc
Enables the ESCTerrain
's NavigationPolygonInstance
specified by the given
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
- node_name: Name of the
NavigationPolygonInstance
node to activate
end_block_say
API-Doc
say
commands used subsequent to using the end_block_say
command will no longer
reuse the dialog box type used by the previous say
command(s) encountered.
Using end_block_say
more than once is safe and idempotent.
Example:
block say
say player "Picture's looking good."
say player "And so am I."
end_block_say
This example will reuse the same dialog box type since they are the same between both say
calls.
hide_menu menu_type
API-Doc
Hides either the main menu or the pause menu. Transitions from the menu using the default transition type (set in the Escoria project settings).
Parameters
- menu_type: Which menu to hide. Can be either
main
orpause
(default:main
)
inc_global name value
API-Doc
Adds the given value to the specified global.
Parameters
- name: Name of the global to be changed
- value: Value to be added (default: 1)
inventory_add item
API-Doc
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
- item: Global ID of the
ESCItem
to add to the inventory
inventory_remove item
API-Doc
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
- item: Global ID of the
ESCItem
to remove from the inventory
play_snd file [player] [start_position_seconds]
API-Doc
Plays the specified sound without blocking the currently running 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
)
print string
API-Doc
Prints a message to the Godot debug window. Use this for debugging game state.
Parameters
- string: The string to log
queue_event object event [channel] [block]
API-Doc
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
). 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
)
queue_resource path [front_of_queue]
API-Doc
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
)
rand_global name max_value
API-Doc
Sets the given global to a random integer between 0 and max_value
(inclusive). e.g. Setting max_value
to 2 could result in '0', '1' or '2'
being returned.
Parameters
- name: Name of the global to set
- max_value: Maximum possible integer value (inclusive) (default: 1)
repeat
API-Doc
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.
save_game slot_id savegame_description
API-Doc
Saves the game in the [slot_id] slot, and sets the [savegame_description] in the savegame name/title.
Example:
save_game 1 "description of game saved
say player text [type]
API-Doc
Displays the specified string as dialog spoken by the player. This command blocks further event execution until the dialog has finished being 'said' (either as displayed text or as audible speech from a file).
Global variables can be substituted into the text by wrapping the global name in braces. e.g. say player "I have {coin_count} coins remaining".
Parameters
- player : Global ID of the
ESCPlayer
orESCItem
object that is active. You can specify
current_player
in order to refer to the currently active player, e.g. in cases where multiple players are playable such as in games like Maniac Mansion or Day of the Tentacle.
- player : Global ID of the
text: Text to display.
type: Dialog type to use. One of
floating
oravatar
. (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.
For more details see: https://docs.escoria-framework.org/en/devel/getting_started/dialogs.html#translations
Playing an audio file while the text is being displayed is also supported by this mechanism. For more details see: https://docs.escoria-framework.org/en/devel/getting_started/dialogs.html#recorded_speech
Example: say player ROOM1_PICTURE:"Picture's looking good."
sched_event time object event
API-Doc
Schedules an event to run at a later time.
If another event is already running when the scheduled event is supposed 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
set_active object active
API-Doc
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
can betrue
orfalse
.
set_active_if_exists object active
API-Doc
*** FOR INTERNAL USE ONLY *
Changes the "active" state of the object in the current room if it currently exists in the object manager. If it doesn't, then, unlike set_active, we don't fail and we just carry on.
Inactive objects are invisible in the room.
Parameters
- object Global ID of the object
- active Whether
object
should be active.active
can betrue
orfalse
.
set_angle object target_degrees [wait]
API-Doc
Turns a movable ESCItem
or ESCPlayer
to face a given target direction.
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
- 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 of0
will complete the turn immediately (default:0
)
set_animations object animations
API-Doc
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
set_direction object direction_id [wait]
API-Doc
Turns a movable ESCItem
or ESCPlayer
to face a given target direction id
(between 0 and 3 for a 4-directional character, or between 0 and 7 for an
8-directional character).
4-directional : 0 : UP / NORTH 1 : RIGHT / EAST 2 : DOWN / SOUTH 3 : LEFT / WEST
8-directional : 0 : UP / NORTH 1 : UP-RIGHT / NORTH-EAST 2 : RIGHT / EAST 3 : DOWN-RIGHT / SOUTH-EAST 4 : DOWN / SOUTH 5 : DOWN-LEFT / SOUTH-WEST 6 : LEFT / WEST 7 : TOP-LEFT / NORTH-WEST
Parameters
- object: Global ID of the object to turn
- target_direction_id: id of the direction as defined in the player animations
- wait: Number of seconds to wait while playing each animation occurring
between the current direction of
object
and the target direction. A value of0
will complete the turn immediately (default:0
)
set_global name value [force=false]
API-Doc
Changes the value of a global.
Parameters
- name: Name of the global
- value: Value to set the global to (can be of type string, boolean, integer or float)
- force: if false, setting a global whose name is reserved will trigger an error. Defaults to false. Reserved globals are: ESC_LAST_SCENE, FORCE_LAST_SCENE_NULL, ANIMATION_RESOURCES, ESC_CURRENT_SCENE
set_globals pattern value
API-Doc
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)
set_gui_visible visible
API-Doc
Show or hide the GUI.
Parameters
- visible: Whether the GUI should be visible (
true
orfalse
)
set_interactive object interactive
API-Doc
Sets whether an object is interactive.
Parameters
- object: Global ID of the object to change
- interactive: Whether the object should be interactive
set_item_custom_data item custom_data
API-Doc
*** FOR INTERNAL USE ONLY *
Sets the "custom_data" of the item if it currently exists in the object manager.
Parameters
- item Global ID of the item
- custom_data Dictionary with custom data. If null empty dictionary will be assigned.
set_speed object speed
API-Doc
Sets the speed of a ESCPlayer
or movable ESCItem
.
Parameters
- object: Global ID of the
ESCPlayer
or movableESCItem
- speed: Speed value for
object
in pixels per second.
set_state object state [immediate]
API-Doc
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 animation is also played.
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
- 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
orfalse
.
show_menu menu_type
API-Doc
Shows either the main menu or the pause menu. Transitions to the menu using the default transition type (set in the Escoria project settings).
Parameters
- menu_type: Which menu to show. Can be either
main
orpause
(default:main
)
slide_block object target [speed]
API-Doc
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: 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.
slide object target [speed]
API-Doc
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: 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.
spawn identifier path [is_active] [position_target]
API-Doc
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 object's position is not specified)
stop
API-Doc
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.
stop_snd [audio_bus]
API-Doc
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
Parameters
- audio_bus: Bus to stop ("_sound", "_music", "_speech", or a custom audio bus you have created.)
teleport object target
API-Doc
Instantly moves an object to a new position.
Parameters
- object: Global ID of the object to move
- target: Global ID of the object to use as the destination coordinates
for
object
teleport_pos object x y
API-Doc
Instantly moves an object to the specified (absolute) coordinates.
Parameters
- object: Global ID of the object to move
- x: X-coordinate of destination position
- y: Y-coordinate of destination position
transition transition_name mode [delay]
API-Doc
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
- transition_name: Name of the transition shader from one of the transition directories
- mode: Set to
in
to transition into orout
to transition out of the room - delay: Delay in seconds before starting the transition (default:
1.0
)
turn_to object object_to_face [wait]
API-Doc
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.
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
- 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
)
wait seconds
API-Doc
Blocks execution of the current event.
Parameters
- seconds: Number of seconds to block
walk_block object target [walk_fast]
API-Doc
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
- object: Global ID of the object to move
- target: Global ID of the target object
- walk_fast: Whether to walk fast (
true
) or normal speed (false
). (default: false)
walk object target [walk_fast]
API-Doc
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
- object: Global ID of the object to move
- target: Global ID of the target object
- walk_fast: Whether to walk fast (
true
) or normal speed (false
) (default: false)
walk_to_pos_block object x y [walk_fast]
API-Doc
Moves the specified ESCPlayer
or movable ESCItem
to the absolute
coordinates provided while playing the object
's walking animation.
This command is blocking.
This command will use the normal walk speed by default.
Parameters
- object: Global ID of the object to move
- x: X-coordinate of target position
- y: Y-coordinate of target position
- walk_fast: Whether to walk fast (
true
) or normal speed (false
). (default: false)
walk_to_pos object x y [walk_fast]
API-Doc
Moves the specified ESCPlayer
or movable ESCItem
to the absolute
coordinates provided while playing the object
's walking animation.
This command is non-blocking.
This command will use the normal walk speed by default.
Parameters
- object: Global ID of the object to move
- x: X-coordinate of target position
- y: Y-coordinate of target position
- walk_fast: Whether to walk fast (
true
) or normal speed (false
). (default: false)
Dialogs are specified by writing ?
with optional parameters,
followed by a list of dialog options starting with -
. Use !
to
end the dialog.
The following parameters are available:
- avatar: The path to a scene displaying an avatar to be used in the UI.
Defaults to no avatar. To set only the parameters below, set this
parameter's value to
-
- timeout: Time allowed to select an option. Default value 0. After the
specified time has elapsed,
timeout_option
will be selected automatically. If the value is 0, there is no timeout (i.e. no time limit to select an option). - timeout_option: Index of option selected when timeout is reached. Default value of 0. Index begins at 1.
Options support translation keys by prepending and separating them with
a :
from the rest of the text.
Example:
# character's "talk" event :talk # After 5 seconds default to the second option ? avatar 5 2 - MAP:"I'd like to buy a map." [!player_has_map] say player "I'd like to buy a map" say map_vendor "Do you know the secret code?" ? - UNCLE_SVEN:"Uncle Sven sends regards." say player "Uncle Sven sends regards." > [player_has_money] say map_vendor "Here you go." say player "Thanks!" inventory_add map set_global player_has_map true stop > [!player_has_money] say map_vendor "You can't afford it" say player "I'll be back" stop - "Nevermind" say player "Nevermind" stop ! - "Nevermind" say player "Nevermind" stop !