最后同步日期：2026-04-15 | Godot 官方原文 — CSGShape3D 系列

CSGShape3D 系列

节点继承关系

继承链：Node → Node3D → GeometryInstance3D → CSGShape3D

GeometryInstance3D

类型	名称	说明
属性	MaterialOverride	材质覆盖
属性	CastShadow	阴影投射模式
属性	VisibilityRangeBegin	可见距离起始
属性	Transparency	透明度模式

Node3D

类型	名称	说明
属性	Position	本地位置（X / Y / Z）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（欧拉角，弧度）
属性	Scale	缩放比例
属性	TopLevel	是否脱离父节点的变换
方法	LookAt()	朝向目标点
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标
方法	RotateX/Y/Z()	绕指定轴旋转

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

CSG（Constructive Solid Geometry，构造实体几何）是一套用基础形状通过"布尔运算"搭建复杂 3D 模型的工具。就像用乐高积木搭房子——你可以用方块、球体、圆柱等基础形状拼合、挖洞、切割，组合出复杂的建筑模型。

CSGShape3D 系列包括：

• CSGBox3D：长方体
• CSGSphere3D：球体
• CSGCylinder3D：圆柱体
• CSGTorus3D：圆环体
• CSGPolygon3D：多边形挤出体（可做墙壁、地板等）
• CSGCombiner3D：组合器，把多个 CSG 形状合并为一个

使用频率：★★★ 一般常用——快速搭建关卡原型时很有用，最终产品通常替换为专业建模软件导出的模型。

节点用途

• 快速搭建关卡原型（白盒测试）
• 创建简单的建筑结构（房间、走廊、楼梯）
• 制作游戏中的简单道具
• 在编辑器中快速测试关卡布局

使用场景

典型场景

• 原型开发：快速搭建关卡布局，测试玩法
• 简单建筑：用方块拼出墙壁和地板
• 布尔运算：在方块上挖出门窗的洞

不适用场景

• 需要精细模型 → 使用专业建模软件（Blender 等）
• 2D 游戏 → 不支持

常用节点搭配

搭配节点	用途	必需？
CSGCombiner3D	组合多个 CSG 形状	可选
StaticBody3D	给 CSG 形状添加碰撞	推荐

典型节点树：

Room (CSGCombiner3D)
├── Floor (CSGBox3D)        ← 地板
├── Wall1 (CSGBox3D)        ← 墙壁1
├── Wall2 (CSGBox3D)        ← 墙壁2
└── DoorHole (CSGBox3D)     ← 门洞（operation = Subtraction，挖洞用）

生效必备素材/资源

资源	类型	说明
无特殊资源	—	CSG 节点自带基础形状，不需要额外导入模型

节点属性与信号

CSGShape3D 基础属性

属性	类型	默认值	继承自	说明
operation	枚举	Union	—	布尔运算类型：Union（合并）、Intersection（相交保留重叠部分）、Subtraction（相减，挖洞用）
use_collision	bool	false	—	是否自动生成碰撞形状

CSGBox3D 属性

属性	类型	默认值	继承自	说明
size	Vector3	(1, 1, 1)	—	长方体的长宽高

CSGSphere3D 属性

属性	类型	默认值	继承自	说明
radius	float	0.5	—	球的半径
radial_segments	int	32	—	径向分段数（越大越圆滑）
rings	int	16	—	环数（越大越圆滑）

CSGCylinder3D 属性

属性	类型	默认值	继承自	说明
radius	float	0.5	—	圆柱半径
height	float	2.0	—	圆柱高度
sides	int	32	—	侧面分段数
cone	bool	false	—	是否为圆锥（顶部半径为 0）

CSGCombiner3D

属性	类型	默认值	继承自	说明
operation	枚举	Union	—	子形状之间的默认运算类型

信号

信号	触发时机	继承自	说明
无自有信号	—	—	CSGShape3D 自身不发出信号

常用方法

