minecraft-datapack-language 17.0.10__py3-none-any.whl → 17.0.12__py3-none-any.whl

minecraft_datapack_language/_embedded/docs/_docs/vscode-extension.md

@@ -0,0 +1,381 @@
+---
+layout: page
+title: VS Code Extension
+permalink: /docs/vscode-extension/
+---
+
+The MDL VS Code extension provides syntax highlighting, error checking, and build commands for `.mdl` files in VS Code, Cursor, and other VS Code-based editors.
+
+## Features
+
+- **Syntax Highlighting**: Color-coded MDL syntax including raw text blocks
+- **Error Checking**: Real-time error checking and validation
+- **Build Commands**: Quick datapack compilation
+- **Workspace Validation**: Check entire projects at once
+- **Raw Text Support**: Special highlighting and snippets for `$!raw` blocks
+
+## Installation
+
+### Option 1: Download from GitHub Releases (Easiest)
+
+The VS Code extension is automatically built and available for download with each release:
+
+1. **Go to [GitHub Releases](https://github.com/aaron777collins/MinecraftDatapackLanguage/releases)**
+2. **Download the latest `.vsix` file** from the release assets
+3. **Install in your editor**:
+   - Open VS Code/Cursor
+   - Go to Extensions (Ctrl+Shift+X)
+   - Click the "..." menu in the Extensions panel
+   - Select "Install from VSIX..."
+   - Choose the downloaded `.vsix` file
+   - Click "Install"
+
+### Option 2: Build from Source
+
+If you want to build the extension yourself:
+
+#### For VS Code/Cursor:
+
+1. **Download the extension**:
+   ```bash
+   # Clone the repository
+   git clone https://github.com/aaron777collins/MinecraftDatapackLanguage.git
+   cd MinecraftDatapackLanguage/vscode-extension
+   
+   # Build the extension
+   npm install
+   npm run compile
+   npm install -g @vscode/vsce
+   vsce package
+   ```
+
+2. **Install in your editor**:
+   - Open VS Code/Cursor
+   - Go to Extensions (Ctrl+Shift+X)
+   - Click the "..." menu in the Extensions panel
+   - Select "Install from VSIX..."
+   - Navigate to `minecraft-datapack-language-0.1.0.vsix`
+   - Click "Install"
+
+#### Alternative: Command Line Installation
+
+```bash
+# Install directly from command line
+code --install-extension minecraft-datapack-language-0.1.0.vsix
+```
+
+### Option 3: Development Installation
+
+For development and testing:
+
+1. **Clone and setup**:
+   ```bash
+   git clone https://github.com/aaron777collins/MinecraftDatapackLanguage.git
+   cd MinecraftDatapackLanguage/vscode-extension
+   npm install
+   npm run compile
+   ```
+
+2. **Launch Extension Development Host**:
+   - Press `F5` in VS Code to launch the extension in a new window
+   - Or use `npm run watch` for continuous compilation
+
+## Quick Start
+
+Once installed, the extension will automatically activate when you open `.mdl` files:
+
+1. **Open any `.mdl` file** - syntax highlighting will activate immediately
+2. **Try the commands** - Press `Ctrl+Shift+P` and type "MDL" to see available commands
+3. **Build a datapack** - Use "MDL: Build current file" to compile your MDL files
+
+## Usage
+
+### Opening MDL Files
+
+1. Open any `.mdl` file in VS Code/Cursor
+2. The extension will automatically activate and provide syntax highlighting
+3. You'll see color-coded syntax for:
+   - Pack declarations
+   - Namespaces
+   - Functions
+   - Comments
+   - Commands
+
+### Syntax Highlighting
+
+The extension highlights the following MDL elements:
+
+- **Pack declarations**: `pack "Name" description "Desc" pack_format 48`
+- **Namespaces**: `namespace "example"`
+- **Functions**: `function namespace:name`
+- **Lifecycle hooks**: `on_load`, `on_tick`
+- **Tags**: `tag function "minecraft:tick":`
+- **Comments**: `# This is a comment`
+- **Commands**: All lines within function blocks
+- **Raw text blocks**: `$!raw` and `raw!$` with special highlighting
+
+### Raw Text Support
+
+The extension provides special support for raw text blocks:
+
+#### Syntax Highlighting
+
+Raw text blocks are highlighted with distinct colors:
+- `$!raw` and `raw!$` keywords are highlighted as special tokens
+- Content inside raw text blocks is highlighted differently from regular MDL code
+- This makes it easy to distinguish raw text from parsed MDL syntax
+
+#### Snippets
+
+Quick snippets for raw text blocks:
+
+1. **Type `raw` and press Tab** - Inserts a complete raw text block:
+   ```mdl
+   $!raw
+       Insert raw text here - this will be inserted directly into the function without parsing
+   raw!$
+   ```
+
+2. **Type `rawfunction` and press Tab** - Inserts an example showing how to use "function" in commands:
+   ```mdl
+   $!raw
+       say "This contains the word function without breaking the parser";
+       say "You can put any text here, including function, if, while, etc.";
+   raw!$
+   ```
+
+#### IntelliSense
+
+The extension provides completion for raw text syntax:
+- `$!raw` completion with snippet that inserts the full block
+- `raw!$` completion for ending blocks
+- Helpful documentation explaining what raw text does
+
+#### Error Checking
+
+Raw text blocks are validated for:
+- Proper opening and closing delimiters
+- Basic syntax checking
+- Integration with the MDL error checker
+
+### Error Checking
+
+The extension provides real-time validation:
+
+1. **Syntax errors**: Invalid MDL syntax is highlighted
+2. **Indentation errors**: Incorrect indentation is flagged
+3. **Missing declarations**: Missing pack declarations are detected
+4. **Duplicate names**: Duplicate function names are identified
+
+**Error indicators:**
+- Red squiggly lines under syntax errors
+- Yellow warnings for potential issues
+- Hover over errors for detailed explanations
+
+### Build Commands
+
+The extension adds several commands to VS Code:
+
+#### MDL: Build current file
+
+Builds the currently open MDL file:
+
+1. Open an `.mdl` file
+2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
+3. Type "MDL: Build current file"
+4. Select the command
+5. Choose an output directory
+6. Optionally specify a wrapper name
+
+#### MDL: Check Workspace
+
+Validates all MDL files in the current workspace:
+
+1. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on macOS)
+2. Type "MDL: Check Workspace"
+3. Select the command
+4. View results in the Problems panel
+
+### Keyboard Shortcuts
+
+You can add custom keyboard shortcuts for the MDL commands:
+
+1. Open VS Code settings (`Ctrl+,`)
+2. Go to "Keyboard Shortcuts"
+3. Search for "MDL"
+4. Add shortcuts for:
+   - `mdl.build` - Build current file
+   - `mdl.checkWorkspace` - Check workspace
+
+**Example shortcuts:**
+```json
+{
+  "key": "ctrl+shift+b",
+  "command": "mdl.build",
+  "when": "resourceExtname == .mdl"
+},
+{
+  "key": "ctrl+shift+c",
+  "command": "mdl.checkWorkspace"
+}
+```
+
+## Configuration
+
+### Extension Settings
+
+The extension can be configured through VS Code settings:
+
+1. Open VS Code settings (`Ctrl+,`)
+2. Search for "MDL"
+3. Configure the following options:
+
+**`mdl.enableLinting`** (default: `true`)
+- Enable or disable real-time error checking
+
+**`mdl.lintingMode`** (default: `"onSave"`)
+- When to run error checking: `"onSave"`, `"onType"`, or `"manual"`
+
+**`mdl.buildOutputDirectory`** (default: `"dist"`)
+- Default output directory for builds
+
+### Workspace Settings
+
+You can configure MDL settings per workspace by creating a `.vscode/settings.json` file:
+
+```json
+{
+  "mdl.enableLinting": true,
+  "mdl.lintingMode": "onSave",
+  "mdl.buildOutputDirectory": "build",
+  "files.associations": {
+    "*.mdl": "mdl"
+  }
+}
+```
+
+## Troubleshooting
+
+### Extension Not Working
+
+1. **Check if MDL is installed**: The extension requires MDL to be installed on your system
+2. **Verify file association**: Make sure `.mdl` files are associated with the MDL language
+3. **Check output panel**: Look for error messages in the Output panel (View → Output → MDL)
+
+### Build Commands Not Available
+
+1. **Ensure MDL is in PATH**: The extension needs to find the `mdl` command
+2. **Restart VS Code**: Sometimes a restart is needed after installation
+3. **Check command palette**: Commands should appear when typing "MDL"
+
+### Error Checking Issues
+
+1. **Check MDL installation**: Run `mdl --version` in terminal to verify installation
+2. **Verify file syntax**: Use `mdl check filename.mdl` to test manually
+3. **Check extension logs**: Look for errors in the Developer Tools (Help → Toggle Developer Tools)
+
+## Development
+
+### Project Structure
+
+```
+vscode-extension/
+├── src/
+│   └── extension.ts          # Main extension code
+├── syntaxes/
+│   └── mdl.tmLanguage.json   # Syntax highlighting rules
+├── language-configuration.json  # Language configuration
+├── package.json              # Extension manifest
+└── tsconfig.json            # TypeScript configuration
+```
+
+### Key Files
+
+**`src/extension.ts`**: Main extension logic
+- Command registration
+- Error checking integration
+- Build command handling
+
+**`syntaxes/mdl.tmLanguage.json`**: Syntax highlighting rules
+- Token definitions
+- Pattern matching
+- Color themes
+
+**`language-configuration.json`**: Language behavior
+- Comment patterns
+- Bracket matching
+- Auto-indentation
+
+### Adding Features
+
+To add new features to the extension:
+
+1. **Modify `extension.ts`**: Add new commands or functionality
+2. **Update `package.json`**: Register new commands
+3. **Test locally**: Use `F5` to test changes
+4. **Build**: Run `npm run compile` to build
+
+### Testing
+
+1. **Unit tests**: Add tests in a `test/` directory
+2. **Integration tests**: Test with real MDL files
+3. **Manual testing**: Test all features in the Extension Development Host
+
+## Contributing
+
+### Development Setup
+
+1. Fork the repository
+2. Clone your fork
+3. Navigate to `vscode-extension/`
+4. Run `npm install`
+5. Make your changes
+6. Test with `F5`
+7. Submit a pull request
+
+### Code Style
+
+- Use TypeScript for all new code
+- Follow VS Code extension conventions
+- Add comments for complex logic
+- Include error handling
+
+### Testing Checklist
+
+Before submitting changes, test:
+
+- [ ] Syntax highlighting works correctly
+- [ ] Error checking catches errors
+- [ ] Build commands work
+- [ ] Workspace validation functions
+- [ ] Error messages are clear
+- [ ] Performance is acceptable
+
+## Future Features
+
+Planned enhancements for the VS Code extension:
+
+- **IntelliSense**: Auto-completion for MDL syntax
+- **Snippets**: Code templates for common patterns
+- **Debugging**: Step-through debugging for MDL files
+- **Multi-file support**: Better handling of multi-file projects
+- **Custom themes**: Additional color themes for MDL
+- **Formatting**: Auto-formatting of MDL files
+- **Refactoring**: Rename functions across files
+- **Search**: Search and replace across MDL files
+
+## Support
+
+If you encounter issues with the VS Code extension:
+
+1. **Check the documentation**: This page and the main README
+2. **Search issues**: Look for similar problems on GitHub
+3. **Create an issue**: Provide detailed information about the problem
+4. **Include logs**: Share relevant error messages and logs
+
+## Related Documentation
+
+- **[Getting Started]({{ site.baseurl }}/docs/getting-started/)** - Installation and first steps
+- **[Language Reference]({{ site.baseurl }}/docs/language-reference/)** - Complete MDL syntax
+- **[CLI Reference]({{ site.baseurl }}/docs/cli-reference/)** - Command-line tools
+- **[Examples]({{ site.baseurl }}/docs/examples/)** - Working examples