Skip to main content

Collision Setup

Set up collisions to prevent bones from penetrating through the body.

note

This page is a setup guide. For all properties and default values of each collision shape, see Collision Parameters.

Collision system overview

Examples of collision placement and the purpose of each shape (diagram labels are in Japanese).

Collision Types​

Sphere​

Suitable for spherical parts like head and shoulders.

Sphere collision example

Capsule​

Suitable for cylindrical parts like arms and legs.

Capsule collision example

Tapered Capsule Collision (planned for v1.22)​

Not officially released

This feature has not been officially released yet. It is planned for KawaiiPhysics v1.22. Specifications may change during development.

An equal-radius capsule fitted to one end of a tapered limb can leave too much space at the other end. Tapered Capsule lets you set the endpoint radii independently, representing the width change with one shape.

  1. Add an entry under Collision > Tapered Capsule Collision.
  2. Select its Driving Bone.
  3. Adjust one endpoint width with Radius0.
  4. Adjust the other endpoint width with Radius1.
  5. Adjust the center-to-center distance with Length.
Separate endpoint radii and center-to-center Length
Concept: Radius0 is at shape-local +Z, Radius1 at −Z. Length measures between endpoint centers.

Strong tapers should not assume identical contacts to Chaos geometry. A length that makes one endpoint sphere contain the other collapses the shape to the larger sphere. See the shape reference for the exact rule.

Plane​

Used for flat surface restrictions like ground and walls.

Box​

Version Info

Added in v1.17.0

Box-shaped collision. Suitable for rectangular shapes like body and buildings.

UPROPERTY()
TArray<FBoxLimit> BoxLimits;

FBoxLimit Properties:

PropertyTypeDefaultDescription
DrivingBoneFBoneReference-Bone that collision follows
OffsetLocationFVector(0, 0, 0)Location offset from the Driving Bone
OffsetRotationFRotator(0, 0, 0)Rotation offset from the Driving Bone (range -360 to 360)
ExtentFVector(5, 5, 5)Box half-extents (size in each axis direction)
note

DrivingBone / OffsetLocation / OffsetRotation are common to all collision shapes (FCollisionLimitBase). FSphericalLimit adds Radius (default 5) and LimitType (Inner/Outer); FCapsuleLimit adds Radius (default 5) and Length (default 10).

Collision Generation from PhysicsAsset​

Version Info

Added in v1.17.0

You can auto-generate collision shapes from existing PhysicsAssets. Collision bodies defined in PhysicsAsset are converted to KawaiiPhysics collisions.

Usage​

  1. Select KawaiiPhysics node
  2. Set existing PhysicsAsset to Physics Asset property
  3. Collision shapes are automatically generated

Benefits​

  • Reuse existing PhysicsAssets
  • Reduces manual collision setup work
  • Consistent collision settings

Adding Collision​

  1. Select the KawaiiPhysics node
  2. Add elements to Spherical Limits / Capsule Limits / Box Limits / Planar Limits array
  3. Set Driving Bone (bone that collision follows)
  4. Adjust offset and size

Driving Bone​

Collision follows and moves with the Driving Bone.

upperarm_r (Driving Bone)
    ↓ Follows
[Capsule Collision] → Hair stops here

Inside vs Outside​

Inside (Inner Limit)​

Limits bones to inside the sphere.

  • Use case: Following head shape

Outside (Outer Limit)​

Limits bones to outside the sphere.

  • Use case: Preventing penetration into shoulders

Combining Multiple Shapes​

In actual characters, multiple collision shapes are used in combination.

Combining multiple collision shapes

Practical collision placement example for the upper body and skirt

Performance Considerations​

More collisions increase processing load.

tip
  • Use the minimum necessary collisions
  • Approximate complex shapes with multiple simple shapes

For more details, see Performance.

Related UE documentation​

  • Physics Asset Editor — Understand PhysicsAssets and the editor used to author their shapes. (UE 5.8)

  • Mirroring Animation — Create a Mirror Data Table and inspect paired bones and Mirror Axis; KawaiiPhysics uses the table for collision generation. (UE 5.8)