Spin2 Extension:
VSCode support for the Propeller languages: Spin2 and Pasm2 for the Parallax Inc. Propeller 2 P2 or P2X8C4M64P, along with Spin and Pasm support for the Propeller 1 P1 or P8X32A.
The P2 and P1 communities thrive in the P2 Forums and the P1 Forums
The P2 Forum Thread containing discussion of this VSCode support
The P1 Forum Thread containing discussion of this VSCode support
The Spin2 Document Formatter now ships with more conservative case defaults: block names and types are uppercase, user constants are uppercase, and control flow, methods, and PASM instructions are preserve (left as-is). See the Formatter User Guide for all options and examples.
Full source code formatter for .spin2 files with section-aware column alignment (CON, VAR, OBJ, DAT), method body indentation normalization, PASM instruction alignment, six independent keyword case controls, and trailing comment alignment. The formatter is provably safe — tested by compiling before and after formatting and verifying the binary output is byte-for-byte identical.
Enable it in settings with spinExtension.formatter.enable: true. Click the status bar indicator ("Spin2 Spaces: 2", "Spin2 Prop Tool", etc.) to switch between spaces, tabs, or elastic tabstop profiles.
- Install the extension by searching for "spin2" in the VSCode Extensions panel.
- Select a theme. After installation, the extension page opens automatically. Choose one of the Spin2 color themes from there before going further — this ensures your syntax highlighting looks right from the start.
- Open a
.spin2or.spinfile. The language server starts automatically and gives you syntax highlighting, error checking, hovers, and signature help. - Set your top-level file. In your workspace
.vscode/settings.json, add"spin2.fNameTopLevel": "your_main_file.spin2"so the extension can discover your full object tree. - Compile with
Ctrl+Shift+B(Cmd+Shift+B on macOS). The extension auto-detects installed compilers (FlexSpin, PNut-TS, PNut on Windows). - Download with
F10(RAM) orF11(FLASH). Use the Status Bar controls to toggle debug mode and select your PropPlug.
For platform-specific setup, see the guides for Windows, macOS, or Raspberry Pi.
Full language server based support for Spin2 and Pasm2 on the Parallax Propeller 2.
- Syntax and Semantic Highlighting — rich, context-aware coloring for Spin2 and Pasm2, including Streamer and Smart-pin symbols as well as all
debug()display types with parameter validation - Error Detection — parse errors are reported as you work. Install the Error Lens extension to see errors inline on the offending line.
- Show Hovers — hover over any symbol to see its type, value, and documentation, including symbols defined in external object files
- Autocomplete / IntelliSense — context-aware code completion with dot-triggered suggestions for object methods/constants and struct fields, general completion for local/global symbols and built-ins, and full documentation resolve
- Signature Help — as you type a method call, see its parameters and types for both user-written and built-in methods
- Code Folding — collapse and expand CON, VAR, OBJ, PUB, PRI, and DAT sections
- Go to Definition (
F12/Ctrl+Click) — jump to where any symbol is declared, including across object files - Find All References (
Shift+F12) — find every use of a symbol across your entire project - Workspace Symbol Search (
Ctrl+T) — search for any global symbol across all files by name - Rename Symbol (
F2) — safely rename a symbol everywhere it appears, with scope awareness and author-file protection - Go to Type Definition — navigate from a STRUCT instance to its type definition
- Document Links —
Ctrl+Clickon quoted filenames in OBJ sections and#includedirectives (FlexSpin) to open the referenced file - Document Highlight — click on any symbol to see all occurrences in the current file highlighted
- Outline View — browse the structure of the current file from the sidebar
- Object Hierarchy View — see your project's full object tree and navigate between files
- Doc-Comment Generation (
Ctrl+Alt+C) — insert a documentation comment template below a PUB or PRI method - Object Public Interface Documentation (
Ctrl+Alt+D) — generate a public interface document with PUB methods, constants, and structures (mark CON blocks with{Spin2_Doc_CON}to include them), displayed in a side panel - Object Hierarchy Report (
Ctrl+Alt+R) — generate a project hierarchy report, displayed in a side panel - Project Archive — generate a ZIP archive containing all source files needed to compile the top-level file, with a
_README_.txtshowing the project name, timestamp, and object hierarchy tree (command: "Spin2: Archive Project")
- Document Formatter — section-aware source code formatting for
.spin2files with column alignment (CON, VAR, OBJ, DAT), method body indentation normalization, inline PASM alignment, six independent keyword case controls (blockNameCase,controlFlowCase,methodCase,typeCase,constantCase,pasmInstructionCase), trailing comment alignment, and format-on-save support. Preserves block comments, string literals, debug() content, and preprocessor directives. Status bar indicator shows active whitespace mode; click to switch between spaces, tabs, or elastic tabstop profiles. - Scope Nesting Guides — color-coded vertical lines in PUB/PRI method bodies showing nesting depth, with L-shaped closers and active-scope highlighting
- Screen Coloring — per-section background coloring à la Parallax Propeller Tool
- Elastic Tabstops — custom tab-stop support per section à la Propeller Tool, with selectable tab sets (
Propeller Tool,IronSheep, orUser1) - Edit Modes — Insert, Overtype, and Align modes à la Propeller Tool
- Color Themes — companion themes for use with or without colored backgrounds
- Compiler auto-detection — supports FlexSpin, PNut-TS, and PNut (Windows only)
- Downloader/debugger auto-detection — supports loadp2 (FlexProp), PNut-TS (built-in loader), and PNut-Term-TS (debug terminal with loader)
- Include path auto-discovery — the extension scans your project and configures include paths for both the compiler and language server
- Status Bar controls — toggle debug compilation on/off, switch between RAM and FLASH download, and select your PropPlug
- Per-workspace settings — choose the default compiler and downloader globally or override per project
The extension also provides Spin and Pasm support for the Propeller 1. P1 users get most of the same features listed above, including:
- Syntax and Semantic Highlighting for Spin and Pasm
- Error Detection, Hovers, Signature Help, and Code Folding
- Full Code Navigation — Go to Definition, Find All References, Workspace Symbol Search, Rename Symbol, Document Highlight, Document Links, Outline View, and Object Hierarchy View
- All Code Generation features (Doc-Comments, Public Interface Docs, Hierarchy Reports)
- All Editor Features (Screen Coloring, Elastic Tabstops, Edit Modes, Color Themes)
- Compile support via FlexSpin
Not yet available for P1: built-in download to hardware and Go to Type Definition (STRUCT is a Spin2 language construct).
The extension tracks the evolving Spin2/PASM2 language specification as new PNut compiler versions add features. Currently supported through PNut v53, including structures, preprocessor directives, math functions, OFFSETOF(), and more. See the language version reference for details on each version's additions.
- Snippets for common Spin2/Pasm2 code patterns (e.g., smart pin setup for a given mode)
In VSCode, search for the "spin2" extension and install it. It's that easy! After installation, you will be notified to download and install new versions as they are released.
Note: This extension fully replaces the Spin by Entomy vscode extension. While either can be used, our version provides more comprehensive Syntax highlighting (as the former has not been maintained), and this extension adds full Semantic Highlighting, Outlining, and Tab support with InsertModes, Document generation, etc. The older Spin extension can now be uninstalled with no loss of functionality.
There are additional companion documents in this Repository:
Getting around your code:
- Editing Features Guide — language intelligence, code generation, and editor features for Spin2 development
- Code Navigation Guide — Find All References, Rename Symbol, Workspace Symbol Search, and more
- Include Directories Guide — how the extension discovers and manages include paths for multi-file projects
Platform setup:
- Setup for Windows — compiler installation and build configuration on Windows
- Setup for macOS — compiler installation and build configuration on macOS
- Setup for Raspberry Pi — compiler installation and build configuration on Raspberry Pi / Linux
Formatter:
- Formatter User Guide — all formatter options with examples, recommended configurations, and what the formatter preserves
- Formatter Regression Testing — theory of operations for the binary-equivalence test suite
Editor features:
- Status Bar Controls — download controls for debug, RAM/FLASH, and PropPlug selection
- Background Coloring — Propeller Tool-style block coloring and theme setup
- Edit Modes — Insert, Overtype, and Align modes à la Propeller Tool
- Tabbing - Visual Examples — a visual walkthrough of how Elastic Tabstops work
- Tabbing - Engineering Notes — detailed specification for the Elastic Tabstops feature
Reference:
- Settings and Keyboard Mapping — all extension settings and key bindings
- ToolChain Reference — compiler detection, task variables, and user-tasks setup
- Useful VSCode Extensions — extensions we find helpful for P2 development
Also, here are a couple of really useful VSCode sources:
- VSCode can do that? Fun website showing specific things VSCode can do - review what's possible that may help you in your use of VSCode.
- YouTube Channel: Code 2020 - A large list of short videos presenting all manner of useful VSCode tips.
Please go look at each of these once so you can know what's here when you need them!
We know the three extension so far which might interfere with our Spin2 extension. Here's what we've seen:
- If I haven't already, I'll be submitting pull requests to the Overtype extension maintainers to add code for avoiding interference with our .spin/.spin2 InsertMode feature, but in the meantime, please ensure that the Overtype by Adma Maras and/or Overtype by DrMerfy extensions are disabled or uninstalled, as they can interfere with our extensions' behavior.
- The Extension Document This v0.8.2 currently also occasionally intercepts the Ctrl+Alt+D keystroke, which we use to generate documentation, and our extension then doesn't get the request. I've filed an issue with the maintainer of that extension, so maybe this will be fixed in the future. Meanwhile, you can either disable the Document This extension or, when you see the warning pop-up from the document this extension, you can usually just click in your editor window again, then press Ctrl+Alt+d again, and it will work after one or more tries.
This is a common issue caused by VS Code's built-in Color Decorator feature, not necessarily a separate extension. VS Code's default behavior interprets # followed by hex digits as CSS color codes and shows color picker swatches.
To confirm and fix this, you can check a couple of things:
Built-in CSS/HTML language features — VS Code ships with extensions like "CSS Language Features" and "HTML Language Features" that detect #RRGGBB patterns even in non-CSS files.
The setting to disable it — Search your VS Code settings for:
editor.colorDecorators — set this to false to disable color picker indicators globally.
Or better, disable it only for Spin2 files by adding to your settings.json:
"[spin2]": {
"editor.colorDecorators": false
}To open your user settings.json for editing: open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P), type "Preferences: Open User Settings (JSON)", and select it. Add the snippet above, save, and the color pickers will stop appearing in .spin2 files.
You can also check which extensions are active in your Spin2 files by opening a .spin2 file, then running the command "Developer: Show Running Extensions" from the command palette (Cmd+Shift+P). Look for any extension that provides color decoration — common culprits besides the built-in ones include extensions like "Color Highlight", "Color Picker", or "Colorize".
This repository contains a single subproject, which is the VS Code extension:
- SPIN2/SPIN and PASM2/PASM syntax Highlighting and code navigation spin2 - Builds
If you like my work and/or this has helped you in some way, then feel free to help me out for a couple of ☕'s or 🍕 slices or support my work by contributing at Patreon!
Ray [Cluso99] in our Propeller 2 Forums, who started this effort for us.
Patrick (GitHub Entomy) for a spin1 extension, which helped me get further along with this one.
Jay B. Harlow for contributing the initial elastic tabs feature.
George (GitHub DrMerfy) for the latest VSCode-Overtype extension, which provided the foundation on which we could add the Align mode.
Licensed under the MIT License.
Follow these links for more information:
