sKSP for VS Code

Compile SublimeKSP projects directly from VS Code, with sKSP syntax highlighting, function navigation, project-aware compilation, and compiler updates.

The extension uses the real SublimeKSP compiler. It includes a compiler for offline use. Sublime Text is not required.

Requirements

• VS Code 1.95 or later.
• A local project folder.
• Python available as python3, or a Python executable configured in sKSP: Python Path. Python 3.10 or later is recommended.

You do not need Node.js, npm, or additional Python packages to use the extension. Only compile source you trust: sKSP scripts can execute embedded Python.

Install from a VSIX

1. Open Extensions in VS Code.
2. Open the ... menu and choose Install from VSIX....
3. Select the downloaded .vsix file, not the extension's source folder.
4. Run Developer: Reload Window from the Command Palette.

Quick start

1. Open your KSP project folder in VS Code.
2. Open any .ksp file in the project.
3. Save changes to imported files.
4. Press Cmd+Shift+K on macOS, or Ctrl+Shift+K on Windows/Linux. You can also run sKSP: Compile Project from the Command Palette.
5. On first use, select the project's main script. This is usually the file containing on init. The extension remembers your selection.

After that, compile while editing any fragment: the command compiles the project's main script, not just the file in the editor. A notification confirms success or reports a compilation error.

Projects and entry points

Each workspace folder has its own entry point. In a multi-root workspace, the active KSP file selects the project to compile. If the file is outside the workspace, or the active editor is not a KSP file, a project picker appears.

The status bar shows the active project and entry point. Click it to compile. To change the main script, run sKSP: Select Project Entry Point.

The selection is saved in that project's folder settings:

{
  "sksp.entryPoint": "src/main.ksp"
}

Files containing on init appear first in the entry-point picker, but are never selected automatically: standalone tests may contain on init too.

Where compiled code goes

Clipboard

If the script has no output pragma, compiled code is copied to your clipboard, ready to paste into Kontakt.

Output files

To write a file instead, add an output pragma to the main script:

{ #pragma save_compiled_source ../compiled/main.txt }

The path is relative to the main script's directory. Create the destination directory before compiling. Output is written using Latin-1 encoding.

When output paths are specified, the extension writes those files instead of copying code to the clipboard. Multiple output pragmas are supported.

Commands

Open the Command Palette and search for sKSP.

Function navigation

Hover over a user-defined function name to see its declaration and source file. Cmd+click on macOS, Ctrl+click on Windows/Linux, or press F12 to jump to the definition. Right-click and choose Go to Definition also works. VS Code's mouse-modifier settings may change the click modifier.

Navigation supports function, taskfunc, and macro declarations, including dotted names such as fn027_sounds.recall_ui_props_data. You can navigate from call statements, ordinary calls, and expressions inside f-strings.

Definitions are searched within the active file's workspace folder, so another open project's matching function will not be selected. No compilation or entry-point selection is needed. Outside a workspace folder, only the current file is searched. Unsaved editor changes are included.

If several definitions match, VS Code presents the available locations. This is source navigation, not compiler expansion: it does not resolve import aliases or generated function names, evaluate conditional compilation, or restrict results to imports of the configured entry point. Built-ins without a source declaration in the project do not have a navigation target.

Saving changes

The main script is compiled from its current editor contents, including unsaved changes. Imported files are read from disk, just as in Sublime Text, so save edited imports before compiling.

Imports and output paths are resolved relative to the main script, not the file you happen to be editing or the terminal's working directory.

Errors and compilation output

Compilation errors appear in Problems and navigate to the original source line, including errors inside imported files.

For full details, open View > Output and select sKSP. The output shows the entry point, compiler version, compilation errors, and saved output paths.

Compilations can be cancelled from the progress notification. Only one compilation runs at a time in each VS Code window.

Syntax highlighting and file associations

The extension recognizes .ksp, .b3s, and .nbsc files. Highlighting comes from SublimeKSP's syntax definitions; your VS Code theme determines the colors.

For .ksp files, the language indicator at the bottom right should say sKSP. If another extension, such as cKSP Tools, has claimed the file:

1. Click the language indicator.
2. Choose Configure File Association for '.ksp'....
3. Select sKSP.

Alternatively, merge this into your workspace or user settings:

{
  "files.associations": {
    "*.ksp": "sksp"
  }
}

The compile shortcut is enabled only while the editor's language is sKSP.

Compiler settings

Open Extensions, find sKSP for VS Code, and choose Extension Settings from its gear menu.

Defaults match Sublime:

• Extra syntax checks, exit sanitization, and the compilation timestamp are on.
• Code optimization, callback combining, and compaction are off.
• Compiled code uses two-space indentation.

Compiler options can be set per workspace folder. Source pragmas retain their normal precedence. Set sKSP: Python Path to the Python executable you want to use; this is separate from the interpreter selected by VS Code's Python extension.

Compiler updates

The extension checks for stable releases from nojanath/SublimeKSP when it activates and every six hours while active.

• New versions are installed only after you choose Update.
• Updates are validated before the compiler is switched.
• Downloads never change an existing SublimeKSP checkout.
• Compilation continues to work offline with the installed compiler.
• Use sKSP: Roll Back Compiler if an update causes problems.

After an update or rollback, reload the window when prompted to apply the matching syntax highlighting. If the installed extension directory is read-only, the update fails explicitly instead of switching the compiler.

Troubleshooting

• The shortcut does not compile: check that the language indicator says sKSP, or run sKSP: Compile Project from the Command Palette.
• The wrong script is compiled: run sKSP: Select Project Entry Point while editing a file in the intended project.
• An imported edit is missing: save the imported file, then compile again.
• Python cannot be started: configure sKSP: Python Path with a valid executable path.
• An output file cannot be written: check the pragma path, destination directory, permissions, and Latin-1 compatibility.
• Compilation is unavailable in Restricted Mode: trust the workspace only if you trust its source code. Virtual workspaces are not supported.

Credits and license

Powered by SublimeKSP. This extension and its bundled compiler retain their applicable GPL license notices.