layout.json 场景布局契约
定义
layout.json 场景布局契约,是指在文本生成 3D 场景或关卡灰盒的流水线中,用一份 JSON 文件记录场景的真实摆放结果,并把它作为 Blender 与下游引擎之间的稳定交接格式。
它的核心作用不是表达创意意图,而是把已经生成、已经摆好的场景结构固定下来:下游工具不再猜测提示词、不再读取概念图、不再复用临时规划文件,而是严格按 layout.json 中记录的层级、物件实例、变换、光照和相机来装配场景。
在来源文章的 dsh-scene-skeleton-pipeline 语境中,layout.json 被明确描述为 Blender 和下游引擎之间的唯一契约。这里的“契约”意味着:Blender 负责按实际结果写出文件,下游如 Unity 适配器再按这份文件装配,双方以 layout.json 为准,而不是以概念图、提示词或模型生成的 plan 为准。
在本文档中的语境
来源文章《DSH新仓游戏美术资产场景骨架:一段文字,生成可编辑 3D 关卡灰盒》介绍的是一个 DSH(DeepSeek Harness) 生态中的编排插件 dsh-scene-skeleton-pipeline。该插件把 ComfyUI 出概念图、Blender 无头建模、可选 Unity 装配串成一条可复现的 文本到 3D 关卡灰盒生成流水线。
在这条流水线里,layout.json 位于 Blender 输出与下游引擎消费之间。插件会产出 scene.blend、scene.fbx、scene.glb 和 layout.json 等文件;其中 blend、fbx、glb 更偏向可打开或可导入的场景资产文件,layout.json 则承担“布局真相来源”的角色,用来告诉下游每个对象应该在什么层级、使用什么资产、放在什么位置、采用什么尺寸或变换,以及场景中有哪些光照和相机。
因此,layout.json 不是概念图。概念图只是 ComfyUI 输出的视觉参考,不能作为精确装配依据。layout.json 也不是提示词。提示词描述的是用户想要什么,但不包含最终实例化后的完整坐标与层级。layout.json 也不是 plan。plan 是模型规划阶段生成的“要摆什么”,而 layout.json 是 Blender 根据真实摆放结果写出的“实际摆成什么样”。
记录内容
来源文章明确指出,layout.json 记录以下几类信息:
- 层级分组:场景中的对象按结构分组。例如来源案例中,Blender 打开 scene.blend 后可看到 SceneSkeleton_Root 下挂着 Terrain、Buildings、Props 三组。
- 每个物件实例的资产信息:每个实例对应使用的资产或生成对象,供下游引擎按实例重新装配。
- 每个物件实例的位置、尺寸或变换:Blender 按实际摆放把每个物件的变换写入 layout.json。来源摘要还强调 plan 阶段会生成带 position 和 size 的布局计划,而 layout.json 则记录最终摆放后的真实变换结果。
- 光照:场景中的光照信息会进入 layout.json。来源案例中验收 Blender 场景时可看到方向光。
- 相机:场景中的相机信息也会进入 layout.json。来源案例中 Blender 验收时同样能看到相机。
这些信息使 layout.json 成为跨工具复现场景布局的依据。只要下游工具理解该文件约定,就可以按同一份布局生成相同或等价的场景结构。
plan 与 layout.json 的分工
layout.json 最容易与 plan 混淆。来源文章对二者的分工说得很明确:
- plan 是“要摆什么”:由模型规划生成,描述用户希望场景中出现哪些对象、对象大致如何布点,来源案例中的 plan_scene_layout 会生成带 position 和 size 的 plan,并经过结构和物理合理性校验。
- layout.json 是“实际摆成什么样”:由 Blender 在真实执行后写出,反映最终摆放结果,包括层级、光照、相机和每个物件的变换。
这一区分很重要。plan 属于规划输入或中间结果,即使它带有坐标和尺寸,也仍然是“计划”。实际执行过程中,Blender 才会根据规则、资产、参数化生成过程和真实摆放结果形成最终场景。下游引擎如果要复现结果,应读取 layout.json,而不是把 plan 当作最终布局。
来源文章还提到,plan_scene_layout 的校验失败时会列出逐条原因让模型重试,最多 3 次;三次仍不过会返回 ok: false,不会静默接受非法 plan。这说明 plan 阶段负责尽量生成合理方案,而 layout.json 阶段负责记录已经执行完成的真实结果。二者共同服务于流水线,但职责边界不同。
与 Blender 和下游引擎的交接机制
在来源语境中,Blender 是 layout.json 的主要写出方。插件通过 Blender 无头模式生成场景骨架后,会把实际摆放出的层级、光照、相机和每个物件实例的变换写入 layout.json。该文件可以原样回灌 Blender,用来复现 Blender 原生坐标下的布局结果。
下游引擎则把 layout.json 当作装配依据。来源文章明确提到,Unity 适配器会严格按这份 layout.json 装配。也就是说,Unity 侧不应再根据提示词重新推断场景,不应以概念图重新估算摆位,而应把 layout.json 当作唯一输入契约。
对于 Unity、Unreal、Godot 等多引擎复用场景,来源文章给出的用法是:同一份 layout.json 可以喂给不同引擎,按各自坐标系口径摆位即可,不需要每换一次引擎就手工重摆一遍。其他引擎也可以导入 scene.fbx 或 scene.glb,再按 layout.json 摆位。
坐标轴规则
layout.json 的坐标轴规则是该契约最关键的兼容点之一。来源文章给出的规则如下:
- 默认坐标系为 z-up:从 v0.1.0 起,layout.json 默认采用 z-up。
- 写入 Blender 原生坐标:layout.json 直接写 Blender 原生坐标,因此可以原样回灌 Blender 复现。
- Unity 直消费可配置为 y-up:如果要让 Unity 直接消费 layout.json,可以把 layoutAxis 配成 y-up。
- 适配器层可做坐标口径转换:来源图注说明,默认 z-up 写 Blender 原生值时,Unity 适配器会在适配器层转成 y-up。
因此,读取 layout.json 的程序不能假定所有文件都采用同一种坐标轴。正确做法是先读取文件中的 axis 字段,再根据 axis 的值决定如何解释坐标和变换。
版本兼容风险
来源文章特别强调,v0.1.0 起默认 z-up 是一个 breaking change。原因是早期版本只有 y-up 一种口径,而 v0.1.0 之后 layout.json 默认改为 z-up,并直接写 Blender 原生坐标。
下游解析 layout.json 时应遵守以下兼容策略:
- 先读取 axis 字段,按字段值解释坐标轴。
- 如果文件中存在 axis,应以 axis 为准。
- 如果历史文件没有 axis 字段,应按 y-up 处理。
- 如果 Unity 需要直接消费 layout.json,可通过 layoutAxis 配置为 y-up,以避免坐标口径不匹配。
这个兼容策略避免了新旧 layout.json 混用时出现物体朝向错误、上下轴颠倒、场景高度与地面方向解释错误等问题。来源没有展开具体错误表现,但从坐标轴 breaking change 的说明看,下游适配器必须把 axis 作为解析入口,而不是依赖默认假设。
细节与边界
layout.json 的边界可以从来源文章对插件产物和能力的说明中看出。
首先,layout.json 记录的是场景骨架的布局,不等于完整游戏关卡。来源文章说明该插件产出的是可继续编辑的灰盒场景,带层级、光照、相机和参数化物件,用于后续填入真实美术资产;它不是一个能直接玩的关卡。
其次,layout.json 不承担物理、导航和玩法逻辑。来源文章明确说插件不做碰撞体、刚体物理、导航和触发器,也不保证白盒可行走。这些内容即使未来可由其他系统补充,也不是该 layout.json 契约在来源中已经覆盖的范围。
再次,layout.json 不从概念图反推几何。来源文章说明插件不做图生 3D,也不会复刻概念图中的建筑形体。概念图是参考,Blender 生成的是参数化或程序化灰盒,layout.json 记录的是这些实际生成对象的布局。
最后,layout.json 不等于资产库本身。来源文章提到材质映射、几何模型库、PBR 贴图等增强项默认关闭,且贴图、材质映射、几何模型库都不自带资产;缺失时会自动回退为纯色或程序化图元。layout.json 可以记录实例与资产引用或摆放结果,但不会凭空提供缺失的真实资产。
来源案例:dsh-scene-skeleton-pipeline 中的用法
来源文章《DSH新仓游戏美术资产场景骨架:一段文字,生成可编辑 3D 关卡灰盒》给出了一个典型流程:用户输入“一座带台阶的日式庭院,四角有石柱”之类的描述,插件先可 dryRun 做依赖检查和节点编排,再可通过 plan_scene_layout 生成带坐标尺寸的 plan,最后真实执行 ComfyUI 出图和 Blender 无头建模,并可选运行 Unity 适配器。
真实执行后,产物落在 outputDir 下 jobs 的对应目录中:comfy 目录放概念图,blender 目录放 scene.blend 和 layout.json,开启贴图时还有 textures,开启 Unity 适配器时还有 unity 相关产物。验收时,Blender 可直接打开 scene.blend;Unity 可打开工程里装配好的场景;其他引擎可导入 scene.fbx 或 scene.glb,再按 layout.json 摆位。
该案例中的 layout.json 不是独立产品规范,也不是所有 3D 引擎通用的事实标准;它是在该插件流水线内被定义为 Blender 与下游引擎之间的唯一契约。其他项目复用这一概念时,应明确自身的字段定义、坐标轴约定、版本兼容规则和适配器行为。
相关条目
- dsh-scene-skeleton-pipeline
- DSH(DeepSeek Harness)
- 文本到 3D 关卡灰盒生成流水线
- LLM 场景布局规划校验
- Blender
- Unity
- Unreal
- Godot