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

ASHES Language Support Extension - Requirements

Project Overview

The ASHES Language Support extension is a Visual Studio Code extension that provides comprehensive language support for the ASHES (Adventure Scripting Helping Escoria) language used in the Escoria adventure game framework. ASHES is a Python-like scripting language specifically designed for creating adventure games, borrowing heavily from Pythonic languages while being optimized for the Escoria framework.

This extension enhances the development experience for game developers working with ASHES scripts by providing syntax highlighting, IntelliSense, error detection, and other modern IDE features. The extension dynamically discovers commands from the project's configuration and provides real-time validation based on the actual Escoria command implementations.

ASHES Language Specifications

Based on the Escoria core documentation, ASHES supports the following language features:

Data Types

• Integers: Whole numbers
• Floats/Reals: Decimal numbers
• Booleans: true and false values
• Strings: Text enclosed in quotes, can be concatenated with + operator
• Nil: The keyword nil is used in place of "null" and/or where empty values are desired

Language Features

• Events: Defined with :event_name at the highest level of scope (no indentation)
• Variables: Local variables with var, global variables with global
• Comments: Line comments using # character (block comments not supported)
• Branching: if, elif, and else statements
• Looping: while loops with break keyword to exit
• Dialog System: Dialog blocks with ?! and choices with -
• Global IDs: Can be prefixed with $ to avoid quotation marks
• Inventory Checking: if $item in inventory: syntax
• State Checking: if $object is active: and if $object is "state": syntax

Operators

• Boolean: not, and, or, ! (exclamation mark for not)
• Arithmetic: +, -, *, /
• Comparison: >, >=, <, <=, ==

Functional Requirements

1. Language Recognition and File Association

FR-1.1: File Extension Association

• The extension MUST recognize .esc files as ASHES language files
• The extension MUST set the language ID to ashes for .esc files
• The extension MUST activate automatically when .esc files are opened

FR-1.2: Language Configuration

• The extension MUST provide proper language configuration including:
  • Line comments using # character
  • Bracket matching for {}, [], ()
  • Auto-closing pairs for brackets and quotes
  • Word pattern recognition for identifiers
  • Smart indentation rules for ASHES syntax

2. Syntax Highlighting

FR-2.1: Comprehensive Syntax Highlighting

• The extension MUST provide syntax highlighting for ASHES language features as specified in the Escoria core documentation:
  • Events: :event_name (blue highlighting) - Events are denoted using :event where "event" is the name of the event
  • Commands: Function calls like say(), set_global() (green highlighting) - Commands are called just as functions normally are
  • Variables: var, global declarations (orange highlighting) - Local variables with var, global variables with global
  • Strings: Quoted text "text" (yellow highlighting) - Strings can be concatenated using the + operator
  • Comments: # comment (gray highlighting) - Line comments using hashtag/pound sign
  • Dialog blocks: ?! syntax (special highlighting) - Dialog blocks begin with ?!
  • Dialog choices: - "choice text" [condition] (special highlighting) - Each dialog choice is prefixed with -
  • Global IDs: $object_id (distinct color) - Global IDs can be prefixed with $ to avoid quotation marks
  • Keywords: if, elif, else, while, break, done, stop, pass, true, false, nil, and, or, not, in, is, active

FR-2.2: Advanced Syntax Patterns

• The extension MUST highlight event definitions with flags: :event_name | FLAG_NAME (e.g., :look | NO_UI | NO_TT)
• The extension MUST highlight event definitions with targets: :event_name "target"
• The extension MUST highlight dialog choices with conditions: - "choice text" [condition]
• The extension MUST highlight control flow statements with proper indentation
• The extension MUST highlight boolean operators: not, and, or, ! (exclamation mark for not)
• The extension MUST highlight arithmetic operators: +, -, *, /
• The extension MUST highlight comparison operators: >, >=, <, <=, ==
• The extension MUST highlight the in inventory feature: if $gold_brick in inventory:
• The extension MUST highlight the is active feature: if $room_monster is active:
• The extension MUST highlight the is keyword for state checking: if $room_monster is "running_away":

