WynnLua — VS Code Extension

A VS Code / VSCodium extension for developing Lua scripts against the WynnLua Fabric mod (Minecraft/Wynncraft client-side automation).

What you get

Scripts tree view in the Activity Bar — browse, run, stop, reload, delete every script in config/wynnlua/scripts/ with icons and running-state badges
Colorized live terminal — ANSI-colored output from every running script streams into a dedicated VS Code Terminal, timestamped, script-name prefixed, severity-colored
Structured log — connection events, errors, and debug info flow into a LogOutputChannel (Output panel → WynnLua) with auto-severity coloring
REPL — WynnLua: Eval Selection (Ctrl+Shift+E) runs the highlighted Lua as a one-shot expression; result pretty-printed via inspect()
Auto hot-reload — hit Ctrl+S on any .lua file in the scripts dir and the running script reloads instantly. External changes (e.g., from a git pull) also trigger reload via VS Code's file watcher.
Full Roblox type definitions — on first activation the extension fetches globalTypes.d.lua from JohnnyMorganz/luau-lsp upstream (the complete pre-generated Roblox API stub) and drops it alongside our own wynnlua.d.luau in the scripts dir. Result: luau-lsp gives you hover docs, autocomplete, type checking for every Roblox API + every WynnLua extension.
Conflict handling — if you already have sumneko.lua, trixnz.vscode-lua, EmmyLua, or another Lua extension, we workspace-scope *.lua → luau language mode in the scripts dir so luau-lsp owns our files without touching your other projects.
Version handshake — extension + mod negotiate protocol version on connect, warn on mismatch
Live file watcher — create/delete/save detection, auto-refreshes the tree and server state

Requirements

Minecraft with the WynnLua Fabric mod installed (the wynnlua-1.0.0.jar from the parent repo)
VS Code 1.85+ or VSCodium
Node.js 18+ (for running the extension during development)
JohnnyMorganz.luau-lsp extension — recommended, not required. Scripts still run without it, you just lose hover docs + type checking. The extension shows a one-time notification nudging you to install it on first touch.

Install (developer mode)

cd wynnlua-ext
npm install

Then open the wynnlua-ext folder in VS Code and press F5. A new VS Code window (Extension Development Host) opens with WynnLua loaded. You'll see the WynnLua icon in the activity bar on the left.

Install (packaged `.vsix`)

npm install -g @vscode/vsce
cd wynnlua-ext
vsce package

