Index · Object → Node → CanvasItem → Node2D → CollisionObject2D → PhysicsBody2D → CharacterBody2D

CharacterBody2D

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

Class Description

CharacterBody2D 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 PhysicsBody2D.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, AnimatableBody2D 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 = 1.0

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 = 4

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: CharacterBody2D.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 CharacterBody2D. By default, all floor bodies are detected and propagate their velocity.

var platform_on_leave: CharacterBody2D.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 CharacterBody2D. By default, all wall bodies are ignored.

var safe_margin: float = 0.08

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: Vector2 = Vector2(0, -1)

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 Vector2.UP. As the vector will be normalized it can't be equal to Vector2.ZERO, if you want all collisions to be reported as walls, consider using MOTION_MODE_FLOATING as motion_mode.

var velocity: Vector2 = Vector2(0, 0)

Current velocity vector in pixels 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 in pixels.

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. This property only affects movement when motion_mode is MOTION_MODE_FLOATING.

Inherited from PhysicsBody2D (1)
var input_pickable: bool = false
Inherited from CollisionObject2D (5)
var input_pickable: bool = true
Inherited from Node2D (12)
var position: Vector2 = Vector2(0, 0)
var rotation: float = 0.0
var scale: Vector2 = Vector2(1, 1)
var skew: float = 0.0
Inherited from CanvasItem (16)
var light_mask: int = 1
var modulate: Color = Color(1, 1, 1, 1)
var self_modulate: Color = Color(1, 1, 1, 1)
var top_level: bool = false
var visible: bool = true
var y_sort_enabled: bool = false
var z_as_relative: bool = true
var z_index: int = 0
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: Vector2 = Vector2(0, -1)) -> float

Returns the floor's collision angle at the last collision point according to up_direction, which is Vector2.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() -> Vector2

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() -> Vector2

Returns the last motion applied to the CharacterBody2D 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() -> KinematicCollision2D

Returns a KinematicCollision2D 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_velocity() -> Vector2

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

func get_position_delta() -> Vector2

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

func get_real_velocity() -> Vector2

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) -> KinematicCollision2D

Returns a KinematicCollision2D, 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().

Example: Iterate through the collisions with a for loop:

for i in get_slide_collision_count():
	var collision = get_slide_collision(i)
	print("Collided with: ", collision.get_collider().name)
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() -> Vector2

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 (by default only on floor) rather than stop immediately. If the other body is a CharacterBody2D or RigidBody2D, 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 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.

The general behavior and available properties change according to the motion_mode.

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

Inherited from PhysicsBody2D (6)
func get_collision_exceptions() -> PhysicsBody2D[]
func move_and_collide(motion: Vector2, test_only: bool = false, safe_margin: float = 0.08, recovery_as_collision: bool = false) -> KinematicCollision2D
func test_move(from: Transform2D, motion: Vector2, collision: KinematicCollision2D = null, safe_margin: float = 0.08, recovery_as_collision: bool = false) -> bool
Inherited from CollisionObject2D (31)
func _input_event(viewport: Viewport, event: InputEvent, shape_idx: int) -> void
func _mouse_enter() -> void
func _mouse_exit() -> void
func _mouse_shape_enter(shape_idx: int) -> void
func _mouse_shape_exit(shape_idx: int) -> 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: Shape2D) -> 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) -> Shape2D
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_one_way_collision(owner_id: int, enable: bool) -> void
func shape_owner_set_one_way_collision_direction(owner_id: int, direction: Vector2) -> void
func shape_owner_set_one_way_collision_margin(owner_id: int, margin: float) -> void
func shape_owner_set_transform(owner_id: int, transform: Transform2D) -> void
Inherited from Node2D (11)
func apply_scale(ratio: Vector2) -> void
func get_angle_to(point: Vector2) -> float
func global_translate(offset: Vector2) -> void
func look_at(point: Vector2) -> void
func move_local_x(delta: float, scaled: bool = false) -> void
func move_local_y(delta: float, scaled: bool = false) -> void
func rotate(radians: float) -> void
func to_global(local_point: Vector2) -> Vector2
func to_local(global_point: Vector2) -> Vector2
func translate(offset: Vector2) -> void
Inherited from CanvasItem (62)
func _draw() -> void
func draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0) -> void
func draw_arc(center: Vector2, radius: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void
func draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void
func draw_circle(position: Vector2, radius: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void
func draw_dashed_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, dash: float = 2.0, aligned: bool = true, antialiased: bool = false) -> void
func draw_ellipse(position: Vector2, major: float, minor: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_ellipse_arc(center: Vector2, major: float, minor: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_end_animation() -> void
func draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_mesh(mesh: Mesh, texture: Texture2D, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_msdf_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), outline: float = 0.0, pixel_range: float = 4.0, scale: float = 1.0) -> void
func draw_multiline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_multiline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void
func draw_multiline_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multiline_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multimesh(multimesh: MultiMesh, texture: Texture2D) -> void
func draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void
func draw_polyline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_polyline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void
func draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null) -> void
func draw_rect(rect: Rect2, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1)) -> void
func draw_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_style_box(style_box: StyleBox, rect: Rect2) -> void
func draw_texture(texture: Texture2D, position: Vector2, modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_texture_rect(texture: Texture2D, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) -> void
func draw_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false, clip_uv: bool = true) -> void
func force_update_transform() -> void
func get_canvas() -> RID
func hide() -> void
func make_canvas_position_local(viewport_point: Vector2) -> Vector2
func move_to_front() -> void
func queue_redraw() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_visibility_layer_bit(layer: int, enabled: bool) -> void
func show() -> 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 CollisionObject2D (5)
signal input_event(viewport: Node, event: InputEvent, shape_idx: int)
signal mouse_entered()
signal mouse_exited()
signal mouse_shape_entered(shape_idx: int)
signal mouse_shape_exited(shape_idx: int)
Inherited from CanvasItem (4)
signal draw()
signal hidden()
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 sided 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 top-down 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.