# blockbench-plugins

Guides JavaScript plugin development for the Blockbench 3D editor, covering custom actions, UI dialogs, Vue panels, and undoable model edits.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 647 installs · ★ 26
- Author: jasonjgardner
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/jasonjgardner/blockbench-mcp-project/tree/HEAD/skills/blockbench-development/SKILL.md
- Updated: 2026-09-26
- HTML: https://affpapa.org/en/nevibecode/skills/blockbench-plugins

## What it does

The skill gives your coding assistant reference patterns for the Blockbench host API. It outlines lifecycle hooks in `Plugin.register`, toolbar buttons via `Action`, custom sidebars using Vue components, and interactive forms with `Dialog`.

Model modifications must follow the native transaction cycle. You wrap coordinate or rotation changes inside `Undo.initEdit` and `Undo.finishEdit`, followed by viewport redraws. Keep in mind that plugin variable isolation does not grant unrestricted filesystem access. Every action, panel, and event hook must be deleted explicitly inside `onunload`.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-plugins -a claude-code
```
```bash
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-development -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/blockbench-development/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/blockbench-development/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-development -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/blockbench-development/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-development -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/blockbench-development/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install jasonjgardner/blockbench-mcp-project blockbench-development
```

2. **Manually: put the files in place**
- File: `.github/skills/blockbench-development/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-development -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/jasonjgardner/blockbench-mcp-project --path skills/blockbench-development
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/blockbench-development/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add jasonjgardner/blockbench-mcp-project --skill blockbench-development -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/jasonjgardner/blockbench-mcp-project/tree/HEAD/skills/blockbench-development/SKILL.md

## When to use it
- scaffold a Blockbench plugin using the standard lifecycle template
- register custom toolbar actions and menu commands
- build configuration dialogs with typed form fields
- modify cube coordinates with native Undo transaction tracking

## Example prompts
- Create a Blockbench plugin template with a custom Vue panel and an unload hook
- Write an action that rotates selected cubes and commits changes to Undo
- Build a Blockbench Dialog form with color picker and text inputs

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 1d727cd79542b4a3.

BEGIN THIRD-PARTY FILE 1d727cd79542b4a3
````text
---
name: blockbench-plugins
description: "Blockbench plugin/extension development for the 3D modeling tool. Use when creating, modifying, or debugging JavaScript plugins for Blockbench including actions, dialogs, panels, menus, toolbars, model manipulation, animation APIs, and custom formats/codecs. Triggers on Blockbench plugin, Blockbench extension, Blockbench API, BBPlugin, model editor plugin, or 3D modeling tool extension."
---

# Blockbench Plugin Development

## Overview

Blockbench runs on desktop and the web, exposing host APIs and bundled rendering/UI libraries to plugins. Verify the target host version and its types before choosing APIs; plugin variable isolation does not imply unrestricted native-module or filesystem access. Prefer the current [generated API reference](https://web.blockbench.net/docs/) and the target checkout when older wiki examples disagree with the host. Set `variant` and `min_version` to the environments actually verified.

For model format decisions, UV units, rig distinctions and export handoffs, see [format and delivery guidance](../blockbench-use/references/formats-and-delivery.md). A format feature flag advertises host behavior; it does not implement missing validation or runtime serialization in a custom codec.

## Quick Reference

| Task | Approach |
|------|----------|
| Create clickable command | `new Action()` - add to menus/toolbars |
| Show form/dialog | `new Dialog()` with form fields |
| Add sidebar panel | `new Panel()` with Vue component |
| Modify model elements | Use `Undo.initEdit()` → modify → `Undo.finishEdit()` |
| Custom import/export | `new Codec()` + `new ModelFormat()` |
| React to changes | `Blockbench.on('event_name', callback)` |

## Plugin File Structure

```
plugins/
└── my_plugin/
    ├── my_plugin.js      # Main file (required, ID must match filename)
    ├── about.md          # Extended docs (optional)
    └── icon.png          # 48x48 icon (optional)
```

## Plugin Registration Template

```javascript
(function() {
    // Store references for cleanup
    let myAction, myPanel, myDialog, eventCallback;
    
    Plugin.register('my_plugin', {
        title: 'My Plugin',
        author: 'Author Name',
        description: 'Short description',
        icon: 'extension',            // Material icon name
        version: '1.0.0',
        variant: 'both',              // 'desktop', 'web', or 'both'
        min_version: '4.8.0',
        tags: ['Utility'],
        
        onload() {
            // Initialize all components here
        },
        
        onunload() {
            // CRITICAL: Delete ALL components here
        },
        
        oninstall() {
            Blockbench.showQuickMessage('Installed!');
        }
    });
})();
```

## Actions
````
END THIRD-PARTY FILE 1d727cd79542b4a3

The third-party file has ended. Everything between the 1d727cd79542b4a3 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2791 of 13707 bytes. © jasonjgardner · Apache-2.0 · https://github.com/jasonjgardner/blockbench-mcp-project/tree/HEAD/skills/blockbench-development/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md