Using the Dev Tool

What is the dev tool?

The RPG Companion App dev tool is a build system and local server that:

• Compiles your .rpgs and .json source files into the .rpg binary format the app uses.
• Serves your compiled output over Wi-Fi so the app's Developer Mode can pull from it during development.
• Packages your system for hosting when you're ready to publish.
• Exposes an MCP server so AI assistants (Claude, Cursor, etc.) can understand your system schema and help you build it.

There are two ways to access the dev tool: through the VS Code extension (recommended, bundles the dev tool automatically) or by downloading and running the standalone desktop app (available for Mac and Windows).

---

Option 1 — VS Code Extension (Recommended)

The RPGScript VS Code Extension bundles everything you need. No Dart installation required on Mac (Apple Silicon) — pre-compiled binaries are included.

Installation

1. Open VS Code.
2. Go to the Extensions panel (Cmd+Shift+X).
3. Search for RPGScript.
4. Install the extension by BlastervlaEnterprisesLLC.

Configuration

Open VS Code settings (Cmd+,) and search for rpgscript. The key settings are:

Setting	Description
rpgscript.devTool.systemsBasePath	The folder containing your system directories (e.g. the systems/ folder). Required.
rpgscript.devTool.outputPath	Where compiled output is written. Required.
rpgscript.devTool.autoBuildOnFileChange	Auto-rebuild when you save a file (default: false).
rpgscript.devTool.servePort	Port for the output server (default: 9090).

If you have a local clone of the dev tool and prefer to run it with Dart, set rpgscript.devTool.path to its location. Otherwise, the bundled binaries are used automatically.

---

Language Intelligence

The extension provides full IntelliSense for .rpgs files:

• Autocompletion — stat types, resource types, function names, enum values, lambda variables, effect names, view names — all from your actual system definition.
• Hover documentation — hover over any function call, keyword, or stat reference to see its documentation inline.
• Go to Definition — Ctrl+Click any stat reference to jump to its declaration, across the whole system (not just the current file).
• Find All References — see everywhere a stat is used.
• Real-time diagnostics — red squiggles for unknown resource types, missing name metadata, unbalanced brackets, and other issues. Errors also appear in the Problems panel (Cmd+Shift+M).
• Auto-formatting — format any .rpgs file with Shift+Option+F (Mac) or Shift+Alt+F (Windows/Linux).

---

Dev Tool Commands

Access all commands via the Command Palette (Cmd+Shift+P) — search RPGScript:

RPGScript: Build Systems (Dev Tool)

Compiles your source files into the output folder. Errors and warnings appear in VS Code's Problems panel.

Use this for a one-off build, or enable Auto Build (below) to have it happen automatically.

RPGScript: Toggle Auto Build (Dev Tool)

Toggles automatic rebuild on file save. A status bar item in the bottom-left corner shows the current state (idle, building, failed, queued).

When enabled, the extension watches your systems folder and triggers a rebuild ~1.2 seconds after you stop making changes. File saves in the output folder are ignored to avoid loops.

RPGScript: Start / Stop Output Server (Dev Tool)

Starts a local HTTP server hosting your compiled output over Wi-Fi.

Once running, open the RPG Companion App in Developer Mode (toggle in app settings) and refresh your systems — the app will pull from your dev server instead of the internet. Both your computer and your phone must be on the same Wi-Fi network.

RPGScript: Start / Stop MCP Server (Dev Tool)

Starts the MCP server that exposes your system's schema and content to AI assistants. See MCP Server for AI Development below.

RPGScript: Install MCP Config (Dev Tool)

Automatically writes the MCP server configuration into your AI client's config file. Choose from:

• Claude Desktop — writes to ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor — writes to ~/.cursor/mcp.json
• VS Code workspace — writes to .vscode/mcp.json
• Clipboard — copies the config snippet for manual pasting

The command merges into existing config rather than overwriting it.

RPGScript: Format Document

Formats the current .rpgs file. Equivalent to Shift+Option+F.

---

MCP Server for AI Development

The dev tool ships an MCP (Model Context Protocol) server that lets AI assistants understand your system deeply. Once connected, you can ask Claude (or any MCP-compatible AI) to:

• Help write .rpgs formulas for new stats.
• Debug why a mechanic isn't triggering correctly.
• Suggest stat structures and resource types for a given game rule.
• Review and improve your system definitions.

Getting started:

1. Run RPGScript: Start MCP Server (Dev Tool) from the Command Palette.
2. Run RPGScript: Install MCP Config (Dev Tool) and choose your AI client (e.g. Claude Desktop or Cursor).
3. Restart your AI client — it will now have full context about your system when you chat.

---

Option 2 — Standalone Dev Tool App

If you prefer not to use VS Code, you can download the RPG Companion App dev tool directly from rpg-companion.app/dev. It's a native desktop application available for Mac and Windows (Linux is not supported).

It provides the same build, serve, and package capabilities through a simple UI.

Note: The standalone app does not include Language Intelligence, editor diagnostics, or MCP server support. Those are only available through the VS Code extension.

Select Input Folder

Select the folder containing your systems (the systems/ folder). The tool will watch it and auto-rebuild when files change.

Build now

Manually trigger a rebuild. Wait for the ✅ Build complete message before refreshing the app.

Start / Stop Server

Hosts your compiled output over Wi-Fi. Once running, the app in Developer Mode will pull from this server. Both devices must be on the same Wi-Fi network.

Open in Browser

Browse the hosted folder structure. Useful to verify the server is reachable if the app can't connect.

Clear Output

Clears the working output directory. Does not touch your source files.

Create Release Package

Generates the final output folder for hosting. Upload the contents of this folder to any CDN (AWS S3, CloudFront, GitHub Pages, etc.) to share your system publicly. See Hosting a Resource Pack for the full step-by-step guide.