@punal_manalan/blender-project-harness 0.0.0-stage → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/.kilo/agent/blender-grader.md +197 -0
  2. package/.kilo/agent/blender-worker.md +127 -0
  3. package/.kilo/blender-project-harness/config.example.json +71 -0
  4. package/.kilo/blender-project-harness/tools/harness/EXPECTED_FLOW.md +656 -0
  5. package/.kilo/blender-project-harness/tools/harness/blender-operations.mjs +882 -0
  6. package/.kilo/blender-project-harness/tools/harness/blender-operations.test.mjs +550 -0
  7. package/.kilo/blender-project-harness/tools/harness/blender.mjs +301 -0
  8. package/.kilo/blender-project-harness/tools/harness/blender.test.mjs +87 -0
  9. package/.kilo/blender-project-harness/tools/harness/cli.mjs +127 -0
  10. package/.kilo/blender-project-harness/tools/harness/documents.mjs +201 -0
  11. package/.kilo/blender-project-harness/tools/harness/download.mjs +94 -0
  12. package/.kilo/blender-project-harness/tools/harness/download.test.mjs +63 -0
  13. package/.kilo/blender-project-harness/tools/harness/engine.mjs +1866 -0
  14. package/.kilo/blender-project-harness/tools/harness/engine.test.mjs +2219 -0
  15. package/.kilo/blender-project-harness/tools/harness/intake.mjs +571 -0
  16. package/.kilo/blender-project-harness/tools/harness/intake.test.mjs +181 -0
  17. package/.kilo/blender-project-harness/tools/harness/package-lock.json +1227 -0
  18. package/.kilo/blender-project-harness/tools/harness/package.json +15 -0
  19. package/.kilo/blender-project-harness/tools/harness/plugin.mjs +550 -0
  20. package/.kilo/blender-project-harness/tools/harness/plugin.test.mjs +526 -0
  21. package/.kilo/blender-project-harness/tools/harness/proxy.mjs +222 -0
  22. package/.kilo/blender-project-harness/tools/harness/proxy.test.mjs +217 -0
  23. package/.kilo/blender-project-harness/tools/harness/scaffold.mjs +83 -0
  24. package/.kilo/blender-project-harness/tools/harness/scaffold.test.mjs +74 -0
  25. package/.kilo/blender-project-harness/tools/harness/server.mjs +24 -0
  26. package/.kilo/blender-project-harness/tools/harness/shell-policy.mjs +196 -0
  27. package/.kilo/blender-project-harness/tools/harness/shell-policy.test.mjs +68 -0
  28. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/ASSETS.md +29 -0
  29. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/DECISIONS.md +8 -0
  30. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Goals/01-project-brief.md +71 -0
  31. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Goals/README.md +17 -0
  32. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/INTAKE.md +8 -0
  33. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/README.md +57 -0
  34. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/REQUIREMENTS.md +64 -0
  35. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/REVIEW.md +29 -0
  36. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/References/README.md +18 -0
  37. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Reviews/README.md +48 -0
  38. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/TASKSTRACKER.md +10 -0
  39. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Tasks/README.md +4 -0
  40. package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/WORKFLOW.md +36 -0
  41. package/.kilo/blender-project-harness/tools/harness/templates/project/README.md +130 -0
  42. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/README.md +31 -0
  43. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/audio/.gitkeep +0 -0
  44. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/external/README.md +43 -0
  45. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/external/SOURCE_TEMPLATE.md +18 -0
  46. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/hdri/.gitkeep +0 -0
  47. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/models/.gitkeep +0 -0
  48. package/.kilo/blender-project-harness/tools/harness/templates/project/assets/textures/.gitkeep +0 -0
  49. package/.kilo/blender-project-harness/tools/harness/templates/project/backups/.gitkeep +0 -0
  50. package/.kilo/blender-project-harness/tools/harness/templates/project/backups/README.md +5 -0
  51. package/.kilo/blender-project-harness/tools/harness/templates/project/exports/.gitkeep +0 -0
  52. package/.kilo/blender-project-harness/tools/harness/templates/project/exports/README.md +11 -0
  53. package/.kilo/blender-project-harness/tools/harness/templates/project/renders/README.md +7 -0
  54. package/.kilo/blender-project-harness/tools/harness/templates/project/renders/final/.gitkeep +0 -0
  55. package/.kilo/blender-project-harness/tools/harness/templates/project/renders/wip/.gitkeep +0 -0
  56. package/.kilo/blender-project-harness/tools/harness/templates/project/scenes/README.md +10 -0
  57. package/.kilo/blender-project-harness/tools/harness/templates/project/scripts/README.md +16 -0
  58. package/.kilo/blender-project-harness/tools/harness/test-fixture.mjs +91 -0
  59. package/.kilo/blender-project-harness/tools/harness/workspace.mjs +30 -0
  60. package/.kilo/blender-project-harness/tools/harness/workspace.test.mjs +31 -0
  61. package/.kilo/blender-project-harness/tools/test_blender_tools.py +427 -0
  62. package/.kilo/plugins/blender-workflow.js +3 -0
  63. package/.kilo/skills/blender-assets/SKILL.md +99 -0
  64. package/.kilo/skills/blender-mcp/SKILL.md +147 -0
  65. package/.kilo/skills/blender-mcp/references/README.md +22 -0
  66. package/.kilo/skills/blender-mcp/references/animation.md +83 -0
  67. package/.kilo/skills/blender-mcp/references/bpy.md +97 -0
  68. package/.kilo/skills/blender-mcp/references/level-design.md +53 -0
  69. package/.kilo/skills/blender-mcp/references/materials.md +80 -0
  70. package/.kilo/skills/blender-mcp/references/retopology.md +104 -0
  71. package/.kilo/skills/blender-mcp/references/rigging.md +123 -0
  72. package/.kilo/skills/blender-mcp/references/scene.md +72 -0
  73. package/.kilo/skills/blender-project-goal/SKILL.md +115 -0
  74. package/.kilo/skills/blender-project-grading/SKILL.md +184 -0
  75. package/.kilo/skills/blender-project-readme/SKILL.md +46 -0
  76. package/.kilo/skills/blender-project-requirements/SKILL.md +84 -0
  77. package/.kilo/skills/blender-project-scaffold/SKILL.md +59 -0
  78. package/.kilo/skills/blender-project-workflow/SKILL.md +96 -0
  79. package/.kilo/skills/blender-subagents/SKILL.md +204 -0
  80. package/.kilo/skills/blender-workflow-harness/SKILL.md +187 -0
  81. package/AGENTS.md +234 -0
  82. package/Blender/README.md +30 -0
  83. package/CHANGELOG.md +22 -0
  84. package/LICENSE +21 -0
  85. package/README.md +368 -2
  86. package/THIRD_PARTY_NOTICES.md +51 -0
  87. package/bin/blender-project-harness.mjs +4 -0
  88. package/installer/cli.mjs +116 -0
  89. package/installer/install.mjs +325 -0
  90. package/installer/install.test.mjs +134 -0
  91. package/package.json +58 -6
