Skip to content

Latest commit

 

History

History
166 lines (109 loc) · 12.7 KB

README.md

File metadata and controls

166 lines (109 loc) · 12.7 KB
Raw

OMI_physics_shape

Contributors

  • Aaron Franke, Godot Engine.
  • Robert Long, The Matrix.org Foundation
  • Mauve Signweaver, Mauve Software Inc.

Status

Open Metaverse Interoperability Group Stage 1 Proposal

Dependencies

Written against the glTF 2.0 spec.

Does nothing on its own. Designed to be used together with the OMI_physics_body spec.

Overview

This extension allows specifying physics shapes to be used in glTF scenes.

All types of physics shapes defined in this extension are intended to be used for physics simulations and to be portable between many engines. Without another extension using it, this extension does not mandate any particular behavior for the shapes aside from their geometric properties. The precise usage of these physics shape primitives SHOULD be specified by the extenions which utilize them. In general, these physics shapes are used to specify geometry which can be used for collision detection.

The OMI_physics_shape extension is intended to be used together with the OMI_physics_body extension, which allows attaching shapes to glTF nodes and specifying their behavior, including static, kinematic, dynamic, and non-solid triggers. The OMI_physics_body extension refers to a shape using an index of a shape in the OMI_physics_shape document-level shapes array.

Example:

This example defines a single box shape with a size of 1 meter in all dimensions:

{
    "asset": {
        "version": "2.0"
    },
    "extensions": {
        "OMI_physics_shape": {
            "shapes": [
                {
                    "type": "box",
                    "box": {
                        "size": [1, 1, 1]
                    }
                }
            ]
        }
    },
    "extensionsUsed": [
        "OMI_physics_shape"
    ]
}

More example assets can be found in the examples/ folder.

glTF Schema Updates

This extension consists of many new data structures for defining physics shapes on the root glTF document and referencing them on a glTF node. The main data structure glTF.OMI_physics_shape.shape.schema.json uses several smaller data structures to define a physics shape. The glTF.OMI_physics_shape.schema.json data structure uses the key "OMI_physics_shape" in the document-level "extensions" which contains a list of the main physics shape data structures. The node.OMI_physics_shape.schema.json data structure uses the key "OMI_physics_shape" in the node-level "extensions" which contains an index of the physics shape to use from the list document-level physics shape list.

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.

Property Summary

The main data structure glTF.OMI_physics_shape.shape.schema.json defines a type property.

Type Description Default value
type string The type of the physics shape as a string. Required, no default

In addition to the type, a key with the same name as the type can be used to define a sub-JSON with the details of the shape. Which sub-properties are allowed depend on which shape type is being used. The possible properties are described in the following table.

Type Description Default value Valid on
size number[3] The size of the box shape in meters. [1.0, 1.0, 1.0] Box
radius number The radius of the shape in meters. 0.5 Sphere, capsule, cylinder
height number The height of the shape in meters. 2.0 Capsule, cylinder
mesh number The index of the glTF mesh in the document to use as a mesh shape. -1 Trimesh, convex

If a key for the type is missing, or a sub-JSON key is missing, implementations should use the default value. A mesh index of -1 means invalid.

Shape Types

The "type" property is a lowercase string that defines what type of shape this physics shape is.

The selection of shapes was carefully chosen with a balance of compatibility between major game engines and containing the most commonly used shapes for easy asset creation. Physics shapes inherit the transform of the glTF node they are attached to. This includes rotation and translation, however it is discouraged to scale physics shape nodes since this can cause problems in some physics engines.

Here is a table listing the mapping between the OMI_physics_shape type and the equivalent types in major game engines.

Shape Unity Unreal Godot Blender Bullet (Ammo, Panda3D, etc)
Box Box Box BoxShape3D Box Box Shape
Sphere Sphere Sphere SphereShape3D Sphere Sphere Shape
Capsule Capsule Capsule CapsuleShape3D Capsule Capsule Shape
Cylinder Approximation Approximation CylinderShape3D Cylinder Cylinder Shape
Convex Mesh (Convex) Convex ConvexPolygonShape3D Convex Hull Convex Shape
Trimesh Mesh Mesh ConcavePolygonShape3D Mesh Mesh Shape

Box

Box shapes describe a cube or cuboid shape. They have size property which is an array of 3 numbers that describes the width, height, and depth. If the size property is omitted, the default size is [1, 1, 1], representing a cube with a volume of one cubic meter, edges/diameters one meter long, and extents/radius of half a meter. The position of the glTF node is the center of the box shape.

