Class UserConstraint`Abstract`

Base class for user-defined N-DOF constraints.

Fully modernized — uses ZPP_UserConstraint directly (extracted to TypeScript). Subclass and override the abstract callback methods to define custom constraints.

Hierarchy (View Summary)

Constraint
- UserConstraint

Index

Constructors

constructor

new UserConstraint(dimensions: number, velocityOnly?: boolean): UserConstraint
Parameters
- dimensions: number
- velocityOnly: boolean = false
Returns UserConstraint
Overrides Constraint.constructor
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:18

Properties

debugDraw

debugDraw: boolean = true

Accessors

active

get active(): boolean
Whether the constraint is currently active (enforced by the solver).

Deactivating a constraint suspends it without removing it from the space.

Returns boolean
Default Value
true
Inherited from Constraint.active
- Defined in packages/nape-js/src/constraint/Constraint.ts:149
set active(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Constraint.active
- Defined in packages/nape-js/src/constraint/Constraint.ts:152

breakUnderError

get breakUnderError(): boolean
When true, the constraint breaks if the positional error exceeds maxError.

Returns boolean
Default Value
false
Inherited from Constraint.breakUnderError
- Defined in packages/nape-js/src/constraint/Constraint.ts:325
set breakUnderError(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Constraint.breakUnderError
- Defined in packages/nape-js/src/constraint/Constraint.ts:328

breakUnderForce

get breakUnderForce(): boolean
When true, the constraint breaks (fires a BREAK event) if the applied force exceeds maxForce in a single step.

Returns boolean
Default Value
false
Inherited from Constraint.breakUnderForce
- Defined in packages/nape-js/src/constraint/Constraint.ts:311
set breakUnderForce(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Constraint.breakUnderForce
- Defined in packages/nape-js/src/constraint/Constraint.ts:314

cbTypes

get cbTypes(): object
The set of CbTypes assigned to this constraint. Used to filter which listeners respond to this constraint's events.

Returns object
Inherited from Constraint.cbTypes
- Defined in packages/nape-js/src/constraint/Constraint.ts:376

compound

get compound(): Compound | null
The compound this constraint belongs to, or null. When set, the constraint's space is managed by the compound.

Returns Compound | null
Inherited from Constraint.compound
- Defined in packages/nape-js/src/constraint/Constraint.ts:121
set compound(value: Compound | null): void
Parameters
- value: Compound | null
Returns void
Inherited from Constraint.compound
- Defined in packages/nape-js/src/constraint/Constraint.ts:125

damping

get damping(): number
Damping ratio for soft constraints (stiff = false).

0 = undamped (oscillates freely), 1 = critically damped. Values > 1 are overdamped. Must be >= 0. Ignored when stiff is true.

Returns number
Default Value
1
Inherited from Constraint.damping
- Defined in packages/nape-js/src/constraint/Constraint.ts:241
set damping(value: number): void
Parameters
- value: number
Returns void
Inherited from Constraint.damping
- Defined in packages/nape-js/src/constraint/Constraint.ts:244

frequency

get frequency(): number
Spring frequency in Hz for soft constraints (stiff = false).

Higher values make the spring stiffer; lower values make it bouncier. Must be > 0. Ignored when stiff is true.

Returns number
Default Value
10
Inherited from Constraint.frequency
- Defined in packages/nape-js/src/constraint/Constraint.ts:216
set frequency(value: number): void
Parameters
- value: number
Returns void
Inherited from Constraint.frequency
- Defined in packages/nape-js/src/constraint/Constraint.ts:219

ignore

get ignore(): boolean
When true the constraint is completely ignored by the engine — bodies are not woken, no impulse is applied, and no callbacks fire.

Returns boolean
Default Value
false
Inherited from Constraint.ignore
- Defined in packages/nape-js/src/constraint/Constraint.ts:183
set ignore(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Constraint.ignore
- Defined in packages/nape-js/src/constraint/Constraint.ts:186

isSleeping

get isSleeping(): boolean
Whether the constraint's simulation component is currently sleeping.

Only valid when the constraint is active and in a space — throws otherwise.

Returns boolean
Inherited from Constraint.isSleeping
- Defined in packages/nape-js/src/constraint/Constraint.ts:352

maxError

get maxError(): number
Maximum positional error (in pixels) allowed before breaking.

Only meaningful when breakUnderError is true. Must be >= 0. Infinity disables the limit.

Returns number
Default Value
Infinity
Inherited from Constraint.maxError
- Defined in packages/nape-js/src/constraint/Constraint.ts:290
set maxError(value: number): void
Parameters
- value: number
Returns void
Inherited from Constraint.maxError
- Defined in packages/nape-js/src/constraint/Constraint.ts:293

maxForce

get maxForce(): number
Maximum force (in Newtons) the constraint may apply per step.

When the required force exceeds this value the constraint becomes slack. If breakUnderForce is true the constraint breaks instead. Must be >= 0. Infinity disables the limit.

Returns number
Default Value
Infinity
Inherited from Constraint.maxForce
- Defined in packages/nape-js/src/constraint/Constraint.ts:267
set maxForce(value: number): void
Parameters
- value: number
Returns void
Inherited from Constraint.maxForce
- Defined in packages/nape-js/src/constraint/Constraint.ts:270

removeOnBreak

get removeOnBreak(): boolean
When true (default), the constraint is automatically removed from its space when it breaks. Set to false to keep it in the space after breaking.

Returns boolean
Default Value
true
Inherited from Constraint.removeOnBreak
- Defined in packages/nape-js/src/constraint/Constraint.ts:340
set removeOnBreak(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Constraint.removeOnBreak
- Defined in packages/nape-js/src/constraint/Constraint.ts:343

space

get space(): Space | null
The space this constraint belongs to, or null if not in a space.

Assign to add/remove the constraint from a space:
```
joint.space = mySpace;  // adds to space
joint.space = null;     // removes from space
```
Cannot be set if the constraint belongs to a Compound.
Returns Space | null
Inherited from Constraint.space
- Defined in packages/nape-js/src/constraint/Constraint.ts:82
set space(value: Space | null): void
Parameters
- value: Space | null
Returns void
Inherited from Constraint.space
- Defined in packages/nape-js/src/constraint/Constraint.ts:86

stiff

get stiff(): boolean
When true (default) the constraint is stiff/rigid. When false the constraint uses a soft spring model driven by frequency and damping.

Returns boolean
Default Value
true
Inherited from Constraint.stiff
- Defined in packages/nape-js/src/constraint/Constraint.ts:199
set stiff(value: boolean): void
Parameters
- value: boolean
Returns void
Inherited from Constraint.stiff
- Defined in packages/nape-js/src/constraint/Constraint.ts:202

userData

get userData(): Record<string, unknown>
Arbitrary user data attached to this constraint. Lazily initialized to {} on first access.

Returns Record<string, unknown>
Inherited from Constraint.userData
- Defined in packages/nape-js/src/constraint/Constraint.ts:365

Methods

__bindVec2

__bindVec2(): Vec2
Returns Vec2
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:50

__broken

__broken(): void
Called when the constraint breaks. Optional override.

Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:67

__clamp

__clamp(_jAcc: number[]): void
Clamp accumulated impulse. Optional override.
Parameters
- _jAcc: number[]
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:94

__copy

__copy(): UserConstraint
Create a copy of this constraint. Must be overridden.

Returns UserConstraint
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:62

__draw

__draw(_debug: any): void
Draw debug visualization. Optional override.
Parameters
- _debug: any
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:73

__eff_mass

__eff_mass(_eff: number[]): void
Compute effective mass matrix (upper triangle). Must be overridden.
Parameters
- _eff: number[]
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:89

__impulse

__impulse(_imp: number[], _body: Body, _out: any): void
Apply impulse to a body. Must be overridden.
Parameters
- _imp: number[]
- _body: Body
- _out: any
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:97

__invalidate

__invalidate(): void
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:165

__position

__position(_err: number[]): void
Compute positional error. Must be overridden for non-velocity-only constraints.
Parameters
- _err: number[]
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:79

__prepare

__prepare(): void
Prepare the constraint for solving. Optional override.

Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:76

__registerBody

__registerBody(oldBody: Body | null, newBody: Body | null): Body | null
Parameters
- oldBody: Body | null
- newBody: Body | null
Returns Body | null
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:175

__validate

__validate(): void
Called to validate the constraint. Optional override.

Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:70

__velocity

__velocity(_err: number[]): void
Compute velocity error. Must be overridden.
Parameters
- _err: number[]
Returns void
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:84

bodyImpulse

bodyImpulse(body: Body): Vec3
The impulse applied to body by this constraint in the last simulation step, expressed as a Vec3 (fx, fy, torque).
Parameters
- body: Body
Returns Vec3
Overrides Constraint.bodyImpulse
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:117

copy

copy(): Constraint
Creates and returns a copy of this constraint with the same parameters. The copy is not automatically added to a space.

Returns Constraint
Inherited from Constraint.copy
- Defined in packages/nape-js/src/constraint/Constraint.ts:419

impulse

impulse(): MatMN
The impulse applied by this constraint in the last simulation step.

The shape of the returned MatMN depends on the constraint's degrees of freedom (e.g., 1×1 for AngleJoint/MotorJoint, 2×1 for PivotJoint/LineJoint, 3×1 for WeldJoint).

Returns MatMN
Overrides Constraint.impulse
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:105

toString

toString(): string
Returns string
Inherited from Constraint.toString
- Defined in packages/nape-js/src/constraint/Constraint.ts:423

visitBodies

visitBodies(lambda: (body: Body) => void): void
Invokes fn once for each distinct body linked to this constraint.
Parameters
- lambda: (body: Body) => void
Returns void
Overrides Constraint.visitBodies
- Defined in packages/nape-js/src/constraint/UserConstraint.ts:138

Class UserConstraintAbstract

Hierarchy (View Summary)

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns UserConstraint

Properties

debugDraw

Accessors

active

Returns boolean

Default Value

Parameters

Returns void

breakUnderError

Returns boolean

Default Value

Parameters

Returns void

breakUnderForce

Returns boolean

Default Value

Parameters

Returns void

cbTypes

Returns object

compound

Returns Compound | null

Parameters

Returns void

damping

Returns number

Default Value

Parameters

Returns void

frequency

Returns number

Default Value

Parameters

Returns void

ignore

Returns boolean

Default Value

Parameters

Returns void

isSleeping

Returns boolean

maxError

Returns number

Default Value

Parameters

Returns void

maxForce

Returns number

Default Value

Parameters

Returns void

removeOnBreak

Returns boolean

Default Value

Parameters

Returns void

space

Returns Space | null

Parameters

Returns void

stiff

Returns boolean

Default Value

Parameters

Returns void

userData

Returns Record<string, unknown>

Methods

__bindVec2

Class UserConstraint`Abstract`