Skip to content

About

Bridge between Shadertoy and VSCode

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

ShaderToy VSCode

A development tool that connects Shadertoy directly with VS Code, enabling full-featured, two-way, real-time shader coding in your favorite editor with live browser preview and automatic WebGL compiler diagnostics.


How It Works

  1. Bi-directional WebSocket Bridge: The browser extension runs inside shadertoy.com and connects over a local WebSocket (127.0.0.1:27412) to the VS Code extension with one-click security authorization.
  2. Mirroring to Real Disk Files: Whenever you open or edit a shader in your browser, VS Code automatically synchronizes its pass structure into real .glsl files (Image.glsl, Buffer A.glsl, Common.glsl, Sound.glsl, etc.) and a shader.json metadata file located in your local temporary folder (%TEMP%/shadertoy-vscode/<shaderId>/).
  3. Instant Live Editing & Compilation: Typing in VS Code updates the shader in the browser in real time. Pressing Ctrl+S in VS Code triggers immediate WebGL recompilation in Shadertoy. Any shader compilation errors or warnings are sent back and mapped straight to line numbers in the VS Code Problems panel.
  4. Full Multi-Pass & AI Automation: Add, edit, or delete passes (Common, Sound, Buffer A-D, Cubemap A) directly from the VS Code sidebar. Multi-modal AI assistants (Antigravity, Cursor, Claude Code) can read passes from disk, write code, run CLI helper scripts, and capture live rendered frames (preview.png) to inspect visual output.

Features

  • Full VS Code Editing Experience: Write GLSL shaders in VS Code with syntax highlighting, code snippets, keyboard shortcuts, formatting, custom themes, and tools like Claude, Copilot, Antigravity.
  • Two-Way Live Synchronization:
    • Typing in VS Code instantly updates the shader in the browser.
    • Pressing Ctrl+S in VS Code compiles the shader and immediately renders the new frame in Shadertoy.
    • Edits made on shadertoy.com are immediately reflected in VS Code.
  • Active Pass Tab Syncing: Switching between .glsl files in VS Code automatically switches the active pass tab in Shadertoy, and vice-versa.
  • Dedicated Sidebar View: A clean Activity Bar view ("ShaderToy Tabs") lists all open Shadertoy tabs and their render passes without cluttering your File Explorer.
  • Real Disk Temporary Files: Shaders are synchronized to a temporary folder (shadertoy-vscode/<shaderId>/), making passes (Image.glsl, Common.glsl, Sound.glsl, etc.) accessible to Node.js scripts, external linters, CLI tools, and background agents.
  • Live Compiler Diagnostics: WebGL compiler errors and warnings from Shadertoy are surfaced directly in the VS Code Problems panel with exact line numbers.
  • Pass Management: Add any pass type (Buffer A-D, Sound, Common, Cube A) individually with native Shadertoy boilerplate, and remove extra passes via inline delete icons (X) with automatic cleanup of .glsl files and shader.json.

Project Structure