Sphere

Sphere shapes describe a uniform "ball" shape. They have a radius property which is a single number. If the radius property is omitted, the default radius is 0.5, representing a sphere with a radius of half a meter, a diameter of one meter. The position of the glTF node is the center of the sphere shape.

Capsule

Capsule shapes describe a "pill" shape. They have a radius and height property. The height is aligned with the node's local vertical axis. If it's desired to align it along a different axis, rotate the glTF node. If the radius property is omitted, the default radius is 0.5, and if the height property is omitted, the default height is 2.0. The height describes the total height from bottom to top. The height of the capsule must be at least twice as much as the radius. The "mid-height" between the centers of each spherical cap end can be found with height - radius * 2.0.

Cylinder

Cylinder shapes describe a "tall circle" shape. They are similar in structure to capsules, they have a radius and height property. If the radius property is omitted, the default radius is 0.5, and if the height property is omitted, the default height is 2.0.

The height property of a cylinder describes the total height, the distance between the center of the bottom disc and the center of the top disc. The height is aligned with the node's local vertical axis. If it's desired to align it along a different axis, rotate the glTF node.

The use of cylinder is discouraged if another shape would work well in its place. Cylinders are harder to calculate than boxes, spheres, and capsules. Not all game engines support cylinder shapes. Engines that do not support cylinder shapes should use an approximation, such as a convex hull roughly shaped like a cylinder. Cylinders over twice as tall as they are wide can use another approximation: a convex hull combined with an embedded capsule (to allow for smooth rolling), by copying the cylinder's values into a new capsule shape.

Convex

Convex shapes represent a convex hull. Being "convex" means that the shape cannot have any holes or divots, and that all line segments connecting points on the surface stay within the shape. Convex hulls are defined with a mesh property with an index of a mesh in the glTF meshes array. The glTF mesh in the array MUST be a trimesh to work, and should be made of only one glTF mesh primitive (one surface). Valid convex hulls must contain at least one triangle, which becomes three points on the convex hull. Convex hulls are recommended to have at least four points so that they have 3D volume.

Convex hulls can be used to represent complex convex shapes that are not easy to represent with other primitives. If a shape can be represented with a few primitives, prefer using those primitives instead of convex hulls. Convex hulls are much faster than trimesh shapes.

When convex hulls are used, asset creators should try to limit the number of vertices in the shape for improved performance and compatibility. Some game engines limit the amount of vertices that can be in a convex hull, which may caused the actual imported shape to be simplified if the shape in the glTF file is too complex.

Trimesh

Trimesh shapes represent a concave triangle mesh. They are defined with a mesh property with an index of a mesh in the glTF meshes array. The glTF mesh in the array MUST be a trimesh to work, and should be made of only one glTF mesh primitive (one surface). Valid trimesh shapes must contain at least one triangle.

Avoid using a trimesh shape for most objects, they are the slowest shapes to calculate and have several limitations. Most physics engines do not support moving trimesh shapes or calculating collisions between multiple trimesh shapes. Trimesh shapes will not work reliably with trigger bodies or with pushing objects out due to not having an "interior" space, they only have a surface. Trimesh shapes are typically used for complex level geometry (for example, things that objects can go inside of). If a shape can be represented with a combination of simpler primitives, or a convex hull, or multiple convex hulls, prefer that instead.

glTF Object Model

The following JSON pointers are defined representing mutable properties defined by this extension, for use with the glTF Object Model including extensions such as KHR_animation_pointer and KHR_interactivity.

JSON Pointer Object Model Type
/extensions/OMI_physics_shape/shapes/{}/box/size float3
/extensions/OMI_physics_shape/shapes/{}/sphere/radius float
/extensions/OMI_physics_shape/shapes/{}/capsule/height float
/extensions/OMI_physics_shape/shapes/{}/capsule/radius float
/extensions/OMI_physics_shape/shapes/{}/cylinder/height float
/extensions/OMI_physics_shape/shapes/{}/cylinder/radius float

Additionally, the following JSON pointers are defined for read-only properties:

JSON Pointer Object Model Type
/extensions/OMI_physics_shape/shapes.length int

JSON Schema

See glTF.OMI_physics_shape.schema.json for the document-level list of shapes, glTF.OMI_physics_shape.shape.schema.json for the shape resource schema, and the glTF.OMI_physics_shape.shape.*.schema.json files for the individual shape types.

Known Implementations

Resources: