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

StaticBody3D

节点继承关系

继承链：Node → Node3D → PhysicsBody3D → StaticBody3D

PhysicsBody3D

类型	名称	说明
方法	MoveAndCollide()	移动并检测碰撞
方法	TestMove()	测试移动是否会碰撞（不实际移动）

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()	获取父节点

定义

完全不动、永远不会移动的 3D 物理体——3D 世界里的地板、墙壁、天花板。

StaticBody3D 和 StaticBody2D 的原理完全一样，区别在于维度。3D 版本使用 Vector3 作为速度类型，支持凹多面体碰撞形状。

使用频率：★★★★ 维度专用常用——每个 3D 游戏关卡都需要。

节点用途

• 3D 地板、地面
• 3D 墙壁、建筑
• 3D 平台（不会动的那些）
• 3D 传送带（利用恒定速度属性）
• 3D 复杂地形（使用凹多面体碰撞形状）

使用场景

典型场景

• 3D 关卡地形：地面、墙壁、建筑外壳
• 传送带：利用 ConstantLinearVelocity 实现 3D 传送带
• 复杂地形：使用 ConcavePolygonShape3D 精确匹配地形网格

不适用场景

• 会移动的平台 → 使用 AnimatableBody3D
• 需要自己控制移动的角色 → 使用 CharacterBody3D

常用节点搭配

搭配节点	用途	必需？
CollisionShape3D	定义碰撞边界	必需
CollisionPolygon3D	用多边形定义碰撞边界	二选一
MeshInstance3D	显示 3D 模型	推荐
StaticBody3D（多个）	组合构成复杂地形	常用

典型节点树：

Ground (StaticBody3D)
├── CollisionShape3D
└── MeshInstance3D

生效必备素材/资源

资源	类型	说明
碰撞形状（如 BoxShape3D）	Shape3D 资源	赋给 CollisionShape3D 子节点

节点属性与信号

物理属性

属性	类型	默认值	继承自	说明
Bounce	float	0.0	—	弹性系数：0 = 不弹，1 = 完美弹跳
Friction	float	1.0	—	摩擦系数：0 = 像冰面一样滑
ConstantLinearVelocity	Vector3	(0, 0, 0)	—	恒定线速度（用于传送带）
ConstantAngularVelocity	Vector3	(0, 0, 0)	—	恒定角速度（用于旋转平台）
PhysicsMaterialOverride	PhysicsMaterial	null	—	自定义物理材质

碰撞层

属性	类型	默认值	继承自	说明
CollisionLayer	uint	1	CollisionObject3D	所在碰撞层
CollisionMask	uint	1	CollisionObject3D	检测哪些碰撞层

信号

信号	触发时机	继承自	说明
无常用自有信号	—	—	StaticBody 通常不需要信号

常用方法

方法	返回值	说明
GetCollisionExceptions()	GodotArray[Node]	获取碰撞例外列表
AddCollisionExceptionWith(body)	void	添加碰撞例外
RemoveCollisionExceptionWith(body)	void	移除碰撞例外

代码示例

C

using Godot;

/// <summary>
/// 3D 传送带：站在上面的物体会被朝一个方向推动
/// 节点结构：ConveyorBelt3D (StaticBody3D) + MeshInstance3D + CollisionShape3D
/// </summary>
public partial class ConveyorBelt3D : StaticBody3D
{
    [Export] public float ExBeltSpeed = 3.0f;  // 传送带速度（米/秒）
    [Export] public Vector3 ExMoveDirection = Vector3.Forward;  // 传送方向

    public override void _Ready()
    {
        // 设置恒定线速度
        ConstantLinearVelocity = ExMoveDirection * ExBeltSpeed;
    }
}

GDScript

# 3D 传送带：站在上面的物体会被朝一个方向推动
# 节点结构：ConveyorBelt3D (StaticBody3D) + MeshInstance3D + CollisionShape3D
extends StaticBody3D

@export var belt_speed: float = 3.0              # 传送带速度（米/秒）
@export var move_direction: Vector3 = Vector3.FORWARD  # 传送方向

func _ready() -> void:
	# 设置恒定线速度
	constant_linear_velocity = move_direction * belt_speed

3D 静态体可以使用凹多面体！

3D 版本的 StaticBody 支持 ConcavePolygonShape3D（凹多面体碰撞形状），这意味着你可以直接用 3D 模型的网格（Mesh）来生成精确的碰撞形状。这是 3D 静态体独有的优势——2D 版本的 StaticBody 不支持凹多边形碰撞形状。