You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit ed48f75
Browse filesBrowse the repository at this point in the historyBrowse files
feat(skills): porting-to-blender-5 index of every 4.x to 5.x break the pack covers
"Make my add-on work on Blender 5" is one of the most common requests, and
the answers were spread over 19 skills, 11 rules and a dozen examples.
porting-to-blender-5 is a single entry point:
- a headless triage recipe: run on the target version, fix the first
traceback, repeat, then grep for the silent breaks;
- a 21-row table (old code, version, what happens on 5.x, fix), where every
row links to the skill, rule or runnable example that owns the measured
facts;
- the dual-version shim pattern.
Covered: bgl, action.fcurves, use_auto_smooth, Principled sockets,
.sequences, new_effect, ID properties, compositor node_tree, NodesModifier
inputs, Grease Pencil v3, EEVEE id, use_nodes, bl_info, bl_ext names, the
5.2 COLOR strip and evaluated-name changes, and gpu.init.
check_skill_refs verifies every link target exists. Six cross-version
examples now list the skill in examples/skills.json. Counts: 20 skills.
Closes#466
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: TM Hospitality Strategies <TMHospitalityStrategies@gmail.com>
@@ -52,6 +52,7 @@ VERSION - Source of truth for the repo version
52
52
| vse-python | VSE timeline from Python: `.strips` vs `.sequences`, `new_effect` kwargs, 5.2 COLOR `width`/`height` bake |
53
53
| extension-runtime-and-packaging | Bundled wheels, `extension_path_user` data that survives upgrades, `online_access`, `bl_ext` names, `--command extension` build in CI |
54
54
| timers-modal-and-threading |`bpy.app.timers` return values and `persistent`, modal operators on `event_timer_add`, worker thread + queue + main-thread drain, no timers in `--background`|
55
+
| porting-to-blender-5 | Index of every 4.x → 5.x break the pack covers (bgl, `action.fcurves`, `use_auto_smooth`, Principled sockets, `.sequences`, ID properties, compositor, NodesModifier inputs, ...), each linked to the skill, rule or example that owns the fix; headless triage recipe |
55
56
| gpu-drawing-and-overlays |`gpu` instead of the removed `bgl`: `draw_handler_add`/`remove`, builtin shader names, `gpu.state` blending and depth, `POLYLINE_*` line width, `blf` text, `GPUOffScreen` with 5.2's `gpu.init()` headless |
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -288,7 +288,7 @@ The drift-check workflow enforces these on every push and PR.
288
288
289
289
## Aggregate Counts
290
290
291
-
`README.md` declares aggregate counts (e.g. "19 skills, 11 rules, 3 templates, 29 snippets, 69 examples, and 80 showcase pieces"). The `validate-counts` job in `.github/workflows/validate.yml` enforces these substrings against the filesystem on every push and PR. Showcase pieces are counted separately from examples. When you add or remove content, update the README counts in the same commit.
291
+
`README.md` declares aggregate counts (e.g. "20 skills, 11 rules, 3 templates, 29 snippets, 69 examples, and 80 showcase pieces"). The `validate-counts` job in `.github/workflows/validate.yml` enforces these substrings against the filesystem on every push and PR. Showcase pieces are counted separately from examples. When you add or remove content, update the README counts in the same commit.
This repository ships **19 skills, 11 rules, 3 templates, 29 snippets, 69 examples, and 80 showcase pieces** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
47
+
This repository ships **20 skills, 11 rules, 3 templates, 29 snippets, 69 examples, and 80 showcase pieces** for Blender Python development targeting Blender 5.2 LTS (current stable) with Blender 4.5 LTS fallback support. Blender 5.1 is prior stable.
48
48
49
49
The content is consumed by AI coding agents, installed as a plugin or read from a checkout. An optional second plugin registers the official [Blender Lab MCP server](https://www.blender.org/lab/mcp-server/) for live sessions (see [Live Blender session](#live-blender-session-mcp)); the server is referenced from upstream, not part of this repository, and nothing else depends on it. Cursor and Claude Code both install it as a plugin (see [Quick start](#quick-start)): Cursor loads the skills and applies `rules/*.mdc` wherever their scope globs match; Claude Code loads the skills and gets the rules through a generated `blender-rules` skill, since it does not read Cursor `.mdc` files. An agent picks a skill up when its description matches the task. Any agent that can read files in a workspace can use it the same way. There is no build step for the content — edit the Markdown and Python files directly.
50
50
51
51
| Layer | Role |
52
52
| --- | --- |
53
-
|**Skills**| Guided workflows: scaffolding, operators, panels, properties, mesh and bmesh, headless batch, slotted actions, geometry nodes, procedural materials, depsgraph queries, drivers and handlers, `bl_info` migration, video sequencer, imported-mesh cleanup, high-to-low baking, engine export presets, extension runtime and packaging, timers, modal operators and threading, GPU drawing and viewport overlays |
53
+
|**Skills**| Guided workflows: scaffolding, operators, panels, properties, mesh and bmesh, headless batch, slotted actions, geometry nodes, procedural materials, depsgraph queries, drivers and handlers, `bl_info` migration, video sequencer, imported-mesh cleanup, high-to-low baking, engine export presets, extension runtime and packaging, timers, modal operators and threading, GPU drawing and viewport overlays, porting add-ons to Blender 5|
54
54
|**Rules**| Guardrails for the most common AI mistakes: ops-in-loops, bmesh leaks, legacy `bl_info` only, prop assignments, deprecated context-copy override, per-element loops over bulk mesh data, import without scale check, export without evaluated geometry, mixed glTF/FBX axis RNA |
55
55
|**Templates**| A working Extensions Platform add-on starter, a headless batch script starter, and a GLB-in engine-ready asset pipeline |
56
56
|**Snippets**| 29 small standalone Python files demonstrating canonical patterns, 5 to 75 lines each |
@@ -61,14 +61,14 @@ The content is consumed by AI coding agents, installed as a plugin or read from
61
61
62
62
Neither agent needs a clone of `main`: both install the slim `plugin-dist` build. Clone the full repository only to [run the examples or contribute](#run-the-examples-or-contribute).
63
63
64
-
-**Cursor** — install it as a local plugin from the slim `plugin-dist` branch, then run **Developer: Reload Window**. **Customize** lists the 19 skills and 11 rules; the rules apply by glob scope and the agent loads a skill when its description matches the task.
64
+
-**Cursor** — install it as a local plugin from the slim `plugin-dist` branch, then run **Developer: Reload Window**. **Customize** lists the 20 skills and 11 rules; the rules apply by glob scope and the agent loads a skill when its description matches the task.
(On Windows the folder is `%USERPROFILE%\.cursor\plugins\local\`. Cursor skips symlinks that point outside that folder, so clone or copy rather than link.) Teams can import the repository as a team marketplace instead; it carries `.cursor-plugin/marketplace.json`. The plugin already applies the rules, so there is nothing to copy. Only to scope the pack to one project without the plugin, copy `skills/*` into that project's `.cursor/skills/` and `rules/*.mdc` into `.cursor/rules/` from a checkout; copying only the rules gives you no skills.
71
-
-**Claude Code** — install as a plugin, then run `/skills` to see all 19 skills plus `blender-rules`:
71
+
-**Claude Code** — install as a plugin, then run `/skills` to see all 20 skills plus `blender-rules`:
Copy file name to clipboardExpand all lines: ROADMAP.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@
9
9
The skill, rule and example work planned for what the plugin teaches, separate from the
10
10
showcase pool further down. Each item is an open issue; nothing here is pinned to a version.
11
11
12
-
-**New skills:**`porting-to-blender-5`, one index of every 4.x to 5.x break the pack covers ([#466](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/466)); teach the API contracts that shipped examples prove but no skill covers yet, such as Grease Pencil v3, the 5.x compositor, constraints and image pixels ([#456](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/456))
12
+
-**New skills:** teach the API contracts that shipped examples prove but no skill covers yet, such as Grease Pencil v3, the 5.x compositor, constraints and image pixels ([#456](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/456))
13
13
-**Skill corrections:** the full Principled BSDF v2 socket rename table in `procedural-materials-and-shaders` ([#382](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/382))
14
14
-**Verification:** run the shipped snippets and SKILL.md code blocks in CI instead of frozen copies ([#447](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/447)); a weekly, non-gating smoke run against Blender daily builds to catch API breaks before a release ([#457](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/457))
15
15
-**More agents:** first-class support for Codex, Copilot, Windsurf and Gemini through `.agents/skills` and an AGENTS.md rules export ([#376](https://github.com/TMHSDigital/Blender-Developer-Tools/issues/376))
@@ -38,6 +38,7 @@ derives the actual version from conventional-commit types.
"<strong>Claude Code:</strong> <code>/plugin marketplace add TMHSDigital/Blender-Developer-Tools@plugin-dist</code> then <code>/plugin install blender-developer-tools@blender-developer-tools</code>. The 19 skills load when a task matches; the rules come along as the <code>blender-rules</code> skill",
22
-
"<strong>Cursor:</strong> <code>git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git ~/.cursor/plugins/local/blender-developer-tools</code>, then reload the window; Customize lists the 19 skills and 11 rules, and the plugin applies the rules for you. This clones only the 0.3 MB plugin build, not <code>main</code>",
21
+
"<strong>Claude Code:</strong> <code>/plugin marketplace add TMHSDigital/Blender-Developer-Tools@plugin-dist</code> then <code>/plugin install blender-developer-tools@blender-developer-tools</code>. The 20 skills load when a task matches; the rules come along as the <code>blender-rules</code> skill",
22
+
"<strong>Cursor:</strong> <code>git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git ~/.cursor/plugins/local/blender-developer-tools</code>, then reload the window; Customize lists the 20 skills and 11 rules, and the plugin applies the rules for you. This clones only the 0.3 MB plugin build, not <code>main</code>",
23
23
"<strong>Other agents (Codex, Copilot, Windsurf):</strong> clone the same slim build (<code>git clone --branch plugin-dist --single-branch https://github.com/TMHSDigital/Blender-Developer-Tools.git</code>) and copy its <code>skills/*</code> into your agent's skills folder (for example <code>.agents/skills/</code>); point it at <code>claude/blender-rules.md</code> for the rules",
24
24
"<strong>Optional, live session:</strong> <code>/plugin install blender-live-session@blender-developer-tools</code> adds the official Blender Lab MCP server (needs <code>uv</code> and Blender 5.1+ with its add-on) so the agent can inspect and drive your open scene, plus a skill that has it read before it mutates and prove changes headless. See the README's <a href=\"https://github.com/TMHSDigital/Blender-Developer-Tools#live-blender-session-mcp\">Live Blender session</a>",
25
25
"Grab <code>snippets/</code> and <code>templates/</code> as starting points for add-ons and headless batch jobs"
0 commit comments