Index · Object → Node → Node3D → CollisionObject3D → PhysicsBody3D → CharacterBody3D

CharacterBody3D

A 3D physics body specialized for characters moved by script.

Class Description

CharacterBody3D is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection (move_and_slide() method) in addition to the general collision detection provided by PhysicsBody3D.move_and_collide(). This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters.

For game objects that don't require complex movement or collision detection, such as moving platforms, AnimatableBody3D is simpler to configure.

Properties

var floor_block_on_wall: bool = true

If true, the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them.

var floor_constant_speed: bool = false

If false (by default), the body will move faster on downward slopes and slower on upward slopes.

If true, the body will always move at the same speed on the ground no matter the slope. Note that you need to use floor_snap_length to stick along a downward slope at constant speed.

var floor_max_angle: float = 0.7853982

Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling move_and_slide(). The default value equals 45 degrees.

var floor_snap_length: float = 0.1

Sets a snapping distance. When set to a value different from 0.0, the body is kept attached to slopes when calling move_and_slide(). The snapping vector is determined by the given distance along the opposite direction of the up_direction.

As long as the snapping vector is in contact with the ground and the body moves against up_direction, the body will remain attached to the surface. Snapping is not applied if the body moves along up_direction, meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use apply_floor_snap().

var floor_stop_on_slope: bool = true

If true, the body will not slide on slopes when calling move_and_slide() when the body is standing still.

If false, the body will slide on floor's slopes when velocity applies a downward force.

var max_slides: int = 6

Maximum number of times the body can change direction before it stops when calling move_and_slide(). Must be greater than zero.

var motion_mode: CharacterBody3D.MotionMode = 0

Sets the motion mode which defines the behavior of move_and_slide().

var platform_floor_layers: int = 4294967295

Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the CharacterBody3D. By default, all floor bodies are detected and propagate their velocity.

var platform_on_leave: CharacterBody3D.PlatformOnLeave = 0

Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied.

var platform_wall_layers: int = 0

Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the CharacterBody3D. By default, all wall bodies are ignored.

var safe_margin: float = 0.001

Extra margin used for collision recovery when calling move_and_slide().

If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion.

A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors.

A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies.

var slide_on_ceiling: bool = true

If true, during a jump against the ceiling, the body will slide, if false it will be stopped and will fall vertically.

var up_direction: Vector3 = Vector3(0, 1, 0)

Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling move_and_slide(). Defaults to Vector3.UP. As the vector will be normalized it can't be equal to Vector3.ZERO, if you want all collisions to be reported as walls, consider using MOTION_MODE_FLOATING as motion_mode.

var velocity: Vector3 = Vector3(0, 0, 0)

Current velocity vector (typically meters per second), used and modified during calls to move_and_slide().

Note: A common mistake is setting this property to the desired velocity multiplied by delta, which produces a motion vector (typically in meters).

var wall_min_slide_angle: float = 0.2617994

Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. When motion_mode is MOTION_MODE_GROUNDED, it only affects movement if floor_block_on_wall is true.

Inherited from PhysicsBody3D (6)
Inherited from CollisionObject3D (6)
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 apply_floor_snap() -> void

Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when is_on_floor() returns true.

func get_floor_angle(up_direction: Vector3 = Vector3(0, 1, 0)) -> float

Returns the floor's collision angle at the last collision point according to up_direction, which is Vector3.UP by default. This value is always positive and only valid after calling move_and_slide() and when is_on_floor() returns true.

func get_floor_normal() -> Vector3

Returns the collision normal of the floor at the last collision point. Only valid after calling move_and_slide() and when is_on_floor() returns true.

Warning: The collision normal is not always the same as the surface normal.

func get_last_motion() -> Vector3

Returns the last motion applied to the CharacterBody3D during the last call to move_and_slide(). The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement.

func get_last_slide_collision() -> KinematicCollision3D

Returns a KinematicCollision3D if a collision occurred. The returned value contains information about the latest collision that occurred during the last call to move_and_slide(). Returns null if no collision occurred. See also get_slide_collision().

func get_platform_angular_velocity() -> Vector3

Returns the angular velocity of the platform at the last collision point. Only valid after calling move_and_slide().

func get_platform_velocity() -> Vector3

Returns the linear velocity of the platform at the last collision point. Only valid after calling move_and_slide().

func get_position_delta() -> Vector3

Returns the travel (position delta) that occurred during the last call to move_and_slide().

func get_real_velocity() -> Vector3

Returns the current real velocity since the last call to move_and_slide(). For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to velocity which returns the requested velocity.

func get_slide_collision(slide_idx: int) -> KinematicCollision3D

