Skip to content

Commit 824ef24

Browse files
nartcnartc
committed
docs: add docs for cannon (WIP)
1 parent 749b97b commit 824ef24

File tree

6 files changed

+444
-1
lines changed

6 files changed

+444
-1
lines changed

‎apps/astro-docs/astro.config.mjs

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -174,6 +174,9 @@ export default defineConfig({
174174
{ label: 'Introduction', slug: 'cannon/introduction' },
175175
{ label: 'How it works', slug: 'cannon/how-it-works' },
176176
{ label: 'Debug', slug: 'cannon/debug' },
177+
{ label: 'Physics', slug: 'cannon/physics' },
178+
{ label: 'Body Functions', slug: 'cannon/bodies' },
179+
{ label: 'Constraint Functions', slug: 'cannon/constraints' },
177180
],
178181
},
179182
{
@@ -182,6 +185,7 @@ export default defineConfig({
182185
items: [
183186
{ label: 'Introduction', slug: 'postprocessing/introduction' },
184187
{ label: 'How it works', slug: 'postprocessing/how-it-works' },
188+
{ label: 'EffectComposer', slug: 'postprocessing/effect-composer' },
185189
],
186190
},
187191
{

‎apps/astro-docs/src/content/docs/cannon/bodies.mdx

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
title: Body Functions
3+
description: Detailed explanation of the Body functions in Angular Three Cannon
4+
---
5+
6+
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.
7+
8+
## Available Body Functions
9+
10+
All body functions are available from `angular-three-cannon/body`:
11+
12+
```angular-ts
13+
import {
14+
injectBox,
15+
injectSphere,
16+
injectPlane,
17+
injectCylinder,
18+
injectHeightfield,
19+
injectParticle,
20+
injectConvexPolyhedron,
21+
injectTrimesh,
22+
injectCompound
23+
} from 'angular-three-cannon/body';
24+
```
25+
26+
## Usage
27+
28+
The general pattern for using these functions is:
29+
30+
```angular-ts
31+
import { Component, ElementRef, viewChild } from '@angular/core';
32+
import { injectBox } from 'angular-three-cannon/body';
33+
import { NgtMesh } from 'angular-three';
34+
35+
@Component({
36+
selector: 'app-physics-box',
37+
standalone: true,
38+
template: `
39+
<ngt-mesh #mesh>
40+
<ngt-box-geometry />
41+
<ngt-mesh-standard-material />
42+
</ngt-mesh>
43+
`,
44+
})
45+
export class PhysicsBox {
46+
mesh = viewChild.required<ElementRef<THREE.Mesh>>('mesh');
47+
48+
boxBody = injectBox(
49+
() => ({
50+
mass: 1,
51+
position: [0, 5, 0],
52+
args: [1, 1, 1],
53+
}),
54+
this.mesh
55+
);
56+
}
57+
```
58+
59+
## Body Functions
60+
61+
| Function | Description | Specific Options |
62+
|----------|-------------|------------------|
63+
| `injectBox` | Creates a box-shaped body | `args: [width, height, depth]` |
64+
| `injectSphere` | Creates a spherical body | `args: [radius]` |
65+
| `injectPlane` | Creates an infinite plane | No specific options |
66+
| `injectCylinder` | Creates a cylindrical body | `args: [radiusTop, radiusBottom, height, numSegments]` |
67+
| `injectHeightfield` | Creates a heightfield body | `args: [data, options]` |
68+
| `injectParticle` | Creates a particle (point mass) | No specific options |
69+
| `injectConvexPolyhedron` | Creates a convex polyhedron | `args: [vertices, faces]` |
70+
| `injectTrimesh` | Creates a triangular mesh body | `args: [vertices, indices]` |
71+
| `injectCompound` | Creates a compound body | `shapes: Array<{ type, args, position?, rotation? }>` |
72+
73+
## Common Options
74+
75+
All body functions accept a set of common options:
76+
77+
| Option | Type | Description |
78+
|--------|------|-------------|
79+
| `mass` | number | The mass of the body (0 for static bodies) |
80+
| `position` | [x: number, y: number, z: number] | Initial position of the body |
81+
| `rotation` | [x: number, y: number, z: number] | Initial rotation of the body (in radians) |
82+
| `velocity` | [x: number, y: number, z: number] | Initial velocity of the body |
83+
| `angularVelocity` | [x: number, y: number, z: number] | Initial angular velocity of the body |
84+
| `linearDamping` | number | Linear damping of the body (0 = no damping, 1 = full damping) |
85+
| `angularDamping` | number | Angular damping of the body |
86+
| `fixedRotation` | boolean | If true, body will not rotate |
87+
| `collisionFilterGroup` | number | The collision group the body belongs to |
88+
| `collisionFilterMask` | number | Which groups this body can collide with |
89+
| `trigger` | boolean | If true, body acts as a trigger (no collision response) |
90+
| `onCollide` | function | Callback function when collision occurs |
91+
| `onCollideBegin` | function | Callback function when collision begins |
92+
| `onCollideEnd` | function | Callback function when collision ends |
93+
94+
## Advanced Usage
95+
96+
You can dynamically update body properties using the returned API:
97+
98+
```angular-ts
99+
import { Component, ElementRef, viewChild, signal } from '@angular/core';
100+
import { injectBox } from 'angular-three-cannon/body';
101+
import { NgtMesh } from 'angular-three';
102+
103+
@Component({
104+
selector: 'app-physics-box',
105+
standalone: true,
106+
template: `
107+
<ngt-mesh #mesh>
108+
<ngt-box-geometry />
109+
<ngt-mesh-standard-material />
110+
</ngt-mesh>
111+
<button (click)="jump()">Jump</button>
112+
`,
113+
})
114+
export class PhysicsBox {
115+
mesh = viewChild.required<ElementRef<THREE.Mesh>>('mesh');
116+
117+
boxBody = injectBox(
118+
() => ({
119+
mass: 1,
120+
position: [0, 5, 0],
121+
args: [1, 1, 1],
122+
}),
123+
this.mesh
124+
);
125+
126+
jump() {
127+
const api = this.boxBody();
128+
if (api) {
129+
api.applyImpulse([0, 5, 0], [0, 0, 0]);
130+
}
131+
}
132+
}
133+
```
134+
135+
This example shows how to apply an impulse to make the box "jump" when a button is clicked.

‎apps/astro-docs/src/content/docs/cannon/constraints.mdx

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
title: Constraint Functions
3+
description: Detailed explanation of the Constraint functions in Angular Three Cannon
4+
---
5+
6+
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.
7+
8+
## Available Constraint Functions
9+
10+
All constraint functions are available from `angular-three-cannon/constraint`:
11+
12+
```angular-ts
13+
import {
14+
injectPointToPoint,
15+
injectConeTwist,
16+
injectDistance,
17+
injectLock,
18+
injectHinge
19+
} from 'angular-three-cannon/constraint';
20+
```
21+
22+
## Usage
23+
24+
The general pattern for using these functions is:
25+
26+
```angular-ts
27+
import { Component, ElementRef, viewChild } from '@angular/core';
28+
import { injectHinge } from 'angular-three-cannon/constraint';
29+
import { NgtMesh } from 'angular-three';
30+
31+
@Component({
32+
selector: 'app-hinge-constraint',
33+
standalone: true,
34+
template: `
35+
<ngt-mesh #bodyA>
36+
<!-- Mesh for body A -->
37+
</ngt-mesh>
38+
<ngt-mesh #bodyB>
39+
<!-- Mesh for body B -->
40+
</ngt-mesh>
41+
`,
42+
})
43+
export class HingeConstraint {
44+
bodyA = viewChild.required<ElementRef<THREE.Mesh>>('bodyA');
45+
bodyB = viewChild.required<ElementRef<THREE.Mesh>>('bodyB');
46+
47+
hingeConstraint = injectHinge(
48+
this.bodyA,
49+
this.bodyB,
50+
{
51+
pivotA: [1, 0, 0],
52+
pivotB: [-1, 0, 0],
53+
axisA: [0, 1, 0],
54+
axisB: [0, 1, 0],
55+
}
56+
);
57+
}
58+
```
59+
60+
## Constraint Functions
61+
62+
| Function | Description | Specific Options |
63+
|----------|-------------|------------------|
64+
| `injectPointToPoint` | Creates a point-to-point constraint | `pivotA`, `pivotB` |
65+
| `injectConeTwist` | Creates a cone twist constraint | `pivotA`, `pivotB`, `axisA`, `axisB` |
66+
| `injectDistance` | Creates a distance constraint | `distance` |
67+
| `injectLock` | Creates a lock constraint | `maxForce` |
68+
| `injectHinge` | Creates a hinge constraint | `pivotA`, `pivotB`, `axisA`, `axisB` |
69+
70+
## Common Options
71+
72+
All constraint functions accept two bodies as the first two arguments, followed by an options object. Common options include:
73+
74+
| Option | Type | Description |
75+
|--------|------|-------------|
76+
| `pivotA` | [x: number, y: number, z: number] | The pivot point for body A in local space |
77+
| `pivotB` | [x: number, y: number, z: number] | The pivot point for body B in local space |
78+
| `axisA` | [x: number, y: number, z: number] | The axis for body A (for certain constraints) |
79+
| `axisB` | [x: number, y: number, z: number] | The axis for body B (for certain constraints) |
80+
| `maxForce` | number | The maximum force that can be applied to maintain the constraint |
81+
82+
## Specific Options
83+
84+
### PointToPoint Constraint
85+
- No additional specific options
86+
87+
### ConeTwist Constraint
88+
- `angle`: number - The maximum cone angle in radians
89+
- `twistAngle`: number - The maximum twist angle in radians
90+
91+
### Distance Constraint
92+
- `distance`: number - The fixed distance between the bodies
93+
94+
### Lock Constraint
95+
- No additional specific options
96+
97+
### Hinge Constraint
98+
- `collideConnected`: boolean - Whether the connected bodies should collide with each other
99+
100+
## Advanced Usage
101+
102+
You can dynamically control constraints using the returned API:
103+
104+
```angular-ts
105+
import { Component, ElementRef, viewChild, signal } from '@angular/core';
106+
import { injectHinge } from 'angular-three-cannon/constraint';
107+
import { NgtMesh } from 'angular-three';
108+
109+
@Component({
110+
selector: 'app-hinge-constraint',
111+
standalone: true,
112+
template: `
113+
<ngt-mesh #bodyA>
114+
<!-- Mesh for body A -->
115+
</ngt-mesh>
116+
<ngt-mesh #bodyB>
117+
<!-- Mesh for body B -->
118+
</ngt-mesh>
119+
<button (click)="toggleMotor()">Toggle Motor</button>
120+
`,
121+
})
122+
export class HingeConstraint {
123+
bodyA = viewChild.required<ElementRef<THREE.Mesh>>('bodyA');
124+
bodyB = viewChild.required<ElementRef<THREE.Mesh>>('bodyB');
125+
126+
motorEnabled = signal(false);
127+
128+
hingeConstraint = injectHinge(
129+
this.bodyA,
130+
this.bodyB,
131+
{
132+
pivotA: [1, 0, 0],
133+
pivotB: [-1, 0, 0],
134+
axisA: [0, 1, 0],
135+
axisB: [0, 1, 0],
136+
}
137+
);
138+
139+
toggleMotor() {
140+
const api = this.hingeConstraint();
141+
if (api) {
142+
if (this.motorEnabled()) {
143+
api.disableMotor();
144+
} else {
145+
api.enableMotor();
146+
api.setMotorSpeed(1);
147+
api.setMotorMaxForce(10);
148+
}
149+
this.motorEnabled.update(value => !value);
150+
}
151+
}
152+
}
153+
```
154+
155+
This example demonstrates how to toggle a motor on a hinge constraint, showing the advanced control you have over constraints during runtime.

‎apps/astro-docs/src/content/docs/cannon/debug.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ export class SceneGraph {}
4040

4141
### Passing options to `NgtcDebug`
4242

43-
We can pas options to `NgtcDebug` by passing in an object to the `debug` input
43+
We can pass options to `NgtcDebug` by passing in an object to the `debug` input
4444

4545
```angular-ts
4646
@Component({

‎apps/astro-docs/src/content/docs/cannon/physics.mdx

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: NgtcPhysics
3+
description: Detailed explanation of the NgtcPhysics component and its options
4+
---
5+
6+
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.
7+
8+
## Usage
9+
10+
```angular-ts
11+
import { NgtcPhysics } from 'angular-three-cannon';
12+
import { Component, signal } from '@angular/core';
13+
14+
@Component({
15+
standalone: true,
16+
imports: [NgtcPhysics],
17+
template: `
18+
<ngtc-physics [options]="{ gravity: [0, -9.81, 0], iterations: 5 }">
19+
<!-- physics-enabled objects go here -->
20+
</ngtc-physics>
21+
`,
22+
})
23+
export class PhysicsScene {}
24+
```
25+
26+
## Options
27+
28+
The `NgtcPhysics` component accepts an `options` input with the following properties:
29+
30+
| Option | Type | Default | Description |
31+
|--------|------|---------|-------------|
32+
| `allowSleep` | boolean | `false` | If true, allows bodies to fall asleep for better performance |
33+
| `axisIndex` | number | `0` | Axis index for broadphase optimization |
34+
| `broadphase` | string | `'Naive'` | Broadphase algorithm to use. Options: 'Naive', 'SAP' |
35+
| `defaultContactMaterial` | object | `{ contactEquationStiffness: 1e6 }` | Default contact material properties |
36+
| `frictionGravity` | number[] \| null | `null` | Gravity to use for friction calculations |
37+
| `gravity` | number[] | `[0, -9.81, 0]` | Gravity force applied to all bodies |
38+
| `iterations` | number | `5` | Number of solver iterations per step |
39+
| `quatNormalizeFast` | boolean | `false` | If true, uses fast quaternion normalization |
40+
| `quatNormalizeSkip` | number | `0` | Number of steps to skip before normalizing quaternions |
41+
| `size` | number | `1000` | Maximum number of physics bodies |
42+
| `solver` | string | `'GS'` | Constraint solver to use. Options: 'GS' (Gauss-Seidel) |
43+
| `tolerance` | number | `0.001` | Solver tolerance |
44+
| `isPaused` | boolean | `false` | If true, pauses the physics simulation |
45+
| `maxSubSteps` | number | `10` | Maximum number of sub-steps per frame |
46+
| `shouldInvalidate` | boolean | `true` | If true, forces a re-render after each physics step |
47+
| `stepSize` | number | `1/60` | Fixed time step size |
48+
49+
## Advanced Usage
50+
51+
You can dynamically update physics options using Angular Signals:
52+
53+
```angular-ts
54+
import { Component, signal } from '@angular/core';
55+
import { NgtcPhysics } from 'angular-three-cannon';
56+
57+
@Component({
58+
standalone: true,
59+
imports: [NgtcPhysics],
60+
template: `
61+
<ngtc-physics [options]="{ gravity: gravity() }">
62+
<!-- physics-enabled objects -->
63+
</ngtc-physics>
64+
`,
65+
})
66+
export class PhysicsScene {
67+
gravity = signal([0, -9.81, 0]);
68+
69+
toggleGravity() {
70+
this.gravity.update((current) => [0, current[1] * -1, 0]);
71+
}
72+
}
73+
```

0 commit comments

Comments
 (0)