Skip to content

Commit

Permalink
Add materials and filtering similar to KHR/MSFT physics
Browse files Browse the repository at this point in the history
  • Loading branch information
@aaronfranke
aaronfranke committed Jul 14, 2024
1 parent 35cd3a3 commit 4f1a0a6
Show file tree
Hide file tree
Showing 23 changed files with 336 additions and 98 deletions.
30 changes: 15 additions & 15 deletions extensions/2.0/Archived/OMI_collider/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
67 changes: 64 additions & 3 deletions extensions/2.0/OMI_physics_body/README.collider.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
39 changes: 23 additions & 16 deletions extensions/2.0/OMI_physics_body/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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
{
Expand Down Expand Up @@ -100,31 +100,38 @@ 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.

### 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
31 changes: 18 additions & 13 deletions extensions/2.0/OMI_physics_body/README.motion.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,21 +2,22 @@

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

| | Type | Description | Default value |
| ---------------------- | ----------- | -------------------------------------------------------------------- | -------------------- |
| **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

Expand Down Expand Up @@ -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.
Expand All @@ -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.
Loading

0 comments on commit 4f1a0a6

Please sign in to comment.