@needle-tools/engine 5.1.0-alpha.5 → 5.1.0-alpha.6

package/src/engine/webcomponents/needle-engine.loading.ts

@@ -1,6 +1,6 @@
 import { needleLogoOnlySVG } from "../assets/index.js"
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
-import { hasCommercialLicense, hasProLicense, runtimeLicenseCheckPromise } from "../engine_license.js";
+import { LynjGsV, _cxKhKwDL, _$oYJ } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { LoadingProgressArgs } from "../engine_setup.js";
 import { getParam } from "../engine_utils.js";
@@ -205,7 +205,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
         }
 
 
-        const hasLicense = hasProLicense();
+        const hasLicense = _cxKhKwDL();
         if (!existing) {
             this._loadingElement.style.position = "absolute";
             this._loadingElement.style.width = "100%";
@@ -373,7 +373,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
 
     // private async handleRuntimeLicense(loadingElement: HTMLElement) {
     //     // First check if we have a commercial license
-    //     let commercialLicense = hasCommercialLicense();
+    //     let commercialLicense = LynjGsV();
     //     // if it's the case then we don't need to perform a runtime check
     //     if (commercialLicense) return;
 
@@ -393,10 +393,10 @@ export class EngineLoadingView implements ILoadingViewHandler {
     //     loadingElement.appendChild(nonCommercialContainer);
 
     //     // Use the runtime license check
-    //     if (!isDevEnvironment() && runtimeLicenseCheckPromise) {
+    //     if (!isDevEnvironment() && _$oYJ) {
     //         if (debugLicense) console.log("Waiting for runtime license check");
-    //         await runtimeLicenseCheckPromise;
-    //         commercialLicense = hasCommercialLicense();
+    //         await _$oYJ;
+    //         commercialLicense = LynjGsV();
     //     }
     //     if (commercialLicense) return;
     //     nonCommercialContainer.style.transition = "opacity .5s ease-in-out";

package/src/engine/webcomponents/needle-engine.ts

@@ -1,7 +1,7 @@
 import { isDevEnvironment, showBalloonWarning } from "../debug/index.js";
 import { PUBLIC_KEY, VERSION } from "../engine_constants.js";
 import { ContextEvent, ContextRegistry } from "../engine_context_registry.js";
-import { hasCommercialLicense } from "../engine_license.js";
+import { LynjGsV } from "../engine_license.js";
 import { onStart } from "../engine_lifecycle_api.js";
 import { setDracoDecoderPath, setDracoDecoderType, setKtx2TranscoderPath } from "../engine_loaders.gltf.js";
 import { Context, ContextCreateArgs } from "../engine_setup.js";
@@ -546,7 +546,7 @@ export class NeedleEngineWebComponent extends HTMLElementBase implements INeedle
 
 
         // Loading start events
-        const allowOverridingDefaultLoading = hasCommercialLicense();
+        const allowOverridingDefaultLoading = LynjGsV();
         // default loading can be overriden by calling preventDefault in the onload start event
         this.ensureLoadStartIsRegistered();
         let useDefaultLoading = this.dispatchEvent(new CustomEvent("loadstart", {

package/src/engine/xr/TempXRContext.ts

@@ -3,7 +3,7 @@ import { ArrayCamera, AxesHelper, Camera, Color, DirectionalLight, Fog, GridHelp
 import { needleLogoOnlySVG } from "../assets/index.js";
 import { isDevEnvironment } from "../debug/index.js";
 import { ObjectUtils, PrimitiveType } from "../engine_create_objects.js";
-import { hasCommercialLicense } from "../engine_license.js";
+import { LynjGsV } from "../engine_license.js";
 import { Mathf } from "../engine_math.js";
 import { delay, DeviceUtilities } from "../engine_utils.js";
 
@@ -215,7 +215,7 @@ export class TemporaryXRContext {
         this._scene.background = new Color(0x000000);
 
         let logoSrc = needleLogoOnlySVG;
-        if (hasCommercialLicense()) {
+        if (LynjGsV()) {
             const htmlComponent = document.querySelector("needle-engine");
             if (htmlComponent) {
                 const licenseLogo = htmlComponent.getAttribute("logo-src");

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

@@ -3,7 +3,7 @@ import { Euler, Material, Matrix4, Mesh, Object3D, Quaternion, Vector3 } from "t
 
 import { isDevEnvironment, showBalloonMessage, showBalloonWarning } from "../../../engine/debug/index.js";
 import { findObjectOfType } from "../../../engine/engine_components.js";
-import { hasProLicense } from "../../../engine/engine_license.js";
+import { _cxKhKwDL } from "../../../engine/engine_license.js";
 import { serializable } from "../../../engine/engine_serialization.js";
 import { getFormattedDate, Progress } from "../../../engine/engine_time_utils.js";
 import { DeviceUtilities, getParam } from "../../../engine/engine_utils.js";
@@ -277,7 +277,7 @@ export class USDZExporter extends Behaviour {
         let name = this.exportFileName ?? this.objectToExport?.name ?? this.name;
         name += "-" + getFormattedDate(); // seems iOS caches the file in some cases, this ensures we always have a fresh file
 
-        if (!hasProLicense()) {
+        if (!_cxKhKwDL()) {
             if (name !== "") name += "-";
             name += "MadeWithNeedle";
         }
@@ -682,7 +682,7 @@ export class USDZExporter extends Behaviour {
                     if (debug)
                         showBalloonMessage("Quicklook url: " + callToActionURL);
                     if (callToActionURL) {
-                        if (!hasProLicense()) {
+                        if (!_cxKhKwDL()) {
                             console.warn("Quicklook closed: custom redirects require a Needle Engine Pro license: https://needle.tools/pricing", callToActionURL)
                         }
                         else {
@@ -697,7 +697,7 @@ export class USDZExporter extends Behaviour {
     private buildQuicklookOverlay(): CustomBranding {
         const obj: CustomBranding = {};
         if (this.customBranding) Object.assign(obj, this.customBranding);
-        if (!hasProLicense()) {
+        if (!_cxKhKwDL()) {
             console.log("Custom Quicklook banner text requires pro license: https://needle.tools/pricing");
             obj.callToAction = "Close";
             obj.checkoutTitle = "🌵 Made with Needle";

package/src/engine-components/webxr/WebXRImageTracking.ts

@@ -12,6 +12,7 @@ import { IUSDExporterExtension } from "../../engine-components/export/usdz/Exten
 import { imageToCanvas, USDObject, USDWriter, USDZExporterContext } from "../../engine-components/export/usdz/ThreeUSDZExporter.js";
 import { USDZExporter } from "../../engine-components/export/usdz/USDZExporter.js";
 import { Behaviour, GameObject } from "../Component.js";
+import { EventList } from "../EventList.js";
 import { Renderer } from "../Renderer.js";
 
 // https://github.com/immersive-web/marker-tracking/blob/main/explainer.md
@@ -41,8 +42,41 @@ export class WebXRTrackedImage {
     get widthInMeters() { return this._trackedImage.widthInMeters ?? undefined; }
     /** The ImageBitmap used for tracking */
     get bitmap(): ImageBitmap { return this._bitmap; }
-    /** The {@link WebXRImageTrackingModel} configuration for this tracked image */
+    /**
+     * The {@link WebXRImageTrackingModel} configuration for this tracked image.
+     * Use this to access the assigned 3D object, marker settings, and other image tracking configuration.
+     * Available on each {@link WebXRTrackedImage} received from the `image-tracking` {@link CustomEvent} (`event.detail`).
+     * @example
+     * ```ts
+     * tracker.addEventListener("image-tracking", event => {
+     *   for (const img of event.detail.trackedImages) {
+     *     const model = img.model;
+     *     // Access the assigned 3D object
+     *     const obj = model.object;
+     *     // Access other settings
+     *     console.log(model.widthInMeters, model.hideWhenTrackingIsLost);
+     *   }
+     * });
+     * ```
+     */
     get model(): WebXRImageTrackingModel { return this._trackedImage; }
+
+    /**
+     * The 3D object or prefab assigned to this tracked image marker in the {@link WebXRImageTrackingModel}.
+     * Use this to access the object associated with an AR image tracking marker from the `image-tracking` {@link CustomEvent}.
+     * Shorthand for `this.model.object`.
+     * @example
+     * ```ts
+     * tracker.addEventListener("image-tracking", event => {
+     *   for (const img of event.detail.trackedImages) {
+     *     const obj = img.trackedModel;
+     *     // verbose alternative: img.model.object
+     *   }
+     * });
+     * ```
+     */
+    get trackedModel(): AssetReference | undefined { return this._trackedImage.object; }
+
     /**
      * The measured size of the detected image in the real world.
      * May differ from `widthInMeters` if the physical marker doesn't match the configured size.
@@ -133,11 +167,6 @@ export class WebXRTrackedImage {
 
 }
 
-/**
- * Event callback type for image tracking updates.
- * @param images Array of currently tracked images
- */
-declare type WebXRImageTrackingEvent = (images: WebXRImageTrackingEvent[]) => void;
 
 /**
  * Initial state of tracked image objects before entering an XR session.
@@ -293,6 +322,17 @@ export class WebXRImageTrackingModel {
     }
 }
 
+/** Data passed to image tracking event listeners. */
+export interface WebXRImageTrackingEvent {
+    /** The images currently being tracked this frame. */
+    readonly trackedImages: readonly WebXRTrackedImage[];
+}
+
+/** Event map for {@link WebXRImageTracking} events. Use with `addEventListener` for typed event handling. */
+export interface WebXRImageTrackingEventMap {
+    /** Dispatched every frame when images are being tracked. The event detail contains the tracking data for the current frame. */
+    "image-tracking": CustomEvent<WebXRImageTrackingEvent>;
+}
 
 // #region USDZ Extension
 class ImageTrackingExtension implements IUSDExporterExtension {
@@ -515,6 +555,34 @@ class ImageTrackingExtension implements IUSDExporterExtension {
  */
 export class WebXRImageTracking extends Behaviour {
 
+    /**
+     * Event invoked every frame when images are being tracked.
+     * @example
+     * ```ts
+     * const tracker = this.gameObject.getComponent(WebXRImageTracking);
+     * tracker?.imageTracked.addEventListener(evt => {
+     *   for (const img of evt.trackedImages) {
+     *     console.log(img.url, img.state);
+     *   }
+     * });
+     * ```
+     */
+    imageTracked: EventList<WebXRImageTrackingEvent> = new EventList();
+
+    /** @inheritdoc */
+    addEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+    addEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
+    addEventListener(type: string, listener: (evt: any) => any): void {
+        super.addEventListener(type, listener);
+    }
+
+    /** @inheritdoc */
+    removeEventListener<K extends keyof WebXRImageTrackingEventMap>(type: K, listener: (evt: WebXRImageTrackingEventMap[K]) => any): void;
+    removeEventListener<T extends Event>(type: string, listener: (evt: T) => any): void;
+    removeEventListener(type: string, listener: (evt: any) => any): void {
+        super.removeEventListener(type, listener);
+    }
+
     /**
      * Set which marker should be primary (first in the list).
      * Useful when deploying to QuickLook mode where one marker is tracked at a time.
@@ -763,7 +831,9 @@ export class WebXRImageTracking extends Behaviour {
                     }
                     if (this.currentImages.length > 0) {
                         try {
-                            this.dispatchEvent(new CustomEvent("image-tracking", { detail: this.currentImages }));
+                            const eventData: WebXRImageTrackingEvent = { trackedImages: this.currentImages };
+                            this.dispatchEvent(new CustomEvent("image-tracking", { detail: eventData }));
+                            this.imageTracked.invoke(eventData);
                             this.onImageTrackingUpdate(this.currentImages);
                         }
                         catch (e) {

package/src/vite-env.d.ts

@@ -1,16 +0,0 @@
-// Vite global defines — see plugins/vite/defines.js
-// declare const entries here are picked up globally (ambient, no import/export).
-// Vite sets these as globals in dev and statically replaces them at build time.
-// Webpack DefinePlugin replaces them at build time too.
-// The globalThis fallbacks for vanilla JS are in engine_constants.ts.
-
-declare const NEEDLE_ENGINE_VERSION: string;
-declare const NEEDLE_ENGINE_GENERATOR: string;
-declare const NEEDLE_PROJECT_BUILD_TIME: string;
-declare const NEEDLE_PUBLIC_KEY: string;
-
-// #region treeshake flags
-// declare var (not const) so globalThis["NEEDLE_USE_*"] access is also type-safe
-declare var NEEDLE_USE_RAPIER: boolean;
-declare var NEEDLE_USE_POSTPROCESSING: boolean;
-// #endregion treeshake flags