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

StaticBody2D

节点继承关系

继承链：Node → CanvasItem → Node2D → PhysicsBody2D → StaticBody2D

PhysicsBody2D

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

Node2D

类型	名称	说明
属性	Position	本地位置（相对于父节点）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（弧度）
属性	Scale	缩放比例
属性	Skew	倾斜角度（弧度）
方法	Rotate()	旋转指定弧度
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

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

定义

完全不动、永远不会移动的 2D 物理体——地板、墙壁、天花板就是它。

想象一下你房间里的地板和墙壁——它们就在那里，不会动。你可以在上面走，东西掉上去不会穿过去。StaticBody2D 就是游戏里的"地板和墙壁"。

因为它永远不会动，所以物理引擎在处理它的时候非常高效——不用每帧重新计算它的碰撞信息。

使用频率：★★★★ 维度专用常用——几乎每个游戏关卡都需要静态体。

节点用途

• 地板、地面
• 墙壁、围栏
• 平台（不会动的那些）
• 传送带（利用恒定速度属性）
• 任何永远固定不动的固体

使用场景

典型场景

• 平台关卡：地面、墙壁、天花板
• 传送带：利用 ConstantLinearVelocity 让站在上面的物体被带着走
• 旋转平台：利用 ConstantAngularVelocity 让物体旋转

不适用场景

• 会移动的平台 → 使用 AnimatableBody2D
• 需要自己控制移动的角色 → 使用 CharacterBody2D
• 只需检测进出的区域 → 使用 Area2D

常用节点搭配

搭配节点	用途	必需？
CollisionShape2D	定义碰撞边界	必需
CollisionPolygon2D	用多边形定义碰撞边界（替代方案）	二选一
Sprite2D	显示外观	推荐
TileMapLayer2D	用瓦片地图绘制地形	可选

典型节点树：

Ground (StaticBody2D)
├── CollisionShape2D
└── Sprite2D

生效必备素材/资源

资源	类型	说明
碰撞形状（如 RectangleShape2D）	Shape2D 资源	赋给 CollisionShape2D 子节点

节点属性与信号

物理属性

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

碰撞层

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

信号

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

常用方法

StaticBody2D 继承自 CollisionObject2D，常用方法如下：

方法	返回值	说明
GetCollisionExceptions()	GodotArray[Node]	获取碰撞例外列表
AddCollisionExceptionWith(body)	void	添加碰撞例外（两个物体不再碰撞）
RemoveCollisionExceptionWith(body)	void	移除碰撞例外

代码示例

C

using Godot;

/// <summary>
/// 传送带地板：站在上面的物体会被朝一个方向推动
/// 节点结构：ConveyorBelt (StaticBody2D) + Sprite2D + CollisionShape2D
/// </summary>
public partial class ConveyorBelt : StaticBody2D
{
    [Export] public float ExBeltSpeed = 200.0f;  // 传送带速度（像素/秒）
    [Export] public bool ExMoveRight = true;      // 传送方向

    public override void _Ready()
    {
        // 设置恒定线速度，让站在上面的物体被带动
        float direction = ExMoveRight ? 1f : -1f;
        ConstantLinearVelocity = new Vector2(direction * ExBeltSpeed, 0f);
    }

    // 在编辑器中可视化传送方向（可选）
    public override void _Draw()
    {
        float direction = ExMoveRight ? 1f : -1f;
        DrawLine(
            new Vector2(-20f, -5f),
            new Vector2(-20f + direction * 20f, -5f),
            new Color(1f, 0.5f, 0f),  // 橙色箭头
            2f
        );
    }
}

GDScript

# 传送带地板：站在上面的物体会被朝一个方向推动
# 节点结构：ConveyorBelt (StaticBody2D) + Sprite2D + CollisionShape2D
extends StaticBody2D

@export var belt_speed: float = 200.0   # 传送带速度（像素/秒）
@export var move_right: bool = true      # 传送方向

func _ready() -> void:
	# 设置恒定线速度，让站在上面的物体被带动
	var direction := 1.0 if move_right else -1.0
	constant_linear_velocity = Vector2(direction * belt_speed, 0.0)

# 在编辑器中可视化传送方向（可选）
func _draw() -> void:
	var direction := 1.0 if move_right else -1.0
	draw_line(
		Vector2(-20.0, -5.0),
		Vector2(-20.0 + direction * 20.0, -5.0),
		Color(1.0, 0.5, 0.0),  # 橙色箭头
		2.0
	)

什么是"恒定速度"？

ConstantLinearVelocity 可以让 StaticBody 表现得像传送带——虽然它自己不动，但站在上面的物体会被带着走。比如一个水平方向速度为 (200, 0) 的 StaticBody，任何落在它上面的角色或物体都会被向右带动。

必须搭配 CollisionShape！

StaticBody 本身只是一个"标记"，告诉物理引擎"这里有东西"。但你必须给它添加一个 CollisionShape2D 子节点来定义具体的碰撞形状。没有 CollisionShape 的 StaticBody 就像一个隐形人——其他物体看不到它，会直接穿过去。