angular-three-cannon 2.0.0-beta.251 → 2.0.0-beta.252
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +90 -4
- package/body/README.md +48 -2
- package/constraint/README.md +46 -2
- package/debug/README.md +36 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,93 @@
|
|
|
1
|
-
# cannon
|
|
1
|
+
# `angular-three-cannon`
|
|
2
2
|
|
|
3
|
-
This library
|
|
3
|
+
This library is a wrapper around the [Cannon.js](https://schteppe.github.io/cannon.js/) physics engine for use with Angular Three.
|
|
4
4
|
|
|
5
|
-
##
|
|
5
|
+
## Installation
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
```bash
|
|
8
|
+
npm install angular-three-cannon cannon-es cannon-es-debugger @pmndrs/cannon-worker-api
|
|
9
|
+
# yarn add angular-three-cannon cannon-es cannon-es-debugger @pmndrs/cannon-worker-api
|
|
10
|
+
# pnpm add angular-three-cannon cannon-es cannon-es-debugger @pmndrs/cannon-worker-api
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
> Make sure to already have `angular-three` installed
|
|
14
|
+
|
|
15
|
+
## Usage
|
|
16
|
+
|
|
17
|
+
```typescript
|
|
18
|
+
@Component({
|
|
19
|
+
template: `
|
|
20
|
+
<ngt-mesh #mesh>
|
|
21
|
+
<ngt-box-geometry />
|
|
22
|
+
</ngt-mesh>
|
|
23
|
+
`,
|
|
24
|
+
})
|
|
25
|
+
export class Box {
|
|
26
|
+
mesh = viewChild.required<ElementRef<Mesh>>('mesh');
|
|
27
|
+
|
|
28
|
+
constructor() {
|
|
29
|
+
// Make this mesh a Box body in Physics. Only works within ngtc-physics
|
|
30
|
+
injectBox(() => ({ mass: 10000, position: [0, 0, 0], args: [1, 1, 1] }), this.mesh);
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
@Component({
|
|
35
|
+
template: `
|
|
36
|
+
<ngtc-physics>
|
|
37
|
+
<app-box />
|
|
38
|
+
</ngtc-physics>
|
|
39
|
+
`,
|
|
40
|
+
imports: [NgtcPhysics, Box],
|
|
41
|
+
})
|
|
42
|
+
export class SceneGraph {}
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Inputs
|
|
46
|
+
|
|
47
|
+
- `allowSleep?: boolean`
|
|
48
|
+
- `axisIndex?: 0 | 1 | 2`
|
|
49
|
+
- `broadphase?: 'Naive' | 'SAP'`
|
|
50
|
+
- `defaultContactMaterial?: ContactMaterialOptions`
|
|
51
|
+
- `frictionGravity?: Vector3 | null`
|
|
52
|
+
- `gravity?: Vector3`
|
|
53
|
+
- `isPaused?: boolean`
|
|
54
|
+
- `iterations?: number`
|
|
55
|
+
- `maxSubSteps?: number`
|
|
56
|
+
- `quatNormalizeFast?: boolean`
|
|
57
|
+
- `quatNormalizeSkip?: number`
|
|
58
|
+
- `shouldInvalidate?: boolean`
|
|
59
|
+
- `size?: number`
|
|
60
|
+
- `solver?: 'GS' | 'Split'`
|
|
61
|
+
- `stepSize?: number`
|
|
62
|
+
- `tolerance?: number`
|
|
63
|
+
|
|
64
|
+
## NgtcPhysicsApi
|
|
65
|
+
|
|
66
|
+
`NgtcPhysicsApi` is an interface that provides access to the internal state and functionality of the `ngtc-physics` component. You can use it to interact with the physics simulation, subscribe to events, and access references to physics bodies.
|
|
67
|
+
|
|
68
|
+
```typescript
|
|
69
|
+
export class Box {
|
|
70
|
+
physicsApi = injectPhysicsApi();
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
The `NgtcPhysicsApi` provides the following properties:
|
|
75
|
+
|
|
76
|
+
- `bodies`: A dictionary mapping object UUIDs to their corresponding body indices in the physics simulation.
|
|
77
|
+
- `events`: An object for subscribing to physics events (e.g., collide, collideBegin, collideEnd, rayhit).
|
|
78
|
+
- `refs`: An object containing references to the THREE.js objects that are part of the physics simulation.
|
|
79
|
+
- `scaleOverrides`: An object for setting custom scale values for specific objects in the simulation.
|
|
80
|
+
- `subscriptions`: An object for managing event subscriptions.
|
|
81
|
+
- `worker`: A signal representing the Cannon.js worker used for physics calculations.
|
|
82
|
+
|
|
83
|
+
## Debug
|
|
84
|
+
|
|
85
|
+
Check [./debug/README.md]
|
|
86
|
+
|
|
87
|
+
## Bodies
|
|
88
|
+
|
|
89
|
+
Check [./body/README.md]
|
|
90
|
+
|
|
91
|
+
## Constraints
|
|
92
|
+
|
|
93
|
+
Check [./constraint/README.md]
|
package/body/README.md
CHANGED
|
@@ -1,3 +1,49 @@
|
|
|
1
|
-
# angular-three-cannon/body
|
|
1
|
+
# `angular-three-cannon/body`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This module provides a set of custom injector functions to create physics bodies that link `ngt-*` objects in THREE.js with bodies in the Cannon.js physics world. These functions simplify the process of adding physics behavior to your 3D objects.
|
|
4
|
+
|
|
5
|
+
### Available `inject*` Functions
|
|
6
|
+
|
|
7
|
+
| Function | Description | `getProps` Arguments | `object` Type |
|
|
8
|
+
| :----------------------- | :----------------------------------------------- | :----------------------------------------------------------------------- | :------------ |
|
|
9
|
+
| `injectBox` | Creates a box-shaped physics body. | `mass`, `position`, `args: [width, height, depth]` | `ElementRef` |
|
|
10
|
+
| `injectConvexPolyhedron` | Creates a convex polyhedron-shaped physics body. | `mass`, `position`, `vertices`, `faces` | `ElementRef` |
|
|
11
|
+
| `injectCylinder` | Creates a cylinder-shaped physics body. | `mass`, `position`, `radiusTop`, `radiusBottom`, `height`, `numSegments` | `ElementRef` |
|
|
12
|
+
| `injectHeightfield` | Creates a heightfield-shaped physics body. | `mass`, `position`, `data`, `elementSize` | `ElementRef` |
|
|
13
|
+
| `injectParticle` | Creates a particle physics body. | `mass`, `position` | `ElementRef` |
|
|
14
|
+
| `injectPlane` | Creates a plane-shaped physics body. | `mass`, `position` | `ElementRef` |
|
|
15
|
+
| `injectSphere` | Creates a sphere-shaped physics body. | `mass`, `position`, `radius` | `ElementRef` |
|
|
16
|
+
| `injectTrimesh` | Creates a trimesh-shaped physics body. | `mass`, `position`, `vertices`, `indices` | `ElementRef` |
|
|
17
|
+
| `injectCompound` | Creates a compound physics body. | `mass`, `position`, `shapes` | `ElementRef` |
|
|
18
|
+
|
|
19
|
+
**All functions also accept an optional `options` argument for additional customization.**
|
|
20
|
+
|
|
21
|
+
### Simple Usage of `injectBox()`
|
|
22
|
+
|
|
23
|
+
```typescript
|
|
24
|
+
@Component({
|
|
25
|
+
template: `
|
|
26
|
+
<ngt-mesh #mesh>
|
|
27
|
+
<ngt-box-geometry />
|
|
28
|
+
</ngt-mesh>
|
|
29
|
+
`,
|
|
30
|
+
})
|
|
31
|
+
export class Box {
|
|
32
|
+
mesh = viewChild.required<ElementRef<Mesh>>('mesh');
|
|
33
|
+
|
|
34
|
+
constructor() {
|
|
35
|
+
// Make this mesh a Box body in Physics. Only works within ngtc-physics
|
|
36
|
+
injectBox(() => ({ mass: 10000, position: [0, 0, 0], args: [1, 1, 1] }), this.mesh);
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
@Component({
|
|
41
|
+
template: `
|
|
42
|
+
<ngtc-physics>
|
|
43
|
+
<app-box />
|
|
44
|
+
</ngtc-physics>
|
|
45
|
+
`,
|
|
46
|
+
imports: [NgtcPhysics, Box],
|
|
47
|
+
})
|
|
48
|
+
export class SceneGraph {}
|
|
49
|
+
```
|
package/constraint/README.md
CHANGED
|
@@ -1,3 +1,47 @@
|
|
|
1
|
-
# angular-three-cannon/constraint
|
|
1
|
+
# `angular-three-cannon/constraint`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This module provides functions to create physics constraints that link physics bodies in the Cannon.js physics world. These functions simplify the process of adding constraints between your 3D objects.
|
|
4
|
+
|
|
5
|
+
### Available `inject*` Functions
|
|
6
|
+
|
|
7
|
+
| Function | Description | Arguments |
|
|
8
|
+
| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------- |
|
|
9
|
+
| `injectPointToPoint` | Creates a point-to-point constraint between two bodies. The constraint tries to keep the distance between the anchor points constant. | `objectA`, `objectB`, `getProps` |
|
|
10
|
+
| `injectConeTwist` | Creates a cone-twist constraint between two bodies. The constraint attempts to keep the bodies aligned along a common axis, allowing swing and twist motion. | `objectA`, `objectB`, `getProps` |
|
|
11
|
+
| `injectDistance` | Creates a distance constraint between two bodies. The constraint tries to keep the distance between the bodies' center of masses constant. | `objectA`, `objectB`, `getProps` |
|
|
12
|
+
| `injectLock` | Creates a lock constraint between two bodies. The constraint completely locks the motion of one body relative to another. | `objectA`, `objectB`, `getProps` |
|
|
13
|
+
| `injectHinge` | Creates a hinge constraint between two bodies. The constraint allows for rotation around a shared axis, like a door hinge. | `objectA`, `objectB`, `getProps` |
|
|
14
|
+
|
|
15
|
+
**All functions' `getProps` argument is a function that returns the properties of the constraint.**
|
|
16
|
+
|
|
17
|
+
### Simple Usage of `injectHinge()`
|
|
18
|
+
|
|
19
|
+
```typescript
|
|
20
|
+
import { Component, viewChild, ElementRef } from '@angular/core';
|
|
21
|
+
import { injectHinge } from 'angular-three-cannon/constraint';
|
|
22
|
+
|
|
23
|
+
@Component({
|
|
24
|
+
template: `
|
|
25
|
+
<ngt-mesh #mesh1>
|
|
26
|
+
<ngt-box-geometry />
|
|
27
|
+
</ngt-mesh>
|
|
28
|
+
<ngt-mesh #mesh2>
|
|
29
|
+
<ngt-box-geometry />
|
|
30
|
+
</ngt-mesh>
|
|
31
|
+
`,
|
|
32
|
+
})
|
|
33
|
+
export class HingedBoxes {
|
|
34
|
+
mesh1 = viewChild.required<ElementRef<Mesh>>('mesh1');
|
|
35
|
+
mesh2 = viewChild.required<ElementRef<Mesh>>('mesh2');
|
|
36
|
+
|
|
37
|
+
constructor() {
|
|
38
|
+
// Create a hinge constraint between mesh1 and mesh2. Only works within <ngtc-physics>
|
|
39
|
+
injectHinge(this.mesh1, this.mesh2, () => ({
|
|
40
|
+
pivotA: [0, 0.5, 0], // hinge location on the first body
|
|
41
|
+
pivotB: [0, -0.5, 0], // hinge location on the second body
|
|
42
|
+
axisA: [0, 1, 0], // axis of rotation on the first body
|
|
43
|
+
axisB: [0, 1, 0], // axis of rotation on the second body
|
|
44
|
+
}));
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
```
|
package/debug/README.md
CHANGED
|
@@ -1,3 +1,37 @@
|
|
|
1
|
-
# angular-three-cannon/debug
|
|
1
|
+
# `angular-three-cannon/debug`
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This module provides the `NgtcDebug` directive, which allows you to visualize the physics bodies within your Angular Three Cannon simulations.
|
|
4
|
+
|
|
5
|
+
## NgtcDebugApi
|
|
6
|
+
|
|
7
|
+
The `NgtcDebugApi` interface provides methods to interact with the debug renderer:
|
|
8
|
+
|
|
9
|
+
- `add(uuid: string, props: BodyProps, type: BodyShapeType)`: Adds a physics body to the debug renderer.
|
|
10
|
+
- `remove(uuid: string)`: Removes a physics body from the debug renderer.
|
|
11
|
+
|
|
12
|
+
### `injectNgtcDebugApi`
|
|
13
|
+
|
|
14
|
+
The `injectNgtcDebugApi` function is used to inject the `NgtcDebugApi` into your components, enabling you to control the debug visualization.
|
|
15
|
+
|
|
16
|
+
## NgtcDebug
|
|
17
|
+
|
|
18
|
+
The `NgtcDebug` directive is applied to the `ngtc-physics` component to enable physics debugging. It has the following inputs:
|
|
19
|
+
|
|
20
|
+
- `debug`: An object containing the following properties:
|
|
21
|
+
|
|
22
|
+
- `enabled`: (boolean) Whether the debug visualization is enabled (default: true).
|
|
23
|
+
- `color`: (string) The color of the debug visualization (default: 'black').
|
|
24
|
+
- `impl`: (typeof CannonDebugger) The implementation of the CannonDebugger to use (default: CannonDebugger).
|
|
25
|
+
- `scale`: (number) The scale of the debug visualization (default: 1).
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
```html
|
|
30
|
+
<ngtc-physics debug></ngtc-physics>
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
You can customize the debug visualization by providing input values within the `debug` object:
|
|
34
|
+
|
|
35
|
+
```html
|
|
36
|
+
<ngtc-physics [debug]="{enabled: true, color: 'red', scale: 0.5}"></ngtc-physics>
|
|
37
|
+
```
|