Index · Object → Node → Node3D → VehicleWheel3D

VehicleWheel3D

A 3D physics body for a VehicleBody3D that simulates the behavior of a wheel.

Class Description

A node used as a child of a VehicleBody3D parent to simulate the behavior of one of its wheels. This node also acts as a collider to detect if the wheel is touching a surface.

Note: This class has known issues and isn't designed to provide realistic 3D vehicle physics. If you want advanced vehicle physics, you may need to write your own physics integration using another PhysicsBody3D class.

Properties

var brake: float = 0.0

Slows down the wheel by applying a braking force. The wheel is only slowed down if it is in contact with a surface. The force you need to apply to adequately slow down your vehicle depends on the RigidBody3D.mass of the vehicle. For a vehicle with a mass set to 1000, try a value in the 25 - 30 range for hard braking.

var damping_compression: float = 0.83

The damping applied to the suspension spring when being compressed, meaning when the wheel is moving up relative to the vehicle. It is measured in Newton-seconds per millimeter (N⋅s/mm), or megagrams per second (Mg/s). This value should be between 0.0 (no damping) and 1.0, but may be more. A value of 0.0 means the car will keep bouncing as the spring keeps its energy. A good value for this is around 0.3 for a normal car, 0.5 for a race car.

var damping_relaxation: float = 0.88

The damping applied to the suspension spring when rebounding or extending, meaning when the wheel is moving down relative to the vehicle. It is measured in Newton-seconds per millimeter (N⋅s/mm), or megagrams per second (Mg/s). This value should be between 0.0 (no damping) and 1.0, but may be more. This value should always be slightly higher than the damping_compression property. For a damping_compression value of 0.3, try a relaxation value of 0.5.

var engine_force: float = 0.0

Accelerates the wheel by applying an engine force. The wheel is only sped up if it is in contact with a surface. The RigidBody3D.mass of the vehicle has an effect on the acceleration of the vehicle. For a vehicle with a mass set to 1000, try a value in the 25 - 50 range for acceleration.

Note: The simulation does not take the effect of gears into account, you will need to add logic for this if you wish to simulate gears.

A negative value will result in the wheel reversing.

var physics_interpolation_mode: Node.PhysicsInterpolationMode = 2
var steering: float = 0.0

The steering angle for the wheel, in radians. Setting this to a non-zero value will result in the vehicle turning when it's moving.

var suspension_max_force: float = 6000.0

The maximum force the spring can resist. This value should be higher than a quarter of the RigidBody3D.mass of the VehicleBody3D or the spring will not carry the weight of the vehicle. Good results are often obtained by a value that is about 3× to 4× this number.

var suspension_stiffness: float = 5.88

The stiffness of the suspension, measured in Newtons per millimeter (N/mm), or megagrams per second squared (Mg/s²). Use a value lower than 50 for an off-road car, a value between 50 and 100 for a race car and try something around 200 for something like a Formula 1 car.

var suspension_travel: float = 0.2

This is the distance the suspension can travel. As Godot units are equivalent to meters, keep this setting relatively low. Try a value between 0.1 and 0.3 depending on the type of car.

var use_as_steering: bool = false

If true, this wheel will be turned when the car steers. This value is used in conjunction with VehicleBody3D.steering and ignored if you are using the per-wheel steering value instead.

var use_as_traction: bool = false

If true, this wheel transfers engine force to the ground to propel the vehicle forward. This value is used in conjunction with VehicleBody3D.engine_force and ignored if you are using the per-wheel engine_force value instead.

var wheel_friction_slip: float = 10.5

This determines how much grip this wheel has. It is combined with the friction setting of the surface the wheel is in contact with. 0.0 means no grip, 1.0 is normal grip. For a drift car setup, try setting the grip of the rear wheels slightly lower than the front wheels, or use a lower value to simulate tire wear.

It's best to set this to 1.0 when starting out.

var wheel_radius: float = 0.5

The radius of the wheel in meters.

var wheel_rest_length: float = 0.15

This is the distance in meters the wheel is lowered from its origin point. Don't set this to 0.0 and move the wheel into position, instead move the origin point of your wheel (the gizmo in Godot) to the position the wheel will take when bottoming out, then use the rest length to move the wheel down to the position it should be in when the car is in rest.

var wheel_roll_influence: float = 0.1

This value affects the roll of your vehicle. If set to 1.0 for all wheels, your vehicle will resist body roll, while a value of 0.0 will be prone to rolling over.

Inherited from Node3D (17)
var position: Vector3 = Vector3(0, 0, 0)
var rotation: Vector3 = Vector3(0, 0, 0)
var rotation_order: EulerOrder = 2
var scale: Vector3 = Vector3(1, 1, 1)
var top_level: bool = false
var transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)
var visibility_parent: NodePath = NodePath("")
var visible: bool = true
Inherited from Node (14)
var owner: Node

Methods

func get_contact_body() -> Node3D

Returns the contacting body node if valid in the tree, as Node3D. At the moment, GridMap is not supported so the node will be always of type PhysicsBody3D.

Returns null if the wheel is not in contact with a surface, or the contact body is not a PhysicsBody3D.

func get_contact_normal() -> Vector3

Returns the normal of the suspension's collision in world space if the wheel is in contact. If the wheel isn't in contact with anything, returns a vector pointing directly along the suspension axis toward the vehicle in world space.

func get_contact_point() -> Vector3

Returns the point of the suspension's collision in world space if the wheel is in contact. If the wheel isn't in contact with anything, returns the maximum point of the wheel's ray cast in world space, which is defined by wheel_rest_length + wheel_radius.

func get_rpm() -> float

Returns the rotational speed of the wheel in revolutions per minute.

func get_skidinfo() -> float

Returns a value between 0.0 and 1.0 that indicates whether this wheel is skidding. 0.0 is skidding (the wheel has lost grip, e.g. icy terrain), 1.0 means not skidding (the wheel has full grip, e.g. dry asphalt road).

func is_in_contact() -> bool

Returns true if this wheel is in contact with a surface.

Inherited from Node3D (37)
func add_gizmo(gizmo: Node3DGizmo) -> void
func clear_gizmos() -> void
func force_update_transform() -> void
func get_gizmos() -> Node3DGizmo[]
func global_rotate(axis: Vector3, angle: float) -> void
func global_scale(scale: Vector3) -> void
func global_translate(offset: Vector3) -> void
func hide() -> void
func look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func orthonormalize() -> void
func rotate(axis: Vector3, angle: float) -> void
func rotate_object_local(axis: Vector3, angle: float) -> void
func rotate_x(angle: float) -> void
func rotate_y(angle: float) -> void
func rotate_z(angle: float) -> void
func scale_object_local(scale: Vector3) -> void
func set_disable_scale(disable: bool) -> void
func set_identity() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) -> void
func show() -> void
func to_global(local_point: Vector3) -> Vector3
func to_local(global_point: Vector3) -> Vector3
func translate(offset: Vector3) -> void
func translate_object_local(offset: Vector3) -> void
func update_gizmos() -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Node3D (1)
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)