@needle-tools/engine 4.4.1 → 4.4.2

package/lib/engine-components/ShadowCatcher.d.ts

@@ -1,33 +1,33 @@
-import { RGBAColor } from "../engine/js-extensions/index.js";
-import { Behaviour } from "./Component.js";
-/**
- * The mode of the ShadowCatcher.
- * - ShadowMask: only renders shadows.
- * - Additive: renders shadows additively.
- * - Occluder: occludes light.
- */
-declare enum ShadowMode {
-    ShadowMask = 0,
-    Additive = 1,
-    Occluder = 2
-}
-/**
- * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.
- * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.
- *
- * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
- * @category Rendering
- * @group Components
- */
-export declare class ShadowCatcher extends Behaviour {
-    mode: ShadowMode;
-    shadowColor: RGBAColor;
-    private targetMesh?;
-    /** @internal */
-    start(): void;
-    applyLightBlendMaterial(): void;
-    applyShadowMaterial(): void;
-    applyOccluderMaterial(): void;
-    private applyMaterialOptions;
-}
-export {};
+import { RGBAColor } from "../engine/js-extensions/index.js";
+import { Behaviour } from "./Component.js";
+/**
+ * The mode of the ShadowCatcher.
+ * - ShadowMask: only renders shadows.
+ * - Additive: renders shadows additively.
+ * - Occluder: occludes light.
+ */
+declare enum ShadowMode {
+    ShadowMask = 0,
+    Additive = 1,
+    Occluder = 2
+}
+/**
+ * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.
+ * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.
+ *
+ * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
+ * @category Rendering
+ * @group Components
+ */
+export declare class ShadowCatcher extends Behaviour {
+    mode: ShadowMode;
+    shadowColor: RGBAColor;
+    private targetMesh?;
+    /** @internal */
+    start(): void;
+    applyLightBlendMaterial(): void;
+    applyShadowMaterial(): void;
+    applyOccluderMaterial(): void;
+    private applyMaterialOptions;
+}
+export {};

package/lib/engine-components/ShadowCatcher.js

