physics.CharacterBody

physics.CharacterBody(world: physics.World)

Create a new character body in the specified world.

The body is created at the origin with default movement properties. Add colliders with add_collider before calling move_and_slide.

Args

• world (World) — The physics world to create the body in.

acceleration: float

The acceleration applied when moving.

air_steer: float

The control factor for steering while in the air (0.0 to 1.0).

capsule_shape: Capsule

The capsule shape used for ground detection and collision casting.

collision_layer: int

The body's collision layer (category bits).

collision_mask: int

The body's collision mask.

friction: float

The friction applied when on the ground.

is_valid: bool

Indicates whether the body is not destroyed.

mass: float

The simulated mass of the character for pushing rigid bodies.

max_speed: float

The maximum speed the character can move.

motion_mode: physics.CharacterBody.MotionMode

The motion mode of the character.

pos: Vec2

The position of the body in world coordinates.

rotation: float

The rotation of the body in radians.

stop_speed: float

The speed threshold below which the character will stop moving.

velocity: Vec2

The velocity of the character body.

add_collider(self, circle: Circle, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

add_collider(self, polygon: Polygon, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

add_collider(self, rect: Rect, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

add_collider(self, capsule: Capsule, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

Overloaded function.

1. add_collider(self, circle: Circle, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

Add a circular collider to the body.

Args

• circle (Circle) — The circular shape to add as a collider.
• density (float, optional) — The density of the collider. Defaults to 1.0.
• friction (float, optional) — The friction coefficient of the collider. Defaults to 0.2.
• restitution (float, optional) — The restitution (bounciness) of the collider. Defaults to 0.0.
• enable_events (bool, optional) — Whether to enable hit, contact, and sensor events for this collider. Defaults to False.
• is_sensor (bool, optional) — Whether the collider is a sensor. Defaults to False.

2. add_collider(self, polygon: Polygon, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

Add a polygonal collider to the body.

Args

• polygon (Polygon) — The polygonal shape to add as a collider.
• density (float, optional) — The density of the collider. Defaults to 1.0.
• friction (float, optional) — The friction coefficient of the collider. Defaults to 0.2.
• restitution (float, optional) — The restitution (bounciness) of the collider. Defaults to 0.0.
• enable_events (bool, optional) — Whether to enable hit, contact, and sensor events for this collider. Defaults to False.
• is_sensor (bool, optional) — Whether the collider is a sensor. Defaults to False.

3. add_collider(self, rect: Rect, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

Add a rectangular collider to the body.

Args

• rect (Rect) — The rectangular shape to add as a collider.
• density (float, optional) — The density of the collider. Defaults to 1.0.
• friction (float, optional) — The friction coefficient of the collider. Defaults to 0.2.
• restitution (float, optional) — The restitution (bounciness) of the collider. Defaults to 0.0.
• enable_events (bool, optional) — Whether to enable hit, contact, and sensor events for this collider. Defaults to False.
• is_sensor (bool, optional) — Whether the collider is a sensor. Defaults to False.

4. add_collider(self, capsule: Capsule, density: float = 1.0, friction: float = 0.20000000298023224, restitution: float = 0.0, enable_events: bool = False, is_sensor: bool = False) -> None

Add a capsule collider to the body.

Args

• capsule (Capsule) — The capsule shape to add as a collider.
• density (float, optional) — The density of the collider. Defaults to 1.0.
• friction (float, optional) — The friction coefficient of the collider. Defaults to 0.2.
• restitution (float, optional) — The restitution (bounciness) of the collider. Defaults to 0.0.
• enable_events (bool, optional) — Whether to enable hit, contact, and sensor events for this collider. Defaults to False.
• is_sensor (bool, optional) — Whether the collider is a sensor. Defaults to False.

destroy(self) -> None

Destroy the body manually.

get_colliders(self) -> list[physics.Collider]

Return non-owning handles for this body's collider shapes.

get_transform(self) -> Transform

Get the current transform of the body (position, rotation, and scale).

Returns

• Transform — The current transform of the body.

is_on_ceiling(self) -> bool

Check if the character is currently in contact with the ceiling.

Returns

• bool — True if the character is on the ceiling, False otherwise.

is_on_floor(self) -> bool

Check if the character is currently in contact with the floor.

Returns

• bool — True if the character is on the floor, False otherwise.

is_on_wall(self) -> bool

Check if the character is currently in contact with a wall.

Returns

• bool — True if the character is on a wall, False otherwise.

move_and_slide(self, delta: float = -1.0) -> None

Perform movement and collision resolution for the character.

This method moves the character according to the velocity property and resolves collisions by sliding along surfaces. It also updates the floor/ceiling/wall contact states.

Args

• delta (float, optional) — The time step to use for movement. Defaults to -1.0, which uses the frame delta.