3. IntelliSense and Auto-completion

FR-3.1: Command Auto-completion

• The extension MUST provide auto-completion for all ASHES commands from the configured command directories:
  • Core Commands (from escoria-core): accept_input, anim, anim_block, block_say, camera_push, camera_set_pos, camera_set_target, camera_set_zoom, change_scene, custom, dec_global, enable_terrain, end_block_say, hide_menu, inc_global, inventory_add, inventory_remove, play_snd, print_internal, queue_event, queue_resource, rand_global, repeat, save_game, say, sched_event, set_active, set_angle, set_animations, set_direction, set_global, set_globals, set_gui_visible, set_interactive, set_item_custom_data, set_speed, set_state, show_menu, slide, spawn, stop, stop_snd, teleport, teleport_pos, transition, turn_to, wait, walk, walk_to_pos
  • UI Commands (from escoria-ui-return-monkey-island): item_count_add, music_enable, play_lib_snd, play_video, set_tooltip
  • Dialog Commands (from escoria-ui-return-monkey-island-dialog-simple): say_last_dialog_option, say_random, say_sequence
• The extension MUST dynamically load commands from project configuration
• The extension MUST show command descriptions and parameter information
• The extension MUST support trigger characters: space, (, $

FR-3.2: Enhanced Parameter Information

• The extension MUST display parameter information with:
  • Required / Optional indicators
  • Parameter types (string, boolean, number, object, scene, animation, etc.)
  • Variable names in bold formatting
  • Default values when available
  • Example usage patterns

FR-3.3: Variable and Keyword Completion

• The extension MUST provide auto-completion for built-in variables as specified in the Escoria core documentation:
  • CURRENT_PLAYER - References the current player scene being used, irrespective of its global ID
  • ESC_LAST_SCENE - Holds the global ID of the last visited room
  • ESC_CURRENT_SCENE - Holds the global ID of the current room
  • FORCE_LAST_SCENE_NULL - Internal use only
  • ANIMATION_RESOURCES - Internal use only
• The extension MUST provide auto-completion for ASHES keywords: var, global, if, elif, else, while, break, done, stop, pass, true, false, nil, and, or, not, in, is, active
• The extension MUST provide auto-completion for global IDs with $ prefix (e.g., $object_1_id)

4. Dynamic Command Discovery

FR-4.1: Project Configuration Parsing

• The extension MUST parse project.godot files to extract command directories from the [escoria] section
• The extension MUST support the main/command_directories setting with array format: ["path1", "path2", "path3"]
• The extension MUST handle the actual project configuration format as seen in real projects:

  [escoria]
  main/command_directories=["res://addons/escoria-core/game/core-scripts/esc/commands", "res://addons/escoria-ui-return-monkey-island/esc/commands", "res://addons/escoria-ui-return-monkey-island-dialog-simple/commands"]
  

• The extension MUST provide fallback to default command directories if parsing fails:
  • res://addons/escoria-core/game/core-scripts/esc/commands (core commands)
  • res://addons/escoria-ui-return-monkey-island/esc/commands (UI commands)
  • res://addons/escoria-ui-return-monkey-island-dialog-simple/commands (dialog commands)

FR-4.2: Command File Parsing

• The extension MUST scan specified directories for .gd files (excluding .gd.uid)
• The extension MUST extract command information from GDScript files following the Escoria command format:
  • Command name from filename (e.g., say.gd → say command)
  • Description from comment blocks starting with # \command_name param1 param2 [optional_param]``
  • Parameters from comment documentation in **Parameters** section with - *param*: description format
  • Parameter types and requirements from configure() method using ESCCommandArgumentDescriptor
  • Examples from comment blocks with Example: \command_name("value1", "value2")`` format
• The extension MUST handle the standard Escoria command documentation format:

  # `command_name param1 param2 [optional_param]`
  #
  # Description of what the command does.
  #
  # **Parameters**
  #
  # - *param1*: Description of parameter 1
  # - *param2*: Description of parameter 2
  # - *optional_param*: Description of optional parameter (default: default_value)
  #
  # Example: `command_name("value1", "value2")`
  #
  # @ESC
  extends ESCBaseCommand
  class_name CommandNameCommand
  

FR-4.3: Command Caching

• The extension MUST cache discovered commands for 5 minutes to improve performance
• The extension MUST provide manual cache refresh functionality
• The extension MUST update cache when workspace changes

5. Hover Information

FR-5.1: Command Documentation

• The extension MUST provide detailed hover information for commands
• The extension MUST show command descriptions and parameter details
• The extension MUST format parameter information with clear indicators
• The extension MUST provide example usage in hover tooltips

FR-5.2: Variable Documentation

• The extension MUST provide hover information for built-in variables
• The extension MUST explain the purpose of each built-in variable

6. Go to Definition

FR-6.1: Command Navigation

• The extension MUST support Ctrl+click navigation to command source files
• The extension MUST find the class definition line in command files
• The extension MUST open the correct file and position the cursor appropriately
• The extension MUST work in both the editor and command reference panel

7. Code Snippets

FR-7.1: Event Snippets

• The extension MUST provide snippets for:
  • event → Create new event
  • eventtarget → Create event with target
  • eventflags → Create event with flags
  • eventflagstarget → Create event with flags and target

FR-7.2: Command Snippets

• The extension MUST provide snippets for common commands:
  • 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

FR-7.3: Control Flow Snippets

• The extension MUST provide snippets for:
  • if → If statement
  • ifelse → If-else statement
  • while → While loop

FR-7.4: Dialog Snippets

• The extension MUST provide snippets for:
  • dialog → Dialog block with choice
  • dialogif → Dialog choice with condition

FR-7.5: Utility Snippets

• The extension MUST provide snippets for:
  • var → Local variable declaration
  • global → Global variable declaration
  • comment → Add comment
  • print → Print debug message

8. Command Reference Panel

FR-8.1: Interactive Command Reference

• The extension MUST provide a webview panel showing all available commands
• The extension MUST display commands in a searchable table format
• The extension MUST show command descriptions and parameter information
• The extension MUST support clickable command names for navigation

FR-8.2: Command Reference Features

• The extension MUST format parameter information with clear indicators
• The extension MUST provide example usage for each command
• The extension MUST support navigation to source files from the reference panel

9. Syntax Validation and Error Detection

FR-9.1: Real-time Syntax Validation

• The extension MUST validate ASHES syntax in real-time
• The extension MUST provide error diagnostics with appropriate severity levels
• The extension MUST debounce validation to avoid excessive processing (500ms)
• The extension MUST validate on document changes, open, and save

FR-9.2: Event Definition Validation

• The extension MUST validate event definitions: :event_name [| FLAGS] ["target"]
• The extension MUST check event name format (letters, numbers, underscores)
• The extension MUST validate event flags against known valid flags (e.g., TK, TR, TG, SKIP, GLOBAL)
• The extension MUST validate event targets as quoted strings
• The extension MUST suggest common event names for better practices (e.g., init, ready, setup, action1, action2, action3, use, look, talk, walk, interact)
• The extension MUST validate that events are at the highest level of scope (no indentation)

FR-9.3: Dialog System Validation

• The extension MUST validate dialog blocks (?!) syntax
• The extension MUST validate dialog choices (- "text" [condition])
• The extension MUST check for proper dialog block closure
• The extension MUST validate choice text is not empty
• The extension MUST validate condition syntax in dialog choices
• The extension MUST support nested dialog blocks with proper indentation
• The extension MUST validate break and done keywords in dialog context
• The extension MUST validate break with level specification (e.g., break 2)

FR-9.4: Command and Control Flow Validation

• The extension MUST validate function calls against known commands from all configured directories
• The extension MUST validate control flow statements (if, elif, else, while)
• The extension MUST check for missing colons in control flow statements
• The extension MUST validate condition expressions including:
  • Boolean operators (and, or, not, !)
  • Comparison operators (>, >=, <, <=, ==)
  • Inventory checks (if $item in inventory:)
  • State checks (if $object is active:, if $object is "state":)
  • Global ID comparisons (if $object1 == $object2:)
• The extension MUST check for proper indentation after control flow statements
• The extension MUST validate while loops with break keyword support

FR-9.5: String and Bracket Validation

• The extension MUST validate string literals for proper quoting
• The extension MUST check for unclosed strings and brackets
• The extension MUST validate parentheses, brackets, and braces matching
• The extension MUST handle escaped characters in strings
• The extension MUST validate string concatenation with + operator
• The extension MUST validate global variable substitution in strings using {variable_name} syntax

FR-9.6: Indentation Validation

• The extension MUST enforce tab-based indentation (not spaces) as required by ASHES
• The extension MUST detect mixed tabs and spaces
• The extension MUST allow deep indentation for complex nested structures
• The extension MUST validate proper indentation for control flow blocks
• The extension MUST validate that events are at the top level (no indentation)
• The extension MUST validate proper indentation for dialog blocks and choices

FR-9.7: Variable and Assignment Validation

• The extension MUST validate variable declarations (var, global)
• The extension MUST check for reserved keyword usage in variable names
• The extension MUST validate assignment syntax
• The extension MUST validate global variable scoping rules
• The extension MUST warn about potential issues with global variable initialization order

FR-9.8: Specific Command Pattern Validation

• The extension MUST validate say() command patterns with proper speaker, text, and optional parameters
• The extension MUST validate inventory command patterns (inventory_add, inventory_remove)
• The extension MUST validate global variable commands (set_global, inc_global, dec_global)
• The extension MUST validate camera commands (camera_set_pos, camera_set_target, etc.)
• The extension MUST validate animation commands (anim, anim_block, set_animations)
• The extension MUST validate movement commands (walk, teleport, slide)
• The extension MUST check for proper parameter formatting in common commands
• The extension MUST validate command-specific parameter requirements based on actual command implementations

10. Smart Indentation

FR-10.1: Automatic Indentation

• The extension MUST provide automatic indentation for:
  • Events and their content
  • Control flow statements (if, elif, else, while)
  • Dialog blocks and choices
• The extension MUST properly outdent for break, done, else, etc.

FR-10.2: Indentation Rules

• The extension MUST use tab-based indentation exclusively
• The extension MUST increase indentation after control flow statements ending with :
• The extension MUST decrease indentation for control flow keywords

11. Code Folding

FR-11.1: Event Folding

• The extension MUST support folding for events
• The extension MUST use :event_name as start markers
• The extension MUST use empty lines as end markers

FR-11.2: Dialog Block Folding

• The extension MUST support folding for dialog blocks
• The extension MUST properly handle nested dialog structures

12. VSCode Commands

FR-12.1: Command Palette Integration

• The extension MUST provide the following commands:
  • ASHES: Show Command Reference - Opens the command reference panel
  • ASHES: Refresh ASHES Commands - Refreshes the command cache
  • ASHES: Refresh ASHES Diagnostics - Refreshes syntax validation

FR-12.2: Command Functionality

• The extension MUST make all commands available in the command palette
• The extension MUST provide appropriate command categories
• The extension MUST show success/error messages for command execution

Non-Functional Requirements

1. Performance

NFR-1.1: Response Time

• The extension MUST provide auto-completion suggestions within 200ms
• The extension MUST validate syntax with minimal impact on editor performance
• The extension MUST use debouncing for real-time validation (500ms)

NFR-1.2: Memory Usage

• The extension MUST cache commands efficiently with 5-minute expiration
• The extension MUST not retain unnecessary data in memory
• The extension MUST handle large projects without excessive memory usage

NFR-1.3: Startup Time

• The extension MUST activate quickly when .esc files are opened
• The extension MUST not significantly impact VSCode startup time

2. Compatibility

NFR-2.1: VSCode Version

• The extension MUST be compatible with VSCode version 1.74.0 and later
• The extension MUST use the VSCode API appropriately for the target version

NFR-2.2: Platform Support

• The extension MUST work on Windows, macOS, and Linux
• The extension MUST handle different file system path formats correctly

NFR-2.3: Theme Compatibility

• The extension MUST work with all VSCode themes
• The extension MUST use VSCode theme variables for consistent appearance

3. Reliability

NFR-3.1: Error Handling

• The extension MUST handle file system errors gracefully
• The extension MUST provide fallback behavior when command parsing fails
• The extension MUST not crash VSCode under any circumstances

NFR-3.2: Robustness

• The extension MUST handle malformed project.godot files
• The extension MUST handle missing command directories
• The extension MUST handle corrupted or invalid command files

4. Usability

NFR-4.1: User Experience

• The extension MUST provide clear and helpful error messages
• The extension MUST offer suggestions for common mistakes
• The extension MUST be intuitive for users familiar with VSCode

NFR-4.2: Documentation

• The extension MUST provide comprehensive hover documentation
• The extension MUST include helpful examples in tooltips
• The extension MUST offer clear parameter information

5. Maintainability

NFR-5.1: Code Quality

• The extension MUST be written in TypeScript for type safety
• The extension MUST follow VSCode extension best practices
• The extension MUST have clear separation of concerns

NFR-5.2: Extensibility

• The extension MUST be designed to easily add new command types
• The extension MUST support custom command directories
• The extension MUST allow for future language feature additions

Technical Requirements

1. Architecture

TR-1.1: Extension Structure

• The extension MUST use the standard VSCode extension structure
• The extension MUST have a clear separation between language features and UI components
• The extension MUST use the VSCode Language Server Protocol where appropriate

TR-1.2: Module Organization

• The extension MUST organize code into logical modules:
  • extension.ts - Main extension entry point
  • commandParser.ts - Command discovery and parsing
  • diagnosticProvider.ts - Syntax validation and error reporting
  • syntaxValidator.ts - ASHES syntax validation logic

2. Dependencies

TR-2.1: External Dependencies

• The extension MUST use minimal external dependencies
• The extension MUST use only VSCode-approved packages
• The extension MUST specify exact version requirements

TR-2.2: Built-in Dependencies

• The extension MUST use Node.js built-in modules (fs, path)
• The extension MUST use VSCode API modules appropriately

3. Configuration

TR-3.1: Project Configuration

• The extension MUST read configuration from project.godot files
• The extension MUST support the Escoria framework configuration format
• The extension MUST provide sensible defaults when configuration is missing

TR-3.2: Extension Configuration

• The extension MUST use VSCode's configuration system appropriately
• The extension MUST not require user configuration for basic functionality

4. File Handling

TR-4.1: File System Operations

• The extension MUST handle file system operations asynchronously where possible
• The extension MUST handle file permission errors gracefully
• The extension MUST support different file system encodings

TR-4.2: Path Handling

• The extension MUST handle both relative and absolute paths correctly
• The extension MUST convert res:// paths to filesystem paths appropriately
• The extension MUST handle different operating system path separators

Integration Requirements

1. Escoria Framework Integration

IR-1.1: Command Compatibility

• The extension MUST support all standard Escoria commands
• The extension MUST work with custom command implementations
• The extension MUST handle command parameter variations correctly

IR-1.2: Project Structure Support

• The extension MUST work with standard Escoria project structures
• The extension MUST support multiple command directories
• The extension MUST handle addon-based command extensions

2. VSCode Integration

IR-2.1: Language Features

• The extension MUST integrate with VSCode's language features system
• The extension MUST provide proper language configuration
• The extension MUST support VSCode's IntelliSense system

IR-2.2: UI Integration

• The extension MUST integrate with VSCode's command palette
• The extension MUST provide webview panels for command reference
• The extension MUST use VSCode's diagnostic system for error reporting

Quality Assurance Requirements

1. Testing

QA-1.1: Unit Testing

• The extension MUST have unit tests for core functionality
• The extension MUST test command parsing logic
• The extension MUST test syntax validation rules

QA-1.2: Integration Testing

• The extension MUST be tested with real ASHES files
• The extension MUST be tested with various project configurations
• The extension MUST be tested with different VSCode versions

2. Documentation

QA-2.1: User Documentation

• The extension MUST provide comprehensive user documentation
• The extension MUST include installation and configuration instructions
• The extension MUST provide examples and tutorials

QA-2.2: Developer Documentation

• The extension MUST have clear code documentation
• The extension MUST include API documentation
• The extension MUST provide contribution guidelines

3. Error Reporting

QA-3.1: Error Messages

• The extension MUST provide clear and actionable error messages
• The extension MUST include error codes for diagnostic purposes
• The extension MUST suggest solutions for common problems

QA-3.2: Logging

• The extension MUST provide appropriate logging for debugging
• The extension MUST not log sensitive information
• The extension MUST use VSCode's logging system appropriately

Security Requirements

1. File System Security

SR-1.1: Path Validation

• The extension MUST validate file paths to prevent directory traversal
• The extension MUST handle malicious file names appropriately
• The extension MUST not execute arbitrary code from files

SR-1.2: Content Validation

• The extension MUST validate file content before processing
• The extension MUST handle malformed files gracefully
• The extension MUST not expose sensitive file content

2. User Data Protection

SR-2.1: Privacy

• The extension MUST not collect or transmit user data
• The extension MUST not access files outside the workspace
• The extension MUST respect user privacy settings

Deployment Requirements

1. Packaging

DR-1.1: Extension Package

• The extension MUST be packaged as a standard VSCode extension
• The extension MUST include all necessary files and dependencies
• The extension MUST have proper version information

DR-1.2: Installation

• The extension MUST be installable via VSCode's extension system
• The extension MUST not require additional system dependencies
• The extension MUST provide clear installation instructions

2. Distribution

DR-2.1: Version Management

• The extension MUST follow semantic versioning
• The extension MUST provide clear release notes
• The extension MUST support automatic updates

DR-2.2: Compatibility

• The extension MUST maintain backward compatibility where possible
• The extension MUST provide migration guides for breaking changes
• The extension MUST support multiple VSCode versions

Success Criteria

The ASHES Language Support extension will be considered successful when:

1. Functionality: All functional requirements are implemented and working correctly
2. Command Coverage: The extension supports all commands from the three main directories:
   • 60+ core commands from escoria-core
   • 5 UI commands from escoria-ui-return-monkey-island
   • 3 dialog commands from escoria-ui-return-monkey-island-dialog-simple
3. Performance: The extension provides responsive IntelliSense and validation without impacting VSCode performance
4. Usability: Users can effectively develop ASHES scripts with improved productivity
5. Reliability: The extension works consistently across different projects and configurations
6. Integration: The extension integrates seamlessly with the Escoria framework and VSCode
7. Quality: The extension provides accurate syntax validation and helpful error messages based on actual ASHES language specifications
8. Documentation: Users can easily understand and use all extension features
9. Language Compliance: The extension correctly implements all ASHES language features as specified in the Escoria core documentation

Future Enhancements

While not part of the current requirements, potential future enhancements include:

1. Language Server Protocol: Full LSP implementation for advanced language features
2. Debugging Support: Integration with ASHES debugging capabilities
3. Refactoring Tools: Code refactoring and restructuring features
4. Project Templates: ASHES project templates and scaffolding
5. Advanced Validation: More sophisticated semantic analysis and validation
6. Performance Profiling: Tools for analyzing ASHES script performance
7. Collaboration Features: Real-time collaboration support for ASHES development