RPGScript Language Support

RPGScript is the official Visual Studio Code extension for developing TTRPG systems compatible with the RPG Companion App. Documentation for the language can be found here

It provides robust syntax highlighting and tooling for RPGScript (.rpgs), making it easier to define Stats, Mechanics, Effects, and Resources for your custom tabletop systems.

✨ Features

🎨 Rich Syntax Highlighting

Write .rpgs files with confidence. The extension provides distinct colorization for:

• Primitive Types: integer, decimal, string, boolean, resource.
• Complex Nested Types: recursive support for generics like list<string> or list<resource<background>>.
• Type Parameters: Distinguishes between the container type (e.g., list) and the inner parameter types for better readability.
• Arrays: Clear definitions for array structures [].

🚀 Upcoming Features (Roadmap)

We are actively working on a full Language Server Protocol (LSP) implementation to bring you:

• [ ] IntelliSense: Auto-completion for keywords, variables, and known resource types.
• [ ] Go to Definition: Jump instantly to where a resource or stat is defined.
• [ ] Error Reporting: Catch type mismatches and syntax errors before you build.
• [ ] Hover Information: See documentation and details by hovering over types.
• [ ] Auto Formatting: Keep your code neat and clean with the help of the IDE.

📝 Code Example

Enjoy clean, readable code for your system definitions:

// Here goes a comment!
base string subrace_id(name = "Subrace ID") = null;

calc resource<feat>[] racial_traits(name = "Racial traits") =
  sortBy(
    filter(
      flatAppend([race.traits, (race.selected_subrace?.traits ?? [])]),
      filter = ($filterValue) => ($filterValue.min_level <= level),
    ),
    order = "asc",
    sort_by_selector = $sortByValue.min_level,
  );

Dev Tool Commands + MCP

The extension now includes command palette actions to drive the RPG Companion dev_tool shell utilities and help install MCP config.

Open the command palette and run:

• RPGScript: Build Systems (Dev Tool)
• RPGScript: Start Output Server (Dev Tool)
• RPGScript: Stop Output Server (Dev Tool)
• RPGScript: Start MCP Server (Dev Tool)
• RPGScript: Stop MCP Server (Dev Tool)
• RPGScript: Install MCP Config (Dev Tool)
• RPGScript: Toggle Auto Build (Dev Tool)

Required setup

• Preferred (works out of the box): use bundled binaries shipped with the extension.
• Fallback mode: install dart, then set rpgscript.devTool.path to your local dev_tool repository.

Optional settings:

• rpgscript.devTool.systemsBasePath
• rpgscript.devTool.outputPath
• rpgscript.devTool.servePort
• rpgscript.devTool.devBuild
• rpgscript.devTool.cleanOnBuild
• rpgscript.devTool.dartCommand
• rpgscript.devTool.preferBundledTools
• rpgscript.devTool.autoBuildOnFileChange
• rpgscript.devTool.autoBuildDebounceMs
• rpgscript.devTool.useEmojiLogs

Install MCP Config (Dev Tool) can copy a snippet to your clipboard or write directly to supported config files. When bundled binaries are present, the generated MCP config points directly to the bundled mcp_dev_tool_server executable.

Bundled platform support

• darwin-arm64: bundled binaries included.
• Other platforms: extension falls back to external dart tools unless bundled binaries are added for that platform.

Maintainer release script

Use this script to (re)build bundled binaries:

npm run bundle-dev-tools

Useful options:

# specific targets only
bash scripts/build-bundled-tools.sh --targets darwin-arm64,linux-x64

# custom dev_tool path
bash scripts/build-bundled-tools.sh --dev-tool-path /path/to/RPGCompanionApp/dev_tool

Supported targets:

• darwin-arm64
• darwin-x64
• linux-arm64
• linux-x64
• win32-arm64
• win32-x64