Body Functions

Angular Three Cannon provides various body functions to create different types of physics bodies. These functions are used to add physical properties to your 3D objects.

Available Body Functions

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

1
import {
2
  injectBox,
3
  injectSphere,
4
  injectPlane,
5
  injectCylinder,
6
  injectHeightfield,
7
  injectParticle,
8
  injectConvexPolyhedron,
9
  injectTrimesh,
10
  injectCompound
11
} from 'angular-three-cannon/body';

Usage

The general pattern for using these functions is:

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

5
@Component({
6
  selector: 'app-physics-box',
7
  standalone: true,
8
  template: `
9
    <ngt-mesh #mesh>
10
      <ngt-box-geometry />
11
      <ngt-mesh-standard-material />
12
    </ngt-mesh>
13
  `,
14
})
15
export class PhysicsBox {
16
  mesh = viewChild.required<ElementRef<THREE.Mesh>>('mesh');
17

18
  boxBody = injectBox(
19
    () => ({
20
      mass: 1,
21
      position: [0, 5, 0],
22
      args: [1, 1, 1],
23
    }),
24
    this.mesh
25
  );
26
}

Body Functions

Function	Description	Specific Options
`injectBox`	Creates a box-shaped body	`args: [width, height, depth]`
`injectSphere`	Creates a spherical body	`args: [radius]`
`injectPlane`	Creates an infinite plane	No specific options
`injectCylinder`	Creates a cylindrical body	`args: [radiusTop, radiusBottom, height, numSegments]`
`injectHeightfield`	Creates a heightfield body	`args: [data, options]`
`injectParticle`	Creates a particle (point mass)	No specific options
`injectConvexPolyhedron`	Creates a convex polyhedron	`args: [vertices, faces]`
`injectTrimesh`	Creates a triangular mesh body	`args: [vertices, indices]`
`injectCompound`	Creates a compound body	`shapes: Array<{ type, args, position?, rotation? }>`

Common Options

All body functions accept a set of common options:

Option	Type	Description
`mass`	number	The mass of the body (0 for static bodies)
`position`	[x: number, y: number, z: number]	Initial position of the body
`rotation`	[x: number, y: number, z: number]	Initial rotation of the body (in radians)
`velocity`	[x: number, y: number, z: number]	Initial velocity of the body
`angularVelocity`	[x: number, y: number, z: number]	Initial angular velocity of the body
`linearDamping`	number	Linear damping of the body (0 = no damping, 1 = full damping)
`angularDamping`	number	Angular damping of the body
`fixedRotation`	boolean	If true, body will not rotate
`collisionFilterGroup`	number	The collision group the body belongs to
`collisionFilterMask`	number	Which groups this body can collide with
`trigger`	boolean	If true, body acts as a trigger (no collision response)
`onCollide`	function	Callback function when collision occurs
`onCollideBegin`	function	Callback function when collision begins
`onCollideEnd`	function	Callback function when collision ends

Advanced Usage

You can dynamically update body properties using the returned API:

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

5
@Component({
6
  selector: 'app-physics-box',
7
  standalone: true,
8
  template: `
9
    <ngt-mesh #mesh>
10
      <ngt-box-geometry />
11
      <ngt-mesh-standard-material />
12
    </ngt-mesh>
13
    <button (click)="jump()">Jump</button>
14
  `,
15
})
16
export class PhysicsBox {
17
  mesh = viewChild.required<ElementRef<THREE.Mesh>>('mesh');
18

19
  boxBody = injectBox(
20
    () => ({
21
      mass: 1,
22
      position: [0, 5, 0],
23
      args: [1, 1, 1],
24
    }),
25
    this.mesh
26
  );
27

28
  jump() {
29
    const api = this.boxBody();
30
    if (api) {
31
      api.applyImpulse([0, 5, 0], [0, 0, 0]);
32
    }
33
  }
34
}

This example shows how to apply an impulse to make the box “jump” when a button is clicked.