@needle-tools/engine 4.3.2-beta.1 → 4.3.2-beta.2

package/CHANGELOG.md

@@ -4,6 +4,9 @@ All notable changes to this package will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## [4.3.2-beta.2] - 2025-03-18
+- Add: Documentation for `Gizmos` API
+
 ## [4.3.2-beta.1] - 2025-03-17
 - Fix: Bug when loading glTF files without any components where a reference to the loaded glTF structre was kept in memory causing the memory to not be freed
 

package/dist/needle-engine.bundle.js

@@ -1787,15 +1787,15 @@ function LC() {
   return n || null;
 }
 const q0 = S("debugdefines");
-To('if(!globalThis[""4.3.2-beta.1""]) globalThis[""4.3.2-beta.1""] = "0.0.0";');
+To('if(!globalThis[""4.3.2-beta.2""]) globalThis[""4.3.2-beta.2""] = "0.0.0";');
 To('if(!globalThis[""undefined""]) globalThis[""undefined""] = "unknown";');
-To('if(!globalThis[""Mon Mar 17 2025 15:55:42 GMT+0100 (Central European Standard Time)""]) globalThis[""Mon Mar 17 2025 15:55:42 GMT+0100 (Central European Standard Time)""] = "unknown";');
+To('if(!globalThis[""Tue Mar 18 2025 14:34:47 GMT+0100 (Central European Standard Time)""]) globalThis[""Tue Mar 18 2025 14:34:47 GMT+0100 (Central European Standard Time)""] = "unknown";');
 To('if(!globalThis[""npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006""]) globalThis[""npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006""] = "unknown";');
-To('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.3.2-beta.1";');
+To('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.3.2-beta.2";');
 To('globalThis["__NEEDLE_ENGINE_GENERATOR__"] = "undefined";');
-To('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Mon Mar 17 2025 15:55:42 GMT+0100 (Central European Standard Time)";');
+To('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Tue Mar 18 2025 14:34:47 GMT+0100 (Central European Standard Time)";');
 To('globalThis["__NEEDLE_PUBLIC_KEY__"] = "npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006";');
-const $s = "4.3.2-beta.1", xg = "undefined", X0 = "Mon Mar 17 2025 15:55:42 GMT+0100 (Central European Standard Time)";
+const $s = "4.3.2-beta.2", xg = "undefined", X0 = "Tue Mar 18 2025 14:34:47 GMT+0100 (Central European Standard Time)";
 q0 && console.log(`Engine version: ${$s} (generator: ${xg})
 Project built at ${X0}`);
 const md = "npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006", wo = "needle_isActiveInHierarchy", fa = "builtin_components", gd = "needle_editor_guid";
@@ -5392,9 +5392,21 @@ const Et = new v(), ky = new v(), Ty = new W(), wP = S("debuggizmos"), hs = 8947
   static isGizmo(t) {
     return t[bm] !== void 0;
   }
+  /** Set visibility of all currently rendered gizmos */
+  static setVisible(t) {
+    for (const e of Ee.timedObjectsBuffer)
+      e.visible = t;
+  }
   /**
    * Draw a label in the scene or attached to an object (if a parent is provided)
-   * @returns a handle to the label that can be used to change the text
+   * @param position the position of the label in world space
+   * @param text the text of the label
+   * @param size the size of the label in world space
+   * @param duration the duration in seconds the label will be rendered. If 0 it will be rendered for one frame
+   * @param color the color of the label
+   * @param backgroundColor the background color of the label
+   * @param parent the parent object to attach the label to. If no parent is provided the label will be attached to the scene
+   * @returns a handle to the label that can be used to update the text
    */
   static DrawLabel(t, e, i = 0.05, s = 0, o, a, l) {
     var d;
@@ -5404,54 +5416,128 @@ const Et = new v(), ky = new v(), Ty = new W(), wP = S("debuggizmos"), hs = 8947
     const c = ((d = J.active) == null ? void 0 : d.rigScale) ?? 1, h = Ee.getTextLabel(s, e, i * c, o, a);
     return l instanceof D && l.add(h), h.position.x = t.x, h.position.y = t.y, h.position.z = t.z, h;
   }