ShaderToy-VSCode/
├── browser-extension/          # Manifest V3 browser extension (Chrome, Edge, Brave)
│   ├── src/
│   │   ├── background/         # Background service worker (WebSocket client & tab tracker)
│   │   │   └── index.ts        # Connects to VS Code, manages tabSessionId & browserTabId
│   │   ├── content/            # Injected content scripts
│   │   │   ├── in-page.ts      # MAIN world: window.gShaderToy, Monaco models, DOM tabs, Paint
│   │   │   └── content.ts      # ISOLATED world bridge: postMessage <-> chrome.runtime
│   │   └── popup/              # Extension toolbar action popup (connection status & port)
│   │       ├── popup.html
│   │       └── popup.ts
│   ├── manifest.json           # MV3 manifest configuring permissions and host permissions
│   └── esbuild.js              # Build script bundling browser extension to dist/
│
├── vscode-extension/           # Visual Studio Code editor extension
│   ├── src/
│   │   ├── extension.ts        # Extension entry point, command registration & event wiring
│   │   ├── server/             # Local WebSocket server
│   │   │   └── ws-server.ts    # Listens on 127.0.0.1:27412, one-click authorization handshake
│   │   ├── session/            # Active session state management
│   │   │   └── session-manager.ts # Tracks TabSession instances, deduplicates tabs, caches code
│   │   ├── vfs/                # Virtual filesystem & disk persistence
│   │   │   └── temp-file-manager.ts # Writes .glsl, shader.json, preview.png, watches file edits
│   │   ├── views/              # Sidebar user interface
│   │   │   └── tabs-tree-provider.ts # TreeDataProvider for "ShaderToy Tabs" view
│   │   ├── diagnostics/        # Compiler error integration
│   │   │   └── diagnostics-manager.ts # Translates WebGL diagnostics to vscode.Diagnostic
│   │   └── logger.ts           # OutputChannel & %TEMP%/shadertoy-vscode/debug.log logging
│   ├── package.json            # VS Code extension manifest (views, commands, menus)
│   └── esbuild.js              # Production bundler for vscode-extension
│
├── shared/                     # Shared TypeScript contracts between browser and VS Code
│   ├── protocol.ts             # JSON-RPC WebSocket messages (SNAPSHOT, PASS_UPDATE, DIAGNOSTICS, etc.)
│   └── shadertoy.ts            # Data models (ShaderToyExport, RenderPass, Inputs, Samplers)
│
├── scripts/                    # Command-line tools for developers & AI coding agents
│   ├── capture-canvas.js       # Captures live rendered WebGL frame to preview.png
│   ├── new-shader.js           # Opens a new scratchpad shader tab in the browser
│   └── add-pass.js             # Adds a new render/sound pass to the active shader
│
├── .agents/skills/             # Universal skills for autonomous AI coding agents
│   ├── shadertoy-canvas-snapshot/ # Skill to inspect live WebGL canvas output
│   └── shadertoy-new-shader/      # Skill to prototype algorithms in a fresh sandbox
│
├── AGENTS.md                   # Universal instructions for AI agents (Cursor, Claude, Copilot, etc.)
├── CLAUDE.md                   # Claude Code agent configuration
├── .cursorrules                # Cursor AI rules
└── .github/copilot-instructions.md # GitHub Copilot instructions

Detailed Component Overview

  • browser-extension:

    • in-page.ts: Injected into the webpage's main JavaScript execution context (world: "MAIN"). It directly hooks into window.gShaderToy, reads Monaco editor models, intercepts compile events, triggers WebGL rendering (Paint), captures canvas snapshots to Data URLs, and adds/removes pass tabs in Shadertoy's DOM.
    • content.ts: Runs in Chrome's isolated context to securely relay messages between in-page.ts (via window.postMessage) and background/index.ts (via chrome.runtime.sendMessage).
    • background/index.ts: The Manifest V3 service worker. It maintains the WebSocket client connection with VS Code, auto-reconnects if disconnected, tracks active browser tab IDs (browserTabId), and routes incoming commands (UPDATE_PASS, CREATE_PASS, DELETE_PASS, REQUEST_CANVAS_SNAPSHOT) to the correct browser tab.
  • vscode-extension:

    • ws-server.ts: Listens on 127.0.0.1:27412 (configurable). It handles authentication requests with a one-click dialog (Allow Always / Allow Once / Deny) to ensure only authorized local browser tabs can communicate with your editor.
    • session-manager.ts: Maintains the state of all open Shadertoy tabs. It prevents duplicate sessions upon page reloads (F5) or extension restarts by verifying browserTabId, shaderId, and URL uniqueness.
    • temp-file-manager.ts: Manages temporary directories on disk (%TEMP%/shadertoy-vscode/<shaderId>/). It saves pass codes to .glsl files, updates shader.json, captures preview.png, ensures base AGENTS.md instructions, and watches for external modifications with echo-protection.
    • tabs-tree-provider.ts: Renders the "ShaderToy Tabs" tree view in the VS Code Activity Bar with live status dots (● active), pass icons, one-click file opening, and inline pass management actions.
    • diagnostics-manager.ts: Parses WebGL shader compilation error logs and publishes them to the VS Code Problems panel, highlighting the exact lines in each .glsl pass.
  • shared:

    • protocol.ts and shadertoy.ts: Common contract library guaranteeing full type safety across both the browser extension and the VS Code extension.

