vscode-extension: LuaMap Tools for VS Code over LuaBridge

.gitignore

@@ -16,3 +16,10 @@ luamap-run/
 ide-plugin/.intellijPlatform/
 # managed IDE runtime artifacts
 .luamap/
+
+# VS Code extension
+vscode-extension/node_modules/
+vscode-extension/out/
+vscode-extension/out-test/
+vscode-extension/*.vsix
+.vscode-test/

README.md

@@ -94,8 +94,8 @@ java -jar luamap-launcher.jar [options]
   --xmx SIZE        game heap (default: 2G)
   --mc VERSION      override the bundled Minecraft version
   --bridgePort N    enable LuaBridge on 127.0.0.1:N for IDE live-eval/debug
-                    (see docs/luabridge.md; the LuaMap IntelliJ plugin
-                    connects here)
+                    (see docs/luabridge.md; the VS Code extension and the
+                    IntelliJ plugin connect here)
   --setup-ide       provision IntelliJ IDEA CE + LuaMap plugin under
                     .luamap/ide/, print the path, exit (no game launch)
   --ide             same, then launch the IDE
@@ -113,20 +113,30 @@ its `plugins/` directory. Start the game with `--bridgePort 25575`, open a
 `.lua` script in the IDE, and use a "LuaMap Script" run configuration to
 live-run it against the world.
 
-## IDE integration (LuaBridge + IntelliJ plugin)
+## IDE integration (LuaBridge + VS Code / IntelliJ)
 
 Two pieces make up the dev-tooling side of the repo:
 
 - **LuaBridge** (`bridge/` module, embedded in the mod jar) — a localhost-only
   newline-delimited-JSON socket server exposing `eval`/`run`/`reload`/`list`/
   `status`. Enable it with `--bridgePort 25575` (or `port=25575` in
   `<gameDir>/luamap-bridge.properties`). Protocol: [docs/luabridge.md](docs/luabridge.md).
-- **LuaMap Tools** (`ide-plugin/` — included Gradle build) — IntelliJ IDEA
-  plugin with `.luamap` file type, API-word highlighting + completion for
-  `world.*`/`player.*`/`npc.*`, a "LuaMap Script" run configuration that
-  sends scripts to LuaBridge, a gutter run marker, and a block-preview tool
-  window stub. Build: `./gradlew :ide-plugin:build` → install the zip from
-  `ide-plugin/build/distributions/` via Settings → Plugins → Install from Disk.
+- **LuaMap Tools for VS Code** (`vscode-extension/`) — **the supported IDE
+  path.** TypeScript extension with a status-bar badge, sidebar (session
+  controls, live NPC inspector, script list/runner), eval console,
+  `world.getblock` queries, and `world.*`/`npc.*`/`player.*` Lua autocomplete
+  + snippets. Commands: `LuaMap: Connect` / `Disconnect` / `Reconnect` /
+  `Run Script` / `Evaluate Lua` / `Query Block`. Build/package:
+  `cd vscode-extension && npm install && npm test && npm run package` →
+  install `luamap-vscode-*.vsix` via `code --install-extension` or
+  Extensions → Install from VSIX. See [vscode-extension/README.md](vscode-extension/README.md).
+- **LuaMap Tools for IntelliJ** (`ide-plugin/` — included Gradle build) —
+  **deprecated, retained during transition.** Same feature set for IDEA
+  (`.luamap` file type, highlighting/completion, run configuration, tool
+  window); still built and bundled into the launcher fat jar so
+  `--setup-ide`/`--ide` keep working. Build: `./gradlew :ide-plugin:build` →
+  install the zip from `ide-plugin/build/distributions/` via Settings →
+  Plugins → Install from Disk. New work should target `vscode-extension/`.
 
 The IDE plugin is a composite included build — `./gradlew build` never
 configures it, so the main build stays fast and JVM-only; build it explicitly
@@ -308,7 +318,10 @@ mods, and runs it.
 │   └── src/main/java/...   # downloader / installer / bootstrap
 ├── bridge/                 # LuaBridge protocol + localhost socket server
 │   └── src/...             # BridgeProtocol / BridgeServer / BridgeClient
-├── ide-plugin/             # IntelliJ plugin (included build; own settings)
+├── vscode-extension/       # VS Code extension (supported IDE path)
+│   ├── src/...             # bridge client, session, sidebar, completion
+│   └── test/...            # node:test suites (framing + client)
+├── ide-plugin/             # IntelliJ plugin — DEPRECATED, retained for now
 │   └── src/...             # file type, completion, run config, tool window
 ├── docs/luabridge.md       # bridge protocol spec
 └── README.md

ide-plugin/README.md

@@ -1,5 +1,11 @@
 # LuaMap Tools — IntelliJ IDEA plugin
 
+> **Deprecated.** The supported IDE path is the VS Code extension in
+> `../vscode-extension/` — same bridge protocol, same feature set, plus a
+> live tool-window-equivalent sidebar. This plugin is retained (it still
+> builds and ships inside `luamap-launcher.jar` for `--setup-ide`/`--ide`)
+> until the VS Code path has soaked; no new features land here.
+
 IDE companion for Lua Map Maker map scripts. Lives in this repo as a Gradle
 **included build** (composite) so it shares nothing with the mod build except
 the protocol documented in `../docs/luabridge.md`.

vscode-extension/.vscodeignore

@@ -0,0 +1,13 @@
+src/**
+test/**
+out/test/**
+node_modules/**
+*.map
+tsconfig.json
+.vscode/**
+.vscode-test/**
+esbuild.*
+*.vsix
+.github/**
+out-test/**
+package-lock.json

vscode-extension/README.md

@@ -0,0 +1,65 @@
+# LuaMap Tools — VS Code extension
+
+Live [LuaBridge](../docs/luabridge.md) client for the Lua Map Maker mod. Connects
+over the loopback NDJSON TCP protocol (protocol v1) to a running game started
+with `--bridgePort` (default `25575`).
+
+## Features
+
+- **Status bar badge** — `Connected` / `Connecting` / `Error` / `Disconnected`,
+  one click to connect.
+- **LuaMap sidebar** (activity bar) — Session state + actions, **NPCs**
+  inspector (name + `x, y, z`, refreshed every poll), and **Scripts** list
+  (click to run).
+- **Commands** — `LuaMap: Connect`, `Disconnect`, `Reconnect`, `Run Script`,
+  `Evaluate Lua`, `Query Block`, `Refresh NPCs`.
+- **Eval console** — script output, `=> result` values, and errors are logged
+  to the **LuaMap** output channel.
+- **NPC inspector** — `eval`s a `npc.list()` snippet, so it works against the
+  stock protocol with no mod changes.
+- **Block query** — `world.getblock(x, y, z)` via an input prompt.
+- **Lua autocomplete + snippets** for `world.*`, `npc.*`, `player.*`, `chat`,
+  `log`, `print` in `.lua` files.
+- **Auto-reconnect** (~1.5 s) and configurable polling
+  (`luamap.pollIntervalSeconds`, default 2 s). All socket I/O is
+  event-driven — nothing blocks the UI.
+
+## Usage
+
+1. Start the game: `java -jar luamap-launcher.jar --bridgePort 25575`
+   (or `--server --bridgePort 25575` headless).
+2. Install the `.vsix`: `code --install-extension luamap-vscode-0.4.0.vsix`
+   or Extensions view → `…` → *Install from VSIX…*.
+3. `Ctrl+Shift+P` → **LuaMap: Connect** (defaults `127.0.0.1:25575`), or click
+   the `LuaMap` status bar item.
+
+## Settings
+
+| Setting | Default | Notes |
+|---|---|---|
+| `luamap.bridge.host` | `127.0.0.1` | Bridge is loopback-only by design |
+| `luamap.bridge.port` | `25575` | Match `--bridgePort` |
+| `luamap.autoReconnect` | `true` | Reconnect ~1.5 s after a drop |
+| `luamap.pollIntervalSeconds` | `2` | Status + NPC refresh cadence |
+
+## Develop
+
+```sh
+cd vscode-extension
+npm install
+npm run compile   # tsc → out/
+npm test          # compile + node:test suite (14 tests)
+npm run package   # vsce → luamap-vscode-<ver>.vsix
+```
+
+Tests are plain `node:test` suites over a mock loopback NDJSON server —
+no VS Code instance required. They cover NDJSON framing, request/response
+id matching, connect/drop/reconnect, and status/NPC reply parsing.
+
+## Limitations
+
+- NPC state is identity + position only — the mod exposes no richer state.
+- No breakpoint debugging yet; the bridge protocol has `eval|run|reload|list|
+  status` only.
+- The extension was smoke-verified by unit tests; full UI behavior inside VS
+  Code was not exercised on a headless CI machine.