@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.
- package/.kilo/agent/blender-grader.md +197 -0
- package/.kilo/agent/blender-worker.md +127 -0
- package/.kilo/blender-project-harness/config.example.json +71 -0
- package/.kilo/blender-project-harness/tools/harness/EXPECTED_FLOW.md +656 -0
- package/.kilo/blender-project-harness/tools/harness/blender-operations.mjs +882 -0
- package/.kilo/blender-project-harness/tools/harness/blender-operations.test.mjs +550 -0
- package/.kilo/blender-project-harness/tools/harness/blender.mjs +301 -0
- package/.kilo/blender-project-harness/tools/harness/blender.test.mjs +87 -0
- package/.kilo/blender-project-harness/tools/harness/cli.mjs +127 -0
- package/.kilo/blender-project-harness/tools/harness/documents.mjs +201 -0
- package/.kilo/blender-project-harness/tools/harness/download.mjs +94 -0
- package/.kilo/blender-project-harness/tools/harness/download.test.mjs +63 -0
- package/.kilo/blender-project-harness/tools/harness/engine.mjs +1866 -0
- package/.kilo/blender-project-harness/tools/harness/engine.test.mjs +2219 -0
- package/.kilo/blender-project-harness/tools/harness/intake.mjs +571 -0
- package/.kilo/blender-project-harness/tools/harness/intake.test.mjs +181 -0
- package/.kilo/blender-project-harness/tools/harness/package-lock.json +1227 -0
- package/.kilo/blender-project-harness/tools/harness/package.json +15 -0
- package/.kilo/blender-project-harness/tools/harness/plugin.mjs +550 -0
- package/.kilo/blender-project-harness/tools/harness/plugin.test.mjs +526 -0
- package/.kilo/blender-project-harness/tools/harness/proxy.mjs +222 -0
- package/.kilo/blender-project-harness/tools/harness/proxy.test.mjs +217 -0
- package/.kilo/blender-project-harness/tools/harness/scaffold.mjs +83 -0
- package/.kilo/blender-project-harness/tools/harness/scaffold.test.mjs +74 -0
- package/.kilo/blender-project-harness/tools/harness/server.mjs +24 -0
- package/.kilo/blender-project-harness/tools/harness/shell-policy.mjs +196 -0
- package/.kilo/blender-project-harness/tools/harness/shell-policy.test.mjs +68 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/ASSETS.md +29 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/DECISIONS.md +8 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Goals/01-project-brief.md +71 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Goals/README.md +17 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/INTAKE.md +8 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/README.md +57 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/REQUIREMENTS.md +64 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/REVIEW.md +29 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/References/README.md +18 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Reviews/README.md +48 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/TASKSTRACKER.md +10 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/Tasks/README.md +4 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/Documents/WORKFLOW.md +36 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/README.md +130 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/README.md +31 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/audio/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/external/README.md +43 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/external/SOURCE_TEMPLATE.md +18 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/hdri/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/models/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/assets/textures/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/backups/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/backups/README.md +5 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/exports/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/exports/README.md +11 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/renders/README.md +7 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/renders/final/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/renders/wip/.gitkeep +0 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/scenes/README.md +10 -0
- package/.kilo/blender-project-harness/tools/harness/templates/project/scripts/README.md +16 -0
- package/.kilo/blender-project-harness/tools/harness/test-fixture.mjs +91 -0
- package/.kilo/blender-project-harness/tools/harness/workspace.mjs +30 -0
- package/.kilo/blender-project-harness/tools/harness/workspace.test.mjs +31 -0
- package/.kilo/blender-project-harness/tools/test_blender_tools.py +427 -0
- package/.kilo/plugins/blender-workflow.js +3 -0
- package/.kilo/skills/blender-assets/SKILL.md +99 -0
- package/.kilo/skills/blender-mcp/SKILL.md +147 -0
- package/.kilo/skills/blender-mcp/references/README.md +22 -0
- package/.kilo/skills/blender-mcp/references/animation.md +83 -0
- package/.kilo/skills/blender-mcp/references/bpy.md +97 -0
- package/.kilo/skills/blender-mcp/references/level-design.md +53 -0
- package/.kilo/skills/blender-mcp/references/materials.md +80 -0
- package/.kilo/skills/blender-mcp/references/retopology.md +104 -0
- package/.kilo/skills/blender-mcp/references/rigging.md +123 -0
- package/.kilo/skills/blender-mcp/references/scene.md +72 -0
- package/.kilo/skills/blender-project-goal/SKILL.md +115 -0
- package/.kilo/skills/blender-project-grading/SKILL.md +184 -0
- package/.kilo/skills/blender-project-readme/SKILL.md +46 -0
- package/.kilo/skills/blender-project-requirements/SKILL.md +84 -0
- package/.kilo/skills/blender-project-scaffold/SKILL.md +59 -0
- package/.kilo/skills/blender-project-workflow/SKILL.md +96 -0
- package/.kilo/skills/blender-subagents/SKILL.md +204 -0
- package/.kilo/skills/blender-workflow-harness/SKILL.md +187 -0
- package/AGENTS.md +234 -0
- package/Blender/README.md +30 -0
- package/CHANGELOG.md +22 -0
- package/LICENSE +21 -0
- package/README.md +368 -2
- package/THIRD_PARTY_NOTICES.md +51 -0
- package/bin/blender-project-harness.mjs +4 -0
- package/installer/cli.mjs +116 -0
- package/installer/install.mjs +325 -0
- package/installer/install.test.mjs +134 -0
- 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
|