使用KinematicBody2D

简介

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 KinematicBody2D node and show some examples of how to use it.

注解

本文假设您熟悉Godot中的各种物理体。 否则请先阅读 物理介绍 。

什么是运动体？

KinematicBody2D is for implementing bodies that are controlled via code. Kinematic 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.

小技巧

KinematicBody2D 可以受到重力和其他力的影响，但您必须在代码中计算它的运动。 物理引擎不会移动 KinematicBody2D。

Movement and collision

When moving a KinematicBody2D, 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 instantly stop if a collision is detected with another body. After a KinematicBody2D has collided, any collision response must be coded manually.

警告

You should only do Kinematic body movement in the _physics_process() callback.

The two movement methods serve different purposes, and later in this tutorial, you’ll see examples of how they work.

move_and_collide

这个方法有一个 Vector2 参数以表示物体的相对运动。 通常，这是您的速度向量乘以帧时间步长( delta )。 如果在沿着此向量方向的任何位置，引擎检测到碰撞，则物体将立即停止移动。 如果发生这种情况，该方法将返回 KinematicCollision2D 对象。

KinematicCollision2D is an object containing data about the collision and the colliding object. Using this data, you can calculate your collision response.

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.

小技巧

move_and_slide() 使用 delta 自动计算基于帧的运动。 在将速度向量传递给 move_and_slide() 之前，请 不要 将速度向量乘以 delta。

除了速度向量之外，move_and_slide() 还有许多其他参数，允许您自定义滑动行为:

  • up_direction - default value: Vector2( 0, 0 )

    This parameter allows you to define what surfaces the engine should consider being the floor. Setting this lets you use the is_on_floor(), is_on_wall(), and is_on_ceiling() methods to detect what type of surface the body is in contact with. The default value means that all surfaces are considered walls.

  • stop_on_slope - default value: false

    This parameter prevents a body from sliding down slopes when standing still.

  • max_slides - default value: 4

    This parameter is the maximum number of collisions before the body stops moving. Setting it too low may prevent movement entirely.

  • floor_max_angle - 默认值: 0.785398 (以弧度表示，相当于 45 度)

    这是表面不再被视为“地板”之前的最大角度。

  • infinite_inertia - default value: true

When this parameter is true, the body can push RigidBody2D nodes, ignoring their mass, but won’t detect collisions with them. If it’s false the body will collide with rigid bodies and stop.

move_and_slide_with_snap

This method adds some additional functionality to move_and_slide() by adding the snap parameter. As long as this vector is in contact with the ground, the body will remain attached to the surface. Note that this means you must disable snapping when jumping, for example. You can do this either by setting snap to Vector2.ZERO or by using move_and_slide() instead.

Detecting collisions

When using move_and_collide() the function returns a KinematicCollision2D directly, and you can use this in your code.

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_count() and get_slide_collision():

GDScript

  1. # Using move_and_collide.
  2. var collision = move_and_collide(velocity * delta)
  3. if collision:
  4.     print("I collided with ", collision.collider.name)
  6. # Using move_and_slide.
  7. velocity = move_and_slide(velocity)
  8. for i in get_slide_count():
  9.     var collision = get_slide_collision(i)
  10.     print("I collided with ", collision.collider.name)

注解

get_slide_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’s “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:

../../_images/k2d_compare.gif

GDScript

C#

  1. # using move_and_collide
  2. var collision = move_and_collide(velocity * delta)
  3. if collision:
  4.     velocity = velocity.slide(collision.normal)
  6. # using move_and_slide
  7. velocity = move_and_slide(velocity)
  1. // using MoveAndCollide
  2. var collision = MoveAndCollide(velocity * delta);
  3. if (collision != null)
  4. {
  5.     velocity = velocity.Slide(collision.Normal);
  6. }
  7. // using MoveAndSlide
  8. velocity = MoveAndSlide(velocity);

您用 move_and_slide() 做的任何事情都可以用 move_and_collide() 来完成，但它可能需要更多的代码。 但是，正如我们在下面的示例中将看到的，有些情况下 move_and_slide() 不能提供您想要的响应。

