Type Alias WorldSettings

type WorldSettings = {
    ccd: {
        linearCastMaxPenetration: number;
        linearCastThreshold: number;
        minVelocityForRestitution: number;
    };
    contacts: { contactPointPreserveLambdaMaxDistSq: number };
    gravity: Vec3;
    gravityEnabled: boolean;
    layers: Layers;
    narrowphase: {
        collideOnlyWithActiveEdges: boolean;
        collideWithBackfaces: boolean;
        collisionTolerance: number;
        manifoldTolerance: number;
        normalCosMaxDeltaRotation: number;
        penetrationTolerance: number;
        returnDeepestPoint: boolean;
        speculativeContactDistance: number;
        useManifoldReduction: boolean;
    };
    sleeping: {
        allowSleeping: boolean;
        pointVelocitySleepThreshold: number;
        timeBeforeSleep: number;
    };
    solver: {
        baumgarteFactor: number;
        maxPenetrationDistance: number;
        minVelocityForRestitution: number;
        penetrationSlop: number;
        positionIterations: number;
        velocityIterations: number;
        warmStartImpulseRatio: number;
        warmStarting: boolean;
    };
}

Index

Properties

ccd contacts gravity gravityEnabled layers narrowphase sleeping solver

Properties

ccd

ccd: {
    linearCastMaxPenetration: number;
    linearCastThreshold: number;
    minVelocityForRestitution: number;
}

Continuous Collision Detection (CCD) options

Type Declaration

linearCastMaxPenetration: number
Fraction of inner radius allowed to penetrate during CCD. Provides penetration slop for stability.
Default
```
0.25 (25%)
```
linearCastThreshold: number
Fraction of inner radius to trigger CCD. If movement < (threshold * innerRadius), use discrete update. Lower = more CCD (expensive), Higher = more tunneling risk.
Default
```
0.05 (5%)
```
minVelocityForRestitution: number
Minimum relative velocity for restitution (bounce) in CCD. Below this, collisions are perfectly inelastic. Unit: m/s
Default
```
1.0
```

contacts

contacts: { contactPointPreserveLambdaMaxDistSq: number }

Contact cache settings

Type Declaration

contactPointPreserveLambdaMaxDistSq: number
Maximum allowed distance between old and new contact point to preserve contact forces for warm start. Unit: meters²
Default
```
0.0001 (0.01² or 1cm²)
```

gravity

gravity: Vec3

Gravity vector. Unit: m/s²

Default

[0,-9.81,0]

gravityEnabled

gravityEnabled: boolean

Enable/disable gravity globally.

Default

true

layers

layers: Layers

Collision layers

narrowphase

narrowphase: {
    collideOnlyWithActiveEdges: boolean;
    collideWithBackfaces: boolean;
    collisionTolerance: number;
    manifoldTolerance: number;
    normalCosMaxDeltaRotation: number;
    penetrationTolerance: number;
    returnDeepestPoint: boolean;
    speculativeContactDistance: number;
    useManifoldReduction: boolean;
}

Narrowphase collision detection settings

Type Declaration

collideOnlyWithActiveEdges: boolean
When false, we prevent collision against non-active (shared) edges. Mainly useful for triangle meshes to avoid ghost collisions at shared edges.
Default
```
true
```
collideWithBackfaces: boolean
Collide with backfaces during raycasts/shapecasts.
Default
```
false
```
collisionTolerance: number
If objects are closer than this distance, they are considered to be colliding (used for GJK). Unit: meters
Default
```
1e-4
```
manifoldTolerance: number
Max distance to use to determine if two points are on the same plane for determining the contact manifold between two shape faces. Unit: meters
Default
```
1e-3 (1mm)
```
normalCosMaxDeltaRotation: number
Maximum angle between normals that allows manifolds between different sub shapes of the same body pair to be combined. Stored as cos(max angle).
Default
```
cos(5°) ≈ 0.996
```
penetrationTolerance: number
A factor that determines the accuracy of the penetration depth calculation. If the change of the squared distance is less than tolerance * current_penetration_depth^2 the algorithm will terminate. Unit: dimensionless
Default
```
1e-4
```
returnDeepestPoint: boolean
Whether to return the deepest point during collision detection.
Default
```
false
```
speculativeContactDistance: number
Radius around objects inside which speculative contact points will be detected. Note that if this is too big you will get ghost collisions as speculative contacts are based on the closest points during the collision detection step which may not be the actual closest points by the time the two objects hit. Unit: meters
Default
```
0.02 (2cm)
```
useManifoldReduction: boolean
Whether or not to reduce manifolds with similar contact normals into one contact manifold. This groups contacts with similar normals that come from different SubShapeIDs (e.g. different triangles in a mesh shape or different compound shapes). If you need to track exactly which SubShapeIDs are in contact, turn this off per-body using body.useManifoldReduction = false.
Default
```
true
```

