Q-SYS Plugin Toolkit

A VS Code extension for Q-SYS plugin work:

• Scaffold a .qplug plugin from a working template.
• Validate a .qplug against the documented Q-SYS plugin surface.
• Install a plugin into the folder Q-SYS Designer reads.
• Preview a Q-SYS design (.qsys) in VS Code so you can see what is in it.
• Deploy Lua to a running Core or Designer emulator over QRC.

Features

New Plugin

Q-SYS Plugin: New Plugin… asks for a name, author, and description, then writes a complete, valid .qplug next to your other plugin sources and opens it. The template contains the required PluginInfo header, the design-time functions QDS calls (GetPrettyName, GetColor, GetProperties, RectifyProperties, GetControls, GetControlLayout), a gain knob and a mute toggle, and a run-time block guarded by if Controls then … end.

Validate Plugin

Q-SYS Plugin: Validate Plugin (also on the editor title bar and on save) reports:

• missing required PluginInfo fields and unknown ones,
• unknown fields in the property, control, layout, and graphics tables,
• values that are not documented for fixed-set fields such as ControlType, PinStyle, ControlUnit, Style, and Type,
• missing required reserved functions, and names close to a reserved function (a misspelled GetControlLayout, for example).

The check follows the documented surface transcribed from the Q-SYS Help topics Basic Plugin Framework, Reserved Functions, Reserved Control Names, Plugin Property Headers and Comments, Dynamic Pages, and Embedded Components. Your own control and property names are never reported. It is not a Lua interpreter: it reads PluginInfo, reserved functions (including Name = function(...)), and design-time tables written with table.insert, t[#t+1] = {, return { { ... } }, or layout["Name"] / layout.Name. Compiled .qplugx packages are not Lua source and are not validated.

While you type, the extension offers documented field names, enum values (ControlType, Style, Type, …), reserved functions, and a few table snippets in .qplug files. In .lua Control Scripts it completes and hovers the runtime API (Controls, Timer, NamedControl, Component, HttpClient, TcpSocket, ChannelGroup).

Keyboard shortcuts (when a .qplug editor is focused):

Install Plugin into Q-SYS Designer

Q-SYS Plugin: Install Plugin into Q-SYS Designer copies the active .qplug (or a compiled .qplugx / .qplugx2) into the plugin folder by file name and asks before replacing a file that is already there. Q-SYS Designer reads plugins from:

Set qsysPluginToolkit.pluginsDirectory if your Documents folder is redirected (for example to OneDrive). Restart Q-SYS Designer after installing; the plugin then appears under Schematic Elements > Plugins. If a plugin with the same PluginInfo.Id is already in that folder under a different file name, the command offers to replace that file. Otherwise it copies by file name and asks before overwriting.

To install a plugin by hand:

1. Run Q-SYS Plugin: Validate Plugin and fix anything it reports.
2. Run Q-SYS Plugin: Install Plugin into Q-SYS Designer.
3. Restart Q-SYS Designer and drag the plugin from Schematic Elements > Plugins.

Q-SYS Plugin: Open Q-SYS Plugins Folder reveals the folder in your file manager.

Deploy Lua to a Core or Designer emulator

Q-SYS Plugin: Deploy Lua to Q-SYS Core… pushes the open .lua or .qplug over QRC (TCP port 1710) onto a running Core or a Q-SYS Designer emulation on 127.0.0.1. Lua files set the component code control; .qplug files set plugin_source.

The target component must have Script Access set to External or All, and you pick it by its Code Name. The last Core and component used for a file are remembered; the next deploy skips those pickers. Use Q-SYS Plugin: Deploy Lua to Q-SYS Core (choose target)… to pick again. If the Core requires External Control Protocol credentials, set them on qsysPluginToolkit.cores (the password is stored in settings as plain text).

{
  "qsysPluginToolkit.cores": [
    { "name": "Designer Emulator", "host": "127.0.0.1" },
    {
      "name": "Lab Core",
      "host": "192.168.1.50",
      "username": "admin",
      "password": "1234"
    }
  ]
}

Preview Q-SYS Design

Q-SYS designs are binary, so VS Code shows nothing useful for a .qsys file. The Q-SYS Design Preview editor decodes the design and shows:

• the design name, author/version when stored, component count, and wire count,
• the plugin instances the design uses, with their scripts called out,
• every component grouped by type, with its properties,
• the connections, as source:port → target:port.

Stored Lua (plugin_source, Script code) can be opened from the preview into a read-only editor tab. The page refreshes when the .qsys file changes on disk.

Open it with Q-SYS Plugin: Preview Q-SYS Design, from the Explorer or editor title context menu, or Open With… → Q-SYS Design Preview. The preview is read-only and registered as an option, so Qscope keeps the default editor for .qsys when both are installed.

Support

The source repository is private. For product questions use quantforge.software.

0.x of this extension is free. From 1.0, Install, design preview, and Core deploy use a 14-day trial and then a license key (Q-SYS Plugin: Enter License Key…). Scaffold and validate stay free.

The project is dual-licensed. The free tier (scaffold, validate, completions) is source-available under LICENSE-FREE-CORE; the Pro features are licensed under the end user agreement in LICENSE-PRO-EULA. The vendored .qsys decoder stays MIT (LICENSE.THIRD-PARTY). See LICENSE for the summary.

Installation

Install from the VS Code Marketplace (search for Q-SYS Plugin Toolkit), or:

code --install-extension QuantForgeSoftware.qsys-plugin-toolkit

From a local package:

npm run package
code --install-extension qsys-plugin-toolkit-<version>.vsix --force

Make .qplug files look like Lua

.qplug files use the Lua language id automatically. Install a Lua grammar extension for syntax highlighting — Lua (sumneko) is a common choice. Validation and completions in this extension work either way.

If a workspace overrode that association, Q-SYS Plugin: Associate .qplug with Lua writes:

{
  "files.associations": {
    "*.qplug": "lua"
  }
}

Settings

Development

Node.js 20 or newer is required.

npm ci
npm run check
npm run format:check
npm test
npm run test:coverage
npm run package

npm run package runs every gate and creates qsys-plugin-toolkit-<version>.vsix. Press F5 in VS Code to run an Extension Development Host.

Attribution

The .qsys decoder in src/design/ is vendored from Qscope (parser/binaryFormatter.ts, parser/qysDesignReader.ts, parser/graph.ts, parser/designLua.ts), MIT licensed, so the preview reads the same design model the Qscope viewer does.

License

Dual-licensed. The free tier (scaffold, validate, completions) is source-available under LICENSE-FREE-CORE; the Pro features (install, design preview, Core deploy) are licensed under LICENSE-PRO-EULA. The .qsys decoder vendored in src/design/ stays MIT (LICENSE.THIRD-PARTY). LICENSE summarizes which files fall under which terms. These are source-available licenses, not open source licenses. Q-SYS and QSC are trademarks of QSC, LLC. This project is not affiliated with or endorsed by QSC.

Maintained by John Baima at Quant Forge Software.