jasonjgardner/blockbench-use

Blockbench Use

Orchestrator for Blockbench MCP work. Load this before touching the 3D scene so the right sub-skills load and the right pre-flight checks run.

Rule

Any request that will call an mcp__blockbench__* tool to create or modify content must go through this skill first.

Steps, in order:

1. Classify the request → pick one or more sub-skills (table below).
2. Pre-flight → confirm a project is open and the format is correct (see "Pre-flight checks").
3. Load the sub-skill(s) via the Skill tool.
4. Checkpoint before risk → call save_checkpoint for multi-step edits that might need rollback.
5. Execute the sub-skill's workflow.
6. Close the loop → screenshot, validate (Hytale), or export if the user asked for a deliverable.

Skill routing table

Pick by primary intent. When the task spans domains, load all relevant skills before starting.

| User intent | Primary skill | Also load when… | |---|---|---| | Build cubes, meshes, groups, hierarchy | blockbench-modeling | needs texture → blockbench-texturing | | Paint, fill, draw, brush, layers, UV | blockbench-texturing | channel-aware (normal/MER) → blockbench-pbr-materials | | Keyframes, bone rigs, walk/idle/attack | blockbench-animation | bones need geometry first → blockbench-modeling | | .texture_set.json, normal/height/MER | blockbench-pbr-materials | textures not yet drawn → blockbench-texturing | | .blockymodel, .blockyanim, attachments, quads, stretch, shading modes | blockbench-hytale | modeling/animation parts → those skills | | "What tools are available?" / unclear scope | blockbench-mcp-overview | — | | Write a Blockbench JS plugin (not use MCP) | blockbench-plugins (from blockbench-development/) | — |

Skip this skill for pure research questions (API docs, "how does Blockbench work?"). Go straight to blockbench-mcp-overview.

Pre-flight checks

Run before any mutation. One round of list_outline + list_textures is usually enough.

1. Is a project open? If no project, call create_project first (format from the routing table below).
2. Is the format correct for the task?
   • Cube modeling (Minecraft) → bedrock_block, java_block, bedrock
   • Mesh/freeform → free, modded_entity, optifine_entity
   • Hytale character → hytale_character (64px)
   • Hytale prop → hytale_prop (32px)
   • Generic → generic or free
3. What's already there? Use list_outline (structure) + list_textures (materials). Prefer find_elements_by_criteria / filter_by_material over dumping the whole outline for large projects.
4. Hytale project? Run hytale_validate_model at the end; never silently exceed 255 nodes.

Multi-skill workflow compositions

"Create a Minecraft character with a walk cycle"

blockbench-modeling    → bones + cubes
blockbench-texturing   → skin texture
blockbench-animation   → walk cycle keyframes
# finally:
capture_screenshot     → preview
export_model: codec_id="project"  → save .bbmodel

"Make a Bedrock RTX block"

blockbench-modeling        → single cube
blockbench-texturing       → color map
blockbench-pbr-materials   → normal + MER + texture_set.json
# finally:
hytale_validate_model      → (skip — not Hytale)
capture_screenshot

"Build a Hytale character with attachments"

blockbench-hytale          → read first: format, node limits, pieces
blockbench-modeling        → geometry in character format
blockbench-animation       → optional keyframes (60 FPS)
# separately per attachment collection:
blockbench-hytale          → hytale_set_attachment_piece on bones
# finally:
hytale_validate_model      → node count, stretch, shading
export_model: codec_id="blockymodel"

"Retexture an existing model"

# Pre-flight: find everything that uses the old texture
filter_by_material: texture="old_skin"
# Load:
blockbench-texturing       → paint/create replacement
# Swap references:
apply_texture per match (from filter_by_material results)

Safety & efficiency rules (apply in every session)

1. Checkpoint before risk. For any workflow of 3+ mutations, call save_checkpoint: name="<descriptive>" first. If the result is wrong, undo: steps=N back.
2. Filter, don't dump. Prefer find_elements_by_criteria, filter_by_material, or select_all_of_type over list_outline when you know the shape of what you want. Large outlines blow context.
3. Respect the format. Don't call Hytale tools on a non-Hytale project — they will error. Check Format.id via risky_eval or hytale_get_format_info if unsure.
4. Screenshot after meaningful changes. capture_screenshot confirms the model looks right. Do it at milestones, not every edit.
5. Export only when the user asks for a deliverable. Use list_export_formats first to pick the right codec, then export_model with a path (or content-only if the user just wants to see it).
6. Never call trigger_action: action="undo" or "redo". Use the dedicated undo / redo tools — they return which actions were traversed.
7. Name everything. Descriptive names make find_elements_by_criteria and filtering work later.

When to load blockbench-mcp-overview

Load it instead of a specialized skill when:

• The user's intent is ambiguous ("help me with this model")
• The tool call count will be small (<5) and spans multiple domains
• The user is asking about capabilities, not executing

Otherwise prefer the specialized skills — they have concrete examples and return shapes.

What this skill does NOT cover

• Blockbench plugin development (writing .js plugins) → blockbench-plugins
• MCP server development (adding tools to this repo) → not in this skill set
• General 3D theory / THREE.js / rendering internals → out of scope