Constraint Functions

Angular Three Cannon provides various constraint functions to create different types of physical constraints between bodies. These functions are used to limit and control the relative movement of physics bodies.

Available Constraint Functions

All constraint functions are available from angular-three-cannon/constraint:

1
import {
2
  injectPointToPoint,
3
  injectConeTwist,
4
  injectDistance,
5
  injectLock,
6
  injectHinge
7
} from 'angular-three-cannon/constraint';

Usage

The general pattern for using these functions is:

1
import { Component, ElementRef, viewChild } from '@angular/core';
2
import { injectHinge } from 'angular-three-cannon/constraint';
3
import { NgtMesh } from 'angular-three';
4

5
@Component({
6
  selector: 'app-hinge-constraint',
7
  standalone: true,
8
  template: `
9
    <ngt-mesh #bodyA>
10
      <!-- Mesh for body A -->
11
    </ngt-mesh>
12
    <ngt-mesh #bodyB>
13
      <!-- Mesh for body B -->
14
    </ngt-mesh>
15
  `,
16
})
17
export class HingeConstraint {
18
  bodyA = viewChild.required<ElementRef<THREE.Mesh>>('bodyA');
19
  bodyB = viewChild.required<ElementRef<THREE.Mesh>>('bodyB');
20

21
  hingeConstraint = injectHinge(
22
    this.bodyA,
23
    this.bodyB,
24
    {
25
      pivotA: [1, 0, 0],
26
      pivotB: [-1, 0, 0],
27
      axisA: [0, 1, 0],
28
      axisB: [0, 1, 0],
29
    }
30
  );
31
}

Constraint Functions

Function	Description	Specific Options
`injectPointToPoint`	Creates a point-to-point constraint	`pivotA`, `pivotB`
`injectConeTwist`	Creates a cone twist constraint	`pivotA`, `pivotB`, `axisA`, `axisB`
`injectDistance`	Creates a distance constraint	`distance`
`injectLock`	Creates a lock constraint	`maxForce`
`injectHinge`	Creates a hinge constraint	`pivotA`, `pivotB`, `axisA`, `axisB`

Common Options

All constraint functions accept two bodies as the first two arguments, followed by an options object. Common options include:

Option	Type	Description
`pivotA`	[x: number, y: number, z: number]	The pivot point for body A in local space
`pivotB`	[x: number, y: number, z: number]	The pivot point for body B in local space
`axisA`	[x: number, y: number, z: number]	The axis for body A (for certain constraints)
`axisB`	[x: number, y: number, z: number]	The axis for body B (for certain constraints)
`maxForce`	number	The maximum force that can be applied to maintain the constraint

Specific Options

PointToPoint Constraint

No additional specific options

ConeTwist Constraint

angle: number - The maximum cone angle in radians
twistAngle: number - The maximum twist angle in radians

Distance Constraint

distance: number - The fixed distance between the bodies

Lock Constraint

No additional specific options

Hinge Constraint

collideConnected: boolean - Whether the connected bodies should collide with each other

Advanced Usage

You can dynamically control constraints using the returned API:

1
import { Component, ElementRef, viewChild, signal } from '@angular/core';
2
import { injectHinge } from 'angular-three-cannon/constraint';
3
import { NgtMesh } from 'angular-three';
4

5
@Component({
6
  selector: 'app-hinge-constraint',
7
  standalone: true,
8
  template: `
9
    <ngt-mesh #bodyA>
10
      <!-- Mesh for body A -->
11
    </ngt-mesh>
12
    <ngt-mesh #bodyB>
13
      <!-- Mesh for body B -->
14
    </ngt-mesh>
15
    <button (click)="toggleMotor()">Toggle Motor</button>
16
  `,
17
})
18
export class HingeConstraint {
19
  bodyA = viewChild.required<ElementRef<THREE.Mesh>>('bodyA');
20
  bodyB = viewChild.required<ElementRef<THREE.Mesh>>('bodyB');
21

22
  motorEnabled = signal(false);
23

24
  hingeConstraint = injectHinge(
25
    this.bodyA,
26
    this.bodyB,
27
    {
28
      pivotA: [1, 0, 0],
29
      pivotB: [-1, 0, 0],
30
      axisA: [0, 1, 0],
31
      axisB: [0, 1, 0],
32
    }
33
  );
34

35
  toggleMotor() {
36
    const api = this.hingeConstraint();
37
    if (api) {
38
      if (this.motorEnabled()) {
39
        api.disableMotor();
40
      } else {
41
        api.enableMotor();
42
        api.setMotorSpeed(1);
43
        api.setMotorMaxForce(10);
44
      }
45
      this.motorEnabled.update(value => !value);
46
    }
47
  }
48
}

This example demonstrates how to toggle a motor on a hinge constraint, showing the advanced control you have over constraints during runtime.