by sixtysevenlf
DSH x Blender direct realtime plugin - let an AI model drive Blender over a direct TCP channel: viewport frames, custom-angle renders, inner-loop search, render profiling, safe decimation, headless offload.
# Add to your Claude Code skills
git clone https://github.com/sixtysevenlf/dsh-blender-pluginGuides for using ai agents skills like dsh-blender-plugin.
See how dsh-blender-plugin compares with popular alternatives.
dsh-blender-plugin is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by sixtysevenlf. DSH x Blender direct realtime plugin - let an AI model drive Blender over a direct TCP channel: viewport frames, custom-angle renders, inner-loop search, render profiling, safe decimation, headless offload. It has 51 GitHub stars.
dsh-blender-plugin's catalog security scan is still queued. You can run an instant dependency and prompt-injection check now with the "Scan for vulnerabilities" button above.
Clone the repository with "git clone https://github.com/sixtysevenlf/dsh-blender-plugin" and add it to your Claude Code skills directory (see the Installation section above).
dsh-blender-plugin is primarily written in Python. It is open-source under sixtysevenlf on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh dsh-blender-plugin against similar tools.
No comments yet. Be the first to share your thoughts!
Unlocks once the catalog security scan passes (runs nightly).
⚠️ Third-Party Software Notice
This skill is third-party open-source software developed and hosted independently on GitHub. SkillsLLM is an informational directory and does not control or maintain the underlying repository.
Any security checks, ratings, or warnings displayed by SkillsLLM are automated and limited in scope. They do not constitute a security certification or guarantee that the software is safe, error-free, or free from malicious code, vulnerabilities, compromised dependencies, or prompt-injection risks.
Review the source code, permissions, dependencies, and configuration before installing or running any third-party skill. Use is at your own risk. To the maximum extent permitted by applicable law, SkillsLLM is not liable for losses arising from third-party software.
The deep catalog scan for this skill is still queued. Run an instant dependency check now instead.
🌐 Language: English (this page) · 简体中文
Let an AI model actually drive Blender — no clicking, no screenshots-into-prompt, no MCP server. One direct TCP channel gives the model 10 primitives: see the viewport / edit the scene / watch over time / run an inner search loop / profile & fix render perf / decimate objects safely / offload heavy work to a headless process / operate the channel itself.
Version 0.8.0 — default render engine is now EEVEE + ray tracing (GPU-only, no device-preference dependency; measured 1.35 s vs 3.13 s per warm frame against Cycles GPU). — hardening from real-world feedback: GPU semantics (headless Cycles silently fell back to CPU — measured 15.4×), a hot headless session (
blender_rt_worker), streaming long calls (clientfetchheaders timeout is 300 s — measuredUND_ERR_HEADERS_TIMEOUT), structured failures, and artifact filtering. See §4.6.Version 0.5.0 — adds a contract layer (hypotheses / ranges / checks / evidence / destructive-op gating) and a planner (Component·Connection·Feature graph compiled to bpy), exposed through the new
blender_rt_plantool. See §4.5.Version 0.4.1 — adds an addon protocol adapter (
addonProtocol, defaultauto), so both the flatMCP for Blenderaddon and theharveyxiacn/blender-mcpcategory/action addon work (contributed by @yihefeikong-rgb, PR #2).Version 0.4.0 · ships its own runtime (Node + Python), all paths resolved relative to the package, and nothing is hard-coded to a specific machine (
runtime/config.mjsdoes env → config file → auto-detect → defaults).
| Capability | Tool | Typical latency |
|---|---|---|
| Peek at the viewport | blender_rt_see |
50–100 ms |
| Render from any angle (no camera object, user viewport untouched) | blender_rt_see {from, look_at, ...} |
85–280 ms |
| Change one thing and verify it | blender_rt_do {see:true} |
≈105 ms |
| Did it move? Is it right? | blender_rt_watch |
≤6 frames/call |
| Inner loop search (thousands of iterations, zero model turns) | blender_rt_loop |
160 ticks/s |
| Pass through any addon command / list them | blender_rt_cmd / blender_rt_commands |
25–55 ms |
| Render performance profiling + preset | blender_rt_perf |
analyze ≈10–20 s |
| Object decimation (safe join, zero geometry loss) | blender_rt_opt |
≈1.4 ms/object |
| Headless process for heavy renders / batch geometry | blender_rt_headless |
cold start 0.8 s |
| Contract layer + planner | blender_rt_plan |
AABB sweep 24 ms · BVH 0.17 ms/pair (307 objects) |
| Hot headless session | blender_rt_worker |
|
| Transactions / rollback | blender_rt_txn |
snapshot 96.7 MB / 824 ms (300 objects) · mark→revert verified |
| 配方库 / Presets | blender_rt_preset |
存/套用/导出参数配方；实测 720 → 640 真实生效 |
| Channel health check / write lease | blender_viewport |
health 70–100 ms |
Detailed walkthrough (Chinese, 377 lines): docs/操作教程.md · configuration reference (Chinese): docs/配置参考.md. This README covers the same ground in condensed English.
-b is only used by the headless tool).MCP for Blender (not bundled) listening on 127.0.0.1:9876. It must provide at least:
ping, get_scene_info, get_world_state_snapshot, get_object_info(name), get_viewport_screenshot(max_size, filepath, format), execute_code(code).
The harveyxiacn enhanced blender_mcp_addon is also supported (different wire protocol — the plugin adapts automatically; addonProtocol, default auto, see docs/配置参考.md §6). That implementation has none of the five asset integrations, and the corresponding commands fail loudly instead of pretending.
Enable it in Blender, then in a 3D viewport press N → MCP for Blender panel → Connect.
Compatibility probe: node runtime/_probe_tools.mjs. Protocol self-test (no Blender needed): node tests/protocol_selftest.mjs.inject: ['tools']).
Works both with DSH in WSL + Blender on Windows (WSL interop is used to spawn blender.exe) and with DSH and Blender on the same Windows machine (path mapping degrades gracefully).# 1) Build (needs a DSH source checkout to link cordis/schemastery/dsh-tools)
cd dsh-blender-plugin
DSH_CHECKOUT=/path/to/dsh-harness bash scripts/build.sh # produces lib/
# 2) (optional) configure — auto-detection usually just works
cp dsh-blender.config.example.json dsh-blender.config.json
# 3) Inject into DSH (dsh-super-injector dev tools; or wire it into your profile bundles)
# dev_build_plugin {"dir":"<absolute path to this package>"}
# dev_inject_plugin {"dir":"<absolute path to this package>"}
# 4) Start Blender → press N → "MCP for Blender" → Connect (127.0.0.1:9876)
# 5) Verify
curl -sS http://127.0.0.1:9877/health # backend alive
curl -sS http://127.0.0.1:9877/doctor # FULL round-trip through bpy; "kind":"ok" is the goal
curl -sS http://127.0.0.1:9877/who # write lease + channel metrics + effective config
The plugin auto-starts the backend (node runtime/server.mjs, default 127.0.0.1:9877) and runs a 15-second watchdog that respawns it if it dies. blender_viewport op=stop pauses the watchdog.
blender_viewport(op="doctor") # health + effective config
blender_rt_see(max_size=560) # what the model sees right now
blender_rt_see(from="9,-9,6", look_at="0,0,1") # a different angle, user viewport untouched
Four issues reported by a heavy user (22 modelling rounds, 45 pipelines) — all reproduced and fixed:
| Issue | What we measured | What changed |
|---|---|---|
| Headless renders on CPU silently | 1821-object project, 480×270/32spp: CPU 2.78 s vs GPU 0.18 s warm = 15.4×; --factory-startup clears preferences and even factory_startup=false did not inherit them |
gpu:"auto" prelude (OPTIX→CUDA→HIP→ONEAPI→METAL), explicit gpu field in every result (before/after/configured/fell_back_to_cpu), use_user_config:true forwards BLENDER_USER_CONFIG/SCRIPTS; gpu:"true" fails loudly when no GPU exists |
| No hot headless session | the addon's socket server returns early in background, so headless meant a cold process every time |
new runtime/worker.py + tool blender_rt_worker: a resident blender -b with a blocking accept loop on the main thread (timers never fire headless — measured 0 in 1.2 s) and the persistent kernel K (K.n survives across exec calls) |
Long calls die with fetch failed |
client fetch headers timeout = 300 s (independent probe: 330 s delay → fetch failed after 300.9s, cause=UND_ERR_HEADERS_TIMEOUT); and a client abort does not kill the server-side child (artifacts still land) |
/headless and /worker now stream ndjson: headers immediately + 15 s heartbeats + the result as the last line |
| Opaque failures & noisy artifacts | — | full stdout/stderr written to files (logs.*), lastException + traceback extracted, reason field, a hint when a script contains a literal \n, and outdir filtering of `pycache / *.pyc / *.blend1 |
Long-task semantics: a client timeout/abort is not a task failure — the server-side child keeps running, artifacts still land in outdir and the log paths are returned. For work beyond ~5 minutes prefer the hot worker session or write results to a file.
blender_rt_txn: file-level snapshot/restore (copy=True, so the current filepath is untouched; measured 96.7 MB / 824 ms on a 300-object scene) and object-level mark/revert (transforms, materials, visibility, modifier flags — no topology/UV changes).runtime/qc.py, exposed as blender_rt_plan(op="qc_compare") (plus qc_compare_basic, qc_self_check, qc_robustness_check, qc_help). Optimized beyond the reference implementation: adaptive mask (alpha detection / border-estimated background + Otsu), centroid alignment with a scale+shift search, actionable metrics (Dice / missing / extra / boundary distance / per-band profile), and anti-gaming guards (iou vs iou_fixed, scale-drift warning, fixed alignment inside the optimizer loop). Self-check: self-IoU 1.0000, 12 px shift still 1.0000; a 12 px + 6% perturbation collapses the naive metric to 0.534 while the searched one holds 0.866./headless, /worker, /txn and /preset write a {"heartbeat":true} NDJSON line every 15 s before the final object, but the client used to JSON.parse the whole body: any call longer than 15 s degraded to exit=undefined even though the subprocess had finished (exitCode=0). The client now takes the last non-heartbeat JSON line and reports the heartbeat count. Measured: a 20 s script went from HEADLESS 失败 · exit=undefined · undefinedms to HEADLESS ok · exit=0 · 21406 ms with the full result/logs; a 20 s rt_worker op=exec now returns WORKER exec ok · 20000ms. Same release: job-layer preload, quoted args, a zero-size image guard (GIF is silently decoded as 0×0 by Blender), two new error hints (stale StructRNA references after open_mainfile, context is incorrect), and a hint to use as_job