Updates to physics manuals

docs/en/manuals/physics-joints.md

@@ -7,10 +7,10 @@ brief: Defold supports joints for 2D physics. This manual explains how to create
 
 Defold supports joints for 2D physics. A joint connects two collision objects using some kind of constraint. The supported joint types are:
 
-* Fixed (physics.JOINT_TYPE_FIXED) - A rope joint that restricts the maximum distance between two points. In Box2D referred to as a Rope joint.
-* Hinge (physics.JOINT_TYPE_HINGE) - A hinge joint specifies an anchor point on two collision objects and moves them so that the two collision objects are always in the same place, and the relative rotation of the collision objects is not restricted. The hinge joint can enable a motor with a defined maximum engine torque and speed. In Box2D referred to as a Revolute joint.
-* Spring (physics.JOINT_TYPE_SPRING) - A spring joint keeps two collision objects at a constant distance from each other. The spring joint can be made soft like a spring with a frequency and damping ratio. In Box2D referred to as a Distance joint.
-* Slider (physics.JOINT_TYPE_SLIDER) - A slider joint allows for relative translation of two collision objects along a specified axis and prevents relative rotation. In Box2D referred to as a Prismatic joint.
+* **Fixed (physics.JOINT_TYPE_FIXED)** - A rope joint that restricts the maximum distance between two points. In Box2D referred to as a Rope joint.
+* **Hinge (physics.JOINT_TYPE_HINGE)** - A hinge joint specifies an anchor point on two collision objects and moves them so that the two collision objects are always in the same place, and the relative rotation of the collision objects is not restricted. The hinge joint can enable a motor with a defined maximum engine torque and speed. In Box2D referred to as a Revolute joint.
+* **Spring (physics.JOINT_TYPE_SPRING)** - A spring joint keeps two collision objects at a constant distance from each other. The spring joint can be made soft like a spring with a frequency and damping ratio. In Box2D referred to as a Distance joint.
+* **Slider (physics.JOINT_TYPE_SLIDER)** - A slider joint allows for relative translation of two collision objects along a specified axis and prevents relative rotation. In Box2D referred to as a Prismatic joint.
 
 ## Creating joints
 
