@needle-tools/engine 4.12.0-beta → 4.12.0-next.0b39d59

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/ShadowCatcher.ts

@@ -23,7 +23,7 @@ enum ShadowMode {
  * 
  * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
  * 
- * @summary Renders shadows or light on the object
+ * @summary Creates a shadow mask or a light occluder 
  * @category Rendering
  * @group Components
  */

package/src/engine-components/SpectatorCamera.ts

@@ -35,7 +35,7 @@ const debug = getParam("debugspectator");
  * 
  * Debug mode can be enabled with the URL parameter `?debugspectator`, which provides additional console output.
  * 
- * @summary Follow other users in a networked room
+ * @summary Spectator camera for following other users
  * @category Networking
  * @group Components
  */

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/Voip.ts

@@ -14,7 +14,7 @@ const debugParam = getParam("debugvoip");
 /**
  * The Voice over IP component (VoIP) allows you to send and receive audio streams to other users in the same networked room.  
  * It requires a networking connection to be working (e.g. by having an active SyncedRoom component in the scene or by connecting to a room manually).  
- * @summary Voice over IP (VoIP) for networked audio communication
+ * @summary Voice over IP for networked audio communication
  * @category Networking
  * @group Components
  */

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/export/gltf/GltfExport.ts

@@ -30,6 +30,11 @@ export class GltfExportBox extends BoxHelperComponent {
 }
 
 /**
+ * GltfExport is a component that enables exporting selected 3D objects from the scene to the glTF format.  
+ * You can specify whether to export in binary format (.glb) or JSON format (.gltf), and select specific objects to include in the export.
+ * The exported glTF file can be used in various 3D applications and engines that support the glTF standard.
+ * 
+ * @summary Export selected 3D objects to glTF format
  * @category Asset Management
  * @group Components
  */

package/src/engine-components/export/usdz/USDZExporter.ts

@@ -84,6 +84,7 @@ type BeforeLODExportArguments = {
  * usdz.autoExportAudioSources = true;
  * usdz.exportAsync();
  * ```
+ * @summary Export 3D objects as USDZ files for QuickLook
  * @category XR
  * @group Components
  */

package/src/engine-components/particlesystem/ParticleSystem.ts

@@ -692,7 +692,7 @@ class ParticlesEmissionState implements EmissionState {
  * 
  * Needle Engine uses [three.quarks](https://github.com/Alchemist0823/three.quarks) under the hood to handle particles.
  * 
- * @summary Particle System
+ * @summary Handles the motion and rendering of many individual particles
  * @category Rendering
  * @group Components
  */

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/Button.ts

@@ -64,7 +64,7 @@ class AnimationTriggers {
  * Button is a UI component that can be clicked by the user to perform an action.  
  * It supports different visual states such as normal, highlighted, pressed, and disabled.  
  * You can customize the button's appearance using colors or animations for each state.
- * @summary Button UI Component
+ * @summary UI Button that can be clicked to perform actions
  * @category User Interface
  * @group Components
  */

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

@@ -29,7 +29,7 @@ const debugLayout = getParam("debuguilayout");
  * It defines the area where UI elements are rendered and manages their layout and rendering settings.  
  * Canvases can be set to render in world space or screen space (overlay or camera).  
  * Multiple canvases can exist in a scene, each with its own settings and hierarchy of UI elements.
- * @summary Canvas UI Component
+ * @summary Root component for UI elements, managing layout and rendering settings
  * @category User Interface
  * @group Components
  */

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

@@ -10,7 +10,7 @@ import { type ICanvasGroup, type IHasAlphaFactor } from "./Interfaces.js";
  * CanvasGroup is a UI component that allows you to control the transparency and interactivity of a group of UI elements.  
  * By adjusting the alpha property, you can fade in or out all child UI elements simultaneously.  
  * The interactable and blocksRaycasts properties let you enable or disable user interaction for the entire group.
- * @summary CanvasGroup UI Component
+ * @summary Group UI elements to control transparency and interactivity
  * @category User Interface
  * @group Components
  */

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

@@ -37,7 +37,7 @@ onInitialized((ctx) => {
 
 /**
  * The EventSystem is responsible for managing and dispatching input events to UI components within the scene.
- * @summary UI Input Event System
+ * @summary Manages and dispatches input events to UI components
  * @category User Interface
  * @group Components
  */

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

@@ -15,7 +15,7 @@ class Sprite {
  * Image is a UI component that displays a sprite (2D image) in the user interface.  
  * You can set the image property to assign a texture to be displayed.  
  * The sprite can be customized with various properties such as color tinting and pixel density.
- * @summary Image UI Component
+ * @summary Display a 2D image in the UI
  * @category User Interface
  * @group Components
  */

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

@@ -13,7 +13,7 @@ const debug = getParam("debuginputfield");
  * InputField is a UI component that allows users to enter and edit text.  
  * It provides a text input area where users can type, delete, and modify text.  
  * The InputField supports placeholder text, events for value changes, and end edit actions.
- * @summary Text Input Field UI Component
+ * @summary Text field for user input
  * @category User Interface
  * @group Components
  */

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

@@ -7,7 +7,7 @@ import { Behaviour } from "../Component.js";
 /**
  * Outline is a UI component that adds an outline effect to UI elements.  
  * You can customize the outline color and distance to create a visual border around the UI element.
- * @summary Outline UI Component
+ * @summary Add an outline effect to UI elements
  * @category User Interface
  * @group Components
  */

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/ui/SpatialHtml.ts

@@ -6,6 +6,13 @@ import { serializable } from '../../engine/engine_serialization.js';
 import { getWorldRotation, setWorldRotationXYZ } from '../../engine/engine_three_utils.js';
 import { Behaviour } from '../Component.js';
 
+/**
+ * SpatialHtml is a component that allows you to integrate HTML elements into a 3D scene.  
+ * By specifying the ID of an existing HTML element, you can render it as a 3D object within the scene.
+ * @summary Render HTML elements as 3D objects in the scene
+ * @category User Interface
+ * @group Components
+ */
 export class SpatialHtml extends Behaviour {
 
     @serializable()

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

@@ -41,6 +41,8 @@ export enum FontStyle {
 
 /**
  * Text is a UI component that displays text in the user interface.
+ * 
+ * @summary Display text in the UI
  * @category User Interface
  * @group Components
  */

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
  */