W
AI-Wiki
ENTITY

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,并进行结构与物理合理性校验。

核心流水线

用户输入一段文字描述后,插件的主链路按以下顺序工作:

  1. 使用 ComfyUI 的文字生图工作流生成概念图。
  2. 使用 Blender 无头模式生成场景骨架。
  3. 写出 Blender 场景文件和布局契约文件。
  4. 可选运行 Unity 适配器,根据 layout.json 装配 Unity 场景。

真实执行时,核心输出包括:

  • scene.blend:可直接在 Blender 中打开和继续编辑的场景文件。
  • scene.fbx:供其他 3D 工具或游戏引擎导入的交换格式。
  • scene.glb:供其他工具链消费的 GLB 格式产物。
  • layout.json:记录实际场景层级、物件实例、变换、光照和相机等信息的布局契约。

启用 Unity 适配器时,还会生成 Unity 相关产物;未启用时,主流程仍可完成 Blender 与通用格式产出。

注册工具与加载行为

插件加载成功时,日志会显示以下工具或服务依次注册:

  1. service
  2. check_environment
  3. run_scene_pipeline
  4. plan_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 查看效果。流程包括:

  1. 先运行 run_scene_pipeline 的 dryRun 模式,只做依赖检查和节点编排。
  2. 再用 plan_scene_layout 对“东侧有喷泉,四角各一根石柱,北侧一段矮墙,西南一棵树”等描述做精确布点,并保存 plan。
  3. 最后用 run_scene_pipeline({ dryRun: false }) 真实执行,生成概念图、Blender 场景文件和 layout.json,可选生成 Unity 产物。
  4. 验收时,在 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 字段。

相关条目