+  /**
+   * Draw a ray gizmo in the scene
+   * @param origin the origin of the ray in world space
+   * @param dir the direction of the ray in world space
+   * @param color the color of the ray
+   * @param duration the duration in seconds the ray will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the ray will be rendered with depth test
+   */
   static DrawRay(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getLine(s), l = a.geometry.getAttribute("position");
     l.setXYZ(0, t.x, t.y, t.z), Et.set(e.x, e.y, e.z).multiplyScalar(999999999), l.setXYZ(1, t.x + Et.x, t.y + Et.y, t.z + Et.z), l.needsUpdate = !0, a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1;
   }
+  /**
+   * Draw a line gizmo in the scene
+   * @param pt0 the start point of the line in world space
+   * @param pt1 the end point of the line in world space
+   * @param color the color of the line
+   * @param duration the duration in seconds the line will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the line will be rendered with depth test
+   * @param lengthFactor the length of the line. Default is 1
+   */
   static DrawDirection(t, e, i = hs, s = 0, o = !0, a = 1) {
     if (!Vi.enabled)
       return;
     const l = Ee.getLine(s), c = l.geometry.getAttribute("position");
     c.setXYZ(0, t.x, t.y, t.z), e.w !== void 0 ? (Et.set(0, 0, -a), Ty.set(e.x, e.y, e.z, e.w), Et.applyQuaternion(Ty)) : (Et.set(e.x, e.y, e.z), Et.multiplyScalar(a)), c.setXYZ(1, t.x + Et.x, t.y + Et.y, t.z + Et.z), c.needsUpdate = !0, l.material.color.set(i), l.material.depthTest = o, l.material.depthWrite = !1;
   }
+  /**
+   * Draw a line gizmo in the scene
+   * @param pt0 the start point of the line in world space
+   * @param pt1 the end point of the line in world space
+   * @param color the color of the line
+   * @param duration the duration in seconds the line will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the line will be rendered with depth test
+   */
   static DrawLine(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getLine(s), l = a.geometry.getAttribute("position");
     l.setXYZ(0, t.x, t.y, t.z), l.setXYZ(1, e.x, e.y, e.z), l.needsUpdate = !0, a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1, a.material.fog = !1;
   }
+  /**
+   * Draw a 2D circle gizmo in the scene
+   * @param pt0 the center of the circle in world space
+   * @param normal the normal of the circle in world space
+   * @param radius the radius of the circle in world space
+   * @param color the color of the circle
+   * @param duration the duration in seconds the circle will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the circle will be rendered with depth test
+   */
   static DrawCircle(t, e, i, s = hs, o = 0, a = !0) {
     if (!Vi.enabled)
       return;
     const l = Ee.getCircle(o);
     l.position.set(t.x, t.y, t.z), l.scale.set(i, i, i), l.quaternion.setFromUnitVectors(this._up, Et.set(e.x, e.y, e.z).normalize()), l.material.color.set(s), l.material.depthTest = a, l.material.depthWrite = !1, l.material.fog = !1;
   }
+  /**
+   * Draw a 3D wiremesh sphere gizmo in the scene
+   * @param center the center of the sphere in world space
+   * @param radius the radius of the sphere in world space
+   * @param color the color of the sphere
+   * @param duration the duration in seconds the sphere will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the sphere will be rendered with depth test
+   */
   static DrawWireSphere(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getSphere(e, s, !0);
     Ha(a, t.x, t.y, t.z), a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1, a.material.fog = !1;
   }
+  /**
+   * Draw a 3D sphere gizmo in the scene
+   * @param center the center of the sphere in world space
+   * @param radius the radius of the sphere in world space
+   * @param color the color of the sphere
+   * @param duration the duration in seconds the sphere will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the sphere will be rendered with depth test
+   */
   static DrawSphere(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getSphere(e, s, !1);
     Ha(a, t.x, t.y, t.z), a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1;
   }
+  /**
+   * Draw a 3D wiremesh box gizmo in the scene
+   * @param center the center of the box in world space
+   * @param size the size of the box in world space
+   * @param color the color of the box
+   * @param duration the duration in seconds the box will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the box will be rendered with depth test
+   */
   static DrawWireBox(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getBox(s);
     a.position.set(t.x, t.y, t.z), a.scale.set(e.x, e.y, e.z), a.material.color.set(i), a.material.depthTest = o, a.material.wireframe = !0, a.material.depthWrite = !1, a.material.fog = !1;
   }
