dsh-scene-skeleton-pipeline
定义与身份
dsh-scene-skeleton-pipeline 是 DSH(DeepSeek Harness) 生态里的游戏关卡美术资产场景骨架编排插件。它的作用是把一段文字描述转换成可继续编辑的 3D 关卡灰盒:先调用 ComfyUI 生成概念图,再调用 Blender 无头模式生成引擎无关的场景骨架,并可选运行 Unity 适配器完成装配。
它不是独立 CLI、桌面客户端或完整游戏编辑器。来源文章明确说明,它唯一的入口是通过 DSH 把插件挂起来;命令行和 Web 控制台属于 DSH 提供的入口,不是该插件自己的独立产品形态。
这里的“场景骨架”不是可直接游玩的完整关卡,而是一份用于继续制作的灰盒场景。它带有层级、光照、相机和参数化物件,目的是为后续填入真实美术资产提供骨架。
角色职责
dsh-scene-skeleton-pipeline 在流水线中承担“编排”职责:它自己不替代 ComfyUI、Blender 或 Unity 的能力,而是把这些工具按固定步骤串成可复现的资产生成流程。
它的核心职责包括:
- 接收用户的文字描述,作为场景主题、构图和布点意图的输入。
- 调用 ComfyUI 生成概念图,作为视觉参考。
- 调用 Blender 无头模式生成引擎无关的场景骨架。
- 输出 scene.blend、scene.fbx、scene.glb 和 layout.json 等产物。
- 在启用 Unity 适配器时,按 layout.json 把场景装配进 Unity。
- 通过 plan_scene_layout 支持文字精确布点,生成带 position 和 size 的布局 plan,并进行结构与物理合理性校验。
核心流水线
用户输入一段文字描述后,插件的主链路按以下顺序工作:
- 使用 ComfyUI 的文字生图工作流生成概念图。
- 使用 Blender 无头模式生成场景骨架。
- 写出 Blender 场景文件和布局契约文件。
- 可选运行 Unity 适配器,根据 layout.json 装配 Unity 场景。
真实执行时,核心输出包括:
scene.blend:可直接在 Blender 中打开和继续编辑的场景文件。scene.fbx:供其他 3D 工具或游戏引擎导入的交换格式。scene.glb:供其他工具链消费的 GLB 格式产物。layout.json:记录实际场景层级、物件实例、变换、光照和相机等信息的布局契约。
启用 Unity 适配器时,还会生成 Unity 相关产物;未启用时,主流程仍可完成 Blender 与通用格式产出。
注册工具与加载行为
插件加载成功时,日志会显示以下工具或服务依次注册:
servicecheck_environmentrun_scene_pipelineplan_scene_layout
这些注册项反映了插件的主要能力边界:先作为 DSH 插件服务被加载,再提供环境检查、流水线执行和布局规划工具。
check_environment
check_environment 的职责是探测 Blender、ComfyUI、Unity 三套环境是否存在,以及路径是否正确。
它只做探测,不启动软件。也就是说,它不会替用户安装、启动或停止 ComfyUI、Blender、Unity;它只用于判断依赖是否可用、路径是否配置正确,帮助用户在真实执行前发现环境问题。
来源文章把它归入“环境探测”能力:一个工具查清 Blender、ComfyUI、Unity 三件套在不在、路径对不对,并明确说明“只探测不启动软件”。
run_scene_pipeline
run_scene_pipeline 是执行主流水线的工具,既可以 dryRun 检查依赖和节点编排,也可以真实执行生成产物。
在 dryRun: true 时,它不会启动实际生产流程,而是用于检查依赖和节点编排。环境不满足时,节点会被标成 blocked,后续节点会被标成 skipped,产物只会是占位结果。这一模式适合在正式生成前确认机器环境是否齐全。
在 dryRun: false 时,它会真实执行流水线。来源示例中,真实执行会启动 ComfyUI 出图和 Blender 无头建模;启用 Unity 适配器时,还会运行 Unity 装配步骤。
真实执行的主要结果包括:
- ComfyUI 生成的概念图。
- Blender 生成的
scene.blend。 - 通用导出格式
scene.fbx与scene.glb。 - 描述实际摆放结果的
layout.json。 - 开启贴图时可能出现的
textures相关目录或产物。 - 开启 Unity 时生成的 Unity 相关产物。
来源文章给出的一个示例耗时是:ComfyUI 出图约 1 到 1.5 分钟,Blender 无头建模约 2 到 5 秒,开启 Unity 适配器后再约 10 到 15 秒。这些是来源案例中的运行经验,不应理解为所有机器和所有场景下的固定性能指标。
plan_scene_layout
plan_scene_layout 用于文字精确布点。它把用户描述转换成一份带 position 和 size 的布局 plan,使 Blender 能按坐标和尺寸摆放对象。
该工具不是简单接受模型输出,而会对 plan 进行结构和物理合理性校验。校验失败时,它会把失败原因反馈给模型并要求重试,最多重试 3 次。三次仍不通过时,会返回 ok: false,而不是静默接受非法 plan。
来源文章用“东侧有喷泉,四角各一根石柱,北侧一段矮墙,西南一棵树”作为示例描述,并设置 width: 24、depth: 20,说明该工具可以把自然语言布点需求落成明确的空间计划。
layout.json 场景布局契约
layout.json 是 dsh-scene-skeleton-pipeline 设计中的关键契约文件。来源文章称它是 Blender 与下游引擎之间的唯一契约。
它记录的是“实际摆成什么样”,而不是“想摆什么”。与此相对,plan 表示“要摆什么”。二者分工如下:
- plan:描述规划目标,即要放置哪些对象、期望的位置与尺寸。
layout.json:记录 Blender 实际生成后的层级、每个实例的资产与变换、光照和相机。
Unity 适配器会严格按 layout.json 装配。其他引擎也可以根据该文件读取实例、变换和层级信息,再按各自坐标系和资源导入方式复现布局。
坐标系与版本边界
来源文章说明,layout.json 默认使用 z-up,直接写 Blender 原生坐标,因此可以原样回灌 Blender 复现。
如果要给 Unity 直接消费,可以把 layoutAxis 配成 y-up。自 v0.1.0 起,默认 z-up 是一个 breaking change:早期版本只有 y-up 一种口径。下游自行解析 layout.json 时,必须先读取 axis 字段;没有该字段的历史文件应按 y-up 处理。
场景生成内容
默认 Blender 无头建模会使用 scenic-bpy 的声明式 spec 生成参数化庭院。来源文章列出的分组包括:
Terrain:地形相关内容。Buildings:建筑或结构体相关内容。Props:道具相关内容。
默认庭院元素包括地形、柱墙、拱门、树、长椅和灯柱。legacy 模式则生成固定体块加参考图平面。
验收时,用户可以直接打开 scene.blend,查看 SceneSkeleton_Root 下的 Terrain、Buildings、Props 三组,以及方向光和相机。
可选增强
来源文章列出三条可选增强,它们默认关闭,缺依赖时会自动降级,不阻断主流程:
- 材质映射:给 9 个语义材质 key 注入真实 PBR 贴图。
- 几何模型库:用 18 种资产库 type 的真实 GLB 模型替换程序化图元,减少积木感。
- PBR 贴图:使用 SuperPBR 为对象生成 albedo、normal、roughness、metallic。
这些增强不自带资产。贴图需要用户自备 CC0 资源,来源文章举例包括 Poly Haven、ambientCG;模型库也需要用户自备 GLB,来源文章举例包括 Kenney、Quaternius 的 CC0 包。缺少资源时,系统会回退到纯色或程序化图元,场景仍能跑通,但质感会下降。
安装与运行条件
dsh-scene-skeleton-pipeline 是源码插件,需要从本地目录装进 DSH profile。来源文章给出的安装方式是把本地源码目录添加到 profile,例如:
dsh plugin --profile web add /absolute/path/to/dsh-scene-skeleton-pipeline
dsh web
安装后,profile 的 package.json 会增加依赖,dsh.profile.bundles 中会自动登记该包,DSH 按包的 dsh.bundle.patch 自动挂载,不需要手工修改 YAML。
来源文章列出的环境要求包括:
- Node 不低于 20,因为插件使用 ESM 和
AbortSignal.timeout。 - DSH 需要支持 bundle;作者实测版本为 0.2.1-rc.5。
- ComfyUI 需要用户自己先运行,并监听
http://127.0.0.1:8188。 - Blender 使用 4.x 无头模式。
- Unity 为可选项,建议 Unity 2022.3 LTS 以上。
- 核心链路磁盘约 25 GB。
- 开启 PBR 贴图时,再增加约 6.4 GB。
核心链路只需要三项配置:
comfyUrl:ComfyUI 地址。blenderExe:Blender 可执行文件路径,留空时自动探测。outputDir:输出目录,留空时使用默认位置。
能力边界
dsh-scene-skeleton-pipeline 明确划定了不会做的事情:
- 不接管 ComfyUI 生命周期;ComfyUI 需要用户自行先运行。
- 不安装、启动或停止 ComfyUI、Blender、Unity。
- 不支持 ComfyUI 的 UI 格式工作流,只支持
POST /prompt的 API 格式工作流。 - 不做图生 3D。
- 不从概念图反推几何。
- 不生成碰撞体。
- 不生成刚体物理。
- 不生成导航。
- 不生成触发器。
- 不保证白盒可行走。
- 不涉及在线游戏自动化、内存读写或反作弊绕过。
因此,它更适合作为关卡原型和资产流水线的前置骨架生成器,而不是成品关卡生成器或运行时游戏系统。
应用场景
来源文章给出的适用场景主要集中在游戏关卡原型、美术资产流水线和多引擎布局复用:
- 关卡原型快速搭建:用一段描述生成可编辑灰盒,再逐步替换为真实资产。
- 多引擎复用布局:同一份
layout.json可供 Unity、Unreal、Godot 等下游工具按各自坐标系口径摆位。 - 自动化资产流水线:把概念图生成、建模和装配串成可复现流程。
- 教学与演示:用参数化庭院 spec 展示文字如何变成带层级的 3D 场景。
这些场景的共同前提是:用户接受先生成“骨架”而不是最终美术成品,并愿意在后续工具中继续编辑、替换和完善资产。
来源案例:今日头条文章中的运行示例
在《DSH新仓游戏美术资产场景骨架:一段文字,生成可编辑 3D 关卡灰盒》一文中,作者举例说明了从文字到可打开场景的流程。
示例目标是生成“一座带台阶的日式庭院,四角有石柱”,并进入 Unity 查看效果。流程包括:
- 先运行
run_scene_pipeline的 dryRun 模式,只做依赖检查和节点编排。 - 再用
plan_scene_layout对“东侧有喷泉,四角各一根石柱,北侧一段矮墙,西南一棵树”等描述做精确布点,并保存 plan。 - 最后用
run_scene_pipeline({ dryRun: false })真实执行,生成概念图、Blender 场景文件和layout.json,可选生成 Unity 产物。 - 验收时,在 Blender 打开
scene.blend,或在其他引擎导入scene.fbx、scene.glb并按layout.json摆位。
该来源还提到,作者在一个真实在用的 Unity 工程上完整跑过一次真实执行,job 状态为 done,原有资产 0 个被改写或删除,只新增了插件自己的 11 个文件。这个结论只代表该来源案例中的测试条件,不应扩大为所有项目都绝对不会受影响。
注意事项
- 它生成的是灰盒,不是成品美术关卡;程序化图元或声明式 spec 不能复刻概念图中的建筑形体。
- LLM 布点成功率不是 100%;即使有校验和最多 3 次重试,复杂描述仍可能产生不合理构图。
- 建议使用
savePath保存 plan,人工检查后再进入真实生成流程。 - ComfyUI 只支持 API 格式工作流,且来源文章说明默认面向单机
127.0.0.1默认端口,可通过comfyUrl修改。 - 核心链路约需 25 GB 磁盘;开启 PBR 贴图额外约需 6.4 GB。
- 8 GB 显存可以运行但会较慢;来源文章建议贴图分辨率使用 512,
textureObjects用main,不要用all,因为每个对象一次推理,48 对象场景可能要十几分钟。 - v0.1.0 起默认 z-up,下游解析
layout.json时应先读axis字段。