Scripting from VS Code

The TTCraft VSC extension edits the scripts of a running game table from Visual Studio Code. It signs in to TTCraft, lists the tables you may manage, and mirrors one table's Lua scripts into a folder of real files: the Global script, every scripted object, every scripted library template. Saving a file pushes it to the live table; the table's console streams back into the editor. Because the files are real, the Lua language server and AI coding agents (Copilot, Claude Code, Codex and the like) can read and edit them like any other project.

It edits scripts only. Objects, decks, zones, assets, the look of the table and everything else are still made in the table itself; whole tables move around as table archives. The table's outline, seats and named areas can also be described as a table plan, which a script applies with Table.set.

Install#

Get it from the Visual Studio Marketplace, or open the Extensions view in VS Code (Ctrl+Shift+X), search for TTCraft and click Install. The extension is free and open source; the code is on GitHub.

At a glance, it gives you:

• Your tables in the sidebar — every table you manage, with its Global script, objects and library templates, updating live as things spawn and despawn.
• Scripts as real files — one folder on disk mirrors the table, so search, git and every editor tool work on the scripts.
• Save is deploy — Ctrl+S sends a script to the running table and it takes effect for every player at once; a compile error is shown on the offending line and the previous version keeps running.
• The console in the editor — everything scripts print and every error, in an output channel and in a file.
• Autocomplete for the whole API — tw, self, players, JSON, Vector, Color and every event, through the Lua language server.
• Made for AI agents — the folder explains itself to Copilot, Claude Code, Codex and friends, so an agent can write and debug table scripts on its own.

The rest of this page walks through each of those.

What you need#

• A TTCraft account that is a member of a room with the Manage table permission (room owners and moderators have it by default).
• The table open in that room. The extension does not boot a stopped table — start it from the room page first, then it appears with a filled dot in the extension's list.
• VS Code 1.85 or newer with the extension installed.
• Optionally the Lua extension (sumneko.lua) for highlighting and autocomplete; TTCraft VSC offers to install it the first time you open a script.

Signing in#

Open the TTCraft view in the Activity Bar and click Sign in. The extension opens the link a device page on ttcraft.net in your browser with a short code already filled in; approve it there. No password is ever typed into the editor — the flow is the same device authorisation that command-line tools use. The resulting token lives in VS Code's secret storage and can be revoked from Settings → Security on ttcraft.net.

The Tables view#

Every table you may manage is listed as #channel with its room name. Expanding a table connects to it and shows:

• Global script — the table-level script.
• Objects — every object on the table, live: spawns appear, despawns disappear. Objects that already carry a script have a code icon.
• Templates — the table's library, foldered by category.
• Effects — listed for reference; effects are data, not scripts, and do not open.

Click an entry to open its script. Clicking a script-less object or template starts an empty script for it. Open table on a table mirrors the whole table and opens global.lua; Switch table (also in the status bar) picks a table from a list.

The table folder#

Opening a script mirrors the table into one folder — the table folder — which the extension adds to your workspace:

Only objects and templates that already carry a script get a file. Names are the same the table shows in the browser, so built-in templates read as Playing cards, not as i18n keys.

One folder holds one table. Opening a script on a different table switches the folder: editors on the old table's files are closed, its files are removed, and the new table's scripts are written in their place. Nothing is lost by this — the table is the source of truth and every save has already reached it — and whoever works in the folder, you or an agent, never sees two tables mixed together. The status bar shows which table is in the folder.

Do not rename, move or create script files by hand: the __<id> suffix is how a file maps back to its entity. Deleting a file deletes nothing on the table.

Saving#

Ctrl+S pushes the file to the table at once, exactly like the Save button in the browser's script editor: the script is compiled in a fresh state and, if it compiles, replaces the running one for every player. If it does not compile, the previous version keeps running, the error is shown as a diagnostic on the offending line, and a line is appended to .ttcraft/console.log.

Everything the table's scripts print — print(), log(), runtime errors — arrives in the TTCraft Table output channel (TTCraft: Show table console) and in .ttcraft/console.log, prefixed by the table. A runtime error disables that script until its next save, as in the browser.