@@ -35,7 +35,7 @@ A joint can be destroyed using [`physics.destroy_joint()`](/ref/physics/#physics
 physics.destroy_joint("obj_a#collisionobject", "my_test_joint")
 ```
 
-## Reading from and Updating joints
+## Reading from and updating joints
 
 The properties of a joint can be read using [`physics.get_joint_properties()`](/ref/physics/#physics.get_joint_properties:collisionobject-joint_id) and set using [`physics.set_joint_properties()`](/ref/physics/#physics.set_joint_properties:collisionobject-joint_id-properties):
 

docs/en/manuals/physics-messages.md

@@ -22,6 +22,16 @@ The `"collision_response"` message is sent for all collision objects. It has the
 
 The collision_response message is only adequate to resolve collisions where you don't need any details on the actual intersection of the objects, for example if you want to detect if a bullet hits an enemy. There is only one of these messages sent for any colliding pair of objects each frame.
 
+```Lua
+function on_message(self, message_id, message, sender)
+    -- check for the message
+    if message_id == hash("collision_response") then
+        -- take action
+        print("I collided with", message.other_id)
+    end
+end
+```
+
 ## Contact point response
 
 The `"contact_point_response"` message is sent when one of the colliding objects is dynamic or kinematic. It has the following fields set:
@@ -61,6 +71,18 @@ The `"contact_point_response"` message is sent when one of the colliding objects
 
 For a game or application where you need to separate objects perfectly, the `"contact_point_response"` message gives you all information you need. However, note that for any given collision pair, several `"contact_point_response"` messages can be received each frame, depending on the nature of the collision. See [Resolving collisions for more information](/manuals/physics-resolving-collisions).
 
+```Lua
+function on_message(self, message_id, message, sender)
+    -- check for the message
+    if message_id == hash("contact_point_response") then
+        -- take action
+        if message.other_mass > 10 then
+            print("I collided with something weighing more than 10 kilos!")
+        end
+    end
+end
+```
+
 ## Trigger response
 
 The `"trigger_response"`  message is sent when a colliding object is of type "trigger".
@@ -73,3 +95,18 @@ In a trigger collision `"collision_response"` messages are sent. In addition, tr
 
 `enter`
 : `true` if the interaction was an entry into the trigger, `false` if it was an exit. (`boolean`).
+
+```Lua
+function on_message(self, message_id, message, sender)
+    -- check for the message
+    if message_id == hash("trigger_response") then
+        if message.enter then
+            -- take action for entry
+            print("I am now inside", message.other_id)
+        else
+            -- take action for exit
+            print("I am now outside", message.other_id)
+        end
+    end
+end
+```

docs/en/manuals/physics-objects.md

@@ -14,7 +14,7 @@ Dynamic objects
 : Dynamic objects are simulated by the physics engine. The engine solves all collisions and applies resulting forces. Dynamic objects are good for objects that should behave realistically but you *cannot* directly manipulate the position and orientation of a dynamic object. The only way to affect them is indirectly, by [applying forces](/ref/physics/#apply_force) or changing the angular [damping](/ref/stable/physics/#angular_damping) and [velocity](/ref/stable/physics/#linear_velocity) and the linear [damping](/ref/stable/physics/#linear_damping) and [velocity](/ref/stable/physics/#angular_velocity).
 
 Kinematic objects
-: Kinematic objects register collisions with other physics objects, but the physics engine do not perform any automatic simulation. The job of resolving collisions, or ignoring them, is left to you. Kinematic objects are very good for player or script controlled objects that require fine grained control of the physical reactions, like a player character.
+: Kinematic objects register collisions with other physics objects, but the physics engine do not perform any automatic simulation. The job of resolving collisions, or ignoring them, is left to you ([learn more](/manuals/physics-resolving-collisions)). Kinematic objects are very good for player or script controlled objects that require fine grained control of the physical reactions, like a player character.
 
 Triggers
 : Triggers are objects that register simple collisions. Triggers are light weight collision objects. They are similar to [ray casts](/manuals/physics-ray-cast) in that they read the physics world as opposed to interacting with it. They are good for objects that just need to register a hit (like a bullet) or as part of game logic where you want to trigger certain actions when an object reaches a specific point. Trigger are computationally cheaper than kinematic objects and should be used in favor of those if possible.
@@ -45,7 +45,7 @@ Id
 : The identity of the component.
 
 Collision Shape
-: This property is used for tile map geometry that does not use ordinary primitive shapes. See [Collision Shapes for more information](/manuals/physics-shapes).
+: This property is used for tile map geometry or convex shapes that does not use primitive shapes. See [Collision Shapes for more information](/manuals/physics-shapes).
 
 Type
 : The type of collision object: `Dynamic`, `Kinematic`, `Static` or `Trigger`. If you set the object to dynamic you _must_ set the *Mass* property to a non zero value. For dynamic or static objects you should also check that the *Friction* and *Restitution* values are good for your use-case.
@@ -56,7 +56,7 @@ Friction
   The friction strength is proportional to the normal force (this is called Coulomb friction). When the friction force is computed between two shapes (`A` and `B`), the friction values of both objects are combined by the geometric mean:
 
   $$
-  F_{combined} = \sqrt{ F_A \times F_B }
+  F = sqrt( F_A * F_B )
   $$
 
   This means that if one of the objects has zero friction then the contact between them will have zero friction.
@@ -67,7 +67,7 @@ Restitution
   Restitution values between two shapes (`A` and `B`) are combined using the following formula:
 
   $$
-  R = \max{ \left( R_A, R_B \right) }
+  R = max( R_A, R_B )
   $$
 
   When a shape develops multiple contacts, restitution is simulated approximately because Box2D uses an iterative solver. Box2D also uses inelastic collisions when the collision velocity is small to prevent bounce-jitter

docs/en/manuals/physics-ray-casts.md

@@ -5,7 +5,7 @@ brief: Ray casts are used to read the physics world along a linear ray. This man
 
 ## Ray casts
 
-Ray casts are used to read the physics world along a linear ray. To cast a ray into the physics world, you provide a start and end position as well as a set of collision groups to test against.
+Ray casts are used to read the physics world along a linear ray. To cast a ray into the physics world, you provide a start and end position as well as [a set of collision groups](/manuals/physics-groups) to test against.
 
 If the ray hits a physics object you will get information about the object it hit. Rays intersect with dynamic, kinematic and static objects. They do not interact with triggers.
 

docs/en/manuals/physics-resolving-collisions.md

@@ -40,7 +40,9 @@ Then the character has already been partially separated from *B*. The final comp
 
 ![Projection](images/physics/projection.png){srcset="images/physics/[email protected] 2x"}
 
-$$l = vmath.project(A, B) \times vmath.length(B)$$
+```
+l = vmath.project(A, B) * vmath.length(B)
+```
 
 The compensation vector can be found by reducing the length of *B* by *l*. To calculate this for an arbitrary number of penetrations, you can accumulate the necessary correction in a vector by, for each contact point, and starting with a zero length correction vector:
 

docs/en/manuals/physics-shapes.md

@@ -5,7 +5,12 @@ brief: A collision component can either use several primitive shapes or a single
 
 # Collision shapes
 
-A collision component can either use several primitive shapes or a single complex shape. The primitive shapes are *box*, *sphere* and *capsule*. A complex shape can either be created from a tilemap component or from a convex hull shape.
+A collision component can either use several primitive shapes or a single complex shape.
+
+### Primitive shapes
+The primitive shapes are *box*, *sphere* and *capsule*. You add a primitive shape by <kbd>right clicking</kbd> the collision object and selecting <kbd>Add Shape</kbd>:
+
+![Add a primitive shape](images/physics/add_shape.png)
 
 ## Box shape
 A box has a position, rotation and dimensions (width, height and depth):
@@ -22,6 +27,13 @@ A capsule has a position, rotation, diameter and height:
 
 ![Sphere shape](images/physics/capsule.png)
 
+::: important
+Capsule shapes are only supported when using 3D physics (configured in the Physics section of the *game.project* file).
+:::
+
+### Complex shapes
+A complex shape can either be created from a tilemap component or from a convex hull shape.
+
 ## Tilemap collision shape
 Defold includes a feature allowing you to easily generate physics shapes for a tile map. The [Tilemap manual](/manuals/tilemap/) explains how to add collision groups to a tile source and assign tiles to collision groups ([example](/examples/tilemap/collisions/)).
 
@@ -53,9 +65,11 @@ The shape will not be drawn in the editor. You can [enable Physics debugging](/m
 It is possible to let the collision object and its shapes inherit the scale of the game object. Check the [Allow Dynamic Transforms](/manuals/project-settings/#allow-dynamic-transforms) checkbox in the Physics section of *game.project* to enable this. Note that only uniform scaling is supported and that the smallest scale value will be used if the scale isn't uniform.
 
 
-# Rotating collision shapes in 3D physics
+# Rotating collision shapes
+
+## Rotating collision shapes in 3D physics
 Collision shapes in 3D physics can be rotated around all axis.
 
 
-# Rotating collision shapes in 2D physics
+## Rotating collision shapes in 2D physics
 Collision shapes in 2D physics can only be rotated around the z-axis. Rotation around the x or y axis will yield incorrect results and should be avoided, even when rotating 180 degrees to essentially flip the shape along the x or y axis. To flip a physics shape it is recommended to use [`physics.set_hlip(url, flip)`](/ref/stable/physics/?#physics.set_hflip:url-flip) and [`physics.set_vlip(url, flip)`](/ref/stable/physics/?#physics.set_vflip:url-flip).

docs/en/manuals/physics.md

@@ -9,19 +9,21 @@ Defold includes a modified version of the [Box2D](http://www.box2d.org) physics
 
 The main concepts of the physics engines used in Defold are:
 
-* Collision objects - A collision object is a component you use to give a game object physical behaviour. A collision object has physical properties like weight, friction and shape. [Learn how to create a collision object](/manuals/physics-objects).
-* Collision shapes - A collision object can either use several primitive shapes or a single complex shape to define its spatial extension. [Learn how to add shapes to a collision object](/manuals/physics-shapes).
-* Collision groups - All collision objects must belong to a predefined group and each collision object can specify a list of other groups it can collide with. [Learn how to use collision groups](/manuals/physics-groups).
-* Collision messages - When two collision objects collide the physics engine send messages to the game objects the components belong to. [Learn more about collision messages](/manuals/physics-messages)
+* **Collision objects** - A collision object is a component you use to give a game object physical behaviour. A collision object has physical properties like weight, friction and shape. [Learn how to create a collision object](/manuals/physics-objects).
+* **Collision shapes** - A collision object can either use several primitive shapes or a single complex shape to define its spatial extension. [Learn how to add shapes to a collision object](/manuals/physics-shapes).
+* **Collision groups** - All collision objects must belong to a predefined group and each collision object can specify a list of other groups it can collide with. [Learn how to use collision groups](/manuals/physics-groups).
+* **Collision messages** - When two collision objects collide the physics engine send messages to the game objects the components belong to. [Learn more about collision messages](/manuals/physics-messages)
 
-In addition to the collision objects themselves you can also define collision object constraints, more commonly known as joints, to connect two collision objects and limit or in other ways apply force and influence how they behave in the physics simulation. [Learn more about joins](/manuals/physics-joints).
+In addition to the collision objects themselves you can also define collision object **constraints**, more commonly known as **joints**, to connect two collision objects and limit or in other ways apply force and influence how they behave in the physics simulation. [Learn more about joins](/manuals/physics-joints).
 
-You can also probe and read the physics world along a linear ray know as ray casts. [Learn more about ray casts](/manuals/physics-ray-casts).
+You can also probe and read the physics world along a linear ray known as a **ray cast**. [Learn more about ray casts](/manuals/physics-ray-casts).
 
 
 ## Units used by the physics engine simulation
 
-The physics engine simulates Newtonian physics and it is designed to work well with meters, kilograms and seconds (MKS) units. Furthermore, the physics engine is tuned to work well with moving objects of a size in the 0.1 to 10 meters range (static objects can be larger) and by default the engine treats 1 unit (pixel) as 1 meter. This conversion between pixels and meters is convenient on a simulation level, but from a game creation perspective it isn't very useful. With default settings a collision shape with a size of 200 pixels would be treated as having a size of 200 meters which is well outside of the recommended range, at least for a moving object. In general it is required that the physics simulation is scaled for it to work well with the typical size of objects in a game. The scale of the physics simulation can be changed in `game.project` via the [physics scale setting](/manuals/project-settings/#physics). Setting this value to for instance 0.02 would mean that 200 pixels would be treated as a 4 meters. Do note that the gravity (also changed in `game.project`) has to be increased to accommodate for the change in scale.
+The physics engine simulates Newtonian physics and it is designed to work well with meters, kilograms and seconds (MKS) units. Furthermore, the physics engine is tuned to work well with moving objects of a size in the 0.1 to 10 meters range (static objects can be larger) and by default the engine treats 1 unit (pixel) as 1 meter. This conversion between pixels and meters is convenient on a simulation level, but from a game creation perspective it isn't very useful. With default settings a collision shape with a size of 200 pixels would be treated as having a size of 200 meters which is well outside of the recommended range, at least for a moving object.
+
+In general it is required that the physics simulation is scaled for it to work well with the typical size of objects in a game. The scale of the physics simulation can be changed in `game.project` via the [physics scale setting](/manuals/project-settings/#physics). Setting this value to for instance 0.02 would mean that 200 pixels would be treated as a 4 meters. Do note that the gravity (also changed in `game.project`) has to be increased to accommodate for the change in scale.
 
 
 ## Caveats and common issues