+  /**
+   * Draw a 3D wiremesh box gizmo in the scene
+   * @param box the box in world space
+   * @param color the color of the box
+   * @param duration the duration in seconds the box will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the box will be rendered with depth test
+   */
   static DrawWireBox3(t, e = hs, i = 0, s = !0) {
     if (!Vi.enabled)
       return;
     const o = Ee.getBox(i);
     o.position.copy(t.getCenter(Et)), o.scale.copy(t.getSize(Et)), o.material.color.set(e), o.material.depthTest = s, o.material.wireframe = !0, o.material.depthWrite = !1, o.material.fog = !1;
   }
+  /**
+   * Draw an arrow gizmo in the scene
+   * @param pt0 the start point of the arrow in world space
+   * @param pt1 the end point of the arrow in world space
+   * @param color the color of the arrow
+   * @param duration the duration in seconds the arrow will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the arrow will be rendered with depth test
+   * @param wireframe if true the arrow will be rendered as wireframe
+   */
   static DrawArrow(t, e, i = hs, s = 0, o = !0, a = !1) {
     if (!Vi.enabled)
       return;
@@ -5479,11 +5565,6 @@ const Et = new v(), ky = new v(), Ty = new W(), wP = S("debuggizmos"), hs = 8947
     const e = Ee.getMesh(t.duration ?? 0);
     "mesh" in t ? (e.geometry = t.mesh.geometry, e.matrix.copy(t.mesh.matrixWorld)) : (e.geometry = t.geometry, e.matrix.copy(t.matrix)), e.matrixAutoUpdate = !1, e.matrixWorldAutoUpdate = !1, e.material.color.set(t.color ?? hs), e.material.depthTest = t.depthTest ?? !0, e.material.wireframe = !0;
   }
-  /** Set visibility of all currently rendered gizmos */
-  static setVisible(t) {
-    for (const e of Ee.timedObjectsBuffer)
-      e.visible = t;
-  }
 };
 let V = Vi;
 /**

package/dist/needle-engine.bundle.light.js

@@ -1787,15 +1787,15 @@ function LC() {
   return n || null;
 }
 const q0 = S("debugdefines");
-To('if(!globalThis[""4.3.2-beta.1""]) globalThis[""4.3.2-beta.1""] = "0.0.0";');
+To('if(!globalThis[""4.3.2-beta.2""]) globalThis[""4.3.2-beta.2""] = "0.0.0";');
 To('if(!globalThis[""undefined""]) globalThis[""undefined""] = "unknown";');
-To('if(!globalThis[""Mon Mar 17 2025 15:56:01 GMT+0100 (Central European Standard Time)""]) globalThis[""Mon Mar 17 2025 15:56:01 GMT+0100 (Central European Standard Time)""] = "unknown";');
+To('if(!globalThis[""Tue Mar 18 2025 14:35:06 GMT+0100 (Central European Standard Time)""]) globalThis[""Tue Mar 18 2025 14:35:06 GMT+0100 (Central European Standard Time)""] = "unknown";');
 To('if(!globalThis[""npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006""]) globalThis[""npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006""] = "unknown";');
-To('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.3.2-beta.1";');
+To('globalThis["__NEEDLE_ENGINE_VERSION__"] = "4.3.2-beta.2";');
 To('globalThis["__NEEDLE_ENGINE_GENERATOR__"] = "undefined";');
-To('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Mon Mar 17 2025 15:56:01 GMT+0100 (Central European Standard Time)";');
+To('globalThis["__NEEDLE_PROJECT_BUILD_TIME__"] = "Tue Mar 18 2025 14:35:06 GMT+0100 (Central European Standard Time)";');
 To('globalThis["__NEEDLE_PUBLIC_KEY__"] = "npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006";');
-const $s = "4.3.2-beta.1", xg = "undefined", X0 = "Mon Mar 17 2025 15:56:01 GMT+0100 (Central European Standard Time)";
+const $s = "4.3.2-beta.2", xg = "undefined", X0 = "Tue Mar 18 2025 14:35:06 GMT+0100 (Central European Standard Time)";
 q0 && console.log(`Engine version: ${$s} (generator: ${xg})
 Project built at ${X0}`);
 const md = "npk_0b7230d0d7c94c5ef23003726b2e2ccfc5ec0f20d26de8f0bda29e63698f9006", wo = "needle_isActiveInHierarchy", fa = "builtin_components", gd = "needle_editor_guid";
@@ -5392,9 +5392,21 @@ const Et = new v(), ky = new v(), Ty = new W(), wP = S("debuggizmos"), hs = 8947
   static isGizmo(t) {
     return t[bm] !== void 0;
   }
+  /** Set visibility of all currently rendered gizmos */
+  static setVisible(t) {
+    for (const e of Ee.timedObjectsBuffer)
+      e.visible = t;
+  }
   /**
    * Draw a label in the scene or attached to an object (if a parent is provided)
-   * @returns a handle to the label that can be used to change the text
+   * @param position the position of the label in world space
+   * @param text the text of the label
+   * @param size the size of the label in world space
+   * @param duration the duration in seconds the label will be rendered. If 0 it will be rendered for one frame
+   * @param color the color of the label
+   * @param backgroundColor the background color of the label
+   * @param parent the parent object to attach the label to. If no parent is provided the label will be attached to the scene
+   * @returns a handle to the label that can be used to update the text
    */
   static DrawLabel(t, e, i = 0.05, s = 0, o, a, l) {
     var d;
@@ -5404,54 +5416,128 @@ const Et = new v(), ky = new v(), Ty = new W(), wP = S("debuggizmos"), hs = 8947
     const c = ((d = J.active) == null ? void 0 : d.rigScale) ?? 1, h = Ee.getTextLabel(s, e, i * c, o, a);
     return l instanceof D && l.add(h), h.position.x = t.x, h.position.y = t.y, h.position.z = t.z, h;
   }