@@ -0,0 +1,147 @@
1
+ ---
2
+ name: blender-mcp
3
+ description: Control a live Blender session through MCP for Blender. Use for modeling, scene edits, materials, lighting, animation, rendering, viewport checks, local asset import, reference images, and exports. Remote library import and 3D generation remain blocked.
4
+ license: MIT
5
+ ---
6
+
7
+ # Blender MCP
8
+
9
+ Use the `blender` MCP server to operate the user's open Blender. The server is `mcp-for-blender`
10
+ (upstream `ahujasid/mcp-for-blender`); the addon exposes a socket on the workspace `BLENDER_PORT`
11
+ from `.kilo/kilo.jsonc`.
12
+
13
+ This skill is required before any Blender scene operation. `AGENTS.md` defines hard invariants;
14
+ `blender-workflow-harness` defines the runtime contract. Read both.
15
+
16
+ ## Preflight
17
+
18
+ 1. Verify confirmed requirements, selected workflow/review records, active goal, and valid grader
19
+ configuration for `All` or `Single`. Stop on a mismatch.
20
+ 2. Launch only through `blender_workflow` `launch`; stop only through `stop`. NEVER invoke Blender
21
+ from the shell.
22
+ 3. Call `blender_get_addon_status` once. Check addon compatibility, Blender version, and enabled
23
+ libraries/generators from the actual response.
24
+ 4. Call `blender_get_scene_info(fields=["settings"])` before editing. Verify the exact authoritative
25
+ file path. Stop on connection, addon, or file mismatch.
26
+ 5. Use `status.nextStep` for the next harness action. Do not infer a lifecycle step.
27
+
28
+ ## Tools
29
+
30
+ | Tool | Use |
31
+ |---|---|
32
+ | `blender_get_addon_status` | Connection, addon version, Blender version, enabled libraries/generators |
33
+ | `blender_get_scene_info` | Text summary: objects, placement, materials, topology, weights, settings |
34
+ | `blender_workflow` | Orchestrator lifecycle and review actions; payload is a JSON string |
35
+ | `blender_document` | Structured document read; declared document or assigned grader-report write |
36
+ | `blender_harness_execute` | Execute one ticketed apply batch/save/seal operation |
37
+ | `blender_look` | Inspect an exact image: sealed render, viewport, camera, angles, frames |
38
+ | `blender_search_assets` | Search asset libraries |
39
+ | `blender_execute_blender_code` | Blocked raw Python; never a fallback or diagnostic route |
40
+ | `blender_import_asset` | Blocked until reviewed harness support exists |
41
+ | `blender_generate_3d` | Blocked until reviewed harness support exists |
42
+ | `blender_disable_telemetry` | Disable telemetry only on user request |
43
+ | `blender_record_trajectory_feedback` | Record user result feedback |
44
+
45
+ Use the exposed `blender_` prefix. Pass the user's exact words in `user_prompt` when supported.
46
+
47
+ ## Production
48
+
49
+ - The orchestrator issues an `apply` ticket and passes it to `blender-worker`. The worker calls
50
+ `blender_harness_execute` with the exact token and payload.
51
+ - The orchestrator executes `save` and `seal` only. Each operation in an apply batch auto-saves.
52
+ - After `seal`, inspect the returned absolute PNG with `blender_look`. Viewport checks do not replace
53
+ the sealed render.
54
+ - Review, approve, commit, and checkpoint through the harness. Never stage or commit project files
55
+ manually or create review documents manually.
56
+ - Read project documents through `blender_document` `{action:"read"}`; direct full-file reads are
57
+ acceptable but discouraged. Create new project markdown with `bootstrap-document` before
58
+ registration or `blender_document` `{action:"write"}` / `document` inside a declared change.
59
+ - Raw Python is forbidden for scene edits, saves, renders, API probes, or filesystem access.
60
+
61
+ ## Visual checks
62
+
63
+ Every scene, material, lighting, or camera change MUST be inspected with `look` before review.
64
+
65
+ - `look(mode="viewport")` for the user's view.
66
+ - `look(mode="viewport", shading="material")` for materials.
67
+ - `look(mode="camera")` for the render camera.
68
+ - `look(mode="angles", target=["Object"])` for a multi-view check.
69
+ - `blender_look(image=<returned absolute render>)` after `seal`.
70
+
71
+ ## Scene operations
72
+
73
+ Reviewed operations cover primitives, text objects, transforms, materials, shared materials,
74
+ duplication, lights, cameras, render settings, and the safe modifier subset: bevel, subdivision
75
+ surface, solidify, mirror, and array. Modifiers are added through `modifier` and are applied only
76
+ when the operation sets `apply:true`. Text objects can receive materials through `material` or
77
+ `shared_material`.
78
+
79
+ Scene operations are `create_scene` (`NEW`, `EMPTY`, `LINK_COPY`, `FULL_COPY`), `switch_scene`,
80
+ `duplicate_scene`, `delete_scene`, `set_scene_camera`, and `scene_strip`. Existing operations accept
81
+ an optional `scene`; when an object is linked into more than one scene, the scene is required.
82
+ `switch_scene` is the only deliberate active-context change. A master Video Sequencer scene uses
83
+ `scene_strip`; a long animation render is a separate render ticket.
84
+
85
+ ## Assets
86
+
87
+ External asset work requires `blender-assets`: licence, attribution, registration, relative paths,
88
+ packing, and delivery rights. Use `blender_workflow {action:"intake"}` for user files; it copies,
89
+ hashes, registers, and adds exact paths to the open change. Use `download` only for HTTPS staging,
90
+ then `intake`. Use the reviewed harness operations for local files:
91
+
92
+ - `import_asset` for GLB/glTF/FBX/OBJ/USD/`.blend`.
93
+ - `link_library` for `.blend` link/append.
94
+ - `import_audio`, `image_reference`, `image_texture`, `world_hdri`.
95
+ - `check_assets`, `pack_assets`, and `export_scene`.
96
+
97
+ The raw `blender_import_asset`, `blender_generate_3d`, and arbitrary Python tools remain blocked.
98
+ Library search does not authorize a remote import. Scripts are source-only under `scripts/` and are
99
+ never executed by the harness.
100
+
101
+ Every `export_scene` returns a harness receipt with project-relative path, bytes, SHA-256, format,
102
+ and source scene. Completion is denied for a missing or changed export. Export validation is
103
+ separate from `check_assets`. External binaries under `assets/external/` are committed only when
104
+ their sidecar explicitly allows redistribution.
105
+
106
+ ## API and documentation gaps
107
+
108
+ 1. Resolve Blender with Context7 and query the matching version's API and manual.
109
+ 2. Inspect the reviewed operation schema and available read-only scene facts. Do not use raw Python
110
+ probes.
111
+ 3. If Context7 is incomplete, search official docs, release notes, Blender source, Blender Stack
112
+ Exchange, and devtalk. Note the Blender version.
113
+ 4. If reviewed operations cannot verify the behavior, STOP and request a reviewed tooling extension
114
+ with isolated tests. Never guess properties, operators, or signatures.
115
+ 5. Report the source and test result; report unresolved gaps instead of pretending they work.
116
+
117
+ Official starting points:
118
+
119
+ - https://docs.blender.org/api/current/
120
+ - https://docs.blender.org/manual/en/latest/
121
+ - https://blender.stackexchange.com/
122
+ - https://devtalk.blender.org/
123
+
124
+ ## Safety
125
+
126
+ `execute_blender_code` is blocked. The harness is a same-user guard, not an OS sandbox; manual
127
+ Blender or external-shell edits invalidate evidence. State under
128
+ `~/.local/state/blender-workflow-harness/<workspace-hash>` is runtime-owned and not agent-editable.
129
+
130
+ Check `telemetry_consent` in addon status; do not assume it. Call `blender_disable_telemetry`
131
+ immediately when the user requests opt-out. Do not disable safe mode or add credentials, tokens, or
132
+ private data to payloads.
133
+
134
+ ## Troubleshooting
135
+
136
+ - **Connection refused**: the addon is stopped, on another port, or MCP started before Blender. Stop
137
+ through the harness, confirm `BLENDER_PORT`, relaunch, and reload Kilo if needed.
138
+ - **Addon outdated**: reinstall `uvx --from mcp-for-blender==2.2.6 mcp-for-blender install-addon`,
139
+ then stop and relaunch through the harness.
140
+ - **Asset source unavailable**: the library toggle is off in the addon. Ask before enabling.
141
+ - **Generator unavailable**: no API key or premium access is configured. Report the missing provider.
142
+ - **`look` fails**: inspect `status` and retry the exact sealed render path. A viewport fallback does
143
+ not satisfy review inspection.
144
+ - **Harness unavailable or stale**: reload Kilo, inspect `status`, and follow `nextStep`. NEVER
145
+ fabricate tickets, reports, approvals, or state.
146
+ - **Registration pending**: wait for the challenge to expire or finish it in its owning session.
147
+ `status {project}` identifies the current bootstrap step.
@@ -0,0 +1,22 @@
1
+ # Blender MCP references
2
+
3
+ Workflow guides for `blender-mcp`. Load only the guide relevant to the current task.
4
+
5
+ These files are adapted from the guides shipped with
6
+ [mcp-for-blender](https://github.com/ahujasid/mcp-for-blender) under the MIT License;
7
+ local changes add version checks, safety and approval rules, and workspace-specific
8
+ guidance. Full attribution and the upstream licence text are in
9
+ [`THIRD_PARTY_NOTICES.md`](../../../../THIRD_PARTY_NOTICES.md).
10
+
11
+ | File | Topic | Upstream guide |
12
+ |---|---|---|
13
+ | `bpy.md` | Version-aware Python API use, context overrides, data API | `src/blender_mcp/guides/bpy.md` |
14
+ | `scene.md` | Scene assembly, imports, composition, lighting | `src/blender_mcp/guides/scene.md` |
15
+ | `materials.md` | Shader nodes, PBR textures, procedural looks | `src/blender_mcp/guides/materials.md` |
16
+ | `animation.md` | Keyframes, slotted actions, loops, motion checks | `src/blender_mcp/guides/animation.md` |
17
+ | `rigging.md` | Armatures, Rigify, skinning, deformation checks | `src/blender_mcp/guides/rigging.md` |
18
+ | `retopology.md` | Cleanup, remeshing, decimation, baking | `src/blender_mcp/guides/retopology.md` |
19
+ | `level-design.md` | Player metrics, blockout, modular kits, export | `src/blender_mcp/guides/level-design.md` |
20
+
21
+ Reference dimensions, material values, camera settings, topology budgets, and snippets
22
+ are examples. Confirmed project requirements control the work.
@@ -0,0 +1,83 @@
1
+ ---
2
+ title: Animation
3
+ summary: Keyframing from Python across Blender versions, easing, cycles, NLA, cameras, and checking motion with frame strips.
4
+ ---
5
+
6
+ # Animation
7
+
8
+ ## Keyframes
9
+
10
+ Keyframe supported animatable properties directly rather than relying on UI operators. Verify the
11
+ property and keyframe result in the active version:
12
+
13
+ ```python
14
+ scene = bpy.context.scene
15
+ scene.frame_start, scene.frame_end = 1, 120
16
+ scene.render.fps = 24
17
+
18
+ obj.location = (0, 0, 0); obj.keyframe_insert("location", frame=1)
19
+ obj.location = (0, 0, 2); obj.keyframe_insert("location", frame=24)
20
+ obj.rotation_euler.z = 3.1416; obj.keyframe_insert("rotation_euler", index=2, frame=48)
21
+ ```
22
+
23
+ Pose bones: `pb = arm.pose.bones["hand.L"]; pb.rotation_mode = "XYZ"`, then
24
+ `pb.keyframe_insert("rotation_euler", frame=f)`. Bone keys use pose-space values, not world space.
25
+
26
+ ## Reaching fcurves
27
+
28
+ Blender 4.4 added slotted actions and 5.0 removed `Action.fcurves`. This helper returns the first
29
+ channelbag for the assigned slot; inspect every layer/strip explicitly when handling complex actions.
30
+ MUST check for an assigned slot before calling the helper: Blender 4.4 does not accept `None` here.
31
+ An assigned action can legitimately have no assigned slot; inspection MUST NOT guess or assign one:
32
+
33
+ ```python
34
+ def fcurves(obj):
35
+ ad = obj.animation_data
36
+ if not ad or not ad.action:
37
+ return []
38
+ if getattr(ad.action, "is_action_layered", False):
39
+ if ad.action_slot is None:
40
+ return []
41
+ from bpy_extras import anim_utils
42
+ cb = anim_utils.action_get_channelbag_for_slot(ad.action, ad.action_slot)
43
+ return list(cb.fcurves) if cb else []
44
+ return list(ad.action.fcurves)
45
+ ```
46
+
47
+ Read supported interpolation enums before assigning. `BEZIER` uses handle shapes; `LINEAR` suits
48
+ constant motion and `CONSTANT` suits stepped blocking. `kp.easing` applies to easing-equation
49
+ interpolation modes, not ordinary Bezier handles.
50
+
51
+ ## Making it feel alive
52
+
53
+ - Timing and spacing matter more than poses. Ease in and out of holds; keep linear for constant
54
+ motion (wheels, conveyors).
55
+ - Anticipation before big moves, overshoot and settle after them, follow-through on
56
+ secondary parts (antennae, tails, cloth) offset by 2–4 frames.
57
+ - Arcs: limbs and thrown objects travel on curves, not straight lines.
58
+ - Loops: make the first and last key identical and add a Cycles modifier
59
+ (`fc.modifiers.new("CYCLES")`), or set the frame range to exclude the duplicate last frame.
60
+ - Procedural motion: drivers (`obj.driver_add("rotation_euler", 2).driver.expression = "frame * 0.1"`)
61
+ or noise modifiers on fcurves. Auto-run restrictions may block scripted drivers; never disable
62
+ safety settings to work around that restriction.
63
+
64
+ ## Organizing
65
+
66
+ - Push finished actions to NLA strips (`track = ad.nla_tracks.new(); track.strips.new(name, start, action)`)
67
+ to layer or sequence clips (walk, then wave).
68
+ - Name actions `Character_Walk`, `Door_Open`; game engines import them by name.
69
+ - Cameras: animate the camera or a parent empty; use a Track To constraint on a target empty for
70
+ smooth follow shots. Keep focal-length changes slow.
71
+
72
+ ## Checking motion
73
+
74
+ A single screenshot can't show motion. Use `look(mode="frames")` to see a strip of evenly spaced
75
+ frames (or pass `frames=[...]` for specific ones, `view="camera"` to see them through the camera).
76
+ Check for popping, interpenetration, feet sliding on the ground, and the loop seam.
77
+
78
+ ## Sources
79
+
80
+ - https://developer.blender.org/docs/release_notes/4.4/upgrading/slotted_actions/
81
+ - https://developer.blender.org/docs/release_notes/5.0/python_api/#animation-rigging
82
+ - https://docs.blender.org/api/current/bpy_extras.anim_utils.html
83
+ - https://raw.githubusercontent.com/blender/blender/v4.4.0/scripts/modules/bpy_extras/anim_utils.py
@@ -0,0 +1,97 @@
1
+ ---
2
+ title: Version-aware bpy scripting
3
+ summary: Version-aware scripting, API introspection, operator context, and the mistakes that break scripts on other people's machines.
4
+ ---
5
+
6
+ # Version-aware bpy scripting
7
+
8
+ Scripts run in the user's live Blender, whose version, language and add-ons you don't know.
9
+ `get_addon_status` reports `blender_version`; check it before using anything version-specific.
10
+
11
+ ## Look things up instead of guessing
12
+
13
+ Introspect with RNA before indexing sockets or setting enums:
14
+
15
+ ```python
16
+ # Values of a static enum property
17
+ [i.identifier for i in bpy.types.Keyframe.bl_rna.properties["interpolation"].enum_items]
18
+ # Properties of a type
19
+ [p.identifier for p in bpy.types.ShaderNodeTexSky.bl_rna.properties]
20
+ # Operator arguments
21
+ [(p.identifier, p.type) for p in bpy.ops.mesh.primitive_cube_add.get_rna_type().properties]
22
+ # A node's sockets, in the mode you intend to use
23
+ tree = bpy.data.node_groups.new("_probe", "ShaderNodeTree")
24
+ n = tree.nodes.new("ShaderNodeMix"); n.data_type = "RGBA"
25
+ print([(i, s.name, s.type) for i, s in enumerate(n.inputs) if s.enabled])
26
+ bpy.data.node_groups.remove(tree)
27
+ ```
28
+
29
+ ## Portability rules
30
+
31
+ - Find nodes by `type`, never by name: names are localized. `next(n for n in nodes if n.type == "BSDF_PRINCIPLED")`.
32
+ - Address sockets by name only after checking they exist in this version (Principled BSDF renamed
33
+ many inputs in 4.0: `Emission Color`, `Subsurface Weight`, `Specular IOR Level`, `Coat Weight`,
34
+ `Sheen Weight`, `Transmission Weight`). `sock = node.inputs.get("Emission Color") or node.inputs.get("Emission")`.
35
+ - Never guess enum identifiers; inspect them before assigning. Dynamic enum listings MUST NOT be
36
+ treated as complete. `scene.render.engine` is a dynamic enum that RNA under-reports; MUST read
37
+ the current value, and if switching is required, assign the requested engine inside
38
+ `try/except TypeError` — the error lists every accepted value. EEVEE is `BLENDER_EEVEE_NEXT` in
39
+ 4.2–4.5 and `BLENDER_EEVEE` in 5.0; older releases also use `BLENDER_EEVEE`. Query later versions.
40
+ - Material colors live on shader node inputs. `material.diffuse_color` only drives the solid
41
+ viewport when material colour is selected. In 5.0 `material.use_nodes` is deprecated and always on;
42
+ it is scheduled for removal in 6.0. Do not rely on toggling it.
43
+ - Animation data changed in 4.4 (slotted actions) and 5.0 removed `Action.fcurves`. Insert keys with
44
+ `obj.keyframe_insert("location", frame=f)` for supported animatable properties. For layered actions,
45
+ use `bpy_extras.anim_utils.action_get_channelbag_for_slot(action, obj.animation_data.action_slot)`;
46
+ use `action.fcurves` for legacy actions. See `animation.md` for the compatibility branch.
47
+
48
+ ## Data API over operators
49
+
50
+ Prefer `bpy.data` and object properties over `bpy.ops`: they need no context and are faster.
51
+ `bpy.data.meshes.new` + `from_pydata`, `bmesh` for editing, `obj.modifiers.new`, `obj.matrix_world`.
52
+
53
+ When you need an operator:
54
+
55
+ - MUST verify the required mode, editable targets, exact operator selection, and `poll()` before
56
+ execution. For example, this Object Mode shading operation overrides both selection members
57
+ without changing the user's actual selection:
58
+ ```python
59
+ if bpy.context.mode != "OBJECT" or obj.type != "MESH":
60
+ raise RuntimeError("Shading requires Object Mode and a mesh")
61
+ if obj not in bpy.context.editable_objects or obj not in bpy.context.selectable_objects:
62
+ raise RuntimeError("Target must be editable and selectable in the current view layer")
63
+ with bpy.context.temp_override(object=obj, active_object=obj,
64
+ selected_objects=[obj], selected_editable_objects=[obj]):
65
+ if not bpy.ops.object.shade_smooth.poll():
66
+ raise RuntimeError("shade_smooth is unavailable in this context")
67
+ bpy.ops.object.shade_smooth()
68
+ ```
69
+ - Code runs from a timer, not a UI area. Operators that require a viewport MUST use a verified
70
+ `VIEW_3D` area and its `WINDOW` region in a matching window override; shading above needs neither.
71
+ - `selected_objects` and `selected_editable_objects` are distinct context members; overriding only
72
+ one does not isolate an operator that reads the other. Some operators read actual selection too.
73
+ If actual selection must change, MUST save selection and active object, select only intended
74
+ targets, and restore both in `finally`. Adding `obj.select_set(True)` alone is insufficient.
75
+ - `mode_set` needs an active, visible, selectable object. MUST check its `poll()` before each mode
76
+ switch and return to OBJECT mode in `finally` after a temporary Edit Mode step. If the starting
77
+ mode is unexpected, stop before mutating data rather than silently leaving the user's mode.
78
+
79
+ ## Working style
80
+
81
+ - Small steps. Run a chunk and `print` what you need to know.
82
+ - Name everything you create; later steps and the user refer to it by name.
83
+ - Keep the scene organized: one collection per logical group (`bpy.data.collections.new`, link
84
+ to `scene.collection`).
85
+ - Assess scale before rigging, scale-sensitive modifiers, or export. Applying transforms can alter
86
+ rigs, animation, constraints, and shared mesh data; follow the confirmed pipeline.
87
+ - Duplicate with `obj.copy()` (shares mesh data, cheap) for repeated props; `obj.data.copy()` only
88
+ when the copy must differ.
89
+ - Read `scene.unit_settings` and `scale_length`; do not assume one Blender unit equals one metre.
90
+ A door around 2.1 m, table around 0.75 m, and person around 1.7 m are scale references only.
91
+
92
+ ## Sources
93
+
94
+ - https://docs.blender.org/api/current/info_gotchas_operators.html
95
+ - https://docs.blender.org/api/current/bpy.types.Context.html
96
+ - https://raw.githubusercontent.com/blender/blender/v5.0.0/source/blender/editors/object/object_edit.cc
97
+ - https://developer.blender.org/docs/release_notes/5.0/python_api/
@@ -0,0 +1,53 @@
1
+ ---
2
+ title: Level design
3
+ summary: Game levels in Blender - player metrics, blockout, modular kits, instancing, collisions, and export to game engines.
4
+ ---
5
+
6
+ # Level design
7
+
8
+ ## Metrics first
9
+
10
+ Agree on the player's size and movement, then build everything to them. Examples for a
11
+ human-scale third/first-person game; confirm values for the user's engine and genre:
12
+
13
+ | Thing | Size |
14
+ |---|---|
15
+ | Player capsule | 1.8 m tall, 0.6 m wide |
16
+ | Doorway | 1.2–1.5 m wide, 2.4–3 m tall (wider than real life) |
17
+ | Corridor | 3–4 m wide |
18
+ | Step | 0.2 m rise, 0.3 m run |
19
+ | Max climbable ledge | ~1 m (jump) |
20
+ | Cover (crouch / full) | 1.0 m / 2.0 m |
21
+ | Grid unit | 1 m, modules on 2 m or 4 m |
22
+
23
+ When approved, place a scale reference using the confirmed player metrics and naming convention.
24
+
25
+ ## Blockout
26
+
27
+ - Grey-box the whole level with simple geometry before any art: rooms, paths, heights,
28
+ sightlines. One collection per area (`Area_Entrance`, `Area_Arena`...).
29
+ - Snap to the grid. Round positions and sizes to the module size in your scripts.
30
+ - Design the critical path, then branches, loops and secrets. Landmarks (tall, distinct shapes)
31
+ help navigation; check they're visible from where the player needs them with
32
+ `look(mode="angles", views=["top"])` and eye-height views.
33
+ - Top view (`look(mode="angles", views=["top"])`) is the fastest way to review flow and spacing.
34
+
35
+ ## Modular kits
36
+
37
+ - Build pieces on the grid: wall 4×3 m, floor 4×4 m, corner, doorway, stairs. Origin at a corner
38
+ or bottom-centre so pieces snap.
39
+ - Place with linked duplicates (`obj.copy()` without copying data) or collection instances, so a
40
+ fix to one piece updates every copy and the file stays small.
41
+ - Scatter props with slight random rotation and scale; keep gameplay-critical props exact.
42
+
43
+ ## Engine-ready output
44
+
45
+ - Apply transforms only as required by the target exporter and confirmed pipeline. Check existing
46
+ animation, rigs, constraints, and instancing before applying them.
47
+ - Name for the engine's conventions. Unreal: `SM_` meshes and `UCX_<mesh>` convex collision.
48
+ Godot: `-col` / `-colonly` suffixes. Unity: separate low-poly collision meshes.
49
+ - Keep collision simple: boxes and convex hulls, not the render mesh.
50
+ - Triangle budgets depend on platform; report counts with `get_scene_info(fields=["topology"])`.
51
+ - Export with `bpy.ops.export_scene.gltf` (Godot, web, most engines) or `export_scene.fbx`
52
+ (Unity, Unreal). Read each operator's arguments first; they change between versions.
53
+ - Lightmap UVs go in a second UV map when the engine bakes lighting.
@@ -0,0 +1,80 @@
1
+ ---
2
+ title: Materials and texturing
3
+ summary: Node-based materials that survive version and language changes, applying Poly Haven textures, real-world tiling, and procedural looks.
4
+ ---
5
+
6
+ # Materials and texturing
7
+
8
+ ## Creating materials
9
+
10
+ Before assigning materials, MUST inspect existing slots, their object/data links, and mesh users.
11
+ MUST preserve unrelated slots. The example replaces only the inspected active slot, or adds the
12
+ first slot on an empty mesh; it does not replace every material on a multi-material object.
13
+ For an object-only change to shared mesh data, MUST make the mesh single-user (as below), or use
14
+ an explicit object-linked slot strategy. Changes intended for all users require that scope.
15
+
16
+ ```python
17
+ if obj.type != "MESH" or obj.mode != "OBJECT" or not obj.is_editable:
18
+ raise RuntimeError("Material assignment requires an editable mesh in Object Mode")
19
+ if obj.data.users > 1 or not obj.data.is_editable:
20
+ obj.data = obj.data.copy()
21
+ mat = bpy.data.materials.new("Brushed Steel")
22
+ if bpy.app.version < (5, 0, 0):
23
+ mat.use_nodes = True
24
+ bsdf = next(n for n in mat.node_tree.nodes if n.type == "BSDF_PRINCIPLED")
25
+ bsdf.inputs["Base Color"].default_value = (0.6, 0.6, 0.62, 1)
26
+ bsdf.inputs["Metallic"].default_value = 1.0
27
+ bsdf.inputs["Roughness"].default_value = 0.35
28
+ if obj.material_slots:
29
+ obj.material_slots[obj.active_material_index].material = mat
30
+ else:
31
+ obj.data.materials.append(mat)
32
+ ```
33
+
34
+ Sockets renamed in 4.0; resolve them defensively (`inputs.get("Emission Color") or inputs.get("Emission")`).
35
+
36
+ ## Believable values
37
+
38
+ | Material | Base colour (linear) | Metallic | Roughness |
39
+ |---|---|---|---|
40
+ | Painted wall | 0.5–0.7 grey | 0 | 0.8–0.9 |
41
+ | Wood (varnished) | textured | 0 | 0.3–0.5 |
42
+ | Plastic | any | 0 | 0.3–0.6 |
43
+ | Polished metal | 0.9 | 1 | 0.05–0.2 |
44
+ | Rubber | 0.02–0.05 | 0 | 0.8 |
45
+ | Glass | white | 0 | 0; Transmission 1, IOR 1.45 |
46
+
47
+ These ranges are starting points for common materials, not physical limits or requirements.
48
+ Match measured/reference values, colour space, and the confirmed look.
49
+
50
+ ## Textures
51
+
52
+ - Poly Haven textures come as PBR sets. `import_asset(source="polyhaven", asset_type="textures", id=...,
53
+ apply_to=["Floor"])` builds the material and applies it in one call.
54
+ - Tiling: the import result gives the texture's real-world size. For 0–1 UVs across a surface,
55
+ Mapping node Scale = surface size in metres / texture size in metres. Prefer large-coverage
56
+ textures (`min_size_m` in search) for walls and floors; small ones repeat visibly.
57
+ - Objects need UVs. Primitives have them; scripted meshes need `smart_project` or box-projection
58
+ (`Texture Coordinate > Object` into Mapping, and the Image Texture node's projection `BOX`).
59
+ - Treat roughness, metallic, and normal maps as non-colour data. Query available colour
60
+ space names before assigning `img.colorspace_settings.name = "Non-Color"`.
61
+
62
+ ## Procedural
63
+
64
+ Noise, Voronoi and Wave textures through a Color Ramp make variation without images: grunge for
65
+ roughness, stains, wood rings. Mixing a little noise into roughness makes any flat material look
66
+ less CG. Look each node up before indexing its sockets (see `bpy.md`).
67
+
68
+ ## Check it
69
+
70
+ Shader node material colours show in Material Preview or Rendered shading:
71
+ `look(mode="camera", shading="material")` or `shading="rendered"`. Solid shading shows only the
72
+ viewport display colour. Rendered `look` is supported for EEVEE and Workbench; inspect a saved render
73
+ or `Render Result` for Cycles.
74
+
75
+ ## Sources
76
+
77
+ - https://docs.blender.org/manual/en/latest/render/shader_nodes/shader/principled.html
78
+ - https://developer.blender.org/docs/release_notes/5.0/python_api/#shading
79
+ - https://docs.blender.org/manual/en/latest/scene_layout/object/editing/duplicate_linked.html
80
+ - https://docs.blender.org/api/current/bpy.types.MaterialSlot.html
@@ -0,0 +1,104 @@
1
+ ---
2
+ title: Retopology and mesh cleanup
3
+ summary: Turning generated or scanned meshes into clean, lighter geometry - cleanup, remeshing, decimation, UVs and baking detail back.
4
+ ---
5
+
6
+ # Retopology and mesh cleanup
7
+
8
+ Generated and scanned models are dense, triangulated, and often non-manifold. What to do depends
9
+ on where the mesh is going:
10
+
11
+ | Goal | Approach |
12
+ |---|---|
13
+ | Still render, background prop | Leave it; maybe Decimate |
14
+ | Game prop | Decimate or remesh, then bake normals from the original |
15
+ | Deforming character | Quad remesh (QuadriFlow), clean loops at joints, then rig |
16
+ | 3D print | Voxel remesh for a watertight solid |
17
+
18
+ Always work on a copy and keep the original as the bake source: `low = src.copy(); low.data = src.data.copy()`.
19
+
20
+ ## Diagnose
21
+
22
+ `get_scene_info(fields=["topology"], query=name)` reports quads, tris, ngons, non-manifold edges,
23
+ boundary edges, loose vertices and poles; `look(mode="angles", shading="wireframe", target=[name])`
24
+ shows the edges.
25
+
26
+ ## Clean up
27
+
28
+ MUST verify mesh type and mode before editing. This standalone BMesh example requires Object Mode;
29
+ MUST NOT use it against Edit Mode's separate mesh data. Thresholds below are examples, not defaults
30
+ for every asset. MUST free an owned standalone BMesh in `finally`, including on failure.
31
+
32
+ ```python
33
+ import bmesh
34
+ if obj.type != "MESH" or obj.mode != "OBJECT" or obj.data.is_editmode:
35
+ raise RuntimeError("Standalone BMesh cleanup requires an Object Mode mesh")
36
+ if not obj.data.is_editable or obj.data.users != 1:
37
+ raise RuntimeError("Cleanup requires an editable single-user mesh copy")
38
+ bm = bmesh.new()
39
+ try:
40
+ bm.from_mesh(obj.data)
41
+ bmesh.ops.remove_doubles(bm, verts=bm.verts, dist=0.0001)
42
+ bmesh.ops.dissolve_degenerate(bm, edges=bm.edges, dist=0.0001)
43
+ loose = [v for v in bm.verts if not v.link_edges]
44
+ bmesh.ops.delete(bm, geom=loose, context="VERTS")
45
+ bmesh.ops.recalc_face_normals(bm, faces=bm.faces)
46
+ bm.to_mesh(obj.data)
47
+ finally:
48
+ bm.free()
49
+ ```
50
+
51
+ For authorized Edit Mode cleanup instead, MUST verify `obj.mode == "EDIT"` and
52
+ `obj.data.is_editmode`, use `bm = bmesh.from_edit_mesh(obj.data)`, and update with
53
+ `bmesh.update_edit_mesh(obj.data, loop_triangles=True, destructive=True)` after topology changes.
54
+ This BMesh is owned by Blender: MUST NOT call `to_mesh()` or `free()` on it. Reacquire it after mode
55
+ changes; do not reuse stale references. MUST apply the operator context rules in `bpy.md` to remesh,
56
+ UV, and bake operators below, including exact selection, mode, `poll()`, and restoration.
57
+
58
+ ## Reduce
59
+
60
+ - **Decimate** reduces faces with shape changes. Inspect the silhouette, UVs, seams, and triangulation:
61
+ `m = obj.modifiers.new("Decimate", "DECIMATE"); m.ratio = 0.1`. Planar mode (`decimate_type="DISSOLVE"`)
62
+ is good for hard-surface.
63
+ - **Voxel remesh** makes a watertight, even mesh but loses UVs and sharp edges:
64
+ `obj.data.remesh_voxel_size = 0.01; bpy.ops.object.voxel_remesh()` (active object needed).
65
+ Size relative to the object: ~1/200 of its largest dimension is a sane start.
66
+ - **QuadriFlow** produces quads but does not guarantee animation-ready loops:
67
+ `bpy.ops.object.quadriflow_remesh(target_faces=4000)`. It is slow on dense input and can fail on
68
+ non-manifold meshes — voxel remesh first, then QuadriFlow the result.
69
+ - **Shrinkwrap** a low mesh onto the high one (`modifiers.new("Shrinkwrap", "SHRINKWRAP")`,
70
+ `target = high`) to recover the silhouette after remeshing.
71
+
72
+ Example face budgets: hero game character 15–50k tris, prop 500–5k, background 50–500. Confirm actual
73
+ platform, camera distance, deformation, and performance targets; these are not acceptance limits.
74
+
75
+ ## UVs
76
+
77
+ ```python
78
+ # in edit mode with everything selected, via a 3D viewport override
79
+ bpy.ops.uv.smart_project(angle_limit=1.15, island_margin=0.02)
80
+ ```
81
+
82
+ For characters mark seams along hidden edges first (`edge.seam = True` in bmesh), then
83
+ `bpy.ops.uv.unwrap()`.
84
+
85
+ ## Bake detail back
86
+
87
+ Bake normals (and colour) from the original high mesh to the low one's UVs, in Cycles:
88
+
89
+ 1. Create an image (`bpy.data.images.new("Low_Normal", 2048, 2048, is_data=True)`) and an Image
90
+ Texture node using it in the low mesh's material, set as the active node.
91
+ 2. Select high, make low active; `scene.render.bake.use_selected_to_active = True`,
92
+ `cage_extrusion` ~1–2% of the object size.
93
+ 3. `bpy.ops.object.bake(type="NORMAL")`; for colour use `type="DIFFUSE"` with only the colour pass.
94
+ 4. Save the image, wire it into a Normal Map node, and compare with `look(mode="angles")`.
95
+
96
+ Switching the engine to Cycles for the bake: read the current engine first and restore it after
97
+ (see `bpy.md`).
98
+
99
+ ## Sources
100
+
101
+ - https://docs.blender.org/manual/en/5.0/modeling/modifiers/generate/decimate.html
102
+ - https://docs.blender.org/manual/en/5.0/modeling/meshes/retopology.html
103
+ - https://docs.blender.org/api/current/info_gotchas_meshes.html
104
+ - https://docs.blender.org/api/current/bmesh.html