Documentation / scene / GPUHairSimulationOptions

Type Alias: GPUHairSimulationOptions

GPUHairSimulationOptions = object

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:107

Tuning for GPUHairSimulation.

Properties

gravity?

optional gravity?: Vector3

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:109

World-space gravity. Defaults to earth gravity along -Y.

---

damping?

optional damping?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:117

Velocity lost per fixed 1/60 s step, in [0, 1]. 0 keeps full inertia.

Remarks

An exponential decay, so the dial means the same thing whatever GPUHairSimulationOptions.substeps is.

---

globalStiffness?

optional globalStiffness?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:129

How strongly a strand is pulled back to its authored pose, in [0, 1].

Remarks

Off by default, as in TressFX. It anchors a point to a fixed place rather than to its neighbours, which is a spring, and a groom held by springs reads as one. GPUHairSimulationOptions.localStiffness is what holds styling without that; pair this with GPUHairSimulationOptions.globalRange where a groom genuinely should not move far from how it was authored.

---

globalRange?

optional globalRange?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:138

Fraction of each strand, from the root, that GPUHairSimulationOptions.globalStiffness acts on, in [0, 1].

Remarks

0 disables the pull outright - both have to be non-zero for it to do anything.

---

localStiffness?

optional localStiffness?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:149

How strongly a strand keeps the shape it was authored with, in [0, 1].

Remarks

The dial to reach for first. It holds the angle each segment makes with the one before it, measured against that segment's current direction rather than a fixed pose, so a strand keeps its curl while remaining free to hang and swing. It is also what damps a groom: a chain with no bending resistance carries a disturbance up and down its length for seconds.

---

localIterations?

optional localIterations?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:157

Times the local shape constraint is applied per substep, in [1, 8].

Remarks

The constraint moves both points it touches, so one pass falls short of the shape it aims for. More passes converge, at proportional cost.

---

ftlDamping?

optional ftlDamping?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:169

Share of a point's length correction fed back into its parent, in [0, 1].

Remarks

The length constraint satisfies a segment by moving the child alone, which leaves the momentum that correction represents unaccounted for. Unaccounted it accumulates: every root movement pumps the chain, and because the segments are coupled in series it collects at the free end and the groom whips. Handing it back as reverse momentum - Mueller's FTL damping - is what prevents that; 0 reproduces the uncorrected behaviour.

---

vspCoeff?

optional vspCoeff?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:180

How much of the node's motion a strand is carried along by, in [0, 1].

Remarks

Velocity shock propagation. 0 leaves a strand where it was in the world and lets the pinned roots drag it through the constraints, which is what produces lag - but a root moving fast enough outruns its strand within a step and the length constraint has to snap it back. 1 carries the strand rigidly with the node. Lower values give a livelier, floppier groom.

---

vspAccelThreshold?

optional vspAccelThreshold?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:190

Node acceleration above which a strand is carried rigidly, in world units per second squared.

Remarks

Past this, GPUHairSimulationOptions.vspCoeff is treated as 1 for the step, since a hard shove is where lag turns into over-stretching. The default is around five gravities.

---

substeps?

optional substeps?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:192

Integration substeps per fixed step, in [1, 8].

---

colliders?

optional colliders?: SpringCollider[]

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:194

Colliders the strands are pushed out of.

---

friction?

optional friction?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:196

Friction applied to the tangential motion of a contact, in [0, 1].

---

maxSpeedFactor?

optional maxSpeedFactor?: number

Defined in: libs/scene/src/animation/hair/gpu_hair_simulation.ts:204

Per-substep ceiling on how far a point may travel, in segment lengths.

Remarks

A backstop, not a dial: at the default it never engages during ordinary motion. Measured in segment lengths, so it is unit-independent.