threejs-cannones-rigger 1.0.1 → 1.0.4

package/dist/threejs-cannones-rigger.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("cannon-es"),i=require("three"),B=require("threejs-cannones-tube");function b(h){return h.reduce((n,t,e)=>n|t<<e,0)}const w=new i.Vector3,y=new i.Vector3,Q=new i.Quaternion,j=new i.Quaternion;class D{constructor(n,t){this.world=n,t&&this.rigScene(t)}obj2bod=new Map;constraints=[];customId2ConstraintFactory=new Map;customConstraints=new Map;registerCustomConstraint(n,t){this.customId2ConstraintFactory.set(n,t)}getConstraintByName(n){return this.constraints.find(t=>t.name==n)}getCustomConstraint(n){return this.customConstraints.get(n)}getCableConstraint(n){return this.getConstraintByName(n)}getSyncConstraint(n){return this.getConstraintByName(n)}getLockConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getHingeConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getPointConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getDistanceConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getBodyByName(n){for(const[t,e]of this.obj2bod.entries())if(t.userData.name===n)return e}rigScene(n){n.traverse(t=>{let e;t.userData.threejscannones_cgroup&&(t.userData.threejscannones_cgroup=b(t.userData.threejscannones_cgroup)),t.userData.threejscannones_cwith&&(t.userData.threejscannones_cwith=b(t.userData.threejscannones_cwith)),t.userData.threejscannones_type==1?e=this.createCollider(new c.Box(new c.Vec3(t.scale.x,t.scale.y,t.scale.z)),t):t.userData.threejscannones_type==2?e=this.createCollider(new c.Sphere(t.scale.x),t):t.userData.threejscannones_type==3&&(e=this.createCollider(void 0,t),this.addCompoundShapes(e,t))}),n.traverse(t=>{const e=this.getBodyByName(t.userData.threejscannones_A?.name),o=this.getBodyByName(t.userData.threejscannones_B?.name);let s;switch(t.userData.threejscannones_type){case 7:s=this.createDistanceConstraint(e,o);break;case 6:s=this.createPointConstraint(e,o,t);break;case 5:s=this.createHingeConstraint(e,o,t);break;case 4:s=this.createLockConstraint(e,o);break;case 8:const a=this.getBodyByName(t.userData.threejscannones_syncSource?.name);this.createSyncBetween(t,a);break;case 9:this.createCable(t,e,o);break;case 10:this.createCustomConstraint(t,e,o)}s&&this.constraints.push(new C(t,s))})}clear(){for(w.set(0,0,0),y.set(0,0,0),Q.set(0,0,0,0),j.set(0,0,0,0);this.constraints.length;)this.constraints.pop().removeFrom(this.world);for(const[n,t]of this.obj2bod.entries())this.world.removeBody(t);this.obj2bod.clear()}addCompoundShapes(n,t){const e=t.children;t.updateMatrixWorld();const o=t.getWorldPosition(new i.Vector3),s=t.getWorldQuaternion(new i.Quaternion),a=s.clone().invert();for(const r of e){r.updateMatrixWorld();const u=r.getWorldPosition(new i.Vector3),m=r.getWorldQuaternion(new i.Quaternion),d=r.getWorldScale(new i.Vector3),p=u.clone().sub(o).applyQuaternion(a),l=a.clone().multiply(m),T=new c.Vec3(p.x,p.y,p.z),k=new c.Quaternion(l.x,l.y,l.z,l.w),v=new c.Vec3(d.x,d.y,d.z),x=new c.Box(v);n.addShape(x,T,k)}return n.position.copy(new c.Vec3(o.x,o.y,o.z)),n.quaternion.copy(new c.Quaternion(s.x,s.y,s.z,s.w)),n}createCustomConstraint(n,t,e){let o=n.userData.threejscannones_cgroup??1,s=n.userData.threejscannones_cwith??1;const a=n.userData.threejscannones_customId;if(!a)throw new Error("A custom constraint MUST have an id...");const r=this.customId2ConstraintFactory.get(a);if(!r)throw new Error(`Custom constraint with id ${a} not found. Dis you forgot to call registerCustomConstraint?`);const u=r({obj:n,collisionGroup:o,collisionMask:s,A:t,B:e});this.customConstraints.set(n.userData.name,u)}createCable(n,t,e){let o=1,s=!1,a=new i.Vector3;n.children.length>1&&(n.children[0].getWorldPosition(w),n.children[1].localToWorld(y),o=w.distanceTo(y),s=!0,a.copy(y));const r=new B.CannonTubeRig(o,20,.1,8);r.material=n instanceof i.Mesh?n.material:new i.MeshNormalMaterial,n.parent?.add(r),s&&(r.position.copy(w),r.lookAt(y)),r.addToPhysicalWorld(this.world),r.syncRig(),this.constraints.push(new g(this.world,n,r,t,e))}createSyncBetween(n,t){if(!t){console.warn(`Object ${n.name} points to a non existent collider for it's sync constrain.`);return}const e=new f(n,t);this.constraints.push(e)}createLockConstraint(n,t){const e=new c.LockConstraint(n,t);return e.collideConnected=!1,this.world.addConstraint(e),e}createHingeConstraint(n,t,e){const o=e.getWorldPosition(new i.Vector3),s=new i.Vector3(0,1,0).applyQuaternion(e.getWorldQuaternion(new i.Quaternion)).normalize(),a=new c.Vec3(o.x,o.y,o.z),r=new c.Vec3(s.x,s.y,s.z),u=n.pointToLocalFrame(a),m=t.pointToLocalFrame(a),d=n.vectorToLocalFrame(r),p=t.vectorToLocalFrame(r),l=new c.HingeConstraint(n,t,{pivotA:u,pivotB:m,axisA:d,axisB:p,collideConnected:!1});return this.world.addConstraint(l),l}createPointConstraint(n,t,e){const o=e.getWorldPosition(new i.Vector3),s=n.pointToLocalFrame(new c.Vec3(o.x,o.y,o.z)),a=t.pointToLocalFrame(new c.Vec3(o.x,o.y,o.z)),r=new c.PointToPointConstraint(n,s,t,a);return this.world.addConstraint(r),r}createDistanceConstraint(n,t){const e=new c.DistanceConstraint(n,t);return this.world.addConstraint(e),e}createCollider(n,t){t.visible=!1;let e=t.userData.threejscannones_cgroup??1,o=t.userData.threejscannones_cwith??1;const s=new c.Body({shape:n,mass:t.userData.threejscannones_mass??0,collisionFilterMask:o,collisionFilterGroup:e}),a=t.getWorldPosition(new i.Vector3);s.position.set(a.x,a.y,a.z);const r=t.getWorldQuaternion(new i.Quaternion);return s.quaternion.set(r.x,r.y,r.z,r.w),this.world.addBody(s),this.obj2bod.set(t,s),s}update(n){for(let t=0;t<this.constraints.length;t++)this.constraints[t].update(n)}}class C{constructor(n,t){this.obj=n,this.cannonConstraint=t}enable(){this.cannonConstraint?.enable()}disable(){this.cannonConstraint?.disable()}update(n){}get name(){return this.obj.userData.name}removeFrom(n){this.cannonConstraint&&n.removeConstraint(this.cannonConstraint)}}class f extends C{constructor(n,t){super(n),this.body=t}offsetPos=new i.Vector3;offsetQuat=new i.Quaternion;hasInit=!1;initOffsets(){const n=new i.Vector3(this.body.position.x,this.body.position.y,this.body.position.z),t=new i.Quaternion(this.body.quaternion.x,this.body.quaternion.y,this.body.quaternion.z,this.body.quaternion.w),e=new i.Vector3,o=new i.Quaternion;this.obj.getWorldPosition(e),this.obj.getWorldQuaternion(o),this.offsetPos.copy(e).sub(n).applyQuaternion(t.clone().invert()),this.offsetQuat.copy(t.clone().invert().multiply(o)),this.hasInit=!0}update(){this.hasInit||this.initOffsets();const n=new i.Vector3(this.body.position.x,this.body.position.y,this.body.position.z),t=new i.Quaternion(this.body.quaternion.x,this.body.quaternion.y,this.body.quaternion.z,this.body.quaternion.w),e=t.clone().multiply(this.offsetQuat),o=this.offsetPos.clone().applyQuaternion(t).add(n);if(this.obj.parent){this.obj.parent.updateMatrixWorld(!0);const s=new i.Matrix4().compose(o,e,new i.Vector3(1,1,1)),a=new i.Matrix4().copy(this.obj.parent.matrixWorld).invert();s.premultiply(a),s.decompose(this.obj.position,this.obj.quaternion,new i.Vector3)}else this.obj.position.copy(o),this.obj.quaternion.copy(e)}}class g extends C{constructor(n,t,e,o,s){super(t),this.world=n,this.cable=e,o&&this.lockHeadTo(o),s&&this.lockTailTo(s)}lockToA;lockToB;lockXTo(n,t,e){let o;return n&&this.world.removeConstraint(n),e&&(o=new c.PointToPointConstraint(t,new c.Vec3,e,e.pointToLocalFrame(t.position)),o.collideConnected=!1,this.world.addConstraint(o)),o}lockHeadTo(n){this.lockToA=this.lockXTo(this.lockToA,this.cable.head,n)}lockTailTo(n){this.lockToB=this.lockXTo(this.lockToB,this.cable.tail,n)}enable(){this.lockToA?.enable(),this.lockToB?.enable(),this.cable.constraints.forEach(n=>n.enable())}disable(){this.lockToA?.disable(),this.lockToB?.disable(),this.cable.constraints.forEach(n=>n.disable())}update(){this.cable.syncRig()}removeFrom(n){this.lockToA&&(n.removeConstraint(this.lockToA),this.lockToA=void 0),this.lockToB&&(n.removeConstraint(this.lockToB),this.lockToA=void 0),this.cable.removeFromPhysicalWorld(n),super.removeFrom(n)}}exports.CableConstraint=g;exports.SyncConstraint=f;exports.ThreeJsCannonEsConstraint=C;exports.ThreeJsCannonEsSceneRigger=D;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const c=require("cannon-es"),i=require("three"),v=require("threejs-cannones-tube"),B={x:0,box:1,sphere:2,compound:3,lock:4,hinge:5,point:6,dist:7,sync:8,tube:9,custom:10};function b(h){return h.reduce((n,t,e)=>n|t<<e,0)}const w=new i.Vector3,y=new i.Vector3,Q=new i.Quaternion,D=new i.Quaternion;class P{constructor(n,t){this.world=n,t&&this.rigScene(t)}obj2bod=new Map;constraints=[];customId2ConstraintFactory=new Map;customConstraints=new Map;registerCustomConstraint(n,t){this.customId2ConstraintFactory.set(n,t)}getConstraintByName(n){return this.constraints.find(t=>t.name==n)}getCustomConstraint(n){return this.customConstraints.get(n)}getCableConstraint(n){return this.getConstraintByName(n)}getSyncConstraint(n){return this.getConstraintByName(n)}getLockConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getHingeConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getPointConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getDistanceConstraint(n){return this.getConstraintByName(n)?.cannonConstraint}getBodyByName(n){for(const[t,e]of this.obj2bod.entries())if(t.userData.name===n)return e}rigScene(n){n.traverse(t=>{let e;typeof t.userData.threejscannones_type=="string"&&(t.userData.threejscannones_type=B[t.userData.threejscannones_type]),t.userData.threejscannones_cgroup&&(t.userData.threejscannones_cgroup=b(t.userData.threejscannones_cgroup)),t.userData.threejscannones_cwith&&(t.userData.threejscannones_cwith=b(t.userData.threejscannones_cwith)),t.userData.threejscannones_type==1?e=this.createCollider(new c.Box(new c.Vec3(t.scale.x,t.scale.y,t.scale.z)),t):t.userData.threejscannones_type==2?e=this.createCollider(new c.Sphere(t.scale.x),t):t.userData.threejscannones_type==3&&(e=this.createCollider(void 0,t),this.addCompoundShapes(e,t))}),n.traverse(t=>{const e=this.getBodyByName(t.userData.threejscannones_A?.name),o=this.getBodyByName(t.userData.threejscannones_B?.name);let s;switch(t.userData.threejscannones_type){case 7:s=this.createDistanceConstraint(e,o);break;case 6:s=this.createPointConstraint(e,o,t);break;case 5:s=this.createHingeConstraint(e,o,t);break;case 4:s=this.createLockConstraint(e,o);break;case 8:const a=this.getBodyByName(t.userData.threejscannones_syncSource?.name);this.createSyncBetween(t,a);break;case 9:this.createCable(t,e,o);break;case 10:this.createCustomConstraint(t,e,o)}s&&this.constraints.push(new C(t,s))})}clear(){for(w.set(0,0,0),y.set(0,0,0),Q.set(0,0,0,0),D.set(0,0,0,0);this.constraints.length;)this.constraints.pop().removeFrom(this.world);for(const[n,t]of this.obj2bod.entries())this.world.removeBody(t);this.obj2bod.clear()}addCompoundShapes(n,t){const e=t.children;t.updateMatrixWorld();const o=t.getWorldPosition(new i.Vector3),s=t.getWorldQuaternion(new i.Quaternion),a=s.clone().invert();for(const r of e){r.updateMatrixWorld();const u=r.getWorldPosition(new i.Vector3),m=r.getWorldQuaternion(new i.Quaternion),d=r.getWorldScale(new i.Vector3),p=u.clone().sub(o).applyQuaternion(a),l=a.clone().multiply(m),T=new c.Vec3(p.x,p.y,p.z),k=new c.Quaternion(l.x,l.y,l.z,l.w),x=new c.Vec3(d.x,d.y,d.z),j=new c.Box(x);n.addShape(j,T,k)}return n.position.copy(new c.Vec3(o.x,o.y,o.z)),n.quaternion.copy(new c.Quaternion(s.x,s.y,s.z,s.w)),n}createCustomConstraint(n,t,e){let o=n.userData.threejscannones_cgroup??1,s=n.userData.threejscannones_cwith??1;const a=n.userData.threejscannones_customId;if(!a)throw new Error("A custom constraint MUST have an id...");const r=this.customId2ConstraintFactory.get(a);if(!r)throw new Error(`Custom constraint with id ${a} not found. Dis you forgot to call registerCustomConstraint?`);const u=r({obj:n,collisionGroup:o,collisionMask:s,A:t,B:e});this.customConstraints.set(n.userData.name,u)}createCable(n,t,e){let o=1,s=!1,a=new i.Vector3;n.children.length>1&&(n.children[0].getWorldPosition(w),n.children[1].localToWorld(y),o=w.distanceTo(y),s=!0,a.copy(y));const r=new v.CannonTubeRig(o,20,.1,8);r.material=n instanceof i.Mesh?n.material:new i.MeshNormalMaterial,n.parent?.add(r),s&&(r.position.copy(w),r.lookAt(y)),r.addToPhysicalWorld(this.world),r.syncRig(),this.constraints.push(new g(this.world,n,r,t,e))}createSyncBetween(n,t){if(!t){console.warn(`Object ${n.name} points to a non existent collider for it's sync constrain.`);return}const e=new f(n,t);this.constraints.push(e)}createLockConstraint(n,t){const e=new c.LockConstraint(n,t);return e.collideConnected=!1,this.world.addConstraint(e),e}createHingeConstraint(n,t,e){const o=e.getWorldPosition(new i.Vector3),s=new i.Vector3(0,1,0).applyQuaternion(e.getWorldQuaternion(new i.Quaternion)).normalize(),a=new c.Vec3(o.x,o.y,o.z),r=new c.Vec3(s.x,s.y,s.z),u=n.pointToLocalFrame(a),m=t.pointToLocalFrame(a),d=n.vectorToLocalFrame(r),p=t.vectorToLocalFrame(r),l=new c.HingeConstraint(n,t,{pivotA:u,pivotB:m,axisA:d,axisB:p,collideConnected:!1});return this.world.addConstraint(l),l}createPointConstraint(n,t,e){const o=e.getWorldPosition(new i.Vector3),s=n.pointToLocalFrame(new c.Vec3(o.x,o.y,o.z)),a=t.pointToLocalFrame(new c.Vec3(o.x,o.y,o.z)),r=new c.PointToPointConstraint(n,s,t,a);return this.world.addConstraint(r),r}createDistanceConstraint(n,t){const e=new c.DistanceConstraint(n,t);return this.world.addConstraint(e),e}createCollider(n,t){t.visible=!1;let e=t.userData.threejscannones_cgroup??1,o=t.userData.threejscannones_cwith??1;const s=new c.Body({shape:n,mass:t.userData.threejscannones_mass??0,collisionFilterMask:o,collisionFilterGroup:e}),a=t.getWorldPosition(new i.Vector3);s.position.set(a.x,a.y,a.z);const r=t.getWorldQuaternion(new i.Quaternion);return s.quaternion.set(r.x,r.y,r.z,r.w),this.world.addBody(s),this.obj2bod.set(t,s),s}update(n){for(let t=0;t<this.constraints.length;t++)this.constraints[t].update(n)}}class C{constructor(n,t){this.obj=n,this.cannonConstraint=t}enable(){this.cannonConstraint?.enable()}disable(){this.cannonConstraint?.disable()}update(n){}get name(){return this.obj.userData.name}removeFrom(n){this.cannonConstraint&&n.removeConstraint(this.cannonConstraint)}}class f extends C{constructor(n,t){super(n),this.body=t}offsetPos=new i.Vector3;offsetQuat=new i.Quaternion;hasInit=!1;initOffsets(){const n=new i.Vector3(this.body.position.x,this.body.position.y,this.body.position.z),t=new i.Quaternion(this.body.quaternion.x,this.body.quaternion.y,this.body.quaternion.z,this.body.quaternion.w),e=new i.Vector3,o=new i.Quaternion;this.obj.getWorldPosition(e),this.obj.getWorldQuaternion(o),this.offsetPos.copy(e).sub(n).applyQuaternion(t.clone().invert()),this.offsetQuat.copy(t.clone().invert().multiply(o)),this.hasInit=!0}update(){this.hasInit||this.initOffsets();const n=new i.Vector3(this.body.position.x,this.body.position.y,this.body.position.z),t=new i.Quaternion(this.body.quaternion.x,this.body.quaternion.y,this.body.quaternion.z,this.body.quaternion.w),e=t.clone().multiply(this.offsetQuat),o=this.offsetPos.clone().applyQuaternion(t).add(n);if(this.obj.parent){this.obj.parent.updateMatrixWorld(!0);const s=new i.Matrix4().compose(o,e,new i.Vector3(1,1,1)),a=new i.Matrix4().copy(this.obj.parent.matrixWorld).invert();s.premultiply(a),s.decompose(this.obj.position,this.obj.quaternion,new i.Vector3)}else this.obj.position.copy(o),this.obj.quaternion.copy(e)}}class g extends C{constructor(n,t,e,o,s){super(t),this.world=n,this.cable=e,o&&this.lockHeadTo(o),s&&this.lockTailTo(s)}lockToA;lockToB;lockXTo(n,t,e){let o;return n&&this.world.removeConstraint(n),e&&(o=new c.PointToPointConstraint(t,new c.Vec3,e,e.pointToLocalFrame(t.position)),o.collideConnected=!1,this.world.addConstraint(o)),o}lockHeadTo(n){this.lockToA=this.lockXTo(this.lockToA,this.cable.head,n)}lockTailTo(n){this.lockToB=this.lockXTo(this.lockToB,this.cable.tail,n)}enable(){this.lockToA?.enable(),this.lockToB?.enable(),this.cable.constraints.forEach(n=>n.enable())}disable(){this.lockToA?.disable(),this.lockToB?.disable(),this.cable.constraints.forEach(n=>n.disable())}update(){this.cable.syncRig()}removeFrom(n){this.lockToA&&(n.removeConstraint(this.lockToA),this.lockToA=void 0),this.lockToB&&(n.removeConstraint(this.lockToB),this.lockToA=void 0),this.cable.removeFromPhysicalWorld(n),super.removeFrom(n)}}exports.CableConstraint=g;exports.SyncConstraint=f;exports.ThreeJsCannonEsConstraint=C;exports.ThreeJsCannonEsSceneRigger=P;

