From ef7a655f45acf9199248e09e463a6d4c3ab1d7d6 Mon Sep 17 00:00:00 2001 From: Aaron Franke Date: Tue, 9 Jul 2024 01:13:11 -0700 Subject: [PATCH] Add materials and filtering similar to KHR/MSFT physics --- .../2.0/Archived/OMI_collider/README.md | 30 ++++----- .../2.0/OMI_physics_body/README.collider.md | 67 ++++++++++++++++++- extensions/2.0/OMI_physics_body/README.md | 67 +++++++++++++------ .../2.0/OMI_physics_body/README.motion.md | 31 +++++---- .../2.0/OMI_physics_body/README.trigger.md | 47 +++++++++++-- ..._physics_body.collision_filter.schema.json | 36 ++++++++++ ...glTF.OMI_physics_body.material.schema.json | 40 +++++++++++ .../schema/glTF.OMI_physics_body.schema.json | 28 ++++++++ ...node.OMI_physics_body.collider.schema.json | 14 +++- .../node.OMI_physics_body.motion.schema.json | 35 +++++++--- .../schema/node.OMI_physics_body.schema.json | 19 +++--- .../node.OMI_physics_body.trigger.schema.json | 18 ++--- extensions/2.0/OMI_physics_joint/README.md | 10 +-- .../schema/glTF.OMI_physics_shape.schema.json | 2 +- ...TF.OMI_physics_shape.shape.box.schema.json | 2 +- ...MI_physics_shape.shape.capsule.schema.json | 2 +- ...OMI_physics_shape.shape.convex.schema.json | 2 +- ...I_physics_shape.shape.cylinder.schema.json | 2 +- .../glTF.OMI_physics_shape.shape.schema.json | 2 +- ...OMI_physics_shape.shape.sphere.schema.json | 2 +- ...MI_physics_shape.shape.trimesh.schema.json | 2 +- .../OMI_seat/schema/node.OMI_seat.schema.json | 2 +- .../schema/node.OMI_spawn_point.schema.json | 2 +- 23 files changed, 358 insertions(+), 104 deletions(-) create mode 100644 extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.collision_filter.schema.json create mode 100644 extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.material.schema.json create mode 100644 extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.schema.json diff --git a/extensions/2.0/Archived/OMI_collider/README.md b/extensions/2.0/Archived/OMI_collider/README.md index 8c48d1f..06e6771 100644 --- a/extensions/2.0/Archived/OMI_collider/README.md +++ b/extensions/2.0/Archived/OMI_collider/README.md @@ -2,13 +2,13 @@ ## Contributors -* Aaron Franke, The Mirror Megaverse Inc. -* Robert Long, The Matrix.org Foundation -* Mauve Signweaver, Mauve Software Inc. +- Aaron Franke, The Mirror Megaverse Inc. +- Robert Long, The Matrix.org Foundation +- Mauve Signweaver, Mauve Software Inc. ## Status -Open Metaverse Interoperability Group Stage 2 Proposal +Archived ## Dependencies @@ -145,17 +145,17 @@ See [schema/glTF.OMI_collider.collider.schema.json](schema/glTF.OMI_collider.col ## Known Implementations -* Godot Engine: https://github.com/godotengine/godot/pull/69266 -* Third Room Unity Exporter: https://github.com/matrix-org/thirdroom-unity-exporter/blob/main/Runtime/Scripts/OMI_collider/OMI_ColliderExtension.cs -* Third Room glTF Transform: https://github.com/matrix-org/thirdroom/blob/main/src/asset-pipeline/extensions/OMIColliderExtension.ts -* Third Room glTF Loader: https://github.com/matrix-org/thirdroom/blob/main/src/engine/gltf/OMI_collider.ts -* Three Object Viewer WordPress Plugin: https://github.com/antpb/three-object-viewer/ +- Godot Engine: https://github.com/godotengine/godot/pull/69266 +- Third Room Unity Exporter: https://github.com/matrix-org/thirdroom-unity-exporter/blob/main/Runtime/Scripts/OMI_collider/OMI_ColliderExtension.cs +- Third Room glTF Transform: https://github.com/matrix-org/thirdroom/blob/main/src/asset-pipeline/extensions/OMIColliderExtension.ts +- Third Room glTF Loader: https://github.com/matrix-org/thirdroom/blob/main/src/engine/gltf/OMI_collider.ts +- Three Object Viewer WordPress Plugin: https://github.com/antpb/three-object-viewer/ ## Resources: -* Godot Shapes: https://docs.godotengine.org/en/latest/classes/class_shape3d.html -* Unity Colliders: https://docs.unity3d.com/Manual/CollidersOverview.html -* Unreal Engine Collision Shapes: https://docs.unrealengine.com/4.27/en-US/API/Runtime/PhysicsCore/FCollisionShape/ -* Unreal Engine Mesh Collisions: https://docs.unrealengine.com/4.27/en-US/WorkingWithContent/Types/StaticMeshes/HowTo/SettingCollision/ -* Blender Collisions: https://docs.blender.org/manual/en/latest/physics/rigid_body/properties/collisions.html -* Mozilla Hubs ammo-shape: https://github.com/MozillaReality/hubs-blender-exporter/blob/bb28096159e1049b6b80da00b1ae1534a6ca0855/default-config.json#L608 +- Godot Shapes: https://docs.godotengine.org/en/latest/classes/class_shape3d.html +- Unity Colliders: https://docs.unity3d.com/Manual/CollidersOverview.html +- Unreal Engine Collision Shapes: https://docs.unrealengine.com/4.27/en-US/API/Runtime/PhysicsCore/FCollisionShape/ +- Unreal Engine Mesh Collisions: https://docs.unrealengine.com/4.27/en-US/WorkingWithContent/Types/StaticMeshes/HowTo/SettingCollision/ +- Blender Collisions: https://docs.blender.org/manual/en/latest/physics/rigid_body/properties/collisions.html +- Mozilla Hubs ammo-shape: https://github.com/MozillaReality/hubs-blender-exporter/blob/bb28096159e1049b6b80da00b1ae1534a6ca0855/default-config.json#L608 diff --git a/extensions/2.0/OMI_physics_body/README.collider.md b/extensions/2.0/OMI_physics_body/README.collider.md index e0adf0e..23fe6c7 100644 --- a/extensions/2.0/OMI_physics_body/README.collider.md +++ b/extensions/2.0/OMI_physics_body/README.collider.md @@ -4,14 +4,75 @@ If a node has the `"collider"` property defined, it is a solid collider node tha ## Collider Properties -| | Type | Description | Default value | -| --------- | --------- | ----------------------------------------------------- | ------------- | -| **shape** | `integer` | The index of the shape to use as the collision shape. | -1 | +| | Type | Description | Default value | +| ------------------- | --------- | ---------------------------------------------------------------------------- | ------------- | +| **shape** | `integer` | The index of the shape to use as the collision shape. | -1 | +| **physicsMaterial** | `integer` | The index of the physics material in the top level physicsMaterials array. | -1 | +| **collisionFilter** | `integer` | The index of the filter information in the top level collisionFilters array. | -1 | ### 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 collider shape, but may be the parent of other nodes that do have collider shapes, and can combine those nodes into one collider (this may be a body or compound collider depending on the engine). +### Physics Material + +The `"physicsMaterial"` property is an integer index that references a physics material in the document-level physicsMaterials array in the `OMI_physics_body` extension. If not specified or -1, the default physics material is used. + +Physics materials define the physical properties of a surface in a physics simulation, which affect how objects respond when they collide with it. See the below [Physics Material Properties](#physics-material-properties) section for more information. + +### Collision Filter + +The `"collisionFilter"` property is an integer index that references a collision filter in the document-level collisionFilters array in the `OMI_physics_body` extension. If not specified or -1, the default collision filter is used. + +Collision filters are used to determine which objects can collide with each other. A collision filter includes a set of collision systems (the "collision layer" the object is on), and a set of collision systems to collide with or to ignore (the "collision mask" of the object). See the [README.trigger.md](README.trigger.md) file for more information on collision filters. + +## Physics Material Properties + +The following properties may be defined in a physics material in the top-level `physicsMaterials` array: + +| | Type | Description | Default value | +| ---------------------- | -------- | ------------------------------------------------------------------------ | ------------- | +| **staticFriction** | `number` | The friction used when an object is laying still on a surface. | 0.6 | +| **dynamicFriction** | `number` | The friction used when already moving. | 0.6 | +| **restitution** | `number` | How bouncy is the surface? | 0.0 | +| **frictionCombine** | `string` | Determines how friction should be combined when two objects interact. | `"average"` | +| **restitutionCombine** | `string` | Determines how restitution should be combined when two objects interact. | `"average"` | + +### Static Friction + +The `"staticFriction"` property is a number that represents the friction used when an object is laying still on a surface. Typically on a range of 0.0 to 1.0. If not specified, the default value is 0.6. + +A value of 0.0 feels like ice, a value of 1.0 will make it very hard to get an object moving. Physics simulations which do not differentiate between static and dynamic friction should use the dynamic friction value. + +### Dynamic Friction + +The `"dynamicFriction"` property is a number that represents the friction used when already moving. Typically on a range of 0.0 to 1.0. If not specified, the default value is 0.6. + +A value of 0.0 feels like ice, a value of 1.0 will make an object come to rest very quickly unless a lot of force or gravity pushes the object. Physics simulations which do not differentiate between static and dynamic friction should use the dynamic friction value. + +### Restitution + +The `"restitution"` property is a number that represents how bouncy the surface is. Typically on a range of 0.0 to 1.0. If not specified, the default value is 0.0, which means the surface is not bouncy at all. + +### Friction Combine + +The `"frictionCombine"` property is a string that determines how friction should be combined when two objects interact. If not specified, the default value is `"average"`. + +### Restitution Combine + +The `"restitutionCombine"` property is a string that determines how restitution should be combined when two objects interact. If not specified, the default value is `"average"`. + +When a pair of physics materials interact during a simulation step, the applied friction and restitution values are based on their "combine" policies: + +- If either uses `"average"`: The two values should be averaged. +- Else if either uses `"minimum"`: The smallest of the two values should be used. +- Else if either uses `"maximum"`: The largest of the two values should be used. +- Else if either uses `"multiply"`: The two values should be multiplied with each other. + ## JSON Schema See [schema/node.OMI_physics_body.collider.schema.json](schema/node.OMI_physics_body.collider.schema.json) for the collider properties JSON schema. + +See [schema/glTF.OMI_physics_body.material.schema.json](schema/glTF.OMI_physics_body.material.schema.json) for the physics material properties JSON schema. + +See [schema/glTF.OMI_physics_body.collision_filter.schema.json](schema/glTF.OMI_physics_body.collision_filter.schema.json) for the collision filter properties JSON schema. diff --git a/extensions/2.0/OMI_physics_body/README.md b/extensions/2.0/OMI_physics_body/README.md index 9dc37da..608bf53 100644 --- a/extensions/2.0/OMI_physics_body/README.md +++ b/extensions/2.0/OMI_physics_body/README.md @@ -2,8 +2,8 @@ ## Contributors -* Aaron Franke, The Mirror Megaverse Inc. -* Mauve Signweaver, Mauve Software Inc. +- Aaron Franke, Godot Engine. +- Mauve Signweaver, Mauve Software Inc. ## Status @@ -25,7 +25,7 @@ If a node with a collider shape does not have a motion property on itself or an ### Example: -This example defines a static body node which has a single box collider as a child: +This example defines a physics node with dynamic motion and a single box collider: ```json { @@ -74,7 +74,7 @@ More example assets can be found in the [examples/](examples/) folder. All of th ## glTF Schema Updates -This extension consists of a new `OMI_physics_body` data structure which can be added to a glTF node. +This extension consists of a new `OMI_physics_body` data structure which can be added to a glTF node, and a new `OMI_physics_body` data structure that can be added to the glTF document to define resources for nodes to use, such as collision filters and physics materials. The extension must also be added to the glTF's `extensionsUsed` array and because it is optional, it does not need to be added to the `extensionsRequired` array. @@ -82,11 +82,13 @@ The extension is intended to be used together with `OMI_physics_shape`, which de ### Property Summary -| | Type | Description | Default value | -| ------------ | ---- | ------------------------------------------------------------ | ------------- | -| **motion** | JSON | If present, this node has its motion controlled by physics. | `null` | -| **collider** | JSON | If present, this node is solid and can be collided with. | `null` | -| **trigger** | JSON | If present, this node is non-solid and can act as a trigger. | `null` | +This table defines properties that can exist on glTF nodes inside of the `OMI_physics_body` extension: + +| | Type | Description | Default value | +| ------------ | ---- | ---------------------------------------------------------------------- | ------------- | +| **motion** | JSON | If present, this node has its motion controlled by physics. | `null` | +| **collider** | JSON | If present, this node has a solid shape that can be collided with. | `null` | +| **trigger** | JSON | If present, this node has a non-solid shape that can act as a trigger. | `null` | Each of these properties are recommended to be defined on separate nodes. This results in a very clear, simple, and portable document structure, and ensures that each behavior has its own transform. However, they may also be all defined on the same node. Implementations must support all of these cases in order to be compliant. @@ -100,31 +102,52 @@ The list of motion properties and their details can be found in the [README.moti If a node has the `"collider"` property defined, it is a solid collider node that objects can collide with. -The list of collider properties and their details can be found in the [README.collider.md](README.collider.md) file. +The list of collider properties and their details can be found in the [README.collider.md](README.collider.md) file. Nodes with a `"collider"` property may have a physics material, which is detailed in the [README.collider.md](README.collider.md) file. Nodes with a `"collider"` property may have a collision filter, which is detailed in a separate file, the [README.trigger.md](README.trigger.md) file. #### Trigger If a node has the `"trigger"` property defined, it is a non-solid trigger that can detect when objects enter it. -The list of trigger properties and their details can be found in the [README.trigger.md](README.trigger.md) file. +The list of trigger properties and their details can be found in the [README.trigger.md](README.trigger.md) file. Nodes with a `"trigger"` property may have a collision filter, which is detailed in the [README.trigger.md](README.trigger.md) file. + +### Document-level Property Summary + +In addition, the following properties may be defined at the glTF document level in `OMI_physics_body` to define resources that nodes can use: + +| | Type | Description | Default value | +| -------------------- | ----- | ------------------------------------------ | ------------- | +| **collisionFilters** | Array | An array of physics materials. | [] | +| **physicsMaterials** | Array | An array of collision filter descriptions. | [] | + +For more details on collision filters, see the [README.trigger.md](README.trigger.md) file. + +For more details on physics materials, see the [README.collider.md](README.collider.md) file. ### JSON Schema See [node.OMI_physics_body.schema.json](schema/node.OMI_physics_body.schema.json) for the main node schema, and these for the sub-JSON property schemas: -* Motion: [node.OMI_physics_body.motion.schema.json](schema/node.OMI_physics_body.motion.schema.json) -* Collider: [node.OMI_physics_body.collider.schema.json](schema/node.OMI_physics_body.collider.schema.json) -* Trigger: [node.OMI_physics_body.trigger.schema.json](schema/node.OMI_physics_body.trigger.schema.json) + +- Motion: [node.OMI_physics_body.motion.schema.json](schema/node.OMI_physics_body.motion.schema.json) +- Collider: [node.OMI_physics_body.collider.schema.json](schema/node.OMI_physics_body.collider.schema.json) +- Trigger: [node.OMI_physics_body.trigger.schema.json](schema/node.OMI_physics_body.trigger.schema.json) +- Document-level: [glTF.OMI_physics_body.schema.json](schema/glTF.OMI_physics_body.schema.json) +- Collision Filter: [glTF.OMI_physics_body.collision_filter.schema.json](schema/glTF.OMI_physics_body.collision_filter.schema.json) +- Physics Material: [glTF.OMI_physics_body.material.schema.json](schema/glTF.OMI_physics_body.material.schema.json) ## Known Implementations -* Godot Engine: https://github.com/godotengine/godot/pull/78967 +- Godot Engine: https://github.com/godotengine/godot/pull/78967 ## Resources: -* Unity colliders: https://docs.unity3d.com/Manual/CollidersOverview.html -* Unreal Engine Physics: https://docs.unrealengine.com/4.27/en-US/InteractiveExperiences/Physics/Collision/Overview/ -* Godot Physics Body: https://docs.godotengine.org/en/stable/classes/class_physicsbody.html -* Godot Area: https://docs.godotengine.org/en/stable/classes/class_area.html -* Godot RigidBody3D: https://docs.godotengine.org/en/latest/classes/class_rigidbody3d.html -* Wikipedia Moment of Inertia: https://en.wikipedia.org/wiki/Moment_of_inertia -* Wikipedia Rigid Body Dynamics: https://en.wikipedia.org/wiki/Rigid_body_dynamics +- Unity Colliders: https://docs.unity3d.com/Manual/CollidersOverview.html +- Unity PhysicMaterial: https://docs.unity3d.com/Manual/class-PhysicMaterial.html +- Unity Physics Layers: https://docs.unity3d.com/Manual/LayerBasedCollision.html +- Unreal Engine Physics Collision: https://dev.epicgames.com/documentation/en-us/unreal-engine/collision-in-unreal-engine +- Unreal Engine Physical Materials: https://dev.epicgames.com/documentation/en-us/unreal-engine/physical-materials-reference-for-unreal-engine +- Unreal Engine Collision Filtering: https://www.unrealengine.com/en-US/blog/collision-filtering +- Godot PhysicsBody3D: https://docs.godotengine.org/en/stable/classes/class_physicsbody3d.html +- Godot Area3D: https://docs.godotengine.org/en/stable/classes/class_area3d.html +- Godot RigidBody3D: https://docs.godotengine.org/en/stable/classes/class_rigidbody3d.html +- Wikipedia Moment of Inertia: https://en.wikipedia.org/wiki/Moment_of_inertia +- Wikipedia Rigid Body Dynamics: https://en.wikipedia.org/wiki/Rigid_body_dynamics diff --git a/extensions/2.0/OMI_physics_body/README.motion.md b/extensions/2.0/OMI_physics_body/README.motion.md index b9da61c..6015247 100644 --- a/extensions/2.0/OMI_physics_body/README.motion.md +++ b/extensions/2.0/OMI_physics_body/README.motion.md @@ -2,9 +2,9 @@ If a node has the `"motion"` property defined, its transform is driven by the physics engine. -* Descendant nodes should move with that node. The physics engine should treat them as part of a single body. -* If a descendant node has its own motion property, that node should be treated as an independent body during simulation. There is no implicit requirement that it follows its "parent" rigid body. -* If a node's transform is animated by animations in the file, those animations should take priority over the physics simulation. +- Descendant nodes should move with that node. The physics engine should treat them as part of a single body. +- If a descendant node has its own motion property, that node should be treated as an independent body during simulation. There is no implicit requirement that it follows its "parent" rigid body. +- If a node's transform is animated by animations in the file, those animations should take priority over the physics simulation. ## Motion Properties @@ -12,11 +12,12 @@ If a node has the `"motion"` property defined, its transform is driven by the ph | ---------------------- | ----------- | -------------------------------------------------------------------- | -------------------- | | **type** | `string` | The type of the physics body as a string. | Required, no default | | **mass** | `number` | The mass of the physics body in kilograms. | 1.0 | -| **linearVelocity** | `number[3]` | The initial linear velocity of the body in meters per second. | [0.0, 0.0, 0.0] | -| **angularVelocity** | `number[3]` | The initial angular velocity of the body in radians per second. | [0.0, 0.0, 0.0] | | **centerOfMass** | `number[3]` | The center of mass offset from the origin in meters. | [0.0, 0.0, 0.0] | | **inertiaDiagonal** | `number[3]` | The inertia around principle axes in kilogram meter squared (kg⋅m²). | [0.0, 0.0, 0.0] | | **inertiaOrientation** | `number[4]` | The inertia orientation as a Quaternion. | [0.0, 0.0, 0.0, 1.0] | +| **linearVelocity** | `number[3]` | The initial linear velocity of the body in meters per second. | [0.0, 0.0, 0.0] | +| **angularVelocity** | `number[3]` | The initial angular velocity of the body in radians per second. | [0.0, 0.0, 0.0] | +| **gravityFactor** | `number` | A multiplier applied to the acceleration due to gravity. | 1.0 | ### Motion Types @@ -46,14 +47,6 @@ Dynamic bodies are bodies simulated with [rigid body dynamics](https://en.wikipe The `"mass"` property is a number that defines how much mass this physics body has in kilograms. Not all body types can make use of mass, such as triggers or non-moving bodies, in which case the mass can be ignored. If not specified, the default value is 1 kilogram. -### Linear Velocity - -The `"linearVelocity"` property is an array of three numbers that defines how much linear velocity this physics body starts with in meters per second. Not all body types can make use of linear velocity, such as non-moving bodies, in which case the linear velocity can be ignored. If not specified, the default value is zero. - -### Angular Velocity - -The `"angularVelocity"` property is an array of three numbers that defines how much angular velocity this physics body starts with in radians per second. Not all body types can make use of angular velocity, such as non-moving bodies, in which case the angular velocity can be ignored. If not specified, the default value is zero. - ### Center of Mass The `"centerOfMass"` property is an array of three numbers that defines the position offset in meters of the center of mass in the body's local space. If not specified, the default value is zero. @@ -68,6 +61,18 @@ The `"inertiaDiagonal"` property is an array of 3 numbers that defines the inert The `"inertiaOrientation"` property is an array of 4 numbers that defines a Quaternion for orientation of the inertia's principle axes relative to the body's local space. If not specified or set to the default value of `[0.0, 0.0, 0.0, 1.0]`, no rotation is applied, the inertia's principle axes are aligned with the body's local space axes. +### Linear Velocity + +The `"linearVelocity"` property is an array of three numbers that defines how much linear velocity this physics body starts with in meters per second. Not all body types can make use of linear velocity, such as non-moving bodies, in which case the linear velocity can be ignored. If not specified, the default value is zero. + +### Angular Velocity + +The `"angularVelocity"` property is an array of three numbers that defines how much angular velocity this physics body starts with in radians per second. Not all body types can make use of angular velocity, such as non-moving bodies, in which case the angular velocity can be ignored. If not specified, the default value is zero. + +### Gravity Factor + +The `"gravityFactor"` property is a number that defines a multiplier applied to the acceleration due to gravity. Values other than 1.0 are not realistic, but may be useful for artistic effects. If not specified, the default value is 1.0. + ## JSON Schema See [schema/node.OMI_physics_body.motion.schema.json](schema/node.OMI_physics_body.motion.schema.json) for the motion properties JSON schema. diff --git a/extensions/2.0/OMI_physics_body/README.trigger.md b/extensions/2.0/OMI_physics_body/README.trigger.md index 702ec63..e3a3c33 100644 --- a/extensions/2.0/OMI_physics_body/README.trigger.md +++ b/extensions/2.0/OMI_physics_body/README.trigger.md @@ -10,10 +10,11 @@ As the name "trigger" suggests, implementations may use these shapes as sensors ## Trigger Properties -| | 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. | [] | +| | 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. | [] | +| **collisionFilter** | `integer` | The index of the filter information in the top level collisionFilters array. | -1 | ### Shape @@ -25,6 +26,44 @@ The `"nodes"` property is an array of integer indices that reference descendant 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. +### Collision Filter + +The `"collisionFilter"` property is an integer index that references a collision filter in the document-level collisionFilters array in the `OMI_physics_body` extension. If not specified or -1, the default collision filter is used. + +Collision filters are used to determine which objects can collide with each other. A collision filter includes a set of collision systems (the "collision layer" the object is on), and a set of collision systems to collide with or to ignore (the "collision mask" of the object). See the below [Collision Filter Properties](#collision-filter-properties) section for more information on collision filters. + +## Collision Filter Properties + +The following properties may be defined in a collision filter in the top-level `collisionFilters` array: + +| | Type | Description | Default value | +| ------------------------- | ---------- | ----------------------------------------------------------------------------------- | ------------- | +| **collisionSystems** | `string[]` | An array of names of the collision systems of which this object is a member. | `[]` | +| **collideWithSystems** | `string[]` | An array of names of the collision systems which this object can collide with. | `[]` | +| **notCollideWithSystems** | `string[]` | An array of names of the collision systems which this object does not collide with. | `[]` | + +### Collision Systems + +The `"collisionSystems"` property is an array of strings representing the names of the collision systems or layers of which this object is a member. If not specified, the default value is an empty array, which means this filter is not a member of any collision systems, but may still collide with other objects. + +### Collide With Systems + +The `"collideWithSystems"` property is an array of strings representing the names of the collision systems or layers which this object can collide with. If not specified, the default value is an empty array. + +If non-empty, objects using this filter should collide with only the collision systems in this array. This is also known as the "collision mask". + +This property is mutually exclusive with the `"notCollideWithSystems"` property. If both are specified, the collision filter is invalid. If neither are specified, the object can collide with all systems. + +### Not Collide With Systems + +The `"notCollideWithSystems"` property is an array of strings representing the names of the collision systems or layers which this object does not collide with. If not specified, the default value is an empty array. + +If non-empty, objects using this filter should collide with all collision systems except those in this array. This is the inverse of the `"collideWithSystems"` property, and represents an inverted "collision mask". + +This property is mutually exclusive with the `"collideWithSystems"` property. If both are specified, the collision filter is invalid. If neither are specified, the object can collide with all systems. + ## JSON Schema See [schema/node.OMI_physics_body.trigger.schema.json](schema/node.OMI_physics_body.trigger.schema.json) for the trigger properties JSON schema. + +See [schema/glTF.OMI_physics_body.collision_filter.schema.json](schema/glTF.OMI_physics_body.collision_filter.schema.json) for the collision filter properties JSON schema. diff --git a/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.collision_filter.schema.json b/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.collision_filter.schema.json new file mode 100644 index 0000000..9899e02 --- /dev/null +++ b/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.collision_filter.schema.json @@ -0,0 +1,36 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "glTF.OMI_physics_body.collision_filter.schema.json", + "title": "OMI_physics_body Collision Filter", + "type": "object", + "description": "Parameters describing a parameterization of a collision filter, allowing for disabling collision between pairs of shapes.", + "allOf": [ { "$ref": "glTFChildOfRootProperty.schema.json" } ], + "properties": { + "collisionSystems": { + "type": "array", + "description": "An array of strings representing the names of the collision systems of which this object is a member.", + "items": { + "type": "string" + } + }, + "collideWithSystems": { + "type": "array", + "description": "An array of strings representing the name of the collision systems which this object can collide with.", + "items": { + "type": "string" + } + }, + "notCollideWithSystems": { + "type": "array", + "description": "An array of strings representing the names of the collision systems which this object does not collide with.", + "items": { + "type": "string" + } + }, + "extensions": { }, + "extras": { } + }, + "not": { + "anyOf": [{ "required": ["collideWithSystems", "notCollideWithSystems"] }] + } +} diff --git a/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.material.schema.json b/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.material.schema.json new file mode 100644 index 0000000..7e04898 --- /dev/null +++ b/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.material.schema.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "glTF.OMI_physics_body.material.schema.json", + "title": "OMI_physics_body Physics Material", + "type": "object", + "description": "Parameters describing the physical properties of a surface in a physics simulation.", + "allOf": [ { "$ref": "glTFChildOfRootProperty.schema.json" } ], + "properties": { + "staticFriction": { + "type": "number", + "description": "The friction used when an object is laying still on a surface. Usually a value from 0 to 1. A value of 0 feels like ice, a value of 1 will make it very hard to get the object moving. Simulations which do not differentiate between static and dynamic friction should use the dynamic friction value.", + "minimum": 0.0, + "default": 0.6 + }, + "dynamicFriction": { + "type": "number", + "description": "The friction used when already moving. Usually a value from 0 to 1. A value of 0 feels like ice, a value of 1 will make it come to rest very quickly unless a lot of force or gravity pushes the object.", + "minimum": 0.0, + "default": 0.6 + }, + "restitution": { + "type": "number", + "description": "How bouncy is the surface? A value of 0 will not bounce. A value of 1 will bounce without any loss of energy.", + "minimum": 0.0, + "default": 0.0 + }, + "frictionCombine": { + "type": "string", + "description": "Determines how friction should be combined when two objects interact.", + "enum": ["average", "minimum", "maximum", "multiply"] + }, + "restitutionCombine": { + "type": "string", + "description": "Determines how restitution should be combined when two objects interact.", + "enum": ["average", "minimum", "maximum", "multiply"] + }, + "extensions": { }, + "extras": { } + } +} diff --git a/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.schema.json b/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.schema.json new file mode 100644 index 0000000..228f820 --- /dev/null +++ b/extensions/2.0/OMI_physics_body/schema/glTF.OMI_physics_body.schema.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "glTF.OMI_physics_body.schema.json", + "title": "OMI_physics_body glTF Document Extension", + "type": "object", + "description": "Top level physics properties and resources.", + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], + "properties": { + "physicsMaterials": { + "type": "array", + "description": "An array of physics materials.", + "items": { + "type": "object", + "$ref": "glTF.OMI_physics_body.material.schema.json" + } + }, + "collisionFilters": { + "type": "array", + "description": "An array of collision filter descriptions.", + "items": { + "type": "object", + "$ref": "glTF.OMI_physics_body.collision_filter.schema.json" + } + }, + "extensions": { }, + "extras": { } + } +} diff --git a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.collider.schema.json b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.collider.schema.json index 6bde046..3655eaf 100644 --- a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.collider.schema.json +++ b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.collider.schema.json @@ -1,16 +1,26 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "node.OMI_physics_body.collider.schema.json", - "title": "OMI_physics_body Collider Property", + "title": "OMI_physics_body Node Collider Property", "type": "object", "description": "Parameters describing the geometric shape used for collisions.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "shape": { "allOf": [ { "$ref": "glTFid.schema.json" } ], "description": "The id of the shape referenced by this node.", "default": -1 }, + "physicsMaterial": { + "allOf": [ { "$ref": "glTFid.schema.json" } ], + "description": "The index of the physics material in the top level physicsMaterials array.", + "default": -1 + }, + "collisionFilter": { + "allOf": [ { "$ref": "glTFid.schema.json" } ], + "description": "The index of the filter information in the top level collisionFilters array.", + "default": -1 + }, "extensions": { }, "extras": { } } diff --git a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.motion.schema.json b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.motion.schema.json index 2d2841b..7bf2330 100644 --- a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.motion.schema.json +++ b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.motion.schema.json @@ -1,10 +1,10 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "node.OMI_physics_body.motion.schema.json", - "title": "OMI_physics_body Motion Property", + "title": "OMI_physics_body Node Motion Property", "type": "object", - "description": "Parameter describing the motion of a physics body glTF node.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "description": "Parameters describing how a node's transform should be driven by physics simulation.", + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "type": { "type": "string", @@ -20,14 +20,14 @@ "description": "The mass of this physics body in kilograms.", "default": 1.0 }, - "linearVelocity": { - "type": "array", - "description": "The initial linear velocity of the body in meters per second.", - "default": [0.0, 0.0, 0.0] - }, - "angularVelocity": { + "centerOfMass": { "type": "array", - "description": "The initial angular velocity of the body in radians per second.", + "description": "The center of mass of the object in local space.", + "items": { + "type": "number" + }, + "minItems": 3, + "maxItems": 3, "default": [0.0, 0.0, 0.0] }, "inertiaDiagonal": { @@ -40,6 +40,21 @@ "description": "The inertia orientation as a Quaternion. If not specified, the inertia is not rotated.", "default": [0.0, 0.0, 0.0, 1.0] }, + "linearVelocity": { + "type": "array", + "description": "The initial linear velocity of the body in meters per second.", + "default": [0.0, 0.0, 0.0] + }, + "angularVelocity": { + "type": "array", + "description": "The initial angular velocity of the body in radians per second.", + "default": [0.0, 0.0, 0.0] + }, + "gravityFactor": { + "type": "number", + "description": "A multiplier applied to the global acceleration due to gravity.", + "default": 1.0 + }, "extensions": { }, "extras": { } }, diff --git a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.schema.json b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.schema.json index 8dfd735..b9cad5d 100644 --- a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.schema.json +++ b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.schema.json @@ -3,23 +3,20 @@ "$id": "node.OMI_physics_body.schema.json", "title": "OMI_physics_body glTF Node Extension", "type": "object", - "description": "Defines physics information for a node.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "description": "Physics properties for a node.", + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "motion": { - "type": "object", - "description": "If present, this node has its motion controlled by physics, specified by these motion parameters.", - "$ref": "glTF.OMI_physics_body.motion.schema.json" + "allOf": [ { "$ref": "node.OMI_physics_body.motion.schema.json" } ], + "description": "If present, this node has its motion controlled by physics, specified by these motion parameters." }, "collider": { - "type": "object", - "description": "If present, this node is solid and can be collided with, specified by these collider parameters.", - "$ref": "glTF.OMI_physics_body.collider.schema.json" + "allOf": [ { "$ref": "node.OMI_physics_body.collider.schema.json" } ], + "description": "If present, this node is solid and can be collided with, specified by these collider parameters." }, "trigger": { - "type": "object", - "description": "If present, this node is non-solid and can act as a trigger, specified by these trigger parameters.", - "$ref": "glTF.OMI_physics_body.trigger.schema.json" + "allOf": [ { "$ref": "node.OMI_physics_body.trigger.schema.json" } ], + "description": "If present, this node is non-solid and can act as a trigger, specified by these trigger parameters." }, "extensions": { }, "extras": { } diff --git a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.trigger.schema.json b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.trigger.schema.json index 5ca2e8e..235a847 100644 --- a/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.trigger.schema.json +++ b/extensions/2.0/OMI_physics_body/schema/node.OMI_physics_body.trigger.schema.json @@ -1,18 +1,14 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "node.OMI_physics_body.trigger.schema.json", - "title": "OMI_physics_body Trigger Property", + "title": "OMI_physics_body Node Trigger Property", "type": "object", - "description": "Parameters describing the geometric shape used for trigger volumes.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "description": "Parameters describing a trigger volume used for detecting physics objects.", + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "shape": { - "description": "The id of the shape referenced by this node.", - "allOf": [ - { - "$ref": "glTFid.schema.json" - } - ], + "allOf": [{ "$ref": "glTFid.schema.json" }], + "description": "The index of the shape in the top level shapes array.", "default": -1 }, "nodes": { @@ -24,6 +20,10 @@ "uniqueItems": true, "minItems": 1 }, + "collisionFilter": { + "allOf": [{ "$ref": "glTFid.schema.json" }], + "description": "The index of the filter information in the top level collisionFilters array." + }, "extensions": { }, "extras": { } }, diff --git a/extensions/2.0/OMI_physics_joint/README.md b/extensions/2.0/OMI_physics_joint/README.md index 5d34d72..40e8543 100644 --- a/extensions/2.0/OMI_physics_joint/README.md +++ b/extensions/2.0/OMI_physics_joint/README.md @@ -2,7 +2,7 @@ ## Contributors -* Aaron Franke, The Mirror Megaverse Inc. +- Aaron Franke, The Mirror Megaverse Inc. ## Status @@ -186,10 +186,10 @@ See [glTF.OMI_physics_joint.joint_constraint.schema.json](schema/glTF.OMI_physic ## Known Implementations -* Godot Engine add-on +- Godot Engine add-on ## Resources: -* Godot Joint3D https://docs.godotengine.org/en/latest/classes/class_generic6dofjoint3d.html -* Unity Joints https://docs.unity3d.com/Manual/Joints.html -* Wikipedia Stiffness https://en.wikipedia.org/wiki/Stiffness +- Godot Joint3D https://docs.godotengine.org/en/latest/classes/class_generic6dofjoint3d.html +- Unity Joints https://docs.unity3d.com/Manual/Joints.html +- Wikipedia Stiffness https://en.wikipedia.org/wiki/Stiffness diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.schema.json index 485e4d8..4f58102 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape glTF Document Extension", "type": "object", "description": "Top level shape resources.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "shapes": { "type": "array", diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.box.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.box.schema.json index d46e842..37961c4 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.box.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.box.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Box Shape", "type": "object", "description": "Parameters describing a box physics shape.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "size": { "type": "array", diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.capsule.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.capsule.schema.json index fbbdd5b..27e9d96 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.capsule.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.capsule.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Capsule Shape", "type": "object", "description": "Parameters describing a capsule physics shape.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "radius": { "type": "number", diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.convex.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.convex.schema.json index 9dcfdf2..3c87921 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.convex.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.convex.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Convex Shape", "type": "object", "description": "Parameters describing a convex hull physics shape.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "mesh": { "allOf": [ { "$ref": "glTFid.schema.json" } ], diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.cylinder.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.cylinder.schema.json index ee0d28a..bfa0d87 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.cylinder.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.cylinder.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Cylinder Shape", "type": "object", "description": "Parameters describing a cylinder physics shape.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "radius": { "type": "number", diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.schema.json index d6e6d84..4e7d41f 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Shape Resource", "type": "object", "description": "Defines a physics shape resource.", - "allOf": [ { "$ref" : "glTFChildOfRootProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFChildOfRootProperty.schema.json" } ], "properties": { "type": { "type": "string", diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.sphere.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.sphere.schema.json index 064ac2a..d06edc7 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.sphere.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.sphere.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Sphere Shape", "type": "object", "description": "Parameters describing a sphere physics shape.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "radius": { "type": "number", diff --git a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.trimesh.schema.json b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.trimesh.schema.json index 3c67d2e..3faddb9 100644 --- a/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.trimesh.schema.json +++ b/extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.trimesh.schema.json @@ -4,7 +4,7 @@ "title": "OMI_physics_shape Trimesh Shape", "type": "object", "description": "Parameters describing a concave trimesh physics shape.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "mesh": { "allOf": [ { "$ref": "glTFid.schema.json" } ], diff --git a/extensions/2.0/OMI_seat/schema/node.OMI_seat.schema.json b/extensions/2.0/OMI_seat/schema/node.OMI_seat.schema.json index 13f08d5..e591f1e 100644 --- a/extensions/2.0/OMI_seat/schema/node.OMI_seat.schema.json +++ b/extensions/2.0/OMI_seat/schema/node.OMI_seat.schema.json @@ -4,7 +4,7 @@ "title": "OMI_seat glTF Node Extension", "type": "object", "description": "Parameters describing a seat for a character.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "back": { "type": "array", diff --git a/extensions/2.0/OMI_spawn_point/schema/node.OMI_spawn_point.schema.json b/extensions/2.0/OMI_spawn_point/schema/node.OMI_spawn_point.schema.json index e605040..b021143 100644 --- a/extensions/2.0/OMI_spawn_point/schema/node.OMI_spawn_point.schema.json +++ b/extensions/2.0/OMI_spawn_point/schema/node.OMI_spawn_point.schema.json @@ -4,7 +4,7 @@ "title": "OMI_spawn_point", "type": "object", "description": "Parameters that define a spawn point.", - "allOf": [ { "$ref" : "glTFProperty.schema.json" } ], + "allOf": [ { "$ref": "glTFProperty.schema.json" } ], "properties": { "title": { "type": "string",