+  /**
+   * Draw a ray gizmo in the scene
+   * @param origin the origin of the ray in world space
+   * @param dir the direction of the ray in world space
+   * @param color the color of the ray
+   * @param duration the duration in seconds the ray will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the ray will be rendered with depth test
+   */
   static DrawRay(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getLine(s), l = a.geometry.getAttribute("position");
     l.setXYZ(0, t.x, t.y, t.z), Et.set(e.x, e.y, e.z).multiplyScalar(999999999), l.setXYZ(1, t.x + Et.x, t.y + Et.y, t.z + Et.z), l.needsUpdate = !0, a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1;
   }
+  /**
+   * Draw a line gizmo in the scene
+   * @param pt0 the start point of the line in world space
+   * @param pt1 the end point of the line in world space
+   * @param color the color of the line
+   * @param duration the duration in seconds the line will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the line will be rendered with depth test
+   * @param lengthFactor the length of the line. Default is 1
+   */
   static DrawDirection(t, e, i = hs, s = 0, o = !0, a = 1) {
     if (!Vi.enabled)
       return;
     const l = Ee.getLine(s), c = l.geometry.getAttribute("position");
     c.setXYZ(0, t.x, t.y, t.z), e.w !== void 0 ? (Et.set(0, 0, -a), Ty.set(e.x, e.y, e.z, e.w), Et.applyQuaternion(Ty)) : (Et.set(e.x, e.y, e.z), Et.multiplyScalar(a)), c.setXYZ(1, t.x + Et.x, t.y + Et.y, t.z + Et.z), c.needsUpdate = !0, l.material.color.set(i), l.material.depthTest = o, l.material.depthWrite = !1;
   }
+  /**
+   * Draw a line gizmo in the scene
+   * @param pt0 the start point of the line in world space
+   * @param pt1 the end point of the line in world space
+   * @param color the color of the line
+   * @param duration the duration in seconds the line will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the line will be rendered with depth test
+   */
   static DrawLine(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getLine(s), l = a.geometry.getAttribute("position");
     l.setXYZ(0, t.x, t.y, t.z), l.setXYZ(1, e.x, e.y, e.z), l.needsUpdate = !0, a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1, a.material.fog = !1;
   }
