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

VehicleWheel3D

节点继承关系

继承链：Node → Node3D → VehicleWheel3D

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

定义

VehicleBody3D 的车轮组件——必须作为 VehicleBody3D 的子节点使用。

VehicleWheel3D 不是独立的物理体，而是 VehicleBody3D 的"配件"。它模拟车轮与地面的接触、摩擦、悬挂等行为。你不需要自己写轮子的物理逻辑，只需要设置参数（轮子半径、悬挂高度等），VehicleBody3D 会自动处理轮子的物理。

使用频率：★★ 偶尔使用——仅在使用 VehicleBody3D 时需要。

节点用途

• 汽车、卡车的轮子
• 坦克的履带轮
• 任何轮式载具的轮子

使用场景

典型场景

• 四轮汽车：4 个 VehicleWheel3D 子节点
• 六轮卡车：6 个 VehicleWheel3D 子节点

不适用场景

• 不是轮式载具 → 不使用

常用节点搭配

搭配节点	用途	必需？
VehicleBody3D（作为父节点）	车身	必需

典型节点树：

Car (VehicleBody3D)
├── CollisionShape3D
├── MeshInstance3D
├── FLWheel (VehicleWheel3D)  ← 前左轮
├── FRWheel (VehicleWheel3D)  ← 前右轮
├── RLWheel (VehicleWheel3D)  ← 后左轮
└── RRWheel (VehicleWheel3D)  ← 后右轮

生效必备素材/资源

资源	类型	说明
轮子 3D 模型	.glb/.gltf 文件	可选，显示轮子外观

节点属性与信号

轮子参数

属性	类型	默认值	继承自	说明
WheelRadius	float	0.5	—	轮子半径（米）
WheelRestLength	float	0.15	—	悬挂静止长度（轮子中心到车身的高度）
WheelFriction	float	3.0	—	轮子摩擦力
SuspensionTravel	float	0.15	—	悬挂最大压缩距离
SuspensionStiffness	float	60.0	—	悬挂刚度（越大越硬）
SuspensionMaxForce	float	6000.0	—	悬挂最大支撑力
DampingCompression	float	0.4	—	悬挂压缩阻尼
DampingRelaxation	float	0.5	—	悬挂回弹阻尼

转向与驱动

属性	类型	默认值	继承自	说明
Steering	bool	false	—	此轮是否参与转向（前轮设为 true）
EngineTranstype	枚举	Undefined	—	驱动类型：Undefined（不驱动）/ Front（前驱）/ Rear（后驱）/ FourWheel（四驱）
UseAsSteering	bool	false	—	是否作为转向轮（旧版，建议用 Steering）
UseAsTraction	bool	false	—	是否作为驱动轮（旧版）

信号

信号	触发时机	继承自	说明
无常用自有信号	—	—	—

常用方法

方法	返回值	说明
GetRpm()	float	获取轮子转速（RPM）
GetSkidinfo()	float	获取打滑信息（0~1，1 = 完全抓地）
IsInContact()	bool	轮子是否接触地面

代码示例

C

using Godot;

/// <summary>
/// 汽车控制器（带车轮参数配置）
/// </summary>
public partial class AdvancedCar : VehicleBody3D
{
    private VehicleWheel3D[] _wheels;

    public override void _Ready()
    {
        // 获取所有车轮子节点
        _wheels = new VehicleWheel3D[]
        {
            GetNode<VehicleWheel3D>("FLWheel"),
            GetNode<VehicleWheel3D>("FRWheel"),
            GetNode<VehicleWheel3D>("RLWheel"),
            GetNode<VehicleWheel3D>("RRWheel"),
        };

        // 设置前轮参与转向
        _wheels[0].Steering = true;  // 前左
        _wheels[1].Steering = true;  // 前右
    }

    public override void _PhysicsProcess(double delta)
    {
        // 引擎和刹车
        float engineInput = Input.GetAxis("accelerate", "brake");
        EngineForce = engineInput * 200f;

        if (Input.IsActionPressed("handbrake"))
            Brake = 50f;
        else
            Brake = 0f;

        // 转向
        float steerInput = Input.GetAxis("steer_left", "steer_right");
        Steering = steerInput * 0.5f;

        // 调试：打印轮子转速
        GD.Print($"前左轮 RPM: {_wheels[0].GetRpm():F0}, 抓地: {_wheels[0].GetSkidinfo():F2}");
    }
}

GDScript

# 汽车控制器（带车轮参数配置）
extends VehicleBody3D

var wheels: Array[VehicleWheel3D]

func _ready() -> void:
	# 获取所有车轮子节点
	wheels = [
		$FLWheel,
		$FRWheel,
		$RLWheel,
		$RRWheel,
	]

	# 设置前轮参与转向
	wheels[0].steering = true  # 前左
	wheels[1].steering = true  # 前右

func _physics_process(_delta: float) -> void:
	# 引擎和刹车
	var engine_input := Input.get_axis("accelerate", "brake")
	engine_force = engine_input * 200.0

	if Input.is_action_pressed("handbrake"):
		brake = 50.0
	else:
		brake = 0.0

	# 转向
	var steer_input := Input.get_axis("steer_left", "steer_right")
	steering = steer_input * 0.5

	# 调试：打印轮子转速
	print("前左轮 RPM: %.0f, 抓地: %.2f" % [wheels[0].get_rpm(), wheels[0].get_skidinfo()])