WynnLua

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

1. Minecraft with the WynnLua Fabric mod installed (the wynnlua-1.0.0.jar from the parent repo)
2. VS Code 1.85+ or VSCodium
3. Node.js 18+ (for running the extension during development)
4. 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

1. Start Minecraft and enter your world
2. In chat, type /lua serve — this starts the WebSocket server on ws://127.0.0.1:3004/ws
3. 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).
4. The Scripts tree shows every .lua / .luau file in your scripts dir
5. Click a script to open it in an editor tab (real file, full IntelliSense)
6. Hit the ▶ icon next to the script (or right-click → Run) to run it
7. 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)

Settings

How type checking works

On first activation the extension:

1. Detects your scripts dir (auto or from config)
2. Copies our bundled types/wynnlua.d.luau into that dir
3. Fetches globalTypes.d.lua from luau-lsp upstream (cached in extension global storage, re-fetched weekly)
4. Copies it to the scripts dir alongside our stubs
5. Writes .luaurc and .vscode/settings.json so luau-lsp loads both files
6. 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.