Dynamic commands

vscode-extension-ashes/DYNAMIC_COMMANDS.md

@@ -0,0 +1,76 @@
+# Dynamic Command Generation
+
+The ASHES VSCode extension now supports dynamic command generation by parsing the `project.godot` file and extracting command information from the specified command directories.
+
+## How it Works
+
+1. **Project.godot Parsing**: The extension reads the `project.godot` file and looks for the `main/command_directories` setting in the `[escoria]` section.
+
+2. **Command Discovery**: It scans each directory specified in `command_directories` for `.gd` files (excluding `.gd.uid` files).
+
+3. **Command Parsing**: For each command file, it extracts:
+   - Command name (from filename)
+   - Description (from comment blocks)
+   - Parameters (from comment documentation and `configure()` method)
+   - Examples (if available)
+
+4. **Caching**: Commands are cached for 5 minutes to improve performance.
+
+## Configuration
+
+The extension automatically detects command directories from your `project.godot` file:
+
+```ini
+[escoria]
+main/command_directories=["res://addons/escoria-core/game/core-scripts/esc/commands", "res://addons/escoria-ui-return-monkey-island/esc/commands", "res://addons/escoria-ui-return-monkey-island-dialog-simple/commands"]
+```
+
+## Features
+
+- **Auto-completion**: Commands are automatically available in IntelliSense
+- **Hover Documentation**: Hover over commands to see descriptions and parameters
+- **Command Reference**: Use `Ctrl+Shift+P` → "ASHES: Show ASHES Command Reference" to see all commands
+- **Cache Refresh**: Use `Ctrl+Shift+P` → "ASHES: Refresh ASHES Commands" to reload commands
+
+## Command File Format
+
+Commands should follow the standard Escoria format:
+
+```gdscript
+# `command_name param1 param2 [optional_param]`
+#
+# Description of what the command does.
+#
+# **Parameters**
+#
+# - *param1*: Description of parameter 1
+# - *param2*: Description of parameter 2
+# - *optional_param*: Description of optional parameter (default: default_value)
+#
+# Example: `command_name("value1", "value2")`
+#
+# @ESC
+extends ESCBaseCommand
+class_name CommandNameCommand
+
+func configure() -> ESCCommandArgumentDescriptor:
+    return ESCCommandArgumentDescriptor.new(
+        2,  # Number of required parameters
+        [TYPE_STRING, TYPE_STRING, TYPE_STRING],  # Parameter types
+        [null, null, "default_value"],  # Default values
+        [true, true, false]  # Required flags
+    )
+```
+
+## Fallback Behavior
+
+If the extension cannot find or parse the `project.godot` file, it falls back to the default command directories:
+- `res://addons/escoria-core/game/core-scripts/esc/commands`
+- `res://addons/escoria-ui-return-monkey-island/esc/commands`
+- `res://addons/escoria-ui-return-monkey-island-dialog-simple/commands`
+
+## Troubleshooting
+
+- **Commands not appearing**: Make sure your `project.godot` file has the correct `main/command_directories` setting
+- **Outdated commands**: Use the "Refresh ASHES Commands" command to reload the cache
+- **Missing descriptions**: Ensure your command files have proper comment documentation