Add explicit compound triggers instead of implicit ones (#206)

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.
+A useful construct in a physics engine is a non-solid volume of space which does not generate impulses when overlapping with other volumes. These objects are typically called "triggers", "sensors", "phantoms", or "overlap volumes" in physics simulation engines. Triggers allow specifying such volumes either as a single shape or combination of nodes with shapes.
 
-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 trigger is added to a glTF node by specifying the `"trigger"` property inside of a node's `"OMI_physics_body"` extension.
+
+A `"trigger"` may specify a `"shape"` property which references a geometric shape defined by the `OMI_physics_shape` extension. Alternatively, a `"trigger"` may have a `"nodes"` property, which is an array of glTF nodes which make up a compound trigger on this glTF node. The nodes in this array must be descendent nodes which must have `"trigger"` properties. At least one of `"shape"` or `"nodes"` must be set to a valid value.
+
+As the name "trigger" suggests, implementations may use these shapes as sensors that generate overlap events, which can be used to trigger things. 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] }]
+}