@needle-tools/engine 4.16.1 → 4.16.2

package/plugins/vite/meta.js

@@ -6,11 +6,12 @@ import { getPosterPath } from './poster.js';
 import { needleGreenBold, needleLog } from './logging.js';
 
 /**
- * @param {string} command
- * @param {import('../types').needleMeta | null} config
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin}
  */
-export const needleMeta = (command, config, userSettings) => {
+export function needleMeta(command, config, userSettings) {
 
     // we can check if this is a build
     const isBuild = command === 'build';

package/plugins/vite/needle-app.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {'serve' | 'build'} command
+ * @param {{} | undefined | null} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin[] | null}
+ */
+export function needleApp(command: "serve" | "build", config: {} | undefined | null, userSettings: import("../types").userSettings): import("vite").Plugin[] | null;

package/plugins/vite/needle-app.js

@@ -10,7 +10,7 @@ import { needleLog } from './logging.js';
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin[] | null}
  */
-export const needleApp = (command, config, userSettings) => {
+export function needleApp(command, config, userSettings) {
 
     if (command !== "build") {
         return null;

package/plugins/vite/npm.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @param {import('../types').userSettings} userSettings
+ */
+export function needleNPM(command: any, config: any, userSettings: import("../types").userSettings): void;

package/plugins/vite/npm.js

@@ -3,6 +3,6 @@ import { ensureNpmDirectoryExists } from '../common/npm.js';
 /**
  * @param {import('../types').userSettings} userSettings
  */
-export const needleNPM = (command, config, userSettings) => {
+export function needleNPM(command, config, userSettings) {
     ensureNpmDirectoryExists();
 }

package/plugins/vite/peer.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import("vite").Plugin | undefined}
+ */
+export function needlePeerjs(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/peer.js

@@ -2,10 +2,12 @@ const peerjsString = `/* needle: fix for peerjs */ window.global = window; var p
 import { needleLog } from './logging.js';
 
 /**
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
  * @returns {import("vite").Plugin | undefined}
  */
-export const needlePeerjs = (command, config, userSettings) => {
+export function needlePeerjs(command, config, userSettings) {
 
     if (userSettings.noPeer === true) return;
 

package/plugins/vite/poster-client.d.ts

@@ -0,0 +1 @@
+export {};

package/plugins/vite/poster.d.ts

@@ -0,0 +1,8 @@
+export function getPosterPath(): string;
+/**
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
+ */
+export function needlePoster(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/poster.js

@@ -10,9 +10,12 @@ export function getPosterPath() {
 }
 
 /**
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
  */
-export const needlePoster = (command, config, userSettings) => {
+export function needlePoster(command, config, userSettings) {
     // only relevant for local development
     if (command === 'build') return [];
 
@@ -76,4 +79,4 @@ export const needlePoster = (command, config, userSettings) => {
             },
         },
     }
-};
+}

package/plugins/vite/pwa.d.ts

@@ -0,0 +1,7 @@
+/** Provides reasonable defaults for a PWA manifest and workbox settings.
+ * @param {"build" | "serve"} command
+ * @param {import("../types/needleConfig").needleMeta | null} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
+ */
+export function needlePWA(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/pwa.js

@@ -8,12 +8,12 @@ import { needleLog } from './logging.js';
 const pwaErrorWithInstructions = "It seems that you're trying to build a PWA using 'vite-plugin-pwa'!\nNeedle can manage PWA settings for you – just pass the same 'pwaOptions' to the needlePlugins and VitePWA plugins:\n\n1. Install the vite PWA plugin: npm install vite-plugin-pwa --save-dev\n\n2. Then update your vite.config.js:\n\n    import { VitePWA } from 'vite-plugin-pwa';\n    ...\n    needlePlugins(command, needleConfig, { pwa: pwaOptions }),\n    VitePWA(pwaOptions),\n\nIf you want to manage PWA building yourself and skip this check, please pass '{ pwa: false }' to needlePlugins.";
 
 /** Provides reasonable defaults for a PWA manifest and workbox settings.
- * @param {string} command
- * @param {import('../types').userSettings} userSettings
+ * @param {"build" | "serve"} command
  * @param {import("../types/needleConfig").needleMeta | null} config
- * @returns {import('vite').Plugin | void}
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
  */
-export const needlePWA = (command, config, userSettings) => {
+export function needlePWA(command, config, userSettings) {
     // @ts-ignore // TODO correctly type the userSettings.pwaOptions object
     /** @type {import("vite-plugin-pwa").VitePWAOptions | false} */
     const pwaOptions = userSettings.pwa === true

package/plugins/vite/reload-client.d.ts

@@ -0,0 +1 @@
+export {};

package/plugins/vite/reload.d.ts

@@ -0,0 +1,7 @@
+/**
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
+ */
+export function needleReload(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/reload.js

@@ -16,10 +16,11 @@ let assetsDirectory = "";
 
 /**
  * @param {"build" | "serve"} command
- * @param {import('../types').userSettings | null} config
+ * @param {import('../types/needleConfig').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
  */
-export const needleReload = (command, config, userSettings) => {
+export function needleReload(command, config, userSettings) {
     if (command === "build") return undefined;
 
     if (userSettings?.noReload === true) return undefined;
@@ -31,7 +32,7 @@ export const needleReload = (command, config, userSettings) => {
         isUpdatingConfig = true;
         const res = await loadConfig();
         isUpdatingConfig = false;
-        if (res) config = /** @type {import('../types').userSettings} */ (res);
+        if (res) config = /** @type {import('../types/needleConfig').needleMeta} */ (res);
     }
 
     const projectConfig = tryLoadProjectConfig();
@@ -61,7 +62,7 @@ export const needleReload = (command, config, userSettings) => {
             if (userSettings?.debug === true)
                 setTimeout(() => needleLog("needle-reload", "Updated server ignore patterns: " + JSON.stringify(config.server?.watch?.ignored)), 100);
         },
-        /** @param {{file: string, server: import('vite').ViteDevServer, modules: unknown[], read: (file?: string) => Promise<string>, buildDirectory?: string}} args */
+        /** @param {import('vite').HmrContext & {buildDirectory?: string}} args */
         handleHotUpdate(args) {
             args.buildDirectory = buildDirectory;
             return handleReload(args);
@@ -118,7 +119,7 @@ function notifyClientWillReload(server, file) {
 }
 
 /**
- * @param {{file: string, server: import('vite').ViteDevServer, modules: unknown[], read: (file?: string) => Promise<string>, buildDirectory?: string}} param0
+ * @param {import('vite').HmrContext & {buildDirectory?: string}} param0
  * @returns {Promise<any>}
  */
 async function handleReload({ file, server, modules: _modules, read, buildDirectory }) {
@@ -255,7 +256,7 @@ function getFileNameLog(file) {
 const hashes = new Map();
 const hash256 = crypto.createHash('sha256');
 
-/** @param {string} file @param {(file?: string) => Promise<string>} read @returns {Promise<boolean>} */
+/** @param {string} file @param {(file?: string) => string | Promise<string>} read @returns {Promise<boolean>} */
 async function testIfFileContentChanged(file, read) {
     let content = await read(file);
     content = removeVersionQueryArgument(content);

package/plugins/vite/server.d.ts

@@ -0,0 +1,7 @@
+/** Can open the network server in the browser.
+ * @param {"build" | "serve"} command
+ * @param {import('../types').needleMeta | null} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin}
+ */
+export function needleServer(command: "build" | "serve", config: import("../types").needleMeta | null, userSettings: import("../types").userSettings): import("vite").Plugin;

package/plugins/vite/server.js

@@ -1,10 +1,10 @@
-/**
- * Can open the network server in the browser
- * @param {string} command
+/** Can open the network server in the browser.
+ * @param {"build" | "serve"} command
  * @param {import('../types').needleMeta | null} config
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin}
  */
-export const needleServer = (command, config, userSettings) => {
+export function needleServer(command, config, userSettings) {
 
     const shouldOpenBrowser = userSettings.openBrowser === true;
 
@@ -64,4 +64,4 @@ export const needleServer = (command, config, userSettings) => {
             }
         },
     }
-};
+}

package/plugins/vite/transform-codegen.d.ts

@@ -0,0 +1,8 @@
+/** Modify the glb load path in codegen files.
+ * This is necessary if the assets directory is not the default (changed by the user in needle.config.json).
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} config
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
+ */
+export function needleTransformCodegen(command: "build" | "serve", config: import("../types/needleConfig").needleMeta | null | undefined, userSettings: import("../types").userSettings): import("vite").Plugin | undefined;

package/plugins/vite/transform-codegen.js

@@ -1,11 +1,13 @@
 import { builtAssetsDirectory, tryLoadProjectConfig } from './config.js';
 
-/** 
- * modify the glb load path in codegen files
- * this is necessary if the assets directory is not the default (changed by the user in needle.config.json)
+/** Modify the glb load path in codegen files.
+ * This is necessary if the assets directory is not the default (changed by the user in needle.config.json).
+ * @param {"build" | "serve"} command
+ * @param {import('../types/needleConfig').needleMeta | null | undefined} config
  * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin | undefined}
  */
-export const needleTransformCodegen = (command, config, userSettings) => {
+export function needleTransformCodegen(command, config, userSettings) {
 
     if (config?.noCodegenTransform === true || userSettings?.noCodegenTransform === true) {
         return;

package/plugins/vite/transform.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @param {import('../types').userSettings} userSettings
+ * @returns {import('vite').Plugin[]}
+ */
+export function needleTransformCode(command: any, config: any, userSettings: import("../types").userSettings): import("vite").Plugin[];

package/plugins/vite/transform.js

@@ -5,7 +5,7 @@
  * @param {import('../types').userSettings} userSettings
  * @returns {import('vite').Plugin[]}
  */
-export const needleTransformCode = (command, config, userSettings) => {
+export function needleTransformCode(command, config, userSettings) {
 
     return [
         {

package/plugins/vite/vite-4.4-hack.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Make sure we dont have vite 4.4.x installed when needle engine is used locally
+ * @param {import('../types').userSettings} userSettings
+ */
+export function vite_4_4_hack(command: any, config: any, userSettings: import("../types").userSettings): {
+    name: string;
+    configureServer(server: any): Promise<void>;
+};

package/plugins/vite/vite-4.4-hack.js

@@ -6,7 +6,7 @@ import { execSync } from 'child_process';
  * Make sure we dont have vite 4.4.x installed when needle engine is used locally
  * @param {import('../types').userSettings} userSettings
  */
-export const vite_4_4_hack = (command, config, userSettings) => {
+export function vite_4_4_hack(command, config, userSettings) {
     if (userSettings.vite44Hack === false) return;
     return {
         name: "needle-vite-4.4-hack",

package/src/engine-components/EventType.ts

@@ -8,16 +8,17 @@ export enum EventType {
     PointerDown = 2,
     PointerUp = 3,
     PointerClick = 4,
-    Drag = 5,
-    Drop = 6,
-    Scroll = 7,
-    UpdateSelected = 8,
-    Select = 9,
-    Deselect = 10,
-    Move = 11,
-    InitializePotentialDrag = 12,
-    BeginDrag = 13,
-    EndDrag = 14,
-    Submit = 15,
-    Cancel = 16
+    // Unity Events, not currently supported:
+    //Drag = 5,
+    //Drop = 6,
+    //Scroll = 7,
+    //UpdateSelected = 8,
+    //Select = 9,
+    //Deselect = 10,
+    //Move = 11,
+    //InitializePotentialDrag = 12,
+    //BeginDrag = 13,
+    //EndDrag = 14,
+    //Submit = 15,
+    //Cancel = 16
 }

package/src/engine-components/ReflectionProbe.ts

@@ -1,17 +1,21 @@
-import { CubeTexture, EquirectangularReflectionMapping, LinearSRGBColorSpace, Material, Object3D, Texture, Vector3 } from "three";
+import { Box3, Color, CubeTexture, EquirectangularReflectionMapping, LinearSRGBColorSpace, LineSegments, Material, Object3D, Quaternion, Texture, Vector3 } from "three";
 
+import { CreateWireCube } from "../engine/engine_gizmos.js";
 import { MaterialPropertyBlock } from "../engine/engine_materialpropertyblock.js";
 import { loadPMREM } from "../engine/engine_pmrem.js";
 import { serializable } from "../engine/engine_serialization.js";
 import { Context } from "../engine/engine_setup.js";
+import { getBoundingBox, getWorldPosition } from "../engine/engine_three_utils.js";
 import { getParam, resolveUrl } from "../engine/engine_utils.js";
-import { BoxHelperComponent } from "./BoxHelperComponent.js";
 import { Behaviour } from "./Component.js";
 import { EventList } from "./EventList.js";
 
 export const debug = getParam("debugreflectionprobe");
 const disable = getParam("noreflectionprobe");
 
+let box: Box3 | null = null;
+const _identityRotation = new Quaternion();
+
 const $reflectionProbeKey = Symbol("reflectionProbeKey");
 /**
  * The [ReflectionProbe](https://engine.needle.tools/docs/api/ReflectionProbe) provides environment reflection data to materials within its defined area.
@@ -40,10 +44,11 @@ const $reflectionProbeKey = Symbol("reflectionProbeKey");
 export class ReflectionProbe extends Behaviour {
 
     private static _probes: Map<Context, ReflectionProbe[]> = new Map();
-    
-    
+    private static testBox: Box3 = new Box3();
+
     /**
-     * Checks if the given material is currently using a reflection probe. This is determined by checking for an override on the material's "envMap" property, which is set by the Renderer component when applying a reflection probe.
+     * Checks if the given material is currently using a reflection probe.  
+     * This is determined by checking for an override on the material's "envMap" property, which is set by the Renderer component when applying a reflection probe.
      */
     static isUsingReflectionProbe(material: Material) {
         return !!(material as any)[$reflectionProbeKey];
@@ -101,14 +106,17 @@ export class ReflectionProbe extends Behaviour {
     private _textureUrlInFlight?: string;
 
     /**
-     * The cubemap or HDR texture used for reflections. Can be assigned directly or via a URL string. When assigning via URL, the texture will be loaded asynchronously and applied once ready.
+     * The cubemap or HDR texture used for reflections. Can be assigned directly or via a URL string.   
+     * When assigning via URL, the texture will be loaded asynchronously and applied once ready.
+     * @param tex The texture or URL to assign to this reflection probe
+     * @default null
      */
     @serializable([Texture, String])
     set texture(tex: Texture | null) {
         if (this._texture === tex) return;
 
         if (typeof tex === "string") {
-            if(debug) console.debug(`[ReflectionProbe] Loading reflection probe texture from URL: ${tex}`);
+            if (debug) console.debug(`[ReflectionProbe] Loading reflection probe texture from URL: ${tex}`);
             this._textureUrlInFlight = tex;
             const textureUrl = resolveUrl(this.sourceId, tex);
             loadPMREM(textureUrl, this.context.renderer).then(loaded => {
@@ -124,7 +132,7 @@ export class ReflectionProbe extends Behaviour {
         // During deserialization / loading of the GLB the deserializer sets an empty DataTexture 
         // But if the texture is serialized as a string (via Blender Reflection Probes) then the async loading above
         // Will abort IF textureInFlight is reset (here). That's why we do NOT reset textureInFlight during initialization (when __didAwake is false). Only after awake, when we are sure that the async loading is done, we reset the in-flight URL to allow new assignments.
-        if(this.__didAwake) this._textureUrlInFlight = undefined;
+        if (this.__didAwake) this._textureUrlInFlight = undefined;
 
         this._texture = tex;
 
@@ -144,30 +152,49 @@ export class ReflectionProbe extends Behaviour {
         return this._texture;
     }
 
+    /**
+     * The intensity of the reflection probe's influence.  
+     *  Higher values will make reflections brighter, while lower values will make them dimmer.  
+     * The default value is 1, which means the reflections will be applied at their original brightness. Adjust this value to achieve the desired look for your scene.
+     * @default 1
+     */
     @serializable()
     intensity: number = 1;
 
     /**
-     * Defines the center and size of the reflection probe's influence area.
+     * Defines the center of the reflection probe's influence area relative to the GameObject's position.   
+     * The probe will affect objects within a box defined by this center and the `size` property.  
+     * Note: The actual influence area is determined by both the `center` and `size` properties. The `center` defines the offset from the GameObject's position, while the `size` defines the dimensions of the box around that center. Objects within this box will be influenced by the reflection probe.
      */
     @serializable(Vector3)
-    center?: Vector3;
+    center: Vector3 = new Vector3();
 
     /**
-     * Defines the size of the reflection probe's influence area. Objects within this box will be affected by the probe's reflections.
+     * Defines the size of the reflection probe's influence area. Objects within this box will be affected by the probe's reflections.  
+     * Note: The actual influence area is determined by both the `center` and `size` properties. The `center` defines the offset from the GameObject's position, while the `size` defines the dimensions of the box around that center. Objects within this box will be influenced by the reflection probe.
      */
     @serializable(Vector3)
-    size?: Vector3;
+    size: Vector3 = new Vector3(1, 1, 1);
 
     /**
      * Workaround for lightmap. Compensates for the fact that lightmaps are pre-multiplied by intensity, while reflection probes are not. This means that if you use both lightmaps and reflection probes, you may need to adjust this value to get the correct balance between them. The default value of `Math.PI` is a good starting point for most cases, but you may need to tweak it based on your specific lighting setup and artistic needs.
      */
     __lightmapIntensityScale: boolean = true;
 
-    private _boxHelper?: BoxHelperComponent;
 
     private isInBox(obj: Object3D) {
-        return this._boxHelper?.isInBox(obj);
+
+        box ??= new Box3();
+        box!.setFromCenterAndSize(this.gameObject.worldPosition.add(this.center), this.gameObject.worldScale.multiply(this.size));
+
+        getBoundingBox([obj], undefined, undefined, ReflectionProbe.testBox);
+
+        if (ReflectionProbe.testBox.isEmpty()) {
+            return box.containsPoint(obj.worldPosition);
+        }
+        else {
+            return box?.intersectsBox(ReflectionProbe.testBox);
+        }
     }
 
     constructor() {
@@ -178,12 +205,15 @@ export class ReflectionProbe extends Behaviour {
         ReflectionProbe._probes.get(this.context)?.push(this);
     }
 
+    private _gizmo: LineSegments | null = null;
+    private _color: Color | null = null;
+
     /** @internal */
     awake() {
-        this._boxHelper = this.gameObject.addComponent(BoxHelperComponent) as BoxHelperComponent;
-        this._boxHelper.updateBox(true);
-        if (debug)
-            this._boxHelper.showHelper(0x555500, true);
+        if (debug) {
+            this._gizmo = CreateWireCube(0x555500);
+            this.gameObject.add(this._gizmo);
+        }
 
         if (this._texture) {
             this._texture.mapping = EquirectangularReflectionMapping;
@@ -192,6 +222,15 @@ export class ReflectionProbe extends Behaviour {
         }
     }
 
+    /** @internal */
+    update(): void {
+        if (this._gizmo) {
+            if (this.center) this._gizmo.position.copy(this.center);
+            if (this.size) this._gizmo.scale.copy(this.size);
+            this._gizmo.worldQuaternion = _identityRotation.identity();
+        }
+    }
+
     /** @internal */
     onEnable(): void {
         ReflectionProbe.onEnabled?.invoke(this);
@@ -221,7 +260,10 @@ export class ReflectionProbe extends Behaviour {
     }
 
     /**
-     * Applies this reflection probe to the given object by setting material property overrides for "envMap", "envMapRotation", and "envMapIntensity". This is typically called by the Renderer component when determining which reflection probe to use for a given object.
+     * Applies this reflection probe to the given object by setting material property overrides for "envMap", "envMapRotation", and "envMapIntensity".   
+     * This is typically called by the Renderer component when determining which reflection probe to use for a given object.
+     * @param object The object to apply the reflection probe to
+     * @see {@link unapply} for the corresponding method to remove the probe's influence from an object.
      */
     apply(object: Object3D) {
         if (disable) return;
@@ -240,7 +282,10 @@ export class ReflectionProbe extends Behaviour {
     }
 
     /**
-     * Removes the reflection probe overrides from the given object. This is typically called by the Renderer component when an object is no longer influenced by this probe or when the probe is disabled.
+     * Removes the reflection probe overrides from the given object.   
+     * This is typically called by the Renderer component when an object is no longer influenced by this probe or when the probe is disabled.
+     * @param object The object to remove the reflection probe overrides from
+     * @see {@link apply} for the corresponding method to apply the probe's influence to an object.
      */
     unapply(obj: Object3D) {
         const block = MaterialPropertyBlock.get(obj);

package/plugins/types/next.d.ts

@@ -1,3 +0,0 @@
-import { userSettings } from './userconfig.js';
-
-export declare function needleNext(nextConfig?: import('next').NextConfig, userSettings?: userSettings): Promise<import('next').NextConfig>;

package/plugins/types/vite.d.ts

@@ -1,14 +0,0 @@
-import { needleConfig, needleMeta } from "./needleConfig.d.ts";
-import { userSettings } from "./userconfig.d.ts";
-
-export declare function needlePlugins(command: import("vite").ConfigEnv["command"], meta?: needleMeta | null, userSettings?: userSettings): Promise<any>;
-
-/**
- * Loads the generated needle meta file
- */
-export declare function loadConfig(path: string | null = null): Promise<needleMeta | null>;
-
-/**
- * Returns true if the project is configured to use gzip compression
- */
-export declare function useGzip(config?: needleConfig): boolean;