NgtcPhysics

The NgtcPhysics component is the core of Angular Three Cannon. It sets up the physics world and manages the simulation. All physics-enabled objects should be children of this component.

Usage

1
import { NgtcPhysics } from 'angular-three-cannon';
2
import { Component, signal } from '@angular/core';
3

4
@Component({
5
  standalone: true,
6
  imports: [NgtcPhysics],
7
  template: `
8
    <ngtc-physics [options]="{ gravity: [0, -9.81, 0], iterations: 5 }">
9
      <!-- physics-enabled objects go here -->
10
    </ngtc-physics>
11
  `,
12
})
13
export class PhysicsScene {}

Options

The NgtcPhysics component accepts an options input with the following properties:

Option	Type	Default	Description
`allowSleep`	boolean	`false`	If true, allows bodies to fall asleep for better performance
`axisIndex`	number	`0`	Axis index for broadphase optimization
`broadphase`	string	`'Naive'`	Broadphase algorithm to use. Options: ‘Naive’, ‘SAP’
`defaultContactMaterial`	object	`{ contactEquationStiffness: 1e6 }`	Default contact material properties
`frictionGravity`	number[] \| null	`null`	Gravity to use for friction calculations
`gravity`	number[]	`[0, -9.81, 0]`	Gravity force applied to all bodies
`iterations`	number	`5`	Number of solver iterations per step
`quatNormalizeFast`	boolean	`false`	If true, uses fast quaternion normalization
`quatNormalizeSkip`	number	`0`	Number of steps to skip before normalizing quaternions
`size`	number	`1000`	Maximum number of physics bodies
`solver`	string	`'GS'`	Constraint solver to use. Options: ‘GS’ (Gauss-Seidel)
`tolerance`	number	`0.001`	Solver tolerance
`isPaused`	boolean	`false`	If true, pauses the physics simulation
`maxSubSteps`	number	`10`	Maximum number of sub-steps per frame
`shouldInvalidate`	boolean	`true`	If true, forces a re-render after each physics step
`stepSize`	number	`1/60`	Fixed time step size

Advanced Usage

You can dynamically update physics options using Angular Signals:

1
import { Component, signal } from '@angular/core';
2
import { NgtcPhysics } from 'angular-three-cannon';
3

4
@Component({
5
  standalone: true,
6
  imports: [NgtcPhysics],
7
  template: `
8
    <ngtc-physics [options]="{ gravity: gravity() }">
9
      <!-- physics-enabled objects -->
10
    </ngtc-physics>
11
  `,
12
})
13
export class PhysicsScene {
14
  gravity = signal([0, -9.81, 0]);
15

16
  toggleGravity() {
17
    this.gravity.update((current) => [0, current[1] * -1, 0]);
18
  }
19
}