Fix command docs, automate API doc generation (#327)

Co-authored-by: Dennis Ploeger <develop@dieploegers.de>
Co-authored-by: dploeger <dploeger@users.noreply.github.com>

.github/workflows/apidoc.yml

@@ -0,0 +1,35 @@
+name: "Update API docs"
+
+on:
+    - push
+
+concurrency: api-${{ github.ref }}
+
+jobs:
+    update:
+        if: "${{ github.event.head_commit.message != 'docs: Automatic update of API docs' }}"
+        name: Update
+        runs-on: ubuntu-latest
+        steps:
+            - name: Checkout
+              uses: actions/checkout@v2
+            - name: Remove existing docs
+              run: |
+                rm -rf docs/api
+            - name: "Update docs"
+              uses: docker://gdquest/gdscript-docs-maker:1
+              with:
+                entrypoint: "bash"
+                args: "-c \"cd /app && ./generate_reference /github/workspace -o /github/workspace/docs/api -d addons/escoria-core\""
+            - name: "Update ESC reference"
+              run: |
+                apt update && apt install -y python3
+                python3 extractesc.py
+            - name: "Commit"
+              uses: EndBug/add-and-commit@v7.2.1
+              with:
+                add: "docs"
+                message: 'docs: Automatic update of API docs'
+                push: true
+
+               

README.md

@@ -97,16 +97,15 @@ Requirements:
 
 * git
 * Current Godot version
-* Current master of [GDScript docs maker](https://github.com/GDQuest/gdscript-docs-maker)
+* Docker (for updating the API docs)
-* Python (>=3) if you changed the ESC commands
+* Python (>=3) (for updating the ESC reference)
 
-During development, run the following to update the class list:
+After pushing something to the repository, the API docs will be updated. If you want to update them during
+development, run the following from the game directory:
 
 ```
-cd gdscripts-docs-maker
+rm -rf docs/api
-rm -rf export &>/dev/null
+docker run --rm -v $(pwd):/game -v $(pwd)/docs/api:/export gdquest/gdscript-docs-maker:1 /game -o /export -d addons/escoria-core
-./generate_reference <path to escoria> -d "addons/escoria"
-cp export/* <path to escoria>/docs/api
 ```
 
 If you changed ESC commands, update the command reference by running 

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

@@ -1,4 +1,4 @@
-# `camera_set_zoom_height pixels [time]
+# `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 

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

@@ -1,4 +1,4 @@
-# `teleport object1 object2
+# `teleport object1 object2`
 #
 # Sets the position of object1 to the position of object2.
 # FIXME re-add the angle parameter here

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

@@ -1,4 +1,4 @@
-# `teleport_pos object1 x y
+# `teleport_pos object1 x y`
 #
 # Sets the position of object1 to the position (x,y).
 # FIXME re-add the angle parameter here

docs/api/CameraSetLimitsCommand.md

@@ -10,7 +10,7 @@
 
 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
+- camlimits_id: int: id of the camera limits to apply (defined in ESCRoom's
   camera_limits array)
 
 @ESC

docs/api/CameraSetZoomHeightCommand.md

@@ -6,7 +6,7 @@
 
 ## Description
 
-`camera_set_zoom_height pixels [time]
+`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

docs/api/ESCGlobalsManager.md

@@ -92,6 +92,17 @@ for the pattern format
 - pattern: The wildcard pattern to match
 - value: The new value
 
+### save\_game
+
+```gdscript
+func save_game(p_savegame: ESCSaveGame) -> void
+```
+
+Save the state of globals in the savegame.
+
+#### Parameters
+- p_savegame: ESCSaveGame resource that holds all data of the save
+
 ## Signals
 
 - signal global_changed(global, old_value, new_value): Emitted when a global is changed

docs/api/ESCItem.md

@@ -289,7 +289,19 @@ Use the movable node to teleport this item to the target item
 
 #### Parameters
 
-- target: Target item to teleport to
+- target: Target node to teleport to
+
+### teleport\_to
+
+```gdscript
+func teleport_to(target: Vector2) -> void
+```
+
+Use the movable node to teleport this item to the target position
+
+#### Parameters
+
+- target: Vector2 position to teleport to
 
 ### walk\_to
 

docs/api/ESCLocation.md

@@ -0,0 +1,53 @@
+<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
+
+# ESCLocation
+
+**Extends:** [Position2D](../Position2D)
+
+## Description
+
+ A simple node extending Position2D with a global ID so that it can be
+referenced in ESC Scripts.
+
+## Property Descriptions
+
+### global\_id
+
+```gdscript
+export var global_id = ""
+```
+
+The global ID of this item
+
+### player\_orients\_on\_arrival
+
+```gdscript
+export var player_orients_on_arrival = true
+```
+
+If true, player orients towards 'interaction_direction' as
+player character arrives.
+
+### interaction\_direction
+
+```gdscript
+export var interaction_direction = 0
+```
+
+Let the player turn to this direction when the player arrives
+at the item
+
+## Method Descriptions
+
+### is\_class
+
+```gdscript
+func is_class(p_classname: String) -> bool
+```
+
+Used by "is" keyword to check whether a node's class_name
+is the same as p_classname.
+
+## Parameters
+
+p_classname: String class to compare against

docs/api/ESCLogger.md

@@ -13,7 +13,7 @@ Logging framework for Escoria
 ### LOG\_DEBUG
 
 ```gdscript
-const LOG_ERROR: int = 0
+const LOG_WARNING: int = 1
 ```
 
 Valid log levels
@@ -21,7 +21,7 @@ Valid log levels
 ### LOG\_ERROR
 
 ```gdscript
-const LOG_ERROR: int = 0
+const LOG_WARNING: int = 1
 ```
 
 Valid log levels
@@ -29,7 +29,7 @@ Valid log levels
 ### LOG\_INFO
 
 ```gdscript
-const LOG_ERROR: int = 0
+const LOG_WARNING: int = 1
 ```
 
 Valid log levels
@@ -37,7 +37,7 @@ Valid log levels
 ### LOG\_WARNING
 
 ```gdscript
-const LOG_ERROR: int = 0
+const LOG_WARNING: int = 1
 ```
 
 Valid log levels

docs/api/ESCMovable.md

@@ -125,7 +125,7 @@ Currenly running task
 ### teleport
 
 ```gdscript
-func teleport(target, angle: Object = null) -> void
+func teleport(target: Node, angle: Object = null) -> void
 ```
 
 Teleports this item to the target position.
@@ -134,7 +134,21 @@ can be removed
 
 #### Parameters
 
-- target: Vector2, Position2d or ESCItem
+- target: Position2d or ESCItem to teleport to
+
+### teleport\_to
+
+```gdscript
+func teleport_to(target: Vector2, 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 target position to teleport to
 
 ### walk\_to
 
@@ -194,7 +208,7 @@ 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: Array of size 2, containing the starting angle, and the size of
   interval
   eg: [90, 40] corresponds to angle between 90° and 130°
 

docs/api/ESCObject.md

@@ -79,3 +79,14 @@ Set the state and start a possible animation
 
 - p_state: State to set
 - immediate: If true, skip directly to the end
+
+### get\_save\_data
+
+```gdscript
+func get_save_data() -> Dictionary
+```
+
+Return the data of the object to be inserted in a savegame file.
+
+**Returns**
+A dictionary containing the data to be saved for this object.

docs/api/ESCObjectManager.md

@@ -13,7 +13,7 @@ A manager for ESC objects
 ### RESERVED\_OBJECTS
 
 ```gdscript
-const RESERVED_OBJECTS: Array = ["bg_music"]
+const RESERVED_OBJECTS: Array = ["bg_music","bg_sound"]
 ```
 
 ## Property Descriptions
@@ -38,7 +38,7 @@ Register the object in the manager
 
 #### Parameters
 
-- object: Obejct to register
+- object: Object to register
 - force: Register the object, even if it has already been registered
 
 ### has
@@ -62,6 +62,11 @@ func get_object(global_id: String) -> ESCObject
 
 Get the object from the object registry
 
+#### Parameters
+
+- global_id: The global id of the object to retrieve
+**Returns** The retrieved object, or null if not found
+
 ### unregister\_object
 
 ```gdscript
@@ -73,3 +78,15 @@ Remove an object from the registry
 #### Parameters
 
 - object: The object to unregister
+
+### save\_game
+
+```gdscript
+func save_game(p_savegame: ESCSaveGame) -> void
+```
+
+Insert data to save into savegame.
+
+#### Parameters
+
+- p_savegame: The savegame resource

docs/api/ESCSaveGame.md

@@ -0,0 +1,85 @@
+<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
+
+# ESCSaveGame
+
+**Extends:** [Resource](../Resource)
+
+## Description
+
+Resource used for holding savegames data.
+
+## Constants Descriptions
+
+### MAIN\_CURRENT\_SCENE\_FILENAME\_KEY
+
+```gdscript
+const MAIN_CURRENT_SCENE_FILENAME_KEY: String = "current_scene_filename"
+```
+
+Access key for the main data current_scene_filename
+
+### MAIN\_LAST\_SCENE\_GLOBAL\_ID\_KEY
+
+```gdscript
+const MAIN_LAST_SCENE_GLOBAL_ID_KEY: String = "last_scene_global_id"
+```
+
+Access key for the main data last_scene_global_id
+
+## Property Descriptions
+
+### escoria\_version
+
+```gdscript
+export var escoria_version: String = ""
+```
+
+Escoria version which the savegame was created with.
+
+### game\_version
+
+```gdscript
+export var game_version: String = ""
+```
+
+Game version which the savegame was created with.
+
+### name
+
+```gdscript
+export var name: String = ""
+```
+
+ Name of the savegame. Can be custom value, provided by the player.
+
+### date
+
+```gdscript
+export var date: String = ""
+```
+
+ Date of creation of the savegame.
+
+### main
+
+```gdscript
+export var main: Dictionary = {}
+```
+
+ Main data to be saved
+
+### globals
+
+```gdscript
+export var globals: Dictionary = {}
+```
+
+Escoria Global variables exported from ESCGlobalsManager
+
+### objects
+
+```gdscript
+export var objects: Dictionary = {}
+```
+
+Escoria objects exported from ESCObjectsManager

docs/api/ESCSaveManager.md

@@ -0,0 +1,101 @@
+<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
+
+# ESCSaveManager
+
+## Constants Descriptions
+
+### SAVE\_NAME\_TEMPLATE
+
+```gdscript
+const SAVE_NAME_TEMPLATE: String = "save_%03d.tres"
+```
+
+Template for savegames filenames
+
+### SETTINGS\_TEMPLATE
+
+```gdscript
+const SETTINGS_TEMPLATE: String = "settings.tres"
+```
+
+Template for settings filename
+
+## Property Descriptions
+
+### save\_folder
+
+```gdscript
+var save_folder: String
+```
+
+Variable containing the saves folder obtained from Project Settings
+
+### settings\_folder
+
+```gdscript
+var settings_folder: String
+```
+
+Variable containing the settings folder obtained from Project Settings
+
+## Method Descriptions
+
+### get\_saves\_list
+
+```gdscript
+func get_saves_list() -> Dictionary
+```
+
+Return a list of savegames metadata (id, date, name and game version)
+
+### save\_game\_exists
+
+```gdscript
+func save_game_exists(id: int) -> bool
+```
+
+Returns true whether the savegame identified by id does exist
+
+## Parameters
+- id: integer suffix of the savegame file
+
+### save\_game
+
+```gdscript
+func save_game(id: int, p_savename: String)
+```
+
+Save the current state of the game in a file suffixed with the id value.
+This id can help with slots development for the game developer.
+
+ ## Parameters
+- id: integer suffix of the savegame file
+- p_savename: name of the savegame
+
+### load\_game
+
+```gdscript
+func load_game(id: int)
+```
+
+Load a savegame file from its id.
+
+ ## Parameters
+- id: integer suffix of the savegame file
+
+### save\_settings
+
+```gdscript
+func save_settings()
+```
+
+Save the game settings in the settings file.
+
+### load\_settings
+
+```gdscript
+func load_settings() -> Resource
+```
+
+Load the game settings from the settings file
+**Returns** The Resource structure loaded from settings file

docs/api/ESCSaveSettings.md

@@ -0,0 +1,99 @@
+<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
+
+# ESCSaveSettings
+
+**Extends:** [Resource](../Resource)
+
+## Description
+
+Resource holding game settings.
+
+## Property Descriptions
+
+### escoria\_version
+
+```gdscript
+export var escoria_version: String = ""
+```
+
+ Version of ESCORIA Framework
+
+### text\_lang
+
+```gdscript
+export var text_lang: String = ""
+```
+
+ Language of displayed text
+
+### voice\_lang
+
+```gdscript
+export var voice_lang: String = ""
+```
+
+Language of voice speech
+
+### speech\_enabled
+
+```gdscript
+export var speech_enabled: bool = false
+```
+
+Whether speech is enabled
+
+### master\_volume
+
+```gdscript
+export var master_volume: float = 0
+```
+
+ Master volume (mix of music, voice and sfx)
+
+### music\_volume
+
+```gdscript
+export var music_volume: float = 0
+```
+
+Volume of music only
+
+### sfx\_volume
+
+```gdscript
+export var sfx_volume: float = 0
+```
+
+ Volume of SFX only
+
+### voice\_volume
+
+```gdscript
+export var voice_volume: float = 0
+```
+
+Voice volume only
+
+### fullscreen
+
+```gdscript
+export var fullscreen: bool = false
+```
+
+ True if game has to be fullscreen
+
+### skip\_dialog
+
+```gdscript
+export var skip_dialog: bool = true
+```
+
+True if skipping dialogs is allowed
+
+### rate\_shown
+
+```gdscript
+export var rate_shown: bool = false
+```
+
+ FIXME: to be defined (achievements?)

docs/api/RandGlobalCommand.md

@@ -0,0 +1,39 @@
+<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
+
+# RandGlobalCommand
+
+**Extends:** [ESCBaseCommand](../ESCBaseCommand) < [Node](../Node)
+
+## Description
+
+`rand_global name max_value`
+
+Fills the "name" global with a random value between 0 and max-value-1.
+
+@ESC
+
+## Method Descriptions
+
+### configure
+
+```gdscript
+func configure() -> ESCCommandArgumentDescriptor
+```
+
+Return the descriptor of the arguments of this command
+
+### validate
+
+```gdscript
+func validate(arguments: Array)
+```
+
+Validate wether the given arguments match the command descriptor
+
+### run
+
+```gdscript
+func run(command_params: Array) -> int
+```
+
+Run the command

docs/api/TeleportCommand.md

@@ -6,7 +6,7 @@
 
 ## Description
 
-`teleport object1 object2
+`teleport object1 object2`
 
 Sets the position of object1 to the position of object2.
 FIXME re-add the angle parameter here

docs/api/TeleportPosCommand.md

@@ -0,0 +1,40 @@
+<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
+
+# TeleportPosCommand
+
+**Extends:** [ESCBaseCommand](../ESCBaseCommand) < [Node](../Node)
+
+## Description
+
+`teleport_pos object1 x y`
+
+Sets the position of object1 to the position (x,y).
+FIXME re-add the angle parameter here
+
+@ESC
+
+## Method Descriptions
+
+### configure
+
+```gdscript
+func configure() -> ESCCommandArgumentDescriptor
+```
+
+Return the descriptor of the arguments of this command
+
+### validate
+
+```gdscript
+func validate(arguments: Array)
+```
+
+Validate wether the given arguments match the command descriptor
+
+### run
+
+```gdscript
+func run(command_params: Array) -> int
+```
+
+Run the command

docs/api/escoria.gd.md

@@ -6,7 +6,7 @@
 
 ## Description
 
-The escorie main script
+The escoria main script
 
 ## Enumerations
 
@@ -21,6 +21,16 @@ Current game state
 * DIALOG: Game is playing a dialog
 * WAIT: Game is waiting
 
+## Constants Descriptions
+
+### ESCORIA\_VERSION
+
+```gdscript
+const ESCORIA_VERSION: String = "0.1.0"
+```
+
+Escoria version number
+
 ## Property Descriptions
 
 ### logger
@@ -138,19 +148,11 @@ Inventory scene
 ### settings
 
 ```gdscript
-var settings: Dictionary
+var settings: ESCSaveSettings
 ```
 
 These are settings that the player can affect and save/load later
 
-### settings\_default
-
-```gdscript
-var settings_default: Dictionary
-```
-
-These are default settings
-
 ### current\_state
 
 ```gdscript
@@ -183,13 +185,13 @@ var inputs_manager
 
 The escoria inputs manager
 
-### save\_data
+### save\_manager
 
 ```gdscript
-var save_data
+var save_manager: ESCSaveManager
 ```
 
-Savegame management
+Savegames and settings manager
 
 ## Method Descriptions
 

docs/api/main.gd.md

@@ -92,6 +92,12 @@ Set the camera limits
 
 * camera_limits_id: The id of the room's camera limits to set
 
+### save\_game
+
+```gdscript
+func save_game(p_savegame_res: Resource) -> void
+```
+
 ### check\_game\_scene\_methods
 
 ```gdscript

docs/api/plugin.gd.md

@@ -44,14 +44,6 @@ func set_escoria_debug_settings()
 
 Prepare the settings in the Escoria debug category
 
-### set\_escoria\_internal\_settings
-
-```gdscript
-func set_escoria_internal_settings()
-```
-
-Prepare the settings in the Escoria internal category
-
 ### set\_escoria\_sound\_settings
 
 ```gdscript

docs/api/save_data.gd.md

@@ -1,112 +0,0 @@
-<!-- Auto-generated from JSON by GDScript docs maker. Do not edit this document directly. -->
-
-# save\_data.gd
-
-## Constants Descriptions
-
-### DATA\_STRING
-
-```gdscript
-class save_data.gd
-```
-
-### DATA\_STRING\_ARRAY
-
-```gdscript
-const DATA_STRING_ARRAY: int = 1
-```
-
-### DATA\_VARIANT
-
-```gdscript
-const DATA_VARIANT: int = 2
-```
-
-## Property Descriptions
-
-### base
-
-```gdscript
-var base
-```
-
-### slots
-
-```gdscript
-var slots
-```
-
-### max\_slots
-
-```gdscript
-var max_slots
-```
-
-### settings
-
-```gdscript
-var settings
-```
-
-## Method Descriptions
-
-### save\_settings
-
-```gdscript
-func save_settings(p_data, p_callback)
-```
-
-### check\_settings
-
-```gdscript
-func check_settings()
-```
-
-### load\_settings
-
-```gdscript
-func load_settings(p_callback)
-```
-
-### save\_game
-
-```gdscript
-func save_game(p_data, p_slot, p_callback)
-```
-
-### load\_slot
-
-```gdscript
-func load_slot(p_slot, p_callback)
-```
-
-### load\_autosave
-
-```gdscript
-func load_autosave(p_callback)
-```
-
-### autosave
-
-```gdscript
-func autosave(p_data, p_callback)
-```
-
-### get\_slots\_available
-
-```gdscript
-func get_slots_available(p_callback)
-```
-
-### autosave\_available
-
-```gdscript
-func autosave_available()
-```
-
-### start
-
-```gdscript
-func start()
-```
-

docs/esc.md

@@ -167,7 +167,7 @@ defaults to QUART. A `time` value of 0 will set the camera immediately.
 
 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
+- camlimits_id: int: id of the camera limits to apply (defined in ESCRoom's
   camera_limits array)
 #### <a name="CameraSetPosCommand.md"></a>`camera_set_pos speed x y` [API-Doc](api/CameraSetPosCommand.md)
 
@@ -185,7 +185,7 @@ 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.
-#### <a name="CameraSetZoomHeightCommand.md"></a>`camera_set_zoom_height pixels [time] [API-Doc](api/CameraSetZoomHeightCommand.md)
+#### <a name="CameraSetZoomHeightCommand.md"></a>`camera_set_zoom_height pixels [time]` [API-Doc](api/CameraSetZoomHeightCommand.md)
 
 Zooms the camera in/out to the desired `pixels` height.
 An optional `time` in seconds controls how long it takes for the camera
@@ -262,6 +262,9 @@ full path inside your game, for example "res://scenes/next_scene.tscn". 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).
+#### <a name="RandGlobalCommand.md"></a>`rand_global name max_value` [API-Doc](api/RandGlobalCommand.md)
+
+Fills the "name" global with a random value between 0 and max-value-1.
 #### <a name="RepeatCommand.md"></a>`repeat` [API-Doc](api/RepeatCommand.md)
 
 Restarts the execution of the current scope at the start. A scope can be a
@@ -349,10 +352,14 @@ object2 (object2 is optional)
 #### <a name="StopCommand.md"></a>`stop` [API-Doc](api/StopCommand.md)
 
 Stops the event's execution.
-#### <a name="TeleportCommand.md"></a>`teleport object1 object2 [API-Doc](api/TeleportCommand.md)
+#### <a name="TeleportCommand.md"></a>`teleport object1 object2` [API-Doc](api/TeleportCommand.md)
 
 Sets the position of object1 to the position of object2.
 FIXME re-add the angle parameter here
+#### <a name="TeleportPosCommand.md"></a>`teleport_pos object1 x y` [API-Doc](api/TeleportPosCommand.md)
+
+Sets the position of object1 to the position (x,y).
+FIXME re-add the angle parameter here
 #### <a name="TurnToCommand.md"></a>`turn_to object degrees` [API-Doc](api/TurnToCommand.md)
 
 **This command is currently not fully implemented.**
@@ -391,6 +398,9 @@ Makes the `player` walk to the position `x`/`y`.
 
 
 
+
+
+
 ## Dialogs
 
 Dialogs are specified by writing `?` with optional parameters, followed by a list of dialog options starting with `-`. Use `!` to end the dialog.