gymkhana-actions/vscode-extension-ashes/HOWTO.md

# 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