Creates wynnlua-<version>.vsix (where <version> matches package.json's version field). Install via Extensions: Install from VSIX… in any VS Code instance.

Usage

Start Minecraft and enter your world
In chat, type /lua serve — this starts the WebSocket server on ws://127.0.0.1:3004/ws
Click the WynnLua icon in the activity bar. The extension first-touches at that moment — syncs type stubs, checks luau-lsp, and (if wynnlua.autoConnect is true) connects. Status bar shows $(circle-filled) WynnLua: 0/0 (running/total).
The Scripts tree shows every .lua / .luau file in your scripts dir
Click a script to open it in an editor tab (real file, full IntelliSense)
Hit the ▶ icon next to the script (or right-click → Run) to run it
The WynnLua Output channel is the Roblox-Studio-style output window — only your print/warn/error output appears there, formatted (tables via inspect), color-coded by level. Extension internals go to debug level so they're hidden by default.

Activation is lazy. The extension does not activate just because VS Code started. It only activates when you open the WynnLua Activity Bar view, invoke a wynnlua.* command, or your workspace contains a wynnlua/scripts/**/*.lua or *.luau file. Unrelated VS Code windows stay untouched — no writes to the scripts dir, no global luau-lsp setting mutations.

The session stays alive once connected. Switching to another activity bar panel does not disconnect. Only clicking WynnLua: Disconnect, stopping the mod, or closing VS Code ends the session.

Key commands (Ctrl+Shift+P)

Command	Default keybind	What it does
`WynnLua: Connect`	—	Manually connect to the WebSocket server
`WynnLua: Disconnect`	—	Stop the connection (disables auto-reconnect)
`WynnLua: Refresh Scripts`	—	Force the server to resend the script list
`WynnLua: New Script`	—	Prompt for a name, create an empty `.lua`, open it
`WynnLua: Run Active File`	Ctrl+F5	Save current `.lua` and run it (or eval if outside scripts dir)
`WynnLua: Eval Selection`	Ctrl+Shift+E	Run highlighted code as one-shot REPL
`WynnLua: Open Terminal`	—	Show the colorized WynnLua terminal
`WynnLua: Show Output`	—	Show the LogOutputChannel for connection/debug logs
`WynnLua: Clear Output`	—	Wipe both the terminal and server-side console buffer
`WynnLua: Open API Reference`	—	Open `API.md` in markdown preview
`WynnLua: Sync Type Stubs`	—	Re-fetch `globalTypes.d.lua` from upstream and rewrite `.luaurc`

Settings

Setting	Default	Notes
`wynnlua.serverUrl`	`ws://127.0.0.1:3004/ws`	WebSocket endpoint — matches `/lua serve`
`wynnlua.autoConnect`	`true`	Connect automatically the first time the WynnLua view is opened in a session. Never fires in unrelated VS Code windows.
`wynnlua.autoReconnect`	`true`	Reconnect after a live session drops (e.g., mod restart). Never retries a failed initial connect — one attempt, one error message, done.
`wynnlua.scriptsDir`	(auto-detect)	Path to `config/wynnlua/scripts`. Leave empty to auto-detect PrismLauncher default. Changing this at runtime rebuilds the file watcher automatically.
`wynnlua.typeStubsUrl`	upstream luau-lsp	Source URL for Roblox type stubs

How type checking works

On first activation the extension:

Detects your scripts dir (auto or from config)
Copies our bundled types/wynnlua.d.luau into that dir
Fetches globalTypes.d.lua from luau-lsp upstream (cached in extension global storage, re-fetched weekly)
Copies it to the scripts dir alongside our stubs
Writes .luaurc and .vscode/settings.json so luau-lsp loads both files
Sets workspace-scoped files.associations to map *.lua → luau language mode

luau-lsp then gives you:

Full Roblox IntelliSense — every class, method, event, enum from the upstream API dump
WynnLua-specific autocomplete — LocalPlayer.WynnHp, wynn.char.hp(), World:GetMobs(30), etc.
Hover documentation — descriptions and parameter docs pulled from the type annotations
Type checking — incorrect types, misspelled properties, missing arguments all flagged inline

Conflict handling

If you already have other Lua extensions (sumneko.lua, trixnz.vscode-lua, EmmyLua, etc.), the extension detects them on activation and shows a one-time info notification. The workspace-scoped files.associations override maps *.lua → luau inside the scripts dir only, so your other extensions stay active in other projects.

Troubleshooting

Status bar shows $(circle-slash) WynnLua: the extension can't connect. Make sure MC is running and /lua serve has been typed in chat.
Scripts tree is empty: connect first (WynnLua: Connect), then WynnLua: Refresh Scripts.
Autocomplete not working: WynnLua: Sync Type Stubs to re-fetch. Check the Output panel (WynnLua) for type sync failed messages.
Script doesn't hot-reload on save: check the script is inside the config/wynnlua/scripts/ dir (not a different location). Configure wynnlua.scriptsDir if auto-detect picked the wrong path.
Conflicts with sumneko.lua: the extension detects this and shows a notification. The workspace-scoped mapping should prevent interference.

Architecture

                               ┌──────────────────────┐
                               │ Minecraft + WynnLua  │
                               │  Fabric mod          │
                               │  (wynnlua-1.0.0.jar) │
                               └──────────┬───────────┘
                                          │ /lua serve
                                          ▼
                         ws://127.0.0.1:3004/ws (Netty)
                                          │
                                          │ MessagePack-framed
                                          │ JSON messages
                                          ▼
          ┌───────────────────────────────────────────────────┐
          │ VS Code + wynnlua-ext                             │
          │  ┌─────────────┐  ┌──────────────┐  ┌──────────┐  │
          │  │ Scripts     │  │ Pseudo-      │  │ Output   │  │
          │  │ Tree        │  │ Terminal     │  │ Channel  │  │
          │  │ (sidebar)   │  │ (ANSI color) │  │ (logs)   │  │
          │  └─────────────┘  └──────────────┘  └──────────┘  │
          │  ┌───────────────────────────────────────────┐    │
          │  │ Monaco Editor (your script .lua files)    │    │
          │  │  + luau-lsp for IntelliSense              │    │
          │  └───────────────────────────────────────────┘    │
          └───────────────────────────────────────────────────┘

File layout

wynnlua-ext/
├── package.json          extension manifest
├── extension.js          main entry — activate, commands, watchers, handshake
├── client.js             WebSocket + MessagePack client
├── scriptTree.js         TreeDataProvider for the Scripts sidebar
├── types/
│   └── wynnlua.d.luau    WynnLua-specific type stubs for luau-lsp
├── API.md                flat API reference with status tiers
├── README.md             this file
└── .vscodeignore         files excluded from .vsix package

License

Same as the parent WynnLua project.

WynnLua

Robert Cincotta