threejs-cannones-rigger 1.0.0 → 1.0.3
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/LICENSE +0 -0
- package/dist/threejs-cannones-rigger.cjs +0 -0
- package/dist/threejs-cannones-rigger.d.ts +0 -0
- package/dist/threejs-cannones-rigger.js +0 -0
- package/package.json +41 -41
- package/readme.md +68 -15
package/LICENSE
CHANGED
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
package/package.json
CHANGED
|
@@ -1,44 +1,44 @@
|
|
|
1
1
|
{
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
}
|
|
22
|
-
},
|
|
23
|
-
"scripts": {
|
|
24
|
-
"dev": "vite --config vite.config.site.js",
|
|
25
|
-
"build": "tsc && vite build",
|
|
26
|
-
"build-test-app": "vite build --config vite.config.site.js",
|
|
27
|
-
"preview": "vite preview --config vite.config.site.js"
|
|
28
|
-
},
|
|
29
|
-
"devDependencies": {
|
|
30
|
-
"@types/three": "^0.178.1",
|
|
31
|
-
"cannon-es": "^0.20.0",
|
|
32
|
-
"cannon-es-debugger": "^1.0.0",
|
|
33
|
-
"three": "^0.179.0",
|
|
34
|
-
"threejs-cannones-tube": "^0.0.9",
|
|
35
|
-
"typescript": "~5.8.3",
|
|
36
|
-
"vite": "^7.0.4",
|
|
37
|
-
"vite-plugin-dts": "^4.5.4"
|
|
38
|
-
},
|
|
39
|
-
"peerDependencies": {
|
|
40
|
-
"cannon-es": ">=0.20.0 <1.0.0",
|
|
41
|
-
"three": ">=0.178.0 <1.0.0",
|
|
42
|
-
"threejs-cannones-tube": ">=0.0.7 <1.0.0"
|
|
2
|
+
"name": "threejs-cannones-rigger",
|
|
3
|
+
"author": {
|
|
4
|
+
"name": "pablo bandinopla",
|
|
5
|
+
"url": "https://github.com/bandinopla"
|
|
6
|
+
},
|
|
7
|
+
"description": "Create and position physics colliders in Blender then export them as GLB and load them automatically in ThreeJs with Cannon-es.",
|
|
8
|
+
"version": "1.0.3",
|
|
9
|
+
"type": "module",
|
|
10
|
+
"packageManager": "pnpm@8.15.4",
|
|
11
|
+
"files": [
|
|
12
|
+
"dist"
|
|
13
|
+
],
|
|
14
|
+
"main": "./dist/threejs-cannones-rigger.cjs",
|
|
15
|
+
"module": "./dist/threejs-cannones-rigger.js",
|
|
16
|
+
"types": "./dist/threejs-cannones-rigger.d.ts",
|
|
17
|
+
"exports": {
|
|
18
|
+
".": {
|
|
19
|
+
"import": "./dist/threejs-cannones-rigger.js",
|
|
20
|
+
"require": "./dist/threejs-cannones-rigger.cjs"
|
|
43
21
|
}
|
|
22
|
+
},
|
|
23
|
+
"devDependencies": {
|
|
24
|
+
"@types/three": "^0.178.1",
|
|
25
|
+
"cannon-es": "^0.20.0",
|
|
26
|
+
"cannon-es-debugger": "^1.0.0",
|
|
27
|
+
"three": "^0.179.0",
|
|
28
|
+
"threejs-cannones-tube": "^0.0.9",
|
|
29
|
+
"typescript": "~5.8.3",
|
|
30
|
+
"vite": "^7.0.4",
|
|
31
|
+
"vite-plugin-dts": "^4.5.4"
|
|
32
|
+
},
|
|
33
|
+
"peerDependencies": {
|
|
34
|
+
"cannon-es": ">=0.20.0 <1.0.0",
|
|
35
|
+
"three": ">=0.178.0 <1.0.0",
|
|
36
|
+
"threejs-cannones-tube": ">=0.0.7 <1.0.0"
|
|
37
|
+
},
|
|
38
|
+
"scripts": {
|
|
39
|
+
"dev": "vite --config vite.config.site.js",
|
|
40
|
+
"build": "tsc && vite build",
|
|
41
|
+
"build-test-app": "vite build --config vite.config.site.js",
|
|
42
|
+
"preview": "vite preview --config vite.config.site.js"
|
|
43
|
+
}
|
|
44
44
|
}
|
package/readme.md
CHANGED
|
@@ -1,16 +1,41 @@
|
|
|
1
|
-
|
|
1
|
+
<a href="https://www.npmjs.com/package/threejs-cannones-rigger">
|
|
2
|
+
<img src="https://img.shields.io/npm/v/threejs-cannones-rigger.svg" alt="npm version">
|
|
3
|
+
</a>
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
## Table of Contents
|
|
10
|
+
- [Who is this for?](#who-is-this-for)
|
|
11
|
+
- [Features](#features)
|
|
12
|
+
- [Test your rig](#test-your-rig)
|
|
13
|
+
- [Usage](#usage)
|
|
14
|
+
- [API](#api)
|
|
15
|
+
- [Colliders / Bodies](#colliders--bodies)
|
|
16
|
+
- [Constraints](#constraints)
|
|
17
|
+
- [Relationship Lines](#relationship-lines)
|
|
18
|
+
- [Collision groups and masks](#collision-groups-and-masks)
|
|
19
|
+
- [Custom constaint](#sparkles-custom-constaint)
|
|
20
|
+
- [License](#license)
|
|
2
21
|
|
|
3
22
|
# ThreeJs / Cannon-es Scene Rigger
|
|
4
23
|
### Design in Blender, simulate in Three!
|
|
5
24
|
|
|
6
25
|
Create and place physics colliders in [Blender](http://blender.org/), export as GLB, and automatically set them up in [three.js](https://threejs.org/) with [cannon-es](https://github.com/pmndrs/cannon-es).
|
|
7
26
|
|
|
27
|
+
Watch [Video Tutorial (Rigging a mechanical claw)](https://youtu.be/RtO2KUH9Vig)
|
|
28
|
+
Demo showcase app that inspired this addon: [Mechanical Claw Machine](https://threejs-claw-machine.vercel.app/)
|
|
29
|
+
|
|
8
30
|
This solution includes two tools:
|
|
9
31
|
|
|
10
32
|
1) A Blender addon for creating colliders in Blender
|
|
11
33
|
2) An NPM package to rig the physics in Three.js using cannon-es
|
|
12
34
|
|
|
13
35
|
|
|
36
|
+
## Who is this for?
|
|
37
|
+
Manually building complex physical rigs vía code can be a headache in the making. This toolset aims to make it a smooth visual experience. Focus on the design aspect in Blender, and let the devs work on the details once the rig is exported. Separate concerns.
|
|
38
|
+
|
|
14
39
|
## Features
|
|
15
40
|
|
|
16
41
|
- Automatically creates Cannon bodies for Three.js objects defined inside of Blender ( _using the addon_ ).
|
|
@@ -32,8 +57,11 @@ Just make sure your glb has a camera and it is in the right angle where you want
|
|
|
32
57
|
## Usage
|
|
33
58
|
|
|
34
59
|
### 1) Install the blender addon
|
|
35
|
-
|
|
36
|
-
|
|
60
|
+
Install from disk → [threejs-cannones-addon.py](https://github.com/bandinopla/threejs-cannones-rigger/raw/refs/heads/main/threejs-cannones-addon.py)
|
|
61
|
+
|
|
62
|
+
| Blender → Preferences | Add-ons → Install (.py) | New Object Panel |
|
|
63
|
+
|---------|---------|---------|
|
|
64
|
+
|  |  |  |
|
|
37
65
|
|
|
38
66
|
After installing, when you select an object in the scene inside of blender, you should see new expandable box appear in the Object's tab.
|
|
39
67
|
|
|
@@ -95,8 +123,8 @@ constructor(world: World, scene?: Object3D)
|
|
|
95
123
|
- `getBodyByName(name: string)`: Returns a Cannon body by the name (the name in `userData.name` )
|
|
96
124
|
|
|
97
125
|
---
|
|
98
|
-
#
|
|
99
|
-
|
|
126
|
+
# Colliders / Bodies
|
|
127
|
+
|
|
100
128
|
|
|
101
129
|
#### Box / Sphere Collider
|
|
102
130
|
> Use a default Cube or UV Sphere. Scale and rotate as needed. Only spheres must be scaled uniformly; boxes can be stretched freely.
|
|
@@ -105,7 +133,22 @@ rigger.getBodyByName(name) //-> CANNON.Body
|
|
|
105
133
|
```
|
|
106
134
|
|
|
107
135
|
#### Compound Collider
|
|
108
|
-
|
|
136
|
+
Assign this to an empty. All children will be glued into one collider/Body. The children **should be empty boxes** with your desire scale, rotation and positioning.
|
|
137
|
+
|
|
138
|
+
#### Tube / Cable
|
|
139
|
+
>Creates a flexible cable using [threejs-cannones-tube](https://www.npmjs.com/package/threejs-cannones-tube).
|
|
140
|
+
Add two child empties to the constraint object — one for the head, one for the tail. A and B can optionally anchor the ends.
|
|
141
|
+
|
|
142
|
+
**Material** : If the constraint body is a mesh (like a Box) it will use whatever material that mesh has and assign it to the mesh of the tube.
|
|
143
|
+
```js
|
|
144
|
+
rigger.getCableConstraint(name) //-> CableConstraint
|
|
145
|
+
rigger.getCableConstraint(name).cable //-> CannonTubeRig
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
# Constraints
|
|
149
|
+
|
|
150
|
+
|
|
151
|
+
In all cases, when you call `get___Constraint( name )` the expected name is the name of the object as you read it in blender. Which is automatically put in `userData.name` when you export to glb.
|
|
109
152
|
|
|
110
153
|
#### Glue/Lock Colliders
|
|
111
154
|
> Connect two colliders (A & B) so they behave as a single rigid body. Creates a LockConstraint...
|
|
@@ -135,17 +178,27 @@ rigger.getDistanceConstraint(name) //-> CANNON.DistanceConstraint
|
|
|
135
178
|
> Use this on a visible object (e.g. mesh) to match the position & rotation of a physics collider.
|
|
136
179
|
```js
|
|
137
180
|
rigger.getSyncConstraint(name) //-> SyncConstraint
|
|
138
|
-
```
|
|
181
|
+
```
|
|
139
182
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
183
|
+
# Relationship Lines
|
|
184
|
+
|
|
185
|
+
When a contraints references other objects, lines will appear to easily see their relationships with the currently selected object. You can toogle thouse lines on and off using the "Show Overlays" button.
|
|
143
186
|
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
187
|
+
# Collision groups and masks
|
|
188
|
+
The panel will show two key properties for physics-based collision management when you select a collider's body type. You can select 1 or many (clicking and holding SHIFT)
|
|
189
|
+
>
|
|
190
|
+
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
- **Collision Group `collisionGroup`**: "I'm in group...". Bitmask. Defines which group(s) the selected object belongs to. This is a single group index (0–31) that identifies the object's collision category.
|
|
194
|
+
- **Collision Mask `collisionMask`**: "I collide with...".Bitmask. Specifies which group(s) the object collides with, using a 32-bit boolean array (checkboxes). Each checkbox corresponds to one of the 32 possible collision groups.
|
|
195
|
+
|
|
196
|
+
### Understanding Collision Group and Mask
|
|
197
|
+
- **Collision Group**: Sets which group your object belongs to (0–31). Think of it as the object’s "team" in the physics simulation.
|
|
198
|
+
- **Collision Mask**: Controls which groups your object can collide with. Check boxes (1–32) to choose which "teams" it interacts with. For example, checking Group 2 means it collides with objects in Group 2.
|
|
199
|
+
|
|
200
|
+
> #### When Collisions Don’t Happen
|
|
201
|
+
> A collision between two objects won’t occur if their **Collision Masks** don’t include each other’s **Collision Group**. For example, if Object A’s mask doesn’t check Group 2, and Object B is in Group 2, they won’t collide, even if they touch in the physics simulation.
|
|
149
202
|
|
|
150
203
|
# :sparkles: Custom constaint
|
|
151
204
|
In blender you can select "**Custom Constraint**" and pass a custom id (an arbitraty string of your choosing) then in javascript side, you define it like so:
|