@needle-tools/engine 4.11.0-next.91b9cf1 → 4.11.0-next.cc37c71

package/plugins/vite/dependencies.js

@@ -8,23 +8,26 @@ export const preloadScriptPaths = [];
 
 /**
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin[]}
  */
 export const needleDependencies = (command, config, userSettings) => {
 
     /**
      * @type {import('vite').Plugin}
      */
-    return {
-        name: 'needle:dependencies',
-        enforce: 'pre',
-        /**
-         * @param {import('vite').UserConfig} config
-         */
-        config: (config, env) => {
-            handleOptimizeDeps(config);
-            handleManualChunks(config);
-        }
-    }
+    return [
+        {
+            name: 'needle:dependencies',
+            enforce: 'pre',
+            /**
+             * @param {import('vite').UserConfig} config
+             */
+            config: (config, env) => {
+                handleOptimizeDeps(config);
+                handleManualChunks(config);
+            },
+        },
+    ]
 }
 
 const excludeDependencies = [
@@ -167,6 +170,13 @@ function handleManualChunks(config) {
                 return name;
             }
         }
+        // else if(chunk.name === 'index') {
+        //     console.log(chunk);
+        //     debugger
+        //     // this is the main chunk
+        //     // we don't want to add a hash here to be able to easily import the main script
+        //     return `index.js`;
+        // }
         return `assets/[name].[hash].js`;
     }
 

package/plugins/vite/index.js

@@ -63,11 +63,16 @@ export { needleImportsLogger } from "./imports-logger.js";
 import { needleBuildInfo } from "./buildinfo.js";
 export { needleBuildInfo } from "./buildinfo.js";
 
+import { needleApp } from "./needle-app.js";
+export { needleApp } from "./needle-app.js";
+
 import { needleServer } from "./server.js";
 import { needleNPM } from "./npm.js";
 import { needleTransformCode } from "./transform.js";
 import { needleMaterialXLoader } from "./materialx.js";
 import { needleLogger } from "./logger.js";
+import { viteFixWorkerImport } from "../common/worker.js";
+
 export { needleServer } from "./server.js";
 
 
@@ -137,6 +142,8 @@ export const needlePlugins = async (command, config = undefined, userSettings =
         needleServer(command, config, userSettings),
         needleNPM(command, config, userSettings),
         needleMaterialXLoader(command, config, userSettings),
+        needleApp(command, config, userSettings),
+        viteFixWorkerImport()
     ];
 
     const asap = await needleAsap(command, config, userSettings);

package/plugins/vite/needle-app.js