sleeping

sleeping: {
    allowSleeping: boolean;
    pointVelocitySleepThreshold: number;
    timeBeforeSleep: number;
}

Sleeping options

Type Declaration

allowSleeping: boolean
If objects can go to sleep or not. Sleeping bodies are excluded from physics simulation until woken.
Default
```
true
```
pointVelocitySleepThreshold: number
To detect if an object is sleeping, we use 3 points:
- The center of mass.
- The centers of the faces of the bounding box that are furthest away from the center.
The movement of these points is tracked and if the velocity of all 3 points is lower than this value, the object is allowed to go to sleep. Unit: m/s
Default
```
0.03 (3cm/s)
```
timeBeforeSleep: number
Time before object is allowed to go to sleep. Unit: seconds
Default
```
0.5
```

solver

solver: {
    baumgarteFactor: number;
    maxPenetrationDistance: number;
    minVelocityForRestitution: number;
    penetrationSlop: number;
    positionIterations: number;
    velocityIterations: number;
    warmStartImpulseRatio: number;
    warmStarting: boolean;
}

Solver options

Type Declaration

baumgarteFactor: number
Baumgarte stabilization factor (how much of the position error to 'fix' in 1 update). Unit: dimensionless Range: 0 (nothing) to 1 (100%)
Default
```
0.2 (20%)
```
maxPenetrationDistance: number
Maximum distance to correct in a single iteration when solving position constraints. Unit: meters
Default
```
0.2 (20cm)
```
minVelocityForRestitution: number
Minimal velocity needed before a collision can be elastic. If the relative velocity between colliding objects in the direction of the contact normal is lower than this, the restitution will be zero regardless of the configured value. This lets an object settle sooner. Unit: m/s
Default
```
1.0
```
penetrationSlop: number
How much bodies are allowed to sink into each other. Used to avoid jitter when objects are stacked. Unit: meters
Default
```
0.02 (2cm)
```
positionIterations: number
Number of solver position iterations to run.
Default
```
2
```
velocityIterations: number
Number of solver velocity iterations to run. Note that this needs to be >= 2 in order for friction to work (friction is applied using the non-penetration impulse from the previous iteration).
Default
```
10
```
warmStartImpulseRatio: number
Scale factor for warm start impulses.
Default
```
1.0
```
warmStarting: boolean
Whether or not to use warm starting for constraints (initially applying previous frames impulses). This helps the solver converge faster.
Default
```
true
```

Type Alias WorldSettings

Index

Properties

Properties

ccd

Type Declaration

linearCastMaxPenetration: number

Default

linearCastThreshold: number

Default

minVelocityForRestitution: number

Default

contacts

Type Declaration

contactPointPreserveLambdaMaxDistSq: number

Default

gravity

Default

gravityEnabled

Default

layers

narrowphase

Type Declaration

collideOnlyWithActiveEdges: boolean

Default

collideWithBackfaces: boolean

Default

collisionTolerance: number

Default

manifoldTolerance: number

Default

normalCosMaxDeltaRotation: number

Default

penetrationTolerance: number

Default

returnDeepestPoint: boolean

Default

speculativeContactDistance: number

Default

useManifoldReduction: boolean

Default

sleeping

Type Declaration

allowSleeping: boolean

Default

pointVelocitySleepThreshold: number

Default

timeBeforeSleep: number

Default

solver

Type Declaration

baumgarteFactor: number

Default

maxPenetrationDistance: number

Default

minVelocityForRestitution: number

Default

penetrationSlop: number

Default

positionIterations: number

Default

velocityIterations: number

Default

warmStartImpulseRatio: number

Default

warmStarting: boolean

Default

Settings

On This Page