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

Installation Guide for ASHES Language Support Extension

Quick Installation

Automated Installation (Recommended)

Use the provided installation script for the easiest setup:

./install-extension.sh

This script will:

1. Compile the extension using npm and the correct Node.js version (via nvm if available)
2. Create a symlink to your VS Code extensions directory
3. Handle dependencies automatically

Manual Installation

1. Compile the extension:

   cd vscode-extension-ashes
   
   # Use nvm if available (recommended)
   nvm use  # Uses version from .nvmrc
   
   # Install dependencies
   npm install
   
   # Compile TypeScript
   npm run compile
   

2. Copy the extension folder to your VS Code extensions directory:

   • Linux: ~/.vscode/extensions/
   • macOS: ~/.vscode/extensions/
   • Windows: %USERPROFILE%\.vscode\extensions\

3. Rename the folder to ashes-language-support-0.1.0 (or similar)

4. Reload VS Code or restart the application

5. Test the extension by opening any .esc file

Alternative Installation (Development Mode)

1. Open VS Code in the extension directory:

   cd vscode-extension
   code .
   

2. Press F5 to run the extension in a new Extension Development Host window

3. Open a .esc file in the new window to test the extension

Building from Source

1. Set up Node.js version (recommended):

   # Use nvm if available to get the correct Node.js version
   nvm use  # Uses version from .nvmrc (v22)
   

2. Install dependencies:

   npm install
   

3. Compile TypeScript:

   npm run compile
   

4. Package the extension (optional):

   npx vsce package
   

Testing the Extension

1. Open the sample file: sample.esc in the extension directory
2. Check syntax highlighting: Events, commands, and variables should be colorized
3. Test auto-completion: Type say( and press Ctrl+Space
4. Test snippets: Type event and press Tab
5. Test hover: Hover over commands like say or set_global
6. Test command reference: Press Ctrl+Shift+P and type "ASHES: Show Command Reference"

Features to Test

• ✅ Syntax highlighting for events (:event_name)
• ✅ Syntax highlighting for commands (say, set_global, etc.)
• ✅ Syntax highlighting for variables (var, global)
• ✅ Syntax highlighting for dialog blocks (?!)
• ✅ Auto-completion for commands
• ✅ Auto-completion for built-in variables
• ✅ Code snippets for common patterns
• ✅ Hover information for commands
• ✅ Smart indentation
• ✅ Code folding for events

Troubleshooting

Extension not loading

• Check that the folder is in the correct extensions directory
• Restart VS Code completely
• Check the Developer Console for errors (Help > Toggle Developer Tools)

Syntax highlighting not working

• Make sure the file has a .esc extension
• Check that the language is set to "ASHES" in the bottom-right corner of VS Code

Auto-completion not working

• Press Ctrl+Space to manually trigger completion
• Check that the extension is activated (should show in the Extensions panel)

Compilation errors

• Make sure you're using the correct Node.js version: nvm use (uses v22 from .nvmrc)
• Clear node_modules and reinstall: rm -rf node_modules && npm install
• Check that TypeScript is installed: npm list typescript
• Ensure all dependencies are installed: npm install

Uninstalling

Simply delete the extension folder from your VS Code extensions directory and restart VS Code.