package/dist/threejs-cannones-rigger.js

@@ -1,11 +1,26 @@
-import { Box as f, Vec3 as l, Sphere as W, Quaternion as g, LockConstraint as P, HingeConstraint as Q, PointToPointConstraint as v, DistanceConstraint as _, Body as A } from "cannon-es";
+import { Box as f, Vec3 as l, Sphere as W, Quaternion as g, LockConstraint as _, HingeConstraint as P, PointToPointConstraint as x, DistanceConstraint as Q, Body as A } from "cannon-es";
 import { Vector3 as r, Quaternion as c, MeshNormalMaterial as z, Mesh as F, Matrix4 as T } from "three";
 import { CannonTubeRig as S } from "threejs-cannones-tube";
+const M = {
+  // in blender 5+ enum properties are no longer exported as int
+  x: 0,
+  box: 1,
+  sphere: 2,
+  compound: 3,
+  lock: 4,
+  hinge: 5,
+  point: 6,
+  dist: 7,
+  sync: 8,
+  tube: 9,
+  custom: 10
+  /* Custom */
+};
 function k(d) {
   return d.reduce((n, t, e) => n | t << e, 0);
 }
-const m = new r(), y = new r(), M = new c(), q = new c();
-class O {
+const m = new r(), w = new r(), q = new c(), L = new c();
+class R {
   /**
    * Creates a new ThreeJsCannonEsSceneRigger.
    * @param world The Cannon-es physics world.
@@ -100,7 +115,7 @@ class O {
   rigScene(n) {
     n.traverse((t) => {
       let e;
-      t.userData.threejscannones_cgroup && (t.userData.threejscannones_cgroup = k(t.userData.threejscannones_cgroup)), t.userData.threejscannones_cwith && (t.userData.threejscannones_cwith = k(t.userData.threejscannones_cwith)), t.userData.threejscannones_type == 1 ? e = this.createCollider(new f(new l(t.scale.x, t.scale.y, t.scale.z)), t) : t.userData.threejscannones_type == 2 ? e = this.createCollider(new W(t.scale.x), t) : t.userData.threejscannones_type == 3 && (e = this.createCollider(void 0, t), this.addCompoundShapes(e, t));
+      typeof t.userData.threejscannones_type == "string" && (t.userData.threejscannones_type = M[t.userData.threejscannones_type]), t.userData.threejscannones_cgroup && (t.userData.threejscannones_cgroup = k(t.userData.threejscannones_cgroup)), t.userData.threejscannones_cwith && (t.userData.threejscannones_cwith = k(t.userData.threejscannones_cwith)), t.userData.threejscannones_type == 1 ? e = this.createCollider(new f(new l(t.scale.x, t.scale.y, t.scale.z)), t) : t.userData.threejscannones_type == 2 ? e = this.createCollider(new W(t.scale.x), t) : t.userData.threejscannones_type == 3 && (e = this.createCollider(void 0, t), this.addCompoundShapes(e, t));
     }), n.traverse((t) => {
       const e = this.getBodyByName(t.userData.threejscannones_A?.name), o = this.getBodyByName(t.userData.threejscannones_B?.name);
       let s;
@@ -134,7 +149,7 @@ class O {
    * Removes all (known) created bodies and constraints from the world and clears internal state.
    */
   clear() {
-    for (m.set(0, 0, 0), y.set(0, 0, 0), M.set(0, 0, 0, 0), q.set(0, 0, 0, 0); this.constraints.length; )
+    for (m.set(0, 0, 0), w.set(0, 0, 0), q.set(0, 0, 0, 0), L.set(0, 0, 0, 0); this.constraints.length; )
       this.constraints.pop().removeFrom(this.world);
     for (const [n, t] of this.obj2bod.entries())
       this.world.removeBody(t);
@@ -146,8 +161,8 @@ class O {
     const o = t.getWorldPosition(new r()), s = t.getWorldQuaternion(new c()), a = s.clone().invert();
     for (const i of e) {
       i.updateMatrixWorld();
-      const u = i.getWorldPosition(new r()), C = i.getWorldQuaternion(new c()), p = i.getWorldScale(new r()), w = u.clone().sub(o).applyQuaternion(a), h = a.clone().multiply(C), x = new l(w.x, w.y, w.z), B = new g(h.x, h.y, h.z, h.w), j = new l(p.x, p.y, p.z), D = new f(j);
-      n.addShape(D, x, B);
+      const u = i.getWorldPosition(new r()), C = i.getWorldQuaternion(new c()), p = i.getWorldScale(new r()), y = u.clone().sub(o).applyQuaternion(a), h = a.clone().multiply(C), v = new l(y.x, y.y, y.z), B = new g(h.x, h.y, h.z, h.w), j = new l(p.x, p.y, p.z), D = new f(j);
+      n.addShape(D, v, B);
     }
     return n.position.copy(new l(o.x, o.y, o.z)), n.quaternion.copy(new g(s.x, s.y, s.z, s.w)), n;
   }
@@ -176,7 +191,7 @@ class O {
    */
   createCable(n, t, e) {
     let o = 1, s = !1, a = new r();
-    n.children.length > 1 && (n.children[0].getWorldPosition(m), n.children[1].localToWorld(y), o = m.distanceTo(y), s = !0, a.copy(y));
+    n.children.length > 1 && (n.children[0].getWorldPosition(m), n.children[1].localToWorld(w), o = m.distanceTo(w), s = !0, a.copy(w));
     const i = new S(
       o,
       // length in world units 
@@ -187,7 +202,7 @@ class O {
       8
       // resolution along the radius
     );
-    i.material = n instanceof F ? n.material : new z(), n.parent?.add(i), s && (i.position.copy(m), i.lookAt(y)), i.addToPhysicalWorld(this.world), i.syncRig(), this.constraints.push(new N(this.world, n, i, t, e));
+    i.material = n instanceof F ? n.material : new z(), n.parent?.add(i), s && (i.position.copy(m), i.lookAt(w)), i.addToPhysicalWorld(this.world), i.syncRig(), this.constraints.push(new I(this.world, n, i, t, e));
   }
   /**
    * Synchronizes a Three.js object with a Cannon body.
@@ -199,7 +214,7 @@ class O {
       console.warn(`Object ${n.name} points to a non existent collider for it's sync constrain.`);
       return;
     }
-    const e = new L(n, t);
+    const e = new N(n, t);
     this.constraints.push(e);
   }
   /**
@@ -209,7 +224,7 @@ class O {
    * @returns The created LockConstraint.
    */
   createLockConstraint(n, t) {
-    const e = new P(n, t);
+    const e = new _(n, t);
     return e.collideConnected = !1, this.world.addConstraint(e), e;
   }
   /**
@@ -220,11 +235,11 @@ class O {
    * @returns The created HingeConstraint.
    */
   createHingeConstraint(n, t, e) {
-    const o = e.getWorldPosition(new r()), s = new r(0, 1, 0).applyQuaternion(e.getWorldQuaternion(new c())).normalize(), a = new l(o.x, o.y, o.z), i = new l(s.x, s.y, s.z), u = n.pointToLocalFrame(a), C = t.pointToLocalFrame(a), p = n.vectorToLocalFrame(i), w = t.vectorToLocalFrame(i), h = new Q(n, t, {
+    const o = e.getWorldPosition(new r()), s = new r(0, 1, 0).applyQuaternion(e.getWorldQuaternion(new c())).normalize(), a = new l(o.x, o.y, o.z), i = new l(s.x, s.y, s.z), u = n.pointToLocalFrame(a), C = t.pointToLocalFrame(a), p = n.vectorToLocalFrame(i), y = t.vectorToLocalFrame(i), h = new P(n, t, {
       pivotA: u,
       pivotB: C,
       axisA: p,
-      axisB: w,
+      axisB: y,
       collideConnected: !1
       //maxForce: 1e9,
     });
@@ -238,7 +253,7 @@ class O {
    * @returns The created PointToPointConstraint.
    */
   createPointConstraint(n, t, e) {
-    const o = e.getWorldPosition(new r()), s = n.pointToLocalFrame(new l(o.x, o.y, o.z)), a = t.pointToLocalFrame(new l(o.x, o.y, o.z)), i = new v(n, s, t, a);
+    const o = e.getWorldPosition(new r()), s = n.pointToLocalFrame(new l(o.x, o.y, o.z)), a = t.pointToLocalFrame(new l(o.x, o.y, o.z)), i = new x(n, s, t, a);
     return this.world.addConstraint(i), i;
   }
   /**
@@ -248,7 +263,7 @@ class O {
    * @returns The created DistanceConstraint.
    */
   createDistanceConstraint(n, t) {
-    const e = new _(n, t);
+    const e = new Q(n, t);
     return this.world.addConstraint(e), e;
   }
   /**
@@ -298,7 +313,7 @@ class b {
     this.cannonConstraint && n.removeConstraint(this.cannonConstraint);
   }
 }
-class L extends b {
+class N extends b {
   constructor(n, t) {
     super(n), this.body = t;
   }
@@ -320,7 +335,7 @@ class L extends b {
       this.obj.position.copy(o), this.obj.quaternion.copy(e);
   }
 }
-class N extends b {
+class I extends b {
   constructor(n, t, e, o, s) {
     super(t), this.world = n, this.cable = e, o && this.lockHeadTo(o), s && this.lockTailTo(s);
   }
@@ -328,7 +343,7 @@ class N extends b {
   lockToB;
   lockXTo(n, t, e) {
     let o;
-    return n && this.world.removeConstraint(n), e && (o = new v(t, new l(), e, e.pointToLocalFrame(t.position)), o.collideConnected = !1, this.world.addConstraint(o)), o;
+    return n && this.world.removeConstraint(n), e && (o = new x(t, new l(), e, e.pointToLocalFrame(t.position)), o.collideConnected = !1, this.world.addConstraint(o)), o;
   }
   /**
    * Locks or Releases the head to or from a body. `PointToPointConstraint` will be used to lock.
@@ -358,8 +373,8 @@ class N extends b {
   }
 }
 export {
-  N as CableConstraint,
-  L as SyncConstraint,
+  I as CableConstraint,
+  N as SyncConstraint,
   b as ThreeJsCannonEsConstraint,
-  O as ThreeJsCannonEsSceneRigger
+  R as ThreeJsCannonEsSceneRigger
 };

package/package.json

@@ -5,7 +5,7 @@
         "url": "https://github.com/bandinopla"
     },
     "description": "Create and position physics colliders in Blender then export them as GLB and load them automatically in ThreeJs with Cannon-es.",
-    "version": "1.0.1",
+    "version": "1.0.4",
     "type": "module",
     "packageManager": "pnpm@8.15.4",
     "files": [

package/readme.md

@@ -5,12 +5,27 @@
 
 ![cover](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/cover.png) 
 
+
+## Table of Contents
+- [Who is this for?](#who-is-this-for)
+- [Features](#features)
+- [Test your rig](#test-your-rig)
+- [Usage](#usage)
+- [API](#api)
+- [Colliders / Bodies](#colliders--bodies)
+- [Constraints](#constraints)
+- [Relationship Lines](#relationship-lines)
+- [Collision groups and masks](#collision-groups-and-masks)
+- [Custom constaint](#sparkles-custom-constaint)
+- [License](#license)
+
 # ThreeJs / Cannon-es Scene Rigger
 ### Design in Blender, simulate in Three!
  
 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).
 
-Watch a use case: [Video Tutorial (Rigging a mechanical claw)](https://youtu.be/RtO2KUH9Vig)
+Watch [Video Tutorial (Rigging a mechanical claw)](https://youtu.be/RtO2KUH9Vig)
+Demo showcase app that inspired this addon: [Mechanical Claw Machine](https://threejs-claw-machine.vercel.app/)
 
 This solution includes two tools:
 
@@ -18,6 +33,9 @@ This solution includes two tools:
 2) An NPM package to rig the physics in Three.js using cannon-es
  
 
+## Who is this for?
+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. 
+
 ## Features
 
 - Automatically creates Cannon bodies for Three.js objects defined inside of Blender ( _using the addon_ ).
@@ -39,8 +57,11 @@ Just make sure your glb has a camera and it is in the right angle where you want
 ## Usage
 
 ### 1) Install the blender addon
-Blender → Preferences → Add-ons → Install → select `threejs-cannones-addon.py`
-> Blender addon : [threejs-cannones-addon.py](https://github.com/bandinopla/threejs-cannones-rigger/raw/refs/heads/main/threejs-cannones-addon.py) 
+Install from disk → [threejs-cannones-addon.py](https://github.com/bandinopla/threejs-cannones-rigger/raw/refs/heads/main/threejs-cannones-addon.py) 
+
+| Blender → Preferences | Add-ons → Install (.py) | New Object Panel |
+|---------|---------|---------|
+| ![Step 1](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/install-1.jpg) | ![Step 2](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/install-2.jpg) | ![Step 3](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/install-3.jpg) | 
 
 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.
 
@@ -102,8 +123,8 @@ constructor(world: World, scene?: Object3D)
 - `getBodyByName(name: string)`: Returns a Cannon body by the name (the name in `userData.name` )  
 
 ---
-# Constraints
-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.
+# Colliders / Bodies
+![Colliders](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/colliders.jpg)
 
 #### Box / Sphere Collider
 > Use a default Cube or UV Sphere. Scale and rotate as needed. Only spheres must be scaled uniformly; boxes can be stretched freely.
@@ -112,7 +133,22 @@ rigger.getBodyByName(name)  //-> CANNON.Body
 ```
 
 #### Compound Collider
-> Assign this to an empty. All children will be glued into one collider/Body.  
+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. 
+
+#### Tube / Cable
+>Creates a flexible cable using [threejs-cannones-tube](https://www.npmjs.com/package/threejs-cannones-tube).
+Add two child empties to the constraint object — one for the head, one for the tail. A and B can optionally anchor the ends. 
+
+**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.
+```js
+rigger.getCableConstraint(name)  //-> CableConstraint
+rigger.getCableConstraint(name).cable //-> CannonTubeRig
+```
+
+# Constraints
+![Constraints](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/constraints.jpg)
+
+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.
 
 #### Glue/Lock Colliders
 > Connect two colliders (A & B) so they behave as a single rigid body. Creates a LockConstraint...
@@ -142,17 +178,27 @@ rigger.getDistanceConstraint(name)  //-> CANNON.DistanceConstraint
 > Use this on a visible object (e.g. mesh) to match the position & rotation of a physics collider.
 ```js
 rigger.getSyncConstraint(name)  //-> SyncConstraint
-```
+``` 
 
-#### Tube / Cable
->Creates a flexible cable using [threejs-cannones-tube](https://www.npmjs.com/package/threejs-cannones-tube).
-Add two child empties to the constraint object — one for the head, one for the tail. A and B can optionally anchor the ends. 
+# Relationship Lines
+![Colliders](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/lines.jpg)
+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.
 
-**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.
-```js
-rigger.getCableConstraint(name)  //-> CableConstraint
-rigger.getCableConstraint(name).cable //-> CannonTubeRig
-```
+# Collision groups and masks
+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)
+> 
+
+![Bitmasks](https://raw.githubusercontent.com/bandinopla/threejs-cannones-rigger/refs/heads/main/imgs/bitmask.jpg)
+
+- **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.
+- **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.
+
+### Understanding Collision Group and Mask
+- **Collision Group**: Sets which group your object belongs to (0–31). Think of it as the object’s "team" in the physics simulation.
+- **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.
+
+> #### When Collisions Don’t Happen
+> 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.
 
 # :sparkles: Custom constaint 
 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: