threejs-cannones-rigger 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pablo Bandinopla (https://x.com/bandinopla) 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/threejs-cannones-rigger.cjs

@@ -0,0 +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;

package/dist/threejs-cannones-rigger.d.ts

@@ -0,0 +1,212 @@
+import { Body, Constraint, DistanceConstraint, HingeConstraint, LockConstraint, PointToPointConstraint, World } from 'cannon-es';
+import { Object3D } from 'three';
+import { CannonTubeRig } from 'threejs-cannones-tube';
+export type CustomContraintConfig = {
+    /**
+     * The object that defined this custom constraint
+     */
+    obj: Object3D;
+    /**
+     * If set or useful, this is the group mask assosiated with this obj...
+     */
+    collisionGroup?: number;
+    /**
+     * If set or useful, this is the collision mask assosiated with this obj...
+     */
+    collisionMask?: number;
+    /**
+     * If set or useful, this is referencing a Body
+     */
+    A?: Body;
+    /**
+     * If set or useful, this is referencing a Body
+     */
+    B?: Body;
+};
+export type ConstraintFactory = (config: CustomContraintConfig) => IConstraint;
+export declare class ThreeJsCannonEsSceneRigger {
+    readonly world: World;
+    /**
+     * Keeps a relation between the object3D that defined the collider and the collider itself.
+     */
+    private obj2bod;
+    private constraints;
+    private customId2ConstraintFactory;
+    private customConstraints;
+    /**
+     * Creates a new ThreeJsCannonEsSceneRigger.
+     * @param world The Cannon-es physics world.
+     * @param scene (Optional) The Three.js scene or root object to rig immediately.
+     */
+    constructor(world: World, scene?: Object3D);
+    /**
+     * You can create a custom constrain using this method. So when you select "Custom Constrain" in blender, this function
+     * will be called when parsing that constraint allowing you to extend the functionality to suit your needs.
+     *
+     * @param id what you type in "custom ID" on blender side...
+     * @param creator the function that creates your custom constraint
+     */
+    registerCustomConstraint(id: string, creator: ConstraintFactory): void;
+    /**
+     * Returns a constraint by its name.
+     * @param name The name of the constraint.
+     * @returns The constraint instance, or undefined if not found.
+     */
+    private getConstraintByName;
+    getCustomConstraint(name: string): IConstraint | undefined;
+    /**
+     * Returns a CableConstraint by name.
+     * @param name The name of the constraint.
+     */
+    getCableConstraint(name: string): CableConstraint | undefined;
+    /**
+     * Returns a SyncConstraint by name.
+     * @param name The name of the constraint.
+     */
+    getSyncConstraint(name: string): SyncConstraint | undefined;
+    /**
+     * Returns a LockConstraint (Cannon-es) by name.
+     * @param name The name of the constraint.
+     */
+    getLockConstraint(name: string): LockConstraint | undefined;
+    /**
+     * Returns a HingeConstraint (Cannon-es) by name.
+     * @param name The name of the constraint.
+     */
+    getHingeConstraint(name: string): HingeConstraint | undefined;
+    /**
+     * Returns a PointToPointConstraint (Cannon-es) by name.
+     * @param name The name of the constraint.
+     */
+    getPointConstraint(name: string): PointToPointConstraint | undefined;
+    /**
+     * Returns a DistanceConstraint (Cannon-es) by name.
+     * @param name The name of the constraint.
+     */
+    getDistanceConstraint(name: string): DistanceConstraint | undefined;
+    /**
+     * Returns a Cannon body by the name of its associated Three.js object.
+     * @param name The name to search for (from userData.name).
+     * @returns The Cannon body, or undefined if not found.
+     */
+    getBodyByName(name: string): Body | undefined;
+    /**
+     * Scans the scene and creates physics bodies and constraints based on object userData.
+     * @param scene The Three.js scene or root object to rig.
+     */
+    rigScene(scene: Object3D): void;
+    /**
+     * Removes all (known) created bodies and constraints from the world and clears internal state.
+     */
+    clear(): void;
+    private addCompoundShapes;
+    private createCustomConstraint;
+    /**
+     * Creates a cable constraint between objects.
+     * @param obj The Three.js object representing the cable.
+     * @param stickToA (Optional) The body to attach the cable head to.
+     * @param stickToB (Optional) The body to attach the cable tail to.
+     */
+    private createCable;
+    /**
+     * Synchronizes a Three.js object with a Cannon body.
+     * @param obj The Three.js object to sync.
+     * @param body The Cannon body to sync with.
+     */
+    private createSyncBetween;
+    /**
+     * Creates a lock constraint between two bodies.
+     * @param a The first body.
+     * @param b The second body.
+     * @returns The created LockConstraint.
+     */
+    private createLockConstraint;
+    /**
+     * Creates a hinge constraint between two bodies.
+     * @param a The first body.
+     * @param b The second body.
+     * @param o The Three.js object representing the hinge.
+     * @returns The created HingeConstraint.
+     */
+    private createHingeConstraint;
+    /**
+     * Creates a point-to-point constraint between two bodies.
+     * @param a The first body.
+     * @param b The second body.
+     * @param o The Three.js object representing the constraint.
+     * @returns The created PointToPointConstraint.
+     */
+    private createPointConstraint;
+    /**
+     * Creates a distance constraint between two bodies.
+     * @param a The first body.
+     * @param b The second body.
+     * @returns The created DistanceConstraint.
+     */
+    private createDistanceConstraint;
+    /**
+     * Creates a Cannon body for a given Three.js object and shape.
+     * @param shape The Cannon-es shape.
+     * @param o The Three.js object.
+     * @returns The created Cannon body.
+     */
+    private createCollider;
+    /**
+     * Updates all constraints. Should be called every frame.
+     * @param delta The time step.
+     */
+    update(delta: number): void;
+}
+export interface IConstraint {
+    enable: VoidFunction;
+    disable: VoidFunction;
+    update: (delta: number) => void;
+    removeFrom: (world: World) => void;
+}
+/**
+ * Base class for all ThreeJsCannonEs constraints.
+ */
+export declare class ThreeJsCannonEsConstraint implements IConstraint {
+    readonly obj: Object3D;
+    readonly cannonConstraint?: Constraint | undefined;
+    enable(): void;
+    disable(): void;
+    update(_delta: number): void;
+    constructor(obj: Object3D, cannonConstraint?: Constraint | undefined);
+    get name(): string;
+    removeFrom(world: World): void;
+}
+export declare class SyncConstraint extends ThreeJsCannonEsConstraint {
+    readonly body: Body;
+    private offsetPos;
+    private offsetQuat;
+    private hasInit;
+    constructor(obj: Object3D, body: Body);
+    private initOffsets;
+    update(): void;
+}
+/**
+ * Creates a cable ( a skinned mesh with a chain on bones that copies a chain of connected cannon-es bodies connected via point to point contraint )
+ */
+export declare class CableConstraint extends ThreeJsCannonEsConstraint {
+    readonly world: World;
+    readonly cable: CannonTubeRig;
+    private lockToA;
+    private lockToB;
+    constructor(world: World, obj: Object3D, cable: CannonTubeRig, stickToA?: Body, stickToB?: Body);
+    private lockXTo;
+    /**
+     * Locks or Releases the head to or from a body. `PointToPointConstraint` will be used to lock.
+     * @param body
+     */
+    lockHeadTo(body: Body | undefined): void;
+    /**
+     * Locks or Releases the tail to or from a body. `PointToPointConstraint` will be used to lock.
+     * @param body
+     */
+    lockTailTo(body: Body | undefined): void;
+    enable(): void;
+    disable(): void;
+    update(): void;
+    removeFrom(world: World): void;
+}

package/dist/threejs-cannones-rigger.js

@@ -0,0 +1,365 @@
+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 { 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";
+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 {
+  /**
+   * Creates a new ThreeJsCannonEsSceneRigger.
+   * @param world The Cannon-es physics world.
+   * @param scene (Optional) The Three.js scene or root object to rig immediately.
+   */
+  constructor(n, t) {
+    this.world = n, t && this.rigScene(t);
+  }
+  /**
+   * Keeps a relation between the object3D that defined the collider and the collider itself.
+   */
+  obj2bod = /* @__PURE__ */ new Map();
+  constraints = [];
+  customId2ConstraintFactory = /* @__PURE__ */ new Map();
+  customConstraints = /* @__PURE__ */ new Map();
+  /** 
+   * You can create a custom constrain using this method. So when you select "Custom Constrain" in blender, this function
+   * will be called when parsing that constraint allowing you to extend the functionality to suit your needs.
+   * 
+   * @param id what you type in "custom ID" on blender side...
+   * @param creator the function that creates your custom constraint
+   */
+  registerCustomConstraint(n, t) {
+    this.customId2ConstraintFactory.set(n, t);
+  }
+  /**
+   * Returns a constraint by its name.
+   * @param name The name of the constraint.
+   * @returns The constraint instance, or undefined if not found.
+   */
+  getConstraintByName(n) {
+    return this.constraints.find((t) => t.name == n);
+  }
+  getCustomConstraint(n) {
+    return this.customConstraints.get(n);
+  }
+  /**
+   * Returns a CableConstraint by name.
+   * @param name The name of the constraint.
+   */
+  getCableConstraint(n) {
+    return this.getConstraintByName(n);
+  }
+  /**
+   * Returns a SyncConstraint by name.
+   * @param name The name of the constraint.
+   */
+  getSyncConstraint(n) {
+    return this.getConstraintByName(n);
+  }
+  /**
+   * Returns a LockConstraint (Cannon-es) by name.
+   * @param name The name of the constraint.
+   */
+  getLockConstraint(n) {
+    return this.getConstraintByName(n)?.cannonConstraint;
+  }
+  /**
+   * Returns a HingeConstraint (Cannon-es) by name.
+   * @param name The name of the constraint.
+   */
+  getHingeConstraint(n) {
+    return this.getConstraintByName(n)?.cannonConstraint;
+  }
+  /**
+   * Returns a PointToPointConstraint (Cannon-es) by name.
+   * @param name The name of the constraint.
+   */
+  getPointConstraint(n) {
+    return this.getConstraintByName(n)?.cannonConstraint;
+  }
+  /**
+   * Returns a DistanceConstraint (Cannon-es) by name.
+   * @param name The name of the constraint.
+   */
+  getDistanceConstraint(n) {
+    return this.getConstraintByName(n)?.cannonConstraint;
+  }
+  /**
+   * Returns a Cannon body by the name of its associated Three.js object.
+   * @param name The name to search for (from userData.name).
+   * @returns The Cannon body, or undefined if not found.
+   */
+  getBodyByName(n) {
+    for (const [t, e] of this.obj2bod.entries())
+      if (t.userData.name === n) return e;
+  }
+  /**
+   * Scans the scene and creates physics bodies and constraints based on object userData.
+   * @param scene The Three.js scene or root object to rig.
+   */
+  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));
+    }), 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 b(t, s));
+    });
+  }
+  /**
+   * 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; )
+      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 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);
+    }
+    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;
+  }
+  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 i = this.customId2ConstraintFactory.get(a);
+    if (!i)
+      throw new Error(`Custom constraint with id ${a} not found. Dis you forgot to call registerCustomConstraint?`);
+    const u = i({
+      obj: n,
+      collisionGroup: o,
+      collisionMask: s,
+      A: t,
+      B: e
+    });
+    this.customConstraints.set(n.userData.name, u);
+  }
+  /**
+   * Creates a cable constraint between objects.
+   * @param obj The Three.js object representing the cable.
+   * @param stickToA (Optional) The body to attach the cable head to.
+   * @param stickToB (Optional) The body to attach the cable tail to.
+   */
+  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));
+    const i = new S(
+      o,
+      // length in world units 
+      20,
+      // resolution along the segment's length
+      0.1,
+      // radius of the tube
+      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));
+  }
+  /**
+   * Synchronizes a Three.js object with a Cannon body.
+   * @param obj The Three.js object to sync.
+   * @param body The Cannon body to sync with.
+   */
+  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 L(n, t);
+    this.constraints.push(e);
+  }
+  /**
+   * Creates a lock constraint between two bodies.
+   * @param a The first body.
+   * @param b The second body.
+   * @returns The created LockConstraint.
+   */
+  createLockConstraint(n, t) {
+    const e = new P(n, t);
+    return e.collideConnected = !1, this.world.addConstraint(e), e;
+  }
+  /**
+   * Creates a hinge constraint between two bodies.
+   * @param a The first body.
+   * @param b The second body.
+   * @param o The Three.js object representing the hinge.
+   * @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, {
+      pivotA: u,
+      pivotB: C,
+      axisA: p,
+      axisB: w,
+      collideConnected: !1
+      //maxForce: 1e9,
+    });
+    return this.world.addConstraint(h), h;
+  }
+  /**
+   * Creates a point-to-point constraint between two bodies.
+   * @param a The first body.
+   * @param b The second body.
+   * @param o The Three.js object representing the constraint.
+   * @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);
+    return this.world.addConstraint(i), i;
+  }
+  /**
+   * Creates a distance constraint between two bodies.
+   * @param a The first body.
+   * @param b The second body.
+   * @returns The created DistanceConstraint.
+   */
+  createDistanceConstraint(n, t) {
+    const e = new _(n, t);
+    return this.world.addConstraint(e), e;
+  }
+  /**
+   * Creates a Cannon body for a given Three.js object and shape.
+   * @param shape The Cannon-es shape.
+   * @param o The Three.js object.
+   * @returns The created Cannon body.
+   */
+  createCollider(n, t) {
+    t.visible = !1;
+    let e = t.userData.threejscannones_cgroup ?? 1, o = t.userData.threejscannones_cwith ?? 1;
+    const s = new A({
+      shape: n,
+      mass: t.userData.threejscannones_mass ?? 0,
+      collisionFilterMask: o,
+      collisionFilterGroup: e
+    }), a = t.getWorldPosition(new r());
+    s.position.set(a.x, a.y, a.z);
+    const i = t.getWorldQuaternion(new c());
+    return s.quaternion.set(i.x, i.y, i.z, i.w), this.world.addBody(s), this.obj2bod.set(t, s), s;
+  }
+  /**
+   * Updates all constraints. Should be called every frame.
+   * @param delta The time step.
+   */
+  update(n) {
+    for (let t = 0; t < this.constraints.length; t++)
+      this.constraints[t].update(n);
+  }
+}
+class b {
+  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 L extends b {
+  constructor(n, t) {
+    super(n), this.body = t;
+  }
+  offsetPos = new r();
+  offsetQuat = new c();
+  hasInit = !1;
+  initOffsets() {
+    const n = new r(this.body.position.x, this.body.position.y, this.body.position.z), t = new c(this.body.quaternion.x, this.body.quaternion.y, this.body.quaternion.z, this.body.quaternion.w), e = new r(), o = new c();
+    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 r(this.body.position.x, this.body.position.y, this.body.position.z), t = new c(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 T().compose(o, e, new r(1, 1, 1)), a = new T().copy(this.obj.parent.matrixWorld).invert();
+      s.premultiply(a), s.decompose(this.obj.position, this.obj.quaternion, new r());
+    } else
+      this.obj.position.copy(o), this.obj.quaternion.copy(e);
+  }
+}
+class N extends b {
+  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 v(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.
+   * @param body 
+   */
+  lockHeadTo(n) {
+    this.lockToA = this.lockXTo(this.lockToA, this.cable.head, n);
+  }
+  /**
+   * Locks or Releases the tail to or from a body. `PointToPointConstraint` will be used to lock.
+   * @param body 
+   */
+  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);
+  }
+}
+export {
+  N as CableConstraint,
+  L as SyncConstraint,
+  b as ThreeJsCannonEsConstraint,
+  O as ThreeJsCannonEsSceneRigger
+};

package/package.json

@@ -0,0 +1,44 @@
+{
+    "name": "threejs-cannones-rigger",
+    "author": {
+        "name": "pablo bandinopla",
+        "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.0",
+    "type": "module",
+    "packageManager": "pnpm@8.15.4",
+    "files": [
+        "dist"
+    ],
+    "main": "./dist/threejs-cannones-rigger.cjs",
+    "module": "./dist/threejs-cannones-rigger.js",
+    "types": "./dist/threejs-cannones-rigger.d.ts",
+    "exports": {
+        ".": {
+            "import": "./dist/threejs-cannones-rigger.js",
+            "require": "./dist/threejs-cannones-rigger.cjs"
+        }
+    },
+    "scripts": {
+        "dev": "vite --config vite.config.site.js",
+        "build": "tsc && vite build",
+        "build-test-app": "vite build --config vite.config.site.js",
+        "preview": "vite preview --config vite.config.site.js"
+    },
+    "devDependencies": {
+        "@types/three": "^0.178.1",
+        "cannon-es": "^0.20.0",
+        "cannon-es-debugger": "^1.0.0",
+        "three": "^0.179.0",
+        "threejs-cannones-tube": "^0.0.9",
+        "typescript": "~5.8.3",
+        "vite": "^7.0.4",
+        "vite-plugin-dts": "^4.5.4"
+    },
+    "peerDependencies": {
+        "cannon-es": ">=0.20.0 <1.0.0",
+        "three": ">=0.178.0 <1.0.0",
+        "threejs-cannones-tube": ">=0.0.7 <1.0.0"
+    }
+}

package/readme.md

@@ -0,0 +1,186 @@
+![cover](https://github.com/bandinopla/threejs-cannones-rigger/raw/main/cover.png) 
+
+# 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).
+
+This solution includes two tools:
+
+1) A Blender addon for creating colliders in Blender 
+2) An NPM package to rig the physics in Three.js using cannon-es
+ 
+
+## Features
+
+- Automatically creates Cannon bodies for Three.js objects defined inside of Blender ( _using the addon_ ).
+- Supports:
+    - box and sphere colliders
+    - hinge
+    - point
+    - distance
+    - lock
+    - glue childrens
+    - [cable](https://www.npmjs.com/package/threejs-cannones-tube) 
+    - synchronization (copy location & rotation) 
+    - :sparkles: your own custom constraint :sparkles:
+
+## Test your rig
+You can quicly test your rig here: https://threejs-cannones-rigger.vercel.app
+Just make sure your glb has a camera and it is in the right angle where you want to focus on (it will use the camera in the file... so if you don't see anything maybe you forgot to export the cameras too)
+
+## 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) 
+
+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.
+
+### 2) Scene Rigging
+
+To create the colliders you work with Empty objects. Their scale is used to define the size of the collider. Sphere colliders can only have uniform scale. Typically you will/should use a Cube or Sphere empty for colliders, and any shape you want for the constraints (since their transform won't be used anyways just their data)
+
+In Blender, when you select an object you will see on the right a panel titled **"ThreeJs / Cannon-es (Physics)"**  From there, create empty objects or boxes or spheres and assign the corresponding options.
+
+### 3) Export `.glb`
+when you export as GLB make sure you tick the option **"include custom properties"**
+
+
+### 4) Load in ThreeJs
+```
+npm install threejs-cannones-rigger
+```
+#### The load the GLB exported from blender like this...
+> See `src/main.ts` for a usage example.
+```typescript
+import { World } from 'cannon-es';
+import { ThreeJsCannonEsSceneRigger } from 'threejs-cannones-rigger';
+
+// Assume you have a Cannon world and a loaded Three.js scene
+const world = new World({ gravity: new Vec3(0, -10, 0) });
+const scene = new THREE.Scene();
+
+// Create the rigger and rig the scene
+const rigger = new ThreeJsCannonEsSceneRigger(world, scene);
+
+new GLTFLoader().load(url, file => {
+    scene.add(file.scene)
+    rigger.rigScene(file.scene); // *** this is where the magic happens ***
+});
+
+// To update physics and sync with Three.js in your animation loop:
+function yourRenderLoop() {
+    // ... update world, render scene, etc.
+    rigger.update(deltaTime);
+    //...
+}
+``` 
+---
+
+# API 
+
+### `ThreeJsCannonEsSceneRigger`
+
+```typescript
+constructor(world: World, scene?: Object3D)
+```
+- `world`: The Cannon-es physics world.
+- `scene` (optional): The Three.js scene or root object to rig immediately.
+
+### Methods
+
+- `rigScene(scene: Object3D)`: Scans the scene and creates physics bodies and constraints based on object `userData`.
+- `clear()`: Removes all created bodies and constraints from the world and clears internal state. 
+- `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.
+
+#### 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.
+```js
+rigger.getBodyByName(name)  //-> CANNON.Body
+```
+
+#### Compound Collider
+> Assign this to an empty. All children will be glued into one collider/Body.  
+
+#### Glue/Lock Colliders
+> Connect two colliders (A & B) so they behave as a single rigid body. Creates a LockConstraint...
+```js
+rigger.getLockConstraint(name)  //-> CANNON.LockConstraint
+```
+
+#### Hinge Constraint
+> Assign to an empty. Local Z axis defines the hinge (like a door axis).
+```js
+rigger.getHingeConstraint(name)  //-> CANNON.HingeConstraint
+```
+
+#### Point Constraint
+> Links A and B via a shared point. Each keeps its relative position to it.
+```js
+rigger.getPointConstraint(name)  //-> CANNON.PointToPointConstraint
+```
+
+#### Keep This Distance
+>Maintains the initial distance between A and B, allowing movement but preserving separation.
+```js
+rigger.getDistanceConstraint(name)  //-> CANNON.DistanceConstraint
+```
+
+#### Sync Constraint
+> 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. 
+
+**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
+```
+
+# :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:
+
+```js
+rigger.registerCustomConstraint("myCustomID", config => {
+    // this function will be called when parsing the scene and your custom id is detected...
+    return yourConstraintInstance;
+});
+
+rigger.getCustomConstraint(name) //=>yourConstraintInstance
+```
+
+Your constraint should implement `IConstraint`. 
+
+The `config` you get has this shape: 
+| Property   | Description |
+|------------|-------------|
+| `obj`   | The Three.js object that defines the constraint in the scene. |
+| `collisionGroup`    | (Optional) Bitmask, If you define it in blender side... |
+| `collisionMask`    | (Optional) Bitmask, If you define it in blender side... |
+| `A`        | (Optional) The Cannon body referenced as A (if set in Blender). |
+| `B`        | (Optional) The Cannon body referenced as B (if set in Blender). | 
+
+To get a reference to your constrain after creation call:
+
+```typescript
+rigger.getCustomConstraint("objectName") as MySuperCoolCustomConstraint
+```
+
+
+
+
+
+
+## License
+
+MIT