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
2. Available Commands & Functionality
3. Language Features
4. Code Snippets
5. Auto-completion & IntelliSense
6. Syntax Highlighting
7. 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:

   cd vscode-extension-ashes
   code .
   

2. Install dependencies:

   npm install
   

3. Compile TypeScript:

   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

:event_name
    # Event code here

:event_with_target "target_id"
    # Event code here

:event_with_flags | NO_UI | NO_TT
    # Event code here

Variables

# Local variables
var my_variable = "value"

# Global variables
global game_state = "playing"

# Global IDs (with $ prefix)
set_active($player, true)

Control Flow

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

?!
    - "Choice 1"
        # Code for choice 1
    - "Choice 2" [condition]
        # Code for choice 2 (only if condition is true)

Comments

# 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:

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