12dPL Language Server
A professional language server for 12dPL with intelligent code completion and real-time validation.
This repository’s documentation is split into the following Markdown files:
README.md - General User Information and Features
CONTRIBUTING.md - Developer specific information.
Table of Contents
- Features
- Quick Start Guide
- Usage
- Configuration
- Dependencies
- License
- Contributing
- Contributors
✨ Features
Implemented
- Syntax Highlighting - Full 12dPL grammar support
- Code Completion - Builtins + local symbols + include-aware symbols
- Real-time Validation - ANTLR-based code parsing and error detection
- AST Parsing - Complete abstract syntax tree generation
- Function Documentation - Hover over builtins, local symbols, include symbols, and
#define macros
- Go to Definition - Works for local symbols and across included files (including
#define macros)
- Signature Help - Parameter info tooltip appears as you type, with active parameter highlighted and all overloads shown
- Rename All Symbols - Scope-aware rename across the current file (F2 or right-click > Rename Symbol)
- Formatting - Brace-based formatting with configurable bracket style, indent style, and line-length wrapping (supports format-on-save)
- Preprocessor Support -
#include/#define suggestions, include-path completion, macro completion, and macro expansion during validation
- Advanced Grammar Support - Arrays, Switch statements, Pass-by-reference, Macros
- Document Outline - Functions and global variables shown in the VS Code outline panel and breadcrumb bar
- Semantic Highlighting - Macro definitions and uppercase constants are highlighted distinctly
- Control Flow Validation - Detects unreachable code, missing
break in switch cases, and switch without default
- Assignment Type Validation - Reports type mismatches and lossy promotions in assignments
- Logical Condition Validation - Warns on non-boolean loop/condition expressions
- Array Size Validation - Flags unsized array declarations in function bodies
- Undeclared Symbol Detection - Flags calls to functions not declared locally, in headers, or in built-in prototypes
- Macro Assistant (MCP) - An MCP server for AI chat that looks up functions, checks and compiles macros, and scaffolds new macro projects (see Macro Assistant for AI Chat)
Coming Soon
- Document Highlights: highlights all matching symbols in a text document
- Find References: find all references to a symbol
- List Workspace Symbols: lists all project-wide symbols
What's New in v1.7.0
- Compile Target Pinning (#93): Added a pinned compile target workflow so compile actions can target a selected
.4dm file while you are editing headers. Includes set/clear commands, context menu actions, and status bar integration.
- Unused Local Variable Detection: Added diagnostics for local variables that are declared but never used.
- Dynamic Array Null Reminder (#107): Added a reminder diagnostic for dynamic arrays to surface null-state checks and improve script robustness.
- Docs Website Search Relevance (#126): Improved docs-site search with weighted token and phrase scoring for more accurate results.
- Dynamic Array Declaration Scope: Fixed global declaration handling for dynamic arrays.
- Snippet Completion Duplicates: Removed duplicate completion entries and kept a single maintainable snippet source.
- Stability and Usability Release: focuses on safer validation, improved compile workflow in mixed
.4dm/.h editing sessions, and cleaner completion/search behaviour.
12dPL Macro Assistant for AI Chat (MCP)
- Connects VS Code Chat agents to the 12dPL guides, reference documentation, built-in function lookup, and example macros
- Provides offline macro validation,
cc4d.exe compilation with parsed errors, and project scaffolding
- Supports custom documentation and example folders through
12dpl.mcp.knowledgePaths
- Includes a command to copy the MCP server configuration for clients such as Claude Code and Claude Desktop
- VS Code Chat integration requires VS Code 1.101 or later
Language Server Fixes
- Go-to-label now works for labels at the end of a block
- Function declarations with the opening parenthesis on the next line are handled correctly
🚀 Quick Start Guide
What's New
✨ Auto-Completion with 8000+ Library Functions
The language server provides intelligent auto-completion for all 12dPL library functions including:
- Mathematical functions (Sin, Cos, Tan, etc.)
- String operations
- File I/O
- Control flow
- And much more...
💡 Usage
Auto-Completion
- Open a
.4dm file
- Start typing a function name or variable (Can be user defined) (e.g., "Sin", "Print")
- Auto-complete suggestions appear
- Press
Ctrl+Space to manually trigger

Diagnostics - Error Checking
- Syntax errors appear with red squiggles
- View all errors in the Problems panel
- Navigate with F8 (next problem)

This extension provides a basic C/C++-style formatter (brace-based indentation) for .4dm files.
Format-on-save is disabled by default, if you wish to use this feature it can be enabled in the extensions settings.

This extension can invoke the 12dPL compiler and can compile the current file into a .4do in the same folder.
- Open a
.4dm file
- Click the Play button (
▶ 12dPL) in the VS Code status bar to compile immediately or run “12dPL: Compile Current File” from the Command Palette
- Check the Output panel: 12dPL Compiler
The Output also prints the detected cc4d compiler version, and the Play button tooltip shows it when available.

Compiler Flags (Checkboxes)
To compile with selectable flags, use the Gear button (⚙ 12dPL) in the status bar or run “12dPL: Compile Current File (Select Flags)”.
Set a Compile Target (Pin a File)
When working in header files you can pin a .4dm file as the compile target, so the Play button and compile commands always build that file without switching back to it:
- Right-click a
.4dm file in the Explorer or editor and select “12dPL: Set as Compile Target”
- The Play button shows the pinned file name (
▶ 12dPL: macro.4dm) and stays available while editing .h files
- All dirty
.4dm/.h files are saved before compiling, so header edits are always included
- Right-click a file explicitly and choosing “12dPL: Compile Current File” still compiles that specific file
To go back to compiling the active file, run “12dPL: Clear Compile Target” (also in the right-click menu while a target is set). The target is remembered per workspace.
Macro Assistant for AI Chat (MCP)
The extension includes the 12dPL Macro Assistant, an MCP server that gives AI agents in chat (such as GitHub Copilot in agent mode) what they need to write 12dPL macros that compile and run. It needs VS Code 1.101 or later, which starts it from the extension with no extra setup.
| Tool |
What it does |
get_macro_guide |
Rules and patterns by topic: essentials, workflow, panels, attributes, elements, signatures, conventions, compiler, files |
lookup_function |
Signatures and overloads of built-in functions, with the gotchas recorded for them |
search_functions |
Finds built-in functions by name fragment or purpose |
search_knowledge, read_knowledge |
Search and read the macro guides and the 12dPL reference docs |
find_examples, read_example |
Search the example macros in your knowledge folders |
validate_macro |
The language server's checks, plus mistakes that compile cleanly but crash 12d Model (&& guards that do not short-circuit, inline ternaries in +, held element handles, and more) |
compile_macro |
Compiles with cc4d.exe and returns the parsed errors |
scaffold_macro |
Creates a compilable macro project: headless, panel, Source_Box panel or tabbed panel |
It also provides the create_macro and review_macro prompts, and serves each guide and doc as an MCP resource.
Add your own knowledge: list folders in 12dpl.mcp.knowledgePaths, for example a macro workspace with a docs/ folder and example macros. Markdown files become searchable docs, .4dm/.h files become examples, and a root CLAUDE.md or docs/*.md replaces the bundled copy.
Other MCP clients (Claude Code, Claude Desktop): run “12dPL: Copy MCP Server Configuration” and paste the result into the client's MCP configuration. The path includes the extension version, so copy it again after the extension updates.
🔧 Configuration
There are a few available settings that are defined for the language server that can be used to customise the way the language server behaves. They are listed below with a description of their use.
- 12dpl.compiler.availableFlags
- List of cc4d compiler flags to show as checkboxes when compiling. Each entry may include arguments, e.g. '-log "build.log"' or '-codepage 1252'.
- 12dpl.compiler.path
- Path to the folder containing the cc4d.exe compiler. Example: C:\Program Files\12d\12dmodel\15.00\nt.x64\
- 12dpl.compiler.includePaths
- List of folders to prepend to the PATH environment variable before running the compiler (useful for include directories). Use platform paths; on Windows use semicolon-separated PATH semantics.
- 12dpl.compiler.defaultFlags
- Default cc4d flags to preselect in the compile checkbox picker. Last selection is remembered per-workspace.
- 12dpl.formatOnSave
- Auto-format 12dPL files when they are saved.
- 12dpl.indentSize
- Indent size (spaces) used by the 12dPL formatter.
- 12dpl.mcp.enabled
- Offer the 12dPL Macro Assistant MCP server to chat in VS Code. It uses the
12dpl.compiler.* settings when compiling.
- 12dpl.mcp.knowledgePaths
- Extra folders for the Macro Assistant to learn from (docs and example macros). Supports
${workspaceFolder} and ${userHome}.
- langServer.maxNumberOfProblems
- Controls the maximum number of problems produced by the server.
- langServer.trace.server
- Traces the communication between VS Code and the language server.
📦 Dependencies
Core
vscode-languageserver - LSP implementation
vscode-languageserver-textdocument - Text document handling
antlr4 - Parser generation
Data
xml2js - XML parsing for prototypes
📄 License
MIT License - See LICENSE file for details
👥 Contributing
Contributions welcome! Please submit pull requests or issues.
👤 Contributors
Ben Olsen
Kamal Jarada
Thanks to everyone helping to improve the extension by reporting bugs and suggesting features: