Stars in Shadow Developer Extension

This extension is your one-stop shop for Stars in Shadow development utilities! It includes:

• Lua debugger: An evolution of devcat's excellent lua debugger, tweaked to work better with SiS's quirky runtime enviornement.
• OpenHint server: A tiny integrated server that allows your running copy of Stars in Shadow to open files in VS Code.
• Lua go-to-definition: A lightweight Ctrl+Click / F12 implementation for SiS Lua that uses workspace search heuristics, and (when paused in the debugger) runtime debug.getinfo to jump to the exact definition line.
• Lua formatter: Minimal SiS-safe Lua formatting (default: whitespace normalization; optional: simple re-indent).

Debugging (Lua / SiS)

The launch config provided in your Stars in Shadow\Lua state\.vscode folder should work once this extension is installed (no separate debugger extension is required).

Typical configs use:

• "type": "lua"
• Typical command line option include:
  • -vscode (enables the SiS Lua debugger)
  • -console (echo game engine outputs to a seperate term)
  • -debugbridge (emulate msvc debug string handling).
• listenPort: SiS defaults to 46692 -- you probably want to keep that default.

Stopping / restarting (Windows)

The adapter is intended to treat Stop Debugging as a hard stop: terminate the launched process tree, close the debuggee connection, and end the session promptly. However, implementing this behavior robustly requires a relatively recent build of SiS -- if you're running a version older than 1.5.0 -- you may see issues where stopping the debugger does not quit the game.

Lua breakpoints

This extension contributes Lua breakpoint support, so breakpoints should work normally in lua files. If VS Code still refuses to place breakpoints, make sure the file's language mode is set to Lua; as a fallback you can set debug.allowBreakpointsEverywhere.

Formatting (Lua)

This extension provides a Lua formatter that avoids “fixing” SiS Lua dialect constructs.

• Set your default formatter for Lua to Stars in Shadow Dev.
• Configure behavior via sisDev.luaFormatter.mode:
  • whitespace (default): converts leading tabs to 2 spaces and otherwise preserves indentation (including whitespace-only lines); does not re-indent blocks (safest for SiS visual-indent conventions).
  • simple: re-indents using lightweight block keywords + {}, but preserves visually-shallow | function blocks (notably UI_File | function(_ENV)) and avoids flattening multiline continuations ((...), [...], and lines following a trailing =).

Code Provenance

The debuggee protocol started as a fork of devCAT's VSCodeLuaDebug; but I've been tweaking it as I see fit. Props to both Seungjae Lee (@devcat) his integration work, and Dan Tull (@adobe) for his awesome OP_HAULT patch. For a deeper dive into what's going on here, see this old lua-l thread.

OpenHint

The OpenHint server starts automatically when vscode open (see settings under remote.*), but you can also control it manually via:

• SiS Dev: Start OpenHint Server
• SiS Dev: Stop OpenHint Server

Extension Developer Runbook:

Local build + install (no publishing)

Option A: Run from source (recommended for development)

1. npm install
2. npm run build:all
3. In VS Code, press F5 (launches an “Extension Development Host” via .vscode/launch.json).

Option B: Build a .vsix and install it

1. npm install
2. npm run build:all
3. npx @vscode/vsce package
4. Install the resulting openhintvc-<version>.vsix:
   • VS Code UI: Extensions view → ... → Install from VSIX...
   • CLI: code --install-extension .\openhintvc-<version>.vsix --force