Instance for Visual Studio Code

Instance is a Roblox Studio companion for Visual Studio Code. It gives Roblox projects a durable local editing surface: a Studio-connected Explorer, typed Properties panel, Luau language intelligence, file-backed project format, and reviewed sync controls.

Instance mirrors the Roblox DataModel into .instance/game/ so scripts, properties, hierarchy, and AI-authored changes can be reviewed as ordinary files while still round-tripping back to Roblox Studio through the Instance plugin.

Copyright (c) 2026 Logisec. All rights reserved.

Why Instance Exists

Roblox Studio is excellent at running and inspecting a live place, but complex games also need the workflows developers expect from a serious IDE:

• Source-controlled project files that represent more than scripts.
• A Studio-like Explorer inside VS Code.
• Typed property editing without hunting through raw JSON.
• Luau completions and diagnostics that know about the actual game tree.
• Manual or automatic push modes, with diff review before risky changes.
• AI-friendly project metadata so tools can create valid Roblox objects.

Instance is designed to be local-first. The VS Code extension hosts a local WebSocket server, the Roblox plugin connects to it, and both sides exchange snapshots, diffs, and commands over 127.0.0.1.

Highlights

Area	What Instance Provides
Studio sync	Bidirectional Studio <-> VS Code communication over local WebSocket
Explorer	Roblox service-aware tree, create/rename/move/delete, search, drag/drop, bookmarks
Properties	Typed property editors, validation, dirty state, undo/redo, multi-select foundations
Files	.instance/game/ mirror with scripts, JSON properties, sidecars, GUIDs, and container metadata
AI workflow	Project context files and an authoring format that AI coding tools can follow
Safety	Manual push mode, diff panel, pending command queue, backups, quarantine, sync health indicators
Luau	Bundled Instance LSP for API-aware and game-tree-aware completions, hover, references, diagnostics
Packaging	Built-in command to build the Roblox Studio plugin from bundled Luau source

Requirements

• Visual Studio Code 1.85 or newer.
• Roblox Studio.
• Node.js 18 or newer when building from source.
• The Instance Roblox Studio plugin installed in Studio.

Quick Start From Source

cd extension
npm install
npm run build:all

Launch the extension development host from VS Code with F5, or package the extension after preparing the plugin resource:

cd extension
npm run prepare:plugin
npm run package

In VS Code:

1. Open the Instance activity-bar view.
2. Run Instance: Connect to Roblox Studio.
3. Open Roblox Studio and click the Instance plugin toolbar button.
4. Click Connect to VS Code in the plugin widget.

The Explorer, Properties panel, file mirror, and LSP project context will populate once the initial snapshot arrives.

Core Commands

Command	Purpose
Instance: Connect to Roblox Studio	Starts the local WebSocket server for the plugin
Instance: New Game	Creates a new local Instance project layout
Instance: Open Existing .instance Project	Opens an existing local mirror without requiring Studio
Instance: Import Roblox Place/Model File	Imports supported Roblox files into the Instance project model
Instance: Export Roblox Place/Model File	Exports the current Instance store back to Roblox XML
Instance: Build Roblox Plugin	Builds Instance.rbxmx from the bundled plugin source
Instance: Open Diff Panel	Reviews outbound file/property changes before pushing
Instance: Push Changes to Studio	Sends queued changes in manual sync mode
Instance: Toggle Sync Mode	Switches between automatic and manual Studio pushes

Documentation

Additional markdown documentation ships in extension/docs/:

• docs/INSTALLATION.md
• docs/PROJECT_FORMAT.md
• docs/SYNC_AND_SAFETY.md
• docs/PUBLISHING.md
• docs/TROUBLESHOOTING.md

Project Format At A Glance

Instance mirrors the DataModel under .instance/game/:

.instance/game/
Workspace/
_meta.json
SpawnLocation.part.json
ReplicatedStorage/
Shared/
_meta.json
Config.module.luau
Config.module.meta.json
ServerScriptService/
Main.server.luau
Main.server.meta.json

AI-authored files may omit GUIDs. Instance backfills missing IDs, writes script sidecars, adopts plain directories as Folder, and reports malformed files in .instance/errors.json.

Architecture

Roblox Studio Plugin VS Code Extension
--------------------- -------------------------------
HttpService WebSocket <----> Local WebSocket server :34872
DataModel serializer InstanceStore and FileIndex
Change tracker Explorer and Properties panels
Command router FileSync and FileCommander
GUID attributes Bundled Luau LSP

The extension owns all filesystem work. The Roblox plugin never reads or writes local files because Roblox plugins do not have filesystem access.

Security Notes

• The WebSocket server binds to localhost only.
• Do not commit credentials, secrets, .env files, or user project backups.
• Review .instance/pending-commands.json and the diff panel before pushing risky hierarchy or script changes.
• Treat imported projects and AI-generated changes as untrusted until validated.

License And Ownership

Instance is copyrighted by Logisec.

Unless a separate written license from Logisec says otherwise, the Instance extension, plugin, documentation, assets, and distributed binaries are proprietary and all rights are reserved.

Roblox, Roblox Studio, Visual Studio Code, and other referenced products are trademarks of their respective owners. Instance is not affiliated with, endorsed by, or sponsored by Roblox Corporation or Microsoft.