Add explicit compound triggers instead of implicit ones

extensions/2.0/OMI_physics_body/README.trigger.md

@@ -1,18 +1,29 @@
 # OMI_physics_body Trigger Property
 
-If a node has the `"trigger"` property defined, it has a non-solid trigger shape that can detect when objects enter it.
+If a node has the `"trigger"` property defined, it has a non-solid trigger shape that can be used as a sensor to detect when objects enter it. At least one of `"shape"` or `"nodes"` must be set to a valid value.
 
-Triggers are not solid and do not "collide" with other objects, but can generate events when another physics body "enters" them. For example, a "goal" area which triggers whenever a ball gets thrown into it.
+A useful construct in a physics engine is a non-solid volume of space which does not generate impulses when overlapping with other volumes. Triggers allow specifying such volumes, as a single shape, or combination of nodes with shapes.
+
+As the name "trigger" suggests, implementations may use these shapes as sensors that generate events, which can be used to trigger application-specific logic. These objects are typically called "triggers", "sensors", "phantoms", or "overlap volumes" in physics simulation engines.
+
+For example, a trigger may be used to define a "goal" area which triggers whenever a ball gets thrown into it. What behavior gets triggered is outside the scope of this extension, but may be defined in other glTF extensions or application-specific logic.
 
 ## Trigger Properties
 
-|           | Type      | Description                                         | Default value |
-| --------- | --------- | --------------------------------------------------- | ------------- |
-| **shape** | `integer` | The index of the shape to use as the trigger shape. | -1            |
+|           | Type        | Description                                                                                                         | Default value |
+| --------- | ----------- | ------------------------------------------------------------------------------------------------------------------- | ------------- |
+| **shape** | `integer`   | The index of the shape to use as the trigger shape.                                                                 | -1            |
+| **nodes** | `integer[]` | For compound triggers, the set of descendant glTF nodes with a trigger property that make up this compound trigger. | []            |
 
 ### Shape
 
-The `"shape"` property is an integer index that references a shape in the document-level shapes array as defined by the `OMI_physics_shape` extension. If not specified or -1, this node has no trigger shape, but may be the parent of other nodes that do have trigger shapes, and should combine those nodes into one trigger (this may be a body or compound trigger depending on the engine).
+The `"shape"` property is an integer index that references a shape in the document-level shapes array as defined by the `OMI_physics_shape` extension. If not specified or -1, this node has no trigger shape, but may have `"nodes"` defined to create a compound trigger.
+
+### Nodes
+
+The `"nodes"` property is an array of integer indices that reference descendant glTF nodes with a trigger property, which make up a compound trigger on this glTF node. If not specified or empty, this node is not a compound trigger.
+
+When this property is set and contains valid items, this indicates that this glTF node is a compound trigger. Each item is the index of a glTF node that must have its own OMI_physics_body trigger property, and must be a descendant of this node.
 
 ## JSON Schema
 

extensions/2.0/OMI_physics_body/examples/basic/compound_trigger.gltf

@@ -0,0 +1,72 @@
+{
+    "asset": {
+        "version": "2.0"
+    },
+    "extensionsUsed": ["OMI_physics_body", "OMI_physics_shape"],
+    "extensions": {
+        "OMI_physics_shape": {
+            "shapes": [
+                {
+                    "type": "box",
+                    "box": {
+                        "size": [3, 1, 1]
+                    }
+                },
+                {
+                    "type": "box",
+                    "box": {
+                        "size": [1, 3, 1]
+                    }
+                }
+            ]
+        }
+    },
+    "nodes": [
+        {
+            "children": [1, 2, 3],
+            "extensions": {
+                "OMI_physics_body": {
+                    "trigger": {
+                        "nodes": [1, 2]
+                    }
+                }
+            },
+            "name": "CompoundTriggerL"
+        },
+        {
+            "extensions": {
+                "OMI_physics_body": {
+                    "trigger": {
+                        "shape": 0
+                    }
+                }
+            },
+            "name": "BottomOfL",
+            "translation": [1, 0, 0]
+        },
+        {
+            "extensions": {
+                "OMI_physics_body": {
+                    "trigger": {
+                        "shape": 1
+                    }
+                }
+            },
+            "name": "TopOfL",
+            "translation": [0, 2, 0]
+        },
+        {
+            "extensions": {
+                "OMI_physics_body": {
+                    "trigger": {
+                        "shape": 0
+                    }
+                }
+            },
+            "name": "SeparateTrigger",
+            "translation": [0, 0, 4]
+        }
+    ],
+    "scene": 0,
+    "scenes": [{ "nodes": [0] }]
+}

extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.trigger.schema.json

@@ -17,6 +17,15 @@
             ],
             "default": -1
         },
+        "nodes": {
+            "type": "array",
+            "description": "For compound triggers, the set of descendant glTF nodes with a trigger property that make up this compound trigger.",
+            "items": {
+                "$ref": "glTFid.schema.json"
+            },
+            "uniqueItems": true,
+            "minItems": 1
+        },
         "extensions": { },
         "extras": { }
     }