Skip to content

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

import { NgtcPhysics } from 'angular-three-cannon';
import { Component, signal } from '@angular/core';
@Component({
standalone: true,
imports: [NgtcPhysics],
template: `
<ngtc-physics [options]="{ gravity: [0, -9.81, 0], iterations: 5 }">
<!-- physics-enabled objects go here -->
</ngtc-physics>
`,
})
export class PhysicsScene {}

Options

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

OptionTypeDefaultDescription
allowSleepbooleanfalseIf true, allows bodies to fall asleep for better performance
axisIndexnumber0Axis index for broadphase optimization
broadphasestring'Naive'Broadphase algorithm to use. Options: ‘Naive’, ‘SAP’
defaultContactMaterialobject{ contactEquationStiffness: 1e6 }Default contact material properties
frictionGravitynumber[] | nullnullGravity to use for friction calculations
gravitynumber[][0, -9.81, 0]Gravity force applied to all bodies
iterationsnumber5Number of solver iterations per step
quatNormalizeFastbooleanfalseIf true, uses fast quaternion normalization
quatNormalizeSkipnumber0Number of steps to skip before normalizing quaternions
sizenumber1000Maximum number of physics bodies
solverstring'GS'Constraint solver to use. Options: ‘GS’ (Gauss-Seidel)
tolerancenumber0.001Solver tolerance
isPausedbooleanfalseIf true, pauses the physics simulation
maxSubStepsnumber10Maximum number of sub-steps per frame
shouldInvalidatebooleantrueIf true, forces a re-render after each physics step
stepSizenumber1/60Fixed time step size

Advanced Usage

You can dynamically update physics options using Angular Signals:

import { Component, signal } from '@angular/core';
import { NgtcPhysics } from 'angular-three-cannon';
@Component({
standalone: true,
imports: [NgtcPhysics],
template: `
<ngtc-physics [options]="{ gravity: gravity() }">
<!-- physics-enabled objects -->
</ngtc-physics>
`,
})
export class PhysicsScene {
gravity = signal([0, -9.81, 0]);
toggleGravity() {
this.gravity.update((current) => [0, current[1] * -1, 0]);
}
}