blendops 0.0.0-stage → 1.1.0

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 (485) hide show
  1. package/CHANGELOG.md +74 -0
  2. package/LICENSE +21 -0
  3. package/README.md +208 -2
  4. package/bin/blendops.mjs +4 -0
  5. package/bundles/claude-desktop-manual/BLENDOPS_SINGLE_FILE.md +78 -0
  6. package/bundles/claude-desktop-manual/IMPORT_STEPS.md +43 -0
  7. package/bundles/claude-desktop-manual/INSTALL_REPORT_TEMPLATE.md +13 -0
  8. package/bundles/claude-desktop-manual/README.md +70 -0
  9. package/bundles/claude-desktop-manual/SKILL.md +62 -0
  10. package/bundles/claude-desktop-manual/manifest.json +278 -0
  11. package/bundles/claude-desktop-manual/references/evidence-rules.md +13 -0
  12. package/bundles/claude-desktop-manual/references/install-boundary.md +13 -0
  13. package/bundles/claude-desktop-manual/references/laws/evidence-before-done.md +14 -0
  14. package/bundles/claude-desktop-manual/references/laws/no-arbitrary-python-interface.md +12 -0
  15. package/bundles/claude-desktop-manual/references/laws/non-blender-user-language.md +13 -0
  16. package/bundles/claude-desktop-manual/references/laws/official-runtime-only.md +20 -0
  17. package/bundles/claude-desktop-manual/references/packs/product-hero-v0.md +30 -0
  18. package/bundles/claude-desktop-manual/references/runtime-stacks.md +13 -0
  19. package/bundles/claude-desktop-manual/references/skill-map.md +36 -0
  20. package/bundles/claude-desktop-manual/references/skills/acceptance-criteria-builder.md +69 -0
  21. package/bundles/claude-desktop-manual/references/skills/asset-discovery.md +73 -0
  22. package/bundles/claude-desktop-manual/references/skills/asset-fallback-strategy.md +66 -0
  23. package/bundles/claude-desktop-manual/references/skills/asset-library-plan.md +69 -0
  24. package/bundles/claude-desktop-manual/references/skills/asset-license-checker.md +69 -0
  25. package/bundles/claude-desktop-manual/references/skills/asset-style-check.md +69 -0
  26. package/bundles/claude-desktop-manual/references/skills/blender-brainstorming.md +62 -0
  27. package/bundles/claude-desktop-manual/references/skills/blender-recipe-decomposer.md +66 -0
  28. package/bundles/claude-desktop-manual/references/skills/blender-troubleshooting.md +78 -0
  29. package/bundles/claude-desktop-manual/references/skills/blendops-help.md +82 -0
  30. package/bundles/claude-desktop-manual/references/skills/bridge-conflicts.md +68 -0
  31. package/bundles/claude-desktop-manual/references/skills/camera-composition.md +65 -0
  32. package/bundles/claude-desktop-manual/references/skills/character-portrait.md +68 -0
  33. package/bundles/claude-desktop-manual/references/skills/cli-appendix-job-outline.md +62 -0
  34. package/bundles/claude-desktop-manual/references/skills/color-management-decision.md +68 -0
  35. package/bundles/claude-desktop-manual/references/skills/composition-quality-checker.md +71 -0
  36. package/bundles/claude-desktop-manual/references/skills/cycles-vs-eevee-decision.md +65 -0
  37. package/bundles/claude-desktop-manual/references/skills/done-criteria.md +70 -0
  38. package/bundles/claude-desktop-manual/references/skills/environment-shot.md +65 -0
  39. package/bundles/claude-desktop-manual/references/skills/glb-animation-handoff.md +69 -0
  40. package/bundles/claude-desktop-manual/references/skills/glb-web-handoff.md +68 -0
  41. package/bundles/claude-desktop-manual/references/skills/intent-to-3d-brief-writer.md +68 -0
  42. package/bundles/claude-desktop-manual/references/skills/interior-scene.md +73 -0
  43. package/bundles/claude-desktop-manual/references/skills/lighting-material-plan.md +65 -0
  44. package/bundles/claude-desktop-manual/references/skills/lighting-quality-checker.md +70 -0
  45. package/bundles/claude-desktop-manual/references/skills/material-quality-checker.md +71 -0
  46. package/bundles/claude-desktop-manual/references/skills/mobile-glb-budget.md +73 -0
  47. package/bundles/claude-desktop-manual/references/skills/output-format-decision.md +63 -0
  48. package/bundles/claude-desktop-manual/references/skills/pack-prerequisite-checker.md +74 -0
  49. package/bundles/claude-desktop-manual/references/skills/path-one-host-outline.md +66 -0
  50. package/bundles/claude-desktop-manual/references/skills/plain-language-response.md +70 -0
  51. package/bundles/claude-desktop-manual/references/skills/polycount-budget-checker.md +71 -0
  52. package/bundles/claude-desktop-manual/references/skills/pre-handoff-verification.md +76 -0
  53. package/bundles/claude-desktop-manual/references/skills/preview-report.md +62 -0
  54. package/bundles/claude-desktop-manual/references/skills/product-grid-scene-planner.md +72 -0
  55. package/bundles/claude-desktop-manual/references/skills/product-hero-scene-planner.md +68 -0
  56. package/bundles/claude-desktop-manual/references/skills/r3f-component-plan.md +66 -0
  57. package/bundles/claude-desktop-manual/references/skills/recipe-fit-assessor.md +75 -0
  58. package/bundles/claude-desktop-manual/references/skills/render-export-evidence.md +70 -0
  59. package/bundles/claude-desktop-manual/references/skills/resolution-aspect-decision.md +65 -0
  60. package/bundles/claude-desktop-manual/references/skills/runtime-attempt-report.md +67 -0
  61. package/bundles/claude-desktop-manual/references/skills/runtime-path-picker.md +67 -0
  62. package/bundles/claude-desktop-manual/references/skills/runtime-readiness.md +63 -0
  63. package/bundles/claude-desktop-manual/references/skills/runtime-setup.md +63 -0
  64. package/bundles/claude-desktop-manual/references/skills/scene-readiness.md +65 -0
  65. package/bundles/claude-desktop-manual/references/skills/scope-guard.md +62 -0
  66. package/bundles/claude-desktop-manual/references/skills/stage-gates.md +91 -0
  67. package/bundles/claude-desktop-manual/references/skills/workflow-stage-router.md +67 -0
  68. package/bundles/generic-project-local/BLENDOPS.md +71 -0
  69. package/bundles/generic-project-local/INSTALL_REPORT_TEMPLATE.md +52 -0
  70. package/bundles/generic-project-local/README.md +73 -0
  71. package/bundles/generic-project-local/ROLLBACK.md +66 -0
  72. package/bundles/generic-project-local/manifest.json +66 -0
  73. package/bundles/skill-package/README.md +54 -0
  74. package/bundles/skill-package/blendops/LICENSE.txt +21 -0
  75. package/bundles/skill-package/blendops/SKILL.md +50 -0
  76. package/bundles/skill-package/blendops/agents/README.md +61 -0
  77. package/bundles/skill-package/blendops/agents/openai.yaml +4 -0
  78. package/bundles/skill-package/blendops/references/evidence-rules.md +17 -0
  79. package/bundles/skill-package/blendops/references/install-boundary.md +13 -0
  80. package/bundles/skill-package/blendops/references/law-evidence-before-done.md +12 -0
  81. package/bundles/skill-package/blendops/references/law-no-arbitrary-python-interface.md +7 -0
  82. package/bundles/skill-package/blendops/references/law-non-blender-user-language.md +8 -0
  83. package/bundles/skill-package/blendops/references/law-official-runtime-only.md +9 -0
  84. package/bundles/skill-package/blendops/references/pack-product-hero-v0.md +21 -0
  85. package/bundles/skill-package/blendops/references/runtime-stacks.md +13 -0
  86. package/bundles/skill-package/blendops/references/skill-acceptance-criteria-builder.md +51 -0
  87. package/bundles/skill-package/blendops/references/skill-asset-discovery.md +54 -0
  88. package/bundles/skill-package/blendops/references/skill-asset-fallback-strategy.md +48 -0
  89. package/bundles/skill-package/blendops/references/skill-asset-library-plan.md +51 -0
  90. package/bundles/skill-package/blendops/references/skill-asset-license-checker.md +51 -0
  91. package/bundles/skill-package/blendops/references/skill-asset-style-check.md +52 -0
  92. package/bundles/skill-package/blendops/references/skill-blender-brainstorming.md +43 -0
  93. package/bundles/skill-package/blendops/references/skill-blender-recipe-decomposer.md +48 -0
  94. package/bundles/skill-package/blendops/references/skill-blender-troubleshooting.md +59 -0
  95. package/bundles/skill-package/blendops/references/skill-blendops-help.md +62 -0
  96. package/bundles/skill-package/blendops/references/skill-bridge-conflicts.md +48 -0
  97. package/bundles/skill-package/blendops/references/skill-camera-composition.md +48 -0
  98. package/bundles/skill-package/blendops/references/skill-character-portrait.md +50 -0
  99. package/bundles/skill-package/blendops/references/skill-cli-appendix-job-outline.md +44 -0
  100. package/bundles/skill-package/blendops/references/skill-color-management-decision.md +50 -0
  101. package/bundles/skill-package/blendops/references/skill-composition-quality-checker.md +53 -0
  102. package/bundles/skill-package/blendops/references/skill-cycles-vs-eevee-decision.md +47 -0
  103. package/bundles/skill-package/blendops/references/skill-done-criteria.md +53 -0
  104. package/bundles/skill-package/blendops/references/skill-environment-shot.md +47 -0
  105. package/bundles/skill-package/blendops/references/skill-glb-animation-handoff.md +51 -0
  106. package/bundles/skill-package/blendops/references/skill-glb-web-handoff.md +51 -0
  107. package/bundles/skill-package/blendops/references/skill-intent-to-3d-brief-writer.md +50 -0
  108. package/bundles/skill-package/blendops/references/skill-interior-scene.md +54 -0
  109. package/bundles/skill-package/blendops/references/skill-lighting-material-plan.md +48 -0
  110. package/bundles/skill-package/blendops/references/skill-lighting-quality-checker.md +52 -0
  111. package/bundles/skill-package/blendops/references/skill-map.md +32 -0
  112. package/bundles/skill-package/blendops/references/skill-material-quality-checker.md +53 -0
  113. package/bundles/skill-package/blendops/references/skill-mobile-glb-budget.md +55 -0
  114. package/bundles/skill-package/blendops/references/skill-output-format-decision.md +46 -0
  115. package/bundles/skill-package/blendops/references/skill-pack-prerequisite-checker.md +56 -0
  116. package/bundles/skill-package/blendops/references/skill-path-one-host-outline.md +48 -0
  117. package/bundles/skill-package/blendops/references/skill-plain-language-response.md +53 -0
  118. package/bundles/skill-package/blendops/references/skill-polycount-budget-checker.md +53 -0
  119. package/bundles/skill-package/blendops/references/skill-pre-handoff-verification.md +57 -0
  120. package/bundles/skill-package/blendops/references/skill-preview-report.md +45 -0
  121. package/bundles/skill-package/blendops/references/skill-product-grid-scene-planner.md +54 -0
  122. package/bundles/skill-package/blendops/references/skill-product-hero-scene-planner.md +51 -0
  123. package/bundles/skill-package/blendops/references/skill-r3f-component-plan.md +48 -0
  124. package/bundles/skill-package/blendops/references/skill-recipe-fit-assessor.md +57 -0
  125. package/bundles/skill-package/blendops/references/skill-render-export-evidence.md +51 -0
  126. package/bundles/skill-package/blendops/references/skill-resolution-aspect-decision.md +48 -0
  127. package/bundles/skill-package/blendops/references/skill-runtime-attempt-report.md +49 -0
  128. package/bundles/skill-package/blendops/references/skill-runtime-path-picker.md +49 -0
  129. package/bundles/skill-package/blendops/references/skill-runtime-readiness.md +45 -0
  130. package/bundles/skill-package/blendops/references/skill-runtime-setup.md +45 -0
  131. package/bundles/skill-package/blendops/references/skill-scene-readiness.md +48 -0
  132. package/bundles/skill-package/blendops/references/skill-scope-guard.md +44 -0
  133. package/bundles/skill-package/blendops/references/skill-stage-gates.md +73 -0
  134. package/bundles/skill-package/blendops/references/skill-workflow-stage-router.md +49 -0
  135. package/docs/README.md +276 -0
  136. package/docs/examples/glb-web-handoff/README.md +174 -0
  137. package/docs/examples/glb-web-handoff/r3f-glb-viewer.tsx +320 -0
  138. package/docs/examples/glb-web-handoff/threejs-glb-viewer.mjs +709 -0
  139. package/docs/knowledge-and-recipe-catalog.md +236 -0
  140. package/docs/recipes/README.md +27 -0
  141. package/docs/recipes/cyberpunk-shoe-hero.md +97 -0
  142. package/docs/workflows/README.md +14 -0
  143. package/docs/workflows/full-non-blender-user-workflow.md +210 -0
  144. package/docs/workflows/product-hero-workflow.md +92 -0
  145. package/laws/README.md +32 -0
  146. package/laws/evidence-before-done.md +37 -0
  147. package/laws/no-arbitrary-python-interface.md +32 -0
  148. package/laws/non-blender-user-language.md +32 -0
  149. package/laws/official-runtime-only.md +78 -0
  150. package/package.json +103 -4
  151. package/packs/README.md +11 -0
  152. package/packs/product-hero-v0/PACK.md +114 -0
  153. package/registry/catalog-index.json +21344 -0
  154. package/registry/compatibility-matrix.json +533 -0
  155. package/registry/contract-context-fields.json +391 -0
  156. package/registry/knowledge-catalog.json +4648 -0
  157. package/registry/knowledge-sources.json +438 -0
  158. package/registry/recipe-catalog.json +2565 -0
  159. package/registry/runtime-capability-policy.json +525 -0
  160. package/registry/runtime-operations.json +4468 -0
  161. package/registry/skills.json +10231 -0
  162. package/registry/workflow-graph.json +7390 -0
  163. package/schemas/adapter-compatibility-matrix.schema.json +166 -0
  164. package/schemas/contract-context-fields.schema.json +147 -0
  165. package/schemas/execution-plan.schema.json +325 -0
  166. package/schemas/glb-web-handoff-manifest.schema.json +744 -0
  167. package/schemas/knowledge-record.schema.json +460 -0
  168. package/schemas/knowledge-source-registry.schema.json +268 -0
  169. package/schemas/operation-execution-ledger.schema.json +348 -0
  170. package/schemas/recipe-record.schema.json +469 -0
  171. package/schemas/runtime-capability-policy.schema.json +184 -0
  172. package/schemas/runtime-evidence-packet.schema.json +211 -0
  173. package/schemas/runtime-operations.schema.json +535 -0
  174. package/schemas/runtime-qualification-report.schema.json +540 -0
  175. package/schemas/runtime-session.schema.json +350 -0
  176. package/schemas/scene-spec.schema.json +624 -0
  177. package/schemas/skill-contract.schema.json +402 -0
  178. package/schemas/skill-eval.schema.json +509 -0
  179. package/scripts/build-knowledge-catalog.mjs +2376 -0
  180. package/scripts/compile-scene-plan.mjs +1945 -0
  181. package/scripts/export-claude-skills.mjs +634 -0
  182. package/scripts/generate-glb-handoff-report.mjs +2376 -0
  183. package/scripts/inspect-glb.mjs +1627 -0
  184. package/scripts/install-skills.mjs +5443 -0
  185. package/scripts/runtime-orchestrator.mjs +7713 -0
  186. package/scripts/validate-capability-policy.mjs +531 -0
  187. package/scripts/validate-evidence-packet.mjs +256 -0
  188. package/skills/README.md +315 -0
  189. package/skills/_template/SKILL.md +296 -0
  190. package/skills/acceptance-criteria-builder/EVAL.md +25 -0
  191. package/skills/acceptance-criteria-builder/SKILL.md +257 -0
  192. package/skills/acceptance-criteria-builder/contract.json +205 -0
  193. package/skills/acceptance-criteria-builder/references/brief-to-criteria-mapper.md +22 -0
  194. package/skills/acceptance-criteria-builder/references/checklist-patterns.md +22 -0
  195. package/skills/acceptance-criteria-builder/references/evidence-hook-rules.md +19 -0
  196. package/skills/asset-discovery/EVAL.md +81 -0
  197. package/skills/asset-discovery/SKILL.md +252 -0
  198. package/skills/asset-discovery/contract.json +291 -0
  199. package/skills/asset-discovery/references/asset-strategy-decision-tree.md +40 -0
  200. package/skills/asset-discovery/references/budget-reconciliation-patterns.md +54 -0
  201. package/skills/asset-discovery/references/license-confidence-table.md +41 -0
  202. package/skills/asset-fallback-strategy/EVAL.md +34 -0
  203. package/skills/asset-fallback-strategy/SKILL.md +248 -0
  204. package/skills/asset-fallback-strategy/contract.json +190 -0
  205. package/skills/asset-fallback-strategy/references/drop-with-caveat-rules.md +36 -0
  206. package/skills/asset-fallback-strategy/references/fallback-option-types.md +55 -0
  207. package/skills/asset-fallback-strategy/references/scoring-rubric.md +61 -0
  208. package/skills/asset-library-plan/EVAL.md +28 -0
  209. package/skills/asset-library-plan/SKILL.md +263 -0
  210. package/skills/asset-library-plan/contract.json +177 -0
  211. package/skills/asset-library-plan/references/folder-structure-rules.md +63 -0
  212. package/skills/asset-library-plan/references/metadata-schema.md +62 -0
  213. package/skills/asset-library-plan/references/naming-rules.md +51 -0
  214. package/skills/asset-license-checker/EVAL.md +33 -0
  215. package/skills/asset-license-checker/SKILL.md +245 -0
  216. package/skills/asset-license-checker/contract.json +172 -0
  217. package/skills/asset-license-checker/references/attribution-rendering-patterns.md +48 -0
  218. package/skills/asset-license-checker/references/common-license-mapping.md +39 -0
  219. package/skills/asset-license-checker/references/license-source-rules.md +38 -0
  220. package/skills/asset-style-check/EVAL.md +26 -0
  221. package/skills/asset-style-check/SKILL.md +238 -0
  222. package/skills/asset-style-check/contract.json +251 -0
  223. package/skills/asset-style-check/references/drift-classification.md +40 -0
  224. package/skills/asset-style-check/references/intentional-mixed-style.md +39 -0
  225. package/skills/asset-style-check/references/style-axes.md +46 -0
  226. package/skills/blender-brainstorming/EVAL.md +79 -0
  227. package/skills/blender-brainstorming/SKILL.md +228 -0
  228. package/skills/blender-brainstorming/contract.json +115 -0
  229. package/skills/blender-brainstorming/references/alternative-scoping-templates.md +43 -0
  230. package/skills/blender-brainstorming/references/clarification-patterns.md +29 -0
  231. package/skills/blender-brainstorming/references/intent-summary-style-guide.md +25 -0
  232. package/skills/blender-recipe-decomposer/EVAL.md +35 -0
  233. package/skills/blender-recipe-decomposer/SKILL.md +258 -0
  234. package/skills/blender-recipe-decomposer/contract.json +152 -0
  235. package/skills/blender-recipe-decomposer/references/dependency-patterns.md +53 -0
  236. package/skills/blender-recipe-decomposer/references/recipe-grouping-rules.md +58 -0
  237. package/skills/blender-recipe-decomposer/references/recipe-naming-rules.md +44 -0
  238. package/skills/blender-troubleshooting/EVAL.md +78 -0
  239. package/skills/blender-troubleshooting/SKILL.md +263 -0
  240. package/skills/blender-troubleshooting/contract.json +352 -0
  241. package/skills/blender-troubleshooting/references/common-symptom-playbooks.md +51 -0
  242. package/skills/blender-troubleshooting/references/divergence-routing-table.md +23 -0
  243. package/skills/blender-troubleshooting/references/four-phase-template.md +51 -0
  244. package/skills/blendops-help/EVAL.md +67 -0
  245. package/skills/blendops-help/SKILL.md +312 -0
  246. package/skills/blendops-help/contract.json +229 -0
  247. package/skills/blendops-help/references/lifecycle-phases.md +91 -0
  248. package/skills/blendops-help/references/quick-start-prompts.md +65 -0
  249. package/skills/blendops-help/references/routing-decision-tree.md +57 -0
  250. package/skills/bridge-conflicts/EVAL.md +83 -0
  251. package/skills/bridge-conflicts/SKILL.md +246 -0
  252. package/skills/bridge-conflicts/contract.json +145 -0
  253. package/skills/bridge-conflicts/references/bridge-state-matrix-template.md +82 -0
  254. package/skills/bridge-conflicts/references/conflict-playbooks.md +99 -0
  255. package/skills/bridge-conflicts/references/do-not-reminders.md +42 -0
  256. package/skills/camera-composition/EVAL.md +32 -0
  257. package/skills/camera-composition/SKILL.md +196 -0
  258. package/skills/camera-composition/contract.json +180 -0
  259. package/skills/camera-composition/references/camera-presets.md +30 -0
  260. package/skills/camera-composition/references/camera-rubric.md +24 -0
  261. package/skills/camera-composition/references/hero-composition-patterns.md +24 -0
  262. package/skills/camera-composition/references/web-layout-negative-space.md +25 -0
  263. package/skills/character-portrait/EVAL.md +42 -0
  264. package/skills/character-portrait/SKILL.md +245 -0
  265. package/skills/character-portrait/contract.json +205 -0
  266. package/skills/character-portrait/references/portrait-framing-rules.md +39 -0
  267. package/skills/character-portrait/references/portrait-lighting-patterns.md +50 -0
  268. package/skills/character-portrait/references/style-consistency-rules.md +41 -0
  269. package/skills/cli-appendix-job-outline/EVAL.md +26 -0
  270. package/skills/cli-appendix-job-outline/SKILL.md +252 -0
  271. package/skills/cli-appendix-job-outline/contract.json +147 -0
  272. package/skills/cli-appendix-job-outline/references/flag-order-reminders.md +16 -0
  273. package/skills/cli-appendix-job-outline/references/job-type-matrix.md +13 -0
  274. package/skills/cli-appendix-job-outline/references/stateless-limitations.md +12 -0
  275. package/skills/color-management-decision/EVAL.md +28 -0
  276. package/skills/color-management-decision/SKILL.md +254 -0
  277. package/skills/color-management-decision/contract.json +162 -0
  278. package/skills/color-management-decision/references/look-comparison.md +44 -0
  279. package/skills/color-management-decision/references/per-channel-rules.md +49 -0
  280. package/skills/color-management-decision/references/pipeline-mapping.md +47 -0
  281. package/skills/composition-quality-checker/EVAL.md +38 -0
  282. package/skills/composition-quality-checker/SKILL.md +260 -0
  283. package/skills/composition-quality-checker/contract.json +221 -0
  284. package/skills/composition-quality-checker/references/aspect-ratio-rules.md +37 -0
  285. package/skills/composition-quality-checker/references/composition-rules.md +58 -0
  286. package/skills/composition-quality-checker/references/headroom-leadroom-rules.md +46 -0
  287. package/skills/cycles-vs-eevee-decision/EVAL.md +26 -0
  288. package/skills/cycles-vs-eevee-decision/SKILL.md +249 -0
  289. package/skills/cycles-vs-eevee-decision/contract.json +142 -0
  290. package/skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md +39 -0
  291. package/skills/cycles-vs-eevee-decision/references/gpu-device-rules.md +51 -0
  292. package/skills/cycles-vs-eevee-decision/references/samples-by-quality.md +53 -0
  293. package/skills/done-criteria/EVAL.md +33 -0
  294. package/skills/done-criteria/SKILL.md +225 -0
  295. package/skills/done-criteria/contract.json +199 -0
  296. package/skills/done-criteria/references/done-vs-perfect.md +56 -0
  297. package/skills/done-criteria/references/out-of-scope-patterns.md +50 -0
  298. package/skills/done-criteria/references/stop-condition-templates.md +39 -0
  299. package/skills/environment-shot/EVAL.md +44 -0
  300. package/skills/environment-shot/SKILL.md +237 -0
  301. package/skills/environment-shot/contract.json +162 -0
  302. package/skills/environment-shot/references/depth-layering-rules.md +49 -0
  303. package/skills/environment-shot/references/time-and-weather-rules.md +35 -0
  304. package/skills/environment-shot/references/wide-shot-camera-rules.md +51 -0
  305. package/skills/glb-animation-handoff/EVAL.md +39 -0
  306. package/skills/glb-animation-handoff/SKILL.md +271 -0
  307. package/skills/glb-animation-handoff/contract.json +247 -0
  308. package/skills/glb-animation-handoff/references/animation-types.md +36 -0
  309. package/skills/glb-animation-handoff/references/transition-rules.md +55 -0
  310. package/skills/glb-animation-handoff/references/web-stack-caveats.md +40 -0
  311. package/skills/glb-web-handoff/EVAL.md +33 -0
  312. package/skills/glb-web-handoff/SKILL.md +212 -0
  313. package/skills/glb-web-handoff/contract.json +171 -0
  314. package/skills/glb-web-handoff/references/artifact-status-language.md +26 -0
  315. package/skills/glb-web-handoff/references/glb-handoff-checklist.md +30 -0
  316. package/skills/glb-web-handoff/references/performance-caveats.md +26 -0
  317. package/skills/glb-web-handoff/references/threejs-r3f-handoff.md +28 -0
  318. package/skills/intent-to-3d-brief-writer/EVAL.md +82 -0
  319. package/skills/intent-to-3d-brief-writer/SKILL.md +238 -0
  320. package/skills/intent-to-3d-brief-writer/contract.json +195 -0
  321. package/skills/intent-to-3d-brief-writer/references/acceptance-criteria-patterns.md +46 -0
  322. package/skills/intent-to-3d-brief-writer/references/eight-slot-template.md +123 -0
  323. package/skills/intent-to-3d-brief-writer/references/mixed-audience-handling.md +39 -0
  324. package/skills/interior-scene/EVAL.md +44 -0
  325. package/skills/interior-scene/SKILL.md +261 -0
  326. package/skills/interior-scene/contract.json +277 -0
  327. package/skills/interior-scene/references/furniture-layout-rules.md +51 -0
  328. package/skills/interior-scene/references/interior-architecture-rules.md +47 -0
  329. package/skills/interior-scene/references/interior-camera-rules.md +47 -0
  330. package/skills/lighting-material-plan/EVAL.md +32 -0
  331. package/skills/lighting-material-plan/SKILL.md +194 -0
  332. package/skills/lighting-material-plan/contract.json +213 -0
  333. package/skills/lighting-material-plan/references/cyberpunk-lookdev.md +22 -0
  334. package/skills/lighting-material-plan/references/lighting-patterns.md +30 -0
  335. package/skills/lighting-material-plan/references/material-portability.md +25 -0
  336. package/skills/lighting-material-plan/references/reflective-floor-pattern.md +22 -0
  337. package/skills/lighting-material-plan/references/web-material-simplification.md +23 -0
  338. package/skills/lighting-quality-checker/EVAL.md +41 -0
  339. package/skills/lighting-quality-checker/SKILL.md +247 -0
  340. package/skills/lighting-quality-checker/contract.json +187 -0
  341. package/skills/lighting-quality-checker/references/hdri-balance-rules.md +48 -0
  342. package/skills/lighting-quality-checker/references/intensity-ranges.md +73 -0
  343. package/skills/lighting-quality-checker/references/shadow-softness-rules.md +38 -0
  344. package/skills/material-quality-checker/EVAL.md +40 -0
  345. package/skills/material-quality-checker/SKILL.md +261 -0
  346. package/skills/material-quality-checker/contract.json +244 -0
  347. package/skills/material-quality-checker/references/consumer-stack-rules.md +62 -0
  348. package/skills/material-quality-checker/references/pbr-sanity-rules.md +78 -0
  349. package/skills/material-quality-checker/references/texture-budget-rules.md +48 -0
  350. package/skills/mobile-glb-budget/EVAL.md +40 -0
  351. package/skills/mobile-glb-budget/SKILL.md +264 -0
  352. package/skills/mobile-glb-budget/contract.json +309 -0
  353. package/skills/mobile-glb-budget/references/budget-tiers.md +30 -0
  354. package/skills/mobile-glb-budget/references/degradation-plan.md +34 -0
  355. package/skills/mobile-glb-budget/references/violation-rules.md +43 -0
  356. package/skills/output-format-decision/EVAL.md +27 -0
  357. package/skills/output-format-decision/SKILL.md +222 -0
  358. package/skills/output-format-decision/contract.json +179 -0
  359. package/skills/output-format-decision/references/bit-depth-rules.md +56 -0
  360. package/skills/output-format-decision/references/compression-tradeoffs.md +62 -0
  361. package/skills/output-format-decision/references/format-decision-matrix.md +34 -0
  362. package/skills/pack-prerequisite-checker/EVAL.md +26 -0
  363. package/skills/pack-prerequisite-checker/SKILL.md +272 -0
  364. package/skills/pack-prerequisite-checker/contract.json +214 -0
  365. package/skills/pack-prerequisite-checker/references/blocked-start-playbook.md +21 -0
  366. package/skills/pack-prerequisite-checker/references/pack-readiness-template.md +38 -0
  367. package/skills/pack-prerequisite-checker/references/prerequisite-matrix.md +20 -0
  368. package/skills/path-one-host-outline/EVAL.md +26 -0
  369. package/skills/path-one-host-outline/SKILL.md +251 -0
  370. package/skills/path-one-host-outline/contract.json +167 -0
  371. package/skills/path-one-host-outline/references/connector-vs-manual-matrix.md +21 -0
  372. package/skills/path-one-host-outline/references/host-checklist-template.md +35 -0
  373. package/skills/path-one-host-outline/references/lab-addon-reminders.md +12 -0
  374. package/skills/plain-language-response/EVAL.md +33 -0
  375. package/skills/plain-language-response/SKILL.md +194 -0
  376. package/skills/plain-language-response/contract.json +242 -0
  377. package/skills/plain-language-response/references/caveat-language.md +25 -0
  378. package/skills/plain-language-response/references/plain-language-patterns.md +30 -0
  379. package/skills/plain-language-response/references/stakeholder-friendly-examples.md +30 -0
  380. package/skills/plain-language-response/references/status-summary-templates.md +50 -0
  381. package/skills/polycount-budget-checker/EVAL.md +40 -0
  382. package/skills/polycount-budget-checker/SKILL.md +251 -0
  383. package/skills/polycount-budget-checker/contract.json +196 -0
  384. package/skills/polycount-budget-checker/references/instance-counting-rules.md +39 -0
  385. package/skills/polycount-budget-checker/references/per-mesh-rules.md +43 -0
  386. package/skills/polycount-budget-checker/references/topology-hints.md +56 -0
  387. package/skills/pre-handoff-verification/EVAL.md +84 -0
  388. package/skills/pre-handoff-verification/SKILL.md +252 -0
  389. package/skills/pre-handoff-verification/contract.json +295 -0
  390. package/skills/pre-handoff-verification/references/downgrade-rules.md +39 -0
  391. package/skills/pre-handoff-verification/references/seven-point-checklist.md +46 -0
  392. package/skills/pre-handoff-verification/references/text-only-mode-handling.md +36 -0
  393. package/skills/preview-report/EVAL.md +39 -0
  394. package/skills/preview-report/SKILL.md +254 -0
  395. package/skills/preview-report/contract.json +141 -0
  396. package/skills/preview-report/references/handoff-recipients.md +41 -0
  397. package/skills/preview-report/references/report-schema.md +60 -0
  398. package/skills/preview-report/references/truth-label-rules.md +36 -0
  399. package/skills/product-grid-scene-planner/EVAL.md +42 -0
  400. package/skills/product-grid-scene-planner/SKILL.md +246 -0
  401. package/skills/product-grid-scene-planner/contract.json +257 -0
  402. package/skills/product-grid-scene-planner/references/grid-consistency-rules.md +53 -0
  403. package/skills/product-grid-scene-planner/references/grid-layout-rules.md +42 -0
  404. package/skills/product-grid-scene-planner/references/grid-output-naming-rules.md +52 -0
  405. package/skills/product-hero-scene-planner/EVAL.md +33 -0
  406. package/skills/product-hero-scene-planner/SKILL.md +227 -0
  407. package/skills/product-hero-scene-planner/contract.json +228 -0
  408. package/skills/product-hero-scene-planner/references/clarification-patterns.md +24 -0
  409. package/skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md +28 -0
  410. package/skills/product-hero-scene-planner/references/product-hero-playbooks.md +22 -0
  411. package/skills/product-hero-scene-planner/references/scene-plan-schema.md +35 -0
  412. package/skills/r3f-component-plan/EVAL.md +43 -0
  413. package/skills/r3f-component-plan/SKILL.md +290 -0
  414. package/skills/r3f-component-plan/contract.json +171 -0
  415. package/skills/r3f-component-plan/references/component-shape-patterns.md +54 -0
  416. package/skills/r3f-component-plan/references/suspense-placement-rules.md +50 -0
  417. package/skills/r3f-component-plan/references/usegltf-caching-rules.md +53 -0
  418. package/skills/recipe-fit-assessor/EVAL.md +28 -0
  419. package/skills/recipe-fit-assessor/SKILL.md +266 -0
  420. package/skills/recipe-fit-assessor/contract.json +220 -0
  421. package/skills/recipe-fit-assessor/references/recipe-catalog.md +30 -0
  422. package/skills/recipe-fit-assessor/references/scope-gap-rules.md +27 -0
  423. package/skills/recipe-fit-assessor/references/workflow-recommendation-template.md +34 -0
  424. package/skills/render-export-evidence/EVAL.md +86 -0
  425. package/skills/render-export-evidence/SKILL.md +339 -0
  426. package/skills/render-export-evidence/contract.json +206 -0
  427. package/skills/render-export-evidence/references/attempted-vs-failed-rubric.md +75 -0
  428. package/skills/render-export-evidence/references/evidence-record-templates.md +143 -0
  429. package/skills/render-export-evidence/references/truth-label-decision-tree.md +57 -0
  430. package/skills/resolution-aspect-decision/EVAL.md +26 -0
  431. package/skills/resolution-aspect-decision/SKILL.md +246 -0
  432. package/skills/resolution-aspect-decision/contract.json +160 -0
  433. package/skills/resolution-aspect-decision/references/aspect-defaults.md +41 -0
  434. package/skills/resolution-aspect-decision/references/print-vs-screen-rules.md +58 -0
  435. package/skills/resolution-aspect-decision/references/resolution-defaults.md +64 -0
  436. package/skills/runtime-attempt-report/EVAL.md +26 -0
  437. package/skills/runtime-attempt-report/SKILL.md +268 -0
  438. package/skills/runtime-attempt-report/contract.json +176 -0
  439. package/skills/runtime-attempt-report/references/attempt-record-template.md +49 -0
  440. package/skills/runtime-attempt-report/references/triage-next-steps.md +15 -0
  441. package/skills/runtime-attempt-report/references/truth-label-blocks.md +27 -0
  442. package/skills/runtime-path-picker/EVAL.md +26 -0
  443. package/skills/runtime-path-picker/SKILL.md +268 -0
  444. package/skills/runtime-path-picker/contract.json +191 -0
  445. package/skills/runtime-path-picker/references/anti-patterns.md +14 -0
  446. package/skills/runtime-path-picker/references/decision-tree.md +29 -0
  447. package/skills/runtime-path-picker/references/path-constraints-table.md +18 -0
  448. package/skills/runtime-readiness/EVAL.md +33 -0
  449. package/skills/runtime-readiness/SKILL.md +218 -0
  450. package/skills/runtime-readiness/contract.json +190 -0
  451. package/skills/runtime-readiness/references/blocker-report-template.md +28 -0
  452. package/skills/runtime-readiness/references/evidence-examples.md +23 -0
  453. package/skills/runtime-readiness/references/readiness-matrix.md +46 -0
  454. package/skills/runtime-setup/EVAL.md +33 -0
  455. package/skills/runtime-setup/SKILL.md +209 -0
  456. package/skills/runtime-setup/contract.json +171 -0
  457. package/skills/runtime-setup/references/runtime-option-decision-tree.md +28 -0
  458. package/skills/runtime-setup/references/setup-summary-template.md +33 -0
  459. package/skills/runtime-setup/references/source-confidence-labels.md +23 -0
  460. package/skills/scene-readiness/EVAL.md +33 -0
  461. package/skills/scene-readiness/SKILL.md +195 -0
  462. package/skills/scene-readiness/contract.json +198 -0
  463. package/skills/scene-readiness/references/blocker-catalog.md +24 -0
  464. package/skills/scene-readiness/references/not-run-handling.md +22 -0
  465. package/skills/scene-readiness/references/quality-rubric.md +23 -0
  466. package/skills/scene-readiness/references/verdict-language.md +22 -0
  467. package/skills/scope-guard/EVAL.md +33 -0
  468. package/skills/scope-guard/SKILL.md +222 -0
  469. package/skills/scope-guard/contract.json +171 -0
  470. package/skills/scope-guard/references/options-language-template.md +51 -0
  471. package/skills/scope-guard/references/recurring-creep-patterns.md +55 -0
  472. package/skills/scope-guard/references/scope-addition-classification.md +55 -0
  473. package/skills/stage-gates/EVAL.md +40 -0
  474. package/skills/stage-gates/SKILL.md +257 -0
  475. package/skills/stage-gates/contract.json +490 -0
  476. package/skills/stage-gates/references/failed-gate-handling.md +42 -0
  477. package/skills/stage-gates/references/gate-template.md +46 -0
  478. package/skills/stage-gates/references/stage-decomposition-patterns.md +55 -0
  479. package/skills/workflow-stage-router/EVAL.md +25 -0
  480. package/skills/workflow-stage-router/SKILL.md +259 -0
  481. package/skills/workflow-stage-router/contract.json +150 -0
  482. package/skills/workflow-stage-router/references/milestone-model.md +20 -0
  483. package/skills/workflow-stage-router/references/routing-decision-tree.md +32 -0
  484. package/skills/workflow-stage-router/references/stage-handoff-template.md +37 -0
  485. package/skills.sh.json +102 -0
@@ -0,0 +1,4648 @@
1
+ {
2
+ "$schema": "../schemas/knowledge-record.schema.json",
3
+ "schemaVersion": "1.0.0",
4
+ "records": [
5
+ {
6
+ "id": "knowledge.quad-dominant-subdivision-topology",
7
+ "title": "Quad-Dominant Subdivision Topology, Pole Routing & Edge-Flow Discipline",
8
+ "domain": "modeling-and-topology",
9
+ "kind": "topology-rule",
10
+ "summary": "Rules for constructing quad-dominant Catmull-Clark subdivision surfaces and deforming meshes, routing 3-edge (N-pole) and 5-edge (E-pole) vertices onto low-curvature planes, and placing support holding loops.",
11
+ "aliases": [
12
+ "catmull-clark-subdivision-topology",
13
+ "quad-edge-flow-and-pole-routing",
14
+ "holding-loops-and-subsurf-pinching"
15
+ ],
16
+ "intent_signals": [
17
+ "fix pinching or lumpiness on a Subdivision Surface mesh",
18
+ "route edge loops and poles for clean quad topology",
19
+ "add holding support loops for sharp creases under subdivision",
20
+ "prepare deforming character or hero product quad topology"
21
+ ],
22
+ "applicability": {
23
+ "when_to_apply": [
24
+ "The mesh uses a Catmull-Clark Subdivision Surface modifier for close-up hero rendering or smooth curved silhouettes.",
25
+ "The mesh will deform via skeletal armature skinning or morph targets (shape keys) where triangles and N-gons cause shading creases."
26
+ ],
27
+ "when_not_to_apply": [
28
+ "The surface is a completely flat, non-deforming architectural wall or floor plane that will never be subdivided or bent.",
29
+ "The asset is a final triangulated low-polyLOD export where MikkTSpace tangents are already locked."
30
+ ],
31
+ "target_representations": [
32
+ "subdivision-mesh",
33
+ "hard-surface-mesh",
34
+ "skeletal-armature"
35
+ ]
36
+ },
37
+ "prerequisites": [
38
+ "Object scale applied to (1.0, 1.0, 1.0) and duplicate vertices merged by distance."
39
+ ],
40
+ "principles": [
41
+ "Catmull-Clark subdivision averages vertex positions across quad rings; triangles and N-gons on curved transitions interrupt continuous edge loops and produce visible specular pinching.",
42
+ "Vertices with 3 edges (N-poles) or 5 edges (E-poles) are mathematically unavoidable when redirecting edge flow, but must be shifted at least one quad loop inset from sharp ridges onto flatter regions.",
43
+ "Vertices with 6 or more edges (high-valence stars) cause radiating shading ripples under subdivision and should be split into quad grids.",
44
+ "Support holding loops control crease tightness more predictably across FBX/glTF interchange than Blender-specific Mean Edge Crease weights."
45
+ ],
46
+ "implementation_guidance": {
47
+ "workflow_steps": [
48
+ "Establish primary silhouette loops and boundary perimeter loops before adding interior grid subdivisions.",
49
+ "Place parallel holding loops (via Loop Cut or a 2-segment Profile=1.0 Bevel modifier) on both sides of structural creases.",
50
+ "Inspect curved regions with a high-gloss zebra or studio MatCap and slide 3-edge and 5-edge poles away from silhouette crests onto planar regions."
51
+ ],
52
+ "recommended_parameters": {
53
+ "subdivision_levels_viewport": 2,
54
+ "subdivision_levels_render": 2,
55
+ "bevel_support_segments": 2,
56
+ "bevel_support_profile": 1,
57
+ "max_pole_valence": 5
58
+ },
59
+ "blender_context": "Modifiers -> Generate -> Subdivision Surface (Catmull-Clark); Edit Mode -> Loop Cut (Ctrl+R) and Edge Slide (G, G); Viewport Shading -> MatCap."
60
+ },
61
+ "observable_checks": [
62
+ {
63
+ "id": "check.zero-high-valence-poles-on-curves",
64
+ "check": "Select vertices by trait or inspect curved ridges for 6+ edge star poles or N-gons.",
65
+ "pass_condition": "Zero 6+ valence poles on curved surfaces and zero N-gons crossing curved borders.",
66
+ "fail_indicator": "Radiating star pinching visible under glossy MatCap reflection lines."
67
+ },
68
+ {
69
+ "id": "check.uniform-quad-aspect-ratio",
70
+ "check": "Compare quad aspect ratios across primary curved surfaces.",
71
+ "pass_condition": "Quads remain near-square (aspect ratio < 4:1) across deforming or curved zones.",
72
+ "fail_indicator": "Elongated sliver quads cause stretched highlights and uneven subdivision density."
73
+ },
74
+ {
75
+ "id": "check.subdivision-level-budget",
76
+ "check": "Verify Subdivision Surface viewport and render levels against scene triangle budget.",
77
+ "pass_condition": "Subdivision levels are <= 2 (or 3 for macro close-ups) with each level multiplying quad count by 4x.",
78
+ "fail_indicator": "Subdivision level >= 4 explodes single-prop polygon count into millions of triangles."
79
+ }
80
+ ],
81
+ "creative_affordances": [
82
+ "Wider spacing between holding loops yields soft, organic elastomeric or Cushion-like transitions; tighter spacing produces crisp machined metal edges.",
83
+ "Concentric anatomical loops around eyes, mouth, and joints allow natural skin compression and stretching without texture swim."
84
+ ],
85
+ "known_limits": [
86
+ "Enforcing 100% quads on flat, non-subdivided hard-surface end-caps wastes triangles and complicates boolean cutouts unnecessarily.",
87
+ "Blender Edge Crease values do not transfer cleanly to standard glTF 2.0 unless the Subdivision Surface modifier is applied prior to export."
88
+ ],
89
+ "claims": [
90
+ {
91
+ "id": "claim.catmull-clark-4x-quad-multiplier",
92
+ "statement": "Each level of Catmull-Clark subdivision splits every quad into 4 quads and converts any triangle or N-gon into quads meeting at an extraordinary pole vertex.",
93
+ "scope": "Blender Subdivision Surface modifier across all supported Blender versions.",
94
+ "uncertainty_or_version_note": "Deterministic mathematical property of Catmull-Clark subdivision.",
95
+ "source_refs": [
96
+ {
97
+ "source_id": "source.blender-manual-modeling",
98
+ "locator": "Subdivision Surface Modifier — Catmull-Clark Algorithm"
99
+ }
100
+ ]
101
+ },
102
+ {
103
+ "id": "claim.pole-placement-shading-continuity",
104
+ "statement": "Placing 3-edge or 5-edge poles directly on a curved crease or silhouette ridge interrupts curvature continuity and creates visible specular pinching.",
105
+ "scope": "Curved subdivision surfaces and specular materials.",
106
+ "uncertainty_or_version_note": "Planar N-gons surrounded by a flat coplanar quad inset loop can subdivide without visible pinching.",
107
+ "source_refs": [
108
+ {
109
+ "source_id": "source.blender-manual-modeling",
110
+ "locator": "Mesh Topology — Poles and Edge Loops"
111
+ }
112
+ ]
113
+ }
114
+ ],
115
+ "source_refs": [
116
+ {
117
+ "source_id": "source.blender-manual-modeling",
118
+ "locator": "Meshes -> Structure, Primitives, and Subdivision Surface"
119
+ },
120
+ {
121
+ "source_id": "source.blender-studio-pipeline",
122
+ "locator": "Modeling & Topology Conventions"
123
+ }
124
+ ],
125
+ "related_ids": {
126
+ "knowledge_ids": [
127
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
128
+ "knowledge.boolean-bevel-shading-cleanup",
129
+ "knowledge.organic-sculpt-to-retopology-workflow"
130
+ ],
131
+ "skill_ids": [
132
+ "polycount-budget-checker",
133
+ "scene-readiness",
134
+ "product-hero-scene-planner",
135
+ "character-portrait"
136
+ ],
137
+ "recipe_ids": [
138
+ "recipe.product-hero-scene",
139
+ "recipe.hard-surface-prop"
140
+ ]
141
+ },
142
+ "blender_versions": {
143
+ "minimum": "3.0+",
144
+ "tested_or_targeted": [
145
+ "3.6 LTS",
146
+ "4.2 LTS",
147
+ "4.5.15 LTS",
148
+ "5.1+",
149
+ "5.2.3 LTS"
150
+ ],
151
+ "doc_checked_version": "5.2.3 LTS",
152
+ "runtime_tested_version": null,
153
+ "maintained_lts_versions": [
154
+ "4.2 LTS",
155
+ "4.5.15 LTS",
156
+ "5.2.3 LTS"
157
+ ],
158
+ "legacy_compatibility_target": "3.6 LTS",
159
+ "version_notes": "Catmull-Clark UV boundary smoothing options are consistent across Blender 3.6 LTS, 4.2 LTS, and 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
160
+ },
161
+ "evidence_status": "version-checked",
162
+ "promoted_from_skill_refs": [
163
+ "skills/polycount-budget-checker/references/topology-hints.md"
164
+ ]
165
+ },
166
+ {
167
+ "id": "knowledge.mesh-manifold-normals-and-scale-hygiene",
168
+ "title": "Mesh Manifold Integrity, Outward Normals & Applied Scale Hygiene",
169
+ "domain": "modeling-and-topology",
170
+ "kind": "topology-rule",
171
+ "summary": "Foundational mesh hygiene invariants requiring applied unit scale (1,1,1), consistent outward face orientation, merged coincident vertices, and manifold closed volumes before modifiers, UV unwrapping, baking, rigging, or glTF export.",
172
+ "aliases": [
173
+ "apply-scale-and-recalculate-normals",
174
+ "manifold-mesh-and-face-orientation",
175
+ "blender-transform-and-mesh-cleanup"
176
+ ],
177
+ "intent_signals": [
178
+ "bevel or UV unwrap is stretched and uneven across axes",
179
+ "faces look inside-out, invisible, or dark in Three.js and Blender",
180
+ "check mesh for non-manifold edges, flipped normals, and unapplied scale",
181
+ "clean up imported CAD or FBX mesh geometry before texturing"
182
+ ],
183
+ "applicability": {
184
+ "when_to_apply": [
185
+ "Before running Bevel, Solidify, Boolean, UV Unwrap, Armature skinning, physics simulation, or glTF/GLB export on any mesh.",
186
+ "When diagnosing unexplained shading black spots, uneven bevels, or inside-out backfaces in web viewers."
187
+ ],
188
+ "when_not_to_apply": [
189
+ "When an object's non-uniform scale is intentionally animated via keyframes and no local-space bevel/unwrap modifier is stacked on top.",
190
+ "Intentional single-sided alpha foliage cards or open ground planes where a closed manifold volume is not expected."
191
+ ],
192
+ "target_representations": [
193
+ "subdivision-mesh",
194
+ "polygon-game-mesh",
195
+ "hard-surface-mesh",
196
+ "glb-container"
197
+ ]
198
+ },
199
+ "prerequisites": [
200
+ "Mesh object exists in Object Mode without locked transform channels."
201
+ ],
202
+ "principles": [
203
+ "Mesh modifiers and UV unwrappers operate in local object space; if Object Scale is non-uniform (e.g., 1.0, 0.2, 3.5) or negative, bevel widths, solidify thicknesses, and UV islands distort proportionally.",
204
+ "Negative scale on any axis (-1.0) inverts the winding order of polygon vertices on export, causing backface culling to hide exterior surfaces in Three.js and game engines.",
205
+ "Consistent outward face normals are mandatory for refraction IOR calculations, Boolean inside/outside classification, and tangent-space normal map baking.",
206
+ "Zero-area faces, loose vertices, and interior faces trapped inside an edge shared by 3+ faces break manifold integrity and cause subdivision spikes."
207
+ ],
208
+ "implementation_guidance": {
209
+ "workflow_steps": [
210
+ "In Object Mode, select all meshes and run Object -> Apply -> Scale (or Rotation & Scale) so scale reads (1.000, 1.000, 1.000).",
211
+ "Enable Viewport Overlays -> Face Orientation to verify all exterior surfaces render blue (outward) and zero exterior surfaces render red (flipped).",
212
+ "In Edit Mode, select all (A), run Mesh -> Merge -> By Distance (0.0001 m), then Mesh -> Normals -> Recalculate Outside (Shift+N), and Select By Trait -> Non-Manifold to inspect unintended holes."
213
+ ],
214
+ "recommended_parameters": {
215
+ "object_scale_xyz": "1.0, 1.0, 1.0",
216
+ "merge_by_distance_threshold_m": 0.0001,
217
+ "face_orientation_exterior": "blue_outward"
218
+ },
219
+ "blender_context": "Object Mode -> Ctrl+A (Apply Scale); Edit Mode -> M (Merge by Distance), Shift+N (Recalculate Outside), Select -> Select All by Trait -> Non Manifold."
220
+ },
221
+ "observable_checks": [
222
+ {
223
+ "id": "check.unit-positive-scale",
224
+ "check": "Inspect Transform Scale X, Y, Z in the N-panel for all mesh and armature objects.",
225
+ "pass_condition": "Scale is exactly (1.000, 1.000, 1.000) with zero negative axes.",
226
+ "fail_indicator": "Non-unit or negative scale values present before modifier evaluation or export."
227
+ },
228
+ {
229
+ "id": "check.outward-face-orientation",
230
+ "check": "Enable Face Orientation overlay in the 3D Viewport.",
231
+ "pass_condition": "100% of visible exterior surfaces are blue (front-facing).",
232
+ "fail_indicator": "Red (back-facing) patches appear on exterior surfaces."
233
+ },
234
+ {
235
+ "id": "check.zero-coincident-or-interior-faces",
236
+ "check": "Run Merge by Distance (0.0001m) and Select All by Trait -> Interior Faces.",
237
+ "pass_condition": "Zero duplicate vertices and zero internal partitions shared by 3+ faces.",
238
+ "fail_indicator": "Coincident vertices clamp bevels to zero or interior faces pinch subdivision surfaces."
239
+ }
240
+ ],
241
+ "creative_affordances": [
242
+ "Guaranteed 1:1 metric scale ensures procedural wear masks, bevel widths (in mm), and subsurface scattering radii transfer predictably across every asset in a scene.",
243
+ "Clean manifold volumes allow effortless Boolean slicing and 3D printing/simulation reuse."
244
+ ],
245
+ "known_limits": [
246
+ "Applying scale on multi-user linked mesh data requires making the mesh single-user or applying scale consistently across all instances.",
247
+ "Open single-sided shells (e.g., cloth capes, foliage cards) will always highlight boundary edges under Select Non-Manifold; boundary edges on open sheets are acceptable if intentional."
248
+ ],
249
+ "claims": [
250
+ {
251
+ "id": "claim.local-space-modifier-distortion",
252
+ "statement": "Blender evaluates mesh modifiers and UV unwrapping in local object coordinates before object-level scale transforms are applied, causing non-uniform object scale to skew bevels and UVs.",
253
+ "scope": "All Blender mesh modifiers and UV operators.",
254
+ "uncertainty_or_version_note": "Applies to Blender 3.0+, 3.6 LTS, 4.2 LTS, and 5.1+.",
255
+ "source_refs": [
256
+ {
257
+ "source_id": "source.blender-manual-modeling",
258
+ "locator": "Object -> Apply -> Apply Transform (Scale)"
259
+ }
260
+ ]
261
+ },
262
+ {
263
+ "id": "claim.negative-scale-winding-inversion",
264
+ "statement": "An odd number of negative scale axes reverses triangle vertex winding order, causing inverted face normals in downstream glTF viewers.",
265
+ "scope": "glTF 2.0 export and WebGL backface culling.",
266
+ "uncertainty_or_version_note": "Defined in Khronos glTF 2.0 specification (counter-clockwise front-face winding).",
267
+ "source_refs": [
268
+ {
269
+ "source_id": "source.khronos-gltf-2-spec",
270
+ "locator": "Meshes — Primitive Winding Order and Normals"
271
+ }
272
+ ]
273
+ }
274
+ ],
275
+ "source_refs": [
276
+ {
277
+ "source_id": "source.blender-manual-modeling",
278
+ "locator": "Mesh Cleanup, Normals, and Apply Transforms"
279
+ },
280
+ {
281
+ "source_id": "source.khronos-gltf-2-spec",
282
+ "locator": "Coordinate System and Winding Order"
283
+ }
284
+ ],
285
+ "related_ids": {
286
+ "knowledge_ids": [
287
+ "knowledge.quad-dominant-subdivision-topology",
288
+ "knowledge.boolean-bevel-shading-cleanup",
289
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions"
290
+ ],
291
+ "skill_ids": [
292
+ "blender-troubleshooting",
293
+ "polycount-budget-checker",
294
+ "scene-readiness",
295
+ "pre-handoff-verification"
296
+ ],
297
+ "recipe_ids": [
298
+ "recipe.product-hero-scene",
299
+ "recipe.hard-surface-prop",
300
+ "recipe.uv-and-pbr-material-preparation",
301
+ "recipe.scene-quality-inspection-and-correction"
302
+ ]
303
+ },
304
+ "blender_versions": {
305
+ "minimum": "3.0+",
306
+ "tested_or_targeted": [
307
+ "3.6 LTS",
308
+ "4.2 LTS",
309
+ "4.5.15 LTS",
310
+ "5.1+",
311
+ "5.2.3 LTS"
312
+ ],
313
+ "doc_checked_version": "5.2.3 LTS",
314
+ "runtime_tested_version": null,
315
+ "maintained_lts_versions": [
316
+ "4.2 LTS",
317
+ "4.5.15 LTS",
318
+ "5.2.3 LTS"
319
+ ],
320
+ "legacy_compatibility_target": "3.6 LTS",
321
+ "version_notes": "Universal across all Blender 3.x, 4.x, and 5.x releases. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
322
+ },
323
+ "evidence_status": "version-checked",
324
+ "promoted_from_skill_refs": [
325
+ "skills/blender-troubleshooting/references/common-symptom-playbooks.md",
326
+ "skills/polycount-budget-checker/references/per-mesh-rules.md"
327
+ ]
328
+ },
329
+ {
330
+ "id": "knowledge.boolean-bevel-shading-cleanup",
331
+ "title": "Boolean Cutout Shading Cleanup, Custom Split Normals & Smooth by Angle",
332
+ "domain": "modeling-and-topology",
333
+ "kind": "topology-rule",
334
+ "summary": "Techniques for preventing diagonal shading streaks, pinched normals, and bevel overlap spikes after Boolean operations on flat and curved surfaces across Blender 3.6 LTS and 4.1+/4.2 LTS.",
335
+ "aliases": [
336
+ "boolean-shading-artifacts-fix",
337
+ "weighted-normals-and-smooth-by-angle",
338
+ "cylinder-boolean-bevel-cleanup"
339
+ ],
340
+ "intent_signals": [
341
+ "fix dark diagonal shading gradients after Boolean difference",
342
+ "how to replace Auto Smooth in Blender 4.1 and 4.2 LTS",
343
+ "clean up Boolean cutouts on a curved cylinder without pinching",
344
+ "stop Bevel modifier from clamping or spiking after a Boolean cut"
345
+ ],
346
+ "applicability": {
347
+ "when_to_apply": [
348
+ "After cutting holes, vents, or recesses into flat or curved meshes using Boolean modifiers or destructive knife/boolean tools.",
349
+ "When migrating shading setups from Blender 3.6 LTS (Mesh Auto Smooth checkbox) to Blender 4.1+/4.2 LTS/5.1+ (Smooth by Angle modifier)."
350
+ ],
351
+ "when_not_to_apply": [
352
+ "Purely organic sculpted characters that do not use sharp mechanical creases or boolean cutouts."
353
+ ],
354
+ "target_representations": [
355
+ "hard-surface-mesh",
356
+ "polygon-game-mesh",
357
+ "subdivision-mesh"
358
+ ]
359
+ },
360
+ "prerequisites": [
361
+ "Boolean operand meshes are manifold with applied scale (1,1,1) and outward normals."
362
+ ],
363
+ "principles": [
364
+ "Default smooth shading averages vertex normals equally across all adjacent faces, causing small bevel faces to pull the normals of large flat faces and produce dark gradients.",
365
+ "Weighted Normal (Face Area weight) forces large flat faces to dominate vertex normals so shading stays planar across N-gons and triangles, provided the surrounding bevel has at least 1 segment and Keep Sharp is enabled.",
366
+ "On curved cylinders, boolean cuts must land on existing longitudinal cylinder segments (or inside an inset support loop) so the surrounding curved normal interpolation is isolated from the cut perimeter.",
367
+ "In Blender 4.1+, the legacy Mesh Data -> Normals -> Auto Smooth property was removed and replaced by the Smooth by Angle modifier (Geometry Nodes group), which must sit before or integrate with Weighted Normal."
368
+ ],
369
+ "implementation_guidance": {
370
+ "workflow_steps": [
371
+ "Match the segment count of cylindrical boolean cutters to the host cylinder's vertical edge density so vertices align rather than creating sub-millimeter slivers.",
372
+ "Insert a Weld modifier (Distance = 0.0001 m) after Boolean if nearly coincident vertices cause the subsequent Bevel modifier's Clamp Overlap to stall.",
373
+ "Add a Bevel modifier (Limit Method = Angle ~30 deg, Segments >= 1, Clamp Overlap = True) followed by Smooth by Angle (Blender 4.1+) and Weighted Normal (Weight = 50-100, Keep Sharp = True) at the very end of the modifier stack."
374
+ ],
375
+ "recommended_parameters": {
376
+ "boolean_solver": "Exact",
377
+ "weld_merge_distance_m": 0.0001,
378
+ "bevel_angle_limit_deg": 30,
379
+ "weighted_normal_weight": 50,
380
+ "weighted_normal_keep_sharp": true
381
+ },
382
+ "blender_context": "Modifiers -> Generate -> Boolean (Exact), Weld, Bevel; Modifiers -> Normals -> Smooth by Angle (4.1+) and Weighted Normal."
383
+ },
384
+ "observable_checks": [
385
+ {
386
+ "id": "check.flat-planar-reflections",
387
+ "check": "Orbit viewport with a high-contrast linear stripe/zebra MatCap across boolean-cut planar faces.",
388
+ "pass_condition": "Reflection stripes remain straight and parallel across the flat face right up to the bevel edge.",
389
+ "fail_indicator": "Reflection lines bend or warp toward boolean corners."
390
+ },
391
+ {
392
+ "id": "check.bevel-width-not-clamped",
393
+ "check": "Verify that the Bevel modifier visibly bevels edges to the specified millimeter width.",
394
+ "pass_condition": "Bevel width matches target parameter without collapsing to zero width.",
395
+ "fail_indicator": "Single stray vertex pair near a boolean corner causes Clamp Overlap to freeze the entire object's bevel."
396
+ },
397
+ {
398
+ "id": "check.version-correct-auto-smooth",
399
+ "check": "Verify normal smoothing setup matches the active Blender version.",
400
+ "pass_condition": "Blender 3.6 LTS uses Mesh Auto Smooth + Weighted Normal (Keep Sharp); Blender 4.2 LTS / 5.1+ uses Smooth by Angle modifier or Bevel Harden Normals + Weighted Normal.",
401
+ "fail_indicator": "Instructions reference the removed `mesh.use_auto_smooth` property on Blender 4.2 LTS."
402
+ }
403
+ ],
404
+ "creative_affordances": [
405
+ "Allows rapid iteration on complex vents, grip cutouts, and industrial housings without manual quad-rebuilding of every flat face.",
406
+ "Produces crisp specular edge highlights that read clearly even at mid-poly real-time budgets."
407
+ ],
408
+ "known_limits": [
409
+ "Weighted Normals cannot hide shading pinches on curved surfaces if a boolean cut interrupts curved edge flow without support loops or sufficient cylinder segments.",
410
+ "Custom split normals must be preserved on export (glTF 2.0 exports custom normals automatically when Export Normals is enabled, but subsequent runtime geometry recalculation in Three.js `computeVertexNormals()` will overwrite them!)."
411
+ ],
412
+ "claims": [
413
+ {
414
+ "id": "claim.blender-41-auto-smooth-replacement",
415
+ "statement": "Blender 4.1 removed the mesh-level Auto Smooth checkbox (`use_auto_smooth`) and replaced it with the modifier-based Smooth by Angle operator and node group.",
416
+ "scope": "Blender 4.1, 4.2 LTS, and 5.1+.",
417
+ "uncertainty_or_version_note": "Blender 3.6 LTS still uses the legacy Mesh Data -> Normals -> Auto Smooth checkbox.",
418
+ "source_refs": [
419
+ {
420
+ "source_id": "source.blender-release-notes",
421
+ "locator": "Blender 4.1 Release Notes — Modeling & Normals (Auto Smooth Replacement)"
422
+ }
423
+ ]
424
+ },
425
+ {
426
+ "id": "claim.weighted-normal-face-area-dominance",
427
+ "statement": "Weighting vertex normals by face area aligns shared vertex normals with large planar polygons, transferring all normal curvature onto the narrow bevel chamfers.",
428
+ "scope": "Hard-surface meshes with beveled edges.",
429
+ "uncertainty_or_version_note": "Requires at least one bevel segment between orthogonal faces.",
430
+ "source_refs": [
431
+ {
432
+ "source_id": "source.blender-manual-modeling",
433
+ "locator": "Weighted Normal Modifier"
434
+ }
435
+ ]
436
+ }
437
+ ],
438
+ "source_refs": [
439
+ {
440
+ "source_id": "source.blender-manual-modeling",
441
+ "locator": "Boolean, Bevel, Smooth by Angle & Weighted Normal Modifiers"
442
+ },
443
+ {
444
+ "source_id": "source.blender-release-notes",
445
+ "locator": "Blender 4.1 / 4.2 LTS Normals Workflow"
446
+ }
447
+ ],
448
+ "related_ids": {
449
+ "knowledge_ids": [
450
+ "knowledge.non-destructive-hard-surface-modifier-stack",
451
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
452
+ "knowledge.quad-dominant-subdivision-topology"
453
+ ],
454
+ "skill_ids": [
455
+ "blender-troubleshooting",
456
+ "polycount-budget-checker",
457
+ "scene-readiness"
458
+ ],
459
+ "recipe_ids": [
460
+ "recipe.hard-surface-prop",
461
+ "recipe.scene-quality-inspection-and-correction"
462
+ ]
463
+ },
464
+ "blender_versions": {
465
+ "minimum": "3.6 LTS",
466
+ "tested_or_targeted": [
467
+ "3.6 LTS",
468
+ "4.2 LTS",
469
+ "4.5.15 LTS",
470
+ "5.1+",
471
+ "5.2.3 LTS"
472
+ ],
473
+ "doc_checked_version": "5.2.3 LTS",
474
+ "runtime_tested_version": null,
475
+ "maintained_lts_versions": [
476
+ "4.2 LTS",
477
+ "4.5.15 LTS",
478
+ "5.2.3 LTS"
479
+ ],
480
+ "legacy_compatibility_target": "3.6 LTS",
481
+ "version_notes": "Critical version boundary at Blender 4.1+: use Smooth by Angle modifier instead of legacy mesh Auto Smooth. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
482
+ },
483
+ "evidence_status": "version-checked",
484
+ "promoted_from_skill_refs": [
485
+ "docs/blender-version-compatibility.md",
486
+ "skills/blender-troubleshooting/references/common-symptom-playbooks.md"
487
+ ]
488
+ },
489
+ {
490
+ "id": "knowledge.non-destructive-hard-surface-modifier-stack",
491
+ "title": "Non-Destructive Hard-Surface Modifier Stack Ordering & Evaluation Rules",
492
+ "domain": "hard-surface-and-organic",
493
+ "kind": "modeling-workflow",
494
+ "summary": "Canonical ordering rules for stacking Mirror, Solidify, Boolean, Weld, Bevel, Subdivision/Triangulate, and Weighted Normal modifiers so hard-surface models remain editable without destructive geometry application.",
495
+ "aliases": [
496
+ "blender-modifier-stack-order",
497
+ "hard-surface-non-destructive-workflow",
498
+ "mirror-boolean-bevel-weighted-normal-order"
499
+ ],
500
+ "intent_signals": [
501
+ "what order should I stack Mirror, Boolean, Bevel, and Weighted Normal modifiers",
502
+ "build a non-destructive hard-surface workflow in Blender",
503
+ "prevent seam creases down the center of a Mirror modifier",
504
+ "stack multiple Bevel modifiers by vertex group or angle"
505
+ ],
506
+ "applicability": {
507
+ "when_to_apply": [
508
+ "Designing manufactured products, consumer electronics, vehicles, weapons, or architectural hardware that require iterative design changes.",
509
+ "Auditing modifier stacks before UV unwrapping or baking."
510
+ ],
511
+ "when_not_to_apply": [
512
+ "Final low-poly export stage when modifiers must be applied or evaluated by the glTF exporter (`Export Apply Modifiers`)."
513
+ ],
514
+ "target_representations": [
515
+ "hard-surface-mesh",
516
+ "subdivision-mesh",
517
+ "polygon-game-mesh"
518
+ ]
519
+ },
520
+ "prerequisites": [
521
+ "Object origin placed on the symmetry plane and object scale applied to (1.0, 1.0, 1.0)."
522
+ ],
523
+ "principles": [
524
+ "Blender evaluates modifiers strictly top-to-bottom; placing Subdivision or Weighted Normal above a Boolean or Bevel modifier invalidates custom normals and exponentially slows boolean solver intersections.",
525
+ "Mirror with Merge and Bisect/Clipping enabled must precede Bevel so edges crossing the symmetry centerline merge seamlessly rather than being beveled as an open seam.",
526
+ "Hierarchical beveling (a larger primary bevel on structural edges via Vertex Group/Bevel Weight followed by a finer 30-degree angle-limited secondary bevel) creates realistic multi-tier manufactured chamfers.",
527
+ "Weighted Normal (or Smooth by Angle) must always sit at the bottom of the non-deforming modeling stack because any subsequent topology change destroys custom split normals."
528
+ ],
529
+ "implementation_guidance": {
530
+ "workflow_steps": [
531
+ "Order the stack top-to-bottom: (1) Mirror (Merge=0.001m, Clipping=True) -> (2) Solidify (Even Thickness=True, if sheet metal/shell) -> (3) Boolean (Exact solver) -> (4) Weld (0.0001m) -> (5) Primary/Secondary Bevel (Clamp Overlap=True, Miter Outer=Arc) -> (6) Weighted Normal (Keep Sharp=True).",
532
+ "Set Bevel Miter Outer to 'Arc' instead of 'Sharp' to prevent three-way corner triangles and improve UV/shading continuity.",
533
+ "Keep boolean cutter objects in a dedicated 'Cutters' collection with Viewport Display = Wire/Bounds and Render visibility disabled."
534
+ ],
535
+ "recommended_parameters": {
536
+ "stack_order": "Mirror -> Solidify -> Boolean -> Weld -> Bevel -> WeightedNormal",
537
+ "mirror_merge_threshold_m": 0.001,
538
+ "solidify_even_thickness": true,
539
+ "bevel_miter_outer": "Arc"
540
+ },
541
+ "blender_context": "Properties -> Modifiers tab; Object Properties -> Viewport Display -> Display As: Wire (for Boolean cutters)."
542
+ },
543
+ "observable_checks": [
544
+ {
545
+ "id": "check.weighted-normal-at-bottom",
546
+ "check": "Inspect the modifier stack order from top to bottom.",
547
+ "pass_condition": "Weighted Normal (and Triangulate with Keep Normals, if baking) is at the bottom of the modeling stack after all topology-changing modifiers.",
548
+ "fail_indicator": "Boolean or Bevel placed below Weighted Normal discards custom split normals and triggers a Blender modifier warning."
549
+ },
550
+ {
551
+ "id": "check.mirror-centerline-continuity",
552
+ "check": "Inspect the symmetry plane where the Mirror modifier meets.",
553
+ "pass_condition": "Zero visible seam or unwanted bevel groove along the mirror centerline.",
554
+ "fail_indicator": "Bevel placed above Mirror chamfers the open symmetry boundary."
555
+ },
556
+ {
557
+ "id": "check.cutter-collection-hidden-from-render",
558
+ "check": "Verify visibility flags on the Boolean cutters collection in the Outliner.",
559
+ "pass_condition": "Cutters collection has Disable in Viewports / Disable in Renders (camera icon) unchecked for final output and excluded from glTF export.",
560
+ "fail_indicator": "Wireframe cutter boxes render as solid geometry in Cycles or export as extra meshes in GLB."
561
+ }
562
+ ],
563
+ "creative_affordances": [
564
+ "Non-destructive boolean cutters can be slid, scaled, or duplicated in real time while bevels and weighted normals update live in the viewport.",
565
+ "Arc outer miters on bevels generate clean quad corner patches that accept procedural edge-wear curvature masks."
566
+ ],
567
+ "known_limits": [
568
+ "Stacking 10+ Exact-solver Boolean modifiers on dense meshes degrades viewport playback speed; convert stable upstream cutters to applied base mesh checkpoints on a duplicate collection when needed.",
569
+ "UV unwrapping requires real geometry; live procedural boolean faces only get auto-generated UVs from cutter materials until modifiers are applied for final UV packing."
570
+ ],
571
+ "claims": [
572
+ {
573
+ "id": "claim.top-to-bottom-modifier-evaluation",
574
+ "statement": "Blender evaluates the object modifier stack sequentially from top to bottom; any modifier that adds or splits vertices invalidates custom normals computed by an earlier modifier.",
575
+ "scope": "Blender Modifier Stack architecture.",
576
+ "uncertainty_or_version_note": "Consistent across Blender 3.0+, 3.6 LTS, 4.2 LTS, and 5.1+.",
577
+ "source_refs": [
578
+ {
579
+ "source_id": "source.blender-manual-modeling",
580
+ "locator": "Modifier Stack Evaluation Order"
581
+ }
582
+ ]
583
+ },
584
+ {
585
+ "id": "claim.bevel-arc-miter-corner-topology",
586
+ "statement": "Setting Bevel Miter Outer to Arc replaces pinch-prone 3-way corner poles with spread quad/arc fillets.",
587
+ "scope": "Blender Bevel modifier.",
588
+ "uncertainty_or_version_note": "Supported in Blender 3.0+ through 5.1+.",
589
+ "source_refs": [
590
+ {
591
+ "source_id": "source.blender-manual-modeling",
592
+ "locator": "Bevel Modifier — Miter Patterns (Arc vs Sharp)"
593
+ }
594
+ ]
595
+ }
596
+ ],
597
+ "source_refs": [
598
+ {
599
+ "source_id": "source.blender-manual-modeling",
600
+ "locator": "Modifiers — Introduction, Mirror, Solidify, Boolean, Bevel"
601
+ }
602
+ ],
603
+ "related_ids": {
604
+ "knowledge_ids": [
605
+ "knowledge.boolean-bevel-shading-cleanup",
606
+ "knowledge.cad-creases-and-panel-gap-detailing",
607
+ "knowledge.mesh-manifold-normals-and-scale-hygiene"
608
+ ],
609
+ "skill_ids": [
610
+ "product-hero-scene-planner",
611
+ "polycount-budget-checker",
612
+ "blender-troubleshooting"
613
+ ],
614
+ "recipe_ids": [
615
+ "recipe.hard-surface-prop",
616
+ "recipe.product-hero-scene"
617
+ ]
618
+ },
619
+ "blender_versions": {
620
+ "minimum": "3.6 LTS",
621
+ "tested_or_targeted": [
622
+ "3.6 LTS",
623
+ "4.2 LTS",
624
+ "4.5.15 LTS",
625
+ "5.1+",
626
+ "5.2.3 LTS"
627
+ ],
628
+ "doc_checked_version": "5.2.3 LTS",
629
+ "runtime_tested_version": null,
630
+ "maintained_lts_versions": [
631
+ "4.2 LTS",
632
+ "4.5.15 LTS",
633
+ "5.2.3 LTS"
634
+ ],
635
+ "legacy_compatibility_target": "3.6 LTS",
636
+ "version_notes": "Modifier stack drag-and-drop and Exact boolean solver are available across 3.6 LTS, 4.2 LTS, and 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
637
+ },
638
+ "evidence_status": "version-checked",
639
+ "promoted_from_skill_refs": [
640
+ "skills/polycount-budget-checker/references/topology-hints.md",
641
+ "skills/product-hero-scene-planner/references/product-hero-playbooks.md"
642
+ ]
643
+ },
644
+ {
645
+ "id": "knowledge.organic-sculpt-to-retopology-workflow",
646
+ "title": "Organic High-Poly Sculpting to Clean Quad Retopology & Detail Transfer",
647
+ "domain": "hard-surface-and-organic",
648
+ "kind": "modeling-workflow",
649
+ "summary": "Workflow for transitioning from dynamic-topology or voxel-remeshed high-poly organic sculpts to animation-ready low/mid-poly quad retopology with Shrinkwrap projection and Multiresolution / normal-map detail transfer.",
650
+ "aliases": [
651
+ "sculpt-to-retopo-pipeline",
652
+ "voxel-remesh-multires-shrinkwrap",
653
+ "character-and-organic-retopology"
654
+ ],
655
+ "intent_signals": [
656
+ "retopologize a high-poly sculpt for animation or web GLB export",
657
+ "transfer sculpted details to a low-poly mesh with Shrinkwrap and Multires",
658
+ "when to use Voxel Remesh vs Dyntopo vs Multiresolution in Blender sculpting",
659
+ "reduce a 2-million-polygon sculpt into a clean quad mesh"
660
+ ],
661
+ "applicability": {
662
+ "when_to_apply": [
663
+ "Creating organic characters, creatures, footwear uppers, cushions, rocks, or botanical assets sculpted at high polygon counts.",
664
+ "Converting a dense scan or voxel-remeshed sculpt into an UV-unwrappable, riggable, or web-exportable mesh."
665
+ ],
666
+ "when_not_to_apply": [
667
+ "Geometric architectural walls or rectilinear mechanical parts that can be box-modeled directly at low polycount."
668
+ ],
669
+ "target_representations": [
670
+ "sculpt-highpoly",
671
+ "subdivision-mesh",
672
+ "polygon-game-mesh",
673
+ "skeletal-armature"
674
+ ]
675
+ },
676
+ "prerequisites": [
677
+ "High-poly reference sculpt silhouette is locked so retopology does not have to be redone after major form changes."
678
+ ],
679
+ "principles": [
680
+ "Voxel Remesh (Ctrl+R in Sculpt Mode) generates uniform isotropic grids ideal for primary/secondary form blocking, but destroys UV maps, vertex groups, and animation edge flow.",
681
+ "Automatic quad remeshing (Quadriflow) is suitable for static rocks or props, whereas deforming faces and limbs require guided quad loops around concentric muscle/joint rings.",
682
+ "Projecting a clean quad base mesh onto the frozen high-poly sculpt via a Multiresolution modifier + Shrinkwrap modifier captures micro-surface detail while preserving clean low-level subdivision topology and UVs.",
683
+ "For real-time web/game delivery, high-frequency Multiresolution/sculpt detail is baked into a tangent-space normal map and ambient occlusion map on the Level 0/1 quad mesh."
684
+ ],
685
+ "implementation_guidance": {
686
+ "workflow_steps": [
687
+ "Block primary and secondary forms using Voxel Remesh; freeze the high-poly sculpt as `<asset>_high` before starting retopology.",
688
+ "Construct the low-poly quad cage `<asset>_low` using surface snapping (Snap to Face Project) and Shrinkwrap modifier targeting `<asset>_high`, placing concentric loops around eyes, mouth, and joints.",
689
+ "Unwrap `<asset>_low` UVs cleanly, then bake Normal, AO, and Curvature maps from `<asset>_high` to `<asset>_low` (or subdivide with Multiresolution + Shrinkwrap Apply Base for offline Cycles rendering)."
690
+ ],
691
+ "recommended_parameters": {
692
+ "retopo_snap_mode": "Face Project",
693
+ "shrinkwrap_wrap_method": "Project (Negative + Positive)",
694
+ "character_portrait_lowpoly_tris": "10000 to 35000",
695
+ "web_organic_prop_lowpoly_tris": "2000 to 15000"
696
+ },
697
+ "blender_context": "Sculpt Mode -> Remesh; Edit Mode -> Snapping (Face Project) + Retopology Overlay (Blender 4.0+); Modifiers -> Multiresolution & Shrinkwrap."
698
+ },
699
+ "observable_checks": [
700
+ {
701
+ "id": "check.silhouette-fidelity",
702
+ "check": "Toggle visibility between `<asset>_high` and `<asset>_low` from the primary camera angle.",
703
+ "pass_condition": "Outer silhouette contour of `<asset>_low` matches `<asset>_high` without obvious facet stepping.",
704
+ "fail_indicator": "Normal maps cannot fake missing silhouette geometry along grazing edges."
705
+ },
706
+ {
707
+ "id": "check.joint-deformation-loops",
708
+ "check": "Inspect edge loops at elbows, knees, fingers, eyelids, and lips on deforming meshes.",
709
+ "pass_condition": "At least 3 parallel quad loops span every bending joint and concentric loops surround facial orifices.",
710
+ "fail_indicator": "Spiral remesher loops cross joints diagonally and collapse volume during bending."
711
+ },
712
+ {
713
+ "id": "check.highpoly-excluded-from-export",
714
+ "check": "Verify that the multi-million-triangle `<asset>_high` sculpt is disabled for export.",
715
+ "pass_condition": "Only `<asset>_low` with baked textures is included in the exported GLB.",
716
+ "fail_indicator": "Exporting `<asset>_high` produces a 100+ MB GLB that crashes web viewers."
717
+ }
718
+ ],
719
+ "creative_affordances": [
720
+ "Decouples expressive sculptural freedom during concepting from strict technical topology and UV constraints.",
721
+ "Allows a single retopologized base mesh to serve both a 4K Multiresolution Cycles portrait and a 15k-triangle mobile GLB."
722
+ ],
723
+ "known_limits": [
724
+ "Voxel Remesh cannot be used after UVs or shape keys are authored without losing them.",
725
+ "Extreme overhang cavities (deep ears, nostrils, between fingers) can cause Shrinkwrap projection spikes unless masked or projected with a distance limit."
726
+ ],
727
+ "claims": [
728
+ {
729
+ "id": "claim.voxel-remesh-destroys-uvs",
730
+ "statement": "Blender's Voxel Remesher rebuilds the mesh surface from a volumetric signed-distance grid, discarding existing UV maps, vertex groups, and shape keys.",
731
+ "scope": "Blender Sculpt Mode Voxel Remesher.",
732
+ "uncertainty_or_version_note": "Documented in Blender Manual Sculpting -> Remesh.",
733
+ "source_refs": [
734
+ {
735
+ "source_id": "source.blender-manual-modeling",
736
+ "locator": "Sculpting -> Remesh (Voxel and QuadriFlow)"
737
+ }
738
+ ]
739
+ },
740
+ {
741
+ "id": "claim.retopology-overlay-40",
742
+ "statement": "Blender 4.0+ provides a built-in Retopology viewport overlay that renders the active edit-mode mesh with a customizable depth offset in front of the reference sculpt.",
743
+ "scope": "Blender 4.0+, 4.2 LTS, and 5.1+.",
744
+ "uncertainty_or_version_note": "In Blender 3.6 LTS, use Object Properties -> Viewport Display -> In Front.",
745
+ "source_refs": [
746
+ {
747
+ "source_id": "source.blender-release-notes",
748
+ "locator": "Blender 4.0 Release Notes — Retopology Overlay"
749
+ }
750
+ ]
751
+ }
752
+ ],
753
+ "source_refs": [
754
+ {
755
+ "source_id": "source.blender-manual-modeling",
756
+ "locator": "Sculpting, Retopology & Multiresolution Modifier"
757
+ },
758
+ {
759
+ "source_id": "source.blender-studio-pipeline",
760
+ "locator": "Character Sculpting & Retopology Workflow"
761
+ }
762
+ ],
763
+ "related_ids": {
764
+ "knowledge_ids": [
765
+ "knowledge.quad-dominant-subdivision-topology",
766
+ "knowledge.high-to-low-normal-and-ao-baking",
767
+ "knowledge.armature-joint-hierarchy-and-linear-blend-skinning"
768
+ ],
769
+ "skill_ids": [
770
+ "character-portrait",
771
+ "polycount-budget-checker",
772
+ "mobile-glb-budget"
773
+ ],
774
+ "recipe_ids": [
775
+ "recipe.rigged-and-animated-asset",
776
+ "recipe.uv-and-pbr-material-preparation"
777
+ ]
778
+ },
779
+ "blender_versions": {
780
+ "minimum": "3.6 LTS",
781
+ "tested_or_targeted": [
782
+ "3.6 LTS",
783
+ "4.2 LTS",
784
+ "4.5.15 LTS",
785
+ "5.1+",
786
+ "5.2.3 LTS"
787
+ ],
788
+ "doc_checked_version": "5.2.3 LTS",
789
+ "runtime_tested_version": null,
790
+ "maintained_lts_versions": [
791
+ "4.2 LTS",
792
+ "4.5.15 LTS",
793
+ "5.2.3 LTS"
794
+ ],
795
+ "legacy_compatibility_target": "3.6 LTS",
796
+ "version_notes": "Blender 4.0+ adds the dedicated Retopology viewport shading overlay. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
797
+ },
798
+ "evidence_status": "version-checked",
799
+ "promoted_from_skill_refs": [
800
+ "skills/character-portrait/references/style-consistency-rules.md",
801
+ "skills/polycount-budget-checker/references/topology-hints.md"
802
+ ]
803
+ },
804
+ {
805
+ "id": "knowledge.cad-creases-and-panel-gap-detailing",
806
+ "title": "Physical Bevel Minimums, Panel Seam Gaps & Industrial Readability",
807
+ "domain": "hard-surface-and-organic",
808
+ "kind": "modeling-workflow",
809
+ "summary": "Industrial design rules for sizing edge bevels and panel seams in physical millimeters so specular catchlights and shadow gaps remain legible at camera distance without sub-pixel aliasing.",
810
+ "aliases": [
811
+ "physical-bevel-widths-and-panel-lines",
812
+ "industrial-design-catchlights",
813
+ "hard-surface-panel-gap-sizing"
814
+ ],
815
+ "intent_signals": [
816
+ "how wide should bevels and panel gaps be on a product model",
817
+ "edges look razor sharp and CGI fake in product render",
818
+ "panel lines shimmer or disappear at camera distance",
819
+ "add realistic manufactured tolerances and seams to a product hero"
820
+ ],
821
+ "applicability": {
822
+ "when_to_apply": [
823
+ "Modeling or auditing consumer electronics, footwear, watches, automotive parts, furniture, or sci-fi props for hero rendering or web viewers."
824
+ ],
825
+ "when_not_to_apply": [
826
+ "Distant background buildings where sub-centimeter bevels are smaller than 0.5 screen pixels."
827
+ ],
828
+ "target_representations": [
829
+ "hard-surface-mesh",
830
+ "subdivision-mesh",
831
+ "polygon-game-mesh"
832
+ ]
833
+ },
834
+ "prerequisites": [
835
+ "Scene unit scale set to Metric 1.0 (1 BU = 1 meter) and object scale applied."
836
+ ],
837
+ "principles": [
838
+ "Zero-radius mathematical 90-degree edges do not exist on manufactured objects and cannot catch specular area-light reflections along their silhouette.",
839
+ "To prevent sub-pixel specular aliasing (shimmering) at standard HD/4K camera distances, primary housing bevels should measure 0.5 mm to 3.0 mm and micro-chamfers at least 0.15 mm to 0.4 mm.",
840
+ "Physical panel gaps (parting lines between housing shells) require an inward extruded recess depth of >= 1.5x the gap width (e.g., 0.5 mm wide x 0.8 mm deep) so ambient occlusion and grazing light form a crisp dark shadow line.",
841
+ "Hierarchy of detail (70% primary clean read / 20% secondary parting lines & fasteners / 10% tertiary micro-knurling or decals) prevents visual noise."
842
+ ],
843
+ "implementation_guidance": {
844
+ "workflow_steps": [
845
+ "Establish a 3-tier bevel hierarchy: Tier 1 outer silhouette fillets (2.0-5.0 mm), Tier 2 housing breaks (0.5-1.5 mm), and Tier 3 machined chamfers (0.2-0.4 mm).",
846
+ "Construct parting lines by splitting or insetting panel borders by 0.3-0.8 mm, extruding inward by 0.6-1.5 mm, and beveling the outer lip so light catches one rim of the gap.",
847
+ "For real-time GLB targets under strict triangle budgets, bake Tier 3 micro-fasteners and shallow vents into the normal/AO map while keeping Tier 1-2 silhouette bevels in geometry."
848
+ ],
849
+ "recommended_parameters": {
850
+ "tier1_silhouette_bevel_mm": 2.5,
851
+ "tier2_housing_bevel_mm": 0.8,
852
+ "tier3_micro_chamfer_mm": 0.25,
853
+ "panel_gap_width_mm": 0.5,
854
+ "panel_gap_depth_mm": 0.8
855
+ },
856
+ "blender_context": "Scene Properties -> Units -> Length: Millimeters (or Meters); Bevel Modifier -> Offset (Width) in mm."
857
+ },
858
+ "observable_checks": [
859
+ {
860
+ "id": "check.zero-mathematical-razor-edges",
861
+ "check": "Inspect hero product edges under studio key and rim lighting.",
862
+ "pass_condition": "Every visible structural corner exhibits a continuous specular highlight ribbon.",
863
+ "fail_indicator": "Unbeveled 90-degree edges appear dead and invisible where two dark faces meet."
864
+ },
865
+ {
866
+ "id": "check.panel-gap-shadow-termination",
867
+ "check": "Inspect parting lines between manufactured shells at final render resolution.",
868
+ "pass_condition": "Parting lines have an occluded dark interior trough and a bright catchlight on the opposing lip.",
869
+ "fail_indicator": "Shallow V-grooves reflect bright light from their bottom face instead of reading as a physical gap."
870
+ },
871
+ {
872
+ "id": "check.70-20-10-detail-distribution",
873
+ "check": "Evaluate visual rest areas vs. detail clusters across the prop.",
874
+ "pass_condition": "Approximately 70% rest surfaces, 20% secondary seams, 10% dense focal hardware.",
875
+ "fail_indicator": "Uniform greeble density across 100% of the surface destroys focal hierarchy."
876
+ }
877
+ ],
878
+ "creative_affordances": [
879
+ "Slightly exaggerating micro-bevels by 1.2x-1.5x over CAD engineering drawings makes small products read as tactile and premium on 1080p/2K web screens.",
880
+ "Contrasting matte blasted recesses inside panel grooves against satin or gloss outer shells amplifies form definition."
881
+ ],
882
+ "known_limits": [
883
+ "Geometry panel gaps add 4-6 quad loops per seam; on mobile web targets (<50k tris), secondary panel seams should be baked into tangent-space normal and AO maps."
884
+ ],
885
+ "claims": [
886
+ {
887
+ "id": "claim.specular-edge-catchlight-requirement",
888
+ "statement": "Specular BRDF reflections only occur where surface normals orient the half-vector toward a light source; unbeveled 90-degree polygon edges have zero surface area at intermediate normal angles and therefore produce zero edge catchlights.",
889
+ "scope": "Physically based rendering (Cycles, EEVEE, Three.js).",
890
+ "uncertainty_or_version_note": "Cycles offers a shader-only Bevel node for offline renders, but it does not export to glTF 2.0.",
891
+ "source_refs": [
892
+ {
893
+ "source_id": "source.blender-manual-modeling",
894
+ "locator": "Bevel Modifier — Shading and Catchlights"
895
+ },
896
+ {
897
+ "source_id": "source.google-filament-pbr",
898
+ "locator": "Geometric Specular Antialiasing & Microfacet Normals"
899
+ }
900
+ ]
901
+ },
902
+ {
903
+ "id": "claim.cycles-bevel-node-non-exportable",
904
+ "statement": "Blender's Shader Editor Bevel node is a Cycles-only raytracing shader effect that is ignored by EEVEE and the glTF 2.0 exporter unless baked into a normal map.",
905
+ "scope": "Blender Cycles vs. EEVEE and glTF 2.0 export.",
906
+ "uncertainty_or_version_note": "Verified in Blender Manual Shader Nodes -> Input -> Bevel.",
907
+ "source_refs": [
908
+ {
909
+ "source_id": "source.blender-manual-shading-color",
910
+ "locator": "Shader Nodes -> Input -> Bevel Node (Cycles Only)"
911
+ }
912
+ ]
913
+ }
914
+ ],
915
+ "source_refs": [
916
+ {
917
+ "source_id": "source.blender-manual-modeling",
918
+ "locator": "Bevel Modifier and Precision Modeling"
919
+ },
920
+ {
921
+ "source_id": "source.google-filament-pbr",
922
+ "locator": "Physically Based Rendering — Specular Aliasing & Surface Detail"
923
+ }
924
+ ],
925
+ "related_ids": {
926
+ "knowledge_ids": [
927
+ "knowledge.non-destructive-hard-surface-modifier-stack",
928
+ "knowledge.boolean-bevel-shading-cleanup",
929
+ "knowledge.three-point-and-hdri-studio-lighting"
930
+ ],
931
+ "skill_ids": [
932
+ "product-hero-scene-planner",
933
+ "lighting-material-plan",
934
+ "polycount-budget-checker"
935
+ ],
936
+ "recipe_ids": [
937
+ "recipe.product-hero-scene",
938
+ "recipe.hard-surface-prop"
939
+ ]
940
+ },
941
+ "blender_versions": {
942
+ "minimum": "3.0+",
943
+ "tested_or_targeted": [
944
+ "3.6 LTS",
945
+ "4.2 LTS",
946
+ "4.5.15 LTS",
947
+ "5.1+",
948
+ "5.2.3 LTS"
949
+ ],
950
+ "doc_checked_version": "5.2.3 LTS",
951
+ "runtime_tested_version": null,
952
+ "maintained_lts_versions": [
953
+ "4.2 LTS",
954
+ "4.5.15 LTS",
955
+ "5.2.3 LTS"
956
+ ],
957
+ "legacy_compatibility_target": "3.6 LTS",
958
+ "version_notes": "Bevel Width (Offset) in physical scene units works identically across 3.6 LTS, 4.2 LTS, and 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
959
+ },
960
+ "evidence_status": "version-checked",
961
+ "promoted_from_skill_refs": [
962
+ "skills/product-hero-scene-planner/references/product-hero-playbooks.md",
963
+ "skills/product-hero-scene-planner/references/cyberpunk-shoe-example.md"
964
+ ]
965
+ },
966
+ {
967
+ "id": "knowledge.geometry-nodes-fields-and-anonymous-attributes",
968
+ "title": "Geometry Nodes Fields Evaluation, Attribute Domains & UV/Shader Persistence",
969
+ "domain": "geometry-nodes-and-procedural",
970
+ "kind": "procedural-system",
971
+ "summary": "Core architecture of Blender Geometry Nodes Fields, attribute domain interpolation (Point, Edge, Face, Face Corner, Instance), and explicit `Store Named Attribute` contracts required to pass UVs and custom data to shaders and glTF exports.",
972
+ "aliases": [
973
+ "geometry-nodes-store-named-attribute",
974
+ "gn-fields-and-face-corner-uvmap",
975
+ "geometry-nodes-to-shader-attribute"
976
+ ],
977
+ "intent_signals": [
978
+ "how do I pass Geometry Nodes attributes or UVs to a material shader",
979
+ "textures disappear on procedural Curve to Mesh or Realize Instances",
980
+ "store UVMap on Face Corner domain in Geometry Nodes",
981
+ "understand Geometry Nodes field evaluation and Capture Attribute"
982
+ ],
983
+ "applicability": {
984
+ "when_to_apply": [
985
+ "Building any Geometry Nodes procedural mesh generator, curve sweep (`Curve to Mesh`), or attribute-driven material variation.",
986
+ "Preparing a Geometry Nodes asset for textured rendering or glTF/GLB export."
987
+ ],
988
+ "when_not_to_apply": [
989
+ "Static hand-modeled meshes that do not use Geometry Nodes modifiers."
990
+ ],
991
+ "target_representations": [
992
+ "geometry-nodes-graph",
993
+ "pbr-material-graph",
994
+ "glb-container"
995
+ ]
996
+ },
997
+ "prerequisites": [
998
+ "Blender 3.0+ Fields architecture (3.6 LTS or 4.2 LTS recommended for full `Store Named Attribute` workflow)."
999
+ ],
1000
+ "principles": [
1001
+ "A Field in Geometry Nodes is a deferred function Recipe (dashed link) that is only evaluated when plugged into a Geometry-consuming operation node (solid link) in the context of that node's target attribute domain.",
1002
+ "UV coordinates MUST be stored on the `Face Corner` domain as a `2D Vector` named `UVMap` (using `Store Named Attribute`); storing UVs on the `Point` (vertex) domain prevents UV splits at seams and causes wrap-around texture smearing.",
1003
+ "`Capture Attribute` freezes a field's value on a specific geometry domain before topology-changing operations (such as `Curve to Mesh`, `Extrude Mesh`, or `Subdivide Mesh`) alter indices or normals.",
1004
+ "Shaders access Geometry Nodes attributes via the Shader Editor `Attribute` node (`Type: Geometry` for Point/Face/Face Corner attributes on meshes, or `Type: Instancer` for attributes stored on the `Instance` domain)."
1005
+ ],
1006
+ "implementation_guidance": {
1007
+ "workflow_steps": [
1008
+ "For `Curve to Mesh` generators, capture `Spline Parameter -> Factor` on the curve (`Capture Attribute`, Float, Point domain) for U and profile curve `Spline Parameter -> Factor` for V, combine into a Vector (`Combine XYZ`), and write to `Store Named Attribute` (`2D Vector`, `Face Corner`, Name = `UVMap`).",
1009
+ "Expose all user-tunable parameters on the `Group Input` interface with explicit Min, Max, and Default values and descriptive socket names.",
1010
+ "In the Shader Editor, add `Input -> Attribute` (`Name: UVMap`, `Type: Geometry`) and wire its `Vector` output into `Image Texture` nodes to guarantee consistent rendering in both Cycles and EEVEE."
1011
+ ],
1012
+ "recommended_parameters": {
1013
+ "uv_attribute_domain": "Face Corner",
1014
+ "uv_attribute_data_type": "2D Vector",
1015
+ "uv_attribute_name": "UVMap",
1016
+ "instance_variation_domain": "Instance"
1017
+ },
1018
+ "blender_context": "Geometry Node Editor -> Attribute -> Store Named Attribute & Capture Attribute; Spreadsheet Editor (to inspect domain values)."
1019
+ },
1020
+ "observable_checks": [
1021
+ {
1022
+ "id": "check.spreadsheet-face-corner-uvmap",
1023
+ "check": "Open the Blender Spreadsheet Editor, select `Mesh -> Face Corner` domain, and inspect attributes.",
1024
+ "pass_condition": "`UVMap` column exists as a 2D Vector on `Face Corner` with non-zero coordinates.",
1025
+ "fail_indicator": "`UVMap` is missing or stored on `Point` domain, causing seam smearing."
1026
+ },
1027
+ {
1028
+ "id": "check.group-input-min-max-clamps",
1029
+ "check": "Inspect the Geometry Nodes modifier Group Input socket properties in the N-panel.",
1030
+ "pass_condition": "Count, density, and resolution inputs have explicit finite Max clamps.",
1031
+ "fail_indicator": "Unbounded density slider allows accidental 10,000,000-point freeze."
1032
+ },
1033
+ {
1034
+ "id": "check.shader-attribute-type-match",
1035
+ "check": "Verify the Shader Editor `Attribute` node `Type` dropdown against the Geometry Nodes storage domain.",
1036
+ "pass_condition": "`Type: Instancer` is used for `Instance` domain attributes (when instances are unrealized); `Type: Geometry` is used for mesh domains.",
1037
+ "fail_indicator": "`Type: Geometry` returns 0.0 on unrealized instances when reading an `Instance`-domain attribute."
1038
+ }
1039
+ ],
1040
+ "creative_affordances": [
1041
+ "Enables single-slider parametric variations (length, cable sag, panel count, wear seed) without destructive remodeling.",
1042
+ "Per-instance random hue/roughness attributes stored on the `Instance` domain allow thousands of shared-mesh instances to look visually unique in Cycles/EEVEE."
1043
+ ],
1044
+ "known_limits": [
1045
+ "Geometry Nodes graphs are NOT executable inside glTF 2.0 / Three.js at runtime; exporting to GLB evaluates the modifier at the current frame into static meshes or node instances.",
1046
+ "Per-instance shader attributes (`Type: Instancer`) do not export automatically into a single standard glTF material; for GLB export, either use distinct material variants or bake/vertex-color realized geometry."
1047
+ ],
1048
+ "claims": [
1049
+ {
1050
+ "id": "claim.face-corner-uv-seam-splitting",
1051
+ "statement": "Because a single mesh vertex on a UV seam belongs to multiple UV islands with different (U,V) coordinates, UV maps in Blender and glTF 2.0 must be stored per Face Corner (loop) rather than per Vertex (Point).",
1052
+ "scope": "Blender Geometry Nodes and glTF 2.0 `TEXCOORD_0` export.",
1053
+ "uncertainty_or_version_note": "In Blender 3.5+, storing a 2D Vector on Face Corner creates a native UV map layer.",
1054
+ "source_refs": [
1055
+ {
1056
+ "source_id": "source.blender-manual-geometry-nodes",
1057
+ "locator": "Attributes — Domains (Face Corner) and Store Named Attribute"
1058
+ }
1059
+ ]
1060
+ },
1061
+ {
1062
+ "id": "claim.deferred-field-evaluation",
1063
+ "statement": "Geometry Nodes field nodes do not compute data until connected to a geometry socket, and evaluate relative to the topology state at that specific operation node.",
1064
+ "scope": "Blender 3.0+ Fields system.",
1065
+ "uncertainty_or_version_note": "Fundamental architecture introduced in Blender 3.0 and used in 3.6 LTS, 4.2 LTS, and 5.1+.",
1066
+ "source_refs": [
1067
+ {
1068
+ "source_id": "source.blender-manual-geometry-nodes",
1069
+ "locator": "Fields — Evaluation Context and Anonymous Attributes"
1070
+ }
1071
+ ]
1072
+ }
1073
+ ],
1074
+ "source_refs": [
1075
+ {
1076
+ "source_id": "source.blender-manual-geometry-nodes",
1077
+ "locator": "Fields, Attribute Domains, Capture Attribute & Store Named Attribute"
1078
+ }
1079
+ ],
1080
+ "related_ids": {
1081
+ "knowledge_ids": [
1082
+ "knowledge.procedural-instancing-and-realize-instances-budget",
1083
+ "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
1084
+ "knowledge.shader-node-gltf-export-portability"
1085
+ ],
1086
+ "skill_ids": [
1087
+ "polycount-budget-checker",
1088
+ "lighting-material-plan",
1089
+ "material-quality-checker",
1090
+ "glb-web-handoff"
1091
+ ],
1092
+ "recipe_ids": [
1093
+ "recipe.procedural-geometry-nodes-asset",
1094
+ "recipe.stylized-environment-scene"
1095
+ ]
1096
+ },
1097
+ "blender_versions": {
1098
+ "minimum": "3.6 LTS",
1099
+ "tested_or_targeted": [
1100
+ "3.6 LTS",
1101
+ "4.2 LTS",
1102
+ "4.5.15 LTS",
1103
+ "5.1+",
1104
+ "5.2.3 LTS"
1105
+ ],
1106
+ "doc_checked_version": "5.2.3 LTS",
1107
+ "runtime_tested_version": null,
1108
+ "maintained_lts_versions": [
1109
+ "4.2 LTS",
1110
+ "4.5.15 LTS",
1111
+ "5.2.3 LTS"
1112
+ ],
1113
+ "legacy_compatibility_target": "3.6 LTS",
1114
+ "version_notes": "Blender 3.5+ unifies UV maps with Face Corner 2D Vector named attributes; Blender 4.0+ adds Repeat Zones and Menu Switch (4.1+). Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
1115
+ },
1116
+ "evidence_status": "version-checked",
1117
+ "promoted_from_skill_refs": [
1118
+ "docs/blender-version-compatibility.md",
1119
+ "skills/polycount-budget-checker/references/instance-counting-rules.md"
1120
+ ]
1121
+ },
1122
+ {
1123
+ "id": "knowledge.procedural-instancing-and-realize-instances-budget",
1124
+ "title": "Procedural Collection Instancing vs. Realize Instances Memory & Export Tradeoffs",
1125
+ "domain": "geometry-nodes-and-procedural",
1126
+ "kind": "procedural-system",
1127
+ "summary": "Memory, draw-call, and export rules governing `Instance on Points` vs. `Realize Instances`, preventing accidental multi-gigabyte mesh explosions while ensuring correct glTF/Three.js instance or merged-mesh output.",
1128
+ "aliases": [
1129
+ "instance-on-points-vs-realize-instances",
1130
+ "geometry-nodes-instancing-memory-budget",
1131
+ "realize-instances-gltf-export-rules"
1132
+ ],
1133
+ "intent_signals": [
1134
+ "when should I use Realize Instances in Geometry Nodes",
1135
+ "Blender runs out of memory or freezes when scattering trees or rocks",
1136
+ "export Geometry Nodes instances to GLB or Three.js InstancedMesh",
1137
+ "difference between unique mesh triangles and instanced triangles"
1138
+ ],
1139
+ "applicability": {
1140
+ "when_to_apply": [
1141
+ "Scattering repeated props, foliage, architectural modules, or fasteners via Geometry Nodes (`Instance on Points`) or Collection Instances.",
1142
+ "Auditing scene memory and polycount budgets in `polycount-budget-checker` and `mobile-glb-budget`."
1143
+ ],
1144
+ "when_not_to_apply": [
1145
+ "Single unique hero mesh with zero repeated components."
1146
+ ],
1147
+ "target_representations": [
1148
+ "geometry-nodes-graph",
1149
+ "scene-hierarchy",
1150
+ "glb-container"
1151
+ ]
1152
+ },
1153
+ "prerequisites": [
1154
+ "Base instance meshes have applied scale (1,1,1) and clean origin placement."
1155
+ ],
1156
+ "principles": [
1157
+ "An unrealized instance stores only a 4x4 transformation matrix (64 bytes) referencing shared mesh data; realizing 10,000 instances of a 20,000-triangle tree copies 200,000,000 unique triangles into RAM/VRAM.",
1158
+ "Use `Realize Instances` ONLY when vertices of individual instances must be deformed differently downstream (e.g., bending instances along a curve or running a boolean across them) or when intentionally merging ultra-low-poly micro-parts into a single static draw call.",
1159
+ "On `Collection Info`, enabling `Separate Children` + `Reset Children` + `Pick Instance` on `Instance on Points` randomly selects individual collection assets at the target point positions without double-applying collection world offsets.",
1160
+ "When exporting to GLB, unrealized instances export as multiple glTF nodes referencing a single shared `mesh` index (keeping `.glb` file size tiny, though web engines should batch high node counts into `THREE.InstancedMesh`)."
1161
+ ],
1162
+ "implementation_guidance": {
1163
+ "workflow_steps": [
1164
+ "Place source scatter assets in a dedicated collection with origins at the base contact point and enable `Separate Children` and `Reset Children` on `Collection Info`.",
1165
+ "Enable `Pick Instance` on `Instance on Points` so each point instances one child rather than the entire collection at once.",
1166
+ "Audit both `Unique Triangles` (VRAM/file size driver) and `Total Evaluated Scene Triangles` (rasterization vertex load) in `polycount-budget-checker`."
1167
+ ],
1168
+ "recommended_parameters": {
1169
+ "collection_info_separate_children": true,
1170
+ "collection_info_reset_children": true,
1171
+ "instance_on_points_pick_instance": true,
1172
+ "max_realized_triangles_web": 100000
1173
+ },
1174
+ "blender_context": "Geometry Node Editor -> Instances -> Instance on Points, Realize Instances; Input -> Scene -> Collection Info."
1175
+ },
1176
+ "observable_checks": [
1177
+ {
1178
+ "id": "check.spreadsheet-instance-count-vs-vertex-count",
1179
+ "check": "Compare `Instances` domain row count vs. `Mesh -> Vertex` count in the Spreadsheet Editor.",
1180
+ "pass_condition": "Heavy scatter systems show entries in the `Instances` domain and near-zero extra vertices in the host `Mesh` domain.",
1181
+ "fail_indicator": "`Instances` domain is empty and `Mesh` vertices exceed millions due to an unnecessary `Realize Instances` node."
1182
+ },
1183
+ {
1184
+ "id": "check.pick-instance-enabled",
1185
+ "check": "Verify `Pick Instance` on `Instance on Points` when driven by a multi-object `Collection Info` node.",
1186
+ "pass_condition": "`Pick Instance` is checked and `Separate Children` + `Reset Children` are enabled.",
1187
+ "fail_indicator": "Every scatter point spawns all collection objects stacked on top of each other."
1188
+ },
1189
+ {
1190
+ "id": "check.dual-triangle-metric-reporting",
1191
+ "check": "Verify that budget reports separate unique base mesh triangles from total instanced triangles.",
1192
+ "pass_condition": "Both unique geometry memory and total rasterized triangles are reported.",
1193
+ "fail_indicator": "Counting only unique triangles hides a 50-million-triangle rasterization bottleneck on mobile GPUs."
1194
+ }
1195
+ ],
1196
+ "creative_affordances": [
1197
+ "Allows lush forests, brick walls, and stadium seating in Cycles/EEVEE using minimal RAM.",
1198
+ "Nested instancing (instancing modular wall assemblies that themselves instance rivets/windows) scales to massive environments."
1199
+ ],
1200
+ "known_limits": [
1201
+ "In Three.js, exporting 5,000 unrealized glTF nodes referencing 1 shared mesh keeps the `.glb` file small (~1 MB), but creates 5,000 scene-graph draw calls unless converted to `THREE.InstancedMesh` or `<Instances>` in React Three Fiber.",
1202
+ "Realizing instances merges objects into one mesh and strips per-object transform hierarchy."
1203
+ ],
1204
+ "claims": [
1205
+ {
1206
+ "id": "claim.realize-instances-memory-multiplication",
1207
+ "statement": "`Realize Instances` converts lightweight transform references into independent vertex, edge, face, and attribute arrays for every instance.",
1208
+ "scope": "Blender Geometry Nodes across 3.0+, 3.6 LTS, 4.2 LTS, and 5.1+.",
1209
+ "uncertainty_or_version_note": "Documented in Blender Manual Geometry Nodes -> Instances -> Realize Instances.",
1210
+ "source_refs": [
1211
+ {
1212
+ "source_id": "source.blender-manual-geometry-nodes",
1213
+ "locator": "Instances -> Realize Instances"
1214
+ }
1215
+ ]
1216
+ },
1217
+ {
1218
+ "id": "claim.gltf-shared-mesh-instancing",
1219
+ "statement": "Multiple glTF nodes referencing the same `mesh` index share vertex/index buffers in the binary `.glb` payload, reducing file size but still issuing per-node draw calls unless GPU-instanced (`EXT_mesh_gpu_instancing` or `THREE.InstancedMesh`).",
1220
+ "scope": "glTF 2.0 export and Three.js / R3F rendering.",
1221
+ "uncertainty_or_version_note": "Standard WebGL/Three.js behavior.",
1222
+ "source_refs": [
1223
+ {
1224
+ "source_id": "source.khronos-gltf-2-spec",
1225
+ "locator": "Nodes and Shared Meshes"
1226
+ },
1227
+ {
1228
+ "source_id": "source.threejs-color-and-gltf",
1229
+ "locator": "InstancedMesh and Draw Call Optimization"
1230
+ }
1231
+ ]
1232
+ }
1233
+ ],
1234
+ "source_refs": [
1235
+ {
1236
+ "source_id": "source.blender-manual-geometry-nodes",
1237
+ "locator": "Instance on Points, Collection Info & Realize Instances"
1238
+ },
1239
+ {
1240
+ "source_id": "source.blender-manual-gltf-io",
1241
+ "locator": "Instancing & Geometry Nodes Export"
1242
+ }
1243
+ ],
1244
+ "related_ids": {
1245
+ "knowledge_ids": [
1246
+ "knowledge.geometry-nodes-fields-and-anonymous-attributes",
1247
+ "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
1248
+ "knowledge.triangle-draw-call-and-vram-budgets"
1249
+ ],
1250
+ "skill_ids": [
1251
+ "polycount-budget-checker",
1252
+ "mobile-glb-budget",
1253
+ "r3f-component-plan",
1254
+ "glb-web-handoff"
1255
+ ],
1256
+ "recipe_ids": [
1257
+ "recipe.procedural-geometry-nodes-asset",
1258
+ "recipe.stylized-environment-scene",
1259
+ "recipe.web-ready-asset-optimization"
1260
+ ]
1261
+ },
1262
+ "blender_versions": {
1263
+ "minimum": "3.6 LTS",
1264
+ "tested_or_targeted": [
1265
+ "3.6 LTS",
1266
+ "4.2 LTS",
1267
+ "4.5.15 LTS",
1268
+ "5.1+",
1269
+ "5.2.3 LTS"
1270
+ ],
1271
+ "doc_checked_version": "5.2.3 LTS",
1272
+ "runtime_tested_version": null,
1273
+ "maintained_lts_versions": [
1274
+ "4.2 LTS",
1275
+ "4.5.15 LTS",
1276
+ "5.2.3 LTS"
1277
+ ],
1278
+ "legacy_compatibility_target": "3.6 LTS",
1279
+ "version_notes": "`Realize Instances` in Blender 3.1+ automatically preserves named Face Corner UV maps instead of discarding them as in Blender 3.0. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
1280
+ },
1281
+ "evidence_status": "version-checked",
1282
+ "promoted_from_skill_refs": [
1283
+ "skills/polycount-budget-checker/references/instance-counting-rules.md",
1284
+ "skills/mobile-glb-budget/references/budget-tiers.md"
1285
+ ]
1286
+ },
1287
+ {
1288
+ "id": "knowledge.procedural-scatter-poisson-disk-and-slope-masking",
1289
+ "title": "Poisson Disk Point Distribution, Slope/Altitude Masking & Orientation Alignment",
1290
+ "domain": "geometry-nodes-and-procedural",
1291
+ "kind": "procedural-system",
1292
+ "summary": "Mathematical and procedural patterns for natural, non-overlapping surface scattering using Poisson Disk minimum-distance distribution, surface-normal dot-product slope filtering, and stable Euler-to-vector orientation alignment.",
1293
+ "aliases": [
1294
+ "poisson-disk-distribute-points-on-faces",
1295
+ "slope-and-altitude-scatter-mask",
1296
+ "align-euler-to-vector-surface-normal"
1297
+ ],
1298
+ "intent_signals": [
1299
+ "stop scattered rocks, trees, or droplets from intersecting each other",
1300
+ "scatter grass only on flat ground and not on steep cliffs",
1301
+ "align scattered instances to surface normal without twisting",
1302
+ "use Distribute Points on Faces Poisson Disk in Geometry Nodes"
1303
+ ],
1304
+ "applicability": {
1305
+ "when_to_apply": [
1306
+ "Scattering vegetation, rocks, debris, condensation water droplets, or architectural props across terrain or product surfaces."
1307
+ ],
1308
+ "when_not_to_apply": [
1309
+ "Regular deterministic grid arrays (use Mesh Grid or Curve Resample instead of Poisson Disk)."
1310
+ ],
1311
+ "target_representations": [
1312
+ "geometry-nodes-graph",
1313
+ "scene-hierarchy"
1314
+ ]
1315
+ },
1316
+ "prerequisites": [
1317
+ "Emitter surface has applied unit scale (1,1,1) and outward face normals."
1318
+ ],
1319
+ "principles": [
1320
+ "`Distribute Points on Faces` in `Random` mode places points independently and causes severe mesh overlaps; `Poisson Disk` mode enforces a hard minimum Euclidean `Distance Min` radius (blue-noise distribution) that prevents bounding-sphere collisions.",
1321
+ "Taking the `Dot Product` of the surface `Normal` vector with world up `(0, 0, 1)` yields `cos(theta)` (`1.0` on flat horizontal ground, `0.0` on vertical walls, `-1.0` on overhangs), providing a resolution-independent slope mask.",
1322
+ "Vertical objects (trees, lampposts, architectural columns) should blend 70-100% toward world `+Z` `(0,0,1)` and only 0-30% toward the terrain normal, whereas ground-hugging moss, pebbles, and droplets align 100% of their local `+Z` to the surface `Normal`.",
1323
+ "Hierarchical scattering (scattering large boulders with a large `Distance Min` first, then masking small pebbles/grass around them via `Geometry Proximity`) mimics natural ecological clustering."
1324
+ ],
1325
+ "implementation_guidance": {
1326
+ "workflow_steps": [
1327
+ "Set `Distribute Points on Faces` to `Poisson Disk`, set `Distance Min` to approximately 0.8x the base diameter of the scattered asset, and set `Density Max` to a bounded ceiling.",
1328
+ "Compute `Vector Math (Dot Product)` between `Normal` and `(0, 0, 1)`, pass through a `Map Range` or `Compare (Greater Than)` node (e.g., `> 0.70` for slopes under ~45 degrees), and multiply with a 3D `Noise Texture` into `Density Factor`.",
1329
+ "Orient instances using `Align Euler to Vector` (or `Align Rotation to Vector` in Blender 4.2+): align `Z` axis to `Normal` (or `Mix Vector` between `(0,0,1)` and `Normal`), then chain `Rotate Euler` (Local, `Z` axis, `Random Value 0..2*pi`) for yaw variation."
1330
+ ],
1331
+ "recommended_parameters": {
1332
+ "distribution_method": "Poisson Disk",
1333
+ "flat_ground_dot_product_min": 0.707,
1334
+ "tree_verticality_mix_to_world_z": 0.85,
1335
+ "yaw_rotation_range_rad": "0.0 to 6.283185"
1336
+ },
1337
+ "blender_context": "Geometry Node Editor -> Point -> Distribute Points on Faces (Poisson Disk); Utilities -> Rotation -> Align Rotation to Vector (4.2+) / Align Euler to Vector (3.6 LTS)."
1338
+ },
1339
+ "observable_checks": [
1340
+ {
1341
+ "id": "check.zero-interpenetrating-trunks-or-rocks",
1342
+ "check": "Inspect scattered instances in close-up viewport views.",
1343
+ "pass_condition": "Adjacent instances respect `Distance Min` spacing without clipping through each other's cores.",
1344
+ "fail_indicator": "`Random` distribution mode was left active instead of `Poisson Disk`."
1345
+ },
1346
+ {
1347
+ "id": "check.slope-threshold-respected",
1348
+ "check": "Inspect vertical cliff faces or steep side walls of the emitter mesh.",
1349
+ "pass_condition": "Ground vegetation and horizontal props do not spawn sideways out of vertical cliffs.",
1350
+ "fail_indicator": "Density Factor is unmasked by `dot(Normal, (0,0,1))`."
1351
+ },
1352
+ {
1353
+ "id": "check.local-z-yaw-randomization",
1354
+ "check": "Verify how random yaw rotation is applied after surface-normal alignment.",
1355
+ "pass_condition": "`Rotate Rotation` / `Rotate Euler` is set to `Local` space around the `Z` axis.",
1356
+ "fail_indicator": "Rotating in `Object` (world) space after normal alignment tilts instances off the surface normal."
1357
+ }
1358
+ ],
1359
+ "creative_affordances": [
1360
+ "Combining slope dot-product, world-Z altitude, and ambient occlusion/curvature into `Density Factor` creates believable snowlines, moss crevices, and shoreline transitions automatically.",
1361
+ "Micro-droplet Poisson scattering on beverage bottles or sneakers adds instant studio macro realism."
1362
+ ],
1363
+ "known_limits": [
1364
+ "`Distribute Points on Faces` evaluates per mesh surface; if the emitter mesh is animated/deforming, surface area changes can cause points to pop unless evaluated on a static rest-position reference (`rest_position` attribute)."
1365
+ ],
1366
+ "claims": [
1367
+ {
1368
+ "id": "claim.poisson-disk-blue-noise-spacing",
1369
+ "statement": "Poisson Disk point distribution generates a blue-noise sample set where no two points lie closer than the specified `Distance Min` radius.",
1370
+ "scope": "Blender Geometry Nodes `Distribute Points on Faces`.",
1371
+ "uncertainty_or_version_note": "Available in Blender 3.0+, 3.6 LTS, 4.2 LTS, and 5.1+.",
1372
+ "source_refs": [
1373
+ {
1374
+ "source_id": "source.blender-manual-geometry-nodes",
1375
+ "locator": "Point -> Distribute Points on Faces (Poisson Disk)"
1376
+ }
1377
+ ]
1378
+ },
1379
+ {
1380
+ "id": "claim.align-rotation-to-vector-42",
1381
+ "statement": "Blender 4.2 LTS introduces the `Align Rotation to Vector` and `Rotate Rotation` nodes using the native `Rotation` socket type, superseding the legacy `Align Euler to Vector` node.",
1382
+ "scope": "Blender 4.2 LTS and 5.1+ vs. Blender 3.6 LTS.",
1383
+ "uncertainty_or_version_note": "Legacy `Align Euler to Vector` files continue to open with a deprecation notice in 4.2 LTS.",
1384
+ "source_refs": [
1385
+ {
1386
+ "source_id": "source.blender-release-notes",
1387
+ "locator": "Blender 4.1 / 4.2 LTS Geometry Nodes — Rotation Socket Nodes"
1388
+ }
1389
+ ]
1390
+ }
1391
+ ],
1392
+ "source_refs": [
1393
+ {
1394
+ "source_id": "source.blender-manual-geometry-nodes",
1395
+ "locator": "Distribute Points on Faces & Rotation Utilities"
1396
+ },
1397
+ {
1398
+ "source_id": "source.blender-release-notes",
1399
+ "locator": "Geometry Nodes Rotation Data Type"
1400
+ }
1401
+ ],
1402
+ "related_ids": {
1403
+ "knowledge_ids": [
1404
+ "knowledge.procedural-instancing-and-realize-instances-budget",
1405
+ "knowledge.geometry-nodes-fields-and-anonymous-attributes",
1406
+ "knowledge.environment-depth-layering-and-atmospheric-perspective"
1407
+ ],
1408
+ "skill_ids": [
1409
+ "environment-shot",
1410
+ "polycount-budget-checker",
1411
+ "product-hero-scene-planner"
1412
+ ],
1413
+ "recipe_ids": [
1414
+ "recipe.procedural-geometry-nodes-asset",
1415
+ "recipe.stylized-environment-scene"
1416
+ ]
1417
+ },
1418
+ "blender_versions": {
1419
+ "minimum": "3.6 LTS",
1420
+ "tested_or_targeted": [
1421
+ "3.6 LTS",
1422
+ "4.2 LTS",
1423
+ "4.5.15 LTS",
1424
+ "5.1+",
1425
+ "5.2.3 LTS"
1426
+ ],
1427
+ "doc_checked_version": "5.2.3 LTS",
1428
+ "runtime_tested_version": null,
1429
+ "maintained_lts_versions": [
1430
+ "4.2 LTS",
1431
+ "4.5.15 LTS",
1432
+ "5.2.3 LTS"
1433
+ ],
1434
+ "legacy_compatibility_target": "3.6 LTS",
1435
+ "version_notes": "Use `Align Euler to Vector` in Blender 3.6 LTS and `Align Rotation to Vector` in Blender 4.2 LTS / 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
1436
+ },
1437
+ "evidence_status": "version-checked",
1438
+ "promoted_from_skill_refs": [
1439
+ "skills/environment-shot/references/depth-layering-rules.md",
1440
+ "skills/polycount-budget-checker/references/instance-counting-rules.md"
1441
+ ]
1442
+ },
1443
+ {
1444
+ "id": "knowledge.uv-seam-placement-and-texel-density",
1445
+ "title": "UV Seam Placement, Hard-Edge Splits, Texel Density & Mipmap Padding",
1446
+ "domain": "uv-texturing-and-baking",
1447
+ "kind": "uv-baking-rule",
1448
+ "summary": "Rules for placing UV seams along occluded contours and sharp shading breaks (>=60 degrees), equalizing texel density (pixels per meter), aligning islands to pixel axes, and sizing UV padding margins to prevent mipmap bleeding.",
1449
+ "aliases": [
1450
+ "uv-seam-and-padding-rules",
1451
+ "texel-density-normalization",
1452
+ "hard-edge-uv-split-mikktspace"
1453
+ ],
1454
+ "intent_signals": [
1455
+ "where should I place UV seams on my 3D model",
1456
+ "how much UV margin padding do I need for 2K or 4K textures",
1457
+ "fix blurry textures or uneven texel density across meshes",
1458
+ "prevent mipmap color bleeding along UV island borders"
1459
+ ],
1460
+ "applicability": {
1461
+ "when_to_apply": [
1462
+ "Unwrapping any 3D mesh for image texturing, normal/AO baking, or glTF 2.0 export.",
1463
+ "Auditing UV stretching and texture sharpness in `material-quality-checker`."
1464
+ ],
1465
+ "when_not_to_apply": [
1466
+ "Untextured meshes that rely strictly on uniform material scalar values or camera-projected triplanar shaders inside offline Cycles renders."
1467
+ ],
1468
+ "target_representations": [
1469
+ "uv-layout",
1470
+ "polygon-game-mesh",
1471
+ "hard-surface-mesh",
1472
+ "glb-container"
1473
+ ]
1474
+ },
1475
+ "prerequisites": [
1476
+ "Object scale is applied to (1.0, 1.0, 1.0) before running Unwrap or Average Islands Scale."
1477
+ ],
1478
+ "principles": [
1479
+ "Every sharp shading edge (hard edge / seam where vertex normals split, typically >= 60 degrees) MUST also be a UV seam with separated UV islands when baking tangent-space normal maps; otherwise the MikkTSpace tangent discontinuity creates a permanent black/bright ridge.",
1480
+ "On smooth organic surfaces, hide UV seams along natural anatomical or clothing boundaries (under arms, inner legs, hairline, underside of footwear soles) away from the primary camera view.",
1481
+ "Mipmap downsampling halves texture resolution at each level; without adequate pixel margin between UV islands (`>= 8 px` at 1024x1024, `>= 16 px` at 2048x2048, `>= 32 px` at 4096x4096), background or adjacent island colors bleed across seams at medium camera distances.",
1482
+ "Aligning straight structural edges of UV islands horizontally or vertically (U or V axis) eliminates diagonal staircase aliasing on panel lines and stripes."
1483
+ ],
1484
+ "implementation_guidance": {
1485
+ "workflow_steps": [
1486
+ "Select all sharp edges (`Select -> Select Sharp Edges`, Angle ~60 deg) plus occluded relief cuts to flatten cylinders/cones, and run `UV -> Mark Seam`.",
1487
+ "Run `UV -> Unwrap` (`Angle Based` for organic forms; `Conformal` or `Minimum Stretch` in Blender 4.3+/5.1+ for hard-surface mechanical parts).",
1488
+ "Enable `UV Stretch` overlay (`Angle` and `Area`) in the UV Editor, run `UV -> Average Islands Scale`, and `UV -> Pack Islands` with Margin set to `0.008` (16 px at 2048x2048) and `Rotate Method = Axis-aligned`."
1489
+ ],
1490
+ "recommended_parameters": {
1491
+ "hard_edge_seam_angle_deg": 60,
1492
+ "margin_px_1024": 8,
1493
+ "margin_px_2048": 16,
1494
+ "margin_px_4096": 32,
1495
+ "hero_product_texel_density_px_per_m": 2048
1496
+ },
1497
+ "blender_context": "UV Editor -> Overlays -> Stretching (Angle/Area); UV -> Unwrap, Average Islands Scale, Pack Islands."
1498
+ },
1499
+ "observable_checks": [
1500
+ {
1501
+ "id": "check.uv-stretch-overlay-blue",
1502
+ "check": "Enable UV Editor -> Overlays -> Display Stretch (Angle) and inspect all islands.",
1503
+ "pass_condition": "All visible hero UV islands display deep blue (low angular distortion).",
1504
+ "fail_indicator": "Green, yellow, or red patches indicate missing relief seams on cylinders/cones or unapplied object scale."
1505
+ },
1506
+ {
1507
+ "id": "check.hard-edges-have-uv-seams",
1508
+ "check": "Compare sharp shading edges (`Mark Sharp` / angle >= 60 deg) against marked UV seams on normal-mapped meshes.",
1509
+ "pass_condition": "100% of sharp shading edges lie on UV island boundaries with padding margin.",
1510
+ "fail_indicator": "A sharp edge passes through the interior of a connected UV island, causing normal bake artifacts."
1511
+ },
1512
+ {
1513
+ "id": "check.sufficient-mipmap-island-margin",
1514
+ "check": "Measure pixel spacing between adjacent UV islands and the 0-1 UV border.",
1515
+ "pass_condition": "Spacing is at least 8 px at 1K, 16 px at 2K, or 32 px at 4K.",
1516
+ "fail_indicator": "Islands touch within 1-2 pixels, causing seam bleeding when camera zooms out."
1517
+ }
1518
+ ],
1519
+ "creative_affordances": [
1520
+ "Giving focal hero surfaces (watch dial, sneaker logo tongue, character face) 1.5x-2.0x higher texel density than hidden undersides maximizes perceived 4K crispness inside a 2K texture budget.",
1521
+ "Rectifying cylindrical straps and trims into straight rectangular UV strips allows clean weave/stitching tiling."
1522
+ ],
1523
+ "known_limits": [
1524
+ "Over-splitting every 30-degree bevel into tiny disconnected 2-pixel UV islands wastes UV space on padding margins and degrades KTX2 compression; keep smooth bevel fillets attached to one adjacent planar island."
1525
+ ],
1526
+ "claims": [
1527
+ {
1528
+ "id": "claim.mikktspace-hard-edge-seam-rule",
1529
+ "statement": "When a vertex normal is split across a hard edge without a corresponding UV split, the interpolated tangent basis jumps discontinuously across the edge while the single shared texel cannot store two opposing tangent-space normals.",
1530
+ "scope": "MikkTSpace tangent-space normal mapping in Blender, glTF 2.0, Three.js, Unreal, and Unity.",
1531
+ "uncertainty_or_version_note": "Fundamental property of MikkTSpace tangent space.",
1532
+ "source_refs": [
1533
+ {
1534
+ "source_id": "source.mikktspace-tangent-standard",
1535
+ "locator": "Hard Edges and UV Seam Splitting Requirements"
1536
+ }
1537
+ ]
1538
+ },
1539
+ {
1540
+ "id": "claim.mipmap-margin-scaling",
1541
+ "statement": "Each mipmap level reduces texture dimensions by a factor of 2; an N-pixel UV island margin remains bleed-free down to log2(N) mipmap levels.",
1542
+ "scope": "GPU trilinear/anisotropic mipmap filtering.",
1543
+ "uncertainty_or_version_note": "16 pixels at 2048x2048 protects down to the 128x128 mip level.",
1544
+ "source_refs": [
1545
+ {
1546
+ "source_id": "source.blender-manual-uv-baking",
1547
+ "locator": "UV Pack Islands — Margin and Mipmapping"
1548
+ }
1549
+ ]
1550
+ }
1551
+ ],
1552
+ "source_refs": [
1553
+ {
1554
+ "source_id": "source.blender-manual-uv-baking",
1555
+ "locator": "UV Unwrapping, Seams, and Packing"
1556
+ },
1557
+ {
1558
+ "source_id": "source.mikktspace-tangent-standard",
1559
+ "locator": "MikkTSpace Tangent Space Specification"
1560
+ }
1561
+ ],
1562
+ "related_ids": {
1563
+ "knowledge_ids": [
1564
+ "knowledge.udim-vs-single-atlas-uv-packing",
1565
+ "knowledge.high-to-low-normal-and-ao-baking",
1566
+ "knowledge.mesh-manifold-normals-and-scale-hygiene"
1567
+ ],
1568
+ "skill_ids": [
1569
+ "material-quality-checker",
1570
+ "lighting-material-plan",
1571
+ "mobile-glb-budget"
1572
+ ],
1573
+ "recipe_ids": [
1574
+ "recipe.uv-and-pbr-material-preparation",
1575
+ "recipe.hard-surface-prop",
1576
+ "recipe.product-hero-scene"
1577
+ ]
1578
+ },
1579
+ "blender_versions": {
1580
+ "minimum": "3.6 LTS",
1581
+ "tested_or_targeted": [
1582
+ "3.6 LTS",
1583
+ "4.2 LTS",
1584
+ "4.5.15 LTS",
1585
+ "5.1+",
1586
+ "5.2.3 LTS"
1587
+ ],
1588
+ "doc_checked_version": "5.2.3 LTS",
1589
+ "runtime_tested_version": null,
1590
+ "maintained_lts_versions": [
1591
+ "4.2 LTS",
1592
+ "4.5.15 LTS",
1593
+ "5.2.3 LTS"
1594
+ ],
1595
+ "legacy_compatibility_target": "3.6 LTS",
1596
+ "version_notes": "Blender 3.6 LTS improved UV Pack Islands performance and non-square packing; Blender 4.3+/5.1+ adds SLIM (Minimum Stretch) unwrapping. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
1597
+ },
1598
+ "evidence_status": "version-checked",
1599
+ "promoted_from_skill_refs": [
1600
+ "skills/material-quality-checker/references/texture-budget-rules.md",
1601
+ "skills/lighting-material-plan/references/material-portability.md"
1602
+ ]
1603
+ },
1604
+ {
1605
+ "id": "knowledge.udim-vs-single-atlas-uv-packing",
1606
+ "title": "Single 0-1 UV Atlas Packing vs. Multi-Tile UDIM Workflows for Offline & glTF",
1607
+ "domain": "uv-texturing-and-baking",
1608
+ "kind": "uv-baking-rule",
1609
+ "summary": "Architectural selection rules between single `0..1` UV atlases (mandatory for standard single-material glTF/GLB web delivery), trim sheets / tiling `KHR_texture_transform` UVs, and multi-tile `1001..100N` UDIM layouts (for offline Cycles VFX).",
1610
+ "aliases": [
1611
+ "0-1-uv-atlas-vs-udim",
1612
+ "gltf-uv-atlas-and-trim-sheets",
1613
+ "udim-export-limitations-gltf"
1614
+ ],
1615
+ "intent_signals": [
1616
+ "should I use UDIMs or a single 0-1 UV atlas",
1617
+ "do UDIM textures export to GLB and Three.js",
1618
+ "combine multiple materials into a single texture atlas to reduce draw calls",
1619
+ "use trim sheets and KHR_texture_transform in glTF"
1620
+ ],
1621
+ "applicability": {
1622
+ "when_to_apply": [
1623
+ "Planning UV and texture architecture before unwrapping or baking.",
1624
+ "Optimizing multi-material assets into a single draw-call atlas for web GLB delivery."
1625
+ ],
1626
+ "when_not_to_apply": [
1627
+ "Untextured geometry."
1628
+ ],
1629
+ "target_representations": [
1630
+ "uv-layout",
1631
+ "pbr-material-graph",
1632
+ "glb-container"
1633
+ ]
1634
+ },
1635
+ "prerequisites": [
1636
+ "Target delivery surface (offline Cycles render vs. real-time glTF/GLB web viewer) is confirmed."
1637
+ ],
1638
+ "principles": [
1639
+ "Core Khronos glTF 2.0 and Three.js `GLTFLoader` do NOT natively resolve multi-tile `1001, 1002...` UDIM texture sequences on a single material; coordinates outside `0..1` simply wrap (`REPEAT`) or clamp (`CLAMP_TO_EDGE`) the single bound texture.",
1640
+ "For real-time web GLB assets, packing all components of a prop into one `0..1` UV atlas (with non-overlapping islands for baked maps) allows a single PBR material and 1 draw call per mesh.",
1641
+ "When an asset uses both a tiling detail texture (e.g., carbon fiber weave via `Mapping` scale -> `KHR_texture_transform`) and a baked non-overlapping Ambient Occlusion / lightmap, glTF 2.0 supports two UV sets: `TEXCOORD_0` (first UV map) and `TEXCOORD_1` (second UV map).",
1642
+ "UDIM tiles (`1001`, `1002`, etc.) should be reserved for offline Cycles/VFX hero assets where a single unified shader needs multiple 4K/8K texture tiles without splitting material assignments."
1643
+ ],
1644
+ "implementation_guidance": {
1645
+ "workflow_steps": [
1646
+ "If targeting glTF/GLB web delivery, pack all unique baked islands strictly inside the `[0.0, 1.0]` UV square on `UVMap` (`TEXCOORD_0`).",
1647
+ "If combining tiling weave/grain with baked AO, keep `UVMap` (`TEXCOORD_0`) for primary PBR maps and create a second non-overlapping `UVMap_AO` (`TEXCOORD_1`) wired via `UV Map` node into the glTF Occlusion socket.",
1648
+ "If converting an offline UDIM asset to GLB, either bake and repack the UDIM tiles into a single `0..1` atlas or split the UDIM tiles into separate material slots with `0..1`-normalized UV offsets."
1649
+ ],
1650
+ "recommended_parameters": {
1651
+ "web_glb_uv_mode": "single_0_1_atlas",
1652
+ "max_gltf_uv_sets": 2,
1653
+ "offline_vfx_uv_mode": "udim_1001_sequence"
1654
+ },
1655
+ "blender_context": "UV Editor -> Image -> UDIM Tiles; Object Data Properties -> UV Maps (`UVMap`, `UVMap_AO`)."
1656
+ },
1657
+ "observable_checks": [
1658
+ {
1659
+ "id": "check.zero-unintended-out-of-bounds-uvs-for-bake",
1660
+ "check": "Verify that all islands on a baked `0..1` atlas reside within `U: [0,1], V: [0,1]`.",
1661
+ "pass_condition": "100% of uniquely baked islands fit inside the `0..1` square (unless intentionally offset by exactly +1.0 U during baking of symmetric stacked halves).",
1662
+ "fail_indicator": "Islands spill across UDIM tile `1002` on a glTF material, causing wrong texture wrapping in Three.js."
1663
+ },
1664
+ {
1665
+ "id": "check.draw-call-consolidation-via-atlas",
1666
+ "check": "Count material slots assigned to a static prop mesh.",
1667
+ "pass_condition": "1-2 material slots (e.g., 1 opaque PBR atlas + 1 optional transparent glass material) per prop.",
1668
+ "fail_indicator": "15 separate 2K material slots on one prop generate 15 draw calls and blow the mobile VRAM budget."
1669
+ },
1670
+ {
1671
+ "id": "check.secondary-uv-set-limit",
1672
+ "check": "Inspect the number of UV maps on meshes destined for WebGL/Three.js.",
1673
+ "pass_condition": "At most 2 UV maps (`TEXCOORD_0` and `TEXCOORD_1`).",
1674
+ "fail_indicator": "3+ UV maps or unreferenced leftover UV layers bloat vertex buffer bandwidth."
1675
+ }
1676
+ ],
1677
+ "creative_affordances": [
1678
+ "Dual-UV workflows (`TEXCOORD_0` trim/tiling + `TEXCOORD_1` baked macro AO) deliver crisp close-up fabric/wood grain on mobile web using tiny 512px tiling maps plus a 1024px AO map.",
1679
+ "UDIMs in offline Cycles allow cinematic close-ups on large characters or vehicles without managing dozens of duplicate shader node trees."
1680
+ ],
1681
+ "known_limits": [
1682
+ "Baking multiple material slots into a single `0..1` atlas requires non-overlapping target UVs on the consolidated UV map.",
1683
+ "`KHR_texture_transform` applies scale/offset/rotation in 2D UV space; 3D object/box-projected textures cannot be exported to glTF without baking to 2D UVs."
1684
+ ],
1685
+ "claims": [
1686
+ {
1687
+ "id": "claim.gltf-no-native-udim-tiles",
1688
+ "statement": "The Khronos glTF 2.0 specification binds a single 2D image resource per `textureInfo` descriptor and does not define multi-image `1001..100N` UDIM tile lookup.",
1689
+ "scope": "Khronos glTF 2.0 core specification and Three.js `GLTFLoader`.",
1690
+ "uncertainty_or_version_note": "Verified against Khronos glTF 2.0 specification Section 3.8 (Textures and Samplers).",
1691
+ "source_refs": [
1692
+ {
1693
+ "source_id": "source.khronos-gltf-2-spec",
1694
+ "locator": "Samplers, Textures, and TextureInfo UV Coordinates"
1695
+ }
1696
+ ]
1697
+ },
1698
+ {
1699
+ "id": "claim.each-material-slot-creates-gltf-primitive",
1700
+ "statement": "In glTF 2.0, a mesh with N assigned materials is split into N `mesh.primitives`, each requiring a separate draw call in standard WebGL renderers.",
1701
+ "scope": "Blender glTF 2.0 exporter and Three.js.",
1702
+ "uncertainty_or_version_note": "Consolidating materials into a shared UV atlas reduces primitive/draw-call count to 1.",
1703
+ "source_refs": [
1704
+ {
1705
+ "source_id": "source.khronos-gltf-2-spec",
1706
+ "locator": "Meshes and Primitives — Material Binding"
1707
+ },
1708
+ {
1709
+ "source_id": "source.blender-manual-gltf-io",
1710
+ "locator": "Meshes and Material Primitives"
1711
+ }
1712
+ ]
1713
+ }
1714
+ ],
1715
+ "source_refs": [
1716
+ {
1717
+ "source_id": "source.blender-manual-uv-baking",
1718
+ "locator": "UDIM Workflows vs. Single Texture Atlases"
1719
+ },
1720
+ {
1721
+ "source_id": "source.khronos-gltf-2-spec",
1722
+ "locator": "Texture Coordinates (TEXCOORD_0 / TEXCOORD_1) & KHR_texture_transform"
1723
+ }
1724
+ ],
1725
+ "related_ids": {
1726
+ "knowledge_ids": [
1727
+ "knowledge.uv-seam-placement-and-texel-density",
1728
+ "knowledge.high-to-low-normal-and-ao-baking",
1729
+ "knowledge.triangle-draw-call-and-vram-budgets"
1730
+ ],
1731
+ "skill_ids": [
1732
+ "material-quality-checker",
1733
+ "mobile-glb-budget",
1734
+ "lighting-material-plan",
1735
+ "glb-web-handoff"
1736
+ ],
1737
+ "recipe_ids": [
1738
+ "recipe.uv-and-pbr-material-preparation",
1739
+ "recipe.web-ready-asset-optimization"
1740
+ ]
1741
+ },
1742
+ "blender_versions": {
1743
+ "minimum": "3.6 LTS",
1744
+ "tested_or_targeted": [
1745
+ "3.6 LTS",
1746
+ "4.2 LTS",
1747
+ "4.5.15 LTS",
1748
+ "5.1+",
1749
+ "5.2.3 LTS"
1750
+ ],
1751
+ "doc_checked_version": "5.2.3 LTS",
1752
+ "runtime_tested_version": null,
1753
+ "maintained_lts_versions": [
1754
+ "4.2 LTS",
1755
+ "4.5.15 LTS",
1756
+ "5.2.3 LTS"
1757
+ ],
1758
+ "legacy_compatibility_target": "3.6 LTS",
1759
+ "version_notes": "UDIM tile creation and UV Pack Islands into 0-1 or active UDIM tile are supported in 3.6 LTS, 4.2 LTS, and 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
1760
+ },
1761
+ "evidence_status": "version-checked",
1762
+ "promoted_from_skill_refs": [
1763
+ "skills/material-quality-checker/references/texture-budget-rules.md",
1764
+ "skills/mobile-glb-budget/references/degradation-plan.md"
1765
+ ]
1766
+ },
1767
+ {
1768
+ "id": "knowledge.high-to-low-normal-and-ao-baking",
1769
+ "title": "Tangent-Space MikkTSpace Normal & Ambient Occlusion Baking Protocol",
1770
+ "domain": "uv-texturing-and-baking",
1771
+ "kind": "uv-baking-rule",
1772
+ "summary": "Precision baking rules for transferring high-poly or procedural surface detail onto low-poly meshes in Cycles using MikkTSpace (+X +Y +Z OpenGL), fixed pre-bake triangulation, cage extrusion, and 16-bit Non-Color buffers.",
1773
+ "aliases": [
1774
+ "high-to-low-normal-map-baking",
1775
+ "cycles-mikktspace-bake-cage",
1776
+ "opengl-normal-map-green-channel"
1777
+ ],
1778
+ "intent_signals": [
1779
+ "bake high-poly sculpt or bevels to a low-poly normal map in Blender",
1780
+ "fix wavy lines, skewed details, or ray misses in baked normal maps",
1781
+ "should Blender normal maps use +Y OpenGL or -Y DirectX for glTF and Three.js",
1782
+ "prevent 8-bit banding in smooth baked normal maps"
1783
+ ],
1784
+ "applicability": {
1785
+ "when_to_apply": [
1786
+ "Baking high-poly sculpts, subdivision surfaces, bevels, or procedural bump/shader setups into tangent-space normal and ambient occlusion maps.",
1787
+ "Diagnosing inverted normal lighting or seam discontinuities in `material-quality-checker` and `blender-troubleshooting`."
1788
+ ],
1789
+ "when_not_to_apply": [
1790
+ "Flat untextured meshes or unbaked high-poly offline renders."
1791
+ ],
1792
+ "target_representations": [
1793
+ "uv-layout",
1794
+ "pbr-material-graph",
1795
+ "polygon-game-mesh",
1796
+ "glb-container"
1797
+ ]
1798
+ },
1799
+ "prerequisites": [
1800
+ "Low-poly mesh has non-overlapping `0..1` UVs, applied scale (1,1,1), and UV seams along all sharp edges."
1801
+ ],
1802
+ "principles": [
1803
+ "MikkTSpace tangent calculation depends on the exact diagonal triangulation of every quad; if the low-poly mesh is baked as quads and triangulated differently on export, the tangent basis changes and produces X-shaped shading crosses.",
1804
+ "Blender, Khronos glTF 2.0, and Three.js all standardize on **OpenGL right-handed tangent space (`+X, +Y, +Z`)**; DirectX normal maps (`-Y` inverted green channel) cause lights from above to illuminate the bottom of bumps unless the G channel is inverted (`1.0 - G`).",
1805
+ "Target normal map image buffers must be created with `Color Space = Non-Color` and `32-bit Float` (saved as 16-bit PNG before optional KTX2 UASTC encoding) to prevent 8-bit quantization stepping on smooth curved surfaces.",
1806
+ "When baking `Selected to Active`, a custom Cage (or small `Extrusion` distance with constrained `Max Ray Distance`) ensures rays cast smoothly across 90-degree corners without gaps or cross-part self-intersection."
1807
+ ],
1808
+ "implementation_guidance": {
1809
+ "workflow_steps": [
1810
+ "Add a `Triangulate` modifier (`Quad Method: Fixed` or `Shortest Diagonal`, `Keep Normals: True`) to the low-poly mesh BEFORE baking and keep that exact triangulation for glTF export.",
1811
+ "Create the target Image Texture node (`32-bit Float: True`, `Color Space: Non-Color`), leave it selected and disconnected in the low-poly material's Shader Editor.",
1812
+ "In Render Properties (`Render Engine: Cycles`), set `Bake Type: Normal`, `Space: Tangent`, Swizzle `+X, +Y, +Z`, enable `Selected to Active` with `Extrusion` (e.g., `0.005 m` - `0.02 m`) or a pushed Cage mesh, set `Margin: 16 px` (`Adjacent Faces`), and bake."
1813
+ ],
1814
+ "recommended_parameters": {
1815
+ "bake_render_engine": "Cycles",
1816
+ "normal_space": "Tangent",
1817
+ "normal_swizzle": "+X, +Y, +Z (OpenGL)",
1818
+ "image_color_space": "Non-Color",
1819
+ "bake_margin_px": 16,
1820
+ "keep_normals_on_triangulate": true
1821
+ },
1822
+ "blender_context": "Render Properties (Cycles) -> Bake -> Normal (Tangent, +X +Y +Z), Selected to Active, Cage/Extrusion, Margin."
1823
+ },
1824
+ "observable_checks": [
1825
+ {
1826
+ "id": "check.triangulated-before-bake",
1827
+ "check": "Verify that the low-poly mesh triangulation is locked (`Triangulate` modifier with `Keep Normals`) prior to baking.",
1828
+ "pass_condition": "Identical triangle diagonals are used during baking and final export.",
1829
+ "fail_indicator": "Quad diagonals flip on export, producing diagonal shading crosses across curved panels."
1830
+ },
1831
+ {
1832
+ "id": "check.opengl-positive-y-normal-orientation",
1833
+ "check": "Inspect the green channel of the normal map or shine a top directional light on a recessed engraving.",
1834
+ "pass_condition": "Top edge of a convex bump is bright in the green channel (+Y up) and recessed top edges are shadowed under a top light.",
1835
+ "fail_indicator": "Recessed grooves appear embossed (inverted -Y DirectX normal map)."
1836
+ },
1837
+ {
1838
+ "id": "check.zero-ray-miss-patches",
1839
+ "check": "Inspect the baked normal map image for flat `(0.5, 0.5, 1.0)` patches or cross-projected limb imprints.",
1840
+ "pass_condition": "Continuous normal detail across all islands with zero ray misses or self-intersection ghosts.",
1841
+ "fail_indicator": "Extrusion distance was too small (ray misses High-Poly) or `Max Ray Distance` was `0.0` (infinite rays hit opposite sides of the model)."
1842
+ }
1843
+ ],
1844
+ "creative_affordances": [
1845
+ "Allows a 5,000-triangle real-time web prop to display the visual bevels, stitching, and fastener detail of a 2,000,000-triangle CAD/sculpt model.",
1846
+ "Baking a Bent Normal or Ambient Occlusion map enriches cavity contact shadows under soft environment lighting."
1847
+ ],
1848
+ "known_limits": [
1849
+ "Tangent-space normal maps perturb surface shading normals only; they do not change the geometric silhouette at grazing angles.",
1850
+ "Symmetric UV islands stacked directly on top of each other during baking will collide and corrupt the bake unless all duplicate islands except one are offset by `+1.0` in U outside the `0..1` square."
1851
+ ],
1852
+ "claims": [
1853
+ {
1854
+ "id": "claim.gltf-opengl-tangent-space-standard",
1855
+ "statement": "Khronos glTF 2.0 specifies MikkTSpace tangent-space normal maps with a right-handed coordinate basis (+X right, +Y up, +Z out / OpenGL convention) encoded in linear (`Non-Color`) space.",
1856
+ "scope": "Khronos glTF 2.0 specification and Blender glTF I/O.",
1857
+ "uncertainty_or_version_note": "Verified in Khronos glTF 2.0 specification Section 3.9.2 (Normal TextureInfo).",
1858
+ "source_refs": [
1859
+ {
1860
+ "source_id": "source.khronos-gltf-2-spec",
1861
+ "locator": "Materials — Normal Texture Info & MikkTSpace"
1862
+ },
1863
+ {
1864
+ "source_id": "source.mikktspace-tangent-standard",
1865
+ "locator": "Triangulation and Tangent Basis Consistency"
1866
+ }
1867
+ ]
1868
+ },
1869
+ {
1870
+ "id": "claim.cycles-required-for-render-baking",
1871
+ "statement": "Blender's Render Baking pipeline (`bpy.ops.object.bake`) executes exclusively under the Cycles render engine; EEVEE does not provide a surface texture baker.",
1872
+ "scope": "Blender 3.6 LTS, 4.2 LTS, and 5.1+.",
1873
+ "uncertainty_or_version_note": "You can temporarily switch Render Engine to Cycles to bake textures and switch back to EEVEE or export to GLB afterward.",
1874
+ "source_refs": [
1875
+ {
1876
+ "source_id": "source.blender-manual-uv-baking",
1877
+ "locator": "Render Baking (Cycles Only)"
1878
+ }
1879
+ ]
1880
+ }
1881
+ ],
1882
+ "source_refs": [
1883
+ {
1884
+ "source_id": "source.blender-manual-uv-baking",
1885
+ "locator": "Render Baking — Normal, Ambient Occlusion & Selected to Active"
1886
+ },
1887
+ {
1888
+ "source_id": "source.mikktspace-tangent-standard",
1889
+ "locator": "MikkTSpace Baking Workflow"
1890
+ }
1891
+ ],
1892
+ "related_ids": {
1893
+ "knowledge_ids": [
1894
+ "knowledge.uv-seam-placement-and-texel-density",
1895
+ "knowledge.normal-roughness-and-orm-channel-packing",
1896
+ "knowledge.organic-sculpt-to-retopology-workflow"
1897
+ ],
1898
+ "skill_ids": [
1899
+ "material-quality-checker",
1900
+ "lighting-material-plan",
1901
+ "cycles-vs-eevee-decision"
1902
+ ],
1903
+ "recipe_ids": [
1904
+ "recipe.uv-and-pbr-material-preparation",
1905
+ "recipe.hard-surface-prop",
1906
+ "recipe.product-hero-scene"
1907
+ ]
1908
+ },
1909
+ "blender_versions": {
1910
+ "minimum": "3.6 LTS",
1911
+ "tested_or_targeted": [
1912
+ "3.6 LTS",
1913
+ "4.2 LTS",
1914
+ "4.5.15 LTS",
1915
+ "5.1+",
1916
+ "5.2.3 LTS"
1917
+ ],
1918
+ "doc_checked_version": "5.2.3 LTS",
1919
+ "runtime_tested_version": null,
1920
+ "maintained_lts_versions": [
1921
+ "4.2 LTS",
1922
+ "4.5.15 LTS",
1923
+ "5.2.3 LTS"
1924
+ ],
1925
+ "legacy_compatibility_target": "3.6 LTS",
1926
+ "version_notes": "Cycles render baking and Adjacent Faces margin filter are consistent across 3.6 LTS, 4.2 LTS, and 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
1927
+ },
1928
+ "evidence_status": "version-checked",
1929
+ "promoted_from_skill_refs": [
1930
+ "skills/material-quality-checker/references/pbr-sanity-rules.md",
1931
+ "skills/blender-troubleshooting/references/common-symptom-playbooks.md"
1932
+ ]
1933
+ },
1934
+ {
1935
+ "id": "knowledge.principled-bsdf-v2-energy-conserving-pbr",
1936
+ "title": "Principled BSDF v2 Energy Conservation, Dielectric vs. Conductor Albedo & Blender 4.0+ Socket Changes",
1937
+ "domain": "materials-shaders-and-pbr",
1938
+ "kind": "material-shader-profile",
1939
+ "summary": "Physically based shading rules for Blender's Principled BSDF (including the Blender 4.0+ Principled BSDF v2 multi-scatter GGX overhaul), enforcing energy-conserving albedo bounds, binary metalness discipline, and accurate Coat/Sheen/Transmission parameterization.",
1940
+ "aliases": [
1941
+ "principled-bsdf-v2-blender-4",
1942
+ "pbr-albedo-and-metallic-rules",
1943
+ "dielectric-vs-conductor-pbr-values"
1944
+ ],
1945
+ "intent_signals": [
1946
+ "what changed in Principled BSDF in Blender 4.0 and 4.2 LTS",
1947
+ "why do white or black materials look blown out or flat in renders",
1948
+ "set physically accurate PBR values for metal, plastic, glass, and fabric",
1949
+ "audit Principled BSDF materials for energy conservation"
1950
+ ],
1951
+ "applicability": {
1952
+ "when_to_apply": [
1953
+ "Authoring or auditing any PBR material in Blender (`lighting-material-plan` and `material-quality-checker`).",
1954
+ "Migrating shader graphs between Blender 3.6 LTS (`Principled BSDF v1`) and Blender 4.0+/4.2 LTS/5.1+ (`Principled BSDF v2`)."
1955
+ ],
1956
+ "when_not_to_apply": [
1957
+ "Deliberately non-photorealistic (NPR) cel-shaded `Shader to RGB` cartoon materials that do not target PBR or glTF."
1958
+ ],
1959
+ "target_representations": [
1960
+ "pbr-material-graph",
1961
+ "glb-container"
1962
+ ]
1963
+ },
1964
+ "prerequisites": [
1965
+ "Scene color management configured to a high-dynamic-range view transform (`AgX` or `Filmic`)."
1966
+ ],
1967
+ "principles": [
1968
+ "No real-world diffuse surface reflects 100% or 0% of incident light; dielectric `Base Color` luminance must stay within `[0.04, 0.90]` linear (`~35..240` sRGB) so carbon black retains specular form and snow/paper does not blow out global illumination.",
1969
+ "Pure materials are either **dielectrics (`Metallic = 0.0`)** with a ~4% Fresnel reflectance (`IOR = 1.5`, `Specular IOR Level = 0.5`) or **conductors (`Metallic = 1.0`)** with zero diffuse bounce and tinted specular reflectance (`Base Color` linear luminance `0.55..0.98`); intermediate metallic values (`0.2..0.8`) only occur on sub-texel dust/oxidation transitions.",
1970
+ "Every real surface has micro-imperfections; keep `Roughness` within `[0.02, 0.98]` with spatial roughness variation so specular highlights neither vanish into infinitesimal pinpoints (`0.0`) nor flatten into chalk (`1.0`).",
1971
+ "Blender 4.0+ **Principled BSDF v2** orders layers top-to-bottom (`Coat -> Emission -> Specular/Metallic -> Diffuse/Subsurface/Transmission`), uses energy-preserving multi-scatter GGX, renames `Specular` to `Specular IOR Level`, renames `Clearcoat` to `Coat Weight`, and places `Sheen` at the top microfiber layer."
1972
+ ],
1973
+ "implementation_guidance": {
1974
+ "workflow_steps": [
1975
+ "Classify each material as Dielectric (`Metallic = 0.0`), Conductor (`Metallic = 1.0`), Refractive Dielectric (`Transmission Weight = 1.0`, `Roughness <= 0.15`, `IOR = 1.45-1.52`), or Coated Dielectric (`Coat Weight = 1.0`, `Coat Roughness = 0.03-0.10`).",
1976
+ "Clamp `Base Color` values inside `[0.04, 0.90]` linear for dielectrics and `[0.55, 0.98]` linear for bare polished metals.",
1977
+ "When authoring across Blender versions, map Blender 3.6 LTS `Specular` (`0.5`) to Blender 4.0+ `Specular IOR Level` (`0.5`), `Clearcoat` to `Coat Weight`, and `Subsurface` to `Subsurface Weight` (`0..1`) + `Subsurface Scale` (in meters)."
1978
+ ],
1979
+ "recommended_parameters": {
1980
+ "dielectric_base_color_linear_range": "0.04 to 0.90",
1981
+ "conductor_base_color_linear_range": "0.55 to 0.98",
1982
+ "default_dielectric_ior": 1.5,
1983
+ "default_specular_ior_level": 0.5,
1984
+ "roughness_safe_bounds": "0.03 to 0.96"
1985
+ },
1986
+ "blender_context": "Shader Editor -> Shader -> Principled BSDF (v2 in Blender 4.0+/4.2 LTS/5.1+, v1 in Blender 3.6 LTS)."
1987
+ },
1988
+ "observable_checks": [
1989
+ {
1990
+ "id": "check.albedo-within-pbr-coal-to-snow-bounds",
1991
+ "check": "Inspect Base Color RGB values and texture histograms on dielectric materials.",
1992
+ "pass_condition": "Linear luminance stays between `0.04` (charcoal) and `0.90` (fresh snow/white paint).",
1993
+ "fail_indicator": "Pure `0.0` black eats all indirect light or pure `1.0` white causes radioactive GI blowouts."
1994
+ },
1995
+ {
1996
+ "id": "check.binary-metalness-discipline",
1997
+ "check": "Inspect `Metallic` scalar or texture values on uniform materials.",
1998
+ "pass_condition": "`Metallic` is `0.0` for plastics/wood/stone/fabric/glass and `1.0` for bare metals.",
1999
+ "fail_indicator": "Constant `Metallic = 0.45` used to fake 'shiny plastic', producing physically invalid grey specular response."
2000
+ },
2001
+ {
2002
+ "id": "check.version-matched-socket-names",
2003
+ "check": "Verify Principled BSDF socket names match the target Blender version.",
2004
+ "pass_condition": "Blender 4.0+/4.2 LTS/5.1+ uses `Specular IOR Level`, `Coat Weight`, `Transmission Weight`, and `Subsurface Weight/Scale`.",
2005
+ "fail_indicator": "Scripts or plans target removed 3.6 socket names (`Clearcoat`, `Subsurface Color`) on Blender 4.2 LTS."
2006
+ }
2007
+ ],
2008
+ "creative_affordances": [
2009
+ "Layering a low-roughness `Coat` (`Coat Weight = 1.0`, `Coat Roughness = 0.04`) over a higher-roughness metallic base (`Roughness = 0.35`) creates authentic automotive flake paint and anodized footwear finishes.",
2010
+ "Blender 4.0+ microfiber `Sheen` (`Sheen Weight = 0.5-1.0`, `Sheen Roughness = 0.4`) produces velvety grazing rim highlights on suede, nylon, and canvas."
2011
+ ],
2012
+ "known_limits": [
2013
+ "`Subsurface Scattering` in Blender Principled BSDF does not export to core glTF 2.0; web engines require `KHR_materials_volume` / `KHR_materials_transmission` or custom thickness maps to approximate translucency."
2014
+ ],
2015
+ "claims": [
2016
+ {
2017
+ "id": "claim.principled-bsdf-v2-overhaul-40",
2018
+ "statement": "Blender 4.0 replaced the original Principled BSDF with an energy-conserving layered shader model (Coat, Emission, Metallic/Specular, Diffuse/Subsurface/Transmission) and renamed several sockets.",
2019
+ "scope": "Blender 4.0+, 4.2 LTS, and 5.1+.",
2020
+ "uncertainty_or_version_note": "Existing 3.6 LTS `.blend` files are automatically version-updated when opened in 4.0+, but Python scripts indexing sockets by old names must be updated.",
2021
+ "source_refs": [
2022
+ {
2023
+ "source_id": "source.blender-release-notes",
2024
+ "locator": "Blender 4.0 Release Notes — Cycles & Shader Nodes (Principled BSDF v2)"
2025
+ },
2026
+ {
2027
+ "source_id": "source.blender-manual-shading-color",
2028
+ "locator": "Shader Nodes -> Shader -> Principled BSDF"
2029
+ }
2030
+ ]
2031
+ },
2032
+ {
2033
+ "id": "claim.dielectric-f0-fresnel-formula",
2034
+ "statement": "At normal incidence, a dielectric surface with index of refraction IOR=1.5 reflects F0 = ((1.5 - 1.0)/(1.5 + 1.0))^2 = 0.04 (4%) of incident light, which corresponds to `Specular IOR Level = 0.5`.",
2035
+ "scope": "Physically based rendering across Blender and glTF 2.0.",
2036
+ "uncertainty_or_version_note": "Exact Fresnel Schlick / dielectric reflectance identity.",
2037
+ "source_refs": [
2038
+ {
2039
+ "source_id": "source.google-filament-pbr",
2040
+ "locator": "Reflectance at Normal Incidence (F0) for Dielectrics and Conductors"
2041
+ }
2042
+ ]
2043
+ }
2044
+ ],
2045
+ "source_refs": [
2046
+ {
2047
+ "source_id": "source.blender-manual-shading-color",
2048
+ "locator": "Principled BSDF Node"
2049
+ },
2050
+ {
2051
+ "source_id": "source.google-filament-pbr",
2052
+ "locator": "Material Models — Standard PBR Parameter Ranges"
2053
+ }
2054
+ ],
2055
+ "related_ids": {
2056
+ "knowledge_ids": [
2057
+ "knowledge.normal-roughness-and-orm-channel-packing",
2058
+ "knowledge.shader-node-gltf-export-portability",
2059
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
2060
+ ],
2061
+ "skill_ids": [
2062
+ "lighting-material-plan",
2063
+ "material-quality-checker",
2064
+ "product-hero-scene-planner"
2065
+ ],
2066
+ "recipe_ids": [
2067
+ "recipe.product-hero-scene",
2068
+ "recipe.uv-and-pbr-material-preparation",
2069
+ "recipe.presentation-lighting-and-camera",
2070
+ "recipe.scene-quality-inspection-and-correction"
2071
+ ]
2072
+ },
2073
+ "blender_versions": {
2074
+ "minimum": "3.6 LTS",
2075
+ "tested_or_targeted": [
2076
+ "3.6 LTS",
2077
+ "4.2 LTS",
2078
+ "4.5.15 LTS",
2079
+ "5.1+",
2080
+ "5.2.3 LTS"
2081
+ ],
2082
+ "doc_checked_version": "5.2.3 LTS",
2083
+ "runtime_tested_version": null,
2084
+ "maintained_lts_versions": [
2085
+ "4.2 LTS",
2086
+ "4.5.15 LTS",
2087
+ "5.2.3 LTS"
2088
+ ],
2089
+ "legacy_compatibility_target": "3.6 LTS",
2090
+ "version_notes": "Major socket and energy-conservation upgrade in Blender 4.0+ (Principled BSDF v2). Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
2091
+ },
2092
+ "evidence_status": "version-checked",
2093
+ "promoted_from_skill_refs": [
2094
+ "docs/blender-version-compatibility.md",
2095
+ "skills/material-quality-checker/references/pbr-sanity-rules.md"
2096
+ ]
2097
+ },
2098
+ {
2099
+ "id": "knowledge.normal-roughness-and-orm-channel-packing",
2100
+ "title": "ORM Channel Packing (Occlusion/Roughness/Metallic) & Linear Non-Color Space Discipline",
2101
+ "domain": "materials-shaders-and-pbr",
2102
+ "kind": "material-shader-profile",
2103
+ "summary": "Rules for packing Ambient Occlusion (R), Roughness (G), and Metallic (B) into a single linear RGB texture for glTF 2.0 and enforcing `Non-Color` color space on all non-albedo data textures.",
2104
+ "aliases": [
2105
+ "orm-texture-channel-packing",
2106
+ "non-color-vs-srgb-texture-rules",
2107
+ "gltf-occlusion-roughness-metallic-packing"
2108
+ ],
2109
+ "intent_signals": [
2110
+ "how do I pack AO, Roughness, and Metallic into one ORM texture in Blender",
2111
+ "which textures should be set to sRGB vs Non-Color in Blender",
2112
+ "normal map or roughness map looks shiny, wrong, or has seam lines",
2113
+ "wire glTF Settings node for Ambient Occlusion export in Blender"
2114
+ ],
2115
+ "applicability": {
2116
+ "when_to_apply": [
2117
+ "Wiring image textures into Principled BSDF for rendering or glTF 2.0 / GLB export.",
2118
+ "Auditing material setups in `material-quality-checker` and `mobile-glb-budget`."
2119
+ ],
2120
+ "when_not_to_apply": [
2121
+ "Untextured scalar-only materials."
2122
+ ],
2123
+ "target_representations": [
2124
+ "pbr-material-graph",
2125
+ "glb-container"
2126
+ ]
2127
+ },
2128
+ "prerequisites": [
2129
+ "AO, Roughness, and Metallic maps share the same UV layout and resolution."
2130
+ ],
2131
+ "principles": [
2132
+ "Color textures (`Base Color`, `Emission`, `Sheen Tint`) store perceptual gamma-encoded values and MUST use `Color Space = sRGB`; all scalar/vector data maps (`Normal`, `Roughness`, `Metallic`, `Ambient Occlusion`, `ORM`, `Alpha`, `Displacement`) store linear math values and MUST use `Color Space = Non-Color`.",
2133
+ "Leaving a Roughness map on `sRGB` applies an inverse ~2.2 gamma curve (`0.5^2.2 = 0.218`), making mid-roughness satin materials appear overly wet and glossy; leaving a Normal map on `sRGB` warps the neutral `0.5` flat vector to `0.218` and creates dark seam borders.",
2134
+ "Khronos glTF 2.0 packs `metallicRoughnessTexture` with **Green = Roughness (`G`)** and **Blue = Metalness (`B`)**, and supports packing **Red = Ambient Occlusion (`R`)** in the exact same image texture (`ORM`), cutting 3 GPU texture lookups and 3 VRAM allocations down to 1.",
2135
+ "Because Principled BSDF has no dedicated Ambient Occlusion socket, Blender's glTF exporter reads baked AO from a shader node group named `glTF Material Output` (or legacy `glTF Settings` with an `Occlusion` input socket) — NEVER multiply baked AO directly into `Base Color` for glTF export."
2136
+ ],
2137
+ "implementation_guidance": {
2138
+ "workflow_steps": [
2139
+ "Verify every `Image Texture` node in the Shader Editor: set `Base Color` and `Emission` to `sRGB`, and set `ORM`, `Roughness`, `Metallic`, `Normal`, and `Height` to `Non-Color`.",
2140
+ "Connect the packed `ORM` `Image Texture` (`Non-Color`) into a `Separate Color` node (`Mode: RGB`): route `Green` -> `Principled BSDF: Roughness`, `Blue` -> `Principled BSDF: Metallic`, and `Red` -> `glTF Material Output: Occlusion`.",
2141
+ "Connect the `Normal` `Image Texture` (`Non-Color`) through a `Vector -> Normal Map` node (`Tangent Space`, `Strength = 1.0`) into `Principled BSDF: Normal`."
2142
+ ],
2143
+ "recommended_parameters": {
2144
+ "orm_red_channel": "Ambient Occlusion",
2145
+ "orm_green_channel": "Roughness",
2146
+ "orm_blue_channel": "Metallic",
2147
+ "data_texture_color_space": "Non-Color",
2148
+ "color_texture_color_space": "sRGB"
2149
+ },
2150
+ "blender_context": "Shader Editor -> Image Texture (Color Space: Non-Color vs. sRGB) -> Converter -> Separate Color (4.0+) / Separate RGB."
2151
+ },
2152
+ "observable_checks": [
2153
+ {
2154
+ "id": "check.non-color-on-all-data-maps",
2155
+ "check": "Inspect the `Color Space` dropdown on every `Image Texture` node connected to Normal, Roughness, Metallic, or Occlusion.",
2156
+ "pass_condition": "100% of data textures are set to `Non-Color`.",
2157
+ "fail_indicator": "Any data map set to `sRGB` distorts surface roughness or bends normals at UV seams."
2158
+ },
2159
+ {
2160
+ "id": "check.orm-channel-order-rgb",
2161
+ "check": "Verify channel routing from `Separate Color` on packed ORM maps.",
2162
+ "pass_condition": "`R` -> Occlusion, `G` -> Roughness, `B` -> Metallic.",
2163
+ "fail_indicator": "Swapping G and B turns non-metallic rough surfaces into mirror-smooth metals."
2164
+ },
2165
+ {
2166
+ "id": "check.ao-not-multiplied-into-basecolor",
2167
+ "check": "Check how Ambient Occlusion is wired in materials destined for glTF export.",
2168
+ "pass_condition": "AO is wired to the `glTF Material Output` (`Occlusion`) socket so it attenuates only indirect ambient light.",
2169
+ "fail_indicator": "Multiplying AO into `Base Color` creates permanent black dirt streaks even under direct flashlight illumination."
2170
+ }
2171
+ ],
2172
+ "creative_affordances": [
2173
+ "Packing AO + Roughness + Metallic into one ORM texture saves 66% of data-map VRAM and speeds up web loading.",
2174
+ "Allows clean separation between direct studio lights and ambient environment occlusion in Three.js."
2175
+ ],
2176
+ "known_limits": [
2177
+ "When Blender exports separate Roughness and Metallic grayscale images to GLB, the glTF exporter automatically packs them into one `G+B` texture at export time, but pre-packing `R+G+B` ORM in your texture pipeline avoids redundant source files."
2178
+ ],
2179
+ "claims": [
2180
+ {
2181
+ "id": "claim.gltf-metallic-roughness-gb-channels",
2182
+ "statement": "The glTF 2.0 specification requires `metallicRoughnessTexture` to encode metalness in the B (blue) channel and roughness in the G (green) channel using linear transfer functions, while `occlusionTexture` reads from the R (red) channel.",
2183
+ "scope": "Khronos glTF 2.0 specification Section 3.9.",
2184
+ "uncertainty_or_version_note": "Allowing a single RGB texture to serve as both `occlusionTexture` and `metallicRoughnessTexture`.",
2185
+ "source_refs": [
2186
+ {
2187
+ "source_id": "source.khronos-gltf-2-spec",
2188
+ "locator": "PBR Metallic-Roughness — Channel Encoding (R=Occlusion, G=Roughness, B=Metalness)"
2189
+ }
2190
+ ]
2191
+ },
2192
+ {
2193
+ "id": "claim.blender-gltf-material-output-occlusion",
2194
+ "statement": "Blender's glTF 2.0 exporter exports an `occlusionTexture` when a scalar channel is wired into the `Occlusion` socket of the `glTF Material Output` (or `glTF Settings`) node.",
2195
+ "scope": "Blender 3.6 LTS, 4.2 LTS, and 5.1+ glTF 2.0 add-on.",
2196
+ "uncertainty_or_version_note": "Blender 4.2 LTS provides `Add -> Output -> glTF Material Output` natively when the glTF add-on is enabled.",
2197
+ "source_refs": [
2198
+ {
2199
+ "source_id": "source.blender-manual-gltf-io",
2200
+ "locator": "glTF Material Output / Occlusion Socket"
2201
+ }
2202
+ ]
2203
+ }
2204
+ ],
2205
+ "source_refs": [
2206
+ {
2207
+ "source_id": "source.khronos-gltf-2-spec",
2208
+ "locator": "Metallic-Roughness Material Model"
2209
+ },
2210
+ {
2211
+ "source_id": "source.blender-manual-gltf-io",
2212
+ "locator": "Principled BSDF and ORM Texture Export"
2213
+ }
2214
+ ],
2215
+ "related_ids": {
2216
+ "knowledge_ids": [
2217
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
2218
+ "knowledge.shader-node-gltf-export-portability",
2219
+ "knowledge.high-to-low-normal-and-ao-baking"
2220
+ ],
2221
+ "skill_ids": [
2222
+ "material-quality-checker",
2223
+ "lighting-material-plan",
2224
+ "glb-web-handoff",
2225
+ "mobile-glb-budget"
2226
+ ],
2227
+ "recipe_ids": [
2228
+ "recipe.uv-and-pbr-material-preparation",
2229
+ "recipe.product-hero-scene",
2230
+ "recipe.blender-to-glb-handoff",
2231
+ "recipe.web-ready-asset-optimization"
2232
+ ]
2233
+ },
2234
+ "blender_versions": {
2235
+ "minimum": "3.6 LTS",
2236
+ "tested_or_targeted": [
2237
+ "3.6 LTS",
2238
+ "4.2 LTS",
2239
+ "4.5.15 LTS",
2240
+ "5.1+",
2241
+ "5.2.3 LTS"
2242
+ ],
2243
+ "doc_checked_version": "5.2.3 LTS",
2244
+ "runtime_tested_version": null,
2245
+ "maintained_lts_versions": [
2246
+ "4.2 LTS",
2247
+ "4.5.15 LTS",
2248
+ "5.2.3 LTS"
2249
+ ],
2250
+ "legacy_compatibility_target": "3.6 LTS",
2251
+ "version_notes": "Blender 4.0+ uses `Separate Color` (replacing `Separate RGB`) and `glTF Material Output` (replacing manual `glTF Settings` node groups). Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
2252
+ },
2253
+ "evidence_status": "version-checked",
2254
+ "promoted_from_skill_refs": [
2255
+ "skills/material-quality-checker/references/pbr-sanity-rules.md",
2256
+ "skills/lighting-material-plan/references/web-material-simplification.md"
2257
+ ]
2258
+ },
2259
+ {
2260
+ "id": "knowledge.shader-node-gltf-export-portability",
2261
+ "title": "Blender Shader Graph to Khronos glTF 2.0 Export Portability & Extension Matrix",
2262
+ "domain": "materials-shaders-and-pbr",
2263
+ "kind": "material-shader-profile",
2264
+ "summary": "Definitive compatibility boundary between Blender-only procedural shader nodes (Noise, Voronoi, ColorRamp, Mix Shader, Shader to RGB, Ambient Occlusion) and the strict Principled BSDF node patterns supported by the glTF 2.0 exporter and KHR material extensions.",
2265
+ "aliases": [
2266
+ "gltf-shader-export-compatibility",
2267
+ "blender-procedural-shader-baking-requirement",
2268
+ "khr-materials-extensions-portability"
2269
+ ],
2270
+ "intent_signals": [
2271
+ "why did my Blender materials disappear or turn white when exported to GLB",
2272
+ "which Blender shader nodes export to glTF 2.0 and Three.js",
2273
+ "do Noise Texture, ColorRamp, or Mix Shader export to GLB",
2274
+ "export glass transmission, clearcoat, or sheen from Blender to Three.js",
2275
+ "metallic material looks black in threejs r3f shader export"
2276
+ ],
2277
+ "applicability": {
2278
+ "when_to_apply": [
2279
+ "Planning or auditing materials for any asset that will be exported to `.glb` / `.gltf` (`lighting-material-plan`, `material-quality-checker`, `glb-web-handoff`)."
2280
+ ],
2281
+ "when_not_to_apply": [
2282
+ "Assets rendered exclusively inside Blender Cycles/EEVEE with zero 3D file interchange."
2283
+ ],
2284
+ "target_representations": [
2285
+ "pbr-material-graph",
2286
+ "glb-container"
2287
+ ]
2288
+ },
2289
+ "prerequisites": [
2290
+ "Target web viewer (`Three.js` / `React Three Fiber`) extension support is known."
2291
+ ],
2292
+ "principles": [
2293
+ "Blender's glTF 2.0 exporter does NOT transpile arbitrary Blender shader graphs into GLSL; it pattern-matches specific direct connections into `Principled BSDF` (`Base Color`, `Metallic`, `Roughness`, `Normal`, `Emission`, `Alpha`) and `glTF Material Output` (`Occlusion`).",
2294
+ "Any procedural generator (`Noise Texture`, `Voronoi`, `Musgrave`/`Wave`, `Ambient Occlusion`, `Bevel`, `Pointiness`) or remapper (`ColorRamp`, `Map Range`, `Mix Shader`, `Shader to RGB`) connected upstream of Principled BSDF will be silently dropped on GLB export unless baked to image textures first.",
2295
+ "UV tiling and offset export ONLY when wired strictly as `Texture Coordinate (UV) -> Mapping (Point/Texture) -> Image Texture`, which translates to `KHR_texture_transform`.",
2296
+ "Advanced physical layers on Principled BSDF v2 export as optional Khronos extensions (`Coat` -> `KHR_materials_clearcoat`, `Transmission` -> `KHR_materials_transmission` + `KHR_materials_volume`, `Sheen` -> `KHR_materials_sheen`, `IOR` -> `KHR_materials_ior`, `Specular` -> `KHR_materials_specular`, `Emission Strength > 1` -> `KHR_materials_emissive_strength`), which require `MeshPhysicalMaterial` in Three.js."
2297
+ ],
2298
+ "implementation_guidance": {
2299
+ "workflow_steps": [
2300
+ "Audit every material's node tree: if any procedural noise, curvature, or `ColorRamp` node is present, bake its output into `Base Color` (sRGB), `ORM` (Non-Color), and `Normal` (Non-Color) image textures before export.",
2301
+ "Ensure every exported material has a single `Principled BSDF` wired directly to `Material Output (Surface)` (never through a `Mix Shader` or `Add Shader`).",
2302
+ "For refractive glass on mobile web where `KHR_materials_transmission` framebuffer copies are expensive, offer an `Alpha Blend` (`Alpha = 0.25`, `Roughness = 0.08`) fallback profile."
2303
+ ],
2304
+ "recommended_parameters": {
2305
+ "allowed_root_shader": "Principled BSDF",
2306
+ "allowed_uv_transform_node": "Mapping",
2307
+ "glass_mobile_fallback": "Alpha Blend",
2308
+ "emissive_bloom_extension": "KHR_materials_emissive_strength"
2309
+ },
2310
+ "blender_context": "Shader Editor -> Principled BSDF + Image Texture + Mapping + Normal Map + Separate Color + glTF Material Output."
2311
+ },
2312
+ "observable_checks": [
2313
+ {
2314
+ "id": "check.zero-unbaked-procedural-nodes-on-glb-materials",
2315
+ "check": "Scan the Shader Editor of every GLB-targeted material for procedural texture or converter nodes.",
2316
+ "pass_condition": "Only `Image Texture`, `UV Map`/`Texture Coordinate`, `Mapping`, `Separate Color`, `Multiply` (for scalar/color factor tinting), `Normal Map`, `Principled BSDF`, and `glTF Material Output` are present.",
2317
+ "fail_indicator": "`Noise Texture`, `ColorRamp`, `Shader to RGB`, or `Mix Shader` is wired directly into the exported shader."
2318
+ },
2319
+ {
2320
+ "id": "check.alpha-mode-explicitly-set",
2321
+ "check": "Verify blend/alpha settings on transparent or cutout materials.",
2322
+ "pass_condition": "Foliage/decals use `Alpha Clip` (`MASK`) with explicit cutoff; glass uses `Alpha Blend` (`BLEND`) or `KHR_materials_transmission`; opaque surfaces use `Opaque` (`OPAQUE`).",
2323
+ "fail_indicator": "Opaque meshes accidentally left on `Alpha Blend` cause Z-sorting transparency flicker in Three.js."
2324
+ },
2325
+ {
2326
+ "id": "check.khr-extension-consumer-awareness",
2327
+ "check": "Verify that any used `KHR_materials_*` extensions are listed in the web handoff report.",
2328
+ "pass_condition": "Transmission, Clearcoat, Sheen, IOR, and Emissive Strength extensions are documented for the Three.js team.",
2329
+ "fail_indicator": "Heavy `KHR_materials_transmission` glass is exported to low-end mobile without warning about extra render-pass overhead."
2330
+ }
2331
+ ],
2332
+ "creative_affordances": [
2333
+ "Authoring rich procedural wear/grime in Blender and baking to a clean 2K `Base Color + ORM + Normal` triplet preserves 100% of the procedural art direction while running at 60 FPS on any WebGL device.",
2334
+ "`KHR_materials_emissive_strength` allows neon cyberpunk accents to drive Three.js post-processing UnrealBloomPass selectively when `emissiveIntensity > 1.0`."
2335
+ ],
2336
+ "known_limits": [
2337
+ "`Shader to RGB` (EEVEE NPR toon shading) cannot be baked into a view-independent static albedo texture because its shading depends on live light direction; toon looks in Three.js require `MeshToonMaterial` or custom shaders."
2338
+ ],
2339
+ "claims": [
2340
+ {
2341
+ "id": "claim.gltf-exporter-socket-pattern-matching",
2342
+ "statement": "Blender's glTF 2.0 exporter inspects a strict predefined topology of nodes connected to `Principled BSDF` (or `Background`/`Emission` for unlit) and ignores arbitrary procedural node chains.",
2343
+ "scope": "Blender glTF 2.0 exporter across 3.6 LTS, 4.2 LTS, and 5.1+.",
2344
+ "uncertainty_or_version_note": "Documented in the official Blender Manual Add-ons -> Import-Export -> glTF 2.0.",
2345
+ "source_refs": [
2346
+ {
2347
+ "source_id": "source.blender-manual-gltf-io",
2348
+ "locator": "Principled BSDF Node Setup & Supported Nodes"
2349
+ }
2350
+ ]
2351
+ },
2352
+ {
2353
+ "id": "claim.khr-materials-physical-extensions",
2354
+ "statement": "Blender 4.2 LTS exports Principled BSDF Coat, Sheen, Transmission, Volume Attenuation, Specular, IOR, Anisotropy, and Emissive Strength via official `KHR_materials_*` glTF 2.0 extensions.",
2355
+ "scope": "Blender 4.2 LTS and 5.1+ glTF exporter + Three.js `GLTFLoader`.",
2356
+ "uncertainty_or_version_note": "Anisotropy (`KHR_materials_anisotropy`) requires Blender 4.0+ and recent Three.js r152+.",
2357
+ "source_refs": [
2358
+ {
2359
+ "source_id": "source.blender-manual-gltf-io",
2360
+ "locator": "Extended Principled BSDF Sockets (KHR_materials_*)"
2361
+ },
2362
+ {
2363
+ "source_id": "source.khronos-gltf-2-spec",
2364
+ "locator": "Khronos Ratified PBR Material Extensions"
2365
+ }
2366
+ ]
2367
+ }
2368
+ ],
2369
+ "source_refs": [
2370
+ {
2371
+ "source_id": "source.blender-manual-gltf-io",
2372
+ "locator": "glTF 2.0 Material & Shader Node Export Rules"
2373
+ },
2374
+ {
2375
+ "source_id": "source.khronos-gltf-2-spec",
2376
+ "locator": "Materials and KHR_materials_* Extensions"
2377
+ }
2378
+ ],
2379
+ "related_ids": {
2380
+ "knowledge_ids": [
2381
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
2382
+ "knowledge.normal-roughness-and-orm-channel-packing",
2383
+ "knowledge.high-to-low-normal-and-ao-baking"
2384
+ ],
2385
+ "skill_ids": [
2386
+ "lighting-material-plan",
2387
+ "material-quality-checker",
2388
+ "glb-web-handoff",
2389
+ "r3f-component-plan"
2390
+ ],
2391
+ "recipe_ids": [
2392
+ "recipe.product-hero-scene",
2393
+ "recipe.uv-and-pbr-material-preparation",
2394
+ "recipe.blender-to-glb-handoff",
2395
+ "recipe.procedural-geometry-nodes-asset"
2396
+ ]
2397
+ },
2398
+ "blender_versions": {
2399
+ "minimum": "3.6 LTS",
2400
+ "tested_or_targeted": [
2401
+ "3.6 LTS",
2402
+ "4.2 LTS",
2403
+ "4.5.15 LTS",
2404
+ "5.1+",
2405
+ "5.2.3 LTS"
2406
+ ],
2407
+ "doc_checked_version": "5.2.3 LTS",
2408
+ "runtime_tested_version": null,
2409
+ "maintained_lts_versions": [
2410
+ "4.2 LTS",
2411
+ "4.5.15 LTS",
2412
+ "5.2.3 LTS"
2413
+ ],
2414
+ "legacy_compatibility_target": "3.6 LTS",
2415
+ "version_notes": "Blender 4.2 LTS adds Export -> Materials -> Export Unused Images/Textures and expanded `KHR_materials_*` mapping from Principled BSDF v2. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
2416
+ },
2417
+ "evidence_status": "version-checked",
2418
+ "promoted_from_skill_refs": [
2419
+ "docs/blender-version-compatibility.md",
2420
+ "skills/lighting-material-plan/references/material-portability.md",
2421
+ "skills/material-quality-checker/references/consumer-stack-rules.md"
2422
+ ]
2423
+ },
2424
+ {
2425
+ "id": "knowledge.three-point-and-hdri-studio-lighting",
2426
+ "title": "Three-Point Studio Lighting Ratios, Area Light Angular Size & HDRI Balance",
2427
+ "domain": "lighting-camera-and-rendering",
2428
+ "kind": "lighting-camera-rule",
2429
+ "summary": "Physically based studio lighting methodology governing Key-to-Fill illuminance ratios (EV contrast), Area light physical size vs. shadow penumbra softness, grazing Rim/kicker placement, and neutral HDRI environment fill.",
2430
+ "aliases": [
2431
+ "studio-three-point-lighting-ratios",
2432
+ "key-fill-rim-and-hdri-balance",
2433
+ "area-light-size-and-shadow-softness"
2434
+ ],
2435
+ "intent_signals": [
2436
+ "set up studio three-point lighting for a product hero or character portrait",
2437
+ "lighting looks flat, washed out, or has harsh black shadows",
2438
+ "balance HDRI environment lighting with key and rim area lights",
2439
+ "how to light dark glossy or metallic products in Blender"
2440
+ ],
2441
+ "applicability": {
2442
+ "when_to_apply": [
2443
+ "Planning or auditing lighting for product hero scenes, product grids, or character portraits (`lighting-material-plan`, `lighting-quality-checker`, `product-hero-scene-planner`, `character-portrait`)."
2444
+ ],
2445
+ "when_not_to_apply": [
2446
+ "Pure sun/sky exterior architectural daylight studies where a single physical sun + sky atmosphere dominates."
2447
+ ],
2448
+ "target_representations": [
2449
+ "lighting-camera-rig",
2450
+ "scene-hierarchy"
2451
+ ]
2452
+ },
2453
+ "prerequisites": [
2454
+ "Subject is modeled at 1:1 metric scale (`1 BU = 1m`) so Area light power (Watts) and inverse-square falloff (`1/d^2`) behave physically."
2455
+ ],
2456
+ "principles": [
2457
+ "Form perception depends on luminance contrast between lit and shadowed planes; an equal `1:1` Key-to-Fill ratio erases volume, whereas a `2:1` to `4:1` ratio (commercial/editorial) or `8:1` ratio (dramatic/cyberpunk) sculpts clear 3D dimensionality.",
2458
+ "Shadow penumbra softness and specular highlight ribbon width are controlled by the **angular size** of the Area light relative to the subject (`Light Size / Distance`), NOT by light wattage.",
2459
+ "Highly reflective metals and dark glossy plastics do not show diffuse light; they reflect the bright cards/softboxes around them, requiring large soft Area lights (or gradient light cards) positioned along reflection vectors plus a dark negative-fill environment.",
2460
+ "An HDRI World environment should serve as a subordinate ambient/reflection base (`0.2` to `0.5` Strength, `-1.5` to `-2.5 EV` below the Key light) rather than overpowering directional studio lights."
2461
+ ],
2462
+ "implementation_guidance": {
2463
+ "workflow_steps": [
2464
+ "Start from a pitch-black world (`Strength = 0`) and place the **Key Area Light** at `30-45 deg` azimuth and `30-45 deg` elevation from the camera-subject axis, sized `1.5x-3.0x` the subject's diameter for soft wrap.",
2465
+ "Add the **Fill Light** on the opposite side (`-45 to -60 deg` azimuth) at `2x` the Key's size and `0.125x-0.5x` the Key's illuminance (`4:1` to `2:1` ratio) to lift shadows without creating a competing secondary sharp shadow.",
2466
+ "Place the **Rim / Kicker Area Strip Light** behind the subject (`135-165 deg` azimuth) to separate the silhouette from the background, then bring up a low-saturation studio HDRI at `Strength = 0.25-0.45` solely to fill metallic specular reflections."
2467
+ ],
2468
+ "recommended_parameters": {
2469
+ "commercial_key_to_fill_ratio": "2.5:1 to 4:1",
2470
+ "dramatic_key_to_fill_ratio": "6:1 to 8:1",
2471
+ "key_azimuth_deg": 40,
2472
+ "key_elevation_deg": 35,
2473
+ "hdri_world_strength": 0.35
2474
+ },
2475
+ "blender_context": "Object Data Properties (Light) -> Area Light (Shape: Rectangle/Disk, Power in Watts, Size X/Y, Spread); Shader Editor (World) -> Environment Texture -> Background."
2476
+ },
2477
+ "observable_checks": [
2478
+ {
2479
+ "id": "check.distinct-key-fill-contrast-ratio",
2480
+ "check": "Inspect the False Color view transform or luminance difference between the key-lit side and fill-lit side of the subject.",
2481
+ "pass_condition": "Key side is at least 1 to 3 stops (2:1 to 8:1) brighter than the fill side, with one clear primary shadow direction.",
2482
+ "fail_indicator": "Equal left/right light intensity flattens the subject and casts crossed double shadows."
2483
+ },
2484
+ {
2485
+ "id": "check.silhouette-rim-separation",
2486
+ "check": "Inspect the subject's shadow-side contour against the background in grayscale.",
2487
+ "pass_condition": "A crisp rim highlight or background value gradient separates 100% of the subject silhouette from the backdrop.",
2488
+ "fail_indicator": "Dark subject shadow side merges indistinguishably into a dark background."
2489
+ },
2490
+ {
2491
+ "id": "check.hdri-subordinate-to-key",
2492
+ "check": "Mute the Key, Fill, and Rim lights and inspect the HDRI-only contribution.",
2493
+ "pass_condition": "HDRI alone provides soft ambient reflection fill without blowing out diffuse exposure.",
2494
+ "fail_indicator": "High-contrast outdoor sun HDRI at Strength >= 1.0 washes out the studio rig and tints white materials orange/blue."
2495
+ }
2496
+ ],
2497
+ "creative_affordances": [
2498
+ "Using a narrow `Spread` angle (`30-60 deg`) on Cycles Area lights acts like a physical honeycomb grid/egg-crate, keeping key light focused on the product while plunging the background floor into moody shadow.",
2499
+ "Split-complementary color temperature contrast (e.g., `5200K` neutral-warm Key + `7500K` cool-cyan Fill or Magenta/Cyan cyberpunk rims) creates instant cinematic separation."
2500
+ ],
2501
+ "known_limits": [
2502
+ "Area light `Spread` beam narrowing is accurately raytraced in Cycles and supported in EEVEE Next (Blender 4.2 LTS), but is ignored in Legacy EEVEE (Blender 3.6 LTS).",
2503
+ "Blender Area lights do not export to standard glTF 2.0 unless `KHR_lights_punctual` is enabled (which only supports Point, Spot, and Directional lights — not rectangular Area softboxes)."
2504
+ ],
2505
+ "claims": [
2506
+ {
2507
+ "id": "claim.angular-light-size-controls-penumbra",
2508
+ "statement": "In physically based rendering, shadow edge softness (penumbra width) is determined by the subtended solid angle of the emitter (`Size / Distance`), whereas emitter `Power` (Watts) only scales radiometric intensity.",
2509
+ "scope": "Blender Cycles and EEVEE Next.",
2510
+ "uncertainty_or_version_note": "Fundamental radiometric law.",
2511
+ "source_refs": [
2512
+ {
2513
+ "source_id": "source.blender-manual-lighting-rendering",
2514
+ "locator": "Light Objects — Area Light Size and Power"
2515
+ }
2516
+ ]
2517
+ },
2518
+ {
2519
+ "id": "claim.khr-lights-punctual-no-area-lights",
2520
+ "statement": "The Khronos `KHR_lights_punctual` glTF 2.0 extension defines only `directional`, `point`, and `spot` light types; rectangular `area` lights are not part of the extension and must be approximated in Three.js via PMREM environment maps (`RectAreaLightUniformsLib` or `<Environment>`).",
2521
+ "scope": "Khronos glTF 2.0 `KHR_lights_punctual` and Three.js.",
2522
+ "uncertainty_or_version_note": "Verified in Khronos `KHR_lights_punctual` specification.",
2523
+ "source_refs": [
2524
+ {
2525
+ "source_id": "source.khronos-gltf-2-spec",
2526
+ "locator": "KHR_lights_punctual Extension — Light Types"
2527
+ }
2528
+ ]
2529
+ }
2530
+ ],
2531
+ "source_refs": [
2532
+ {
2533
+ "source_id": "source.blender-manual-lighting-rendering",
2534
+ "locator": "Lighting -> Light Objects & World Environment"
2535
+ },
2536
+ {
2537
+ "source_id": "source.google-filament-pbr",
2538
+ "locator": "Image-Based Lighting and Photometric Light Units"
2539
+ }
2540
+ ],
2541
+ "related_ids": {
2542
+ "knowledge_ids": [
2543
+ "knowledge.physically-based-camera-lens-and-dof",
2544
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
2545
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
2546
+ ],
2547
+ "skill_ids": [
2548
+ "lighting-material-plan",
2549
+ "lighting-quality-checker",
2550
+ "product-hero-scene-planner",
2551
+ "character-portrait"
2552
+ ],
2553
+ "recipe_ids": [
2554
+ "recipe.product-hero-scene",
2555
+ "recipe.presentation-lighting-and-camera",
2556
+ "recipe.scene-quality-inspection-and-correction"
2557
+ ]
2558
+ },
2559
+ "blender_versions": {
2560
+ "minimum": "3.6 LTS",
2561
+ "tested_or_targeted": [
2562
+ "3.6 LTS",
2563
+ "4.2 LTS",
2564
+ "4.5.15 LTS",
2565
+ "5.1+",
2566
+ "5.2.3 LTS"
2567
+ ],
2568
+ "doc_checked_version": "5.2.3 LTS",
2569
+ "runtime_tested_version": null,
2570
+ "maintained_lts_versions": [
2571
+ "4.2 LTS",
2572
+ "4.5.15 LTS",
2573
+ "5.2.3 LTS"
2574
+ ],
2575
+ "legacy_compatibility_target": "3.6 LTS",
2576
+ "version_notes": "Blender 4.2 LTS EEVEE Next adds raytraced soft shadows and Area Light Spread support. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
2577
+ },
2578
+ "evidence_status": "version-checked",
2579
+ "promoted_from_skill_refs": [
2580
+ "skills/lighting-material-plan/references/lighting-patterns.md",
2581
+ "skills/lighting-quality-checker/references/intensity-ranges.md",
2582
+ "skills/lighting-quality-checker/references/hdri-balance-rules.md",
2583
+ "skills/lighting-quality-checker/references/shadow-softness-rules.md"
2584
+ ]
2585
+ },
2586
+ {
2587
+ "id": "knowledge.physically-based-camera-lens-and-dof",
2588
+ "title": "Physical Camera Sensor Size, Focal Length Compression, Tilt-Shift & Depth of Field",
2589
+ "domain": "lighting-camera-and-rendering",
2590
+ "kind": "lighting-camera-rule",
2591
+ "summary": "Optical rules for selecting full-frame (36mm) equivalent focal lengths by scene domain, preventing wide-angle perspective distortion on products/portraits, maintaining parallel architectural verticals via Lens Shift Y, and calibrating physical f-stop depth of field.",
2592
+ "aliases": [
2593
+ "camera-focal-length-and-sensor-size",
2594
+ "depth-of-field-f-stop-and-metric-scale",
2595
+ "architectural-two-point-vertical-shift"
2596
+ ],
2597
+ "intent_signals": [
2598
+ "what camera focal length and f-stop should I use for a product or portrait render",
2599
+ "product or character face looks warped and fish-eyed in close-up",
2600
+ "keep vertical walls straight in an architectural interior render",
2601
+ "depth of field is either completely blurry or not blurring at all"
2602
+ ],
2603
+ "applicability": {
2604
+ "when_to_apply": [
2605
+ "Configuring camera optics, framing, and depth of field in `camera-composition`, `composition-quality-checker`, `product-hero-scene-planner`, `character-portrait`, `interior-scene`, and `environment-shot`."
2606
+ ],
2607
+ "when_not_to_apply": [
2608
+ "Asset-only geometry preparation where no camera or render view is configured."
2609
+ ],
2610
+ "target_representations": [
2611
+ "lighting-camera-rig",
2612
+ "scene-hierarchy"
2613
+ ]
2614
+ },
2615
+ "prerequisites": [
2616
+ "Scene modeled at true metric scale (`1 BU = 1m`) and Camera Sensor Width locked to `36 mm` (Full Frame standard)."
2617
+ ],
2618
+ "principles": [
2619
+ "Perspective distortion is governed by camera-to-subject distance; using a wide lens (`< 35mm` on a 36mm sensor) close to a product or face exaggerates near features (nose/toe-box) by 30-50%, whereas `50mm-105mm` lenses allow a flattering working distance with natural proportion compression.",
2620
+ "Physical Depth of Field circle-of-confusion radius scales inversely with f-stop (`D = f / N`) and quadratically with focus distance; if a 0.30m sneaker is modeled at 30 meters by mistake, `f/2.8` produces almost zero blur unless the scene scale is corrected to meters.",
2621
+ "In architectural interiors and exteriors, tilting the camera up or down (`Rotation X != 90 deg`) introduces 3-point perspective where vertical walls converge; locking `Rotation X = 90.0 deg` and framing vertically via `Camera -> Lens -> Shift Y` preserves strict 2-point parallel verticals.",
2622
+ "For e-commerce product grids and UI cards, leaving 25-35% intentional negative space (or a dedicated copy-safe third) prevents text overlays and badges from colliding with the hero silhouette."
2623
+ ],
2624
+ "implementation_guidance": {
2625
+ "workflow_steps": [
2626
+ "Set Camera `Sensor Fit = Auto`, `Sensor Width = 36 mm`, and choose focal length by domain: **Product Hero** `65mm-105mm` (`85mm` default), **Character Portrait** `85mm-135mm`, **Interior Archviz** `24mm-35mm` (with `Rotation X = 90 deg` + `Shift Y`), **Environment Wide Shot** `24mm-35mm`.",
2627
+ "Place an `Empty` object (`Focus_Target`) at the nearest hero focal feature (e.g., front eye or product logo badge) and assign it as the Camera's `Depth of Field -> Focus Object`.",
2628
+ "Set `F-Stop` according to subject size at 1:1 meter scale: `f/4.0 - f/8.0` for tabletop products (`0.15m - 0.5m` size) so the front and mid-body stay sharp while the background softens; `f/2.0 - f/4.0` for human portraits."
2629
+ ],
2630
+ "recommended_parameters": {
2631
+ "sensor_width_mm": 36,
2632
+ "product_hero_focal_length_mm": 85,
2633
+ "portrait_focal_length_mm": 85,
2634
+ "interior_focal_length_mm": 28,
2635
+ "product_hero_f_stop": 5.6
2636
+ },
2637
+ "blender_context": "Object Data Properties (Camera) -> Lens (Focal Length, Shift X/Y), Depth of Field (Focus Object, F-Stop, Blades), Sensor (Width: 36mm)."
2638
+ },
2639
+ "observable_checks": [
2640
+ {
2641
+ "id": "check.no-wide-angle-distortion-on-hero-or-portrait",
2642
+ "check": "Inspect Camera Focal Length (at 36mm sensor width) for product hero and character portrait shots.",
2643
+ "pass_condition": "Focal length is `>= 50 mm` (`65-105 mm` preferred for products, `85-135 mm` for portraits).",
2644
+ "fail_indicator": "Default `50mm` or `<35mm` lens used at macro distance, warping product geometry."
2645
+ },
2646
+ {
2647
+ "id": "check.parallel-verticals-in-archviz",
2648
+ "check": "Check Camera `Rotation X` on interior and architectural eye-level shots.",
2649
+ "pass_condition": "`Rotation X = 90.0 deg` (level horizon) with vertical composition adjusted via `Lens Shift Y`.",
2650
+ "fail_indicator": "Pitched camera tilts vertical walls and doorways inward or outward."
2651
+ },
2652
+ {
2653
+ "id": "check.focus-locked-on-primary-feature",
2654
+ "check": "Verify Depth of Field focus target and front-to-back sharpness on the hero subject.",
2655
+ "pass_condition": "Primary logo/eye is tack-sharp and at least 60-80% of the hero product body remains within the depth-of-field acceptable sharpness zone.",
2656
+ "fail_indicator": "`f/0.5` miniature toy blur makes a real-scale product look like a 1cm plastic miniature."
2657
+ }
2658
+ ],
2659
+ "creative_affordances": [
2660
+ "Setting Aperture `Blades = 6` or `8` with slight `Rotation` produces polygonal cinema bokeh highlights in background specular out-of-focus lights.",
2661
+ "Using `Shift X / Shift Y` allows placing a product in the right-hand third of a 16:9 web hero banner with zero perspective keystoning."
2662
+ ],
2663
+ "known_limits": [
2664
+ "Camera `Lens Shift X/Y` (tilt-shift off-axis projection) is fully supported in Cycles and EEVEE, but is not part of the standard glTF 2.0 `camera.perspective` specification."
2665
+ ],
2666
+ "claims": [
2667
+ {
2668
+ "id": "claim.aperture-diameter-focal-over-fstop",
2669
+ "statement": "Blender computes physical Depth of Field using entrance pupil diameter `D = Focal_Length / F_Stop` in scene meters relative to `Sensor Width`.",
2670
+ "scope": "Blender Cycles and EEVEE physical camera model.",
2671
+ "uncertainty_or_version_note": "Requires scene geometry to be modeled in real-world meters.",
2672
+ "source_refs": [
2673
+ {
2674
+ "source_id": "source.blender-manual-lighting-rendering",
2675
+ "locator": "Camera -> Depth of Field & Sensor Size"
2676
+ }
2677
+ ]
2678
+ },
2679
+ {
2680
+ "id": "claim.tilt-shift-two-point-perspective",
2681
+ "statement": "Keeping the camera optical axis horizontal (`Rotation X = 90 deg` in Blender's Z-up space) and translating the sensor plane via `Shift Y` keeps all world-Z vertical lines strictly parallel in the image plane.",
2682
+ "scope": "Projective geometry in Blender Cameras.",
2683
+ "uncertainty_or_version_note": "Standard architectural photography tilt-shift principle.",
2684
+ "source_refs": [
2685
+ {
2686
+ "source_id": "source.blender-manual-lighting-rendering",
2687
+ "locator": "Camera Lens — Shift X/Y (Two-Point Perspective)"
2688
+ }
2689
+ ]
2690
+ }
2691
+ ],
2692
+ "source_refs": [
2693
+ {
2694
+ "source_id": "source.blender-manual-lighting-rendering",
2695
+ "locator": "Cameras — Focal Length, Sensor Fit, Shift, and Depth of Field"
2696
+ }
2697
+ ],
2698
+ "related_ids": {
2699
+ "knowledge_ids": [
2700
+ "knowledge.three-point-and-hdri-studio-lighting",
2701
+ "knowledge.modular-architectural-grid-and-metric-scale",
2702
+ "knowledge.environment-depth-layering-and-atmospheric-perspective"
2703
+ ],
2704
+ "skill_ids": [
2705
+ "camera-composition",
2706
+ "composition-quality-checker",
2707
+ "product-hero-scene-planner",
2708
+ "character-portrait",
2709
+ "interior-scene",
2710
+ "environment-shot"
2711
+ ],
2712
+ "recipe_ids": [
2713
+ "recipe.product-hero-scene",
2714
+ "recipe.presentation-lighting-and-camera",
2715
+ "recipe.stylized-environment-scene"
2716
+ ]
2717
+ },
2718
+ "blender_versions": {
2719
+ "minimum": "3.0+",
2720
+ "tested_or_targeted": [
2721
+ "3.6 LTS",
2722
+ "4.2 LTS",
2723
+ "4.5.15 LTS",
2724
+ "5.1+",
2725
+ "5.2.3 LTS"
2726
+ ],
2727
+ "doc_checked_version": "5.2.3 LTS",
2728
+ "runtime_tested_version": null,
2729
+ "maintained_lts_versions": [
2730
+ "4.2 LTS",
2731
+ "4.5.15 LTS",
2732
+ "5.2.3 LTS"
2733
+ ],
2734
+ "legacy_compatibility_target": "3.6 LTS",
2735
+ "version_notes": "Camera sensor, lens shift, and f-stop DoF parameters are identical across 3.6 LTS, 4.2 LTS, and 5.1+. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
2736
+ },
2737
+ "evidence_status": "version-checked",
2738
+ "promoted_from_skill_refs": [
2739
+ "skills/camera-composition/references/camera-presets.md",
2740
+ "skills/camera-composition/references/camera-rubric.md",
2741
+ "skills/interior-scene/references/interior-camera-rules.md",
2742
+ "skills/character-portrait/references/portrait-framing-rules.md"
2743
+ ]
2744
+ },
2745
+ {
2746
+ "id": "knowledge.agx-filmic-color-management-and-cycles-eevee",
2747
+ "title": "AgX vs. Filmic Color Management, EEVEE Next (4.2+) vs. Cycles & Output Bit Depth",
2748
+ "domain": "lighting-camera-and-rendering",
2749
+ "kind": "render-engine-profile",
2750
+ "summary": "Version-aware rendering and color management architecture comparing `AgX` (Blender 4.0+ default) vs. `Filmic` (3.6 LTS default) vs. `Khronos PBR Neutral`, `Cycles` path tracing vs. `EEVEE Next` (4.2 LTS) / `Legacy EEVEE` (3.6 LTS), and 8-bit/16-bit PNG vs. linear OpenEXR output.",
2751
+ "aliases": [
2752
+ "agx-vs-filmic-color-management",
2753
+ "cycles-vs-eevee-next-blender-42",
2754
+ "openexr-vs-png-16bit-output"
2755
+ ],
2756
+ "intent_signals": [
2757
+ "should I use AgX, Filmic, or Khronos PBR Neutral in Blender",
2758
+ "what changed in EEVEE Next in Blender 4.2 LTS vs Cycles",
2759
+ "fix neon colors clipping to yellow or cyan in Blender renders",
2760
+ "prevent color banding in dark studio background gradients"
2761
+ ],
2762
+ "applicability": {
2763
+ "when_to_apply": [
2764
+ "Selecting color management (`color-management-decision`), render engine (`cycles-vs-eevee-decision`), and output file format (`output-format-decision`).",
2765
+ "Synchronizing Blender lookdev with Three.js / React Three Fiber web viewers."
2766
+ ],
2767
+ "when_not_to_apply": [
2768
+ "Geometry-only container checks with no rendering or color pipeline."
2769
+ ],
2770
+ "target_representations": [
2771
+ "lighting-camera-rig",
2772
+ "pbr-material-graph",
2773
+ "glb-container"
2774
+ ]
2775
+ },
2776
+ "prerequisites": [
2777
+ "Target Blender version (3.6 LTS vs. 4.2 LTS / 5.1+) and final delivery medium (direct web sRGB vs. Nuke/Resolve/Compositor grading) are known."
2778
+ ],
2779
+ "principles": [
2780
+ "Per-channel display transforms (`Standard` and `Filmic`) clip individual R, G, or B channels sequentially at high exposure, skewing intense red/blue/magenta lights into harsh yellow/cyan/white (`Notorious Six`); **AgX** (Blender 4.0+ default) attenuates chroma smoothly toward white before channel clipping, preserving natural highlight roll-off.",
2781
+ "**Khronos PBR Neutral** (added in Blender 4.2 LTS) is specifically engineered for e-commerce product photography where exact sRGB brand swatch fidelity in midtones is required without filmic hue shifts.",
2782
+ "Blender 4.2 LTS replaced Legacy EEVEE with **EEVEE Next**, introducing screen-space raytraced indirect lighting, virtual shadow maps, and horizon scan, while removing the legacy EEVEE `Bloom` checkbox in favor of the Viewport/Render Compositor `Glare` (`Fog Glow` / `Bloom`) node.",
2783
+ "Saving smooth dark studio vignettes to 8-bit PNG (256 levels per channel) causes visible staircase color banding; use **16-bit PNG** (with `Dither = 1.0-2.0`) for direct delivery or **16-bit half-float OpenEXR (DWAA/ZIP)** for linear scene-referred compositing (note: OpenEXR stores raw linear data and does NOT bake the AgX/Filmic view transform)."
2784
+ ],
2785
+ "implementation_guidance": {
2786
+ "workflow_steps": [
2787
+ "Set `Display Device = sRGB` and select `View Transform`: `AgX` (`Look: Medium High Contrast` or `Punchy`) for general/cinematic/neon scenes in Blender 4.0+; `Khronos PBR Neutral` for color-critical e-commerce in 4.2+; `Filmic` (`Medium High Contrast`) if constrained to Blender 3.6 LTS.",
2788
+ "Choose Render Engine: `Cycles` (`GPU Compute`, `Noise Threshold = 0.01`, `Max Samples = 256-1024`, `OpenImageDenoise` with `Albedo and Normal` passes) for refractive glass, caustics, or baking; `EEVEE Next` (4.2+) for fast turntables and stylization.",
2789
+ "In Blender 4.2+ EEVEE Next or Cycles, add a `Filter -> Glare` (`Bloom` or `Fog Glow`, `Mix = -0.85`) node in the Compositor with Viewport Compositor set to `Always` instead of looking for the removed EEVEE Bloom property."
2790
+ ],
2791
+ "recommended_parameters": {
2792
+ "view_transform_40_plus": "AgX",
2793
+ "view_transform_ecommerce_42_plus": "Khronos PBR Neutral",
2794
+ "view_transform_36_lts": "Filmic",
2795
+ "cycles_noise_threshold": 0.01,
2796
+ "png_color_depth_bits": 16,
2797
+ "dither_intensity": 1
2798
+ },
2799
+ "blender_context": "Render Properties -> Color Management (View Transform, Look, Exposure) & Film -> Transparent; Output Properties -> Output (File Format: PNG 16-bit or OpenEXR) & Post Processing -> Dither."
2800
+ },
2801
+ "observable_checks": [
2802
+ {
2803
+ "id": "check.view-transform-not-standard-for-pbr",
2804
+ "check": "Inspect `Render Properties -> Color Management -> View Transform`.",
2805
+ "pass_condition": "`AgX`, `Khronos PBR Neutral`, or `Filmic` is selected for physically lit 3D scenes.",
2806
+ "fail_indicator": "`Standard` view transform clips all values above 1.0 linear immediately, blowing out highlights."
2807
+ },
2808
+ {
2809
+ "id": "check.eevee-bloom-version-accuracy",
2810
+ "check": "Verify how bloom/glow is configured on Blender 4.2 LTS / 5.1+ vs. Blender 3.6 LTS.",
2811
+ "pass_condition": "Blender 4.2 LTS / 5.1+ uses the Compositor `Glare` node (`Bloom`/`Fog Glow`); Blender 3.6 LTS uses EEVEE `Bloom` or Compositor `Glare`.",
2812
+ "fail_indicator": "Instructions tell a Blender 4.2 LTS user to check the removed `Render Properties -> Bloom` checkbox."
2813
+ },
2814
+ {
2815
+ "id": "check.bit-depth-and-exr-linear-awareness",
2816
+ "check": "Verify output format bit depth and color management expectations.",
2817
+ "pass_condition": "16-bit PNG + Dither is used for display-referred deliverables with dark gradients; OpenEXR is documented as linear scene-referred requiring OCIO view transform in downstream compositors.",
2818
+ "fail_indicator": "User opens a linear OpenEXR in a basic image viewer and thinks the render is washed out or broken."
2819
+ }
2820
+ ],
2821
+ "creative_affordances": [
2822
+ "AgX `Punchy` or `Medium High Contrast` look lets saturated neon cyberpunk rim lights glow vibrantly with realistic white core desaturation.",
2823
+ "Viewport `False Color` look provides an instant light-meter heat map (`Grey = 0.18 middle grey`, `Red = clipping`)."
2824
+ ],
2825
+ "known_limits": [
2826
+ "`AgX` intentionally desaturates ultra-bright colors toward white (matching physical cameras); if a graphic flat UI element must remain 100% saturated hex color regardless of light intensity, render it in a separate pass or use `Khronos PBR Neutral`."
2827
+ ],
2828
+ "claims": [
2829
+ {
2830
+ "id": "claim.agx-default-in-blender-40",
2831
+ "statement": "Blender 4.0 replaced `Filmic` with `AgX` as the default OCIO view transform, and Blender 4.2 LTS added `Khronos PBR Neutral`.",
2832
+ "scope": "Blender 4.0+, 4.2 LTS, and 5.1+.",
2833
+ "uncertainty_or_version_note": "Verified in Blender 4.0 and 4.2 LTS Release Notes.",
2834
+ "source_refs": [
2835
+ {
2836
+ "source_id": "source.blender-release-notes",
2837
+ "locator": "Blender 4.0 (AgX) and Blender 4.2 LTS (Khronos PBR Neutral) Color Management"
2838
+ }
2839
+ ]
2840
+ },
2841
+ {
2842
+ "id": "claim.eevee-next-overhaul-42",
2843
+ "statement": "Blender 4.2 LTS replaced Legacy EEVEE with EEVEE Next, removing per-material Blend Mode / Shadow Mode dropdowns (replaced by Render Method: Dithered vs. Blended) and moving Bloom to the real-time Compositor Glare node.",
2844
+ "scope": "Blender 4.2 LTS and 5.1+.",
2845
+ "uncertainty_or_version_note": "Blender 3.6 LTS retains Legacy EEVEE.",
2846
+ "source_refs": [
2847
+ {
2848
+ "source_id": "source.blender-release-notes",
2849
+ "locator": "Blender 4.2 LTS Release Notes — EEVEE Next Migration"
2850
+ }
2851
+ ]
2852
+ }
2853
+ ],
2854
+ "source_refs": [
2855
+ {
2856
+ "source_id": "source.blender-manual-shading-color",
2857
+ "locator": "Color Management — View Transforms (AgX, Filmic, Khronos PBR Neutral)"
2858
+ },
2859
+ {
2860
+ "source_id": "source.blender-release-notes",
2861
+ "locator": "Blender 4.0 & 4.2 LTS Color Management and EEVEE Next"
2862
+ }
2863
+ ],
2864
+ "related_ids": {
2865
+ "knowledge_ids": [
2866
+ "knowledge.three-point-and-hdri-studio-lighting",
2867
+ "knowledge.principled-bsdf-v2-energy-conserving-pbr",
2868
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
2869
+ ],
2870
+ "skill_ids": [
2871
+ "color-management-decision",
2872
+ "cycles-vs-eevee-decision",
2873
+ "output-format-decision",
2874
+ "lighting-quality-checker"
2875
+ ],
2876
+ "recipe_ids": [
2877
+ "recipe.product-hero-scene",
2878
+ "recipe.presentation-lighting-and-camera",
2879
+ "recipe.stylized-environment-scene",
2880
+ "recipe.scene-quality-inspection-and-correction",
2881
+ "recipe.blender-to-glb-handoff"
2882
+ ]
2883
+ },
2884
+ "blender_versions": {
2885
+ "minimum": "3.6 LTS",
2886
+ "tested_or_targeted": [
2887
+ "3.6 LTS",
2888
+ "4.2 LTS",
2889
+ "4.5.15 LTS",
2890
+ "5.1+",
2891
+ "5.2.3 LTS"
2892
+ ],
2893
+ "doc_checked_version": "5.2.3 LTS",
2894
+ "runtime_tested_version": null,
2895
+ "maintained_lts_versions": [
2896
+ "4.2 LTS",
2897
+ "4.5.15 LTS",
2898
+ "5.2.3 LTS"
2899
+ ],
2900
+ "legacy_compatibility_target": "3.6 LTS",
2901
+ "version_notes": "Major version boundary: 3.6 LTS = Filmic + Legacy EEVEE; 4.2 LTS / 5.1+ = AgX / Khronos PBR Neutral + EEVEE Next. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
2902
+ },
2903
+ "evidence_status": "version-checked",
2904
+ "promoted_from_skill_refs": [
2905
+ "docs/blender-version-compatibility.md",
2906
+ "skills/color-management-decision/references/look-comparison.md",
2907
+ "skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md",
2908
+ "skills/output-format-decision/references/bit-depth-rules.md"
2909
+ ]
2910
+ },
2911
+ {
2912
+ "id": "knowledge.armature-joint-hierarchy-and-linear-blend-skinning",
2913
+ "title": "Armature Joint Hierarchy, Transform Alignment & 4-Bone Linear Blend Skinning",
2914
+ "domain": "rigging-and-animation",
2915
+ "kind": "rigging-animation-rule",
2916
+ "summary": "Skeletal rigging invariants for Blender and glTF 2.0: shared mesh/armature world origin with applied unit transforms, separation of deform bones from IK control rigs, consistent bone roll, and normalized <=4-bone vertex weight limits.",
2917
+ "aliases": [
2918
+ "linear-blend-skinning-4-bone-limit",
2919
+ "armature-deform-bones-and-transform-reset",
2920
+ "gltf-joints-0-weights-0-skinning"
2921
+ ],
2922
+ "intent_signals": [
2923
+ "character mesh explodes or stretches when exported to GLB",
2924
+ "how many bone influences per vertex are allowed in glTF and Three.js",
2925
+ "limit and normalize vertex weights in Blender Weight Paint",
2926
+ "separate Rigify control bones from deform bones for export"
2927
+ ],
2928
+ "applicability": {
2929
+ "when_to_apply": [
2930
+ "Rigging and skinning any character, creature, or articulated mechanical asset destined for animation playback or glTF/GLB export (`glb-animation-handoff`)."
2931
+ ],
2932
+ "when_not_to_apply": [
2933
+ "Static unrigged props."
2934
+ ],
2935
+ "target_representations": [
2936
+ "skeletal-armature",
2937
+ "glb-container"
2938
+ ]
2939
+ },
2940
+ "prerequisites": [
2941
+ "Mesh topology has sufficient joint bending loops (`knowledge.quad-dominant-subdivision-topology`) and rest pose is symmetric."
2942
+ ],
2943
+ "principles": [
2944
+ "Both the Skinned Mesh and the Armature object MUST share the exact same world origin `(0, 0, 0)` with applied Location `(0,0,0)`, Rotation `(0,0,0)`, and Scale `(1,1,1)` BEFORE binding (`Armature Deform`); mismatched object transforms cause double-transform or 100x scale explosions in glTF viewers.",
2945
+ "Standard glTF 2.0 and WebGL GPU skinning (`JOINTS_0` and `WEIGHTS_0` `VEC4` vertex attributes) evaluate Linear Blend Skinning (LBS) with at most **4 bone influences per vertex** whose weights MUST sum strictly to `1.0`.",
2946
+ "Blender's `Preserve Volume` checkbox on the Armature modifier uses Dual Quaternion Skinning (DQS), which is NOT supported by glTF 2.0 or Three.js; always preview and weight-paint with `Preserve Volume = False` when targeting web/game engines.",
2947
+ "Non-uniform scaling on a parent deform bone shears child bone rotation matrices in Linear Blend Skinning; keep all deform bone scales uniform `(1,1,1)` or disable `Inherit Scale` on child bones."
2948
+ ],
2949
+ "implementation_guidance": {
2950
+ "workflow_steps": [
2951
+ "In Object Mode at Rest Pose, select both the Mesh and the Armature and run `Ctrl+A -> All Transforms` so both sit at `(0,0,0)` with scale `(1,1,1)`.",
2952
+ "In Weight Paint Mode, select all deform vertex groups (`Subset: Deform Pose Bones`), run `Weights -> Limit Total` (`Limit = 4`), and immediately run `Weights -> Normalize All` (`Lock Active = False`).",
2953
+ "Uncheck `Bone Properties -> Deform` on all IK pole targets, widget shapes, and root-motion helper bones, and enable `Animation -> Armature -> Export Deformation Bones Only` in the glTF 2.0 exporter."
2954
+ ],
2955
+ "recommended_parameters": {
2956
+ "max_bone_influences_per_vertex": 4,
2957
+ "vertex_weight_sum": 1,
2958
+ "armature_preserve_volume_for_gltf": false,
2959
+ "export_deform_bones_only": true
2960
+ },
2961
+ "blender_context": "Weight Paint Mode -> Weights -> Limit Total (4) & Normalize All; Armature Modifier (Preserve Volume: False); Bone Properties -> Deform."
2962
+ },
2963
+ "observable_checks": [
2964
+ {
2965
+ "id": "check.shared-origin-and-unit-transforms",
2966
+ "check": "Compare Location, Rotation, and Scale of the Armature object and all child Skinned Mesh objects.",
2967
+ "pass_condition": "Both Armature and Skinned Meshes have Location `(0,0,0)`, Rotation `(0,0,0)`, and Scale `(1,1,1)`.",
2968
+ "fail_indicator": "Mesh has scale `(0.01, 0.01, 0.01)` while Armature has `(1, 1, 1)`, causing inverseBindMatrices mismatch on export."
2969
+ },
2970
+ {
2971
+ "id": "check.four-bone-weight-normalization",
2972
+ "check": "Verify that `Limit Total (4)` and `Normalize All` have been executed on all deforming vertex groups.",
2973
+ "pass_condition": "Every vertex has `<= 4` deform bone weights summing to `1.000`.",
2974
+ "fail_indicator": "Vertices weighted to 6-8 bones get truncated on GLB export, leaving unnormalized weights that pull vertices toward world origin `(0,0,0)`."
2975
+ },
2976
+ {
2977
+ "id": "check.linear-blend-skinning-preview",
2978
+ "check": "Verify Armature modifier settings during pose testing.",
2979
+ "pass_condition": "`Preserve Volume` is unchecked when validating deformations for glTF/Three.js.",
2980
+ "fail_indicator": "Elbows/wrists look thick in Blender with `Preserve Volume` on, then candy-wrapper collapse after GLB export."
2981
+ }
2982
+ ],
2983
+ "creative_affordances": [
2984
+ "Adding a dedicated twist deform bone along the forearm and thigh distributes 180-degree pronation rotation smoothly under standard 4-bone Linear Blend Skinning without needing Dual Quaternions.",
2985
+ "Rigid mechanical props (hinged laptop lid, watch hands, turret) can be parented directly to individual bones (`Parent to Bone`) with zero vertex skinning overhead."
2986
+ ],
2987
+ "known_limits": [
2988
+ "Blender 4.0+ replaced numbered 32-slot Armature layers (`armature.layers`) with named `Bone Collections` (`armature.collections`); older rigging scripts referencing `layers[n]` fail on Blender 4.0+/4.2 LTS."
2989
+ ],
2990
+ "claims": [
2991
+ {
2992
+ "id": "claim.gltf-vec4-joints-weights-limit",
2993
+ "statement": "Standard glTF 2.0 skinning stores joint indices and weights in `JOINTS_0` and `WEIGHTS_0` `VEC4` accessors (4 components per vertex) and requires the sum of weights for each vertex to equal `1.0`.",
2994
+ "scope": "Khronos glTF 2.0 specification Section 3.7.3 (Skinned Meshes).",
2995
+ "uncertainty_or_version_note": "While a second `JOINTS_1`/`WEIGHTS_1` set is theoretically permitted by spec, standard WebGL shaders in Three.js bind 4 influences (`JOINTS_0`/`WEIGHTS_0`).",
2996
+ "source_refs": [
2997
+ {
2998
+ "source_id": "source.khronos-gltf-2-spec",
2999
+ "locator": "Skins — Joint Hierarchy, inverseBindMatrices, JOINTS_0 and WEIGHTS_0"
3000
+ }
3001
+ ]
3002
+ },
3003
+ {
3004
+ "id": "claim.bone-collections-blender-40",
3005
+ "statement": "Blender 4.0 replaced the fixed 32-bit Armature Bone Layers array with named hierarchical `Bone Collections`.",
3006
+ "scope": "Blender 4.0+, 4.2 LTS, and 5.1+.",
3007
+ "uncertainty_or_version_note": "Verified in Blender 4.0 Release Notes — Animation & Rigging.",
3008
+ "source_refs": [
3009
+ {
3010
+ "source_id": "source.blender-release-notes",
3011
+ "locator": "Blender 4.0 Release Notes — Bone Collections"
3012
+ }
3013
+ ]
3014
+ }
3015
+ ],
3016
+ "source_refs": [
3017
+ {
3018
+ "source_id": "source.blender-manual-rigging-animation",
3019
+ "locator": "Armatures, Skinning & Weight Paint Tools"
3020
+ },
3021
+ {
3022
+ "source_id": "source.khronos-gltf-2-spec",
3023
+ "locator": "Skins and Linear Blend Skinning"
3024
+ }
3025
+ ],
3026
+ "related_ids": {
3027
+ "knowledge_ids": [
3028
+ "knowledge.nla-action-baking-and-morph-target-export",
3029
+ "knowledge.organic-sculpt-to-retopology-workflow",
3030
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions"
3031
+ ],
3032
+ "skill_ids": [
3033
+ "glb-animation-handoff",
3034
+ "polycount-budget-checker",
3035
+ "mobile-glb-budget",
3036
+ "r3f-component-plan"
3037
+ ],
3038
+ "recipe_ids": [
3039
+ "recipe.rigged-and-animated-asset",
3040
+ "recipe.blender-to-glb-handoff"
3041
+ ]
3042
+ },
3043
+ "blender_versions": {
3044
+ "minimum": "3.6 LTS",
3045
+ "tested_or_targeted": [
3046
+ "3.6 LTS",
3047
+ "4.2 LTS",
3048
+ "4.5.15 LTS",
3049
+ "5.1+",
3050
+ "5.2.3 LTS"
3051
+ ],
3052
+ "doc_checked_version": "5.2.3 LTS",
3053
+ "runtime_tested_version": null,
3054
+ "maintained_lts_versions": [
3055
+ "4.2 LTS",
3056
+ "4.5.15 LTS",
3057
+ "5.2.3 LTS"
3058
+ ],
3059
+ "legacy_compatibility_target": "3.6 LTS",
3060
+ "version_notes": "Blender 4.0+ uses Bone Collections instead of numbered Bone Layers; Weight Paint Limit Total / Normalize All are identical. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3061
+ },
3062
+ "evidence_status": "version-checked",
3063
+ "promoted_from_skill_refs": [
3064
+ "docs/blender-version-compatibility.md",
3065
+ "skills/glb-animation-handoff/references/animation-types.md",
3066
+ "skills/glb-animation-handoff/references/web-stack-caveats.md"
3067
+ ]
3068
+ },
3069
+ {
3070
+ "id": "knowledge.nla-action-baking-and-morph-target-export",
3071
+ "title": "NLA Action Baking, Constraint Sampling, and Shape Key (Morph Target) Export Rules",
3072
+ "domain": "rigging-and-animation",
3073
+ "kind": "rigging-animation-rule",
3074
+ "summary": "Rules for baking IK/constraint rigs into visual FK keyframe clips on NLA tracks and managing Shape Key (Morph Target) memory overhead for glTF 2.0 export.",
3075
+ "aliases": [
3076
+ "nla-strip-action-baking",
3077
+ "gltf-morph-target-shape-keys",
3078
+ "visual-keying-constraint-sampling"
3079
+ ],
3080
+ "intent_signals": [
3081
+ "bake IK constraints to FK keyframes for glb export",
3082
+ "organize multiple animation clips on NLA tracks for Three.js AnimationMixer",
3083
+ "export shape keys morph targets without exploding glb file size"
3084
+ ],
3085
+ "applicability": {
3086
+ "when_to_apply": [
3087
+ "When exporting character animations (Idle, Walk, Run) or mechanical rigged assemblies to .glb.",
3088
+ "When choosing between skeletal armature animation and Shape Keys (Morph Targets) for facial expressions or soft deformations."
3089
+ ],
3090
+ "when_not_to_apply": [
3091
+ "When animations remain exclusively inside a native .blend file for offline Cycles rendering.",
3092
+ "When animations are procedural camera orbits driven by React Three Fiber at runtime."
3093
+ ],
3094
+ "target_representations": [
3095
+ "skeletal-armature",
3096
+ "glb-container"
3097
+ ]
3098
+ },
3099
+ "prerequisites": [
3100
+ "Scene frame rate (24, 30, or 60 fps) is locked before baking and each clip is stored as a named Action on an NLA Track."
3101
+ ],
3102
+ "principles": [
3103
+ "Core glTF 2.0 animation channels only evaluate node translation, rotation, scale (TRS), or morph target weights; Blender IK solvers, drivers, and constraints must be baked into visual TRS keyframes.",
3104
+ "Pushing named Actions down onto separate NLA Tracks ensures the glTF exporter emits distinct named AnimationClips for THREE.AnimationMixer.",
3105
+ "Shape Keys (glTF Morph Targets) store per-vertex position/normal deltas; attaching dozens of shape keys to a 100k-vertex unified body mesh multiplies buffer size across every vertex."
3106
+ ],
3107
+ "implementation_guidance": {
3108
+ "workflow_steps": [
3109
+ "Bake complex IK chains and constraints to deform bones using Pose -> Animation -> Bake Action with Visual Keying and Clear Constraints enabled.",
3110
+ "Push each baked clip (Idle, Walk, OpenLid) onto its own named NLA track in the NLA Editor and verify Optimize Animation Size is enabled on export.",
3111
+ "Isolate meshes that require Shape Keys (e.g., separate head/face mesh from body) so morph delta buffers only cover deforming vertices."
3112
+ ],
3113
+ "recommended_parameters": {
3114
+ "bake_visual_keying": true,
3115
+ "optimize_animation_size": true,
3116
+ "max_morph_target_vertices": 15000,
3117
+ "scene_frame_rate_fps": 30
3118
+ },
3119
+ "blender_context": "Pose Mode -> Pose -> Animation -> Bake Action; NLA Editor -> Push Down Action; File -> Export -> glTF 2.0 -> Animation."
3120
+ },
3121
+ "observable_checks": [
3122
+ {
3123
+ "id": "check.nla-track-clip-naming",
3124
+ "check": "Inspect NLA Tracks and Action names in the NLA Editor before export.",
3125
+ "pass_condition": "Each intended clip has a clean semantic name (Idle, Walk, Activate) and non-overlapping strip state.",
3126
+ "fail_indicator": "Exported .glb contains a single Action.001 or merges unrelated tracks together."
3127
+ },
3128
+ {
3129
+ "id": "check.morph-target-mesh-isolation",
3130
+ "check": "Inspect vertex count of any mesh object carrying Shape Keys in Object Data Properties.",
3131
+ "pass_condition": "Shape Keys reside only on the sub-mesh that deforms and total morph buffer stays within budget.",
3132
+ "fail_indicator": "Dozens of Shape Keys are attached to a full-body high-poly mesh, bloating .glb size by tens of megabytes."
3133
+ }
3134
+ ],
3135
+ "creative_affordances": [
3136
+ "Enables interactive product states (lid opening, exploded assembly view, character idle loops) triggered via @react-three/drei useAnimations.",
3137
+ "Allows expressive facial micro-expressions via Morph Targets combined with skeletal head and neck rotation."
3138
+ ],
3139
+ "known_limits": [
3140
+ "glTF 2.0 does not export arbitrary Blender modifier parameter animations without baking to meshes or morph targets.",
3141
+ "Blender 4.4+ introduced slotted Actions (Action Slots), allowing one Action datablock to store tracks for multiple objects."
3142
+ ],
3143
+ "claims": [
3144
+ {
3145
+ "id": "claim.gltf-animation-channels",
3146
+ "statement": "Core glTF 2.0 animation channels target node translation, rotation, scale, or morph target weights; Blender constraints and IK solvers must be sampled into TRS keyframes during export.",
3147
+ "scope": "Khronos glTF 2.0 specification and Blender glTF 2.0 exporter.",
3148
+ "uncertainty_or_version_note": "Confirmed in Khronos glTF 2.0 specification Section 3.7 (Animations).",
3149
+ "source_refs": [
3150
+ {
3151
+ "source_id": "source.khronos-gltf-2-spec",
3152
+ "locator": "Section 3.7 — Animations"
3153
+ },
3154
+ {
3155
+ "source_id": "source.blender-manual-gltf-io",
3156
+ "locator": "glTF 2.0 — Animation & Sampling"
3157
+ }
3158
+ ]
3159
+ }
3160
+ ],
3161
+ "source_refs": [
3162
+ {
3163
+ "source_id": "source.blender-manual-rigging-animation",
3164
+ "locator": "Non-Linear Animation (NLA), Action Baking & Shape Keys"
3165
+ },
3166
+ {
3167
+ "source_id": "source.blender-manual-gltf-io",
3168
+ "locator": "glTF 2.0 — Animations & Shape Keys"
3169
+ }
3170
+ ],
3171
+ "related_ids": {
3172
+ "knowledge_ids": [
3173
+ "knowledge.armature-joint-hierarchy-and-linear-blend-skinning",
3174
+ "knowledge.rigid-body-cloth-and-simulation-cache-baking",
3175
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
3176
+ ],
3177
+ "skill_ids": [
3178
+ "glb-animation-handoff",
3179
+ "r3f-component-plan",
3180
+ "glb-web-handoff",
3181
+ "mobile-glb-budget"
3182
+ ],
3183
+ "recipe_ids": [
3184
+ "recipe.rigged-and-animated-asset",
3185
+ "recipe.blender-to-glb-handoff"
3186
+ ]
3187
+ },
3188
+ "blender_versions": {
3189
+ "minimum": "3.6 LTS",
3190
+ "tested_or_targeted": [
3191
+ "3.6 LTS",
3192
+ "4.2 LTS",
3193
+ "4.5.15 LTS",
3194
+ "5.1+",
3195
+ "5.2.3 LTS"
3196
+ ],
3197
+ "doc_checked_version": "5.2.3 LTS",
3198
+ "runtime_tested_version": null,
3199
+ "maintained_lts_versions": [
3200
+ "4.2 LTS",
3201
+ "4.5.15 LTS",
3202
+ "5.2.3 LTS"
3203
+ ],
3204
+ "legacy_compatibility_target": "3.6 LTS",
3205
+ "version_notes": "Blender 4.4+ and 5.x support slotted Actions (Action Slots) in addition to NLA strips. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3206
+ },
3207
+ "evidence_status": "version-checked",
3208
+ "promoted_from_skill_refs": [
3209
+ "skills/glb-animation-handoff/references/animation-types.md",
3210
+ "skills/glb-animation-handoff/references/web-stack-caveats.md",
3211
+ "skills/r3f-component-plan/references/component-shape-patterns.md"
3212
+ ]
3213
+ },
3214
+ {
3215
+ "id": "knowledge.rigid-body-cloth-and-simulation-cache-baking",
3216
+ "title": "Rigid Body, Cloth, and Physics Simulation Cache Baking vs. Real-Time Tradeoffs",
3217
+ "domain": "simulation-and-vfx",
3218
+ "kind": "simulation-vfx-profile",
3219
+ "summary": "Principles for setting solver substeps, collision margins, and baking Blender physics simulations (Rigid Body, Cloth, Soft Body, Fluid) for offline rendering or keyframe interchange.",
3220
+ "aliases": [
3221
+ "rigid-body-bake-to-keyframes",
3222
+ "cloth-simulation-collision-substeps",
3223
+ "physics-point-cache-baking"
3224
+ ],
3225
+ "intent_signals": [
3226
+ "bake rigid body physics simulation to object keyframes",
3227
+ "fix cloth simulation self-intersection tunneling and collision margin",
3228
+ "prepare settled physics prop piles or draped fabric in Blender"
3229
+ ],
3230
+ "applicability": {
3231
+ "when_to_apply": [
3232
+ "When simulating cloth drapes, falling rigid-body piles, cables, or dynamic settled poses in Blender.",
3233
+ "When preparing physics-settled props or baked rigid-body transform animations for export."
3234
+ ],
3235
+ "when_not_to_apply": [
3236
+ "When exporting raw Mantaflow fluid voxel grids or per-frame cloth vertex caches directly to a lightweight mobile .glb.",
3237
+ "When simple manual placement or Geometry Nodes scatter achieves the layout without simulation instability."
3238
+ ],
3239
+ "target_representations": [
3240
+ "simulation-cache",
3241
+ "polygon-game-mesh",
3242
+ "glb-container"
3243
+ ]
3244
+ },
3245
+ "prerequisites": [
3246
+ "Real-world metric scale (1 BU = 1m), applied scale (1,1,1), and Origin to Center of Mass on active Rigid Body objects."
3247
+ ],
3248
+ "principles": [
3249
+ "Blender physics solvers assume 1 Blender Unit equals 1 meter for gravity (-9.81 m/s^2); unapplied or 100x centimeter scale makes simulations appear slow and floaty.",
3250
+ "Convex Hull and primitive collision shapes (Box, Sphere, Capsule) evaluate orders of magnitude faster and more stably than triangle Mesh colliders.",
3251
+ "Baking Rigid Body motion to TRS keyframes (Bake to Keyframes) produces standard node animations that export cleanly to glTF 2.0."
3252
+ ],
3253
+ "implementation_guidance": {
3254
+ "workflow_steps": [
3255
+ "Apply scale (Ctrl+A -> Scale) and set Origin to Center of Mass (Volume) on all active Rigid Body objects before simulating.",
3256
+ "Use Convex Hull collision shapes with 0.002m-0.005m collision margin and 10+ substeps per frame to prevent fast-object tunneling.",
3257
+ "Freeze static settled poses via Convert to Mesh, or bake dynamic rigid bodies via Object -> Rigid Body -> Bake to Keyframes."
3258
+ ],
3259
+ "recommended_parameters": {
3260
+ "rigid_body_substeps_per_frame": 10,
3261
+ "collision_margin_meters": 0.004,
3262
+ "cloth_quality_steps": 8,
3263
+ "cloth_collision_quality": 4
3264
+ },
3265
+ "blender_context": "Physics Properties -> Rigid Body / Cloth; Scene Properties -> Rigid Body World -> Cache -> Bake All Dynamics; Object -> Rigid Body -> Bake to Keyframes."
3266
+ },
3267
+ "observable_checks": [
3268
+ {
3269
+ "id": "check.physics-scale-and-origin",
3270
+ "check": "Verify object scale is (1.0, 1.0, 1.0) and Rigid Body origins lie at the center of mass.",
3271
+ "pass_condition": "Objects fall and tumble at physically plausible speeds without pivoting around a distant world origin.",
3272
+ "fail_indicator": "Objects pivot wildly around (0,0,0) or float in slow motion due to unapplied scale."
3273
+ },
3274
+ {
3275
+ "id": "check.simulation-cache-baked",
3276
+ "check": "Verify physics caches are explicitly baked (Bake All Dynamics or Bake to Keyframes) before rendering or exporting.",
3277
+ "pass_condition": "Scrubbing timeline or rendering out-of-order frames produces deterministic positions.",
3278
+ "fail_indicator": "Unbaked simulation snaps or resets mid-render."
3279
+ }
3280
+ ],
3281
+ "creative_affordances": [
3282
+ "Cloth pressure (Physics -> Cloth -> Pressure) rapidly sculpts believable cushions, pillows, inflated jackets, and padded footwear panels.",
3283
+ "Rigid Body drop simulations create organic clutter piles (cables, rocks, coins) free of manual intersection."
3284
+ ],
3285
+ "known_limits": [
3286
+ "Variable-topology simulations (Mantaflow liquid meshes, remeshed fracture) cannot be exported as glTF morph targets and require Alembic (.abc) or USD (.usdc) for offline DCC pipelines."
3287
+ ],
3288
+ "claims": [
3289
+ {
3290
+ "id": "claim.rigid-body-bake-to-keyframes",
3291
+ "statement": "Blender's Rigid Body -> Bake to Keyframes converts simulated rigid-body motion into standard object Location and Rotation keyframes and removes the active simulation solver dependency.",
3292
+ "scope": "Blender 3.0+ through 5.1+.",
3293
+ "uncertainty_or_version_note": "Standard Blender Physics workflow documented in Blender Manual.",
3294
+ "source_refs": [
3295
+ {
3296
+ "source_id": "source.blender-manual-physics",
3297
+ "locator": "Rigid Body — Baking to Keyframes"
3298
+ }
3299
+ ]
3300
+ }
3301
+ ],
3302
+ "source_refs": [
3303
+ {
3304
+ "source_id": "source.blender-manual-physics",
3305
+ "locator": "Rigid Body, Cloth & Physics Cache Baking"
3306
+ },
3307
+ {
3308
+ "source_id": "source.blender-manual-gltf-io",
3309
+ "locator": "glTF 2.0 — Supported Animation Types"
3310
+ }
3311
+ ],
3312
+ "related_ids": {
3313
+ "knowledge_ids": [
3314
+ "knowledge.nla-action-baking-and-morph-target-export",
3315
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
3316
+ "knowledge.volumetrics-fog-and-principled-volume-tradeoffs"
3317
+ ],
3318
+ "skill_ids": [
3319
+ "glb-animation-handoff",
3320
+ "scene-readiness",
3321
+ "glb-web-handoff"
3322
+ ],
3323
+ "recipe_ids": [
3324
+ "recipe.rigged-and-animated-asset",
3325
+ "recipe.blender-to-glb-handoff"
3326
+ ]
3327
+ },
3328
+ "blender_versions": {
3329
+ "minimum": "3.0+",
3330
+ "tested_or_targeted": [
3331
+ "3.0+",
3332
+ "3.6 LTS",
3333
+ "4.2 LTS",
3334
+ "4.5.15 LTS",
3335
+ "5.1+",
3336
+ "5.2.3 LTS"
3337
+ ],
3338
+ "doc_checked_version": "5.2.3 LTS",
3339
+ "runtime_tested_version": null,
3340
+ "maintained_lts_versions": [
3341
+ "4.2 LTS",
3342
+ "4.5.15 LTS",
3343
+ "5.2.3 LTS"
3344
+ ],
3345
+ "legacy_compatibility_target": "3.6 LTS",
3346
+ "version_notes": "Rigid Body (Bullet) and Cloth solvers plus Bake to Keyframes are stable across Blender 3.x-5.x. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3347
+ },
3348
+ "evidence_status": "source-reviewed",
3349
+ "promoted_from_skill_refs": [
3350
+ "skills/glb-animation-handoff/references/animation-types.md",
3351
+ "skills/glb-animation-handoff/references/web-stack-caveats.md"
3352
+ ]
3353
+ },
3354
+ {
3355
+ "id": "knowledge.volumetrics-fog-and-principled-volume-tradeoffs",
3356
+ "title": "Volumetric Lighting, Principled Volume, and Real-Time Depth Fog Tradeoffs",
3357
+ "domain": "simulation-and-vfx",
3358
+ "kind": "simulation-vfx-profile",
3359
+ "summary": "Decision rules for using Principled Volume shaders in Cycles/EEVEE versus Mist Pass compositing or lightweight scene fog for web and real-time targets.",
3360
+ "aliases": [
3361
+ "principled-volume-god-rays-fog",
3362
+ "cycles-mist-pass-vs-volumetrics",
3363
+ "eevee-next-volume-froxels"
3364
+ ],
3365
+ "intent_signals": [
3366
+ "add volumetric fog haze and god rays in Blender Cycles or EEVEE",
3367
+ "fix black render when using Principled Volume on World shader with Sun light",
3368
+ "translate Blender atmospheric depth fog to Three.js React Three Fiber"
3369
+ ],
3370
+ "applicability": {
3371
+ "when_to_apply": [
3372
+ "When adding atmospheric haze, crepuscular god rays, or depth separation to environment and hero product renders.",
3373
+ "When deciding how to translate Blender atmospheric mood to Three.js / React Three Fiber."
3374
+ ],
3375
+ "when_not_to_apply": [
3376
+ "When attaching Principled Volume to the unbounded World output in Cycles with a Sun light (infinite volume blocks distant Sun lamps).",
3377
+ "When expecting volumetric domain cubes to export as fog inside a .glb file."
3378
+ ],
3379
+ "target_representations": [
3380
+ "lighting-camera-rig",
3381
+ "scene-hierarchy"
3382
+ ]
3383
+ },
3384
+ "prerequisites": [
3385
+ "Volume bounds are contained within a finite domain cube mesh rather than an unbounded World shader in Cycles."
3386
+ ],
3387
+ "principles": [
3388
+ "In Cycles, attaching a Volume shader to the World output fills infinite space and completely attenuates light from Sun lamps and HDRIs evaluated at infinity.",
3389
+ "A bounded domain cube with Principled Volume (Density 0.005-0.03, Anisotropy 0.3-0.7) produces directional light shafts without blocking distant environment lights.",
3390
+ "Open-air volumetric fog does not export inside .glb files; web viewers reproduce atmospheric depth using THREE.Fog or THREE.FogExp2."
3391
+ ],
3392
+ "implementation_guidance": {
3393
+ "workflow_steps": [
3394
+ "Create a bounded fog cube around the staging area with Surface disconnected and Principled Volume connected to the Volume material output.",
3395
+ "Set Density to 0.005-0.03 and Anisotropy to 0.4-0.6 for forward-scattered backlight beams, or use the Mist render pass for zero-noise composited depth haze.",
3396
+ "Exclude the volume domain cube from .glb exports and document equivalent <fog> parameters in the web handoff spec."
3397
+ ],
3398
+ "recommended_parameters": {
3399
+ "principled_volume_density": 0.015,
3400
+ "principled_volume_anisotropy": 0.5,
3401
+ "cycles_max_volume_bounces": 0,
3402
+ "eevee_volume_steps": 64
3403
+ },
3404
+ "blender_context": "Shader Editor -> Principled Volume (Volume Output); View Layer Properties -> Passes -> Data -> Mist; Render Properties -> Volumes."
3405
+ },
3406
+ "observable_checks": [
3407
+ {
3408
+ "id": "check.bounded-volume-domain",
3409
+ "check": "Verify that volumetric fog uses a bounded mesh domain rather than the infinite World Volume output.",
3410
+ "pass_condition": "World shader has no infinite volume blocking distant lights, and the fog domain cube is excluded from GLB export.",
3411
+ "fail_indicator": "World shader has Principled Volume blocking Sun lights or fog cube exports as an opaque white box in GLB."
3412
+ },
3413
+ {
3414
+ "id": "check.volume-density-and-noise",
3415
+ "check": "Inspect hero subject contrast and shadow noise through the volumetric domain.",
3416
+ "pass_condition": "Hero silhouette remains crisp and single-scatter volume (0 bounces) avoids fireflies.",
3417
+ "fail_indicator": "Density > 0.2 obscures the subject in milky grey smoke."
3418
+ }
3419
+ ],
3420
+ "creative_affordances": [
3421
+ "Forward-scattered volumetric haze (Anisotropy 0.5) turns a rim spotlight behind a cyberpunk sneaker into a dramatic silhouette beam.",
3422
+ "Driving Principled Volume density with a 3D Noise Texture and ColorRamp creates low-lying ground mist."
3423
+ ],
3424
+ "known_limits": [
3425
+ "glTF 2.0 KHR_materials_volume models refractive attenuation inside solid transmissive glass/liquid, not open-air participating fog."
3426
+ ],
3427
+ "claims": [
3428
+ {
3429
+ "id": "claim.world-volume-sun-light-occlusion",
3430
+ "statement": "In Cycles, attaching a Volume shader to the World output fills infinite space, which completely attenuates light from Sun lamps and background HDRIs because they are evaluated at infinite distance.",
3431
+ "scope": "Blender Cycles renderer (3.0+ through 5.1+).",
3432
+ "uncertainty_or_version_note": "Documented in Blender Manual — World Volume & Principled Volume.",
3433
+ "source_refs": [
3434
+ {
3435
+ "source_id": "source.blender-manual-lighting-rendering",
3436
+ "locator": "Cycles — World Volume & Sun Light Attenuation"
3437
+ }
3438
+ ]
3439
+ }
3440
+ ],
3441
+ "source_refs": [
3442
+ {
3443
+ "source_id": "source.blender-manual-lighting-rendering",
3444
+ "locator": "Volumetric Rendering, Principled Volume & Mist Pass"
3445
+ },
3446
+ {
3447
+ "source_id": "source.threejs-color-and-gltf",
3448
+ "locator": "THREE.Fog and THREE.FogExp2"
3449
+ }
3450
+ ],
3451
+ "related_ids": {
3452
+ "knowledge_ids": [
3453
+ "knowledge.environment-depth-layering-and-atmospheric-perspective",
3454
+ "knowledge.three-point-and-hdri-studio-lighting",
3455
+ "knowledge.agx-filmic-color-management-and-cycles-eevee"
3456
+ ],
3457
+ "skill_ids": [
3458
+ "lighting-material-plan",
3459
+ "environment-shot",
3460
+ "cycles-vs-eevee-decision",
3461
+ "r3f-component-plan"
3462
+ ],
3463
+ "recipe_ids": [
3464
+ "recipe.stylized-environment-scene",
3465
+ "recipe.product-hero-scene",
3466
+ "recipe.presentation-lighting-and-camera"
3467
+ ]
3468
+ },
3469
+ "blender_versions": {
3470
+ "minimum": "3.0+",
3471
+ "tested_or_targeted": [
3472
+ "3.0+",
3473
+ "3.6 LTS",
3474
+ "4.2 LTS",
3475
+ "4.5.15 LTS",
3476
+ "5.1+",
3477
+ "5.2.3 LTS"
3478
+ ],
3479
+ "doc_checked_version": "5.2.3 LTS",
3480
+ "runtime_tested_version": null,
3481
+ "maintained_lts_versions": [
3482
+ "4.2 LTS",
3483
+ "4.5.15 LTS",
3484
+ "5.2.3 LTS"
3485
+ ],
3486
+ "legacy_compatibility_target": "3.6 LTS",
3487
+ "version_notes": "EEVEE Next (Blender 4.2+) overhauled volume froxel temporal reprojection and horizon calculation. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3488
+ },
3489
+ "evidence_status": "version-checked",
3490
+ "promoted_from_skill_refs": [
3491
+ "skills/lighting-material-plan/references/cyberpunk-lookdev.md",
3492
+ "skills/environment-shot/references/depth-layering-rules.md",
3493
+ "skills/cycles-vs-eevee-decision/references/engine-feature-matrix.md"
3494
+ ]
3495
+ },
3496
+ {
3497
+ "id": "knowledge.modular-architectural-grid-and-metric-scale",
3498
+ "title": "Modular Architectural Grid Snapping, Pivot Placement, and Real-World Metric Scale",
3499
+ "domain": "environment-and-architecture",
3500
+ "kind": "scene-assembly-pattern",
3501
+ "summary": "Standardized real-world metric dimensions, modular grid increments (0.25m / 0.5m / 1.0m / 2.0m / 4.0m), and corner/base pivot conventions for architectural and studio staging kits.",
3502
+ "aliases": [
3503
+ "modular-grid-snapping-and-pivots",
3504
+ "architectural-metric-scale-dimensions",
3505
+ "base-z-zero-origin-placement"
3506
+ ],
3507
+ "intent_signals": [
3508
+ "snap modular architectural walls and floors on a metric grid",
3509
+ "set object origin pivot to bottom center Z=0 or modular corner",
3510
+ "verify real-world metric dimensions for doors tables rooms and props"
3511
+ ],
3512
+ "applicability": {
3513
+ "when_to_apply": [
3514
+ "When building modular rooms, corridors, storefronts, pedestals, or interior environment blockouts.",
3515
+ "When verifying that hero props, furniture, and architectural elements share consistent real-world proportions."
3516
+ ],
3517
+ "when_not_to_apply": [
3518
+ "When sculpting irregular organic terrain boulders where center-of-mass pivots are preferred."
3519
+ ],
3520
+ "target_representations": [
3521
+ "scene-hierarchy",
3522
+ "hard-surface-mesh",
3523
+ "polygon-game-mesh"
3524
+ ]
3525
+ },
3526
+ "prerequisites": [
3527
+ "Scene Unit System is set to Metric, Unit Scale = 1.0, Length = Meters, and Absolute Grid Snap is enabled."
3528
+ ],
3529
+ "principles": [
3530
+ "Blender's physically based camera Depth of Field, inverse-square light wattage, Subsurface Scattering, and gravity (-9.81 m/s^2) are calibrated to 1 Blender Unit = 1 meter.",
3531
+ "Modular structural walls and floors built on binary metric increments (0.25m, 0.5m, 1.0m, 2.0m, 4.0m) with corner pivots tile cleanly without hairline gaps or T-junctions.",
3532
+ "Placing standalone prop origins at bottom-center (Z = 0) allows instant placement onto any floor or pedestal at world Z = 0 without sinking or floating."
3533
+ ],
3534
+ "implementation_guidance": {
3535
+ "workflow_steps": [
3536
+ "Verify scene units (1 BU = 1.0m) and compare bounding boxes against ergonomic benchmarks (doorway 0.9m x 2.1m, desk height 0.75m, sneaker length 0.30m).",
3537
+ "Place object origins at the bottom-back-left corner for modular wall/floor tiles and at bottom-center (Z = 0) for standalone props and pedestals.",
3538
+ "Author master kit modules inside a hidden asset collection at (0,0,0) and assemble scenes using Collection Instances."
3539
+ ],
3540
+ "recommended_parameters": {
3541
+ "modular_grid_unit_meters": 1,
3542
+ "modular_subgrid_meters": 0.25,
3543
+ "standard_doorway_height_m": 2.1,
3544
+ "standard_table_height_m": 0.75
3545
+ },
3546
+ "blender_context": "Scene Properties -> Units (Metric, 1.0); 3D Viewport -> Snap (Increment, Absolute Grid Snap); Object -> Set Origin."
3547
+ },
3548
+ "observable_checks": [
3549
+ {
3550
+ "id": "check.base-z-zero-origin",
3551
+ "check": "Verify standalone props and modular tiles have their object origin at Z = 0 relative to their resting base.",
3552
+ "pass_condition": "Setting an object's world Z location to 0.0m places its bottom surface flush on the ground plane.",
3553
+ "fail_indicator": "Setting Z = 0 buries half the object underground because the origin is at the geometric center."
3554
+ },
3555
+ {
3556
+ "id": "check.metric-bounding-box-plausibility",
3557
+ "check": "Compare object Dimensions in the N-panel against real-world metric bounds.",
3558
+ "pass_condition": "Dimensions match the intended real-world class (0.30m shoe, 0.75m table, 3.0m wall).",
3559
+ "fail_indicator": "Dimensions are off by 10x or 100x due to centimeter/millimeter unit confusion."
3560
+ }
3561
+ ],
3562
+ "creative_affordances": [
3563
+ "Bottom-center Z = 0 pivots allow instant drop-in replacement of hero products onto any studio pedestal without re-aligning floor contact.",
3564
+ "Consistent metric scale guarantees that Depth of Field (f/2.8) and area light falloff behave predictably across shots."
3565
+ ],
3566
+ "known_limits": [
3567
+ "Curved or irregular organic architecture (caves, Art Nouveau facades) requires spline/deform workflows on top of base metric modules."
3568
+ ],
3569
+ "claims": [
3570
+ {
3571
+ "id": "claim.metric-scale-couples-lighting-dof-physics",
3572
+ "statement": "Blender's physically based camera Depth of Field, inverse-square light power (Watts), Subsurface Scattering radius, and rigid-body gravity (-9.81 m/s^2) are calibrated to 1 Blender Unit = 1 meter.",
3573
+ "scope": "Blender 3.0+ through 5.1+.",
3574
+ "uncertainty_or_version_note": "Confirmed across Blender Manual Scene Units, Camera DoF, Lights, and Physics documentation.",
3575
+ "source_refs": [
3576
+ {
3577
+ "source_id": "source.blender-manual-modeling",
3578
+ "locator": "Scene Properties — Units & Metric Scale"
3579
+ },
3580
+ {
3581
+ "source_id": "source.blender-manual-lighting-rendering",
3582
+ "locator": "Light Power & Camera Depth of Field Units"
3583
+ }
3584
+ ]
3585
+ }
3586
+ ],
3587
+ "source_refs": [
3588
+ {
3589
+ "source_id": "source.blender-manual-modeling",
3590
+ "locator": "Units, Snapping & Object Origins"
3591
+ },
3592
+ {
3593
+ "source_id": "source.blender-studio-pipeline",
3594
+ "locator": "Asset Scale, Origins & Collection Conventions"
3595
+ }
3596
+ ],
3597
+ "related_ids": {
3598
+ "knowledge_ids": [
3599
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
3600
+ "knowledge.environment-depth-layering-and-atmospheric-perspective",
3601
+ "knowledge.procedural-instancing-and-realize-instances-budget"
3602
+ ],
3603
+ "skill_ids": [
3604
+ "scene-readiness",
3605
+ "interior-scene",
3606
+ "environment-shot",
3607
+ "product-hero-scene-planner"
3608
+ ],
3609
+ "recipe_ids": [
3610
+ "recipe.stylized-environment-scene",
3611
+ "recipe.product-hero-scene",
3612
+ "recipe.scene-quality-inspection-and-correction"
3613
+ ]
3614
+ },
3615
+ "blender_versions": {
3616
+ "minimum": "3.0+",
3617
+ "tested_or_targeted": [
3618
+ "3.0+",
3619
+ "3.6 LTS",
3620
+ "4.2 LTS",
3621
+ "4.5.15 LTS",
3622
+ "5.1+",
3623
+ "5.2.3 LTS"
3624
+ ],
3625
+ "doc_checked_version": "5.2.3 LTS",
3626
+ "runtime_tested_version": null,
3627
+ "maintained_lts_versions": [
3628
+ "4.2 LTS",
3629
+ "4.5.15 LTS",
3630
+ "5.2.3 LTS"
3631
+ ],
3632
+ "legacy_compatibility_target": "3.6 LTS",
3633
+ "version_notes": "Blender 4.0+ added interactive Base Point snapping (B key during transform) for corner-to-corner modular alignment. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3634
+ },
3635
+ "evidence_status": "version-checked",
3636
+ "promoted_from_skill_refs": [
3637
+ "skills/scene-readiness/references/blocker-catalog.md",
3638
+ "skills/interior-scene/references/furniture-layout-rules.md",
3639
+ "skills/product-hero-scene-planner/references/clarification-patterns.md"
3640
+ ]
3641
+ },
3642
+ {
3643
+ "id": "knowledge.environment-depth-layering-and-atmospheric-perspective",
3644
+ "title": "Foreground / Midground / Background Depth Layering and Cyclorama Staging",
3645
+ "domain": "environment-and-architecture",
3646
+ "kind": "scene-assembly-pattern",
3647
+ "summary": "Compositional staging patterns for studio cycloramas (infinity curves) and 3-plane environment depth layering (foreground framing, lit midground focal hero, low-contrast atmospheric background).",
3648
+ "aliases": [
3649
+ "foreground-midground-background-layering",
3650
+ "studio-cyclorama-infinity-curve",
3651
+ "figure-ground-luminance-separation"
3652
+ ],
3653
+ "intent_signals": [
3654
+ "stage a hero product on a seamless studio cyclorama infinity backdrop",
3655
+ "compose foreground midground background depth layers in an environment shot",
3656
+ "separate hero silhouette from background clutter using luminance contrast"
3657
+ ],
3658
+ "applicability": {
3659
+ "when_to_apply": [
3660
+ "When staging a hero product on a seamless studio backdrop or pedestal.",
3661
+ "When composing an interior room, diorama, or stylized exterior environment with strong visual depth."
3662
+ ],
3663
+ "when_not_to_apply": [
3664
+ "When exporting an isolated standalone prop .glb that will be placed into an existing third-party environment at runtime."
3665
+ ],
3666
+ "target_representations": [
3667
+ "scene-hierarchy",
3668
+ "lighting-camera-rig"
3669
+ ]
3670
+ },
3671
+ "prerequisites": [
3672
+ "Primary camera angle, aspect ratio (16:9, 1:1, 4:5), and hero subject Z = 0 ground contact are normalized."
3673
+ ],
3674
+ "principles": [
3675
+ "Three-plane depth staging separates Foreground (framing/reflections), Midground (highest-contrast focal hero), and Background (lower-contrast cyclorama or fog-softened architecture).",
3676
+ "An L-shaped backdrop with a large multi-segment Bevel modifier (radius 1.5m-3.0m, 16-32 segments) creates a seamless cyclorama infinity curve with no harsh horizon crease.",
3677
+ "Isolating studio backdrops and environment dressing in a dedicated Staging collection ensures standalone hero .glb exports never leak backdrop meshes."
3678
+ ],
3679
+ "implementation_guidance": {
3680
+ "workflow_steps": [
3681
+ "Construct an L-shaped studio backdrop or 3-plane environment layout in a dedicated Staging_Env collection separate from the hero subject.",
3682
+ "Apply a 16-32 segment Bevel modifier (Width 2.0m) with Shade Smooth to the floor-to-wall corner for a seamless studio infinity curve.",
3683
+ "Verify grayscale luminance separation (>= 3:1 edge contrast) between the midground hero silhouette and the background value."
3684
+ ],
3685
+ "recommended_parameters": {
3686
+ "cyclorama_bevel_radius_meters": 2,
3687
+ "cyclorama_bevel_segments": 24,
3688
+ "min_hero_to_bg_contrast_ratio": 3
3689
+ },
3690
+ "blender_context": "Modifiers -> Generate -> Bevel (Cyclorama Curve); Object Properties -> Visibility -> Shadow Catcher (Cycles); Outliner -> Collection Visibility."
3691
+ },
3692
+ "observable_checks": [
3693
+ {
3694
+ "id": "check.silhouette-value-separation",
3695
+ "check": "Inspect the camera view luminance contrast between the hero subject and background.",
3696
+ "pass_condition": "The midground hero subject reads clearly as a distinct silhouette against the background value.",
3697
+ "fail_indicator": "Hero edges blend into mid-tone background clutter with identical luminance."
3698
+ },
3699
+ {
3700
+ "id": "check.staging-collection-isolation",
3701
+ "check": "Verify that cyclorama, pedestal, and background props reside in a separate collection from the hero asset.",
3702
+ "pass_condition": "Hero asset can be isolated or exported independently without geometry surgery.",
3703
+ "fail_indicator": "Backdrop and hero meshes are joined into one object."
3704
+ }
3705
+ ],
3706
+ "creative_affordances": [
3707
+ "Sweeping a spot light with a wide Blend (0.8-1.0) onto a dark cyclorama creates a natural radial vignette behind the hero subject.",
3708
+ "Using Cycles Shadow Catcher on a ground plane allows transparent-background PNG renders that retain grounded contact shadows."
3709
+ ],
3710
+ "known_limits": [
3711
+ "Shadow Catcher is a Cycles-native feature; for EEVEE or Three.js web viewers, use baked ambient occlusion planes or @react-three/drei <ContactShadows>."
3712
+ ],
3713
+ "claims": [
3714
+ {
3715
+ "id": "claim.cycles-shadow-catcher-transparent-film",
3716
+ "statement": "In Cycles, enabling Shadow Catcher on a ground mesh together with Render Properties -> Film -> Transparent renders only the subject and its ground shadows into the alpha channel for compositing.",
3717
+ "scope": "Blender Cycles renderer (3.0+ through 5.1+).",
3718
+ "uncertainty_or_version_note": "Confirmed in Blender Manual — Cycles Object Settings (Shadow Catcher).",
3719
+ "source_refs": [
3720
+ {
3721
+ "source_id": "source.blender-manual-lighting-rendering",
3722
+ "locator": "Cycles — Shadow Catcher & Transparent Film"
3723
+ }
3724
+ ]
3725
+ }
3726
+ ],
3727
+ "source_refs": [
3728
+ {
3729
+ "source_id": "source.blender-manual-lighting-rendering",
3730
+ "locator": "Shadow Catcher, Film Transparency & Studio Staging"
3731
+ },
3732
+ {
3733
+ "source_id": "source.3dviz-pro-max-architecture",
3734
+ "locator": "3D Scene Composition & Studio Staging Patterns"
3735
+ }
3736
+ ],
3737
+ "related_ids": {
3738
+ "knowledge_ids": [
3739
+ "knowledge.three-point-and-hdri-studio-lighting",
3740
+ "knowledge.physically-based-camera-lens-and-dof",
3741
+ "knowledge.volumetrics-fog-and-principled-volume-tradeoffs"
3742
+ ],
3743
+ "skill_ids": [
3744
+ "product-hero-scene-planner",
3745
+ "environment-shot",
3746
+ "camera-composition",
3747
+ "composition-quality-checker"
3748
+ ],
3749
+ "recipe_ids": [
3750
+ "recipe.product-hero-scene",
3751
+ "recipe.stylized-environment-scene",
3752
+ "recipe.presentation-lighting-and-camera"
3753
+ ]
3754
+ },
3755
+ "blender_versions": {
3756
+ "minimum": "3.0+",
3757
+ "tested_or_targeted": [
3758
+ "3.0+",
3759
+ "3.6 LTS",
3760
+ "4.2 LTS",
3761
+ "4.5.15 LTS",
3762
+ "5.1+",
3763
+ "5.2.3 LTS"
3764
+ ],
3765
+ "doc_checked_version": "5.2.3 LTS",
3766
+ "runtime_tested_version": null,
3767
+ "maintained_lts_versions": [
3768
+ "4.2 LTS",
3769
+ "4.5.15 LTS",
3770
+ "5.2.3 LTS"
3771
+ ],
3772
+ "legacy_compatibility_target": "3.6 LTS",
3773
+ "version_notes": "Bevel modifier cyclorama and Cycles Shadow Catcher are consistent across Blender 3.x-5.x. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3774
+ },
3775
+ "evidence_status": "source-reviewed",
3776
+ "promoted_from_skill_refs": [
3777
+ "skills/product-hero-scene-planner/references/clarification-patterns.md",
3778
+ "skills/environment-shot/references/depth-layering-rules.md",
3779
+ "skills/composition-quality-checker/references/aspect-ratio-rules.md"
3780
+ ]
3781
+ },
3782
+ {
3783
+ "id": "knowledge.triangle-draw-call-and-vram-budgets",
3784
+ "title": "Triangle, Draw Call, Texture VRAM, and File Size Budgets by Target Tier",
3785
+ "domain": "optimization-lod-and-performance",
3786
+ "kind": "performance-budget-rule",
3787
+ "summary": "Quantitative performance budget envelopes across Mobile Web, Desktop Web / E-Commerce Hero, Real-Time Engine, and Offline Rendering tiers.",
3788
+ "aliases": [
3789
+ "mobile-desktop-triangle-budget-tiers",
3790
+ "webgl-draw-call-and-texture-vram-budget",
3791
+ "khronos-ecommerce-asset-budgets"
3792
+ ],
3793
+ "intent_signals": [
3794
+ "check mobile web and desktop triangle count and draw call budgets",
3795
+ "calculate uncompressed 4K RGBA8 texture GPU VRAM memory usage",
3796
+ "set performance budget acceptance criteria for a web GLB asset"
3797
+ ],
3798
+ "applicability": {
3799
+ "when_to_apply": [
3800
+ "When setting acceptance criteria and optimization targets before modeling, baking, or exporting a 3D asset.",
3801
+ "When auditing whether a scene or .glb file fits its target deployment platform."
3802
+ ],
3803
+ "when_not_to_apply": [
3804
+ "Do not enforce mobile draw-call limits on a single-frame offline Cycles print render unless viewport responsiveness is degraded."
3805
+ ],
3806
+ "target_representations": [
3807
+ "polygon-game-mesh",
3808
+ "glb-container",
3809
+ "scene-hierarchy"
3810
+ ]
3811
+ },
3812
+ "prerequisites": [
3813
+ "Target deployment tier (mobile_web, desktop_web_hero, desktop_realtime_scene, or offline_render) is specified."
3814
+ ],
3815
+ "principles": [
3816
+ "Real-time 3D performance is governed by four orthogonal budgets: evaluated triangle count, draw calls (mesh primitives x material slots), uncompressed GPU texture VRAM, and network .glb payload size.",
3817
+ "Standard PNG and JPEG textures stored in a .glb decompress into raw RGBA8 texel buffers (+33% for mipmaps) in GPU VRAM: a single 4096x4096 RGBA8 texture consumes ~89.4 MB of VRAM regardless of its PNG disk size.",
3818
+ "Merging static meshes that share a texture atlas and removing duplicate material slots keeps WebGL draw calls within mobile envelopes (<= 15 per hero asset)."
3819
+ ],
3820
+ "implementation_guidance": {
3821
+ "workflow_steps": [
3822
+ "Measure evaluated triangle count (with active export modifiers enabled) and distinct mesh-primitive draw calls (Objects x Material Slots).",
3823
+ "Cap mobile web hero assets at <= 35,000 triangles, <= 15 draw calls, <= 2048px textures (KTX2 recommended), and <= 5 MB .glb payload.",
3824
+ "Cap desktop web hero assets at <= 100,000 triangles, <= 30 draw calls, <= 2048-4096px textures, and <= 15 MB .glb payload."
3825
+ ],
3826
+ "recommended_parameters": {
3827
+ "mobile_hero_max_triangles": 35000,
3828
+ "mobile_hero_max_draw_calls": 15,
3829
+ "desktop_hero_max_triangles": 100000,
3830
+ "uncompressed_4k_rgba8_vram_mb": 89.4
3831
+ },
3832
+ "blender_context": "Viewport Overlays -> Statistics; Outliner -> Blender File -> Materials / Images; glTF 2.0 Export Manifest."
3833
+ },
3834
+ "observable_checks": [
3835
+ {
3836
+ "id": "check.evaluated-triangle-count",
3837
+ "check": "Measure evaluated triangle count in Viewport Statistics with active export modifiers enabled.",
3838
+ "pass_condition": "Evaluated triangle count is within the target tier envelope (<= 35k mobile hero, <= 100k desktop hero).",
3839
+ "fail_indicator": "Base cage is 10k tris, but an uncounted Level 3 Subsurf modifier exports 640k tris."
3840
+ },
3841
+ {
3842
+ "id": "check.draw-call-and-material-slot-count",
3843
+ "check": "Count distinct exported mesh primitives (Objects x Material Slots per Object).",
3844
+ "pass_condition": "Primitive/material count stays within the draw-call budget (<= 15 mobile hero, <= 30 desktop hero).",
3845
+ "fail_indicator": "Dozens of duplicate materials (Material.001, Material.002) fragment the asset into 80+ draw calls."
3846
+ }
3847
+ ],
3848
+ "creative_affordances": [
3849
+ "Allocating 70% of the triangle budget to silhouette bevels and 30% to planar interiors makes a 40k-triangle web asset look like a 500k CAD model.",
3850
+ "Packing Ambient Occlusion, Roughness, and Metallic into one ORM map cuts texture sampler count and VRAM by two-thirds."
3851
+ ],
3852
+ "known_limits": [
3853
+ "iOS Safari frequently terminates WebGL contexts when total canvas and uncompressed texture VRAM exceeds ~256-384 MB."
3854
+ ],
3855
+ "claims": [
3856
+ {
3857
+ "id": "claim.png-vram-expansion-in-webgl",
3858
+ "statement": "Standard PNG and JPEG textures stored in a .glb are decompressed into raw RGBA8 texel buffers (+33% for mipmaps) when uploaded to the GPU in WebGL/Three.js, whereas KTX2 (KHR_texture_basisu) remains block-compressed in GPU VRAM.",
3859
+ "scope": "Khronos glTF 2.0 KHR_texture_basisu specification and Three.js KTX2Loader.",
3860
+ "uncertainty_or_version_note": "Confirmed in Khronos KHR_texture_basisu specification and 3D Commerce Asset Creation Guidelines.",
3861
+ "source_refs": [
3862
+ {
3863
+ "source_id": "source.khronos-ktx2-draco-meshopt",
3864
+ "locator": "KHR_texture_basisu Extension & GPU Memory"
3865
+ },
3866
+ {
3867
+ "source_id": "source.khronos-gltf-asset-auditor",
3868
+ "locator": "3D Commerce Asset Creation Guidelines — Texture Memory & Draw Calls"
3869
+ }
3870
+ ]
3871
+ }
3872
+ ],
3873
+ "source_refs": [
3874
+ {
3875
+ "source_id": "source.khronos-gltf-asset-auditor",
3876
+ "locator": "Khronos 3D Commerce Asset Creation Guidelines — Performance Budgets"
3877
+ },
3878
+ {
3879
+ "source_id": "source.threejs-color-and-gltf",
3880
+ "locator": "WebGLRenderer.info & Performance Optimization"
3881
+ }
3882
+ ],
3883
+ "related_ids": {
3884
+ "knowledge_ids": [
3885
+ "knowledge.lod-hierarchy-and-decimation-strategy",
3886
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
3887
+ "knowledge.normal-roughness-and-orm-channel-packing"
3888
+ ],
3889
+ "skill_ids": [
3890
+ "polycount-budget-checker",
3891
+ "mobile-glb-budget",
3892
+ "material-quality-checker",
3893
+ "acceptance-criteria-builder"
3894
+ ],
3895
+ "recipe_ids": [
3896
+ "recipe.web-ready-asset-optimization",
3897
+ "recipe.blender-to-glb-handoff",
3898
+ "recipe.scene-quality-inspection-and-correction"
3899
+ ]
3900
+ },
3901
+ "blender_versions": {
3902
+ "minimum": "3.0+",
3903
+ "tested_or_targeted": [
3904
+ "3.0+",
3905
+ "3.6 LTS",
3906
+ "4.2 LTS",
3907
+ "4.5.15 LTS",
3908
+ "5.1+",
3909
+ "5.2.3 LTS"
3910
+ ],
3911
+ "doc_checked_version": "5.2.3 LTS",
3912
+ "runtime_tested_version": null,
3913
+ "maintained_lts_versions": [
3914
+ "4.2 LTS",
3915
+ "4.5.15 LTS",
3916
+ "5.2.3 LTS"
3917
+ ],
3918
+ "legacy_compatibility_target": "3.6 LTS",
3919
+ "version_notes": "Viewport Statistics overlay and evaluated dependency graph triangle counts work across Blender 3.x-5.x. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
3920
+ },
3921
+ "evidence_status": "source-reviewed",
3922
+ "promoted_from_skill_refs": [
3923
+ "skills/polycount-budget-checker/references/instance-counting-rules.md",
3924
+ "skills/mobile-glb-budget/references/budget-tiers.md"
3925
+ ]
3926
+ },
3927
+ {
3928
+ "id": "knowledge.lod-hierarchy-and-decimation-strategy",
3929
+ "title": "Level of Detail (LOD0–LOD3) Hierarchy, Planar Dissolve, and UV-Safe Decimation",
3930
+ "domain": "optimization-lod-and-performance",
3931
+ "kind": "performance-budget-rule",
3932
+ "summary": "Rules for generating LOD0-LOD3 mesh cascades using Decimate (Planar) and UV-seam-preserving Decimate (Collapse) without destroying UV islands or silhouette fidelity.",
3933
+ "aliases": [
3934
+ "lod-cascade-decimation-strategy",
3935
+ "planar-dissolve-uv-safe-decimate",
3936
+ "multi-tier-lod-mesh-reduction"
3937
+ ],
3938
+ "intent_signals": [
3939
+ "generate LOD0 LOD1 LOD2 cascade with Blender Decimate modifier",
3940
+ "reduce mesh polygon count without destroying UV seams or baked normal maps",
3941
+ "use Planar dissolve and Vertex Group masks for safe mesh decimation"
3942
+ ],
3943
+ "applicability": {
3944
+ "when_to_apply": [
3945
+ "When reducing an over-budget mesh for desktop or mobile web delivery.",
3946
+ "When building multi-tier LOD cascades (LOD0, LOD1, LOD2) for distance-switched 3D scenes."
3947
+ ],
3948
+ "when_not_to_apply": [
3949
+ "When reducing an animated character face or limb joint that requires strict quad deformation loops (use quad retopology instead of triangulated Decimate Collapse)."
3950
+ ],
3951
+ "target_representations": [
3952
+ "polygon-game-mesh",
3953
+ "hard-surface-mesh",
3954
+ "glb-container"
3955
+ ]
3956
+ },
3957
+ "prerequisites": [
3958
+ "Mesh manifold hygiene (Merge by Distance), scale application (1,1,1), and UV seams / sharp edges are marked on LOD0."
3959
+ ],
3960
+ "principles": [
3961
+ "Decimate (Planar) with Delimit set to UV and Sharp dissolves redundant coplanar interior polygons losslessly without altering silhouettes or UV island boundaries.",
3962
+ "Progressive LOD cascades (LOD1 at 50%, LOD2 at 25%, LOD3 at 10%) must preserve UV seam borders so all LOD tiers share the exact same baked texture set without multiplying VRAM.",
3963
+ "Vertex Group masking inside Decimate (Collapse) protects high-attention hero details (logos, eyelets, rims) while concentrating reduction on flat or underside regions."
3964
+ ],
3965
+ "implementation_guidance": {
3966
+ "workflow_steps": [
3967
+ "Run Decimate -> Planar (Angle Limit 2-5 deg, Delimit: UV, Sharp, Material) first to strip coplanar grid subdivisions.",
3968
+ "Generate LOD1 (0.5 ratio) and LOD2 (0.25 ratio) using Decimate -> Collapse with UV seam preservation and a protective Vertex Group mask on hero features.",
3969
+ "Verify that all LOD meshes share the single LOD0 material/texture atlas and name nodes deterministically (Asset_LOD0, Asset_LOD1, Asset_LOD2)."
3970
+ ],
3971
+ "recommended_parameters": {
3972
+ "planar_decimate_angle_deg": 3,
3973
+ "lod1_collapse_ratio": 0.5,
3974
+ "lod2_collapse_ratio": 0.25,
3975
+ "lod3_collapse_ratio": 0.1
3976
+ },
3977
+ "blender_context": "Modifiers -> Generate -> Decimate (Planar / Collapse / Un-Subdivide); Object Data Properties -> Vertex Groups."
3978
+ },
3979
+ "observable_checks": [
3980
+ {
3981
+ "id": "check.lod-shared-uv-integrity",
3982
+ "check": "Assign the LOD0 baked normal/basecolor material to LOD1 and LOD2 and inspect UV seam borders.",
3983
+ "pass_condition": "All LOD tiers share the same material and display zero UV texture tearing along seams.",
3984
+ "fail_indicator": "UV seams collapse across island boundaries on LOD1/LOD2, causing visible texture shifts."
3985
+ },
3986
+ {
3987
+ "id": "check.lod-silhouette-overlay",
3988
+ "check": "Overlay LOD0 and LOD1 at expected switching distance in camera view.",
3989
+ "pass_condition": "Outer silhouette contour matches within 1-2 pixels at the transition distance.",
3990
+ "fail_indicator": "Aggressive decimation flattens curved rims, causing a jarring silhouette pop."
3991
+ }
3992
+ ],
3993
+ "creative_affordances": [
3994
+ "Vertex-group-masked decimation preserves 100% of the polygons on a sneaker's hero branding badge while reducing the rubber sole tread by 65%.",
3995
+ "Pairs directly with @react-three/drei <Detailed> component for automatic camera-distance LOD switching."
3996
+ ],
3997
+ "known_limits": [
3998
+ "glTF 2.0 core does not define a universal built-in LOD node; Three.js/R3F apps switch named *_LOD0/*_LOD1 nodes via THREE.LOD or <Detailed>."
3999
+ ],
4000
+ "claims": [
4001
+ {
4002
+ "id": "claim.decimate-planar-delimit-uv",
4003
+ "statement": "Blender's Decimate modifier in Planar mode supports Delimit flags for Normal, Material, Seam, Sharp, and UVs, preventing face dissolution across UV island boundaries.",
4004
+ "scope": "Blender 3.0+ through 5.1+.",
4005
+ "uncertainty_or_version_note": "Confirmed in Blender Manual — Decimate Modifier (Planar mode options).",
4006
+ "source_refs": [
4007
+ {
4008
+ "source_id": "source.blender-manual-modeling",
4009
+ "locator": "Modifiers -> Generate -> Decimate (Planar Delimit Options)"
4010
+ }
4011
+ ]
4012
+ }
4013
+ ],
4014
+ "source_refs": [
4015
+ {
4016
+ "source_id": "source.blender-manual-modeling",
4017
+ "locator": "Decimate Modifier (Collapse, Un-Subdivide, Planar)"
4018
+ },
4019
+ {
4020
+ "source_id": "source.khronos-gltf-asset-auditor",
4021
+ "locator": "Real-Time Asset Decimation & LOD Guidelines"
4022
+ }
4023
+ ],
4024
+ "related_ids": {
4025
+ "knowledge_ids": [
4026
+ "knowledge.triangle-draw-call-and-vram-budgets",
4027
+ "knowledge.high-to-low-normal-and-ao-baking",
4028
+ "knowledge.uv-seam-placement-and-texel-density"
4029
+ ],
4030
+ "skill_ids": [
4031
+ "polycount-budget-checker",
4032
+ "mobile-glb-budget",
4033
+ "r3f-component-plan",
4034
+ "scene-readiness"
4035
+ ],
4036
+ "recipe_ids": [
4037
+ "recipe.web-ready-asset-optimization",
4038
+ "recipe.hard-surface-prop"
4039
+ ]
4040
+ },
4041
+ "blender_versions": {
4042
+ "minimum": "3.0+",
4043
+ "tested_or_targeted": [
4044
+ "3.0+",
4045
+ "3.6 LTS",
4046
+ "4.2 LTS",
4047
+ "4.5.15 LTS",
4048
+ "5.1+",
4049
+ "5.2.3 LTS"
4050
+ ],
4051
+ "doc_checked_version": "5.2.3 LTS",
4052
+ "runtime_tested_version": null,
4053
+ "maintained_lts_versions": [
4054
+ "4.2 LTS",
4055
+ "4.5.15 LTS",
4056
+ "5.2.3 LTS"
4057
+ ],
4058
+ "legacy_compatibility_target": "3.6 LTS",
4059
+ "version_notes": "Decimate modifier modes (Collapse, Un-Subdivide, Planar) are stable across Blender 3.x-5.x. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
4060
+ },
4061
+ "evidence_status": "source-reviewed",
4062
+ "promoted_from_skill_refs": [
4063
+ "skills/polycount-budget-checker/references/instance-counting-rules.md",
4064
+ "skills/r3f-component-plan/references/component-shape-patterns.md"
4065
+ ]
4066
+ },
4067
+ {
4068
+ "id": "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression",
4069
+ "title": "KTX2 / Basis Universal Texture Compression vs. Draco and Meshopt Geometry Compression",
4070
+ "domain": "optimization-lod-and-performance",
4071
+ "kind": "performance-budget-rule",
4072
+ "summary": "Decision matrix for choosing between Draco (KHR_draco_mesh_compression), Meshopt (EXT_meshopt_compression), and KTX2 (KHR_texture_basisu) based on bottleneck type (network payload vs. GPU VRAM vs. CPU decode time).",
4073
+ "aliases": [
4074
+ "draco-vs-meshopt-vs-ktx2-compression",
4075
+ "khr-texture-basisu-uastc-etc1s",
4076
+ "gltf-geometry-and-texture-compression"
4077
+ ],
4078
+ "intent_signals": [
4079
+ "choose between Draco vs Meshopt vs KTX2 Basis Universal compression",
4080
+ "compress glb textures in GPU VRAM with KTX2 UASTC and ETC1S",
4081
+ "reduce glb file download size and configure Three.js DRACOLoader KTX2Loader"
4082
+ ],
4083
+ "applicability": {
4084
+ "when_to_apply": [
4085
+ "When optimizing .glb assets for web delivery, mobile browsers, or React Three Fiber.",
4086
+ "When deciding whether an asset's primary bottleneck is geometry buffer size or texture VRAM."
4087
+ ],
4088
+ "when_not_to_apply": [
4089
+ "When archiving uncompressed master interchange files for further editing in Blender or Substance.",
4090
+ "Do not apply lossy ETC1S compression to tangent-space Normal Maps (use UASTC for normal maps)."
4091
+ ],
4092
+ "target_representations": [
4093
+ "glb-container",
4094
+ "pbr-material-graph",
4095
+ "polygon-game-mesh"
4096
+ ]
4097
+ },
4098
+ "prerequisites": [
4099
+ "Baseline .glb asset is inspected to determine the byte share between mesh buffers and embedded image textures."
4100
+ ],
4101
+ "principles": [
4102
+ "Draco and Meshopt compress vertex/index geometry buffers over the network, whereas KTX2 (KHR_texture_basisu) compresses textures both over the network AND inside GPU VRAM (transcoding to BC7/ASTC/ETC2).",
4103
+ "KTX2 UASTC preserves high-frequency non-color vectors required for tangent-space Normal and ORM maps, whereas KTX2 ETC1S is suited for diffuse/albedo maps prioritizing small file size.",
4104
+ "Draco achieves the smallest network size for dense static meshes, while Meshopt decodes significantly faster in WASM and also compresses morph target and animation keyframe buffers."
4105
+ ],
4106
+ "implementation_guidance": {
4107
+ "workflow_steps": [
4108
+ "Inspect the .glb byte breakdown between geometry buffers and images before selecting compression tools.",
4109
+ "Enable Draco compression (14-bit position, 10-bit normal, 12-bit texcoord) for geometry-heavy static assets or use Meshopt for animated/morph assets.",
4110
+ "Encode Normal and ORM textures with KTX2 UASTC and diffuse textures with KTX2 ETC1S, and document required loader decoders (DRACOLoader, MeshoptDecoder, KTX2Loader) in the web handoff."
4111
+ ],
4112
+ "recommended_parameters": {
4113
+ "draco_position_quantization_bits": 14,
4114
+ "draco_normal_quantization_bits": 10,
4115
+ "draco_texcoord_quantization_bits": 12,
4116
+ "ktx2_normal_orm_mode": "UASTC"
4117
+ },
4118
+ "blender_context": "File -> Export -> glTF 2.0 -> Compression -> Draco; Post-export CLI optimization (gltf-transform / gltfpack) for KTX2 and Meshopt."
4119
+ },
4120
+ "observable_checks": [
4121
+ {
4122
+ "id": "check.payload-vs-vram-bottleneck-diagnosis",
4123
+ "check": "Inspect the byte share of buffers vs. images in the .glb export manifest.",
4124
+ "pass_condition": "Compression strategy matches the dominant bottleneck (KTX2/resize for image-heavy assets; Draco/Meshopt for geometry-heavy assets).",
4125
+ "fail_indicator": "Draco is enabled on a texture-bound asset while 4K uncompressed PNGs are left untouched."
4126
+ },
4127
+ {
4128
+ "id": "check.required-extensions-declared",
4129
+ "check": "Inspect extensionsRequired in the exported .glb (KHR_draco_mesh_compression, EXT_meshopt_compression, KHR_texture_basisu).",
4130
+ "pass_condition": "Every required glTF extension is documented in the handoff contract so the frontend configures the matching Three.js decoder.",
4131
+ "fail_indicator": "Compressed .glb fails to load at runtime because the frontend GLTFLoader lacks the required decoder."
4132
+ }
4133
+ ],
4134
+ "creative_affordances": [
4135
+ "Combining 2K KTX2 textures with Draco/Meshopt geometry compression routinely turns a 45 MB raw .glb into a 3.2 MB instant-loading web hero asset.",
4136
+ "gltf-transform CLI pipelines can automate KTX2 + Meshopt optimization after clean baseline .glb export from Blender."
4137
+ ],
4138
+ "known_limits": [
4139
+ "Blender's built-in glTF 2.0 exporter includes native Draco mesh compression, whereas KTX2 and Meshopt are applied via post-export tooling (gltf-transform or gltfpack)."
4140
+ ],
4141
+ "claims": [
4142
+ {
4143
+ "id": "claim.blender-native-draco-vs-external-ktx2-meshopt",
4144
+ "statement": "Blender's built-in glTF 2.0 add-on natively encodes KHR_draco_mesh_compression, while KHR_texture_basisu (KTX2) and EXT_meshopt_compression are standard Khronos extensions applied via post-export optimization tools.",
4145
+ "scope": "Blender 3.6 LTS, 4.2 LTS, 5.1+ glTF-Blender-IO and Khronos glTF 2.0 extensions.",
4146
+ "uncertainty_or_version_note": "Confirmed in Blender Manual glTF 2.0 Compression section and Khronos extension specs.",
4147
+ "source_refs": [
4148
+ {
4149
+ "source_id": "source.blender-manual-gltf-io",
4150
+ "locator": "glTF 2.0 — Mesh Compression (Draco)"
4151
+ },
4152
+ {
4153
+ "source_id": "source.khronos-ktx2-draco-meshopt",
4154
+ "locator": "KHR_draco_mesh_compression, EXT_meshopt_compression, KHR_texture_basisu"
4155
+ }
4156
+ ]
4157
+ }
4158
+ ],
4159
+ "source_refs": [
4160
+ {
4161
+ "source_id": "source.khronos-ktx2-draco-meshopt",
4162
+ "locator": "Compression Extensions (Draco, Meshopt, BasisU/KTX2)"
4163
+ },
4164
+ {
4165
+ "source_id": "source.khronos-gltf-asset-auditor",
4166
+ "locator": "3D Commerce Compression & Delivery Guidelines"
4167
+ }
4168
+ ],
4169
+ "related_ids": {
4170
+ "knowledge_ids": [
4171
+ "knowledge.triangle-draw-call-and-vram-budgets",
4172
+ "knowledge.normal-roughness-and-orm-channel-packing",
4173
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation"
4174
+ ],
4175
+ "skill_ids": [
4176
+ "mobile-glb-budget",
4177
+ "glb-web-handoff",
4178
+ "r3f-component-plan",
4179
+ "output-format-decision"
4180
+ ],
4181
+ "recipe_ids": [
4182
+ "recipe.web-ready-asset-optimization",
4183
+ "recipe.blender-to-glb-handoff"
4184
+ ]
4185
+ },
4186
+ "blender_versions": {
4187
+ "minimum": "3.0+",
4188
+ "tested_or_targeted": [
4189
+ "3.0+",
4190
+ "3.6 LTS",
4191
+ "4.2 LTS",
4192
+ "4.5.15 LTS",
4193
+ "5.1+",
4194
+ "5.2.3 LTS"
4195
+ ],
4196
+ "doc_checked_version": "5.2.3 LTS",
4197
+ "runtime_tested_version": null,
4198
+ "maintained_lts_versions": [
4199
+ "4.2 LTS",
4200
+ "4.5.15 LTS",
4201
+ "5.2.3 LTS"
4202
+ ],
4203
+ "legacy_compatibility_target": "3.6 LTS",
4204
+ "version_notes": "Native Draco encoder is bundled with Blender's official glTF 2.0 exporter across Blender 3.x-5.x. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
4205
+ },
4206
+ "evidence_status": "version-checked",
4207
+ "promoted_from_skill_refs": [
4208
+ "skills/mobile-glb-budget/references/budget-tiers.md",
4209
+ "skills/glb-web-handoff/references/artifact-status-language.md"
4210
+ ]
4211
+ },
4212
+ {
4213
+ "id": "knowledge.gltf-2-coordinate-system-and-transform-conventions",
4214
+ "title": "glTF 2.0 Right-Handed +Y Up Coordinate System and Blender Transform Conversion",
4215
+ "domain": "interchange-gltf-and-web",
4216
+ "kind": "interchange-export-rule",
4217
+ "summary": "Rules governing coordinate axis conversion between Blender (+Z Up, -Y Forward) and glTF 2.0 / Three.js (+Y Up, +Z Forward) along with TRS transform application requirements.",
4218
+ "aliases": [
4219
+ "gltf-yup-coordinate-conversion",
4220
+ "blender-to-threejs-axis-orientation",
4221
+ "gltf-trs-non-uniform-scale-shear"
4222
+ ],
4223
+ "intent_signals": [
4224
+ "convert Blender +Z up -Y forward coordinate system to glTF 2.0 +Y up +Z forward",
4225
+ "fix skewed rotated child hierarchy or backward facing model in Three.js",
4226
+ "apply rotation and scale before glb export for clean TRS matrices"
4227
+ ],
4228
+ "applicability": {
4229
+ "when_to_apply": [
4230
+ "Before exporting any asset or scene from Blender to .glb/.gltf for Three.js, React Three Fiber, Babylon.js, or PlayCanvas.",
4231
+ "When diagnosing why an exported model faces backward, lies on its side, or has skewed child hierarchy rotations in Three.js."
4232
+ ],
4233
+ "when_not_to_apply": [
4234
+ "When exchanging native .blend files directly between two Blender sessions."
4235
+ ],
4236
+ "target_representations": [
4237
+ "glb-container",
4238
+ "scene-hierarchy"
4239
+ ]
4240
+ },
4241
+ "prerequisites": [
4242
+ "All mesh objects have Ctrl+A -> Rotation & Scale applied (Scale = 1,1,1; Rotation = 0,0,0) in Blender prior to export, and +Y Up is enabled in the glTF exporter."
4243
+ ],
4244
+ "principles": [
4245
+ "glTF 2.0 mandates a right-handed coordinate system where +Y is up, +Z is forward, and 1 unit equals 1 meter; Blender's exporter maps Blender -Y to glTF +Z and Blender +Z to glTF +Y when +Y Up is enabled.",
4246
+ "glTF 2.0 nodes decompose transforms strictly into Translation, Rotation, and Scale (TRS) without shear; a rotated child under a non-uniformly scaled parent cannot be represented without skew distortion.",
4247
+ "Semantic PascalCase or snake_case node and material names ensure @react-three/drei useGLTF and gltfjsx destructuring remain stable across iterative re-exports."
4248
+ ],
4249
+ "implementation_guidance": {
4250
+ "workflow_steps": [
4251
+ "Orient hero assets in Blender so the front faces -Y (Front Orthographic View, Numpad 1) and the resting base sits at Z = 0.",
4252
+ "Apply Rotation & Scale (Ctrl+A) on all parent and child nodes so every exported node has uniform (1.0, 1.0, 1.0) scale.",
4253
+ "Keep +Y Up enabled (default) in the Blender glTF 2.0 exporter and assign clean semantic names to all meshes and materials."
4254
+ ],
4255
+ "recommended_parameters": {
4256
+ "gltf_export_yup": true,
4257
+ "gltf_unit_scale_meters": 1,
4258
+ "required_parent_scale": "1.0, 1.0, 1.0"
4259
+ },
4260
+ "blender_context": "3D Viewport -> Viewpoint -> Front (Numpad 1); Object -> Apply -> Rotation & Scale (Ctrl+A); File -> Export -> glTF 2.0 -> Transform -> +Y Up."
4261
+ },
4262
+ "observable_checks": [
4263
+ {
4264
+ "id": "check.front-orthographic-alignment",
4265
+ "check": "Inspect Front Orthographic view (Numpad 1, looking toward +Y) in Blender before export.",
4266
+ "pass_condition": "The front of the asset faces the viewer in Front Orthographic view and rests on Z = 0.",
4267
+ "fail_indicator": "The asset appears sideways or upside-down in Front Orthographic view."
4268
+ },
4269
+ {
4270
+ "id": "check.no-non-uniform-parent-scale",
4271
+ "check": "Inspect all parent nodes, Empties, and Armatures for non-uniform scale (sx != sy or sy != sz).",
4272
+ "pass_condition": "Every parent node has uniform (1.0, 1.0, 1.0) scale.",
4273
+ "fail_indicator": "Non-uniform parent scale induces shear distortion on rotated child nodes during glTF TRS decomposition."
4274
+ }
4275
+ ],
4276
+ "creative_affordances": [
4277
+ "Clean semantic node naming (Shoe_Upper, Sole_Mid, Lid_Pivot) turns npx gltfjsx model.glb into a self-documenting declarative React component.",
4278
+ "Consistent Y = 0 ground origin allows swapping multiple hero .glb products inside the same <Stage> wrapper without per-asset position offsets."
4279
+ ],
4280
+ "known_limits": [
4281
+ "Lights exported via KHR_lights_punctual orient along -Z in local glTF node space; the Blender exporter handles this conversion automatically when +Y Up is enabled."
4282
+ ],
4283
+ "claims": [
4284
+ {
4285
+ "id": "claim.gltf-2-coordinate-system-spec",
4286
+ "statement": "glTF 2.0 uses a right-handed coordinate system where +Y is up, +Z is forward, -X is right, and 1 unit equals 1 meter; node transforms must be decomposable into TRS (translation, rotation, scale) without skew/shear.",
4287
+ "scope": "Khronos glTF 2.0 core specification.",
4288
+ "uncertainty_or_version_note": "Confirmed in Khronos glTF 2.0 specification Section 3.4 and Section 3.2.",
4289
+ "source_refs": [
4290
+ {
4291
+ "source_id": "source.khronos-gltf-2-spec",
4292
+ "locator": "Section 3.4 — Coordinate System and Units; Section 3.2 — Nodes and TRS"
4293
+ }
4294
+ ]
4295
+ }
4296
+ ],
4297
+ "source_refs": [
4298
+ {
4299
+ "source_id": "source.khronos-gltf-2-spec",
4300
+ "locator": "Section 3.4 — Coordinate System and Units"
4301
+ },
4302
+ {
4303
+ "source_id": "source.blender-manual-gltf-io",
4304
+ "locator": "glTF 2.0 — Transform (+Y Up) & Hierarchy"
4305
+ }
4306
+ ],
4307
+ "related_ids": {
4308
+ "knowledge_ids": [
4309
+ "knowledge.mesh-manifold-normals-and-scale-hygiene",
4310
+ "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
4311
+ "knowledge.threejs-r3f-tone-mapping-and-environment-parity"
4312
+ ],
4313
+ "skill_ids": [
4314
+ "scene-readiness",
4315
+ "glb-web-handoff",
4316
+ "r3f-component-plan",
4317
+ "pre-handoff-verification"
4318
+ ],
4319
+ "recipe_ids": [
4320
+ "recipe.blender-to-glb-handoff",
4321
+ "recipe.scene-quality-inspection-and-correction",
4322
+ "recipe.product-hero-scene"
4323
+ ]
4324
+ },
4325
+ "blender_versions": {
4326
+ "minimum": "3.0+",
4327
+ "tested_or_targeted": [
4328
+ "3.0+",
4329
+ "3.6 LTS",
4330
+ "4.2 LTS",
4331
+ "4.5.15 LTS",
4332
+ "5.1+",
4333
+ "5.2.3 LTS"
4334
+ ],
4335
+ "doc_checked_version": "5.2.3 LTS",
4336
+ "runtime_tested_version": null,
4337
+ "maintained_lts_versions": [
4338
+ "4.2 LTS",
4339
+ "4.5.15 LTS",
4340
+ "5.2.3 LTS"
4341
+ ],
4342
+ "legacy_compatibility_target": "3.6 LTS",
4343
+ "version_notes": "Blender glTF 2.0 exporter defaults to +Y Up enabled across Blender 3.x-5.x. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
4344
+ },
4345
+ "evidence_status": "source-reviewed",
4346
+ "promoted_from_skill_refs": [
4347
+ "skills/scene-readiness/references/blocker-catalog.md",
4348
+ "skills/glb-web-handoff/references/artifact-status-language.md"
4349
+ ]
4350
+ },
4351
+ {
4352
+ "id": "knowledge.glb-binary-chunk-alignment-and-khronos-validation",
4353
+ "title": "GLB Binary Container Structure, Export Flags, and Khronos Validator Compliance",
4354
+ "domain": "interchange-gltf-and-web",
4355
+ "kind": "interchange-export-rule",
4356
+ "summary": "Specification rules for single-file .glb binary packaging (12-byte header, JSON chunk 0x4E4F534A, BIN chunk 0x004E4942), deterministic Blender export settings, and zero-error Khronos gltf-validator compliance.",
4357
+ "aliases": [
4358
+ "glb-binary-header-chunk-alignment",
4359
+ "khronos-gltf-validator-compliance",
4360
+ "blender-gltf-export-flags-and-collection-exporters"
4361
+ ],
4362
+ "intent_signals": [
4363
+ "validate glb binary header magic 0x46546C67 and 4-byte chunk alignment",
4364
+ "configure Blender glTF 2.0 export flags Apply Modifiers UVs Normals Tangents",
4365
+ "verify exported glb with Khronos gltf-validator zero errors before handoff"
4366
+ ],
4367
+ "applicability": {
4368
+ "when_to_apply": [
4369
+ "When configuring Blender's glTF 2.0 exporter for production .glb delivery.",
4370
+ "When auditing or validating an exported .glb artifact before marking it Produced or Verified."
4371
+ ],
4372
+ "when_not_to_apply": [
4373
+ "When intermediate multi-file .gltf + .bin inspection is temporarily needed for manual JSON diffs (convert to .glb for final delivery)."
4374
+ ],
4375
+ "target_representations": [
4376
+ "glb-container"
4377
+ ]
4378
+ },
4379
+ "prerequisites": [
4380
+ "Export scope is explicitly filtered (Selected Objects, Visible Objects, or Active Collection) so staging and helper meshes are excluded."
4381
+ ],
4382
+ "principles": [
4383
+ "A valid .glb file starts with a 12-byte little-endian header (magic 0x46546C67 'glTF', version 2, total byte length), followed by a 4-byte-aligned JSON chunk (0x4E4F534A) and BIN chunk (0x004E4942).",
4384
+ "Enabling Apply Modifiers, UVs, Normals, and Tangents during export ensures non-destructive Bevel/Weighted Normal stacks and MikkTSpace normal maps evaluate accurately in web engines.",
4385
+ "Under law-validation-before-done, an exported .glb cannot be marked Verified without confirming file existence, non-zero byte size, valid header, and zero schema errors."
4386
+ ],
4387
+ "implementation_guidance": {
4388
+ "workflow_steps": [
4389
+ "Filter export scope (Include -> Selected Objects / Active Collection) and disable Cameras and Punctual Lights for standalone web props.",
4390
+ "Select Format: glTF Binary (.glb) and enable Mesh -> Apply Modifiers, UVs, Normals, and Tangents (when normal maps are used).",
4391
+ "Run Khronos gltf-validator or inspect the exported binary header, node/material inventory, and accessor bounds before handoff."
4392
+ ],
4393
+ "recommended_parameters": {
4394
+ "export_format": "GLB",
4395
+ "export_apply_modifiers": true,
4396
+ "export_tangents": true,
4397
+ "export_cameras_and_lights": false
4398
+ },
4399
+ "blender_context": "File -> Export -> glTF 2.0 (.glb/.gltf); Collection Properties -> Exporters -> glTF 2.0 (Blender 4.2 LTS+)."
4400
+ },
4401
+ "observable_checks": [
4402
+ {
4403
+ "id": "check.glb-header-and-chunk-integrity",
4404
+ "check": "Verify the .glb exists on disk, has byte size > 0, starts with magic 0x46546C67 ('glTF') version 2, and passes Khronos gltf-validator with 0 errors.",
4405
+ "pass_condition": "Binary header is valid, numErrors === 0, and all bufferViews/images resolve internally.",
4406
+ "fail_indicator": "Missing file, truncated binary buffer, or ACCESSOR_NON_UNIT / URI_GLB_INVALID validator errors."
4407
+ },
4408
+ {
4409
+ "id": "check.no-leaked-helper-objects",
4410
+ "check": "Inspect the exported glTF nodes and meshes list against the intended export collection.",
4411
+ "pass_condition": "Only intended asset nodes are present; zero Cutter_*, HighPoly_*, or Backdrop_* helper meshes leaked into the .glb.",
4412
+ "fail_indicator": "Hidden boolean cutters or studio staging walls are present in the exported node tree."
4413
+ }
4414
+ ],
4415
+ "creative_affordances": [
4416
+ "Using Blender 4.2+ Collection Exporters (Collection Properties -> Exporters -> glTF 2.0) saves deterministic export presets per collection inside the .blend file.",
4417
+ "Single-file .glb packaging eliminates relative texture URI 404 errors when moving assets across CDN buckets."
4418
+ ],
4419
+ "known_limits": [
4420
+ "Vanilla Blender cannot apply modifiers during export on a mesh that simultaneously contains Shape Keys unless pre-processed."
4421
+ ],
4422
+ "claims": [
4423
+ {
4424
+ "id": "claim.glb-binary-format-layout",
4425
+ "statement": "A valid .glb file begins with a 12-byte header (magic = 0x46546C67, version = 2, length), followed by a 4-byte-aligned JSON chunk (0x4E4F534A) and an optional 4-byte-aligned BIN chunk (0x004E4942).",
4426
+ "scope": "Khronos glTF 2.0 specification Section 4 (Binary glTF Layout).",
4427
+ "uncertainty_or_version_note": "Exact normative binary layout in Khronos glTF 2.0 specification.",
4428
+ "source_refs": [
4429
+ {
4430
+ "source_id": "source.khronos-gltf-2-spec",
4431
+ "locator": "Section 4 — Binary glTF (.glb) Layout"
4432
+ }
4433
+ ]
4434
+ },
4435
+ {
4436
+ "id": "claim.collection-exporters-blender-42",
4437
+ "statement": "Blender 4.2 LTS introduced Collection Exporters (Collection Properties -> Exporters), allowing per-collection glTF 2.0 export settings and output paths to be persisted on the collection datablock.",
4438
+ "scope": "Blender 4.2 LTS and 5.1+.",
4439
+ "uncertainty_or_version_note": "Verified in Blender 4.2 LTS Manual — Collection Exporters.",
4440
+ "source_refs": [
4441
+ {
4442
+ "source_id": "source.blender-manual-gltf-io",
4443
+ "locator": "Blender 4.2 LTS — Collection Exporters & glTF 2.0"
4444
+ }
4445
+ ]
4446
+ }
4447
+ ],
4448
+ "source_refs": [
4449
+ {
4450
+ "source_id": "source.khronos-gltf-2-spec",
4451
+ "locator": "Section 4 — Binary glTF (.glb) Layout"
4452
+ },
4453
+ {
4454
+ "source_id": "source.khronos-gltf-asset-auditor",
4455
+ "locator": "glTF Validator & 3D Commerce QA Checks"
4456
+ },
4457
+ {
4458
+ "source_id": "source.blender-manual-gltf-io",
4459
+ "locator": "glTF 2.0 — Export Options & Collection Exporters"
4460
+ }
4461
+ ],
4462
+ "related_ids": {
4463
+ "knowledge_ids": [
4464
+ "knowledge.gltf-2-coordinate-system-and-transform-conventions",
4465
+ "knowledge.shader-node-gltf-export-portability",
4466
+ "knowledge.texture-resolution-ktx2-and-draco-meshopt-compression"
4467
+ ],
4468
+ "skill_ids": [
4469
+ "glb-web-handoff",
4470
+ "render-export-evidence",
4471
+ "pre-handoff-verification",
4472
+ "output-format-decision"
4473
+ ],
4474
+ "recipe_ids": [
4475
+ "recipe.blender-to-glb-handoff",
4476
+ "recipe.web-ready-asset-optimization",
4477
+ "recipe.product-hero-scene"
4478
+ ]
4479
+ },
4480
+ "blender_versions": {
4481
+ "minimum": "3.0+",
4482
+ "tested_or_targeted": [
4483
+ "3.0+",
4484
+ "3.6 LTS",
4485
+ "4.2 LTS",
4486
+ "4.5.15 LTS",
4487
+ "5.1+",
4488
+ "5.2.3 LTS"
4489
+ ],
4490
+ "doc_checked_version": "5.2.3 LTS",
4491
+ "runtime_tested_version": null,
4492
+ "maintained_lts_versions": [
4493
+ "4.2 LTS",
4494
+ "4.5.15 LTS",
4495
+ "5.2.3 LTS"
4496
+ ],
4497
+ "legacy_compatibility_target": "3.6 LTS",
4498
+ "version_notes": "Blender 4.2 LTS+ adds persistent Collection Exporters in the Properties panel. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
4499
+ },
4500
+ "evidence_status": "version-checked",
4501
+ "promoted_from_skill_refs": [
4502
+ "skills/glb-web-handoff/references/artifact-status-language.md",
4503
+ "skills/render-export-evidence/references/attempted-vs-failed-rubric.md",
4504
+ "skills/pre-handoff-verification/references/downgrade-rules.md"
4505
+ ]
4506
+ },
4507
+ {
4508
+ "id": "knowledge.threejs-r3f-tone-mapping-and-environment-parity",
4509
+ "title": "Three.js and React Three Fiber Tone Mapping, Color Management, and IBL Parity with Blender",
4510
+ "domain": "interchange-gltf-and-web",
4511
+ "kind": "interchange-export-rule",
4512
+ "summary": "Rules for matching Blender's AgX/Filmic PBR appearance in Three.js (r152+ / r162+) and React Three Fiber using linear working space, AgXToneMapping or NeutralToneMapping, and HDR Environment IBL.",
4513
+ "aliases": [
4514
+ "threejs-r3f-agx-tonemapping-parity",
4515
+ "metallic-looks-black-in-threejs-ibl",
4516
+ "threejs-color-management-srgb-linear"
4517
+ ],
4518
+ "intent_signals": [
4519
+ "fix metallic material looking black or dark in Three.js React Three Fiber",
4520
+ "match Blender AgX or Filmic tone mapping and color management in Three.js",
4521
+ "configure HDR Environment IBL PMREMGenerator and SRGBColorSpace in R3F"
4522
+ ],
4523
+ "applicability": {
4524
+ "when_to_apply": [
4525
+ "When handing off a .glb asset to a frontend Three.js or React Three Fiber (@react-three/fiber / @react-three/drei) developer.",
4526
+ "When diagnosing why a metallic or glossy .glb looks dark, washed out, or over-saturated in the browser compared to Blender."
4527
+ ],
4528
+ "when_not_to_apply": [
4529
+ "When rendering exclusively offline inside Blender without a web viewer target."
4530
+ ],
4531
+ "target_representations": [
4532
+ "glb-container",
4533
+ "pbr-material-graph",
4534
+ "lighting-camera-rig"
4535
+ ]
4536
+ },
4537
+ "prerequisites": [
4538
+ "Exported .glb uses spec-compliant PBR metallic-roughness materials and modern Three.js (r152+ / r162+) is targeted."
4539
+ ],
4540
+ "principles": [
4541
+ "Pure conductors (Metallic = 1.0) have zero diffuse reflection and appear completely black in Three.js unless an HDR environment map (scene.environment / <Environment />) supplies specular IBL.",
4542
+ "Three.js r152+ enables linear ColorManagement and SRGBColorSpace output by default, and r162+ provides native THREE.AgXToneMapping and Khronos THREE.NeutralToneMapping.",
4543
+ "BaseColor and Emissive textures must use THREE.SRGBColorSpace, whereas Normal, Roughness, Metallic, and ORM maps must remain in linear THREE.NoColorSpace."
4544
+ ],
4545
+ "implementation_guidance": {
4546
+ "workflow_steps": [
4547
+ "Configure an HDR environment map (<Environment preset=\"city\" /> or custom .hdr via PMREMGenerator) in the R3F/Three.js scene so metallic surfaces reflect full 360-degree lighting.",
4548
+ "Set renderer.toneMapping to THREE.AgXToneMapping (to match Blender 4.0+ AgX) or THREE.NeutralToneMapping (for color-accurate e-commerce products) with outputColorSpace = THREE.SRGBColorSpace.",
4549
+ "Verify that any manually loaded Normal/ORM textures keep THREE.NoColorSpace while BaseColor/Emissive textures use THREE.SRGBColorSpace."
4550
+ ],
4551
+ "recommended_parameters": {
4552
+ "threejs_tone_mapping": "THREE.AgXToneMapping",
4553
+ "threejs_output_color_space": "THREE.SRGBColorSpace",
4554
+ "r3f_environment_intensity": 1
4555
+ },
4556
+ "blender_context": "Render Properties -> Color Management (View Transform: AgX); World Properties -> Environment Texture (HDRI); Three.js Canvas / WebGLRenderer config."
4557
+ },
4558
+ "observable_checks": [
4559
+ {
4560
+ "id": "check.scene-environment-ibl-present",
4561
+ "check": "Verify the R3F/Three.js viewer specification includes scene.environment (<Environment /> or PMREMGenerator).",
4562
+ "pass_condition": "Metallic and glossy materials receive full 360-degree specular reflection from an HDR environment map.",
4563
+ "fail_indicator": "Metallic surfaces look black or flat grey because only punctual lights are active."
4564
+ },
4565
+ {
4566
+ "id": "check.tonemapping-and-colorspace-contract",
4567
+ "check": "Verify the handoff document specifies the target tone mapping (AgX, ACESFilmic, or Neutral) and SRGBColorSpace output.",
4568
+ "pass_condition": "Frontend viewer configuration matches the Blender look-dev view transform.",
4569
+ "fail_indicator": "Viewer defaults to NoToneMapping or mismatched exposure, blowing out specular highlights."
4570
+ }
4571
+ ],
4572
+ "creative_affordances": [
4573
+ "Using @react-three/drei <Lightformer> inside <Environment resolution={512}> recreates procedural studio softboxes directly in the browser's PMREM environment map.",
4574
+ "Khronos THREE.NeutralToneMapping guarantees that a sneaker or cosmetic bottle's brand color matches the CSS page palette."
4575
+ ],
4576
+ "known_limits": [
4577
+ "Real-time WebGL transmission (MeshPhysicalMaterial transmission: 1) approximates single-bounce refraction rather than Cycles multi-bounce path-traced caustics."
4578
+ ],
4579
+ "claims": [
4580
+ {
4581
+ "id": "claim.threejs-color-management-r152",
4582
+ "statement": "Three.js r152 enabled linear ColorManagement and SRGBColorSpace output by default, and subsequent releases added AgXToneMapping and Khronos NeutralToneMapping for PBR parity.",
4583
+ "scope": "Three.js r152+ / r162+ and @react-three/fiber v8+.",
4584
+ "uncertainty_or_version_note": "Confirmed in official Three.js Color Management documentation.",
4585
+ "source_refs": [
4586
+ {
4587
+ "source_id": "source.threejs-color-and-gltf",
4588
+ "locator": "Color Management, Tone Mapping & GLTFLoader"
4589
+ }
4590
+ ]
4591
+ }
4592
+ ],
4593
+ "source_refs": [
4594
+ {
4595
+ "source_id": "source.threejs-color-and-gltf",
4596
+ "locator": "Color Management, PMREMGenerator, MeshStandardMaterial & GLTFLoader"
4597
+ },
4598
+ {
4599
+ "source_id": "source.khronos-gltf-asset-auditor",
4600
+ "locator": "Khronos PBR Neutral Tone Mapper & Viewer Parity"
4601
+ }
4602
+ ],
4603
+ "related_ids": {
4604
+ "knowledge_ids": [
4605
+ "knowledge.agx-filmic-color-management-and-cycles-eevee",
4606
+ "knowledge.shader-node-gltf-export-portability",
4607
+ "knowledge.three-point-and-hdri-studio-lighting"
4608
+ ],
4609
+ "skill_ids": [
4610
+ "r3f-component-plan",
4611
+ "glb-web-handoff",
4612
+ "color-management-decision",
4613
+ "pre-handoff-verification"
4614
+ ],
4615
+ "recipe_ids": [
4616
+ "recipe.blender-to-glb-handoff",
4617
+ "recipe.product-hero-scene",
4618
+ "recipe.web-ready-asset-optimization"
4619
+ ]
4620
+ },
4621
+ "blender_versions": {
4622
+ "minimum": "3.0+",
4623
+ "tested_or_targeted": [
4624
+ "3.0+",
4625
+ "3.6 LTS",
4626
+ "4.2 LTS",
4627
+ "4.5.15 LTS",
4628
+ "5.1+",
4629
+ "5.2.3 LTS"
4630
+ ],
4631
+ "doc_checked_version": "5.2.3 LTS",
4632
+ "runtime_tested_version": null,
4633
+ "maintained_lts_versions": [
4634
+ "4.2 LTS",
4635
+ "4.5.15 LTS",
4636
+ "5.2.3 LTS"
4637
+ ],
4638
+ "legacy_compatibility_target": "3.6 LTS",
4639
+ "version_notes": "Blender 4.0+ AgX view transform pairs directly with THREE.AgXToneMapping in Three.js. Verified against Blender 4.5.15 LTS and 5.2.3 LTS documentation (live runtime: Not Run)."
4640
+ },
4641
+ "evidence_status": "version-checked",
4642
+ "promoted_from_skill_refs": [
4643
+ "skills/r3f-component-plan/references/component-shape-patterns.md",
4644
+ "skills/color-management-decision/references/look-comparison.md"
4645
+ ]
4646
+ }
4647
+ ]
4648
+ }