oier/gymkhana-actions
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Documentation and Optimization Part 1 (#2)

Browse Source 
Authored-by: Dennis Ploeger <develop@dieploegers.de>
This commit is contained in:
Dennis Ploeger
2021-06-16 10:12:51 +02:00
committed by GitHub
parent a22805d0e6
commit 4e09f522ff
109 changed files with 3556 additions and 2043 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docs/api/Movable.md Normal file
View File

@@ -0,0 +1,205 @@
<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
# Movable
**Extends:** [Node](../Node)
## Description
Node that performs the moving (walk, teleport, terrain scaling...) actions on
its parent node.
## Property Descriptions
### walk\_path
```gdscript
var walk_path: Array
```
Character path through the scene as calculated by the Pathfinder
### path\_ofs
```gdscript
var path_ofs: int
```
Current active walk path entry
### walk\_destination
```gdscript
var walk_destination: Vector2
```
The destination where the character should be moving to
### walk\_context
```gdscript
var walk_context: Dictionary
```
A dictionary with context information about the walk command
fast => Wether to walk fast or slow
target => Walk target
### moved
```gdscript
var moved: bool
```
Wether the character was moved at all
### last\_deg
```gdscript
var last_deg: int
```
Angle degrees to the last position (TODO is that correct?)
### last\_dir
```gdscript
var last_dir: int
```
Direction of the last position (TODO is that correct?)
### last\_scale
```gdscript
var last_scale: Vector2
```
Scale of the last position (TODO is that correct?)
### pose\_scale
```gdscript
var pose_scale: int
```
TODO Isn't this actually the flip state of the current animation?
### parent
```gdscript
var parent
```
Shortcut variable that references the node's parent
### bypass\_missing\_animation
```gdscript
var bypass_missing_animation
```
 If character misses an animation, bypass it and proceed.
## Method Descriptions
### teleport
```gdscript
func teleport(target, angle: Object = null) -> void
```
Teleports this item to the target position.
TODO angle is only used for logging and has no further use, so it probably
can be removed
#### Parameters
- target: Vector2, Position2d or ESCItem
### walk\_to
```gdscript
func walk_to(pos: Vector2, p_walk_context = null) -> void
```
Walk to a given position
#### Parameters
- pos: Position to walk to
- p_walk_context: Walk context to use
### walk
```gdscript
func walk(target_pos, p_speed, context = null) -> void
```
FIXME this function doesn't seem to be used anywhere
### walk\_stop
```gdscript
func walk_stop(pos: Vector2) -> var
```
We have finished walking. Set the idle pose and complete
#### Parameters
- pos: Final target position
### update\_terrain
```gdscript
func update_terrain(on_event_finished_name = null) -> void
```
Update the sprite scale and lighting
#### Parameters
- on_event_finished_name: Used if this function is called from an ESC event
### is\_angle\_in\_interval
```gdscript
func is_angle_in_interval(angle: float, interval: Array) -> bool
```
Returns true if given angle is inside the interval given by a starting_angle
and the size.
TODO Refactor to make this stuff understandable :D
#### Parameters
- angle: Angle to test
- interval : Array of size 2, containing the starting angle, and the size of
interval
eg: [90, 40] corresponds to angle between 90° and 130°
### set\_angle
```gdscript
func set_angle(deg: int, immediate = true) -> void
```
Sets character's angle and plays according animation.
TODO: depending on current angle and current angle, the character may
directly turn around with no "progression". We may enhance this by
calculating successive directions to turn the character to, so that he
doesn't switch to opposite direction too fast.
For example, if character looks WEST and set_angle(EAST) is called, we may
want the character to first turn SOUTHWEST, then SOUTH, then SOUTHEAST and
finally EAST, all more or less fast.
Whatever the implementation, this should be activated using "parameter
"immediate" set to false.
#### Parameters
- deg int angle to set the character
- immediate bool (currently unused, see TODO below)
If true, direction is switched immediately. Else, successive animations are
used so that the character turns to target angle.

275
docs/api/esc_compiler.gd.md Normal file
View File

@@ -0,0 +1,275 @@
<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
# esc\_compiler.gd
**Extends:** [Node](../Node)
## Description
ESC compiler
The workflow is like this:
Lines beginning with ":" such as :push, :say are EVENTS.
Lines in between are usually the ESC API functions calls. They are called COMMANDS.
Steps
* compile_script(path/to/esc) : called once
* compile(path/to/esc, errors) : called once
* read_events() : called once\
create an ESCState, initialized with 1st line\
for each line in ESCState that corresponds to an event (:event), create a new level
* add_level(state, level, errors)\
for each state.line that belongs to same group (same indentation), create a command
* read_cmd(state, level, errors)\
get the token in state.line : this is the actual command (say, teleport, etc.)\
get the parameters next to the token\
create an ESCCommand, check it and push it into level array\
* create an ESCEvent with the level created\
* add it to the returned Dictionary of events
In the end, the ESCState has read all lines in the file and is deleted
Returned value is a Dictionary { event name : ESCEvent}
And ESCEvent.level is an array of ESCCommand
## Constants Descriptions
### COMMANDS
```gdscript
const COMMANDS: Dictionary = {"!":{"alias":"end_dialog","min_args":0},"%":{"alias":"label","min_args":1},">":{"alias":"branch"},"?":{"alias":"dialog"},"accept_input":{"min_args":1,"types":[4]},"anim":{"min_args":2,"types":[4,4,1,1,1]},"autosave":{"min_args":0},"camera_push":{"min_args":1,"types":[4]},"camera_set_drag_margin_enabled":{"min_args":2,"types":[1,1]},"camera_set_limits":{"min_args":1,"types":[2]},"camera_set_pos":{"min_args":3,"types":[3,2,2]},"camera_set_target":{"min_args":1,"types":[3]},"camera_set_zoom":{"min_args":1,"types":[3]},"camera_set_zoom_height":{"min_args":1,"types":[2]},"camera_shift":{"min_args":2,"types":[2,2]},"change_scene":{"min_args":1,"types":[4,1]},"custom":{"min_args":2,"types":[4,4]},"cut_scene":{"min_args":2,"types":[4,4,1,1,1]},"debug":{"min_args":1},"dec_global":{"min_args":2,"types":[4,2]},"enable_terrain":{"min_args":1,"types":[4]},"game_over":{"min_args":1,"types":[1]},"inc_global":{"min_args":2,"types":[4,2]},"inventory_add":{"min_args":1},"inventory_display":{"min_args":1,"types":[1]},"inventory_remove":{"min_args":1},"jump":{"min_args":1},"label":{"min_args":1},"queue_animation":{"min_args":2,"types":[4,4,1]},"queue_resource":{"min_args":1,"types":[4,1]},"repeat":true,"say":{"min_args":2},"sched_event":{"min_args":3,"types":[3,4,4]},"set_active":{"min_args":2,"types":[4,1]},"set_angle":{"min_args":2,"types":[4,2]},"set_global":{"min_args":2,"types":[4,4]},"set_globals":{"min_args":2,"types":[4,1]},"set_hud_visible":{"min_args":1,"types":[1]},"set_interactive":{"min_args":2,"types":[4,1]},"set_sound_state":{"min_args":2,"types":[4,4,1]},"set_speed":{"min_args":2,"types":[4,2]},"set_state":{"min_args":2,"types":[4,4,1]},"slide":{"min_args":2},"slide_block":{"min_args":2},"spawn":{"min_args":1},"stop":true,"superpose_scene":{"min_args":1,"types":[4,1]},"teleport":{"min_args":2,"types":[4,4,2]},"teleport_pos":{"min_args":3},"turn_to":{"min_args":2},"wait":true,"walk":{"min_args":2},"walk_block":{"min_args":2},"walk_to_pos":{"min_args":3},"walk_to_pos_block":{"min_args":3}}
```
A list of valid ESC commands
### DEBUG\_COMMANDS
```gdscript
const DEBUG_COMMANDS: Dictionary = {"get_active":{"min_args":1,"types":[4]},"get_global":{"min_args":1,"types":[4]},"get_interactive":{"min_args":1,"types":[4]},"get_state":{"min_args":1,"types":[4]}}
```
Commands that can be called only by the ESC debug prompt
## Method Descriptions
### compile\_str
```gdscript
func compile_str(p_str: String, errors: Array)
```
Compile a string into a dictionary of ESC events
#### Parameters
- p_str: String to compile
- errors: List of errors occured during parsing
**Returns** A dictionary of ESCEvents
### load\_esc\_file
```gdscript
func load_esc_file(esc_file_path: String) -> Dictionary
```
Loads an ESC or special GDScript file and compiles it to a dictionary of
events.
#### Parameters
- esc_file_path: The path to the ESC file to load
**Returns** A dictionary of ESC events
### compile\_script
```gdscript
func compile_script(p_path: String) -> Dictionary
```
Compiles an ESC file into a dictionary of events.
Alternatively, a GDScript file can be specified as well. In that case,
the compiler expects a function get_events in that script that
returns a dictionary of events.
#### Parameters
- p_path: Path to the ESC/GDScript-file
**Returns** A dictionary of ESC events
### compile
```gdscript
func compile(p_fname: String, errors: Array) -> Dictionary
```
Compile an ESC file into a list of events
#### Parameters
- p_fname: Path to the ESC file
- errors: A list of errors that wil be filled by the compiler
**Returns** A dictionary of ESC events
### read\_events
```gdscript
func read_events(f, ret: Dictionary, errors: Array) -> void
```
Parse a file or a special dictionary into a dictionary of ESC events
The dictionary is currently used as a workaround to parse ESC from text
(see read_line for specifics)
#### Parameters
- f: File or Dictionary to read
- ret: The parsed dictionary
- errors: A list of errors that have been found during parsing
### add\_level
```gdscript
func add_level(state: ESCState, level: Array, errors: Array) -> void
```
Add a new level of indent to the current event parsing
#### Parameters
- state: The state we're working on
- level: The existing levels
- errors: A list of errors during parsing
### read\_cmd
```gdscript
func read_cmd(state: ESCState, level: Array, errors: Array) -> void
```
Interpret a line in an esc event level as a command and add it to the
level commands
#### Parameters
- state: The state we're working on
- level: The list of level commands
- errors: A list of errors occured during parsing
### add\_dialog
```gdscript
func add_dialog(state: ESCState, level: Array, errors: Array) -> void
```
Add a dialog into the current level
#### Parameters
- state: State we're working on
- level: Current list of level commands
- errors: List of errors occured during parsing
### read\_dialog\_option
```gdscript
func read_dialog_option(state: ESCState, level: Array, errors: Array) -> void
```
### check\_normal\_command
```gdscript
func check_normal_command(cmd: ESCCommand, state: ESCState, errors: Array) -> bool
```
### check\_debug\_command
```gdscript
func check_debug_command(cmd: ESCCommand, state: ESCState, errors: Array) -> bool
```
### check\_command
```gdscript
func check_command(commands_list: Dictionary, cmd: ESCCommand, state: ESCState, errors: Array) -> bool
```
### read\_line
```gdscript
func read_line(state: ESCState) -> void
```
Advance to the next line in the state
#### Parameters
- state: State we're working on
### is\_comment
```gdscript
func is_comment(line: String) -> bool
```
 Check wether line is a comment (starting with #)
#### Parameters
- line: Current line as string
**Returns** Wether the line is a comment or not
### get\_indent
```gdscript
func get_indent(line: String) -> int
```
Returns the position of the first non-blank character in given line string
#### Parameters
- line: Line to check
**Returns** Indent of the checked line
### is\_event
```gdscript
func is_event(line: String)
```
Check wether the given line is a event (begins with ":")
#### Parameters
- line: Line to check
**Returns**
### is\_flags
```gdscript
func is_flags(tk: String) -> bool
```
Checks wetehr the given token is a flag (ie. "[.+]")
#### Parameters
- tk: Token to check
**Returns** Wether the token is a flag or not
### get\_token
```gdscript
func get_token(line: String, p_from: int, line_count: int, errors: Array) -> int
```
### parse\_flags
```gdscript
func parse_flags(p_flags: String, flags_list: Array, ifs: Dictionary)
```
Parses a flags string (usually defined by '[.*]') and fills the flags_list array
and ifs variable (Dictionary containing all ifs conditions)

164
docs/api/escoria.gd.md Normal file
View File

@@ -0,0 +1,164 @@
<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
# escoria.gd
**Extends:** [Node](../Node)
## Description
The escorie main script
## Enumerations
### GAME\_STATE
```gdscript
const GAME_STATE: Dictionary = {"DEFAULT":0,"DIALOG":1,"WAIT":2}
```
An enum of game states
* DEFAULT - Default mode
* DIALOG - Game is running a dialog
* WAIT - Game is currently waiting for a specified time
## Property Descriptions
### main\_menu\_instance
```gdscript
var main_menu_instance
```
The instance of the used main menu scene
### dialog\_player
```gdscript
var dialog_player
```
Dialog player instantiator. This instance is called directly for dialogs.
### inventory
```gdscript
var inventory
```
The inventory scene used
### room\_terrain
```gdscript
var room_terrain
```
The terrain of the current main room
### esc\_compiler
```gdscript
var esc_compiler
```
The ESC compiler instance
### logger
```gdscript
var logger
```
The logger instance
### main
```gdscript
var main
```
The main scene
### esc\_runner
```gdscript
var esc_runner
```
The ESC main loop
### esc\_level\_runner
```gdscript
var esc_level_runner
```
The ESC interpreter
### inputs\_manager
```gdscript
var inputs_manager
```
The escoria inputs manager
### utils
```gdscript
var utils
```
Several utilities
### current\_state
```gdscript
var current_state
```
The current state of the game
### game\_size
```gdscript
var game_size
```
The game resolution
## Method Descriptions
### new\_game
```gdscript
func new_game()
```
Called by Main menu "start new game"
### register\_object
```gdscript
func register_object(object: Object)
```
Register an object to the matching manager. (A dialog player as the
main dialog player, an item in the ESC runner, etc.)
#### Parameters
- object: The object to register
### do
```gdscript
func do(action: String, params: Array) -> void
```
Run a generic action
#### Parameters
- action: type of the action to run
- params: Parameters for the action

144
docs/api/escoria_types.gd.md Normal file
View File

@@ -0,0 +1,144 @@
<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
# escoria\_types.gd
**Extends:** [Node](../Node)
## Description
Escoria basic types
## Enumerations
### EVENT\_LEVEL\_STATE
```gdscript
const EVENT_LEVEL_STATE: Dictionary = {"BREAK":2,"CALL":4,"JUMP":5,"REPEAT":3,"RETURN":0,"YIELD":1}
```
ESC script states
RETURN - The ESC script has been completed successfully
YIELD - ESC is waiting for Godot to finish something (e.g. Sprite animation)
BREAK - ESC has completed the current command block. Jump back
REPEAT - ESC is repeating a command block
CALL - Call another ESC command block
JUMP - Jump to another ESC label
## Constants Descriptions
### OBJ\_DEFAULT\_STATE
```gdscript
const OBJ_DEFAULT_STATE: String = "default"
```
The default state of an object
## Sub\-classes
### ESCState
#### Property Descriptions
### file
```gdscript
var file
```
File or Dictionary
### line
```gdscript
var line
```
String, can be null
### indent
```gdscript
var indent: int
```
### line\_count
```gdscript
var line_count: int
```
#### Method Descriptions
### \_init
```gdscript
func _init(p_file, p_line, p_indent, p_line_count)
```
### ESCEvent
#### Property Descriptions
### ev\_name
```gdscript
var ev_name: String
```
### ev\_level
```gdscript
var ev_level: Array
```
### ev\_flags
```gdscript
var ev_flags: Array
```
#### Method Descriptions
### \_init
```gdscript
func _init(p_name, p_level, p_flags)
```
### ESCCommand
#### Property Descriptions
### name
```gdscript
var name: String
```
### params
```gdscript
var params: Array
```
### conditions
```gdscript
var conditions: Dictionary
```
### flags
```gdscript
var flags: Array
```
#### Method Descriptions
### \_init
```gdscript
func _init(p_name)
```

31
docs/architecture.md Normal file
View File

@@ -0,0 +1,31 @@
# Escoria architecture
## The plugin script, autoload and classes
According to the [concept of Godot plugins](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/making_plugins.html), `Escoria`initializes itself in the plugin script `addons/escoria-core/editor/plugin_escoria.gd`. This script is mostly used to initialize the [Escoria configuration items](configuration.md) and initialize (and later remove) the autoloads.
Escoria is based on an autoload scene available as [`escoria`](api/escoria.gd.md), that binds together all required objects and interfaces in a central place. An additional autoload, [`esctypes`](api/escoria_types.gd.md) defines basic escoria classes.
In addition to this, various classes are defined in the respective class files and build up the various resources used in Escoria.
* [Movable](api/Movable.md): A class that can be added to another node to handle movements on that node.
## Nodes of the Escoria autoload scene
The Escoria autoload scene holds various nodes that take vital parts of the engine.
### Inputs Manager
The central component in Escoria to receive, handle and deliver input events.
### ESC Compiler
The [ESC compiler](api/esc_compiler.gd.md) compiles files in the [ESC language](../esc.md) into a list of events that can be run by the ESC runner
### Main
`escoria.main` is the main scene manager used in Escoria that allows for switching scenes with transitions
## The Godot main scene of Escoria
The scene, that Godot loads when starting a game (the [*main scene*](https://docs.godotengine.org/en/stable/getting_started/step_by_step/exporting.html#setting-a-main-scene)) is set to `addons/escoria-core/game/main_scene.tscn` and basically instantiates the configured main menu scene and starts it.

27
docs/configuration.md Normal file
View File

@@ -0,0 +1,27 @@
# Game configuration
Aside from the common [Godot project settings](https://docs.godotengine.org/en/stable/classes/class_projectsettings.html), Escoria includes some special settings to configuration the Escoria components. These settings can be found in the "Escoria"-section in the project settings:
| Section | Setting | Description |
| -------- | ----------------------- | ------------------------------------------------------------ |
| Main | Game Start Script | ESC-script that will be executed when the game starts |
| | Force Quit | Allow quitting the game using the operating system's quit commands (Alt-F4 on Windows, Cmd-Q on macOS, etc.) |
| | Text Lang | Default language of texts displayed in the game |
| | Voice Lang | Default language of voices |
| Debug | Terminate On Warnings | If an Escoria warning is received, quit the game |
| | Terminate On Errors | If an Escoria error is received, quit the game |
| | Development Lang | Basic language the game is developed in. Useful for translation management |
| | Log Level | Level of log files produced. Even if this is set to DEBUG, debugging logs will not be available in production builds |
| Ui | Tooltip Follows Mouse | The tooltips for items in the scene follows the mouse cursor (used e.g. for mouse cursor icons UI) |
| | Dialogs Folder | Folder containing UI scenes related to dialogs |
| | Default Dialog Scene | The scene used for dialogs |
| | Main Menu Scene | The scene used for menus |
| | Pause Menu Scene | The scene used when the game is paused |
| | Game Scene | The game UI used |
| | Items Autoregister Path | Path that holds ESCItems that aren't registered in a scene before, but are added to the inventory for example |
| Sound | Music Volume | The volume used for music |
| | Sound Volume | The volume used for sound |
| | Speech Volume | The volume used for voices |
| | Master Volume | The master volume for all channels |
| Platform | Skip Cache | Wether to skip caching scenes. Some platforms might not have the enough amount of memory required for this (e.g. mobile platforms) and should have this setting set to true for their respective targets |

402
docs/esc.md Normal file
View File

@@ -0,0 +1,402 @@
# ESC language documentation
## Objects
### Global IDs
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.
### States
Each object can have a "state". The state is stored in the global state of the game, and the savegame, and it's set on the object when the scene is instanced. States can also be animations with the same name in the object's scene, in that case the animation is run when the state is set.
### Active objects
Objects can be active or not active. Non-active objects are hidden and non 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."
```
Caveat: This works only when `set_active` has been called. Therefore if "elaine" is not set `active` in the editor but `set_active elaine true` is
called later, everything works as expected. If you have an item that can be picked up, even if it's `active` in the editor, but its state *may* toggle,
you must use this pattern:
```
:setup
set_active broom true [!i/inv_broom]
```
Now it has been explicitly set and it will work. The underlying technical rationale is way beyond the scope of this reference; just trust us
that it's the best way to go.
### Interactive objects
If you have something that only blocks the terrain, something you can move behind, you probably don't want to hassle with interaction areas
and tooltip texts. In this case, just set `is_interactive` to `false` and the item will not be checked for areas and its mouse events will
not be connected.
## Global flags
Global flags define the state of the game, and can have a value of true, false or an integer. All commands or groups can be conditioned to the value of a global flag.
### Inventory
The inventory is handled as a special case of global flags. All flags with a name starting with "i/" are considered an inventory object, with the object's global id following. Example:
```
# adds the object "key" to the inventory
set_global i/key true
```
```
# removes the object "key" to the inventory
set_global i/key false
```
## Game global state
The following values are saved in the global game state and savegames:
* Global flags
* Object's "state" values
* Object's "active" values
* Object's potisions if moved
## Events
When a scene is loaded, it may have events. We will not cover `:load` as it is used only internally for save games, nor will we cover `:start` here.
To initialize a room properly, you may want to use `:setup` like this:
```
:setup
teleport player door1 [eq last_exit door1]
teleport player door2 [eq last_exit door2]
```
It covers the fact that your `player` can be set anywhere in the room and be visible for just a moment before the `teleport` happens.
It's not mandatory, nor mutually exclusive with `:setup` to have a `:ready` event.
```
:ready
say player player_wants_out:"I want out! To live my life and to be free!" [want_out]
```
When the player interacts with an object in the game, the object receives an even. Each event executes a series of commands.
Events start with the character ":" in the Events file. Example:
```
:use
```
Especially useful for fallbacks, you can give flags to events:
```
:use | TK
say player player_does_not_wanna:"I don't wanna."
```
These flags are implemented:
* `TK` stands for "telekinetic". It means the player won't walk over to the item to say the line.
* `NO_TT` stands for "No tooltip". It hides the tooltip for the duration of the event. Probably not very useful, because events having multiple `say` commands in them are automatically hidden.
* `NO_HUD` stands for "No HUD". It hides the HUD for the duration of the event. Useful when you want something to look like a cut scene but not disable input for skipping dialog.
* `NO_SAVE` disables saving. Use this in cut scenes and anywhere a badly-timed autosave would leave your game in a messed-up state.
* `CUT_BLACK` applies only to `:setup`. It makes the screen go black during the setup phase. You will probably see a quick black flash, so use it only if you prefer it over the standard cut.
* `LEAVE_BLACK` applies only to `:setup`. In case your `:ready` starts with `cut_scene telon fade_in`, you must apply this flag or you will see a flash of your new scene before going black again for the `fade_in`.
## Commands
Commands consist of one word followed by parameters. Parameters can be one word, or strings in quotes. A string can also be preceeded by an ID for localization and the ":" character. Example:
```
# one parameter "player", another parameter "hello world", with id "dialog_hello"
say player dialog_hello:"hello world"
```
### Conditions
In order to run a command conditionally dependin on the value of a flag, use [] with a list of conditions. All conditions in the list must be true. The character "!" before a flag can be used to negate it.
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's 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]
```
### Groups
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
animation player pick_up
# end of group
```
### Blocking
Some commands will block execution of the event until they finish, others won't. See the command's reference for details on which commands block.
### List of commands
#### `debug string [string2 ...]`
Takes 1 or more strings, prints them to the console.
#### `set_global name value`
Changes the value of the global "name" with the value. Value can be "true", "false" or an integer.
#### `dec_global name value`
Subtracts the value from global with given "name". Value and global must both be integers.
#### `inc_global name value`
Adds the value to global with given "name". Value and global must both be integers.
#### `set_globals pattern value`
Changes the value of multiple globals using a wildcard pattern. Example:
```
# clears the inventory
set_globals i/#### false
```
#### `accept_input [ALL|NONE|SKIP]`
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.
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`.
#### `set_state object state` (Currently not available)
Changes the state of an object, and executes the state animation if present. The command can be used to change the appearance of an item or a player character.
When used on a player object, the command is used to dress the player in a costume identified by the state parameter. An `AnimationPlayer` with the given parameter should be a child of the player node, although one named "animation" is always the fallback when trying set a missing costume.
Items can also change state by playing animations from an `AnimationPlayer` named "animation". The `AnimationPlayer` is typically used to change the texture of a `Sprite` node, but it's also possible to add additional tracks for changing the tooltip and other properties of the item scene. By using keyframes and looping, any given state can also use multiple textures to bring more life to the item.
#### `set_hud_visible visible` (Currently not available)
If you have a cut#### scene#### 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.
#### `say object text [type] [avatar]`
Runs the specified string as a dialog said by the object. Blocks execution until the dialog finishes playing. Optional parameters:
* "type" determines the type of dialog UI to use. Default value is "default"
* "avatar" determines the avatar to use for the dialog. Default value is "default"
#### `anim object name [reverse] [flip_x] [flip_y]`
Executes the animation specificed with the "name" parameter on the object, without blocking. The next command in the event will be executed immediately after. Optional parameters:
* reverse plays the animation in reverse when true
* flip_x flips the x axis of the object's sprites when true (object's root node needs to be Node2D)
* flip_y flips the y axis of the object's sprites when true (object's root node needs to be Node2D)
#### `cut_scene object name [reverse] [flip_x] [flip_y]`
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:
* reverse plays the animation in reverse when true
* flip_x flips the x axis of the object's sprites when true (object's root node needs to be Node2D)
* flip_y flips the y axis of the object's sprites when true (object's root node needs to be Node2D)
#### `play_snd object file [loop]` (Currently not available)
Plays the sound specificed with the "file" parameter on the object, without blocking. You can play background sounds, eg. during scene changes, with `play_snd bg_snd res://...`
#### `set_active object value`
Changes the "active" state of the object, value can be true or false. Inactive objects are hidden in the scene.
#### `set_interactive object value`
Sets whether or not an action menu should be used, and a tooltip shown, on object. It must use the `item.gd` script. Value can be true or false. Useful for "soft#### disabling" objects without removing them by `set_active`.
#### `wait seconds`
Blocks execution of the current script for a number of seconds specified by the "seconds" parameter.
#### `change_scene path run_events`
Loads a new scene, specified by "path". 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.
#### `set_speed object speed`
Sets how fast object moves. It must use the `interactive.gd` script or something extended from it. Value is an integer.
#### `teleport object1 object2 [angle]`
Sets the position of object1 to the position of object2. By default object2's `interact_angle` is used to turn `object1`, but `angle` will override this.
Useful for doors and such with an `interact_angle` you don't always want to adhere to when re#### entering a room.
#### `slide object1 object2 [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.
#### `slide_block object1 object2 [speed]`
Moves object1 towards the position of object2, at the speed determined by object1's "speed" propert, unless overriddeny. This command is blocking. It does not respect the room's navigation polygons, so you can move items where the player can't walk.
#### `walk object1 object2 [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.
#### `walk_block object1 object2 [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.
#### `turn_to object degrees`
Turns `object` to a `degrees` angle with a `directions` animation.
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`.
`object` must be player or interactive.
`degrees` must be between [0, 360] or an error is reported.
#### `set_angle object degrees`
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`.
`object` must be player or interactive.
`degrees` must be between [0, 360] or an error is reported.
#### `spawn path [object2]`
Instances a scene determined by "path", and places in the position of object2 (object2 is optional)
#### `stop`
Stops the event's execution.
#### `repeat`
Restarts the execution of the current scope at the start. A scope can be a group or an event.
#### `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.
`event` can consist of multiple words like in `sched_event 0 tow_hook use inv_rope`
#### `custom obj func_name [params]`
If `obj` has a `(Node2D) custom` node, `func_name` will be searched for in its script and called with `params`. See device/contrib/custom/spine.gd for an example.
#### `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.
#### `camera_set_target speed object [object2 object3 ...]`
Configures the camera to follow 1 or more objects, using "speed" as speed limit. This is the default behavior (default follow object is "player"). If there's more than 1 object, the camera follows the average position of all the objects specified.
#### `camera_set_zoom magnitude [time]`yx
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.
#### `camera_set_zoom_height pixels [time]`
Similar to the command above, but uses pixel height instead of magnitude to zoom.
#### `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.
#### `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`.
#### `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).
#### `queue_animation object animation`
Similar to queue_resource, queues the resources necessary to have an animation loaded on an item. The resource paths are taken from the item placeholders.
#### `game_over continue_enabled show_credits`
Ends the game. Use the "continue_enabled" parameter to enable or disable the continue button in the main menu afterwards. The "show_credits" parameter loads the `ui/end_credits` scene if true. You can configure it to your regular credits scene if you want.
## Dialogs
To start a dialog, use the "?" character, with some parameters, followed by a list of dialog options. This hides the HUD. Each option starts with the "-" character, followed by a parameter with the text to display in the dialog interface. Inside the option, a group of commands is specified using indentation. Use "!" to signify the dialog is over and the HUD may be restored. The HUD will not be restored if the running event is flagged NO_HUD. Either way the Escoria virtual machine will know if the game is in a dialog context.
Example:
```
# character's "talk" event
:talk
? type avatar timeout timeout_option
- "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 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
repeat
```
All parameters are options:
* type: (default value "default") the type of dialog menu to use. All types are in the "dd_player" scene.
* avatar: (default value "default") the avatar to use in the dialog ui.
* timeout: (default value 0) timeout to select an option. After the time has passed, the "timeout_option" will be selected automatically. If the value is 0, there's no timeout.
* timeout_option: (default value 0) option selected when timeout is reached.