Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Change capsules and cylinders to have separate top and bottom radiuses #234

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+44 −20
Open

Change capsules and cylinders to have separate top and bottom radiuses #234

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 21 additions & 11 deletions extensions/2.0/OMI_physics_shape/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,12 +69,14 @@ The main data structure `glTF.OMI_physics_shape.shape.schema.json` defines a typ

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 |
| | 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 sphere shape in meters. | 0.5 | Sphere |
| **radiusBottom** | `number` | The radius of the bottom disc or hemisphere in meters. | 0.5 | Capsule, cylinder |
| **radiusTop** | `number` | The radius of the top disc or hemisphere in meters. | 0.5 | Capsule, cylinder |
| **height** | `number` | The mid-height of the cylindrical part of the shape in meters. | 1.0 or 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.

Expand Down Expand Up @@ -105,15 +107,21 @@ Sphere shapes describe a uniform "ball" shape. They have a `radius` property whi

#### 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`.
Capsule shapes describe a "pill" shape. They have `height`, `radiusBottom`, and `radiusTop` properties. If either of the radius properties are omitted, the default radius is `0.5`, and if the `height` property is omitted, the default height is `1.0`.

The `height` property describes the "mid height", the distance between the centers of the two capping hemispheres. The full height from the bottom-most point to the top-most point can be found with `height + radiusBottom + radiusTop`, meaning that a capsule with default values has a full height of 2.0 meters. 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 `radiusBottom` and `radiusTop` properties are recommended to be set to the same value. Having these be different values results in a shape that is not a regular capsule, but a "tapered capsule". Tapered capsules are not supported by all game engines, so using them may result in importers approximating the tapered capsule shape with a convex hull shape.

#### 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`.
Cylinder shapes describe a "tall circle" shape. They are similar in structure to capsules, they have `height`, `radiusBottom`, and `radiusTop` properties. 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.
The `radiusBottom` and `radiusTop` properties are recommended to be set to the same value. Having these be different values results in a shape that is not a regular cylinder, but a "tapered cylinder". Tapered cylinders are not supported by all game engines, so using them may result in importers approximating the tapered cylinder shape with a convex hull shape.

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 radius values, and setting the capsule's full height to the cylinder's height, meaning setting the capsule's mid height property to `height - radiusBottom - radiusTop`.

#### Convex

Expand All @@ -138,9 +146,11 @@ The following JSON pointers are defined representing mutable properties defined
| `/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/{}/capsule/radiusBottom` | `float` |
| `/extensions/OMI_physics_shape/shapes/{}/capsule/radiusTop` | `float` |
| `/extensions/OMI_physics_shape/shapes/{}/cylinder/height` | `float` |
| `/extensions/OMI_physics_shape/shapes/{}/cylinder/radius` | `float` |
| `/extensions/OMI_physics_shape/shapes/{}/cylinder/radiusBottom` | `float` |
| `/extensions/OMI_physics_shape/shapes/{}/cylinder/radiusTop` | `float` |

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

Expand Down
5 changes: 3 additions & 2 deletions extensions/2.0/OMI_physics_shape/examples/capsule_collider.gltf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@
{
"type": "capsule",
"capsule": {
"height": 2.0,
"radius": 0.5
"height": 1.0,
"radiusBottom": 0.5,
"radiusTop": 0.5
}
}
]
Expand Down
3 changes: 2 additions & 1 deletion extensions/2.0/OMI_physics_shape/examples/cylinder_collider.gltf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@
"type": "cylinder",
"cylinder": {
"height": 2.0,
"radius": 0.5
"radiusBottom": 0.5,
"radiusTop": 0.5
}
}
]
Expand Down
14 changes: 10 additions & 4 deletions extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.capsule.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,13 +8,19 @@
"properties": {
"height": {
"type": "number",
"description": "The full height of the capsule shape in meters.",
"description": "The mid height of the capsule shape in meters, the distance between the centers of the two capping hemispheres.",
"exclusiveMinimum": 0.0,
"default": 2.0
"default": 1.0
},
"radius": {
"radiusBottom": {
"type": "number",
"description": "The radius of the capsule in meters.",
"description": "The radius of the bottom of the capsule (the hemisphere located along -Y) in meters.",
"minimum": 0.0,
"default": 0.5
},
"radiusTop": {
"type": "number",
"description": "The radius of the top of the capsule (the hemisphere located along +Y) in meters.",
"minimum": 0.0,
"default": 0.5
},
Expand Down
10 changes: 8 additions & 2 deletions extensions/2.0/OMI_physics_shape/schema/glTF.OMI_physics_shape.shape.cylinder.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,15 @@
"exclusiveMinimum": 0.0,
"default": 2.0
},
"radius": {
"radiusBottom": {
"type": "number",
"description": "The radius of the cylinder in meters.",
"description": "The radius of the bottom of the cylinder (the disc located along -Y) in meters.",
"minimum": 0.0,
"default": 0.5
},
"radiusTop": {
"type": "number",
"description": "The radius of the top of the cylinder (the disc located along +Y) in meters.",
"minimum": 0.0,
"default": 0.5
},
Expand Down