Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

KinematicBody2D 사용하기

소개

Godot는 콜리전 감지와 반응성을 모두 제공하기 위해 많은 콜리전 오브젝트를 제공합니다. 프로젝트에 사용할 항목을 결정하는 것은 혼란스러울 수 있습니다. 각각의 작동 방식 및 장단점이 무엇인지 이해한다면 문제를 피하고 개발을 간소화할 수 있습니다. 이 튜토리얼에서는 KinematicBody2D 노드를 살펴보고 사용 방법에 대한 몇 가지 예를 보여 드리겠습니다.

참고

이 문서에서는 예제에서 ``CharacterBody2D``를 사용하지만 동일한 개념이 3D에도 적용됩니다.

캐릭터 바디가 무엇입니까?

CharacterBody2D는 코드로 제어되는 바디를 구현하기 위한 것입니다. 캐릭터 바디는 움직일 때 다른 바디와의 콜리전을 감지하지만, 중력이나 마찰과 같은 물리 엔진 속성에 의해 영향을 받지 않습니다. 이것은 당신이 그것들의 행동을 만들어내기 위해 몇 개의 코드를 써야 한다는 것이기도 하지만, 반대로 그것들이 어떻게 움직이고 반응하는지 더 정확히 제어할 수 있다는 것을 의미합니다.

Despite its name CharacterBody2D, it can also be used for other physics objects that require precise manual movement logic and detailed collision information, such as moving platforms or complex projectiles.

참고

이 문서는 당신이 Godot의 다양한 물리 바디에 대해 잘 알고 있다고 가정합니다. 먼저 물리 소개를 읽어주세요.

팁

KinematicBody2D는 중력과 다른 힘에 의해 영향을 받을 수 있지만 코드로 움직임을 계산해야 합니다. 물리 엔진이 KinematicBody2D를 움직이게 하진 않습니다.

이동과 콜리전

KinematicBody2D를 움직일 때 position 속성을 직접 설정해서는 안 됩니다. 대신 move_and_collide() 또는 move_and_slide() 메서드를 사용해야 합니다. 이러한 방법은 주어진 벡터를 따라 바디가 이동하며 콜리전이 감지될 경우 즉시 중지됩니다. KinematicBody2D가 충돌한 후에는 콜리전 반응을 수동으로 코딩해야 합니다.

경고

키네마틱 바디의 움직임은 _physics_process() 콜백으로 이루어져야 합니다.

두 개의 이동 메서드는 다른 목적을 지닙니다, 그리고 이 튜토리얼 이후에, 어떻게 작동하는 지에 대한 예제를 볼 것입니다.

move_and_collide

이 메서드는 하나의 매개변수를 가집니다: 바디의 상대적인 움직임을 나타내는 Vector2입니다. 일반적으로, 이것은 속도 벡터에 프레임 타임 스텝 (delta)을 곱한 것입니다. 엔진이 이 벡터를 따라 어느 곳이든 콜리전을 감지하면, 바디는 즉시 이동을 멈춥니다. 이 경우, 메서드는 KinematicCollision2D 오브젝트를 반환합니다.

KinematicCollision2D는 콜리전과 충돌하는 오브젝트에 대한 데이터를 담고 있는 오브젝트입니다. 이 데이터를 사용하여 콜리전 반응을 계산할 수 있습니다.

``move_and_collide``는 몸체를 움직이고 충돌을 감지하고 싶지만 자동 충돌 응답은 필요하지 않을 때 가장 유용합니다. 예를 들어, 벽에 부딪히는 총알이 필요한 경우 충돌을 감지할 때 속도 각도를 직접 변경할 수 있습니다. 예를 보려면 아래를 참조하세요.

move_and_slide

move_and_slide() 메서드는 콜리전 응답을 한 바디가 다른 바디를 따라 미끄러지는 일반적인 경우에서 단순화 하기 위한 것입니다. 이것은 특히, 예를 들어 플랫포머나 탑뷰 게임에서 유용합니다.

``move_and_slide()``를 호출할 때 함수는 다양한 노드 속성을 사용하여 슬라이드 동작을 계산합니다. 이러한 속성은 인스펙터에서 찾거나 코드에서 설정할 수 있습니다.

velocity - 디폴트 값: Vector2( 0, 0 )

이 속성은 신체의 속도 벡터를 초당 픽셀 단위로 나타냅니다. ``move_and_slide()``는 충돌 시 이 값을 자동으로 수정합니다.
max_bounces - 기본 값: 4

