XCL Twee X-Lowe (VS Code Extension)
VS Code extension for X-Change Life Twee (.twee) files using X-Lowe (Harlowe-style syntax).
Features
- Syntax highlighting for XCL/X-Lowe patterns (passages, macros, variables, hooks, HTML)
- Passage Explorer panel in the Activity Bar for quick navigation
- Macro Handbook panel (categorized macro browser + docs)
- Palette Gallery panel with live theme previews and one-click application
- Go to Definition (
F12 or Ctrl/Cmd+Click) on passage references
- Autocomplete for macros and passage names
- CodeLens showing passage targets inline
- Hover info for macros and passage references
- Status bar showing current passage
- 14 custom color themes optimized for Twee editing
Color Themes
The extension includes 14 carefully crafted color themes optimized for XCL Twee syntax highlighting.
Dark Themes
| Theme |
Description |
| XCL Blessing |
Warm golden tones on deep purple-black |
| XCL Northwest Passage |
Cool blues and teals with forest undertones |
| XCL Cerise |
Vibrant pinks and magentas on dark cherry |
| XCL Ocean |
Deep sea blues with aqua accents |
| XCL Dark |
Balanced neutral dark theme |
| XCL Summer City |
Warm sunset oranges and corals |
| XCL Valentine |
Romantic reds and soft pinks |
| XCL Royal |
Regal purples with gold highlights |
| XCL Dream |
Soft pastels on midnight blue |
| Goblin's Pet 1970s Umbral |
Earthy browns and amber on dark crimson |
| Goblin's Pet Goblin Market |
Mysterious greens and golds |
Light Themes
| Theme |
Description |
| XCL DMG-01 |
Retro Game Boy–inspired monochrome green |
| XCL Parchment |
Warm sepia tones like aged paper |
| Goblin's Pet Reliquary White |
Clean ivory with antique accents |
Applying Themes
- Via Palette Gallery: Click the XCL icon in the Activity Bar → Palettes panel → Click Apply on any theme
- Via Command Palette:
Ctrl+Shift+P → "Preferences: Color Theme" → Select an XCL theme
- Via Settings:
File → Preferences → Color Theme
Click the XCL icon in the Activity Bar to access all panels.
Passages
Shows passages in the currently active .twee file. Click a passage to jump to it.
Toolbar actions:
- Configure Search Paths — Add or remove folders from the index
- Exclude Folder from Index — Quickly exclude folders from indexing
- Refresh — Rebuild the passage index
Macro Handbook
A categorized, searchable macro browser built from bundled JSON documentation.
Organization:
- XCL Macros — X-Change Life / X-Lowe custom macros
- Harlowe Macros — Core Harlowe macros
- TGP Macros — The Goblin's Pet macros
Within each group, macros are organized by Category (Navigation, Variables, Output, etc.) and sorted by macro count. Click any macro to open its rendered documentation.
Palettes
A visual gallery of all bundled color themes with:
- Live color swatches extracted from each theme's JSON
- One-click Apply button to instantly set your VS Code theme
- Open JSON button to inspect/edit the theme file
- Search filter to quickly find themes by name
Macro Docs Files
By default, the extension loads all bundled macro documentation:
| File |
Contents |
macros/xcl-macros.harlowe.json |
Core Harlowe macros |
macros/xcl-macros.xlowe.json |
X-Change Life / X-Lowe macros |
macros/xcl-macros.stats.json |
Stats, Sidebar, Tertiary, Meter macros |
macros/xcl-macros.tgp.json |
The Goblin's Pet macros |
Override behavior:
- Set
xcl.macroDocsFile to a single JSON file path to load only that file
- Workspace-relative paths are supported
Navigation
These macros support Go to Definition on their first string argument:
(display:"passage")
(goto:"passage")
(link-goto:"passage")
(click-goto:"passage")
(cs:"passage")
(simple_option:"passage", ...)
($simple_option:"passage", ...)
Configure the list in settings: xcl.passageReferenceMacros
Commands
| Command |
Description |
XCL: Passage Picker |
Quick-pick menu to jump to any passage |
XCL: Open Passage |
Open a passage by name |
XCL: Reindex Workspace Passages |
Rebuild the passage index |
XCL: Reload Macro Docs |
Reload macro documentation JSON |
XCL: Open Macro Docs File |
Open the last-loaded macro docs JSON |
XCL: Open Palette Gallery |
Focus the Palette Gallery panel |
Refresh |
Refresh the Passage Explorer (toolbar button) |
Configure Search Paths |
Add or remove folders from the index (toolbar button) |
Exclude Folder from Index |
Exclude a folder from indexing (toolbar button) |
Settings
| Setting |
Default |
Description |
xcl.indexGlobs |
["**/*.twee"] |
File patterns to index (prefix with ! to exclude) |
xcl.passageReferenceMacros |
["display", "goto", "link-goto", "click-goto", "cs", "simple_option", "$simple_option"] |
Macros whose first string argument is treated as a passage reference |
xcl.macroDocsFile |
"" |
Custom macro docs JSON path (loads ONLY this file if set) |
xcl.statusBar.enabled |
true |
Show passage in status bar |
xcl.codeLens.enabled |
true |
Show CodeLens for passages |
xcl.documentLinks.enabled |
true |
Show visible hyperlinks on passage references (Ctrl+Click navigation still works when disabled) |
xcl.showPassageNotFoundWarnings |
true |
Show warnings in CodeLens and hover when a referenced passage is not found |
xcl.passageView.groupByFile |
true |
Group passages by file in the Passage Explorer view |
Installation
From VSIX
npm install
npm run compile
npm run package
code --install-extension ./xcl-twee-xlowe-1.0.3.vsix
Development Mode
Open the folder in VS Code and press F5 to launch the Extension Development Host.
Project Structure
xcl-twee-xlowe/
├── src/
│ └── extension.ts # Main extension logic
│ ├── PassageIndex # Workspace-wide passage indexing
│ ├── PassageTreeDataProvider # Passage Explorer sidebar
│ ├── MacroHandbookDataProvider # Macro Handbook sidebar
│ ├── PaletteGalleryViewProvider # Palette Gallery webview
│ ├── MacroRegistry # Macro documentation loader
│ ├── MacroDocMarkdownProvider # Virtual markdown docs
│ ├── PassageDefinitionProvider # Go to Definition
│ ├── PassageLinkProvider # Document links
│ ├── PassageSymbolProvider # Document symbols
│ ├── MacroHoverProvider # Macro hover info
│ ├── MacroCompletionProvider # Macro autocomplete
│ ├── PassageNameCompletionProvider # Passage name autocomplete
│ ├── PassageCodeLensProvider # CodeLens for passages
│ └── PassageReferenceHoverProvider # Passage reference hover
│
├── syntaxes/
│ └── xcl-twee.tmLanguage.json # TextMate grammar for syntax highlighting
│
├── themes/ # Color themes (14 total)
│ ├── xcl-blessing-color-theme.json
│ ├── xcl-northwest-passage-color-theme.json
│ ├── xcl-cerise-color-theme.json
│ ├── xcl-ocean-color-theme.json
│ ├── xcl-dark-color-theme.json
│ ├── xcl-summer-city-color-theme.json
│ ├── xcl-valentine-color-theme.json
│ ├── xcl-royal-color-theme.json
│ ├── xcl-dream-color-theme.json
│ ├── xcl-dmg-01-color-theme.json
│ ├── xcl-parchment-color-theme.json
│ ├── goblins-pet-1970s-umbral-color-theme.json
│ ├── goblins-pet-goblin-market-color-theme.json
│ └── goblins-pet-reliquary-white-color-theme.json
│
├── macros/ # Macro documentation JSON
│ ├── xcl-macros.harlowe.json # Core Harlowe macros
│ ├── xcl-macros.xlowe.json # XCL/X-Lowe macros
│ ├── xcl-macros.stats.json # Stats + Sidebar + Tertiary + Meter
│ └── xcl-macros.tgp.json # The Goblin's Pet macros
│
├── language-configuration.json # Brackets, comments, folding
├── package.json # Extension manifest
├── tsconfig.json # TypeScript configuration
├── icon.svg # Activity bar icon
├── icon.png # Marketplace icon
└── README.md # This file
Syntax Highlighting
The TextMate grammar (xcl-twee.tmLanguage.json) provides highlighting for:
| Element |
Scope |
Passage headers (:: Name) |
entity.name.section.passage.xcl-twee |
Passage tags ([tag]) |
entity.other.attribute-name.passage.tag.xcl-twee |
| Navigation macros |
support.function.macro.navigation.xcl-twee |
| Audio macros |
support.function.macro.audio.xcl-twee |
| UI macros |
support.function.macro.ui.xcl-twee |
Custom macros ($name:) |
support.function.macro.custom.xcl-twee |
| Generic macros |
entity.name.function.macro.xcl-twee |
Variables ($var, _var) |
variable.other.xcl-twee |
Hooks ([...], |name>[...]) |
meta.hook.xcl-twee |
Link markup ([[...]]) |
meta.link.twee.xcl-twee |
| Strings |
string.quoted.*.xcl-twee |
| Numbers |
constant.numeric.xcl-twee |
| Booleans |
constant.language.boolean.xcl-twee |
| Operators |
keyword.operator.xcl-twee |
| HTML tags |
entity.name.tag.*.html |
| Comments |
comment.block.html |
Language Configuration
The extension configures VS Code with:
- Block comments:
<!-- -->
- Bracket pairs:
{}, (), []
- Auto-closing pairs: All brackets, quotes, and HTML comments
- Folding markers:
<!-- #region --> / <!-- #endregion -->
Repository
License
MIT