In the example above, we assign the velocity that move_and_slide() returns back into 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 function returns the character’s new velocity that we can store in our velocity variable, and use on the next frame.

示例

要查看这些示例，请下载示例项目: using_kinematic2d.zip。

移动和墙壁

If you’ve downloaded the sample project, this example is in “BasicMovement.tscn”.

For this example, add a KinematicBody2D with two children: a Sprite and a CollisionShape2D. Use the Godot “icon.png” as the Sprite’s texture (drag it from the Filesystem dock to the Texture property of the Sprite). In the CollisionShape2D‘s Shape property, select “New RectangleShape2D” and size the rectangle to fit over the sprite image.

注解

有关实现2D移动方案的示例，请参阅 2D运动概述 。

将脚本附加到KinematicBody2D并添加以下代码:

GDScript

C#

  1. extends KinematicBody2D
  3. var speed = 250
  4. var velocity = Vector2()
  6. func get_input():
  7.     # Detect up/down/left/right keystate and only move when pressed.
  8.     velocity = Vector2()
  9.     if Input.is_action_pressed('ui_right'):
  10.         velocity.x += 1
  11.     if Input.is_action_pressed('ui_left'):
  12.         velocity.x -= 1
  13.     if Input.is_action_pressed('ui_down'):
  14.         velocity.y += 1
  15.     if Input.is_action_pressed('ui_up'):
  16.         velocity.y -= 1
  17.     velocity = velocity.normalized() * speed
  19. func _physics_process(delta):
  20.     get_input()
  21.     move_and_collide(velocity * delta)
  1. using Godot;
  2. using System;
  4. public class KBExample : KinematicBody2D
  5. {
  6.     public int Speed = 250;
  7.     private Vector2 _velocity = new Vector2();
  9.     public void GetInput()
  10.     {
  11.         // Detect up/down/left/right keystate and only move when pressed
  12.         _velocity = new Vector2();
  14.         if (Input.IsActionPressed("ui_right"))
  15.             _velocity.x += 1;
  17.         if (Input.IsActionPressed("ui_left"))
  18.             _velocity.x -= 1;
  20.         if (Input.IsActionPressed("ui_down"))
  21.             _velocity.y += 1;
  23.         if (Input.IsActionPressed("ui_up"))
  24.             _velocity.y -= 1;
  25.     }
  27.     public override void _PhysicsProcess(float delta)
  28.     {
  29.         GetInput();
  30.         MoveAndCollide(_velocity * delta);
  31.     }
  32. }

运行这个场景，您会看到 move_and_collide() 按预期工作，沿着速度向量方向移动物体。 现在让我们看看当您添加一些障碍时会发生什么。 添加一个具有矩形碰撞形状的 StaticBody2D 。 为了可见性，您可以使用精灵，Polygon2D，或从“调试”菜单中打开“可见碰撞形状”。

再次运行场景并尝试移动到障碍物中。 您会看到 KinematicBody2D 无法穿透障碍物。 但是，尝试以某个角度进入障碍物，您会发现障碍物就像胶水一样 - 感觉物体被卡住了。

发生这种情况是因为没有 碰撞响应 。 ``move_and_collide()``在碰撞发生时停止物体的运动。 我们需要编写我们想要的碰撞响应。

尝试将函数更改为 move_and_slide(velocity) 并再次运行。 请注意，我们从速度计算中删除了“delta”。

``move_and_slide()``提供了一个沿碰撞对象滑动物体的默认碰撞响应。 这对于许多游戏类型都很有用，并且可能是获得所需行为所需的全部内容。

弹跳/反射

如果您不想要滑动碰撞响应怎么办？ 对于这个示例(示例项目中的“BounceandCollide.tscn”)，我们有一个角色射击子弹，我们希望子弹从墙上反弹。

此示例使用三个场景。 主场景包含游戏角色和墙壁。 子弹和墙是单独的场景，以便它们可以实例化。

