Dynamic commands
This commit is contained in:
355
vscode-extension-ashes/HOWTO.md
Normal file
355
vscode-extension-ashes/HOWTO.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# ASHES Language Support - HowTo Guide
|
||||
|
||||
This guide provides comprehensive instructions for configuring and using the ASHES Language Support extension for Visual Studio Code.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Installation & Configuration](#installation--configuration)
|
||||
2. [Available Commands & Functionality](#available-commands--functionality)
|
||||
3. [Language Features](#language-features)
|
||||
4. [Code Snippets](#code-snippets)
|
||||
5. [Auto-completion & IntelliSense](#auto-completion--intellisense)
|
||||
6. [Syntax Highlighting](#syntax-highlighting)
|
||||
7. [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Installation & Configuration
|
||||
|
||||
### Quick Installation
|
||||
|
||||
1. **Copy the extension folder** to your VS Code extensions directory:
|
||||
- **Linux**: `~/.vscode/extensions/`
|
||||
- **macOS**: `~/.vscode/extensions/`
|
||||
- **Windows**: `%USERPROFILE%\.vscode\extensions\`
|
||||
|
||||
2. **Rename the folder** to `ashes-language-support-0.1.0`
|
||||
|
||||
3. **Reload VS Code** or restart the application
|
||||
|
||||
4. **Verify installation** by opening any `.esc` file - you should see "ASHES" in the language selector (bottom-right corner)
|
||||
|
||||
### Development Mode Installation
|
||||
|
||||
1. **Open VS Code** in the extension directory:
|
||||
```bash
|
||||
cd vscode-extension-ashes
|
||||
code .
|
||||
```
|
||||
|
||||
2. **Install dependencies**:
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
3. **Compile TypeScript**:
|
||||
```bash
|
||||
npm run compile
|
||||
```
|
||||
|
||||
4. **Press F5** to run the extension in a new Extension Development Host window
|
||||
|
||||
### Configuration Options
|
||||
|
||||
The extension automatically configures itself when you open `.esc` files. No additional configuration is required, but you can customize:
|
||||
|
||||
- **File associations**: Ensure `.esc` files are associated with the ASHES language
|
||||
- **Editor settings**: Configure indentation, word wrap, etc. in VS Code settings
|
||||
- **Theme compatibility**: The extension works with all VS Code themes
|
||||
|
||||
## Available Commands & Functionality
|
||||
|
||||
### VSCode Commands
|
||||
|
||||
#### `ASHES: Show Command Reference`
|
||||
- **Access**: `Ctrl+Shift+P` → Type "ASHES: Show Command Reference"
|
||||
- **Description**: Opens a webview panel with a complete reference of all ASHES commands
|
||||
- **Features**:
|
||||
- Searchable table of commands
|
||||
- Parameter information
|
||||
- Command descriptions
|
||||
|
||||
### ASHES Language Commands
|
||||
|
||||
The extension supports **60+ ASHES commands** organized by category:
|
||||
|
||||
#### Animation Commands
|
||||
- `anim(object_id, animation_name)` - Play animation on object
|
||||
- `anim_block(object_id, animation_name)` - Play animation and wait for completion
|
||||
- `set_animations(object_id, animations)` - Set object animations
|
||||
|
||||
#### Camera Commands
|
||||
- `camera_push(x, y)` - Push camera to new position
|
||||
- `camera_set_pos(x, y)` - Set camera position
|
||||
- `camera_set_target(object_id)` - Set camera target
|
||||
- `camera_set_zoom(zoom_level)` - Set camera zoom level
|
||||
- `camera_shift(x, y)` - Shift camera position
|
||||
|
||||
#### Dialog & Text Commands
|
||||
- `say(speaker, text, translation_key, type)` - Display dialog text
|
||||
- `say_random(speaker, list_id, length)` - Say random text from list
|
||||
- `say_sequence(speaker, list_id, length, loop)` - Say text sequence
|
||||
- `block_say()` - Start a block of say commands
|
||||
- `end_block_say()` - End a block of say commands
|
||||
|
||||
#### Game State Commands
|
||||
- `change_scene(scene_path, enable_transition, run_events)` - Change to a different scene
|
||||
- `save_game(save_name)` - Save game state
|
||||
- `set_global(variable_name, value, force)` - Set global variable
|
||||
- `set_globals(variables_dict)` - Set multiple global variables
|
||||
- `inc_global(variable_name)` - Increment global variable
|
||||
- `dec_global(variable_name)` - Decrement global variable
|
||||
|
||||
#### Inventory Commands
|
||||
- `inventory_add(item_id)` - Add item to inventory
|
||||
- `inventory_remove(item_id)` - Remove item from inventory
|
||||
- `item_count_add(item_id, count)` - Add to item count
|
||||
- `set_item_custom_data(item_id, key, value)` - Set item custom data
|
||||
|
||||
#### Object Manipulation Commands
|
||||
- `set_active(object_id, active)` - Set object active/inactive
|
||||
- `set_interactive(object_id, interactive)` - Set object interactive state
|
||||
- `set_state(object_id, state)` - Set object state
|
||||
- `set_tooltip(object_id, action, text)` - Set object tooltip
|
||||
- `teleport(object_id, target_id)` - Teleport object to target
|
||||
- `teleport_pos(object_id, x, y)` - Teleport object to position
|
||||
- `walk(object_id, target_id)` - Walk object to target
|
||||
- `walk_to_pos(object_id, x, y)` - Walk object to position
|
||||
|
||||
#### Audio/Video Commands
|
||||
- `play_snd(sound_path, type)` - Play sound file
|
||||
- `play_lib_snd(filename, namespace)` - Play library sound
|
||||
- `play_video(video_path)` - Play video file
|
||||
- `stop_snd(sound_type)` - Stop sound
|
||||
|
||||
#### Utility Commands
|
||||
- `print(message)` - Print debug message
|
||||
- `wait(duration)` - Wait for specified time
|
||||
- `transition(transition_type, duration)` - Play transition effect
|
||||
- `custom(command_name, ...args)` - Execute custom command
|
||||
|
||||
### Built-in Variables
|
||||
|
||||
The extension provides auto-completion for these built-in variables:
|
||||
- `CURRENT_PLAYER` - Current player object
|
||||
- `ESC_LAST_SCENE` - Last scene identifier
|
||||
- `ESC_CURRENT_SCENE` - Current scene identifier
|
||||
- `FORCE_LAST_SCENE_NULL` - Force last scene to null
|
||||
- `ANIMATION_RESOURCES` - Animation resources
|
||||
|
||||
### Keywords
|
||||
|
||||
Auto-completion for ASHES keywords:
|
||||
- `var` - Local variable declaration
|
||||
- `global` - Global variable declaration
|
||||
- `if`, `elif`, `else` - Conditional statements
|
||||
- `while` - Loop statement
|
||||
- `break`, `done` - Loop control
|
||||
- `stop`, `pass` - Flow control
|
||||
- `true`, `false`, `nil` - Boolean values
|
||||
- `and`, `or`, `not` - Logical operators
|
||||
- `in`, `is`, `active` - Special operators
|
||||
|
||||
## Language Features
|
||||
|
||||
### Events
|
||||
```ashes
|
||||
:event_name
|
||||
# Event code here
|
||||
|
||||
:event_with_target "target_id"
|
||||
# Event code here
|
||||
|
||||
:event_with_flags | NO_UI | NO_TT
|
||||
# Event code here
|
||||
```
|
||||
|
||||
### Variables
|
||||
```ashes
|
||||
# Local variables
|
||||
var my_variable = "value"
|
||||
|
||||
# Global variables
|
||||
global game_state = "playing"
|
||||
|
||||
# Global IDs (with $ prefix)
|
||||
set_active($player, true)
|
||||
```
|
||||
|
||||
### Control Flow
|
||||
```ashes
|
||||
if condition:
|
||||
# Code here
|
||||
elif other_condition:
|
||||
# Code here
|
||||
else:
|
||||
# Code here
|
||||
|
||||
while condition:
|
||||
# Code here
|
||||
break # Exit loop
|
||||
# or
|
||||
done # Continue to next iteration
|
||||
```
|
||||
|
||||
### Dialog System
|
||||
```ashes
|
||||
?!
|
||||
- "Choice 1"
|
||||
# Code for choice 1
|
||||
- "Choice 2" [condition]
|
||||
# Code for choice 2 (only if condition is true)
|
||||
```
|
||||
|
||||
### Comments
|
||||
```ashes
|
||||
# This is a line comment
|
||||
```
|
||||
|
||||
## Code Snippets
|
||||
|
||||
The extension provides **20+ code snippets** for common ASHES patterns:
|
||||
|
||||
### Event Snippets
|
||||
- `event` → Create new event
|
||||
- `eventtarget` → Create event with target
|
||||
- `eventflags` → Create event with flags
|
||||
- `eventflagstarget` → Create event with flags and target
|
||||
|
||||
### Command Snippets
|
||||
- `say` → Say command
|
||||
- `setglobal` → Set global variable
|
||||
- `changescene` → Change scene
|
||||
- `setactive` → Set object active
|
||||
- `teleport` → Teleport object
|
||||
- `walk` → Walk object
|
||||
- `playsnd` → Play sound
|
||||
- `playvideo` → Play video
|
||||
- `inventoryadd` → Add to inventory
|
||||
- `inventoryremove` → Remove from inventory
|
||||
|
||||
### Control Flow Snippets
|
||||
- `if` → If statement
|
||||
- `ifelse` → If-else statement
|
||||
- `while` → While loop
|
||||
|
||||
### Dialog Snippets
|
||||
- `dialog` → Dialog block with choice
|
||||
- `dialogif` → Dialog choice with condition
|
||||
|
||||
### Utility Snippets
|
||||
- `var` → Local variable declaration
|
||||
- `global` → Global variable declaration
|
||||
- `comment` → Add comment
|
||||
- `print` → Print debug message
|
||||
|
||||
### Using Snippets
|
||||
1. Type the snippet prefix (e.g., `event`)
|
||||
2. Press `Tab` to expand
|
||||
3. Use `Tab` to navigate between placeholders
|
||||
4. Press `Enter` or `Escape` to finish
|
||||
|
||||
## Auto-completion & IntelliSense
|
||||
|
||||
### Trigger Characters
|
||||
Auto-completion is triggered by:
|
||||
- Space character (` `)
|
||||
- Opening parenthesis (`(`)
|
||||
- Dollar sign (`$`) for global IDs
|
||||
|
||||
### Command Completion
|
||||
- Type any ASHES command and press `Ctrl+Space`
|
||||
- Commands show with descriptions and parameter hints
|
||||
- Parameters are automatically inserted with placeholders
|
||||
|
||||
### Variable Completion
|
||||
- Built-in variables are automatically suggested
|
||||
- Global IDs with `$` prefix are suggested
|
||||
- Keywords are suggested in appropriate contexts
|
||||
|
||||
### Hover Information
|
||||
- Hover over any command to see detailed information
|
||||
- Shows command description and parameter list
|
||||
- Works for built-in variables and keywords
|
||||
|
||||
## Syntax Highlighting
|
||||
|
||||
The extension provides comprehensive syntax highlighting:
|
||||
|
||||
### Color Scheme
|
||||
- **Events** (`:event_name`) - Blue
|
||||
- **Commands** (`say`, `set_global`, etc.) - Green
|
||||
- **Variables** (`var`, `global`) - Orange
|
||||
- **Strings** (`"text"`) - Yellow
|
||||
- **Comments** (`# comment`) - Gray
|
||||
- **Dialog blocks** (`?!`) - Special highlighting
|
||||
- **Global IDs** (`$object_id`) - Distinct color
|
||||
|
||||
### Smart Indentation
|
||||
- Automatic indentation for events, control flow, and dialog blocks
|
||||
- Proper outdenting for `break`, `done`, `else`, etc.
|
||||
- Configurable through VS Code settings
|
||||
|
||||
### Code Folding
|
||||
- Events can be folded for better organization
|
||||
- Dialog blocks can be folded
|
||||
- Folding markers: `:event_name` (start), empty line (end)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Extension Not Loading
|
||||
1. Check that the folder is in the correct extensions directory
|
||||
2. Restart VS Code completely
|
||||
3. Check the Developer Console for errors (`Help > Toggle Developer Tools`)
|
||||
|
||||
### Syntax Highlighting Not Working
|
||||
1. Ensure the file has a `.esc` extension
|
||||
2. Check that the language is set to "ASHES" in the bottom-right corner
|
||||
3. Reload the window (`Ctrl+Shift+P` → "Developer: Reload Window")
|
||||
|
||||
### Auto-completion Not Working
|
||||
1. Press `Ctrl+Space` to manually trigger completion
|
||||
2. Check that the extension is activated (should show in the Extensions panel)
|
||||
3. Ensure you're typing in a `.esc` file
|
||||
|
||||
### Snippets Not Working
|
||||
1. Make sure you're in a `.esc` file
|
||||
2. Type the snippet prefix and press `Tab`
|
||||
3. Check that the language is set to "ASHES"
|
||||
|
||||
### Performance Issues
|
||||
1. Large files may cause slower auto-completion
|
||||
2. Consider splitting large `.esc` files into smaller ones
|
||||
3. Disable other extensions if needed
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### Custom Commands
|
||||
The extension supports custom commands through the `custom()` function:
|
||||
```ashes
|
||||
custom("my_custom_command", "param1", "param2")
|
||||
```
|
||||
|
||||
### File Organization
|
||||
- Use multiple `.esc` files for different scenes/characters
|
||||
- Organize events logically within files
|
||||
- Use comments to document complex logic
|
||||
|
||||
### Integration with Escoria
|
||||
- The extension is designed specifically for the Escoria framework
|
||||
- Commands correspond to Escoria's ASHES implementation
|
||||
- Global IDs should match your Escoria project structure
|
||||
|
||||
## Contributing
|
||||
|
||||
To contribute to the extension:
|
||||
1. Fork the repository
|
||||
2. Make your changes
|
||||
3. Test thoroughly with `.esc` files
|
||||
4. Submit a pull request
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions:
|
||||
1. Check this HowTo guide first
|
||||
2. Review the main README.md
|
||||
3. Check the installation guide (INSTALL.md)
|
||||
4. Report issues through the project's issue tracker
|
||||
Reference in New Issue
Block a user