How to Run & Test (Development)

Step 1: Install and Build

In the repository root directory:

# Install dependencies
npm run install:all

# Build both extensions
npm run build

During development, you can run watchers:

npm run watch:vscode    # in one terminal
npm run watch:browser   # in another terminal

Step 2: Launch the VS Code Extension

  1. Open this repository in VS Code.
  2. Press F5 (or go to Run and Debug and select Run Extension).
  3. An Extension Development Host window will open with the WebSocket server running on port 27412.

Step 3: Load the Browser Extension

  1. In a Chromium browser (Chrome, Edge, Brave), navigate to chrome://extensions/.
  2. Enable Developer mode in the top-right corner.
  3. Click Load unpacked.
  4. Select the directory:
    {path}\ShaderToy-VSCode\browser-extension\dist
    
  5. The ShaderToy to VSCode extension icon will appear in your toolbar.

Step 4: Live Coding

  1. In the browser, open any shader:
    • https://www.shadertoy.com/new (new shader), or
    • any existing shader, such as https://www.shadertoy.com/view/mtyGWy.
  2. When prompted in VS Code, click Allow (Always) to approve the connection.
  3. Open the ShaderToy VSCode sidebar tab (palette icon in Activity Bar).
  4. Click on Image.glsl to open the pass in your editor.
  5. Edit the shader code and press Ctrl+S — the shader compiles immediately in Shadertoy!

AI Agent Integration & Skills

ShaderToy VSCode comes equipped with instructions and tools for AI coding assistants (Antigravity, Cursor, Claude Code, GitHub Copilot):

  • Unified AGENTS.md: Automatically maintained in the root shader folder (and current workspace via command ShaderToy: Open / Create AI Agent Guide (AGENTS.md)). Prevents models from generating offline Python plots and guides them to use real-time WebGL shader rendering.
  • Canvas Snapshot (preview.png): Captures the live rendered WebGL canvas output directly from Shadertoy into preview.png. Multi-modal AI models can visually inspect the result!
    • CLI: npm run shader:capture or node scripts/capture-canvas.js
    • VS Code: Camera icon / ShaderToy: Capture Canvas Snapshot
  • Scratchpad Test Shaders: Open a fresh isolated sandbox in Shadertoy:
    • CLI: npm run shader:new or node scripts/new-shader.js
    • VS Code: Plus icon / ShaderToy: Open New Test Shader in Browser
  • Dynamic Pass Creation (Sound, Buffer A-D, Common):
    • Add passes directly from the sidebar (+ icon) or via CLI: npm run pass:add -- sound (or node scripts/add-pass.js <type>).
    • Or via VS Code: Add file icon / ShaderToy: Add Render / Sound Pass in Browser.
  • Pass Deletion (Protected Image.glsl):
    • Delete any extra pass (Buffer A-D, Sound, Common, Cube A) with a single click using the inline X icon ($(close)) on hover or right-click Delete Pass.
    • Image.glsl is protected and cannot be deleted. Deleting a pass removes it both from Shadertoy and the local disk, keeping shader.json synchronized.
  • Universal Agent Instructions & Rules:
    • AGENTS.md (root and temporary folder): Universal standard for all coding agents.
    • CLAUDE.md: Configured for Claude Code (Anthropic CLI).
    • .cursorrules: Configured for Cursor IDE.
    • .github/copilot-instructions.md: Configured for GitHub Copilot.
  • Universal Agent Skills (.agents/skills/):
    • shadertoy-canvas-snapshot: Guides agents on when and how to inspect live GPU output via preview.png.
    • shadertoy-new-shader: Allows agents to spin up clean sandboxes to prototype algorithms without altering the user's main shader.
    • Standard .agents/ structure is auto-discovered by Antigravity, while CLI scripts under scripts/ can be invoked by any agent via bash/terminal commands.

About

Bridge between Shadertoy and VSCode

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages