在关卡原型设计这件事上，Godot 开发者长期处于“能用，但不够顺手”的状态。手动摆一堆StaticBody3D加BoxShape3D做灰盒，节点多、调整慢、试玩时要到处开碰撞；换到建模软件里画白模，又脱离了游戏引擎的实时运行环境。CSG Blockout 3.0 这个插件的价值，就在于把 Godot 原生 CSG 节点重新组织成一套完整可执行的关卡灰盒流程：画、量、试玩、冻结。这篇文章会从 CSG 的基本原理讲起，把四个阶段逐个拆开，最后用一个跳跃平台关卡原型把整条流程串起来。如果你正在用 Godot 做原型、做关卡通、做独立游戏第一版，这篇文章值得看完。
1. 这篇文章真正要解决的问题
很多 Godot 开发者在做关卡时，第一步就栽了跟头。
常见做法是打开建模软件，花半天雕一个房间白模，再导进 Godot 摆放、加碰撞、调材质。听起来很正规，但实际效率非常低。关卡设计最重要的是“跑起来感受空间”，而不是在建模软件里看静态渲染图。等你把模型导进引擎再跑起来，发现走廊太窄、台阶太陡、跳跃距离不够，又要回到建模软件去改，一来一回，一天时间就没了。
另一部分开发者会在 Godot 里手动拉盒子。做法是新建一批StaticBody3D，每个里面加MeshInstance3D和CollisionShape3D，然后复制、拖拽、对齐。这个方法确实在引擎内，但节点数量爆炸，调整一面墙的厚度可能要让好几个节点跟着动，改到后面根本分不清哪个盒子是哪面墙。
CSG Blockout 3.0 要解决的就是这个两难问题。它复用 Godot 原生 CSG 节点，让开发者直接在编辑器里“画”出关卡体块，随时测量尺度，直接进入游戏试玩角色移动，最终把灰盒“冻结”成普通网格节点，继续后续美术替换和生产流程。
什么样的人最该读这篇文章？
- 正在用 Godot 做独立游戏，项目还处在关卡探索阶段的开发者。
- 想在 Godot 里建立关卡原型标准流程的团队。
- 对 CSG 有好奇，但不知道它具体能干什么、跟手动摆盒子有什么区别的人。
- 从 Unity 或 Unreal 转过来，习惯使用灰盒工作流的开发者。
读完你至少能掌握一条清晰路径：如何在 30 分钟内搭出一个可以实际跑跳测试的灰盒关卡，再如何把它安全转成静态网格，避免 CSG 带来的性能和编辑问题。
2. Godot 中的 CSG 原理：不是“又一个盒子节点”
CSG 是 Constructive Solid Geometry 的缩写，中文通常叫“构造实体几何”。它是一套用基本体素做布尔运算，从而生成复杂几何形状的技术。平时大家接触更多可能是 3D 建模软件里的布尔修改器，比如用一个大方块减去一个小球体，得到一个有凹坑的方块。Godot 的 CSG 节点就是把这套能力搬进游戏引擎，并且保持了实时可编辑性。
2.1 基本体素节点有哪些
Godot 4 内置的 CSG 节点主要分布在CSGShape3D这个基类下：
| 节点类名 | 作用 | 常见场景 |
|---|---|---|
| CSGBox3D | 长方体 | 地面、墙体、台阶、房间框架 |
| CSGCylinder3D | 圆柱体 | 柱子、管道、圆形舞台 |
| CSGSphere3D | 球体 | 圆钝装饰、穹顶、障碍物 |
| CSGPolygon3D | 多边形沿路径挤出 | 不规则墙体、坡道、围栏 |
| CSGTorus3D | 圆环 | 环状结构、跑道边缘 |
| CSGMesh3D | 用一个现有网格做 CSG | 把复杂美术资源参与布尔运算 |
| CSGCombiner3D | 布尔合并器 | 组合多个 CSG 子节点 |
这些节点不像普通MeshInstance3D那样只负责显示，它们会实时计算最终几何体，而且节点之间可以通过父子关系或CSGCombiner3D完成并集、差集、交集运算。
2.2 CSG 与手动摆盒子有什么本质区别
手动摆盒子的本质是“一批独立网格和独立碰撞体组合出一个看似完整的空间”。每面墙、每段地板都是一个独立对象，修改一面墙的位置时，墙角不会自动延伸，也不会考虑相邻墙体。CSG 则不同，它始终维护一个“整体几何”的概念。
我们可以用一个类比来理解：
手动摆盒子，类似用积木搭房子，每块积木是独立的，你移动一块，倒塌与否取决于物理，不取决于逻辑；CSG 更像匠人削木头，你先把一整块木头切出外形，再挖出窗洞、抠出门洞，每一步都作用于同一个连续实体。
这个差异直接影响了灰盒效率。你可以先放一个大方块作为整个房间的体积，再用另一个小一些的长方体做差集，把门洞和窗洞“挖”出来。后续修改只需调整“挖空”用的那个盒子的位置和大小，门洞就会随之变化，不需要手动修墙的断面。
2.3 碰撞与物理
CSG 节点有一个use_collision属性，开启后运行时就会自动生成碰撞体。默认生成的碰撞是针对网格的三角形碰撞，相对粗糙但足够用于灰盒测试。进游戏之后可以直接让玩家角色在 CSG 地面上跑、跳、撞墙，不需要手动挂CollisionShape3D。
也正因为这一点，CSG 特别适合“试玩”这个环节。你画完一堵墙，开一下use_collision，立刻就能跑起来撞一下试试手感。
2.4 代价与边界
CSG 不是没有代价。它会在运行时实时重建网格，节点越多、布尔操作越深，开销越大。大量、复杂、嵌套的 CSG 场景直接在移动设备上跑，性能会很难看。这也是“冻结”这一步存在的根本原因：CSG 适合做原型，不适合做最终交付物。
CSG 的编辑器内计算性能也不理想。一个关卡里摆几百个 CSGBox3D，每个都参与布尔运算，编辑器会变得卡顿。实际操作中，块状图阶段控制在合理节点数量范围内，比如一百到两百个基础体素，体验还能接受。
小结论：Godot 的 CSG 不是建模软件的替代品，而是引擎内的快速空间表达工具。CSG Blockout 3.0 的意义，是让这套表达工具遵循标准的关卡原型工作流，而不是让开发者自己摸索。
3. CSG Blockout 3.0 的设计理念：画、量、试玩、冻结
单独使用 CSG 节点，虽然比手动摆盒子高效，但仍然缺少工作流约束。你很容易陷入一种状态：反复加盒子、改大小、拖动位置，却忘了检查“这个平台够不够高”“这扇门能不能走人”“角色在这个空间里有没有被压抑感”。
CSG Blockout 3.0 把 CSG 的原型能力归纳成四个明确的阶段：
| 阶段 | 中文语义 | 核心目标 | 对应操作 |
|---|---|---|---|
| Draw | 画 | 快速搭建空间体块 | 用 CSG 体素绘制墙体、地面、平台 |
| Measure | 量 | 确保尺度符合角色和能力 | 测量高度、宽度、间距 |
| Playtest | 试玩 | 验证空间体验和手感 | 在 CSG 关卡中运行角色，测试跳跃和移动 |
| Freeze | 冻结 | 把原型转成可交付的普通网格 | CSG 转 MeshInstance3D / StaticBody3D |
这四步不是一次性的，而是循环迭代的。画几堵墙，量一下比例，试跑两步发现问题，再回去画，再改尺寸，直到手感过关，最后冻结这个区域交给美术细化。
这个设计理念和关卡设计行业经典的“Blockout 工作流”一致。在 Unity 社区常用 Probuilder 做灰盒，Unreal 内置 BSP Brush，Godot 也有 CSG，但一直缺少像 CSG Blockout 这样的流程化整理。3.0 版本之所以值得关注，是因为它把散落在 Godot 原生功能里的能力整合成了一个可持续使用的关卡原型管线。
后面四个章节，我们就按这个顺序逐一展开。
4. 环境准备与前置条件
在进入实操之前，先把环境准备清楚。
CSG Blockout 3.0 是一个基于 Godot 编辑器的插件，因此你需要一个可用的 Godot 环境。本文演示以 Godot 4.x 为主，CSG 节点的接口在 Godot 4 里比较稳定统一；如果你还在用 Godot 3.x，CSG 的概念相通，但个别属性名和编辑器界面有差异，建议优先迁移或对照官方文档调整。
准备工作分三步：
- 安装 Godot 编辑器。从官方下载对应系统的标准版即可，无需额外 SDK，因为 CSG 和插件都属于引擎内置能力。
- 下载 CSG Blockout 3.0 插件包。将插件目录复制到项目的
addons/文件夹下。 - 在 Godot 编辑器中打开项目，进入“项目设置 - 插件”面板，启用 CSG Blockout 插件。
假设插件已经正确启用，你在编辑器顶部或侧边会看到插件对应的工具面板，核心是快捷绘制基本体、打开测量模式、切换试玩状态、执行冻结转换这几个入口。
如果插件面板没有出现，优先检查两件事：
- 插件是否确实位于
res://addons/下。 project.godot是否记录了对插件的启用配置，有时复制项目后插件列表没有自动加载，需要重新打开插件设置并启用。
4.1 项目目录结构建议
使用任何插件之前，先把项目结构整理好：
res:// ├── addons/ │ └── csg_blockout/ │ ├── plugin.cfg │ └── scripts/ ├── scenes/ │ ├── levels/ │ │ └── playground.tscn │ └── player/ │ └── test_player.tscn └── scripts/ └── tools/ └── bake_csg.gd把灰盒关卡放在scenes/levels/下，把测试玩家单独做成一个场景，方便在不同关卡里复用。冻结工具脚本放在scripts/tools/，它不属于运行时游戏逻辑，只作为编辑器辅助脚本存在。
5. 阶段一：画——快速搭建关卡空间
“画”是整个工作流里最直观的环节。但这里不能等同于随意摆方块，需要有策略地组织 CSG 节点。
5.1 创建 CSG 根节点
在开始绘制之前，先建立一个空节点作为 CSG 总根：
LevelRoot (Node3D) └── CSGRoot (CSGCombiner3D) └── ...之所以用CSGCombiner3D作为 CSG 根节点，而不是普通的Node3D，是因为组合器会把子节点的所有 CSG 体素统一进行布尔合并，最终只要根节点开启use_collision，整个灰盒关卡就都具备碰撞。这比让每个盒子自己处理碰撞更统一、更高效。
实际操作中，如果你的场景里包含多个彼此不相连的大区块，比如室内区和室外区，就应该建两个CSGCombiner3D根节点，分别管理各自的体素，避免在大型差集时产生不必要的跨区计算。
5.2 绘制地面的顺序
灰盒绘制时有一个常见的错误：先画了很多细碎的墙体，最后才发现地面没对齐。更稳的绘制顺序是“从大到小、从整体到局部”。
以一个小演示场景为例：
- 先画地面。添加
CSGBox3D，设置尺寸为20 × 1 × 20，作为一整个房间的基座。 - 再画外轮廓墙体。四面墙用四个细长
CSGBox3D，高度统一为4米。 - 然后挖门洞。添加一个比墙体略厚的
CSGBox3D，把它要挖除的位置摆在墙上，再在 CSG 节点属性里把操作类型设为“差集”。 - 最后加平台和障碍物，这些通常用
CSGBox3D、CSGCylinder3D单独摆放，不需要和墙体做布尔运算。
5.3 在编辑器中调整 CSG 布尔操作
在 Godot 编辑器里，选中任意CSGShape3D节点的子节点，检查器里有一个operation属性，可选值包括：
Union：并集。Intersection：交集。Subtraction：差集。
默认是并集。当你把一个小盒子放在一个地板节点内部时，如果操作类型是并集，它“溶入”地板；如果是差集，它会从地板上“挖掉”一块。
实际操作中，最常用的是差集来挖门洞、窗口和凹坑。比如要做一个坑洞，先建地面，再放一个很小的盒子作为“挖除模具”，将其operation设为Subtraction，调整位置和大小，就能实时看到地面上出现凹陷。
5.4 画阶段要守住的原则
绘制阶段的所有决策都要服务于一个目标：快速获得一个可以感受的空间，而不是一个好看的建筑模型。
几个实用原则：
- 模块化尺寸意识。所有体素尽量使用整数尺寸，比如墙体高度 4 米、地面厚度 1 米。后面测量时，整数倍数更容易判断。
- 尽量减少嵌套布尔。每个 CSG 子节点作为独立体素，能用位置调整解决的，就不要疯狂叠差集。
- 不急着做表面细分和装饰。灰盒只需要边界、体积、遮挡关系。
6. 阶段二：量——测量与校验空间尺度
关卡原型如果没有测量环节，很容易出现“看着没问题，跑起来全是问题”。
6.1 为什么要单独强调测量
人的眼睛在编辑器透视图里对空间大小的判断非常不可靠。稍有透视角度，就会把三米高的墙看成一米八，把一米五的通道看成宽敞走廊。因此关卡原型必须引入一组“参考尺度”和“测量动作”，用客观数值代替眼睛的主观猜测。
CSG Blockout 3.0 对这一阶段的支持，主要是把测量动作集中到一个可切换的模式里。进入测量模式后，你可以在场景里点选 CSG 节点，快速读取它的包围盒尺寸，以及两个节点之间的间隙距离。
6.2 建立你的“角色尺度表”
在灰盒设计之前，先设定角色的关键尺寸。下面是我的常用参考表，你可以按自己的玩法调整：
| 测量项 | 推荐值（以 1 米 = 100 单位为例） | 用途 |
|---|---|---|
| 角色高度 | 1.8 米 | 门洞至少应该 2.2 米 |
| 角色宽度 | 0.6 米 | 通道至少 1.2 米 |
| 最高可跨步 | 0.5 米 | 台阶高度不要超过 0.4 米 |
| 最大可跳过宽度 | 3 米 | 平台间距控制在 2.5 米以内 |
| 最大可跳上高度 | 1.2 米 | 高台不要超过 1 米 |
这些数据不需要精确复刻某个游戏，只要和你的角色控制器参数匹配即可。角色能跳 1.5 米高，那么关卡里 1.2 米的高台就是合理设计的；角色只能跳 1.0 米，你画个 1.5 米平台就是无效体验。
6.3 测量里的常见陷阱
- 内外尺寸混淆。量房间宽度时，如果从一面墙的中心量到另一面墙的中心，吃到墙体厚度后，实际可用宽度少了两面墙的厚度。因此要用碰撞表面的间隙来判断。
- 忽略角色体积。很多灰盒看着宽敞，但角色有体积半径，实际能挤过去的通道要减掉角色宽度。
- 只量平面不量垂直。平台间距、头顶障碍高度、跳跃最高点，都要单独量。
测量阶段结束了，下一步就是把这个空间真正跑起来。
7. 阶段三：试玩——用真实碰撞检验关卡
画得再漂亮，不如跑起来见分晓。
7.1 开启 CSG 碰撞
最简单的方式是选中 CSG 根节点，在检查器里勾选use_collision。这样整个 CSG 组合体在运行时都会自动生成碰撞体。
如果想让某个局部不参与碰撞，比如一个装饰性柱子，可以直接在该子节点上关闭use_collision，父级的开启不会强制所有子节点参与碰撞。
CSGRoot (CSGCombiner3D, use_collision = true) └── Floor (CSGBox3D) └── Wall (CSGBox3D) └── Pillar (CSGBox3D, use_collision = false)7.2 准备一个轻量测试玩家
不需要把正式游戏角色放进灰盒阶段。测试角色只要具备移动、跳跃和碰撞检测即可。一个最简测试玩家场景可以这样做：
场景结构：
TestPlayer (CharacterBody3D) ├── CollisionShape3D (CapsuleShape3D) └── MeshInstance3D (CapsuleMesh)脚本内容：
# 文件路径: scenes/player/test_player.gd extends CharacterBody3D @export var move_speed := 5.0 @export var sprint_speed := 8.0 @export var jump_velocity := 5.0 @export var gravity := 12.0 var _current_speed: float func _physics_process(delta: float) -> void: # 读取输入 var input_dir := Input.get_vector("move_left", "move_right", "move_forward", "move_back") var direction := (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized() # 移动速度：按住 Shift 冲刺 if Input.is_action_pressed("sprint"): _current_speed = sprint_speed else: _current_speed = move_speed # 水平速度 velocity.x = direction.x * _current_speed velocity.z = direction.z * _current_speed # 重力 if not is_on_floor(): velocity.y -= gravity * delta # 跳跃 if Input.is_action_just_pressed("jump") and is_on_floor(): velocity.y = jump_velocity move_and_slide()然后在项目设置里配置输入映射：
move_left、move_right、move_forward、move_back：方向键或 WASD。jump：空格。sprint：Shift。
7.3 试玩阶段重点观察什么
跑起来并不等于试玩完成。试玩阶段要有意识地检查：
- 通道宽度是否让角色移动不卡顿。
- 连续跳跃平台的距离和高度是否在角色能力范围内。
- 跳下去之后有没有足够空间缓冲和转向。
- 头顶有没有过低障碍导致视角压迫。
- 墙壁和地面的衔接处有没有露缝、卡角。
CSG 在试玩阶段的优势此刻完全体现出来：你可以在编辑器里直接拖放一个平台的位置，然后立刻再跑一遍测试手感，整个过程不需要重新导入模型。
试玩阶段发现问题，回到“画”和“量”阶段修改，重复循环。这是整个 Blockout 工作流里最核心的迭代节奏。
8. 阶段四：冻结——从 CSG 动态节点到静态网格
当灰盒最终确定，就可以考虑“冻结”了。
8.1 为什么要冻结
CSG 节点会在运行时反复计算几何体，这个性能开销随着场景复杂度直线上升。如果你把整个灰盒关卡原封不动放进正式游戏，几面墙可能没事，二三十面墙加上布尔运算就会明显吃帧，尤其是在低端手机上。
冻结的目标是：把 CSG 生成好的最终网格提取出来，放进普通的MeshInstance3D和StaticBody3D，彻底摆脱 CSG 的实时计算。
8.2 冻结脚本示例
下面这个脚本把 CSG 节点转换成一个StaticBody3D，然后挂上MeshInstance3D和CollisionShape3D，碰撞使用三角网格。
# 文件路径: scripts/tools/bake_csg.gd extends EditorScript ## 把 CSG 节点冻结为 StaticBody3D + MeshInstance3D ## 使用方法：在编辑器里选中 CSG 根节点，运行本脚本 func _run() -> void: var csg_root := get_scene().get_node("CSGRoot") if csg_root == null or not (csg_root is CSGShape3D): push_error("请选中一个 CSG 节点作为根节点") return _bake_csg(csg_root) func _bake_csg(csg: CSGShape3D) -> void: var meshes: Array = csg.get_meshes() if meshes.size() < 2: push_error("CSG 节点没有生成网格，请检查场景") return var render_mesh: ArrayMesh = meshes[0] var collision_mesh: ArrayMesh = meshes[1] var body := StaticBody3D.new() body.name = "Baked_" + csg.name body.position = csg.position body.rotation = csg.rotation body.scale = csg.scale var mesh_instance := MeshInstance3D.new() mesh_instance.mesh = render_mesh body.add_child(mesh_instance) var collision := CollisionShape3D.new() collision.shape = collision_mesh.create_trimesh_shape() body.add_child(collision) csg.get_parent().add_child(body) print("冻结完成：", body.name)这个脚本的用法：
- 把
bake_csg.gd挂在编辑器某个辅助脚本节点上，或者直接作为EditorScript运行。 - 打开目标关卡场景，选中 CSG 根节点。
- 运行脚本。
- 场景里会出现一个
Baked_CSGRoot的StaticBody3D。
8.3 冻结后如何处理原 CSG 节点
冻结完成后，建议先把 CSG 根节点隐藏或者移到单独图层，验证烘焙结果无误后再删除。
推荐顺序：
- 运行冻结脚本，生成
Baked节点。 - 隐藏原 CSGRoot，进游戏测试烘焙后的静态网格碰撞和渲染。
- 如果一切正常，再彻底删除原 CSGRoot。
不要一次性把原场景清空。如果烘焙后的网格有破面或碰撞不对，至少还能切回来继续调 CSG。
8.4 冻结不是一步到位
第一次冻结可能就暴露问题。破面、UV 错乱、碰撞网格粗糙、多边形数量过高，这些都会在正式替换美术资源之前显形。正因如此，冻结本身也是验证灰盒工作流是否规范的手段；如果在画 CSG 时经常出现自相交体素，冻结出来的网格大概率会有破面。
9. 完整示例：一个跳跃平台灰盒关卡
现在把前四阶段完整串起来，做一个小型跳跃平台灰盒关卡。
9.1 关卡目标
一个 10 米宽的坑洞，玩家需要经过三个漂浮平台跳到对岸高台，然后从高台跳到地面平台。整个关卡要在十分钟内画完，可以跑可以跳，最后冻结成静态网格。
9.2 场景结构
LevelRoot (Node3D) ├── CSGRoot (CSGCombiner3D) │ ├── Ground (CSGBox3D, 15 × 1 × 12) │ ├── StartPlatform (CSGBox3D, 3 × 0.5 × 2) │ ├── Platform1 (CSGBox3D, 2 × 0.5 × 2) │ ├── Platform2 (CSGBox3D, 2 × 0.5 × 2) │ ├── Platform3 (CSGBox3D, 2 × 0.5 × 2) │ ├── HighPlatform (CSGBox3D, 4 × 1 × 3) │ ├── WallBack (CSGBox3D, 15 × 4 × 0.5) │ └── WallSide (CSGBox3D, 0.5 × 4 × 12) └── TestPlayer (场景实例)9.3 关键参数设计
| 对象 | 尺寸 | 位置 | 说明 |
|---|---|---|---|
| Ground | 15×1×12 | (0, 0, 0) | 主地面 |
| StartPlatform | 3×0.5×2 | (-5, 0.75, 0) | 起点高台 |
| Platform1 | 2×0.5×2 | (-2, 1.2, 0) | 第一块浮台 |
| Platform2 | 2×0.5×2 | (1, 1.8, 0) | 第二块浮台 |
| Platform3 | 2×0.5×2 | (4, 2.4, 0) | 第三块浮台 |
| HighPlatform | 4×1×3 | (8, 3, 0) | 终点高台 |
这个布局假设测试玩家角色的跳跃能力大约能跳 1.2 米高、2.5 米远。第一块浮台到第二块浮台的间距约 2 米，属于合理挑战范围。
9.4 手动创建 CSG 节点的 GDScript 方式
如果不想在编辑器里逐个拖拽，也可以用脚本生成整块灰盒。下面是一个在编辑器内通过工具脚本生成 CSG 结构的示例：
# 文件路径: scripts/tools/create_jump_level.gd @tool extends EditorScript func _run() -> void: var root := Node3D.new() root.name = "LevelRoot" get_scene().add_child(root) var csg_root := CSGCombiner3D.new() csg_root.name = "CSGRoot" csg_root.use_collision = true root.add_child(csg_root) _add_box(csg_root, "Ground", Vector3(15, 1, 12), Vector3(0, 0, 0)) _add_box(csg_root, "StartPlatform", Vector3(3, 0.5, 2), Vector3(-5, 0.75, 0)) _add_box(csg_root, "Platform1", Vector3(2, 0.5, 2), Vector3(-2, 1.2, 0)) _add_box(csg_root, "Platform2", Vector3(2, 0.5, 2), Vector3(1, 1.8, 0)) _add_box(csg_root, "Platform3", Vector3(2, 0.5, 2), Vector3(4, 2.4, 0)) _add_box(csg_root, "HighPlatform", Vector3(4, 1, 3), Vector3(8, 3, 0)) _add_box(csg_root, "WallBack", Vector3(15, 4, 0.5), Vector3(0, 2, -5.75)) _add_box(csg_root, "WallSide", Vector3(0.5, 4, 12), Vector3(-7.25, 2, 0)) func _add_box(parent: Node, node_name: String, size: Vector3, pos: Vector3) -> void: var box := CSGBox3D.new() box.name = node_name box.size = size box.position = pos parent.add_child(box)在编辑器里运行这个脚本，整个灰盒关卡就自动生成了。之后再修改高度、间距，回到场景里直接拖动对应节点即可。
9.5 运行验证
- 按下 F6 运行当前关卡场景。
- 使用 WASD 移动，空格跳跃。
- 测试从起点依次跳到三块浮台，再跳上高台。
- 如果不满意，暂停回到编辑器，拖拽浮台的位置微调。
- 确定手感后，运行
bake_csg.gd冻结 CSG。
10. 常见问题与排查思路
10.1 CSG 节点在运行时看不到物体
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 游戏里 CSG 不显示 | CSG 根节点没有加入场景树 | 检查运行场景的根节点 | 重新挂载 CSGRoot |
| 有显示但没有碰撞 | use_collision未开启 | 选中 CSG 根节点看检查器 | 勾选use_collision |
| 布尔挖空不生效 | 子节点operation一直为Union | 选中挖除盒子看属性 | 将operation改为Subtraction |
| 网格出现破面 | 体素自相交或重叠 | 放大场景检查相交区域 | 调整体素位置避免自相交 |
10.2 冻结后碰撞不对
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 角色穿过冻结后的墙体 | 三角碰撞网格生成失败 | 检查 CollisionShape3D 是否有形状 | 重新运行冻结脚本 |
| 冻结后的网格出现缝隙 | CSG 根节点存在大量自相交 | 编辑器里旋转检查原 CSG | 先清理 CSG 体素再冻结 |
| 冻结后位置偏移 | 脚本未保留原节点 transform | 对比原节点和烘焙节点位置 | 确保复制 position/rotation/scale |
10.3 编辑器卡顿
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
| 拖动 CSG 节点时编辑器掉帧 | CSG 实时重算网格 | 观察节点数量和布尔嵌套深度 | 减少差集节点数量 |
| 大型关卡操作很卡 | 一个 CSG 根节点承载太多体素 | 检查节点层级 | 按区域拆分多个 CSGCombiner3D |
10.4 脚本运行失败
| 问题现象 | 可能原因 | 排查方式 | 解决方案 |
|---|---|---|---|
_run()没有输出 | 脚本没有正确继承 EditorScript | 检查脚本类型 | 继承EditorScript |
get_scene()返回空 | 脚本不在编辑器中运行 | 确认运行方式 | 在编辑器顶部的“场景”菜单执行工具脚本 |
get_meshes()大小异常 | CSG 节点未完全构建 | 先刷新 CSG 再冻结 | 选中 CSG 节点后强制更新，再运行脚本 |
11. 最佳实践与工程建议
11.1 命名规范
CSG 节点命名直接决定一个关卡的维护体验。推荐规则：
- 全部使用英文加语义前缀：
Floor_01、Wall_North、Platform_PitA。 - 同一个逻辑组挂在同一父节点下，不要一梭子平铺在根节点里。
- 差集用的“挖除模具”加
Cut_前缀，方便识别。
例如：
CSGRoot ├── Solid │ ├── Floor_01 │ └── Wall_North └── Cut ├── Cut_Doorway └── Cut_Window11.2 灰盒阶段不要引入美术资源
早期原型阶段，只用纯色材质，甚至可以用不同颜色区分地面、平台、危险区域。CSG 表面材质一变，眼睛就会开始关注光照和纹理，影响你对真实空间的判断。
建议建立一个简单的分色规范：
- 灰色：可站立地面和平台。
- 蓝色：可交互但非危险物体。
- 红色：危险区域、掉落坑洞。
- 半透明：只做参考的不可碰撞结构。
11.3 用版本控制管理 CSG 场景
CSG 节点保存在.tscn文件中，每次拖动都会修改文本内容。建议：
- 每次进入一个较大的修改阶段前，提交一次版本。
- 把灰盒关卡和正式美术关卡分开放在不同场景文件里，不要共用同一个场景。
- 冻结后的网格也保留一份快照版本，方便后续对比渲染差异。
11.4 冻结前先做性能拆解
不要等到整个关卡画完才冻结。更合理的做法是分区块冻结：
- 完成并验证 A 区灰盒。
- 冻结 A 区。
- 继续画 B 区，A 区保留为静态网格。
这样既避免大规模 CSG 运算，又能始终有一个可玩版本。
11.5 安全与授权边界
这里的“安全”主要指生产环境的安全。冻结脚本是一个编辑器工具脚本，它可能会修改你的场景文件。尤其是团队协作项目中，如果脚本没有经过验证就往共享场景里写，可能会污染其他人的工作区。建议：
- 冻结脚本在自己的分支或本地场景上验证。
- 先复制一份场景文件再做批量修改。
- 操作前确认当前场景有版本提交记录，保证可以回滚。
12. 总结与后续学习方向
CSG Blockout 3.0 本质上不是某个玄妙的黑科技，它是把 Godot 原生 CSG 能力组织成一套“画、量、试玩、冻结”的关卡原型工作流。这个过程的价值在于：你在进入美术制作之前，用最低成本获得了真实的空间感受度、可玩性和性能参考。
读完这篇文章，你应该已经能：
- 理解 Godot CSG 节点体系运行的基本原理。
- 在编辑器里快速建立灰盒关卡。
- 使用参考尺寸和测量意识检查关卡空间。
- 用轻量角色脚本直接试玩。
- 用工具脚本把 CSG 冻结成静态网格。
下一步值得深入的方向：
- 研究 CSGPolygon3D 的编辑模式，它特别适合绘制不规则墙体、坡道和非对称结构。
- 尝试把 CSG 灰盒与 Godot 的 NavigationRegion3D 结合，在原型阶段就验证 AI 寻路区域。
- 学习 ArrayMesh 手动烘焙流程，把冻结后的网格进一步优化，合并材质、清理网格数据和简化碰撞体。
- 如果你的项目最终面向移动端，建议从灰盒阶段就严格控制 CSG 节点数量，并在冻结后用 GPU 调试工具检查三角形数量。
做关卡原型最忌讳的，是把时间花在“看起来不错”而忽略“跑起来感受”。CSG Blockout 式的工作流，正是为了让“跑起来感受”这件事变得又快又直接。先画，再量，然后跑一跑，最后冻结住，这套节奏比什么都实用。
