Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

使用 CSG 设计关卡原型

CSG stands for Constructive Solid Geometry, and is a tool to combine basic shapes or custom meshes to create more complex shapes. In 3D modeling software, CSG is mostly known as "Boolean Operators".

Level prototyping is one of the main uses of CSG in Godot. This technique allows users to create the most common shapes by combining primitives. Interior environments can be created by using inverted primitives.


The CSG nodes in Godot are mainly intended for prototyping. There is no built-in support for UV mapping or editing 3D polygons (though extruded 2D polygons can be used with the CSGPolygon3D node).

如果你正在为一个项目寻找一个简单易用的关卡设计工具, 你可能会想使用 Qodot 来代替. 它可以让你使用 TrenchBroom 设计关卡, 并在Godot中导入它们.



You can check how to use CSG nodes to build various shapes (such as stairs or roads) using the Constructive Solid Geometry demo project.

CSG 节点简介

与 Godot 的其他功能一样,CSG 以节点的形式存在。这些是 CSG 节点:

../../_images/csg_nodes.png ../../_images/csg_mesh.png

CSG 工具功能

每个 CSG 节点都支持 3 种布尔运算:

  • 并集(Union):合并两个图元的几何体,删除交叉的几何体。

  • 交集(Intersection):只保留相交的几何体,其余的被删除。

  • 差集(Subtraction):从第一种形状中减去第二种形状,留下一个凹陷的形状。

../../_images/csg_operation_menu.png ../../_images/csg_operation.png


The CSGPolygon3D node extrude along a Polygon drawn in 2D (in X, Y coordinates) in the following ways:

  • Depth:(深度)挤出一定量。

  • Spin:(旋转)围绕原点旋转时挤出。

  • 路径(Path): 沿路径节点挤出. 此操作通常称为放样.

../../_images/csg_poly_mode.png ../../_images/csg_poly.png


The Path mode must be provided with a Path3D node to work. In the Path node, draw the path and the polygon in CSGPolygon3D will extrude along the given path.


Any mesh can be used for CSGMesh3D; the mesh can be modeled in other software and imported into Godot. Multiple materials are supported. There are some restrictions for geometry:

  • 它必须被关闭,

  • 它不能自我相交,

  • 它不能包含内部面,

  • 每条边都必须连接到另外两个面.



The CSGCombiner3D node is an empty shape used for organization. It will only combine children nodes.


Every CSG node will first process its children nodes and their operations: union, intersection, or subtraction, in tree order, and apply them to itself one after the other.


为了保证性能, 确保CSG几何体保持相对简单, 因为复杂的网格可能需要一段时间来处理. 如果将对象添加在一起(如桌子和房间对象), 请将它们创建为单独的CSG树. 强制在一棵树中添加太多对象最终会影响性能. 仅在实际需要的地方使用二进制操作.




正交视角下工作,在组合 CSG 形状时可以得到更好的视图。


  • 一个房间,

  • 一张床,

  • 一盏灯,

  • 一张桌子,

  • 一个书架.

Create a scene with a Node3D node as root node.


环境的默认光照在某些角度不能提供清晰的阴影。使用 3D 视图菜单中的显示重复绘制改变显示模式,或者添加一个 DirectionalLight 节点来帮助你清楚看到。


Create a CSGBox3D and name it room, enable Invert Faces and change the dimensions of your room.

../../_images/csg_room.png ../../_images/csg_room_invert.png

Next, create a CSGCombiner3D and name it desk.


  • Create 1 CSGBox3D children node in Union mode for the surface and adjust the dimensions.

  • Create 4 CSGBox3D children nodes in Union mode for the legs and adjust the dimensions.

调整它们的摆放位置, 就像一张办公桌.



CSG nodes inside a CSGCombiner3D will only process their operation within the combiner. Therefore, CSGCombiner3Ds are used to organize CSG nodes.

Create a CSGCombiner3D and name it bed.