@@ -1,167 +1,167 @@
-var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
-    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-    return c > 3 && r && Object.defineProperty(target, key, r), r;
-};
-import { AdditiveBlending, Mesh, MeshBasicMaterial, MeshStandardMaterial, ShadowMaterial } from "three";
-import { ObjectUtils, PrimitiveType } from "../engine/engine_create_objects.js";
-import { serializable } from "../engine/engine_serialization_decorator.js";
-import { RGBAColor } from "../engine/js-extensions/index.js";
-import { Behaviour } from "./Component.js";
-/**
- * The mode of the ShadowCatcher.
- * - ShadowMask: only renders shadows.
- * - Additive: renders shadows additively.
- * - Occluder: occludes light.
- */
-var ShadowMode;
-(function (ShadowMode) {
-    ShadowMode[ShadowMode["ShadowMask"] = 0] = "ShadowMask";
-    ShadowMode[ShadowMode["Additive"] = 1] = "Additive";
-    ShadowMode[ShadowMode["Occluder"] = 2] = "Occluder";
-})(ShadowMode || (ShadowMode = {}));
-/**
- * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.
- * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.
- *
- * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
- * @category Rendering
- * @group Components
- */
-export class ShadowCatcher extends Behaviour {
-    //@type Needle.Engine.ShadowCatcher.Mode
-    mode = ShadowMode.ShadowMask;
-    //@type UnityEngine.Color
-    shadowColor = new RGBAColor(0, 0, 0, 1);
-    targetMesh;
-    /** @internal */
-    start() {
-        // if there's no geometry, make a basic quad
-        if (!(this.gameObject instanceof Mesh)) {
-            const quad = ObjectUtils.createPrimitive(PrimitiveType.Quad, {
-                name: "ShadowCatcher",
-                material: new MeshStandardMaterial({
-                    // HACK heuristic to get approx. the same colors out as with the current default ShadowCatcher material
-                    // not clear why this is needed; assumption is that the Renderer component does something we're not respecting here
-                    color: 0x999999,
-                    roughness: 1,
-                    metalness: 0,
-                    transparent: true,
-                })
-            });
-            quad.receiveShadow = true;
-            quad.geometry.rotateX(-Math.PI / 2);
-            // TODO breaks shadow catching right now
-            // const renderer  = new Renderer();
-            // renderer.receiveShadows = true;
-            // GameObject.addComponent(quad, Renderer);
-            this.gameObject.add(quad);
-            this.targetMesh = quad;
-        }
-        else if (this.gameObject instanceof Mesh && this.gameObject.material) {
-            // make sure we have a unique material to work with
-            this.gameObject.material = this.gameObject.material.clone();
-            this.targetMesh = this.gameObject;
-            // make sure the mesh can receive shadows
-            this.targetMesh.receiveShadow = true;
-        }
-        if (!this.targetMesh) {
-            console.warn("ShadowCatcher: no mesh to apply shadow catching to. Groups are currently not supported.");
-            return;
-        }
-        // Shadowcatcher mesh isnt raycastable
-        this.targetMesh.layers.set(2);
-        switch (this.mode) {
-            case ShadowMode.ShadowMask:
-                this.applyShadowMaterial();
-                break;
-            case ShadowMode.Additive:
-                this.applyLightBlendMaterial();
-                break;
-            case ShadowMode.Occluder:
-                this.applyOccluderMaterial();
-                break;
-        }
-    }
-    // Custom blending, diffuse-only lighting blended onto the scene additively.
-    // Works great for Point Lights and spot lights, 
-    // doesn't work for directional lights (since they're lighting up everything else).
-    // Works even better with an additional black-ish gradient to darken parts of the AR scene
-    // so that lights become more visible on bright surfaces.
-    applyLightBlendMaterial() {
-        if (!this.targetMesh)
-            return;
-        const material = this.targetMesh.material;
-        material.blending = AdditiveBlending;
-        this.applyMaterialOptions(material);
-        material.onBeforeCompile = (shader) => {
-            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderLib/meshphysical.glsl.js#L181
-            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderLib.js#LL284C11-L284C11
-            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderLib/shadow.glsl.js#L40
-            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderChunk/shadowmask_pars_fragment.glsl.js#L2
-            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderChunk/shadowmap_pars_fragment.glsl.js#L281
-            shader.fragmentShader = shader.fragmentShader.replace("vec3 outgoingLight = totalDiffuse + totalSpecular + totalEmissiveRadiance;", `vec3 outgoingLight = totalDiffuse + totalSpecular + totalEmissiveRadiance;
-            // diffuse-only lighting with overdrive to somewhat compensate
-            // for the loss of indirect lighting and to make it more visible.
-            vec3 direct = (reflectedLight.directDiffuse + reflectedLight.directSpecular) * 6.6;
-            float max = max(direct.r, max(direct.g, direct.b));
-            
-            // early out - we're simply returning direct lighting and some alpha based on it so it can 
-            // be blended onto the scene.
-            gl_FragColor = vec4(direct, max);
-            return;
-            `);
-        };
-        material.userData.isLightBlendMaterial = true;
-    }
-    // ShadowMaterial: only does a mask; shadowed areas are fully black.
-    // doesn't take light attenuation into account.
-    // works great for Directional Lights.
-    applyShadowMaterial() {
-        if (this.targetMesh) {
-            if (this.targetMesh.material.type !== "ShadowMaterial") {
-                const material = new ShadowMaterial();
-                material.color = this.shadowColor;
-                material.opacity = this.shadowColor.alpha;
-                this.applyMaterialOptions(material);
-                this.targetMesh.material = material;
-                material.userData.isShadowCatcherMaterial = true;
-            }
-            else {
-                const material = this.targetMesh.material;
-                material.color = this.shadowColor;
-                material.opacity = this.shadowColor.alpha;
-                this.applyMaterialOptions(material);
-                material.userData.isShadowCatcherMaterial = true;
-            }
-        }
-    }
-    applyOccluderMaterial() {
-        if (this.targetMesh) {
-            let material = this.targetMesh.material;
-            if (!material) {
-                const mat = new MeshBasicMaterial();
-                this.targetMesh.material = mat;
-                material = mat;
-            }
-            material.depthWrite = true;
-            material.stencilWrite = true;
-            material.colorWrite = false;
-            this.gameObject.renderOrder = -100;
-        }
-    }
-    applyMaterialOptions(material) {
-        if (material) {
-            material.depthWrite = false;
-            material.stencilWrite = false;
-        }
-    }
-}
-__decorate([
-    serializable()
-], ShadowCatcher.prototype, "mode", void 0);
-__decorate([
-    serializable(RGBAColor)
-], ShadowCatcher.prototype, "shadowColor", void 0);
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { AdditiveBlending, Mesh, MeshBasicMaterial, MeshStandardMaterial, ShadowMaterial } from "three";
+import { ObjectUtils, PrimitiveType } from "../engine/engine_create_objects.js";
+import { serializable } from "../engine/engine_serialization_decorator.js";
+import { RGBAColor } from "../engine/js-extensions/index.js";
+import { Behaviour } from "./Component.js";
+/**
+ * The mode of the ShadowCatcher.
+ * - ShadowMask: only renders shadows.
+ * - Additive: renders shadows additively.
+ * - Occluder: occludes light.
+ */
+var ShadowMode;
+(function (ShadowMode) {
+    ShadowMode[ShadowMode["ShadowMask"] = 0] = "ShadowMask";
+    ShadowMode[ShadowMode["Additive"] = 1] = "Additive";
+    ShadowMode[ShadowMode["Occluder"] = 2] = "Occluder";
+})(ShadowMode || (ShadowMode = {}));
+/**
+ * ShadowCatcher can be added to an Object3D to make it render shadows (or light) in the scene. It can also be used to create a shadow mask, or to occlude light.
+ * If the GameObject is a Mesh, it will apply a shadow-catching material to it - otherwise it will create a quad with the shadow-catching material.
+ *
+ * Note that ShadowCatcher meshes are not raycastable by default; if you want them to be raycastable, change the layers in `onEnable()`.
+ * @category Rendering
+ * @group Components
+ */
+export class ShadowCatcher extends Behaviour {
+    //@type Needle.Engine.ShadowCatcher.Mode
+    mode = ShadowMode.ShadowMask;
+    //@type UnityEngine.Color
+    shadowColor = new RGBAColor(0, 0, 0, 1);
+    targetMesh;
+    /** @internal */
+    start() {
+        // if there's no geometry, make a basic quad
+        if (!(this.gameObject instanceof Mesh)) {
+            const quad = ObjectUtils.createPrimitive(PrimitiveType.Quad, {
+                name: "ShadowCatcher",
+                material: new MeshStandardMaterial({
+                    // HACK heuristic to get approx. the same colors out as with the current default ShadowCatcher material
+                    // not clear why this is needed; assumption is that the Renderer component does something we're not respecting here
+                    color: 0x999999,
+                    roughness: 1,
+                    metalness: 0,
+                    transparent: true,
+                })
+            });
+            quad.receiveShadow = true;
+            quad.geometry.rotateX(-Math.PI / 2);
+            // TODO breaks shadow catching right now
+            // const renderer  = new Renderer();
+            // renderer.receiveShadows = true;
+            // GameObject.addComponent(quad, Renderer);
+            this.gameObject.add(quad);
+            this.targetMesh = quad;
+        }
+        else if (this.gameObject instanceof Mesh && this.gameObject.material) {
+            // make sure we have a unique material to work with
+            this.gameObject.material = this.gameObject.material.clone();
+            this.targetMesh = this.gameObject;
+            // make sure the mesh can receive shadows
+            this.targetMesh.receiveShadow = true;
+        }
+        if (!this.targetMesh) {
+            console.warn("ShadowCatcher: no mesh to apply shadow catching to. Groups are currently not supported.");
+            return;
+        }
+        // Shadowcatcher mesh isnt raycastable
+        this.targetMesh.layers.set(2);
+        switch (this.mode) {
+            case ShadowMode.ShadowMask:
+                this.applyShadowMaterial();
+                break;
+            case ShadowMode.Additive:
+                this.applyLightBlendMaterial();
+                break;
+            case ShadowMode.Occluder:
+                this.applyOccluderMaterial();
+                break;
+        }
+    }
+    // Custom blending, diffuse-only lighting blended onto the scene additively.
+    // Works great for Point Lights and spot lights, 
+    // doesn't work for directional lights (since they're lighting up everything else).
+    // Works even better with an additional black-ish gradient to darken parts of the AR scene
+    // so that lights become more visible on bright surfaces.
+    applyLightBlendMaterial() {
+        if (!this.targetMesh)
+            return;
+        const material = this.targetMesh.material;
+        material.blending = AdditiveBlending;
+        this.applyMaterialOptions(material);
+        material.onBeforeCompile = (shader) => {
+            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderLib/meshphysical.glsl.js#L181
+            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderLib.js#LL284C11-L284C11
+            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderLib/shadow.glsl.js#L40
+            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderChunk/shadowmask_pars_fragment.glsl.js#L2
+            // see https://github.com/mrdoob/three.js/blob/dev/src/renderers/shaders/ShaderChunk/shadowmap_pars_fragment.glsl.js#L281
+            shader.fragmentShader = shader.fragmentShader.replace("vec3 outgoingLight = totalDiffuse + totalSpecular + totalEmissiveRadiance;", `vec3 outgoingLight = totalDiffuse + totalSpecular + totalEmissiveRadiance;
+            // diffuse-only lighting with overdrive to somewhat compensate
+            // for the loss of indirect lighting and to make it more visible.
+            vec3 direct = (reflectedLight.directDiffuse + reflectedLight.directSpecular) * 6.6;
+            float max = max(direct.r, max(direct.g, direct.b));
+            
+            // early out - we're simply returning direct lighting and some alpha based on it so it can 
+            // be blended onto the scene.
+            gl_FragColor = vec4(direct, max);
+            return;
+            `);
+        };
+        material.userData.isLightBlendMaterial = true;
+    }
+    // ShadowMaterial: only does a mask; shadowed areas are fully black.
+    // doesn't take light attenuation into account.
+    // works great for Directional Lights.
+    applyShadowMaterial() {
+        if (this.targetMesh) {
+            if (this.targetMesh.material.type !== "ShadowMaterial") {
+                const material = new ShadowMaterial();
+                material.color = this.shadowColor;
+                material.opacity = this.shadowColor.alpha;
+                this.applyMaterialOptions(material);
+                this.targetMesh.material = material;
+                material.userData.isShadowCatcherMaterial = true;
+            }
+            else {
+                const material = this.targetMesh.material;
+                material.color = this.shadowColor;
+                material.opacity = this.shadowColor.alpha;
+                this.applyMaterialOptions(material);
+                material.userData.isShadowCatcherMaterial = true;
+            }
+        }
+    }
+    applyOccluderMaterial() {
+        if (this.targetMesh) {
+            let material = this.targetMesh.material;
+            if (!material) {
+                const mat = new MeshBasicMaterial();
+                this.targetMesh.material = mat;
+                material = mat;
+            }
+            material.depthWrite = true;
+            material.stencilWrite = true;
+            material.colorWrite = false;
+            this.gameObject.renderOrder = -100;
+        }
+    }
+    applyMaterialOptions(material) {
+        if (material) {
+            material.depthWrite = false;
+            material.stencilWrite = false;
+        }
+    }
+}
+__decorate([
+    serializable()
+], ShadowCatcher.prototype, "mode", void 0);
+__decorate([
+    serializable(RGBAColor)
+], ShadowCatcher.prototype, "shadowColor", void 0);
 //# sourceMappingURL=ShadowCatcher.js.map

