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

ASHES Language Support

A Visual Studio Code extension that provides syntax highlighting and IntelliSense for the ASHES (Adventure Scripting Helping Escoria) language used in Escoria adventure game framework.

Features

• Syntax Highlighting: Full syntax highlighting for ASHES language files (.esc)
• Auto-completion: IntelliSense for ASHES commands, built-in variables, and keywords with enhanced parameter information
• Hover Information: Detailed information about commands and variables on hover with clear parameter indicators (required/optional, type, variable name)
• Go to Definition: Ctrl+click on any command to navigate to its source file
• Code Snippets: Pre-built snippets for common ASHES patterns
• Command Reference: Built-in command reference panel with clickable command names
• Smart Indentation: Proper indentation rules for ASHES code structure
• Dynamic Command Generation: Automatically discovers and loads commands from your project's project.godot configuration - Learn more about dynamic commands

ASHES Language Features Supported

Events

• Event definitions with :event_name
• Event flags with | FLAG_NAME

Commands

• All standard Escoria commands (say, set_global, change_scene, etc.)
• Custom commands
• Enhanced command parameter hints with:
  • Required / Optional indicators
  • Parameter types (string, boolean, number, object, scene, animation, etc.)
  • Variable names in bold
  • Default values when available

Variables

• Local variables with var
• Global variables with global
• Built-in variables (CURRENT_PLAYER, ESC_LAST_SCENE, etc.)
• Global IDs with $ prefix

Control Flow

• If/elif/else statements
• While loops
• Break and done keywords

Dialog System

• Dialog blocks with ?!
• Dialog choices with -
• Conditional dialog choices with [condition]

Comments

• Line comments with #

Installation

1. Copy this extension folder to your VS Code extensions directory
2. Reload VS Code
3. Open any .esc file to see syntax highlighting

Usage

Auto-completion

• Type any ASHES command and press Ctrl+Space for suggestions
• Use $ prefix for global ID suggestions
• Built-in variables are automatically suggested

Go to Definition

• Ctrl+click on any command name in .esc files to navigate to its source file
• Works in both the editor and the command reference panel

Snippets

• Type snippet prefixes and press Tab to expand:
  • event - Create new event
  • say - Say command
  • dialog - Dialog block
  • if - If statement
  • And many more...

Command Reference

• Press Ctrl+Shift+P and type "ASHES: Show Command Reference"
• View all available commands with descriptions and enhanced parameter information
• Parameters show clear indicators: Required / Optional, type, variable name, and default values
• Click on any command name to navigate to its source file

Language Features

Syntax Highlighting

• Events are highlighted in blue
• Commands are highlighted in green
• Variables are highlighted in orange
• Strings are highlighted in yellow
• Comments are highlighted in gray
• Dialog blocks have special highlighting

Smart Indentation

• Automatic indentation for events, control flow, and dialog blocks
• Proper outdenting for break, done, else, etc.

Folding

• Events can be folded for better code organization
• Dialog blocks can be folded

Contributing

This extension is designed specifically for the Escoria framework and ASHES language. If you find issues or want to add features, please contribute to the project.

License

This extension is part of the Gymkhana project and follows the same license terms.