From 5b9cc8e29c4fe53316c684a26cedd1618fddb2a5 Mon Sep 17 00:00:00 2001 From: AGulev Date: Sat, 27 Jan 2024 21:10:48 +0100 Subject: [PATCH 1/4] add documentation for events --- docs/en/en.json | 4 ++ docs/en/manuals/physics-events.md | 95 +++++++++++++++++++++++++++++++ 2 files changed, 99 insertions(+) create mode 100644 docs/en/manuals/physics-events.md diff --git a/docs/en/en.json b/docs/en/en.json index 7ba62a07..d97e2274 100644 --- a/docs/en/en.json +++ b/docs/en/en.json @@ -929,6 +929,10 @@ "path": "/manuals/physics-messages", "name": "Collision messages" }, + { + "path": "/manuals/physics-events", + "name": "Collision events listener" + }, { "path": "/manuals/physics-resolving-collisions", "name": "Resolving collisions" diff --git a/docs/en/manuals/physics-events.md b/docs/en/manuals/physics-events.md new file mode 100644 index 00000000..a0d7216a --- /dev/null +++ b/docs/en/manuals/physics-events.md @@ -0,0 +1,95 @@ +--- +title: Collision events in Defold +brief: Collision event handling can be centralized by using `physics.set_listener()` to direct all collision and interaction messages to a single specified function. +--- + +# Defold Physics Event Handling + +Previously, physics interactions in Defold were handled by broadcasting messages to all components of colliding objects. However, starting with version 1.6.4, Defold offers a more centralized approach through the `physics.set_listener()` function. This function allows you to set a custom listener to handle all physics interaction events in one place, thereby streamlining your code and improving efficiency. + +## Setting the Physics World Listener + +To start using this new functionality, you need to use the `physics.set_listener` function. This function takes a callback as its argument, which will be called with information about all physics interactions in the world. The general syntax is as follows: + +```lua +physics.set_listener(function(self, event, data) + -- Event handling logic goes here +end) + +``` + +## Event Data Structure + +Each physics event provides a `data` table containing specific information relevant to the event. The structure of `a` and `b` objects within this data varies based on the event type: + +1. **Contact Point Event (`contact_point_event`):** +This event reports a contact point between two collision objects. It is useful for detailed collision handling, such as calculating impact forces or custom collision responses. + + - `applied_impulse`: The impulse resulting from the contact. + - `distance`: The penetration distance between the objects. + - `a` and `b`: Objects representing the colliding entities, each containing: + - `position`: World position (vector3). + - `id`: Instance ID (hash). + - `group`: Collision group (hash). + - `relative_velocity`: Velocity relative to the other object (vector3). + - `mass`: Mass in kilograms (number). + - `normal`: Contact normal, pointing from the other object (vector3). + +2. **Collision Event (`collision_event`):** +This event indicates that a collision has occurred between two objects. It is a more generalized event compared to the contact point event, ideal for detecting collisions without needing detailed information about the contact points. + + - `a` and `b`: Objects representing the colliding entities, each containing: + - `position`: World position (vector3). + - `id`: Instance ID (hash). + - `group`: Collision group (hash). + +3. **Trigger Event (`trigger_event`):** +This event is sent when an object interacts with a trigger object. It's useful for creating areas in your game that cause something to happen when an object enters or exits. + + - `enter`: Indicates if the interaction was an entry (true) or an exit (false). + - `a` and `b`: Objects involved in the trigger event, each containing: + - `id`: Instance ID (hash). + - `group`: Collision group (hash). + +4. **Ray Cast Response (`ray_cast_response`):** +This event is sent in response to a raycast, providing information about the object hit by the ray. + + - `group`: Collision group of the hit object (hash). + - `request_id`: Identifier of the raycast request (number). + - `position`: Hit position (vector3). + - `fraction`: The fraction of the ray's length at which the hit occurred (number). + - `normal`: Normal at the hit position (vector3). + - `id`: Instance ID of the hit object (hash). + +5. **Ray Cast Missed (`ray_cast_missed`):** +This event is sent when a raycast does not hit any object. + + - `request_id`: Identifier of the raycast request that missed (number). + +## Example Usage + +To utilize this new functionality, you can set up a listener function like so: + +```lua +local function physics_world_listener(self, event, data) + if event == hash("contact_point_event") then + -- Handle detailed contact point data + pprint(data) + elseif event == hash("collision_event") then + -- Handle general collision data + pprint(data) + elseif event == hash("trigger_event") then + -- Handle trigger interaction data + pprint(data) + elseif event == hash("ray_cast_response") then + -- Handle raycast hit data + pprint(data) + elseif event == hash("ray_cast_missed") then + -- Handle raycast miss data + pprint(data) + end +end + +function init(self) + physics.set_listener(physics_world_listener) +end From 466718bb561d185bb2cee15808de052f003ff094 Mon Sep 17 00:00:00 2001 From: Alexey Gulev Date: Sat, 27 Jan 2024 22:27:54 +0100 Subject: [PATCH 2/4] Update physics-events.md --- docs/en/manuals/physics-events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/manuals/physics-events.md b/docs/en/manuals/physics-events.md index a0d7216a..8de200a7 100644 --- a/docs/en/manuals/physics-events.md +++ b/docs/en/manuals/physics-events.md @@ -20,7 +20,7 @@ end) ## Event Data Structure -Each physics event provides a `data` table containing specific information relevant to the event. The structure of `a` and `b` objects within this data varies based on the event type: +Each physics event provides a `data` table containing specific information relevant to the event. 1. **Contact Point Event (`contact_point_event`):** This event reports a contact point between two collision objects. It is useful for detailed collision handling, such as calculating impact forces or custom collision responses. From 1e981af8c3fac94bc8e7515f7d91d74422661ff1 Mon Sep 17 00:00:00 2001 From: Alexey Gulev Date: Sat, 27 Jan 2024 22:30:24 +0100 Subject: [PATCH 3/4] Update physics-events.md --- docs/en/manuals/physics-events.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/en/manuals/physics-events.md b/docs/en/manuals/physics-events.md index 8de200a7..a21f16bf 100644 --- a/docs/en/manuals/physics-events.md +++ b/docs/en/manuals/physics-events.md @@ -68,8 +68,6 @@ This event is sent when a raycast does not hit any object. ## Example Usage -To utilize this new functionality, you can set up a listener function like so: - ```lua local function physics_world_listener(self, event, data) if event == hash("contact_point_event") then From f566f3cb1b002bfaa32b13e8fe4892d651eaab84 Mon Sep 17 00:00:00 2001 From: Alexey Gulev Date: Sun, 28 Jan 2024 07:30:20 +0100 Subject: [PATCH 4/4] Update physics-events.md --- docs/en/manuals/physics-events.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/en/manuals/physics-events.md b/docs/en/manuals/physics-events.md index a21f16bf..0ed2b4e3 100644 --- a/docs/en/manuals/physics-events.md +++ b/docs/en/manuals/physics-events.md @@ -91,3 +91,4 @@ end function init(self) physics.set_listener(physics_world_listener) end +```