@needle-tools/engine 4.12.0-beta.1 → 4.12.0-next.c6c0281

package/src/engine-components/Joints.ts

@@ -36,6 +36,12 @@ export abstract class Joint extends Behaviour {
     protected abstract createJoint(self: Rigidbody, other: Rigidbody);
 }
 
+/**
+ * The FixedJoint groups together 2 rigidbodies, making them stick together in their bound position
+ * @summary Connect two Rigidbodies and make them stick together
+ * @category Physics
+ * @group Components
+ */
 export class FixedJoint extends Joint {
 
     protected createJoint(self: Rigidbody, other: Rigidbody) {
@@ -43,6 +49,14 @@ export class FixedJoint extends Joint {
     }
 }
 
+/**
+ * The HingeJoint groups together 2 rigid bodies, constraining them to move like connected by a hinge.
+ * 
+ * You can specify the anchor point and axis of rotation for the hinge.
+ * @summary Connect two Rigidbodies with a hinge
+ * @category Physics
+ * @group Components
+ */
 export class HingeJoint extends Joint {
 
     @serializable(Vector3)

package/src/engine-components/LookAtConstraint.ts

@@ -9,7 +9,7 @@ import type { OrbitControls } from "./OrbitControls.js";
  * This component is used by {@link OrbitControls} internally.
  * 
  * @summary Look At Constraint for OrbitControls
- * @category Camera Controls
+ * @category Camera and Controls
  * @group Components
  */
 export class LookAtConstraint extends Behaviour {

package/src/engine-components/OrbitControls.ts

@@ -64,7 +64,7 @@ declare module 'three/examples/jsm/controls/OrbitControls.js' {
  * The three OrbitControls object can be accessed via the `controls` property.  
  * The object being controlled by the OrbitControls (usually the camera) can be accessed via the `controllerObject` property.
  * @summary Camera controller using three.js OrbitControls
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  */
 export class OrbitControls extends Behaviour implements ICameraController {

package/src/engine-components/Renderer.ts

@@ -805,6 +805,12 @@ export class Renderer extends Behaviour implements IRenderer {
 export class MeshRenderer extends Renderer {
 }
 
+/**
+ * Renders deformable meshes that deform via bones and/or blend shapes.
+ * @summary Renderer for deformable meshes
+ * @category Rendering
+ * @group Components
+ **/
 export class SkinnedMeshRenderer extends MeshRenderer {
 
     private _needUpdateBoundingSphere = false;

package/src/engine-components/RendererInstancing.ts

@@ -669,14 +669,17 @@ class InstancedMeshRenderer {
     private grow(geometry: BufferGeometry) {
         const id = ++this._growId;
         const growFactor = 2;
-        const newSize = Math.ceil(this._maxInstanceCount * growFactor);
+
+        const growInstances = this.count >= this._maxInstanceCount;
+        const newSize = growInstances ? Math.ceil(this._maxInstanceCount * growFactor) : this._maxInstanceCount;
 
         // create a new BatchedMesh instance
         // TODO: we should keep track of how many instances for each geometry we have and consider that when estimating new space
         const estimatedSpace = this.tryEstimateVertexCountSize(newSize, [geometry]);// geometry.attributes.position.count;
         // const indices = geometry.index ? geometry.index.count : 0;
-        const newMaxVertexCount = Math.max(this._maxVertexCount, estimatedSpace.vertexCount);
-        const newMaxIndexCount = Math.max(this._maxIndexCount, estimatedSpace.indexCount);//, Math.ceil(this._maxVertexCount * growFactor));
+        const vertexGrowFactor = 1.25;
+        const newMaxVertexCount = Math.max(this._maxVertexCount, Math.ceil(estimatedSpace.vertexCount * vertexGrowFactor));
+        const newMaxIndexCount = Math.max(this._maxIndexCount, Math.ceil(estimatedSpace.indexCount * vertexGrowFactor));
 
         if (debugInstancing) {
             const geometryInfo = getMeshInformation(geometry);

package/src/engine-components/SceneSwitcher.ts

@@ -261,7 +261,7 @@ export class SceneSwitcher extends Behaviour {
             if (scene && !scene.hasUrl && scene.asset instanceof Object3D) {
                 GameObject.remove(scene.asset);
             }
-            else if(scene instanceof Object3D) {
+            else if (scene instanceof Object3D) {
                 GameObject.remove(scene);
             }
         }
@@ -477,13 +477,13 @@ export class SceneSwitcher extends Behaviour {
      * @returns a promise that resolves to true if the scene was loaded successfully
      */
     select(index: number | string): Promise<boolean> {
-        if (debug) console.log("select", index);
+        if (debug) console.log("[SceneSwitcher] select", index);
 
         if (typeof index === "object") {
             // If a user tries to reference a scene object in a UnityEvent and invoke select(obj) 
             // Then the object will be serialized as a object { guid : ... } or with the index json pointer
             // This case is not supported right now. Object references in the editor must not be scene references
-            console.warn("Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
+            console.warn("[SceneSwitcher] Switching to \"" + index + "\" might not work. Please either use an index or a AssetReference (not a scene reference)");
         }
 
         if (typeof index === "string") {
@@ -595,7 +595,7 @@ export class SceneSwitcher extends Behaviour {
         const current = this._currentScene;
         this._currentScene = undefined;
         if (current) {
-            if (debug) console.log("UNLOAD", current.url, "HasURL?: " + current.hasUrl)
+            if (debug) console.log("[SceneSwitcher] UNLOAD", current.url, "HasURL?: " + current.hasUrl)
             const sceneListener = this.tryGetSceneEventListener(current.asset as any as Object3D);
             if (sceneListener?.sceneClosing) {
                 const res = sceneListener.sceneClosing();
@@ -620,6 +620,7 @@ export class SceneSwitcher extends Behaviour {
         const index = this._currentIndex = this.scenes?.indexOf(scene) ?? -1;
 
         try {
+            if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene start: ${scene.url} (index: ${index})`);
             this._currentlyLoadingScene = scene;
             this._currentLoadingProgress = new ProgressEvent("progress", { loaded: 0, total: 1 });
 
@@ -632,7 +633,7 @@ export class SceneSwitcher extends Behaviour {
                 if (debug) {
                     const t01 = prog.loaded / prog.total;
                     const progressBarString = "[" + "=".repeat(Math.floor(t01 * 20)) + "-".repeat(20 - Math.floor(t01 * 20)) + "]";
-                    console.debug(`[SceneSwitcher] Download ${(t01 * 100).toFixed(1)} % ${progressBarString}`, scene.url);
+                    console.debug(`${Date.now()} [SceneSwitcher] Loading scene progress: ${(t01 * 100).toFixed(1)} % ${progressBarString}`, scene.url);
                 }
                 this._currentLoadingProgress = prog;
                 this.dispatchEvent(prog);
@@ -646,15 +647,15 @@ export class SceneSwitcher extends Behaviour {
             this._currentlyLoadingScene = undefined;
 
             if (finishedEvt.defaultPrevented) {
-                if (debug) console.warn("Adding loaded scene prevented:", scene, finishedEvt);
+                if (debug) console.warn("[SceneSwitcher] Adding loaded scene prevented:", scene, finishedEvt);
                 return false;
             }
             if (!scene.asset) {
-                if (debug) console.warn("Failed loading scene:", scene);
+                if (debug) console.warn("[SceneSwitcher] Failed loading scene:", scene);
                 return false;
             }
             if (this._currentIndex === index) {
-                if (debug) console.log("ADD", scene.url);
+                if (debug) console.log("[SceneSwitcher] ADD", scene.url);
                 this._currentScene = scene;
 
 
@@ -683,7 +684,7 @@ export class SceneSwitcher extends Behaviour {
                         this.context.scene.background = skybox;
                     }
                     else if (debug) {
-                        console.warn("SceneSwitcher: Can't find skybox for scene " + scene.url);
+                        console.warn("[SceneSwitcher] Can't find skybox for scene " + scene.url);
                     }
                 }
 
@@ -713,10 +714,9 @@ export class SceneSwitcher extends Behaviour {
                     const res = sceneListener.sceneOpened(this);
                     if (res instanceof Promise) await res;
                 }
-
+                if (debug) console.debug(`${Date.now()} [SceneSwitcher] Loading scene finished: ${scene.url} (index: ${index})`);
                 const openedEvt = new CustomEvent<LoadSceneEvent>("scene-opened", { detail: { scene: scene, switcher: this, index: index } });
                 this.dispatchEvent(openedEvt);
-
                 this.sceneLoaded?.invoke(this);
                 return true;
             }
@@ -772,7 +772,7 @@ export class SceneSwitcher extends Behaviour {
             }
         }
 
-        if (isLocalNetwork()) console.warn("Can not find scene: \"" + value + "\"", this)
+        if (isLocalNetwork()) console.warn("[SceneSwitcher] Can not find scene: \"" + value + "\"", this)
 
         return couldNotLoadScenePromise;
     }
@@ -913,7 +913,7 @@ class PreLoadScheduler {
      */
     begin(delay: number) {
         if (this._isRunning) return;
-        if (debug) console.log("Preload begin", { delay })
+        if (debug) console.log("[SceneSwitcher] Preload scheduled", { delay });
         this._isRunning = true;
         let lastRoom: number = -10;
         let searchDistance: number;
@@ -923,7 +923,7 @@ class PreLoadScheduler {
         const interval = setInterval(() => {
             if (this.allLoaded()) {
                 if (debug)
-                    console.log("All scenes (pre-)loaded");
+                    console.log("[SceneSwitcher] All scenes (pre-)loaded");
                 this.stop();
             }
             if (!this._isRunning) {
@@ -950,7 +950,7 @@ class PreLoadScheduler {
             if (roomIndex < 0 || roomIndex >= array.length) return;
             if (!this._loadTasks.some(t => t.index === roomIndex)) {
                 const scene = array[roomIndex];
-                if (debug) console.log("Preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
+                if (debug) console.log("[SceneSwitcher] Schedule preload scene", { roomIndex, searchForward, lastRoom, currentIndex: this._switcher.currentIndex, tasks: this._loadTasks.length }, scene?.url);
                 new LoadTask(roomIndex, scene, this._loadTasks);
             }
         }, 200);
@@ -1019,10 +1019,10 @@ class LoadTask {
     private async awaitLoading() {
         if (this.asset && !this.asset.isLoaded()) {
             if (debug)
-                console.log("Preload start: " + this.asset.url, this.index);
+                console.log("[SceneSwitcher] Preload start: " + this.asset.url, this.index);
             await this.asset.preload();
             if (debug)
-                console.log("Preload finished: " + this.asset.url, this.index);
+                console.log("[SceneSwitcher] Preload finished: " + this.asset.url, this.index);
         }
 
         const i = this.tasks.indexOf(this);

package/src/engine-components/SpriteRenderer.ts

@@ -262,7 +262,8 @@ export class SpriteData {
  * 
  * - Example: https://engine.needle.tools/samples/spritesheet-animation
  * 
- * @category Sprites
+ * @summary Renders 2D images from a sprite sheet
+ * @category Rendering
  * @group Components
  */
 export class SpriteRenderer extends Behaviour {

package/src/engine-components/api.ts

@@ -35,7 +35,8 @@
  */
 
 export * from "./codegen/components.js";
-export { Behaviour, Component, GameObject } from "./Component.js"
+export { Behaviour, Component, GameObject } from "./Component.js";
+export { Collider } from "./Collider.js"; // export abstract type
 
 // We dont want to export everything in the extensions
 export { ClearFlags } from "./Camera.js"

package/src/engine-components/codegen/components.ts

@@ -23,7 +23,6 @@ export { BoxHelperComponent } from "../BoxHelperComponent.js";
 export { Camera } from "../Camera.js";
 export { CharacterController } from "../CharacterController.js";
 export { CharacterControllerInput } from "../CharacterController.js";
-export { Collider } from "../Collider.js";
 export { SphereCollider } from "../Collider.js";
 export { BoxCollider } from "../Collider.js";
 export { MeshCollider } from "../Collider.js";

package/src/engine-components/timeline/SignalAsset.ts

@@ -30,7 +30,7 @@ export class SignalReceiverEvent {
  * Signals can be added to a signal track on a {@link PlayableDirector}
  * 
  * @summary Receives signals and invokes reactions
- * @category Sequencing and Timelines
+ * @category Animation and Sequencing
  * @group Components
  */
 export class SignalReceiver extends Behaviour {

package/src/engine-components/ui/Raycaster.ts

@@ -31,7 +31,7 @@ export abstract class Raycaster extends Behaviour {
 /**
  * A Raycaster that performs raycasting against its own GameObject.  
  * 
- * @category Interaction
+ * @category Interactivity
  * @group Components
  */
 export class ObjectRaycaster extends Raycaster {
@@ -75,7 +75,8 @@ export class ObjectRaycaster extends Raycaster {
 /**
  * A Raycaster that performs raycasting against UI elements (objects with a CanvasRenderer component).  
  * 
- * @category UI
+ * @summary Raycaster for UI elements
+ * @category User Interface
  * @group Components
  */
 export class GraphicRaycaster extends ObjectRaycaster {

package/src/engine-components/ui/RectTransform.ts

@@ -29,6 +29,12 @@ const tempVec = new Vector3();
 const tempMatrix = new Matrix4();
 const tempQuaternion = new Quaternion();
 
+/** 
+* RectTransform is a component that defines a rectangle for UI layout. 
+* @summary UI Rectangle Transform
+* @category User Interface
+* @group Components
+*/
 export class RectTransform extends BaseUIComponent implements IRectTransform, IRectTransformChangedReceiver {
 
     get parent() {

package/src/engine-components/utils/LookAt.ts

@@ -13,7 +13,8 @@ import { Behaviour } from "../Component.js";
  * It can also invert the forward direction and keep the up direction.
  * 
  * @summary Makes the object look at a target object or the camera
- * @category Interactivity, Everywhere Actions
+ * @category Everywhere Actions
+ * @category Interactivity
  * @group Components
  */
 export class LookAt extends Behaviour implements UsdzBehaviour {

package/src/engine-components/web/CursorFollow.ts

@@ -15,7 +15,7 @@ const debug = getParam("debugcursor");
  * - Example: [Look At Cursor sample](https://engine.needle.tools/samples/look-at-cursor-interactive-3d-header/). This sample combines the CursorFollow component with a LookAt component to create an interactive 3D header that looks at the cursor.
  * 
  * @summary Makes the object follow the cursor position on screen
- * @category Web
+ * @category Interactivity
  * @group Components
  * @component
  */

package/src/engine-components/web/HoverAnimation.ts

@@ -14,7 +14,7 @@ import { Behaviour } from "../Component.js";
  * By default, a simple scale-up animation is used. You can customize the hover and idle animations by providing your own animation clips.
  * 
  * @summary Hover Animation on Pointer Enter/Exit
- * @category Web
+ * @category Interactivity
  * @group Components
  */
 @registerType

package/src/engine-components/web/ViewBox.ts

@@ -32,7 +32,7 @@ export type ViewBoxMode = "continuous" | "once";
  * ```
   
  * @summary Automatically fits a box area into the camera view
- * @category Camera
+ * @category Camera and Controls
  * @group Components
  * @component
  */