Our bed consists of 3 parts: the bed, the mattress and a pillow. Create a CSGBox3D and adjust its dimension for the bed. Create another CSGBox3D and adjust its dimension for the mattress.


We will create another CSGCombiner3D named pillow as the child of bed. The scene tree should look like this:


We will combine 3 CSGSphere3D nodes in Union mode to form a pillow. Scale the Y axis of the spheres and enable Smooth Faces.


选择 pillow 节点,并将模式切换到 Subtraction;组合后的球体将在床垫上开一个洞。


Try to re-parent the pillow node to the root Node3D node; the hole will disappear.


This is to illustrate the effect of CSG processing order. Since the root node is not a CSG node, the CSGCombiner3D nodes are the end of the operations; this shows the use of CSGCombiner3D to organize the CSG scene.

观察效果后, 撤消重新选择父节点. 你搭建的床应如下所示:


Create a CSGCombiner3D and name it lamp.

A lamp consists of 3 parts: the stand, the pole and the lampshade. Create a CSGCylinder3D, enable the Cone option and make it the stand. Create another CSGCylinder3D and adjust the dimensions to use it as a pole.


We will use a CSGPolygon3D for the lampshade. Use the Spin mode for the CSGPolygon3D and draw a trapezoid while in Front View (numeric keypad 1); this shape will extrude around the origin and form the lampshade.

../../_images/csg_lamp_spin.png ../../_images/csg_lamp_polygon.png ../../_images/csg_lamp_extrude.png

调整3个部分的位置, 使其看起来像一盏灯.


Create a CSGCombiner3D and name it bookshelf.

We will use 3 CSGBox3D nodes for the bookshelf. Create a CSGBox3D and adjust its dimensions; this will be the size of the bookshelf.


Duplicate the CSGBox3D and shorten the dimensions of each axis and change the mode to Subtraction.

../../_images/csg_shelf_subtract.png ../../_images/csg_shelf_subtract_menu.png

You've almost built a shelf. Create one more CSGBox3D for dividing the shelf into two levels.


根据你的喜好将你的家具放在房间里, 你的场景应该是这样的:


你已经成功地用Godot中的CSG工具制作了一个房间关卡的原型.CSG工具可以用于设计各种类型的关卡, 如迷宫或城市;在设计游戏时探究它的局限性.


Godot's 标准 3D 材质与 ORM 3D 材质 supports triplanar mapping, which can be used to automatically apply a texture to arbitrary objects without distortion. This is handy when using CSG as Godot doesn't support editing UV maps on CSG nodes yet. Triplanar mapping is relatively slow, which usually restricts its usage to organic surfaces like terrain. Still, when prototyping, it can be used to quickly apply textures to CSG-based levels.


如果你需要一些原型的图片,Kenney做了一套 CC0授权的原型图片.


  • Applying it to a CSGCombiner3D node as a material override (Geometry > Material Override in the Inspector). This will affect its children automatically, but will make it impossible to change the material in individual children.

  • 将材质应用于单个节点( 材质 在(属性)检查器中). 这样, 每个CSG节点都可以有自己的外观. 减去CSG节点将把它们的材质应用到 "digging" 到的节点上.

To apply triplanar mapping to a CSG node, select it, go to the Inspector, click the [empty] text next to Material Override (or Material for individual CSG nodes). Choose New StandardMaterial3D. Click the newly created material's icon to edit it. Unfold the Albedo section and load a texture into the Texture property. Now, unfold the Uv1 section and check Triplanar. You can change the texture offset and scale on each axis by playing with the Scale and Offset properties just above. Higher values in the Scale property will cause the texture to repeat more often.


You can copy a StandardMaterial3D to reuse it across CSG nodes. To do so, click the dropdown arrow next to a material property in the Inspector and choose Copy. To paste it, select the node you'd like to apply the material onto, click the dropdown arrow next to its material property then choose Paste.

导出为 glTF

It can be useful to block out a level using CSG, then export it as a 3d model, to import into 3D modeling software. You can do this by selecting Scene > Export As... > glTF 2.0 Scene.