이 매개변수는 엔진이 바닥이라고 생각하는 표면을 정의할 수 있습니다. 이것을 설정하면 is_on_floor(), is_on_wall(), 그리고 is_on_ceiling() 메서드를 사용할 수 있고, 어떤 타입의 표면이 바디와 닿았는지 감지할 수 있습니다. 기본 값으로 모든 표면은 벽으로 간주되는 것을 뜻합니다.
up_direction - 디폴트 값: Vector2( 0, -1 )

이 매개변수는 엔진이 바닥이라고 생각하는 표면을 정의할 수 있습니다. 이것을 설정하면 is_on_floor(), is_on_wall(), 그리고 is_on_ceiling() 메서드를 사용할 수 있고, 어떤 타입의 표면이 바디와 닿았는지 감지할 수 있습니다. 기본 값으로 모든 표면은 벽으로 간주되는 것을 뜻합니다.
slope_stop_min_velocity - 기본 값: 5

이 매개변수는 서있는 상태일 때 바디가 경사면에 미끄러져 내려가는 것을 방지합니다.
floor_max_angle - 기본 값: 0.785398 (라디안에서는, 45도와 같습니다)

이는 신체가 경사면에 부딪혔을 때 미끄러질 수 있는 최소 각도입니다.
floor_max_angle - 기본 값: 0.785398 (라디안에서는, 45도와 같습니다)

이것은 표면이 더 이상 "바닥"으로 인식되지 않는 최대 각도입니다.

특정 상황에서 신체의 행동을 수정하는 데 사용할 수 있는 다른 속성이 많이 있습니다. 자세한 내용은 CharacterBody2D 문서를 참조하세요.

콜리전 감지하기

move_and_collide()를 사용할 때 함수는 KinematicCollision2D를 직접 반환하고, 이 정보를 여러분의 코드에 사용할 수 있습니다.