package/lib/engine-components/Skybox.d.ts

@@ -1,82 +1,82 @@
-import { Behaviour } from "./Component.js";
-/**
- * RemoteSkybox is a component that allows you to set the skybox of a scene from a URL or a local file.
- * It supports .hdr, .exr, .jpg, .png files.
- *
- * ### Events
- * - `dropped-unknown-url`: Emitted when a file is dropped on the scene. The event detail contains the sender, the url and a function to apply the url.
- *
- * @example adding a skybox
- * ```ts
- * GameObject.addComponent(gameObject, Skybox, { url: "https://example.com/skybox.hdr", background: true, environment: true });
- * ```
- *
- * @example handle custom url
- * ```ts
- * const skybox = GameObject.addComponent(gameObject, Skybox);
- * skybox.addEventListener("dropped-unknown-url", (evt) => {
- *    let url = evt.detail.url;
- *    console.log("User dropped file", url);
- *    // change url or resolve it differently
- *    url = "https://example.com/skybox.hdr";
- *    // apply the url
- *    evt.detail.apply(url);
- * });
- * ```
- */
-export declare class RemoteSkybox extends Behaviour {
-    /**
-     * URL to a remote skybox. This value can also use a magic skybox name. Options are "quicklook", "quicklook-ar", "studio", "blurred-skybox".
-     * @example
-     * ```ts
-     * skybox.url = "https://example.com/skybox.hdr";
-     * ```
-     */
-    url?: string;
-    /**
-     * When enabled a user can drop a link to a skybox image on the scene to set the skybox.
-     * @default true
-     */
-    allowDrop: boolean;
-    /**
-     * When enabled the skybox will be set as the background of the scene.
-     * @default true
-     */
-    background: boolean;
-    /**
-     * When enabled the skybox will be set as the environment of the scene (to be used as environment map for reflections and lighting)
-     * @default true
-     */
-    environment: boolean;
-    /**
-     * When enabled dropped skybox urls (or assigned skybox urls) will be networked to other users in the same networked room.
-     * @default true
-     */
-    allowNetworking: boolean;
-    private _loader?;
-    private _prevUrl?;
-    private _prevLoadedEnvironment?;
-    private _prevEnvironment;
-    private _prevBackground;
-    /** @internal */
-    onEnable(): void;
-    /** @internal */
-    onDisable(): void;
-    private urlChangedSyncField;
-    /**
-     * Set the skybox from a given url
-     * @param url The url of the skybox image
-     * @param name Define name of the file with extension if it isn't apart of the url
-     * @returns Whether the skybox was successfully set
-     */
-    setSkybox(url: string | undefined | null, name?: string): Promise<boolean>;
-    private loadTexture;
-    private applySkybox;
-    private readonly validTextureTypes;
-    private isRemoteTexture;
-    private isValidTextureType;
-    private registerDropEvents;
-    private unregisterDropEvents;
-    private onDragOverEvent;
-    private onDrop;
-}
+import { Behaviour } from "./Component.js";
+/**
+ * RemoteSkybox is a component that allows you to set the skybox of a scene from a URL or a local file.
+ * It supports .hdr, .exr, .jpg, .png files.
+ *
+ * ### Events
+ * - `dropped-unknown-url`: Emitted when a file is dropped on the scene. The event detail contains the sender, the url and a function to apply the url.
+ *
+ * @example adding a skybox
+ * ```ts
+ * GameObject.addComponent(gameObject, Skybox, { url: "https://example.com/skybox.hdr", background: true, environment: true });
+ * ```
+ *
+ * @example handle custom url
+ * ```ts
+ * const skybox = GameObject.addComponent(gameObject, Skybox);
+ * skybox.addEventListener("dropped-unknown-url", (evt) => {
+ *    let url = evt.detail.url;
+ *    console.log("User dropped file", url);
+ *    // change url or resolve it differently
+ *    url = "https://example.com/skybox.hdr";
+ *    // apply the url
+ *    evt.detail.apply(url);
+ * });
+ * ```
+ */
+export declare class RemoteSkybox extends Behaviour {
+    /**
+     * URL to a remote skybox. This value can also use a magic skybox name. Options are "quicklook", "quicklook-ar", "studio", "blurred-skybox".
+     * @example
+     * ```ts
+     * skybox.url = "https://example.com/skybox.hdr";
+     * ```
+     */
+    url?: string;
+    /**
+     * When enabled a user can drop a link to a skybox image on the scene to set the skybox.
+     * @default true
+     */
+    allowDrop: boolean;
+    /**
+     * When enabled the skybox will be set as the background of the scene.
+     * @default true
+     */
+    background: boolean;
+    /**
+     * When enabled the skybox will be set as the environment of the scene (to be used as environment map for reflections and lighting)
+     * @default true
+     */
+    environment: boolean;
+    /**
+     * When enabled dropped skybox urls (or assigned skybox urls) will be networked to other users in the same networked room.
+     * @default true
+     */
+    allowNetworking: boolean;
+    private _loader?;
+    private _prevUrl?;
+    private _prevLoadedEnvironment?;
+    private _prevEnvironment;
+    private _prevBackground;
+    /** @internal */
+    onEnable(): void;
+    /** @internal */
+    onDisable(): void;
+    private urlChangedSyncField;
+    /**
+     * Set the skybox from a given url
+     * @param url The url of the skybox image
+     * @param name Define name of the file with extension if it isn't apart of the url
+     * @returns Whether the skybox was successfully set
+     */
+    setSkybox(url: string | undefined | null, name?: string): Promise<boolean>;
+    private loadTexture;
+    private applySkybox;
+    private readonly validTextureTypes;
+    private isRemoteTexture;
+    private isValidTextureType;
+    private registerDropEvents;
+    private unregisterDropEvents;
+    private onDragOverEvent;
+    private onDrop;
+}