方法	返回值	说明
GetMeshes()	MeshInstance3D[]	获取生成的网格
GetCollisionShapes()	Shape3D[]	获取生成的碰撞形状

代码示例

C

using Godot;

/// <summary>
/// 用 CSG 节点快速搭建一个简单的房间
/// 包含地板、四面墙壁和一个门洞
/// </summary>
public partial class SimpleRoom : CSGCombiner3D
{
    public override void _Ready()
    {
        // 地板
        var floor = new CSGBox3D
        {
            Size = new Vector3(10f, 0.2f, 10f),
            Position = new Vector3(0, -0.1f, 0)
        };
        AddChild(floor);

        // 后墙
        var backWall = new CSGBox3D
        {
            Size = new Vector3(10f, 3f, 0.2f),
            Position = new Vector3(0, 1.5f, -5f)
        };
        AddChild(backWall);

        // 左墙
        var leftWall = new CSGBox3D
        {
            Size = new Vector3(0.2f, 3f, 10f),
            Position = new Vector3(-5f, 1.5f, 0)
        };
        AddChild(leftWall);

        // 右墙
        var rightWall = new CSGBox3D
        {
            Size = new Vector3(0.2f, 3f, 10f),
            Position = new Vector3(5f, 1.5f, 0)
        };
        AddChild(rightWall);

        // 前墙（有门洞）
        var frontWall = new CSGBox3D
        {
            Size = new Vector3(10f, 3f, 0.2f),
            Position = new Vector3(0, 1.5f, 5f)
        };
        AddChild(frontWall);

        // 门洞（用 Subtraction 从前墙挖出一个方块）
        var doorHole = new CSGBox3D
        {
            Size = new Vector3(1.2f, 2.2f, 0.4f),
            Position = new Vector3(0, 1.1f, 5f),
            Operation = CSGShape3D.OperationType.Subtraction
        };
        AddChild(doorHole);
    }
}

GDScript

## 用 CSG 节点快速搭建一个简单的房间
## 包含地板、四面墙壁和一个门洞
extends CSGCombiner3D

func _ready():
    # 地板
    var floor := CSGBox3D.new()
    floor.size = Vector3(10.0, 0.2, 10.0)
    floor.position = Vector3(0, -0.1, 0)
    add_child(floor)

    # 后墙
    var back_wall := CSGBox3D.new()
    back_wall.size = Vector3(10.0, 3.0, 0.2)
    back_wall.position = Vector3(0, 1.5, -5.0)
    add_child(back_wall)

    # 左墙
    var left_wall := CSGBox3D.new()
    left_wall.size = Vector3(0.2, 3.0, 10.0)
    left_wall.position = Vector3(-5.0, 1.5, 0)
    add_child(left_wall)

    # 右墙
    var right_wall := CSGBox3D.new()
    right_wall.size = Vector3(0.2, 3.0, 10.0)
    right_wall.position = Vector3(5.0, 1.5, 0)
    add_child(right_wall)

    # 前墙（有门洞）
    var front_wall := CSGBox3D.new()
    front_wall.size = Vector3(10.0, 3.0, 0.2)
    front_wall.position = Vector3(0, 1.5, 5.0)
    add_child(front_wall)

    # 门洞（用 Subtraction 从前墙挖出一个方块）
    var door_hole := CSGBox3D.new()
    door_hole.size = Vector3(1.2, 2.2, 0.4)
    door_hole.position = Vector3(0, 1.1, 5.0)
    door_hole.operation = CSGShape3D.OPERATION_SUBTRACTION
    add_child(door_hole)

使用建议

• CSG 非常适合快速原型开发，但不适合做最终的游戏模型
• operation = Subtraction 可以在任何形状上挖洞（门、窗、地道等）
• 开启 use_collision 可以自动给 CSG 形状添加碰撞
• 正式开发时建议用 Blender 等建模软件制作精细模型，然后用 MeshInstance3D 替换
• CSGCombiner3D 可以把多个 CSG 形状组合为一个整体，方便管理