游戏角色由’w`和`s`键控制前进和后退。 瞄准使用鼠标指针。 这是游戏角色的代码，使用``move_and_slide()``:

GDScript

C#

  1. extends KinematicBody2D
  3. var Bullet = preload("res://Bullet.tscn")
  4. var speed = 200
  5. var velocity = Vector2()
  7. func get_input():
  8.     # Add these actions in Project Settings -> Input Map.
  9.     velocity = Vector2()
  10.     if Input.is_action_pressed('backward'):
  11.         velocity = Vector2(-speed/3, 0).rotated(rotation)
  12.     if Input.is_action_pressed('forward'):
  13.         velocity = Vector2(speed, 0).rotated(rotation)
  14.     if Input.is_action_just_pressed('mouse_click'):
  15.         shoot()
  17. func shoot():
  18.     # "Muzzle" is a Position2D placed at the barrel of the gun.
  19.     var b = Bullet.instance()
  20.     b.start($Muzzle.global_position, rotation)
  21.     get_parent().add_child(b)
  23. func _physics_process(delta):
  24.     get_input()
  25.     var dir = get_global_mouse_position() - global_position
  26.     # Don't move if too close to the mouse pointer.
  27.     if dir.length() > 5:
  28.         rotation = dir.angle()
  29.         velocity = move_and_slide(velocity)
  1. using Godot;
  2. using System;
  4. public class KBExample : KinematicBody2D
  5. {
  6.     private PackedScene _bullet = (PackedScene)GD.Load("res://Bullet.tscn");
  7.     public int Speed = 200;
  8.     private Vector2 _velocity = new Vector2();
  10.     public void GetInput()
  11.     {
  12.         // add these actions in Project Settings -> Input Map
  13.         _velocity = new Vector2();
  14.         if (Input.IsActionPressed("backward"))
  15.         {
  16.             _velocity = new Vector2(-Speed/3, 0).Rotated(Rotation);
  17.         }
  18.         if (Input.IsActionPressed("forward"))
  19.         {
  20.             _velocity = new Vector2(Speed, 0).Rotated(Rotation);
  21.         }
  22.         if (Input.IsActionPressed("mouse_click"))
  23.         {
  24.             Shoot();
  25.         }
  26.     }
  28.     public void Shoot()
  29.     {
  30.         // "Muzzle" is a Position2D placed at the barrel of the gun
  31.         var b = (Bullet)_bullet.Instance();
  32.         b.Start(GetNode<Node2D>("Muzzle").GlobalPosition, Rotation);
  33.         GetParent().AddChild(b);
  34.     }
  36.     public override void _PhysicsProcess(float delta)
  37.     {
  38.         GetInput();
  39.         var dir = GetGlobalMousePosition() - GlobalPosition;
  40.         // Don't move if too close to the mouse pointer
  41.         if (dir.Length() > 5)
  42.         {
  43.             Rotation = dir.Angle();
  44.             _velocity = MoveAndSlide(_velocity);
  45.         }
  46.     }
  47. }

子弹的代码:

GDScript

C#

  1. extends KinematicBody2D
  3. var speed = 750
  4. var velocity = Vector2()
  6. func start(pos, dir):
  7.     rotation = dir
  8.     position = pos
  9.     velocity = Vector2(speed, 0).rotated(rotation)
  11. func _physics_process(delta):
  12.     var collision = move_and_collide(velocity * delta)
  13.     if collision:
  14.         velocity = velocity.bounce(collision.normal)
  15.         if collision.collider.has_method("hit"):
  16.             collision.collider.hit()
  18. func _on_VisibilityNotifier2D_screen_exited():
  19.     queue_free()
  1. using Godot;
  2. using System;
  4. public class Bullet : KinematicBody2D
  5. {
  6.     public int Speed = 750;
  7.     private Vector2 _velocity = new Vector2();
  9.     public void Start(Vector2 pos, float dir)
  10.     {
  11.         Rotation = dir;
  12.         Position = pos;
  13.         _velocity = new Vector2(speed, 0).Rotated(Rotation);
  14.     }
  16.     public override void _PhysicsProcess(float delta)
  17.     {
  18.         var collision = MoveAndCollide(_velocity * delta);
  19.         if (collision != null)
  20.         {
  21.             _velocity = _velocity.Bounce(collision.Normal);
  22.             if (collision.Collider.HasMethod("Hit"))
  23.             {
  24.                 collision.Collider.Call("Hit");
  25.             }
  26.         }
  27.     }
  29.     public void OnVisibilityNotifier2DScreenExited()
  30.     {
  31.         QueueFree();
  32.     }
  33. }

The action happens in _physics_process(). After using move_and_collide(), if a collision occurs, a KinematicCollision2D object is returned (otherwise, the return is Nil).

如果有一个返回的碰撞，我们使用碰撞的 normal 来反映子弹的 velocity 和 Vector2.bounce() 方法。

如果碰撞对象( collider )有一个 hit 方法，我们也调用它。 在示例项目中，我们为墙壁添加了一个颜色闪烁效果来演示这一点。

../../_images/k2d_bullet_bounce.gif

平台运动

让我们尝试一个更流行的示例:2D平台游戏。 ``move_and_slide()``非常适合快速启动和运行功能字符控制器。 如果您已下载示例项目，可以在“Platformer.tscn”中找到它。

对于这个示例，我们假设您有一个由 StaticBody2D 对象构成的级别。 它们可以是任何形状和大小。 在示例项目中，我们使用 Polygon2D 来创建平台形状。

这是游戏角色物体的代码:

GDScript

C#

  1. extends KinematicBody2D
  3. export (int) var run_speed = 100
  4. export (int) var jump_speed = -400
  5. export (int) var gravity = 1200
  7. var velocity = Vector2()
  8. var jumping = false
  10. func get_input():
  11.     velocity.x = 0
  12.     var right = Input.is_action_pressed('ui_right')
  13.     var left = Input.is_action_pressed('ui_left')
  14.     var jump = Input.is_action_just_pressed('ui_select')
  16.     if jump and is_on_floor():
  17.         jumping = true
  18.         velocity.y = jump_speed
  19.     if right:
  20.         velocity.x += run_speed
  21.     if left:
  22.         velocity.x -= run_speed
  24. func _physics_process(delta):
  25.     get_input()
  26.     velocity.y += gravity * delta
  27.     if jumping and is_on_floor():
  28.         jumping = false
  29.     velocity = move_and_slide(velocity, Vector2(0, -1))
  1. using Godot;
  2. using System;
  4. public class KBExample : KinematicBody2D
  5. {
  6.     [Export] public int RunSpeed = 100;
  7.     [Export] public int JumpSpeed = -400;
  8.     [Export] public int Gravity = 1200;
  10.     Vector2 velocity = new Vector2();
  11.     bool jumping = false;
  13.     public void GetInput()
  14.     {
  15.         velocity.x = 0;
  16.         bool right = Input.IsActionPressed("ui_right");
  17.         bool left = Input.IsActionPressed("ui_left");
  18.         bool jump = Input.IsActionPressed("ui_select");
  20.         if (jump && IsOnFloor())
  21.         {
  22.             jumping = true;
  23.             velocity.y = JumpSpeed;
  24.         }
  26.         if (right)
  27.             velocity.x += RunSpeed;
  28.         if (left)
  29.             velocity.x -= RunSpeed;
  30.     }
  32.     public override void _PhysicsProcess(float delta)
  33.     {
  34.         GetInput();
  35.         velocity.y += Gravity * delta;
  36.         if (jumping && IsOnFloor())
  37.             jumping = false;
  38.         velocity = MoveAndSlide(velocity, new Vector2(0, -1));
  39.     }
  40. }

../../_images/k2d_platform.gif

When using move_and_slide(), the function returns a vector representing the movement that remained after the slide collision occurred. Setting that value back to the character’s velocity allows us to move up and down slopes smoothly. Try removing velocity = and see what happens if you don’t do this.

Also note that we’ve added Vector2(0, -1) as the floor normal. This vector points straight upward. As a result, if the character collides with an object that has this normal, it will be considered a floor.

Using the floor normal allows us to make jumping work, using is_on_floor(). This function will only return true after a move_and_slide() collision where the colliding body’s normal is within 45 degrees of the given floor vector. You can control the maximum angle by setting floor_max_angle.

This angle also allows you to implement other features like wall jumps using is_on_wall(), for example.