Live changes on the table reach the folder as they happen: a despawned object's file goes away, a template edited in the browser is rewritten. An object's script edited in the browser is not broadcast, so after editing the same script in both places press Refresh in the view's toolbar — it reconnects and re-pulls every script.

Autocomplete and checking#

The extension ships EmmyLua definitions of the whole API — tw, the object and player handles, JSON, Vector, Color, and every event callback — and points the Lua language server at them through the folder's .luarc.json. With the Lua extension installed you get completion, signatures and undefined-global checks for self, tw and friends. The definitions file (resources/library/ttcraft.lua inside the extension) is also the most exact description of the API there is, and AGENTS.md names its absolute path for agents.

Working with an AI agent#

The folder is made for it. Open VS Code on the table folder, or point your agent at it, and read AGENTS.md yourself once: it tells the agent

• what the folder is and which table it mirrors (with .ttcraft/table.json as the machine-readable copy);
• that saving a .lua file pushes it to the running table, and how to see the result in .ttcraft/console.log;
• where the manual and the API definitions are, and that scripts run sandboxed on the server — no require, no HTTP, nothing fetched from URLs;
• what cannot be done from the folder: booting or closing the table, uploading assets, importing other tabletops' saves.

CLAUDE.md defers to AGENTS.md for tools that only read the former. The manual itself is served as markdown for agents at /llms.txt (an index) and /llms-full.txt (every page in one file).

A useful loop for an agent: edit → save → read the tail of .ttcraft/console.log → adjust. A save that lands prints saved to the table; a rejected one prints the compiler's message.

Workspace restarts#

VS Code restarts all extensions when a window gets its first workspace folder, and reloads the window when a single-folder workspace turns into a multi-root one. The first table you open in a window may therefore flash once. The extension expects this: the open you started is finished after the restart, and a table folder that is already in the workspace reconnects on its own every time the window opens. Closing a table or signing out empties the folder but leaves it in the workspace, so nothing restarts again.

To avoid the restart entirely, set Settings → TTCraft → Table Folder to an empty folder inside a workspace folder you already have open — my-campaign/table, say. Nothing is added to the workspace then, and an agent working on your project sees the table's scripts next to your own files. The folder must be empty the first time; the extension owns its contents from then on.

Troubleshooting#

Under the hood#

For anyone building their own tooling — the extension is a thin client over two existing surfaces, and both are documented here so a script or agent can use them directly.

Signing in is the OAuth 2.0 Device Authorization Grant (RFC 8628) against ttcraft.net:

• POST /api/devices/code with {"client_name": "…"} returns device_code, user_code, verification_uri, verification_uri_complete, expires_in (600) and interval (5).
• The user approves at verification_uri_complete (the /link page) while signed in to TTCraft.
• POST /api/devices/token with {"device_code": "…"} returns {"error": "authorization_pending"} until then, then {"access_token": "ttcd_…", "token_type": "Bearer", "name", "user": {"id", "username"}}. Other errors: slow_down, access_denied, expired_token, invalid_grant. The token is valid for 90 days.

The dev API takes that token as Authorization: Bearer ttcd_…:

• GET /api/dev/me → {"user": {"id", "username", "name"}}.
• GET /api/dev/tables → {"tables": [{"id", "channel": {"id", "name", "slug"}, "room": {"name", "slug"}, "status", "running", "last_activity_at"}]} — the tables whose room grants you Manage table.
• GET /api/dev/tables/{id}/connect → {"table_id", "token", "caps", "ws_url", "http_url", "expires_in"} — a two-minute WebSocket token for one running table, with the same capabilities you would get in the browser. A stopped table answers 409 {"error": "table_not_open"}.

The table itself speaks JSON over ws_url?token=…. After {"type": "identify", "clientId", "tabId"} the server sends hello (object names) and props (objects with their guid), then keeps both up to date. The scripting messages:

Object runtime ids change across reconnects; scripts persist by guid, which is why the extension names files after it. setscript needs the Edit capability, which Manage table grants.