capsuleShape

function capsuleShape(radius: number, halfHeight: number): ConvexShape

import { capsuleShape } from '@driftengine/physics';

Parameters

In depth

No new representation. Point-cloud-plus-radius already expresses a capsule exactly, so this is a named constructor over hullShape rather than a shape type. A named thing is discoverable and an idiom is not. It stands along y because that is the axis a character capsule uses, and a rotation nobody has to apply is a rotation nobody gets wrong.

At halfHeight zero the two points dedupe to one and the result is a sphere, which is the right degenerate case rather than an error.

A cylinder is a different shape and has its own constructor, cylinderShape below. The rounding radius here grows uniformly around every feature, so applying it to a segment can only ever give a capsule: it would round a cylinder's rim as well as its side. sideRadius is the field that expresses the difference, and it was added on 2026-08-27 with the second condition this file had been recording — a wheel rim, a rolling barrel — as its reason.

The advice until then was "build one as an n-gon prism with hullShape and accept the facets", and it had a measured ceiling: hullShape refuses more than 64 points, a prism spends two a side, so thirty-two sides was the wall, and a thirty-two-sided wheel of radius 1 rolling at 6 m/s bobbed 16 mm that no side count could reduce. prismRoll.test.ts still measures that, beside the same wheel built as a cylinder, because the comparison is the reason the shape kind exists.