+  /**
+   * Draw a 2D circle gizmo in the scene
+   * @param pt0 the center of the circle in world space
+   * @param normal the normal of the circle in world space
+   * @param radius the radius of the circle in world space
+   * @param color the color of the circle
+   * @param duration the duration in seconds the circle will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the circle will be rendered with depth test
+   */
   static DrawCircle(t, e, i, s = hs, o = 0, a = !0) {
     if (!Vi.enabled)
       return;
     const l = Ee.getCircle(o);
     l.position.set(t.x, t.y, t.z), l.scale.set(i, i, i), l.quaternion.setFromUnitVectors(this._up, Et.set(e.x, e.y, e.z).normalize()), l.material.color.set(s), l.material.depthTest = a, l.material.depthWrite = !1, l.material.fog = !1;
   }
+  /**
+   * Draw a 3D wiremesh sphere gizmo in the scene
+   * @param center the center of the sphere in world space
+   * @param radius the radius of the sphere in world space
+   * @param color the color of the sphere
+   * @param duration the duration in seconds the sphere will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the sphere will be rendered with depth test
+   */
   static DrawWireSphere(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getSphere(e, s, !0);
     Ha(a, t.x, t.y, t.z), a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1, a.material.fog = !1;
   }
+  /**
+   * Draw a 3D sphere gizmo in the scene
+   * @param center the center of the sphere in world space
+   * @param radius the radius of the sphere in world space
+   * @param color the color of the sphere
+   * @param duration the duration in seconds the sphere will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the sphere will be rendered with depth test
+   */
   static DrawSphere(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getSphere(e, s, !1);
     Ha(a, t.x, t.y, t.z), a.material.color.set(i), a.material.depthTest = o, a.material.depthWrite = !1;
   }
+  /**
+   * Draw a 3D wiremesh box gizmo in the scene
+   * @param center the center of the box in world space
+   * @param size the size of the box in world space
+   * @param color the color of the box
+   * @param duration the duration in seconds the box will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the box will be rendered with depth test
+   */
   static DrawWireBox(t, e, i = hs, s = 0, o = !0) {
     if (!Vi.enabled)
       return;
     const a = Ee.getBox(s);
     a.position.set(t.x, t.y, t.z), a.scale.set(e.x, e.y, e.z), a.material.color.set(i), a.material.depthTest = o, a.material.wireframe = !0, a.material.depthWrite = !1, a.material.fog = !1;
   }
+  /**
+   * Draw a 3D wiremesh box gizmo in the scene
+   * @param box the box in world space
+   * @param color the color of the box
+   * @param duration the duration in seconds the box will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the box will be rendered with depth test
+   */
   static DrawWireBox3(t, e = hs, i = 0, s = !0) {
     if (!Vi.enabled)
       return;
     const o = Ee.getBox(i);
     o.position.copy(t.getCenter(Et)), o.scale.copy(t.getSize(Et)), o.material.color.set(e), o.material.depthTest = s, o.material.wireframe = !0, o.material.depthWrite = !1, o.material.fog = !1;
   }
+  /**
+   * Draw an arrow gizmo in the scene
+   * @param pt0 the start point of the arrow in world space
+   * @param pt1 the end point of the arrow in world space
+   * @param color the color of the arrow
+   * @param duration the duration in seconds the arrow will be rendered. If 0 it will be rendered for one frame
+   * @param depthTest if true the arrow will be rendered with depth test
+   * @param wireframe if true the arrow will be rendered as wireframe
+   */
   static DrawArrow(t, e, i = hs, s = 0, o = !0, a = !1) {
     if (!Vi.enabled)
       return;
@@ -5479,11 +5565,6 @@ const Et = new v(), ky = new v(), Ty = new W(), wP = S("debuggizmos"), hs = 8947
     const e = Ee.getMesh(t.duration ?? 0);
     "mesh" in t ? (e.geometry = t.mesh.geometry, e.matrix.copy(t.mesh.matrixWorld)) : (e.geometry = t.geometry, e.matrix.copy(t.matrix)), e.matrixAutoUpdate = !1, e.matrixWorldAutoUpdate = !1, e.material.color.set(t.color ?? hs), e.material.depthTest = t.depthTest ?? !0, e.material.wireframe = !0;
   }
-  /** Set visibility of all currently rendered gizmos */
-  static setVisible(t) {
-    for (const e of Ee.timedObjectsBuffer)
-      e.visible = t;
-  }
 };
 let V = Vi;
 /**