move_and_slide()``를 사용하면 슬라이드 응답이 계산되므로 여러 충돌이 발생할 수 있습니다. 이러한 충돌을 처리하려면 ``get_slide_collision_count() 및 ``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()`는 몸체가 충돌하고 방향을 바꾼 횟수만 계산합니다.

반환되는 콜리전 데이터에 대한 자세한 내용은 KinematicCollision2D를 참조하세요.

어떤 이동 메서드를 사용해야 할까요?

새로운 Godot 사용자로부터 흔한 질문이 있습니다: "어떻게 어떤 이동 함수를 사용하는 지를 결정하나요?" 자주하는 대답은 move_and_slide()를 사용하라는 것인데, "더 쉽기" 때문입니다, 그러나 반드시 그런 것은 아닙니다. 생각을 해보자면 move_and_slide()는 특별한 경우, 그리고 move_and_collide()는 더 일반적인 것입니다. 예를 들어 두 개의 코드 단문은 값은 콜리전 반응 결과가 나타납니다:

# 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()가 원하는 응답을 제공하지 않는 경우도 있습니다.

위의 예에서 move_and_slide()``는 ``velocity 변수를 자동으로 변경합니다. 캐릭터가 환경과 충돌할 때 함수가 속도 저하를 반영하기 위해 내부적으로 속도를 다시 계산하기 때문입니다.

예를 들어 캐릭터가 바닥에 떨어진 경우 중력의 영향으로 인해 수직 속도가 누적되는 것을 원하지 않습니다. 대신 수직 속도를 0으로 재설정하려고 합니다.

``move_and_slide()``는 또한 부드러운 모션을 생성하기 위해 캐릭터를 움직이고 기본적으로 최대 5번 충돌하므로 루프에서 운동체의 속도를 여러 번 다시 계산할 수도 있습니다. 프로세스가 끝나면 캐릭터의 새 속도를 다음 프레임에서 사용할 수 있습니다.

예제

이러한 예제가 실제로 작동하는 모습을 보려면 샘플 프로젝트를 다운로드하세요: character_body_2d_starter.zip

이동과 벽

샘플 프로젝트를 다운로드 했다면, 이 예제는 "BasicMovement.tscn"입니다.

이 예시에서 CharacterBody2D를 두 자식과 함께 추가합니다: Sprite2D와 CollisionShape2D입니다. Godot "icon.png"를 Sprite2D의 텍스처 속성으로 사용합니다 (파일시스템 독에서 Sprite2D의 텍스처 속성으로 끌어 놓으세요). CollisionShape2D의 모양 속성에서 "새 RectangleShape2D"를 선택하고 스프라이트 이미지에 맞게 사각형 크기를 조절합니다.

참고

2D 이동 구조를 구현하는 예제는 2D 이동 개요를 참조하세요.

CharacterBody2D에 스크립트를 붙이고 다음 코드를 추가하세요:

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);
    }
}

이 씬을 실행하고 move_and_collide()가 예상대로, 바디가 속도 벡터를 따라 움직이는 것을 볼 수 있습니다. 이제 장애물을 추가하면 어떻게 되는지 봅시다. 직사각형 콜리전 모양을 가진 StaticBody2D를 추가합니다. 가시성을 위해, 스프라이트, Polygon2D, 혹은 "디버그" 메뉴에서 "콜리전 모양 보이기"를 키면 됩니다.

씬을 다시 실행하고 장애물로 움직여 봅니다. KinematicBody2D가 장애물을 통과하지 못하는 것을 볼 수 있습니다. 하지만 장애물 안으로 움직이려고 하면 장애물이 풀처럼 행동하는 것을 찾을 수 있습니다 - 바디가 끼어있는 느낌이 듭니다.

이것은 콜리전 응답이 없기 때문에 발생한 것입니다. move_and_collide()는 콜리전이 발생할 때 바디의 움직임을 멈춥니다. 콜리전로부터 원하는 어떤 응답이라도 코딩해야 합니다.

함수를 move_and_slide(velocity)로 변경하고 다시 실행합니다. 우리는 속도 계산에서 delta를 제거했습니다.

move_and_slide()는 다비가 콜리전 오브젝트를 따라 미끄러지는 기본 콜리전 응답을 제공합니다. 이것은 아주 많은 게임 유형에 유용하고, 원하는 행동을 얻을 때 필요할 수도 있습니다.

튕김/반사

미끄러지는 콜리전 응답을 원하지 않으면 어떻게 해야 할까요? (샘플 프로젝트에 있는 "BounceandCollide.tscn") 이 예제의 경우, 총을 쏘는 캐릭터가 있고 총알이 벽에 튕겨 나가게 하고 싶습니다.

이 예제는 세 개의 씬을 사용합니다. 메인 씬은 Player와 Wall을 갖고 있습니다. Bullet과 Wall은 분리된 씬으로 그들은 인스턴스 할 수 있습니다.

Player는 w와 s키로 조작하며 각각 앞뒤로 움직입니다. 마우스로 조준합니다. 이것이 move_and_slide()를 사용하는 Player 코드입니다:

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();
    }
}

동작은 _physics_process()에서 발생합니다. move_and_collide()를 사용한 이후, 콜리전이 발생하면, KinematicCollision2D 오브젝트는 반환됩니다 (그렇지 않으면, Nil을 반환합니다).

반환된 콜리전이 있다면, 우리는 콜리전의 normal을 사용해 Vector2.bounce() 메서드로 총알의 velocity를 반사합니다.

충돌 오브젝트 (collider)가 hit 메서드를 가진다면, 또한 그것을 호출합니다. 예제 프로젝트에서는, 이를 설명하기 위해 Wall에 반짝이는 색상 효과를 추가했습니다.

플랫포머 움직임

인기있는 예제를 하나 더 들어보겠습니다: 2D 플랫포머 입니다. move_and_slide()가 빠르게 기능의 캐릭터 조작을 얻고 실행시키기에 이상적입니다. 샘플 프로젝트를 다운로드 했다면, "Platformer.tscn"에서 이것을 찾을 수 있습니다.

이 예제를 위해,.``StaticBody2D`` 오브젝트로 만들어진 레벨이 있다고 가정합니다. 어떤 모양이나 크기가 될 수 있습니다. 샘플 프로젝트에서, 우리는 플랫폼 모양을 만들기 위해 Polygon2D를 사용합니다.

플레이어 바디를 위한 코드입니다:

extends CharacterBody2D

var speed = 300.0
var jump_speed = -400.0

func _physics_process(delta):
    # Add the gravity.
    velocity.y += get_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 override void _PhysicsProcess(double delta)
    {
        Vector2 velocity = Velocity;

        // Add the gravity.
        velocity.Y += GetGravity() * (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();
    }
}

이 코드에서는 위에서 설명한 대로 ``move_and_slide()``를 사용하여 속도 벡터를 따라 몸체를 이동하고 지면이나 플랫폼과 같은 충돌 표면을 따라 미끄러집니다. 또한 점프가 허용되어야 하는지 확인하기 위해 ``is_on_floor()``를 사용하고 있습니다. 이것이 없으면 공중에서 "점프"할 수 있습니다. Flappy Bird를 만드는 경우에는 좋지만 플랫폼 게임에는 적합하지 않습니다.

완전한 플랫폼 게임 캐릭터에는 가속, 이중 점프, 코요테 시간 등 더 많은 것들이 포함됩니다. 위의 코드는 단지 시작점일 뿐입니다. 이를 기반으로 사용하여 자신의 프로젝트에 필요한 모든 동작 동작을 확장할 수 있습니다.