Up to date
This page is up to date for Godot 4.2
.
If you still find outdated information, please open an issue.
Using CharacterBody2D/3D¶
소개¶
Godot offers several collision objects to provide both collision detection and response. Trying to decide which one to use for your project can be confusing. You can avoid problems and simplify development if you understand how each of them works and what their pros and cons are. In this tutorial, we'll look at the CharacterBody2D node and show some examples of how to use it.
참고
While this document uses CharacterBody2D
in its examples, the same
concepts apply in 3D as well.
What is a character body?¶
CharacterBody2D
is for implementing bodies that are controlled via code.
Character bodies detect collisions with other bodies when moving, but are not affected by
engine physics properties, like gravity or friction. While this means that you
have to write some code to create their behavior, it also means you have more
precise control over how they move and react.
참고
This document assumes you're familiar with Godot's various physics bodies. Please read 물리 소개 first, for an overview of the physics options.
팁
A CharacterBody2D can be affected by gravity and other forces, but you must calculate the movement in code. The physics engine will not move a CharacterBody2D.
이동과 콜리전¶
When moving a CharacterBody2D
, you should not set its position
property
directly. Instead, you use the move_and_collide()
or move_and_slide()
methods.
These methods move the body along a given vector and detect collisions.
경고
You should handle physics body movement in the _physics_process()
callback.
두 개의 이동 메서드는 다른 목적을 지닙니다, 그리고 이 튜토리얼 이후에, 어떻게 작동하는 지에 대한 예제를 볼 것입니다.
move_and_collide¶
This method takes one required parameter: a Vector2 indicating
the body's relative movement. Typically, this is your velocity vector multiplied by the
frame timestep (delta
). If the engine detects a collision anywhere along
this vector, the body will immediately stop moving. If this happens, the
method will return a KinematicCollision2D object.
KinematicCollision2D
는 콜리전과 충돌하는 오브젝트에 대한 정보를 담고 있는 오브젝트입니다. 이 정보로, 콜리전 반응을 계산할 수 있습니다.
move_and_collide
is most useful when you just want to move the body and
detect collision, but don't need any automatic collision response. For example,
if you need a bullet that ricochets off a wall, you can directly change the angle
of the velocity when you detect a collision. See below for an example.
move_and_slide¶
The move_and_slide()
method is intended to simplify the collision
response in the common case where you want one body to slide along the other.
It is especially useful in platformers or top-down games, for example.
When calling move_and_slide()
, the function uses a number of node properties
to calculate its slide behavior. These properties can be found in the Inspector,
or set in code.
velocity
- default value:Vector2( 0, 0 )
This property represents the body's velocity vector in pixels per second.
move_and_slide()
will modify this value automatically when colliding.motion_mode
- default value:MOTION_MODE_GROUNDED
This property is typically used to distinguish between side-scrolling and top-down movement. When using the default value, you can use the
is_on_floor()
,is_on_wall()
, andis_on_ceiling()
methods to detect what type of surface the body is in contact with, and the body will interact with slopes. When usingMOTION_MODE_FLOATING
, all collisions will be considered "walls".up_direction
- default value:Vector2( 0, -1 )
This property allows you to define what surfaces the engine should consider being the floor. Its value lets you use the
is_on_floor()
,is_on_wall()
, andis_on_ceiling()
methods to detect what type of surface the body is in contact with. The default value means that the top side of horizontal surfaces will be considered "ground".floor_stop_on_slope
- default value:true
This parameter prevents a body from sliding down slopes when standing still.
wall_min_slide_angle
- default value:0.261799
(in radians, equivalent to15
degrees)This is the minimum angle where the body is allowed to slide when it hits a slope.
floor_max_angle
- 기본 값:0.785398
(라디안에서는,45
도와 같습니다)This parameter is the maximum angle before a surface is no longer considered a "floor."
There are many other properties that can be used to modify the body's behavior under specific circumstances. See the CharacterBody2D docs for full details.
콜리전 감지하기¶
move_and_collide()
를 사용할 때 함수는 KinematicCollision2D
를 직접 반환하고, 이 정보를 여러분의 코드에 사용할 수 있습니다.
When using move_and_slide()
it's possible to have multiple collisions occur,
as the slide response is calculated. To process these collisions, use get_slide_collision_count()
and get_slide_collision()
:
# Using move_and_collide.
var collision = move_and_collide(velocity * delta)
if collision:
print("I collided with ", collision.get_collider().name)
# Using move_and_slide.
move_and_slide()
for i in get_slide_collision_count():
var collision = get_slide_collision(i)
print("I collided with ", collision.get_collider().name)
// Using MoveAndCollide.
var collision = MoveAndCollide(Velocity * (float)delta);
if (collision != null)
{
GD.Print("I collided with ", ((Node)collision.GetCollider()).Name);
}
// Using MoveAndSlide.
MoveAndSlide();
for (int i = 0; i < GetSlideCollisionCount(); i++)
{
var collision = GetSlideCollision(i);
GD.Print("I collided with ", ((Node)collision.GetCollider()).Name);
}
참고
get_slide_collision_count() only counts times the body has collided and changed direction.
See KinematicCollision2D for details on what collision data is returned.
어떤 이동 메서드를 사용해야 할까요?¶
A common question from new Godot users is: "How do you decide which movement
function to use?" Often, the response is to use move_and_slide()
because
it seems simpler, but this is not necessarily the case. One way to think of it
is that move_and_slide()
is a special case, and move_and_collide()
is more general. For example, the following two code snippets result in
the same collision response:
# using move_and_collide
var collision = move_and_collide(velocity * delta)
if collision:
velocity = velocity.slide(collision.get_normal())
# using move_and_slide
move_and_slide()
// using MoveAndCollide
var collision = MoveAndCollide(Velocity * (float)delta);
if (collision != null)
{
Velocity = Velocity.Slide(collision.GetNormal());
}
// using MoveAndSlide
MoveAndSlide();
move_and_slide()
로 하는 것을 move_and_collide()
또한 할 수 있습니다, 하지만 좀 더 많은 코드를 갖습니다. 하지만 아래에서 예제를 보면, move_and_slide()
가 원하는 응답을 제공하지 않는 경우도 있습니다.
In the example above, move_and_slide()
automatically alters the velocity
variable. This is because when the character collides with the environment,
the function recalculates the speed internally to reflect
the slowdown.
For example, if your character fell on the floor, you don't want it to accumulate vertical speed due to the effect of gravity. Instead, you want its vertical speed to reset to zero.
move_and_slide()
may also recalculate the kinematic body's velocity several
times in a loop as, to produce a smooth motion, it moves the character and
collides up to five times by default. At the end of the process, the character's
new velocity is available for use on the next frame.
예제¶
To see these examples in action, download the sample project: character_body_2d_starter.zip
이동과 벽¶
If you've downloaded the sample project, this example is in "basic_movement.tscn".
For this example, add a CharacterBody2D
with two children: a Sprite2D
and a
CollisionShape2D
. Use the Godot "icon.svg" as the Sprite2D's texture (drag it
from the Filesystem dock to the Texture property of the Sprite2D
). In the
CollisionShape2D
's Shape property, select "New RectangleShape2D" and
size the rectangle to fit over the sprite image.
참고
2D 이동 구조를 구현하는 예제는 2D 이동 개요를 참고하세요.
Attach a script to the CharacterBody2D and add the following code:
extends CharacterBody2D
var speed = 300
func get_input():
var input_dir = Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
velocity = input_dir * speed
func _physics_process(delta):
get_input()
move_and_collide(velocity * delta)
using Godot;
public partial class MyCharacterBody2D : CharacterBody2D
{
private int _speed = 300;
public void GetInput()
{
Vector2 inputDir = Input.GetVector("ui_left", "ui_right", "ui_up", "ui_down");
Velocity = inputDir * _speed;
}
public override void _PhysicsProcess(double delta)
{
GetInput();
MoveAndCollide(Velocity * (float)delta);
}
}
Run this scene and you'll see that move_and_collide()
works as expected, moving
the body along the velocity vector. Now let's see what happens when you add
some obstacles. Add a StaticBody2D with a
rectangular collision shape. For visibility, you can use a Sprite2D, a
Polygon2D, or turn on "Visible Collision Shapes" from the "Debug" menu.
Run the scene again and try moving into the obstacle. You'll see that the CharacterBody2D
can't penetrate the obstacle. However, try moving into the obstacle at an angle and
you'll find that the obstacle acts like glue - it feels like the body gets stuck.
이것은 콜리전 응답이 없기 때문에 발생한 것입니다. move_and_collide()
는 콜리전이 발생할 때 바디의 움직임을 멈춥니다. 콜리전로부터 원하는 어떤 응답이라도 코딩해야 합니다.
Try changing the function to move_and_slide()
and running again.
move_and_slide()
는 다비가 콜리전 오브젝트를 따라 미끄러지는 기본 콜리전 응답을 제공합니다. 이것은 아주 많은 게임 유형에 유용하고, 원하는 행동을 얻을 때 필요할 수도 있습니다.
튕김/반사¶
What if you don't want a sliding collision response? For this example ("bounce_and_collide.tscn" in the sample project), we have a character shooting bullets and we want the bullets to bounce off the walls.
이 예제는 세 개의 씬을 사용합니다. 메인 씬은 Player와 Wall을 갖고 있습니다. Bullet과 Wall은 분리된 씬으로 그들은 인스턴스 할 수 있습니다.
The Player is controlled by the w
and s
keys for forward and back. Aiming
uses the mouse pointer. Here is the code for the Player, using move_and_slide()
:
extends CharacterBody2D
var Bullet = preload("res://bullet.tscn")
var speed = 200
func get_input():
# Add these actions in Project Settings -> Input Map.
var input_dir = Input.get_axis("backward", "forward")
velocity = transform.x * input_dir * speed
if Input.is_action_just_pressed("shoot"):
shoot()
func shoot():
# "Muzzle" is a Marker2D placed at the barrel of the gun.
var b = Bullet.instantiate()
b.start($Muzzle.global_position, rotation)
get_tree().root.add_child(b)
func _physics_process(delta):
get_input()
var dir = get_global_mouse_position() - global_position
# Don't move if too close to the mouse pointer.
if dir.length() > 5:
rotation = dir.angle()
move_and_slide()
using Godot;
public partial class MyCharacterBody2D : CharacterBody2D
{
private PackedScene _bullet = GD.Load<PackedScene>("res://Bullet.tscn");
private int _speed = 200;
public void GetInput()
{
// Add these actions in Project Settings -> Input Map.
float inputDir = Input.GetAxis("backward", "forward");
Velocity = Transform.X * inputDir * _speed;
if (Input.IsActionPressed("shoot"))
{
Shoot();
}
}
public void Shoot()
{
// "Muzzle" is a Marker2D placed at the barrel of the gun.
var b = (Bullet)_bullet.Instantiate();
b.Start(GetNode<Node2D>("Muzzle").GlobalPosition, Rotation);
GetTree().Root.AddChild(b);
}
public override void _PhysicsProcess(double delta)
{
GetInput();
var dir = GetGlobalMousePosition() - GlobalPosition;
// Don't move if too close to the mouse pointer.
if (dir.Length() > 5)
{
Rotation = dir.Angle();
MoveAndSlide();
}
}
}
그리고 Bullet을 위한 코드입니다:
extends CharacterBody2D
var speed = 750
func start(_position, _direction):
rotation = _direction
position = _position
velocity = Vector2(speed, 0).rotated(rotation)
func _physics_process(delta):
var collision = move_and_collide(velocity * delta)
if collision:
velocity = velocity.bounce(collision.get_normal())
if collision.get_collider().has_method("hit"):
collision.get_collider().hit()
func _on_VisibilityNotifier2D_screen_exited():
# Deletes the bullet when it exits the screen.
queue_free()
using Godot;
public partial class Bullet : CharacterBody2D
{
public int _speed = 750;
public void Start(Vector2 position, float direction)
{
Rotation = direction;
Position = position;
Velocity = new Vector2(speed, 0).Rotated(Rotation);
}
public override void _PhysicsProcess(double delta)
{
var collision = MoveAndCollide(Velocity * (float)delta);
if (collision != null)
{
Velocity = Velocity.Bounce(collision.GetNormal());
if (collision.GetCollider().HasMethod("Hit"))
{
collision.GetCollider().Call("Hit");
}
}
}
private void OnVisibilityNotifier2DScreenExited()
{
// Deletes the bullet when it exits the screen.
QueueFree();
}
}
The action happens in _physics_process()
. After using move_and_collide()
, if a
collision occurs, a KinematicCollision2D
object is returned (otherwise, the return
is null
).
반환된 콜리전이 있다면, 우리는 콜리전의 normal
을 사용해 Vector2.bounce()
메서드로 총알의 velocity
를 반사합니다.
충돌 오브젝트 (collider
)가 hit
메서드를 가진다면, 또한 그것을 호출합니다. 예제 프로젝트에서는, 이를 설명하기 위해 Wall에 반짝이는 색상 효과를 추가했습니다.
플랫포머 움직임¶
Let's try one more popular example: the 2D platformer. move_and_slide()
is ideal for quickly getting a functional character controller up and running.
If you've downloaded the sample project, you can find this in "platformer.tscn".
For this example, we'll assume you have a level made of one or more StaticBody2D
objects. They can be any shape and size. In the sample project, we're using
Polygon2D to create the platform shapes.
플레이어 바디를 위한 코드입니다:
extends CharacterBody2D
var speed = 300.0
var jump_speed = -400.0
# Get the gravity from the project settings so you can sync with rigid body nodes.
var gravity = ProjectSettings.get_setting("physics/2d/default_gravity")
func _physics_process(delta):
# Add the gravity.
velocity.y += gravity * delta
# Handle Jump.
if Input.is_action_just_pressed("jump") and is_on_floor():
velocity.y = jump_speed
# Get the input direction.
var direction = Input.get_axis("ui_left", "ui_right")
velocity.x = direction * speed
move_and_slide()
using Godot;
public partial class MyCharacterBody2D : CharacterBody2D
{
private float _speed = 100.0f;
private float _jumpSpeed = -400.0f;
// Get the gravity from the project settings so you can sync with rigid body nodes.
public float Gravity = ProjectSettings.GetSetting("physics/2d/default_gravity").AsSingle();
public override void _PhysicsProcess(double delta)
{
Vector2 velocity = Velocity;
// Add the gravity.
velocity.Y += Gravity * (float)delta;
// Handle jump.
if (Input.IsActionJustPressed("jump") && IsOnFloor())
velocity.Y = _jumpSpeed;
// Get the input direction.
float direction = Input.GetAxis("ui_left", "ui_right");
velocity.X = direction * _speed;
Velocity = velocity;
MoveAndSlide();
}
}
In this code we're using move_and_slide()
as described above - to move the body
along its velocity vector, sliding along any collision surfaces such as the ground
or a platform. We're also using is_on_floor()
to check if a jump should be
allowed. Without this, you'd be able to "jump" in midair; great if you're making
Flappy Bird, but not for a platformer game.
There is a lot more that goes into a complete platformer character: acceleration, double-jumps, coyote-time, and many more. The code above is just a starting point. You can use it as a base to expand into whatever movement behavior you need for your own projects.