mcpField
B
blender-scene-setup

blender-scene-setup

github.com/el4cteo创意与媒体569103 次安装2 周前更新
代码仓库

关于 blender-scene-setup

面向准备复用或导出资产的 Blender 美术人员的场景设置与清理技能，涵盖场景审计、组织、命名、比例、路径、资产库和清理规范。

主要功能

  1. 01审计场景问题并按需修复
  2. 02将资产整理到命名集合中
  3. 03统一命名、比例和原点规范
  4. 04管理链接与追加的数据
  5. 05准备资产库并清理文件

适用场景

  1. 01交付资产前检查场景
  2. 02统一集合结构和对象名称
  3. 03迁移或修复外部文件路径
  4. 04注册和维护资产库

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/el4cteo/blender-skills --skill blender-scene-setup

安装后在 Claude Code 中输入/blender-scene-setup确认已加载。

附带文件scripts/_bpyx.pyscripts/scene_audit.py

详细介绍

场景设置与规范

执行模型和验证步骤请参阅 blender-core。

流程

  1. 运行 scripts/scene_audit.py（仅对你拥有的文件添加 --fix purge scale paths）。该脚本会报告单位、未应用的缩放／负缩放、默认名称、场景根目录中的对象、缺失的图像、孤立数据和远离原点的对象。
  2. 设置单位：公制，单位比例 1.0，长度单位为米。即使使用 Unreal／Roblox，也保持 1.0，因为导出器会处理转换（参阅 blender-export-pipelines）。
  3. 按照下方布局构建集合。每个对象都必须放在一个命名集合中，不能放在场景根目录。
  4. 按照下方约定为所有内容命名。每次复制或合并后都要重命名，确保不留下 .001 后缀。
  5. 设置原点：道具设在底部中心（使其放置在地面上时 Z=0），角色设在双脚之间的世界原点处，门／铰链设在枢轴处。
  6. 对网格应用旋转和缩放（Ctrl+A）。除非资产应在原点导出，否则保留位置。
  7. 重新运行审计。当 issues 为空，或所有剩余问题均为有意保留且已说明时，即表示完成。

集合布局（每个 .blend 放一个资产，或每个资产放一个集合）

ASSET_Crate
├── Crate_high      # sculpt / subdiv source (exclude from export)
├── Crate_low       # game mesh(es) SM_Crate, SM_Crate_LOD1..
├── Crate_bake      # cages, bake helpers
├── Crate_collision # UCX_SM_Crate_00 (UE) / Crate-col (Godot)
└── Crate_ref       # reference images/blockout (hide_render)

使用 Collection Exporters（4.2+）为每个集合定义一次导出，然后通过一次调用重新导出：

with bpy.context.temp_override(collection=col):
    bpy.ops.collection.exporter_add(name="IO_FH_gltf2")
ex = col.exporters[-1]; ex.export_properties.filepath = "//export/SM_Crate.glb"
with bpy.context.temp_override(collection=col):
    bpy.ops.collection.exporter_export(index=len(col.exporters) - 1)

bpy.ops.wm.collection_export_all() 会重新运行每个集合导出器。

命名约定（Unreal 风格，所有引擎均接受）

类型模式示例
静态网格SM_<Name>[_LOD#]SM_Crate_LOD1
骨骼网格／绑定SK_<Name> / RIG_<Name>（骨架对象为 Armature 或 root）SK_Hero
材质M_<Name> / 实例 MI_<Name>M_Wood_Oak
纹理T_<Name>_<Suffix>：_BC 基础颜色，_N 法线，_ORM（R=AO G=Rough B=Metal），_E 自发光，_M 遮罩T_Crate_ORM
碰撞UE UCX_<Mesh>_##，Godot 后缀 -col/-colonly/-convcolonlyUCX_SM_Crate_00
骨骼／侧向.L/.R 后缀（Blender 镜像工具依赖此后缀）upper_arm.L
动作<Rig>_<Clip>Hero_Run
仅使用 ASCII，不加空格，并在整个项目中统一使用 PascalCase 或 snake_case。

真实世界尺寸参考（米）

门 2.0–2.1 × 0.9 · 天花板 2.4–2.7 · 桌子 0.75 · 椅面 0.45 · 柜台 0.9 · 楼梯高度 0.18／踏面 0.28 · 成年人 1.7–1.8（眼睛高度 1.6）· 汽车 4.5 × 1.8 × 1.5。Roblox：1 stud ≈ 0.28 m；默认角色约 5 stud 高。尺寸错误会影响物理、光照衰减、DOF 和纹素密度，因此先检查 ob.dimensions。

链接、追加、覆盖

  • 追加（libraries.load(link=False)）会创建本地副本。用于一次性复用。
  • 链接（link=True）为只读，会从源文件更新，也是流水线所用的方式。要编辑链接的集合，请添加库覆盖：ob.override_hierarchy_create(scene, view_layer, do_fully_editable=False)。只有可覆盖的属性（变换、姿态及任何标记为可覆盖的属性）可以更改。
  • 保持库路径为相对路径（//）。检查 bpy.data.libraries 中是否存在失效路径。

资产库

  • 标记：ob.asset_mark(); ob.asset_generate_preview()。元数据存放在 ob.asset_data 中（author、description、license、tags.new("wood")、catalog_id）。
  • 分类目录位于库根目录下的 blender_assets.cats.txt 中，每个分类目录占一行：UUID:Path/Sub:Simple Name。
  • 使用 prefs.filepaths.asset_libraries.new(name=..., directory=...) 注册库。5.2+：通过 use_remote_url + remote_url 使用远程库。在 5.2 中，active_asset_library 的索引偏移量为 2（“All”、“Essentials”）。
  • 每个库的导入方式：LINK、APPEND、APPEND_REUSE（默认；复用已追加的数据）。

清理规则

  • 发布前清除孤立数据块（bpy.data.orphans_purge(do_recursive=True)）。仅在有意为之时使用假用户。
  • 图像路径：使用相对路径（file.make_paths_relative），或打包资源以便单文件交付（file.pack_all）。
  • 切勿发布使用了尚未应用的对象级缩放的多用户网格数据。实例可以保留，但导出前必须烘焙缩放。
  • 使用 hide_render=True 隐藏辅助对象，并且将其排除在导出集合之外；仅在视口中隐藏还不够。
  • 交付文件中只保留一个活动场景。额外场景会让导出器混淆（use_active_scene）。

评论

支持 Markdown