physics_introduction.rst 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506
  1. .. _doc_physics_introduction:
  2. Physics introduction
  3. ====================
  4. In game development, you often need to know when two objects in the game
  5. intersect or come into contact. This is known as **collision detection**.
  6. When a collision is detected, you typically want something to happen. This
  7. is known as **collision response**.
  8. Godot offers a number of collision objects in 2D and 3D to provide both collision detection
  9. and response. Trying to decide which one to use for your project can be confusing.
  10. You can avoid problems and simplify development if you understand how each works
  11. and what their pros and cons are.
  12. In this guide, you will learn:
  13. - Godot's four collision object types
  14. - How each collision object works
  15. - When and why to choose one type over another
  16. .. note:: This document's examples will use 2D objects. Every 2D physics object
  17. and collision shape has a direct equivalent in 3D and in most cases
  18. they work in much the same way.
  19. Collision objects
  20. -----------------
  21. Godot offers four kinds of collision objects which all extend :ref:`CollisionObject2D <class_CollisionObject2D>`.
  22. The last three listed below are physics bodies and additionally extend :ref:`PhysicsBody2D <class_PhysicsBody2D>`.
  23. - :ref:`Area2D <class_Area2D>`
  24. ``Area2D`` nodes provide **detection** and **influence**. They can detect when
  25. objects overlap and can emit signals when bodies enter or exit. An ``Area2D``
  26. can also be used to override physics properties, such as gravity or damping,
  27. in a defined area.
  28. - :ref:`StaticBody2D <class_StaticBody2D>`
  29. A static body is one that is not moved by the physics engine. It participates
  30. in collision detection, but does not move in response to the collision. They
  31. are most often used for objects that are part of the environment or that do
  32. not need to have any dynamic behavior.
  33. - :ref:`RigidBody2D <class_RigidBody2D>`
  34. This is the node that implements simulated 2D physics. You do not control a
  35. ``RigidBody2D`` directly, but instead you apply forces to it (gravity, impulses,
  36. etc.) and the physics engine calculates the resulting movement.
  37. :ref:`Read more about using rigid bodies. <doc_rigid_body>`
  38. - :ref:`CharacterBody2D <class_CharacterBody2D>`
  39. A body that provides collision detection, but no physics. All movement and
  40. collision response must be implemented in code.
  41. Physics material
  42. ~~~~~~~~~~~~~~~~
  43. Static bodies and rigid bodies can be configured to use a :ref:`PhysicsMaterial
  44. <class_PhysicsMaterial>`. This allows adjusting the friction and bounce of an object,
  45. and set if it's absorbent and/or rough.
  46. Collision shapes
  47. ~~~~~~~~~~~~~~~~
  48. A physics body can hold any number of :ref:`Shape2D <class_Shape2D>` objects
  49. as children. These shapes are used to define the object's collision bounds
  50. and to detect contact with other objects.
  51. .. note:: In order to detect collisions, at least one ``Shape2D`` must be
  52. assigned to the object.
  53. The most common way to assign a shape is by adding a :ref:`CollisionShape2D <class_CollisionShape2D>`
  54. or :ref:`CollisionPolygon2D <class_CollisionPolygon2D>` as a child of the object.
  55. These nodes allow you to draw the shape directly in the editor workspace.
  56. .. important:: Be careful to never scale your collision shapes in the editor.
  57. The "Scale" property in the Inspector should remain ``(1, 1)``. When changing
  58. the size of the collision shape, you should always use the size handles, **not**
  59. the ``Node2D`` scale handles. Scaling a shape can result in unexpected
  60. collision behavior.
  61. .. image:: img/player_coll_shape.png
  62. Physics process callback
  63. ~~~~~~~~~~~~~~~~~~~~~~~~
  64. The physics engine runs at a fixed rate (a default of 60 iterations per second). This rate
  65. is typically different from the frame rate which fluctuates based on what is rendered and
  66. available resources.
  67. It is important that all physics related code runs at this fixed rate. Therefore Godot
  68. differentiates :ref:`between physics and idle processing <doc_idle_and_physics_processing>`.
  69. Code that runs each frame is called idle processing and code that runs on each physics
  70. tick is called physics processing. Godot provides two different callbacks, one for each
  71. of those processing rates.
  72. The physics callback, :ref:`Node._physics_process() <class_Node_private_method__physics_process>`,
  73. is called before each physics step. Any code that needs to access a body's properties should
  74. be run in here. This method will be passed a ``delta``
  75. parameter, which is a floating-point number equal to the time passed in
  76. *seconds* since the last step. When using the default 60 Hz physics update rate,
  77. it will typically be equal to ``0.01666...`` (but not always, see below).
  78. .. note::
  79. It's recommended to always use the ``delta`` parameter when relevant in your
  80. physics calculations, so that the game behaves correctly if you change the
  81. physics update rate or if the player's device can't keep up.
  82. .. _doc_physics_introduction_collision_layers_and_masks:
  83. Collision layers and masks
  84. ~~~~~~~~~~~~~~~~~~~~~~~~~~
  85. One of the most powerful, but frequently misunderstood, collision features
  86. is the collision layer system. This system allows you to build up complex
  87. interactions between a variety of objects. The key concepts are **layers**
  88. and **masks**. Each ``CollisionObject2D`` has 32 different physics layers
  89. it can interact with.
  90. Let's look at each of the properties in turn:
  91. - collision_layer
  92. This describes the layers that the object appears **in**. By default, all
  93. bodies are on layer ``1``.
  94. - collision_mask
  95. This describes what layers the body will **scan** for collisions. If an
  96. object isn't in one of the mask layers, the body will ignore it. By default,
  97. all bodies scan layer ``1``.
  98. These properties can be configured via code, or by editing them in the Inspector.
  99. Keeping track of what you're using each layer for can be difficult, so you
  100. may find it useful to assign names to the layers you're using. Names can
  101. be assigned in Project Settings -> Layer Names.
  102. .. image:: img/physics_layer_names.png
  103. GUI example
  104. ^^^^^^^^^^^
  105. You have four node types in your game: Walls, Player, Enemy, and Coin. Both
  106. Player and Enemy should collide with Walls. The Player node should detect
  107. collisions with both Enemy and Coin, but Enemy and Coin should ignore each
  108. other.
  109. Start by naming layers 1-4 "walls", "player", "enemies", and "coins" and
  110. place each node type in its respective layer using the "Layer" property.
  111. Then set each node's "Mask" property by selecting the layers it should
  112. interact with. For example, the Player's settings would look like this:
  113. .. image:: img/player_collision_layers.png
  114. .. image:: img/player_collision_mask.png
  115. .. _doc_physics_introduction_collision_layer_code_example:
  116. Code example
  117. ^^^^^^^^^^^^
  118. In function calls, layers are specified as a bitmask. Where a function enables
  119. all layers by default, the layer mask will be given as ``0xffffffff``. Your code
  120. can use binary, hexadecimal, or decimal notation for layer masks, depending
  121. on your preference.
  122. The code equivalent of the above example where layers 1, 3 and 4 were enabled
  123. would be as follows::
  124. # Example: Setting mask value for enabling layers 1, 3 and 4
  125. # Binary - set the bit corresponding to the layers you want to enable (1, 3, and 4) to 1, set all other bits to 0.
  126. # Note: Layer 32 is the first bit, layer 1 is the last. The mask for layers 4,3 and 1 is therefore
  127. 0b00000000_00000000_00000000_00001101
  128. # (This can be shortened to 0b1101)
  129. # Hexadecimal equivalent (1101 binary converted to hexadecimal)
  130. 0x000d
  131. # (This value can be shortened to 0xd)
  132. # Decimal - Add the results of 2 to the power of (layer to be enabled - 1).
  133. # (2^(1-1)) + (2^(3-1)) + (2^(4-1)) = 1 + 4 + 8 = 13
  134. pow(2, 1-1) + pow(2, 3-1) + pow(2, 4-1)
  135. Area2D
  136. ------
  137. Area nodes provide **detection** and **influence**. They can detect when
  138. objects overlap and emit signals when bodies enter or exit. Areas can also
  139. be used to override physics properties, such as gravity or damping, in a
  140. defined area.
  141. There are three main uses for :ref:`Area2D <class_Area2D>`:
  142. - Overriding physics parameters (such as gravity) in a given region.
  143. - Detecting when other bodies enter or exit a region or what bodies are currently in a region.
  144. - Checking other areas for overlap.
  145. By default, areas also receive mouse and touchscreen input.
  146. StaticBody2D
  147. ------------
  148. A static body is one that is not moved by the physics engine. It participates
  149. in collision detection, but does not move in response to the collision. However,
  150. it can impart motion or rotation to a colliding body **as if** it were moving,
  151. using its ``constant_linear_velocity`` and ``constant_angular_velocity`` properties.
  152. ``StaticBody2D`` nodes are most often used for objects that are part of the environment
  153. or that do not need to have any dynamic behavior.
  154. Example uses for ``StaticBody2D``:
  155. - Platforms (including moving platforms)
  156. - Conveyor belts
  157. - Walls and other obstacles
  158. RigidBody2D
  159. -----------
  160. This is the node that implements simulated 2D physics. You do not control a
  161. :ref:`RigidBody2D <class_RigidBody2D>` directly. Instead, you apply forces
  162. to it and the physics engine calculates the resulting movement, including
  163. collisions with other bodies, and collision responses, such as bouncing,
  164. rotating, etc.
  165. You can modify a rigid body's behavior via properties such as "Mass",
  166. "Friction", or "Bounce", which can be set in the Inspector.
  167. The body's behavior is also affected by the world's properties, as set in
  168. `Project Settings -> Physics`, or by entering an :ref:`Area2D <class_Area2D>`
  169. that is overriding the global physics properties.
  170. When a rigid body is at rest and hasn't moved for a while, it goes to sleep.
  171. A sleeping body acts like a static body, and its forces are not calculated by
  172. the physics engine. The body will wake up when forces are applied, either by
  173. a collision or via code.
  174. Using RigidBody2D
  175. ~~~~~~~~~~~~~~~~~
  176. One of the benefits of using a rigid body is that a lot of behavior can be had
  177. "for free" without writing any code. For example, if you were making an
  178. "Angry Birds"-style game with falling blocks, you would only need to create
  179. RigidBody2Ds and adjust their properties. Stacking, falling, and bouncing would
  180. automatically be calculated by the physics engine.
  181. However, if you do wish to have some control over the body, you should take
  182. care - altering the ``position``, ``linear_velocity``, or other physics properties
  183. of a rigid body can result in unexpected behavior. If you need to alter any
  184. of the physics-related properties, you should use the :ref:`_integrate_forces() <class_RigidBody2D_private_method__integrate_forces>`
  185. callback instead of ``_physics_process()``. In this callback, you have access
  186. to the body's :ref:`PhysicsDirectBodyState2D <class_PhysicsDirectBodyState2D>`,
  187. which allows for safely changing properties and synchronizing them with
  188. the physics engine.
  189. For example, here is the code for an "Asteroids" style spaceship:
  190. .. tabs::
  191. .. code-tab:: gdscript GDScript
  192. extends RigidBody2D
  193. var thrust = Vector2(0, -250)
  194. var torque = 20000
  195. func _integrate_forces(state):
  196. if Input.is_action_pressed("ui_up"):
  197. state.apply_force(thrust.rotated(rotation))
  198. else:
  199. state.apply_force(Vector2())
  200. var rotation_direction = 0
  201. if Input.is_action_pressed("ui_right"):
  202. rotation_direction += 1
  203. if Input.is_action_pressed("ui_left"):
  204. rotation_direction -= 1
  205. state.apply_torque(rotation_direction * torque)
  206. .. code-tab:: csharp
  207. using Godot;
  208. public partial class Spaceship : RigidBody2D
  209. {
  210. private Vector2 _thrust = new Vector2(0, -250);
  211. private float _torque = 20000;
  212. public override void _IntegrateForces(PhysicsDirectBodyState2D state)
  213. {
  214. if (Input.IsActionPressed("ui_up"))
  215. state.ApplyForce(_thrust.Rotated(Rotation));
  216. else
  217. state.ApplyForce(new Vector2());
  218. var rotationDir = 0;
  219. if (Input.IsActionPressed("ui_right"))
  220. rotationDir += 1;
  221. if (Input.IsActionPressed("ui_left"))
  222. rotationDir -= 1;
  223. state.ApplyTorque(rotationDir * _torque);
  224. }
  225. }
  226. Note that we are not setting the ``linear_velocity`` or ``angular_velocity``
  227. properties directly, but rather applying forces (``thrust`` and ``torque``) to
  228. the body and letting the physics engine calculate the resulting movement.
  229. .. note:: When a rigid body goes to sleep, the ``_integrate_forces()``
  230. function will not be called. To override this behavior, you will
  231. need to keep the body awake by creating a collision, applying a
  232. force to it, or by disabling the :ref:`can_sleep <class_RigidBody2D_property_can_sleep>`
  233. property. Be aware that this can have a negative effect on performance.
  234. Contact reporting
  235. ~~~~~~~~~~~~~~~~~
  236. By default, rigid bodies do not keep track of contacts, because this can
  237. require a huge amount of memory if many bodies are in the scene. To enable
  238. contact reporting, set the :ref:`max_contacts_reported <class_RigidBody2D_property_max_contacts_reported>`
  239. property to a non-zero value. The contacts can then be obtained via
  240. :ref:`PhysicsDirectBodyState2D.get_contact_count() <class_PhysicsDirectBodyState2D_method_get_contact_count>`
  241. and related functions.
  242. Contact monitoring via signals can be enabled via the :ref:`contact_monitor <class_RigidBody2D_property_contact_monitor>`
  243. property. See :ref:`RigidBody2D <class_RigidBody2D>` for the list of available
  244. signals.
  245. CharacterBody2D
  246. ---------------
  247. :ref:`CharacterBody2D <class_CharacterBody2D>` bodies detect collisions with
  248. other bodies, but are not affected by physics properties like gravity or friction.
  249. Instead, they must be controlled by the user via code. The physics engine will
  250. not move a character body.
  251. When moving a character body, you should not set its ``position`` directly.
  252. Instead, you use the ``move_and_collide()`` or ``move_and_slide()`` methods.
  253. These methods move the body along a given vector, and it will instantly stop
  254. if a collision is detected with another body. After the body has collided,
  255. any collision response must be coded manually.
  256. Character collision response
  257. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  258. After a collision, you may want the body to bounce, to slide along a wall,
  259. or to alter the properties of the object it hit. The way you handle collision
  260. response depends on which method you used to move the CharacterBody2D.
  261. :ref:`move_and_collide <class_PhysicsBody2D_method_move_and_collide>`
  262. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  263. When using ``move_and_collide()``, the function returns a
  264. :ref:`KinematicCollision2D <class_KinematicCollision2D>` object, which contains
  265. information about the collision and the colliding body. You can use this
  266. information to determine the response.
  267. For example, if you want to find the point in space where the collision
  268. occurred:
  269. .. tabs::
  270. .. code-tab:: gdscript GDScript
  271. extends PhysicsBody2D
  272. var velocity = Vector2(250, 250)
  273. func _physics_process(delta):
  274. var collision_info = move_and_collide(velocity * delta)
  275. if collision_info:
  276. var collision_point = collision_info.get_position()
  277. .. code-tab:: csharp
  278. using Godot;
  279. public partial class Body : PhysicsBody2D
  280. {
  281. private Vector2 _velocity = new Vector2(250, 250);
  282. public override void _PhysicsProcess(double delta)
  283. {
  284. var collisionInfo = MoveAndCollide(_velocity * (float)delta);
  285. if (collisionInfo != null)
  286. {
  287. var collisionPoint = collisionInfo.GetPosition();
  288. }
  289. }
  290. }
  291. Or to bounce off of the colliding object:
  292. .. tabs::
  293. .. code-tab:: gdscript GDScript
  294. extends PhysicsBody2D
  295. var velocity = Vector2(250, 250)
  296. func _physics_process(delta):
  297. var collision_info = move_and_collide(velocity * delta)
  298. if collision_info:
  299. velocity = velocity.bounce(collision_info.get_normal())
  300. .. code-tab:: csharp
  301. using Godot;
  302. public partial class Body : PhysicsBody2D
  303. {
  304. private Vector2 _velocity = new Vector2(250, 250);
  305. public override void _PhysicsProcess(double delta)
  306. {
  307. var collisionInfo = MoveAndCollide(_velocity * (float)delta);
  308. if (collisionInfo != null)
  309. _velocity = _velocity.Bounce(collisionInfo.GetNormal());
  310. }
  311. }
  312. :ref:`move_and_slide <class_CharacterBody2D_method_move_and_slide>`
  313. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  314. Sliding is a common collision response; imagine a player moving along walls
  315. in a top-down game or running up and down slopes in a platformer. While it's
  316. possible to code this response yourself after using ``move_and_collide()``,
  317. ``move_and_slide()`` provides a convenient way to implement sliding movement
  318. without writing much code.
  319. .. warning:: ``move_and_slide()`` automatically includes the timestep in its
  320. calculation, so you should **not** multiply the velocity vector
  321. by ``delta``.
  322. For example, use the following code to make a character that can walk along
  323. the ground (including slopes) and jump when standing on the ground:
  324. .. tabs::
  325. .. code-tab:: gdscript GDScript
  326. extends CharacterBody2D
  327. var run_speed = 350
  328. var jump_speed = -1000
  329. var gravity = 2500
  330. func get_input():
  331. velocity.x = 0
  332. var right = Input.is_action_pressed('ui_right')
  333. var left = Input.is_action_pressed('ui_left')
  334. var jump = Input.is_action_just_pressed('ui_select')
  335. if is_on_floor() and jump:
  336. velocity.y = jump_speed
  337. if right:
  338. velocity.x += run_speed
  339. if left:
  340. velocity.x -= run_speed
  341. func _physics_process(delta):
  342. velocity.y += gravity * delta
  343. get_input()
  344. move_and_slide()
  345. .. code-tab:: csharp
  346. using Godot;
  347. public partial class Body : CharacterBody2D
  348. {
  349. private float _runSpeed = 350;
  350. private float _jumpSpeed = -1000;
  351. private float _gravity = 2500;
  352. private void GetInput()
  353. {
  354. var velocity = Velocity;
  355. velocity.X = 0;
  356. var right = Input.IsActionPressed("ui_right");
  357. var left = Input.IsActionPressed("ui_left");
  358. var jump = Input.IsActionPressed("ui_select");
  359. if (IsOnFloor() && jump)
  360. velocity.Y = _jumpSpeed;
  361. if (right)
  362. velocity.X += _runSpeed;
  363. if (left)
  364. velocity.X -= _runSpeed;
  365. Velocity = velocity;
  366. }
  367. public override void _PhysicsProcess(double delta)
  368. {
  369. var velocity = Velocity;
  370. velocity.Y += _gravity * (float)delta;
  371. Velocity = velocity;
  372. GetInput();
  373. MoveAndSlide();
  374. }
  375. }
  376. See :ref:`doc_kinematic_character_2d` for more details on using ``move_and_slide()``,
  377. including a demo project with detailed code.