Returns a KinematicCollision3D, which contains information about a collision that occurred during the last call to move_and_slide(). Since the body can collide several times in a single call to move_and_slide(), you must specify the index of the collision in the range 0 to (get_slide_collision_count() - 1). See also get_last_slide_collision().

func get_slide_collision_count() -> int

Returns the number of times the body collided and changed direction during the last call to move_and_slide().

func get_wall_normal() -> Vector3

Returns the collision normal of the wall at the last collision point. Only valid after calling move_and_slide() and when is_on_wall() returns true.

Warning: The collision normal is not always the same as the surface normal.

func is_on_ceiling() -> bool

Returns true if the body collided with the ceiling on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "ceiling" or not.

func is_on_ceiling_only() -> bool

Returns true if the body collided only with the ceiling on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "ceiling" or not.

func is_on_floor() -> bool

Returns true if the body collided with the floor on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "floor" or not.

func is_on_floor_only() -> bool

Returns true if the body collided only with the floor on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "floor" or not.

func is_on_wall() -> bool

Returns true if the body collided with a wall on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "wall" or not.

func is_on_wall_only() -> bool

Returns true if the body collided only with a wall on the last call of move_and_slide(). Otherwise, returns false. The up_direction and floor_max_angle are used to determine whether a surface is "wall" or not.

func move_and_slide() -> bool

Moves the body based on velocity. If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a CharacterBody3D or RigidBody3D, it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes.

This method should be used in Node._physics_process() (or in a method called by Node._physics_process()), as it uses the physics step's delta value automatically in calculations. Otherwise, the simulation will run at an incorrect speed.

Modifies velocity if a slide collision occurred. To get the latest collision call get_last_slide_collision(), for more detailed information about collisions that occurred, use get_slide_collision().

When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions.

Returns true if the body collided, otherwise, returns false.

Inherited from PhysicsBody3D (8)
func get_collision_exceptions() -> PhysicsBody3D[]
func move_and_collide(motion: Vector3, test_only: bool = false, safe_margin: float = 0.001, recovery_as_collision: bool = false, max_collisions: int = 1) -> KinematicCollision3D
func set_axis_lock(axis: PhysicsServer3D.BodyAxis, lock: bool) -> void
func test_move(from: Transform3D, motion: Vector3, collision: KinematicCollision3D = null, safe_margin: float = 0.001, recovery_as_collision: bool = false, max_collisions: int = 1) -> bool
Inherited from CollisionObject3D (23)
func _input_event(camera: Camera3D, event: InputEvent, event_position: Vector3, normal: Vector3, shape_idx: int) -> void
func _mouse_enter() -> void
func _mouse_exit() -> void
func create_shape_owner(owner: Object) -> int
func get_collision_layer_value(layer_number: int) -> bool
func get_collision_mask_value(layer_number: int) -> bool
func get_rid() -> RID
func is_shape_owner_disabled(owner_id: int) -> bool
func remove_shape_owner(owner_id: int) -> void
func set_collision_layer_value(layer_number: int, value: bool) -> void
func set_collision_mask_value(layer_number: int, value: bool) -> void
func shape_find_owner(shape_index: int) -> int
func shape_owner_add_shape(owner_id: int, shape: Shape3D) -> void
func shape_owner_clear_shapes(owner_id: int) -> void
func shape_owner_get_owner(owner_id: int) -> Object
func shape_owner_get_shape(owner_id: int, shape_id: int) -> Shape3D
func shape_owner_get_shape_index(owner_id: int, shape_id: int) -> int
func shape_owner_remove_shape(owner_id: int, shape_id: int) -> void
func shape_owner_set_disabled(owner_id: int, disabled: bool) -> void
func shape_owner_set_transform(owner_id: int, transform: Transform3D) -> void
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 CollisionObject3D (3)
signal input_event(camera: Node, event: InputEvent, event_position: Vector3, normal: Vector3, shape_idx: int)
signal mouse_entered()
signal mouse_exited()
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)

Enums & Constants

enum MotionMode
MOTION_MODE_GROUNDED = 0

Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for grounded games like platformers.

MOTION_MODE_FLOATING = 1

Apply when there is no notion of floor or ceiling. All collisions will be reported as on_wall. In this mode, when you slide, the speed will always be constant. This mode is suitable for games without ground like space games.

enum PlatformOnLeave
PLATFORM_ON_LEAVE_ADD_VELOCITY = 0

Add the last platform velocity to the velocity when you leave a moving platform.

PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY = 1

Add the last platform velocity to the velocity when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down.

PLATFORM_ON_LEAVE_DO_NOTHING = 2

Do nothing when leaving a platform.