@@ -0,0 +1,194 @@
+import { writeFile } from 'fs';
+import { tryParseNeedleEngineSrcAttributeFromHtml } from '../common/needle-engine.js';
+
+
+
+/**
+ * @param {'serve' | 'build'} command
+ * @param {{} | undefined | null} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin[] | null}
+ */
+export const needleApp = (command, config, userSettings) => {
+
+    if (command !== "build") {
+        return null;
+    }
+
+    /** @type {Array<import("rollup").OutputChunk>} */
+    const entryFiles = new Array();
+
+    let outputDir = "dist";
+
+    /**
+     * @type {import('vite').Plugin}
+     */
+    return [
+        {
+            name: 'needle:app',
+            enforce: "post",
+            configResolved(config) {
+                outputDir = config.build.outDir || "dist";
+            },
+            transformIndexHtml: {
+                handler: async function (html, context) {
+                    const name = context.filename;
+                    if (name.includes("index.html")) {
+                        if (context.chunk?.isEntry) {
+                            try {
+                                entryFiles.push(context.chunk);
+                                const path = context.chunk.fileName;
+                                // console.log("[needle-dependencies] entry chunk imports", {
+                                //     name: context.chunk.fileName,
+                                //     imports: context.chunk.imports,
+                                //     dynamicImports: context.chunk.dynamicImports,
+                                //     refs: context.chunk.referencedFiles,
+                                // });
+
+                                // TODO: here we try to find the main asset (entrypoint) for this web app. It's a bit hacky right now but we have to assign this url directly to make it work with `gen.js` where multiple needle-apps are on different (or the same) pages.
+                                const attribute_src = tryParseNeedleEngineSrcAttributeFromHtml(html);
+                                const imported_glbs = Array.from(context.chunk.viteMetadata?.importedAssets?.values() || [])?.filter(f => f.endsWith(".glb") || f.endsWith(".gltf"));
+
+                                const main_asset = attribute_src?.[0] || imported_glbs?.[0];
+
+                                const webComponent = generateNeedleEmbedWebComponent(path, main_asset);
+                                await writeFile(`${outputDir}/needle-app.js`, webComponent, (err) => {
+                                    if (err) {
+                                        console.error("[needle-app] could not create needle-app.js", err);
+                                    }
+                                    else {
+                                        console.log("[needle-app] created needle-app.js");
+                                    }
+                                });
+                            }
+                            catch (e) {
+                                console.warn("WARN: could not create needle-app.js\n", e);
+                            }
+                        }
+                    }
+                }
+            },
+
+        }
+    ]
+}
+
+
+/**
+ * @param {string} filepath
+ * @param {string | null} src
+ * @returns {string}
+ */
+function generateNeedleEmbedWebComponent(filepath, src) {
+
+
+    // filepath is e.g. `assets/index-XXXXXXXX.js`
+    // we want to make sure the path is correct relative to where the component will be used
+    // this script will be emitted in the output directory root (e.g. needle-embed.js)
+
+    const componentDefaultName = 'needle-app';
+
+    return `
+
+// Needle Engine attributes we want to allow to be overriden
+const knownAttributes = [
+    "src",
+    "background-color", 
+    "background-image", 
+    "environment-image", 
+    "focus-rect",
+];
+
+const scriptUrl = new URL(import.meta.url);
+const componentName = scriptUrl.searchParams.get("component-name") || '${componentDefaultName}';
+
+
+if (!customElements.get(componentName)) {
+    console.debug(\`Defining needle-app as <\${componentName}>\`);
+    customElements.define(componentName, class extends HTMLElement {
+
+        static get observedAttributes() {
+            return knownAttributes;
+        }
+
+        constructor() {
+            super();
+            this.attachShadow({ mode: 'open' });
+            const template = document.createElement('template');
+            template.innerHTML = \`
+                <style>
+                    :host {
+                        position: relative;
+                        display: block;
+                        width: max(360px 100%);
+                        height: max(240px, 100%);
+                        margin: 0;
+                        padding: 0;
+                    }
+                    needle-engine {
+                        position: absolute;
+                        top: 0;
+                        left: 0;
+                        width: 100%;
+                        height: 100%;
+                    }
+                </style>
+            \`;
+            this.shadowRoot.appendChild(template.content.cloneNode(true));
+
+            const script = document.createElement('script');
+            script.type = 'module';
+            const url = new URL('.', import.meta.url);
+            this.basePath = this.getAttribute('base-path') || \`\${url.protocol}//\${url.host}\${url.pathname}\`;
+            while(this.basePath.endsWith('/')) {
+                this.basePath = this.basePath.slice(0, -1);
+            }
+            script.src = this.getAttribute('script-src') || \`\${this.basePath}/${filepath}\`;
+            this.shadowRoot.appendChild(script);
+
+            this.needleEngine = document.createElement('needle-engine');
+            this.updateAttributes();
+            this.shadowRoot.appendChild(this.needleEngine);
+
+            console.debug(this.basePath, script.src, this.needleEngine.getAttribute("src"));
+        }
+
+        onConnectedCallback() {
+            console.debug('NeedleEmbed connected to the DOM');
+        }
+
+        disconnectedCallback() {
+            console.debug('NeedleEmbed disconnected from the DOM');
+        }
+        
+        attributeChangedCallback(name, oldValue, newValue) {
+            console.debug(\`NeedleApp attribute changed: \${name} from \${oldValue} to \${newValue}\`);
+            this.updateAttributes();
+        }
+
+        updateAttributes() {
+            console.debug("NeedleApp updating attributes");
+            
+            const src = this.getAttribute('src') || ${src?.length ? `\`\${this.basePath}/${src}\`` : null};
+            if(src) this.needleEngine.setAttribute("src", src);
+            else this.needleEngine.removeAttribute("src");
+
+            for(const attr of knownAttributes) {
+                
+                if(attr === "src") continue; // already handled above
+
+                if(this.hasAttribute(attr)) {
+                    this.needleEngine.setAttribute(attr, this.getAttribute(attr));
+                }
+                else {
+                    this.needleEngine.removeAttribute(attr);    
+                }
+            }
+        }
+    });
+}
+else {
+    console.warn(\`needle-app <\${componentName}> already defined.\`);
+}
+`
+}

package/src/engine/engine_physics.ts

@@ -572,6 +572,9 @@ declare module 'three' {
 
 
 namespace NEMeshBVH {
+
+    let failedToCreateMeshBVHWorker = 0;
+
     export function runMeshBVHRaycast(method: Raycaster | Sphere, mesh: Mesh, results: Intersection[], context: Pick<Context, "xr">, options: { allowSlowRaycastFallback?: boolean }): boolean {
         if (!mesh.geometry) {
             return false;
@@ -630,6 +633,10 @@ namespace NEMeshBVH {
                 || geom.index && geom.index?.["isInterleavedBufferAttribute"]) {
                 canUseWorker = false;
             }
+            else if (failedToCreateMeshBVHWorker > 10) {
+                // if we failed to create a worker multiple times, don't try again
+                canUseWorker = false;
+            }
 
             // if we have a worker use that
             if (canUseWorker && _GenerateMeshBVHWorker) {
@@ -646,8 +653,23 @@ namespace NEMeshBVH {
                     }
                     // if there are no workers available, create a new one
                     if (!workerInstance && workerInstances.length < 3) {
-                        workerInstance = new _GenerateMeshBVHWorker();
-                        workerInstances.push(workerInstance);
+                        try {
+                            workerInstance = new _GenerateMeshBVHWorker();
+                            workerInstances.push(workerInstance);
+                        }
+                        catch (err) {
+                            const isSecurityError = err instanceof DOMException && err.name === "SecurityError";
+                            if (isSecurityError) {
+                                console.warn("Failed to create MeshBVH worker, falling back to main thread generation. This can happen when running from file://, if the browser does not support workers or if the browser is blocking workers for other reasons.");
+                                console.debug(err);
+                                failedToCreateMeshBVHWorker += 10;
+                            }
+                            else {
+                                console.error("Failed to create MeshBVH worker");
+                                console.debug(err);
+                            }
+                            failedToCreateMeshBVHWorker++;
+                        }
                     }
 
                     if (workerInstance != null && !workerInstance.running) {
@@ -806,6 +828,9 @@ namespace NEMeshBVH {
                 if (debugPhysics || isDevEnvironment()) {
                     console.warn("Failed to setup mesh bvh worker");
                 }
+                else {
+                    console.debug("Failed to setup mesh bvh worker", _err);
+                }
             })
             .finally(() => {
                 isRequestingWorker = false;

package/src/engine/js-extensions/Object3D.ts

@@ -157,6 +157,14 @@ declare module 'three' {
          * Added by Needle Engine.
          */
         get worldUp(): Vector3;
+
+
+        /**
+         * Check if the given object is contained in the hierarchy of this object or if it's the same object.
+         * @param object The object to check.
+         * @returns True if the object is contained in the hierarchy, false otherwise.
+         */
+        contains(object: Object3D | null | undefined): boolean;
     }
 }
 
@@ -356,5 +364,21 @@ if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "worldUp")) {
 
 
 
+if (!Object.getOwnPropertyDescriptor(Object3D.prototype, "contains")) {
+    Object.defineProperty(Object3D.prototype, "contains", {
+        value: function (object: Object3D | null | undefined): boolean {
+            if (!object) return false;
+            if (this === object) return true;
+            for (const child of this.children) {
+                if (child.contains(object)) return true;
+            }
+            return false;
+        }
+    });
+}
+
+
+
+
 // do this after adding the component extensions
 registerPrototypeExtensions(Object3D);

package/src/engine/physics/workers/mesh-bvh/GenerateMeshBVHWorker.js

@@ -4,14 +4,16 @@ import { MeshBVH } from 'three-mesh-bvh';
 // Modified according to https://github.com/gkjohnson/three-mesh-bvh/issues/636#issuecomment-2209571751
 import { WorkerBase } from "three-mesh-bvh/src/workers/utils/WorkerBase.js";
 
+
 export class GenerateMeshBVHWorker extends WorkerBase {
 
 	constructor() {
 		// TODO: make mesh bvh worker "work" for prebundled CDN loading
 		// https://linear.app/needle/issue/NE-6572
 		// Also we don't use toplevel imports to not completely fail to load needle-engine where loading the worker fails
-		// const url = new URL('three-mesh-bvh/src/workers/generateMeshBVH.worker.js', import.meta.url)
+		// const meta_url = import.meta.url;
 		// const getWorker = () => new Worker(url, { type: 'module' })
+		// console.log(meta_url, url, getWorker());
 		super(new Worker(new URL('three-mesh-bvh/src/workers/generateMeshBVH.worker.js', import.meta.url), { type: 'module' }));
 		this.name = 'GenerateMeshBVHWorker';
 

package/src/engine-components/Collider.ts

@@ -16,7 +16,13 @@ import { Rigidbody } from "./RigidBody.js";
 /**
  * Collider is the base class for all colliders. A collider is a physical shape that is used to detect collisions with other objects in the scene.  
  * Colliders are used in combination with a {@link Rigidbody} to create physical interactions between objects.  
- * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.
+ * Colliders are registered with the physics engine when they are enabled and removed when they are disabled.  
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
+ * 
  * @category Physics  
  * @group Components
  */
@@ -112,6 +118,11 @@ export class Collider extends Behaviour implements ICollider {
 /**
  * SphereCollider represents a sphere-shaped collision volume.
  * Useful for objects that are roughly spherical in shape or need a simple collision boundary.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */
@@ -158,6 +169,11 @@ export class SphereCollider extends Collider implements ISphereCollider {
 /**
  * BoxCollider represents a box-shaped collision volume.
  * Ideal for rectangular objects or objects that need a simple cuboid collision boundary.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */
@@ -260,6 +276,11 @@ export class BoxCollider extends Collider implements IBoxCollider {
 /**
  * MeshCollider creates a collision shape from a mesh geometry.
  * Allows for complex collision shapes that match the exact geometry of an object.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */
@@ -343,6 +364,11 @@ export class MeshCollider extends Collider {
 /**
  * CapsuleCollider represents a capsule-shaped collision volume (cylinder with hemispherical ends).
  * Ideal for character controllers and objects that need a rounded collision shape.
+ * 
+ * - Example: https://samples.needle.tools/physics-basic
+ * - Example: https://samples.needle.tools/physics-playground
+ * - Example: https://samples.needle.tools/physics-&-animation 
+ * 
  * @category Physics
  * @group Components
  */

package/src/engine-components/ContactShadows.ts

@@ -44,10 +44,19 @@ type FitParameters = {
 // - node can simply be scaled in Y to adjust max. ground height
 
 /**
- * ContactShadows is a component that allows to display contact shadows in the scene.
+ * ContactShadows is a component that allows to display contact shadows in the scene. It has options for darkness, opacity and blur of the shadows.  
+ * 
+ * - Example: https://samples.needle.tools/contact-shadows
+ * 
+ * ## Usage
+ * You can use {@link ContactShadows.auto} to automatically create a ContactShadows instance for the scene or you can add the component to an object in the scene. Note that the scale of the object will be used to define the size of the shadow area.  
+ * 
+ * ContactShadows can also be enabled on the `<needle-engine>` web component directly by adding the `contactshadows` attribute. The value of the attribute will be used as opacity and darkness of the shadows: `<needle-engine contactshadows="0.7">`.
+ * 
+ * 
  * @category Rendering
  * @group Components
- */
+*/
 export class ContactShadows extends Behaviour {
 
     private static readonly _instances: Map<Context, ContactShadows> = new Map();
@@ -362,8 +371,7 @@ export class ContactShadows extends Behaviour {
             !this.depthMaterial || !this.shadowCamera ||
             !this.blurPlane || !this.shadowGroup || !this.plane ||
             !this.horizontalBlurMaterial || !this.verticalBlurMaterial) {
-            if (debug)
-                console.error("ContactShadows: not initialized yet");
+            if (debug) console.error("ContactShadows: not initialized yet");
             return;
         }
 

package/src/engine-components/DropListener.ts

@@ -1,23 +1,22 @@
-import { AxesHelper, Box3, Cache, Object3D, Vector2, Vector3 } from "three";
+import { Box3, Object3D, Vector2, Vector3 } from "three";
 
 import { isDevEnvironment } from "../engine/debug/index.js";
 import { AnimationUtils } from "../engine/engine_animation.js";
-import { addComponent } from "../engine/engine_components.js";
 import { Context } from "../engine/engine_context.js";
 import { destroy } from "../engine/engine_gameobject.js";
 import { Gizmos } from "../engine/engine_gizmos.js";
 import { getLoader } from "../engine/engine_gltf.js";
 import { BlobStorage } from "../engine/engine_networking_blob.js";
 import { PreviewHelper } from "../engine/engine_networking_files.js";
-import { generateSeed, InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
+import { InstantiateIdProvider } from "../engine/engine_networking_instantiate.js";
 import { serializable } from "../engine/engine_serialization_decorator.js";
 import { fitObjectIntoVolume, getBoundingBox, placeOnSurface } from "../engine/engine_three_utils.js";
-import { IGameObject, Model, Vec3 } from "../engine/engine_types.js";
+import { Model, Vec3 } from "../engine/engine_types.js";
 import { getParam, setParamWithoutReload } from "../engine/engine_utils.js";
 import { determineMimeTypeFromExtension } from "../engine/engine_utils_format.js";
-import { Animation } from "./Animation.js";
 import { Behaviour } from "./Component.js";
 import { EventList } from "./EventList.js";
+import { Renderer } from "./Renderer.js";
 
 /**
  * Debug mode can be enabled with the URL parameter `?debugdroplistener`, which
@@ -116,6 +115,8 @@ const blobKeyName = "blob";
  * If {@link useNetworking} is enabled, the DropListener will automatically synchronize dropped files to other connected clients.
  * Enable {@link fitIntoVolume} to automatically scale dropped objects to fit within the volume defined by {@link fitVolumeSize}.
  * 
+ * - Example: [DropListener Sample](https://droplistener-zubcksz1veaoo.needle.run/)
+ * 
  * The following events are dispatched by the DropListener:
  * - **object-added** - dispatched when a new object is added to the scene
  * - **file-dropped** - dispatched when a file is dropped into the scene
@@ -214,7 +215,14 @@ export class DropListener extends Behaviour {
     }
 
 
-
+    awake() {
+        for (const ch of this.gameObject.children) {
+            if (this.dropArea && ch.contains(this.dropArea)) {
+                continue;
+            }
+            this._addedObjects.push(ch);
+        }
+    }
 
     // #region internals
 
@@ -223,7 +231,15 @@ export class DropListener extends Behaviour {
         this.context.renderer.domElement.addEventListener("dragover", this.onDrag);
         this.context.renderer.domElement.addEventListener("drop", this.onDrop);
         window.addEventListener("paste", this.handlePaste);
-        this.context.connection.beginListen("droplistener", this.onNetworkEvent)
+        this.context.connection.beginListen("droplistener", this.onNetworkEvent);
+        if (isDevEnvironment()) {
+            if (this.dropArea) {
+                const anyRenderer = this.dropArea.getComponentInChildren(Renderer);
+                if (!anyRenderer) {
+                    console.warn("[DropListener] The assigned DropArea does not seem to have a renderer/mesh. Drag and Drop events will not be detected.");
+                }
+            }
+        }
     }
     /** @internal */
     onDisable(): void {
@@ -287,6 +303,7 @@ export class DropListener extends Behaviour {
      * @param evt The drag event
      */
     private onDrag = (evt: DragEvent) => {
+        if(debug) console.debug("DropListener Drag", evt, this.context.connection.allowEditing);
         if (this.context.connection.allowEditing === false) return;
         // necessary to get drop event
         evt.preventDefault();
@@ -298,9 +315,9 @@ export class DropListener extends Behaviour {
      * @param evt The drop event
      */
     private onDrop = async (evt: DragEvent) => {
+        if (debug) console.debug("DropListener Drop", evt, this.context.connection.allowEditing);
         if (this.context.connection.allowEditing === false) return;
 
-        if (debug) console.log(evt);
         if (!evt?.dataTransfer) return;
         // If the event is marked as handled for droplisteners then ignore it
         if (evt["droplistener:handled"]) return;
@@ -473,7 +490,7 @@ export class DropListener extends Behaviour {
         if (doDestroy) {
             for (const prev of this._addedObjects) {
                 if (prev.parent === this.gameObject) {
-                    destroy(prev, true, true);
+                    prev.destroy();
                 }
             }
         }
@@ -596,24 +613,28 @@ export class DropListener extends Behaviour {
      * @returns True if the drop is valid (either no drop area is set or the drop occurred inside it)
      */
     private testIfIsInDropArea(ctx: DropContext): boolean {
+        const screenPoint = this.context.input.convertScreenspaceToRaycastSpace(ctx.screenposition.clone());
+        const hits = this.context.physics.raycast({
+            screenPoint,
+            recursive: true,
+            testObject: obj => {
+                // Ignore hits on the already added objects, they don't count as part of the dropzone
+                if (this._addedObjects.some(o => o.contains(obj))) return false;
+                return true;
+            }
+        });
+        if (!hits.length) {
+            if (isDevEnvironment()) console.log(`Dropped outside of drop area for DropListener \"${this.name}\".`);
+            return false;
+        }
+
+        const hit = hits[0];
         if (this.dropArea) {
-            const screenPoint = this.context.input.convertScreenspaceToRaycastSpace(ctx.screenposition.clone());
-            const hits = this.context.physics.raycast({
-                targets: [this.dropArea],
-                screenPoint,
-                recursive: true,
-                testObject: obj => {
-                    // Ignore hits on the already added objects, they don't count as part of the dropzone
-                    if (this._addedObjects.includes(obj)) return false;
-                    return true;
-                }
-            });
-            if (!hits.length) {
-                if (isDevEnvironment()) console.log(`Dropped outside of drop area for DropListener \"${this.name}\".`);
-                return false;
+            if (this.dropArea.contains(hit.object)) {
+                return true;
             }
         }
-        return true;
+        return false;
     }
 
 }

package/src/engine-components/Duplicatable.ts

@@ -12,8 +12,8 @@ import { type IPointerEventHandler, PointerEventData } from "./ui/PointerEvents.
 import { ObjectRaycaster } from "./ui/Raycaster.js";
 
 /**
- * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the GameObject.  
- * It implements the {@link IPointerEventHandler} interface and can be used to expose duplication to the user in the editor without writing code.
+ * The Duplicatable component is used to duplicate a assigned {@link GameObject} when a pointer event occurs on the object.   
+ *  
  * @category Interactivity
  * @group Components
  */

package/src/engine-components/EventList.ts

@@ -97,7 +97,24 @@ export class EventListEvent<TArgs extends any> extends Event { //implements Arra
 
 
 /**
- * The EventList is a class that can be used to create a list of event listeners that can be invoked
+ * The EventList is a class that can be used to create a list of event listeners that can be invoked.  
+ * 
+ * @example
+ * ```ts
+ * // create an event list
+ * const onClick = new EventList<(event: MouseEvent) => void>();
+ * 
+ * // add an event listener
+ * onClick.addEventListener((event) => {
+ *   console.log("Clicked!", event);
+ * });
+ * 
+ * // invoke the event list
+ * onClick.invoke(new MouseEvent("click"));
+ * ```
+ * 
+ * @category Events
+ * @group Utilities
  */
 export class EventList<TArgs extends any = any> implements IEventList {
 

package/src/engine-components/GroundProjection.ts

@@ -10,7 +10,10 @@ import { Behaviour } from "./Component.js";
 const debug = getParam("debuggroundprojection");
 
 /**
- * GroundProjectedEnv creates a ground projection of the current environment map.  
+ * GroundProjectedEnv creates a ground projection of the current environment map.    
+ * 
+ * - Example https://engine.needle.tools/samples/ground-projection
+ * 
  * @category Rendering
  * @group Components
  */