@needle-tools/engine 4.13.1 → 4.14.0-beta

package/lib/engine/engine_lightdata.js.map

@@ -1 +1 @@
-{"version":3,"file":"engine_lightdata.js","sourceRoot":"","sources":["../../src/engine/engine_lightdata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAW,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAEnE,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE,MAAM,aAAa,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAWhE,gEAAgE;AAChE,sEAAsE;AACtE,gFAAgF;AAEhF,+DAA+D;AAC/D,wGAAwG;AACxG,mDAAmD;AAEnD,MAAM,OAAO,iBAAiB;IAET,OAAO,CAAU;IACjB,GAAG,GAAwD,IAAI,GAAG,EAAE,CAAC;IAEtF,KAAK;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,YAAY,OAAgB;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,eAAe,CAAC,QAA0B,EAAE,IAAkB,EAAE,GAAY,EAAE,KAAa;QACvF,IAAI,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;QAClG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,GAAG,CAAC,MAAM,GAAG,KAAK;YAAE,GAAG,CAAC,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;QAC/C,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,cAAc,CAAC,QAA6C,EAAE,QAAgB,CAAC;QAC3E,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;IAED,YAAY,CAAC,QAAkC;QAC3C,IAAI,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QAClE,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,gBAAgB,CAAC,QAAkC;QAC/C,IAAI,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACtE,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,CAAC,QAA6C,EAAE,IAAkB,EAAE,KAAa;QACnF,IAAI,CAAC,QAAQ,EAAE;YACX,IAAI,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC;SACf;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE;YACR,IAAI,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,YAAY,CAAC,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;YACnG,OAAO,IAAI,CAAC;SACf;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,GAAG,KAAK,SAAS,EAAE;YACnB,IAAI,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,YAAY,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC7G,OAAO,IAAI,CAAC;SACf;QACD,IAAI,CAAC,GAAG,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACrD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;CAEJ;AAKD,8BAA8B;AAC9B,4BAA4B;AAC5B,oHAAoH;AACpH,WAAW,CAAC,oBAAoB,GAAG,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,0DAA0D,EAAE;;;;;;;KAOnI,CAAC,CAAC;AAEP,WAAW,CAAC,sBAAsB,GAAG;;;;;;;;;;;KAWhC,CAAC;AAEN,sFAAsF;AACtF,kDAAkD;AAClD,0GAA0G;AAC1G,gFAAgF;AAChF,WAAW,CAAC,qBAAqB,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,CACzE,uEAAuE,EAAE;;;;;OAKtE,CAAC,CAAC;AAET,WAAW,CAAC,QAAQ,CAAC,qBAAqB,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC"}
+{"version":3,"file":"engine_lightdata.js","sourceRoot":"","sources":["../../src/engine/engine_lightdata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAW,MAAM,OAAO,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAEhE,MAAM,aAAa,GAAG,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;AAWhE,gEAAgE;AAChE,sEAAsE;AACtE,gFAAgF;AAEhF,+DAA+D;AAC/D,wGAAwG;AACxG,mDAAmD;AAEnD,MAAM,OAAO,iBAAiB;IAET,OAAO,CAAU;IACjB,GAAG,GAAwD,IAAI,GAAG,EAAE,CAAC;IAEtF,KAAK;QACD,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;IACrB,CAAC;IAED,YAAY,OAAgB;QACxB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IAC3B,CAAC;IAED,eAAe,CAAC,QAA0B,EAAE,IAAkB,EAAE,GAAY,EAAE,KAAa;QACvF,IAAI,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,KAAK,GAAG,QAAQ,GAAG,IAAI,EAAE,GAAG,CAAC,CAAC;QAClG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;YACvB,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QACtC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACnC,MAAM,GAAG,GAAG,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;QACjC,IAAI,GAAG,CAAC,MAAM,GAAG,KAAK;YAAE,GAAG,CAAC,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC;QAC/C,aAAa,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAC1B,GAAG,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;QACjB,GAAG,EAAE,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,cAAc,CAAC,QAA6C,EAAE,QAAgB,CAAC;QAC3E,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/D,CAAC;IAED,YAAY,CAAC,QAAkC;QAC3C,IAAI,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QAClE,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,gBAAgB,CAAC,QAAkC;QAC/C,IAAI,aAAa;YAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB,EAAE,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;QACtE,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,CAAC,QAA6C,EAAE,IAAkB,EAAE,KAAa;QACnF,IAAI,CAAC,QAAQ,EAAE;YACX,IAAI,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC;SACf;QACD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACrC,IAAI,CAAC,KAAK,EAAE;YACR,IAAI,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,YAAY,CAAC,IAAI,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;YACnG,OAAO,IAAI,CAAC;SACf;QACD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,GAAG,KAAK,SAAS,EAAE;YACnB,IAAI,aAAa;gBAAE,OAAO,CAAC,IAAI,CAAC,iBAAiB,YAAY,CAAC,IAAI,CAAC,cAAc,EAAE,QAAQ,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC7G,OAAO,IAAI,CAAC;SACf;QACD,IAAI,CAAC,GAAG,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,KAAK;YAAE,OAAO,IAAI,CAAC;QACrD,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC;IACtB,CAAC;CAEJ;AAKD,8BAA8B;AAC9B,4BAA4B;AAC5B,oHAAoH;AACpH,uDAAuD;AACvD,6GAA6G;AAC7G,WAAW,CAAC,oBAAoB,GAAG,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,0DAA0D,EAAE;;;;;;KAMnI,CAAC,CAAC;AAEP,WAAW,CAAC,sBAAsB,GAAG;;;;;;;;;;KAUhC,CAAC;AAEN,sFAAsF;AACtF,kDAAkD;AAClD,0GAA0G;AAC1G,gFAAgF;AAChF,WAAW,CAAC,qBAAqB,GAAG,WAAW,CAAC,qBAAqB,CAAC,OAAO,CACzE,uEAAuE,EAAE;;;;;OAKtE,CAAC,CAAC;AAET,yDAAyD;AACzD,6EAA6E;AAC7E,+EAA+E"}

package/lib/engine/engine_materialpropertyblock.d.ts

@@ -0,0 +1,259 @@
+import { Material, Object3D, Color, Texture, Vector2, Vector3, Vector4, Euler } from "three";
+/**
+ * Valid types that can be used as material property overrides
+ */
+type MaterialPropertyType = number | number[] | Color | Texture | Vector2 | Vector3 | Vector4 | null | Euler;
+/**
+ * Defines offset and repeat transformations for texture coordinates
+ */
+export interface TextureTransform {
+    /** UV offset applied to the texture */
+    offset?: Vector2;
+    /** UV repeat/scale applied to the texture */
+    repeat?: Vector2;
+}
+/**
+ * Represents a single material property override with optional texture transformation
+ * @template T The type of the property value
+ */
+export interface PropertyBlockOverride<T extends MaterialPropertyType = MaterialPropertyType> {
+    /** The name of the material property to override (e.g., "color", "map", "roughness") */
+    name: string;
+    /** The value to set for this property */
+    value: T;
+    /** Optional texture coordinate transformation (only used when value is a Texture) */
+    textureTransform?: TextureTransform;
+}
+/**
+ * Utility type that extracts only non-function property names from a type
+ * @template T The type to extract property names from
+ */
+type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K;
+}[keyof T];
+/**
+ * MaterialPropertyBlock allows per-object material property overrides without creating new material instances.
+ * This is useful for rendering multiple objects with the same base material but different properties
+ * (e.g., different colors, textures, or shader parameters).
+ *
+ * The property block system works by:
+ * - Temporarily applying overrides in onBeforeRender
+ * - Restoring original values in onAfterRender
+ * - Managing shader defines and program cache keys for correct shader compilation
+ * - Supporting texture coordinate transforms per object
+ *
+ * Common use cases:
+ * - **Lightmaps**: Apply unique lightmap textures to individual objects sharing the same material
+ * - **Reflection Probes**: Apply different environment maps per object for localized reflections
+ * - **See-through effects**: Temporarily override transparency/transmission properties for X-ray effects
+ *
+ * ## Getting a MaterialPropertyBlock
+ *
+ * **Important**: Do not use the constructor directly. Instead, use the static {@link MaterialPropertyBlock.get} method:
+ *
+ * ```typescript
+ * const block = MaterialPropertyBlock.get(myMesh);
+ * ```
+ *
+ * This method will either return an existing property block or create a new one if it doesn't exist.
+ * It automatically:
+ * - Creates the property block instance
+ * - Registers it in the internal registry
+ * - Attaches the necessary render callbacks to the object
+ * - Handles Groups by applying overrides to all child meshes
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Get or create a property block for an object
+ * const block = MaterialPropertyBlock.get(myMesh);
+ *
+ * // Override the color property
+ * block.setOverride("color", new Color(1, 0, 0));
+ *
+ * // Override a texture with custom UV transform (useful for lightmaps)
+ * block.setOverride("lightMap", myLightmapTexture, {
+ *   offset: new Vector2(0.5, 0.5),
+ *   repeat: new Vector2(2, 2)
+ * });
+ *
+ * // Set a shader define
+ * block.setDefine("USE_CUSTOM_FEATURE", 1);
+ * ```
+ *
+ * @example Lightmap usage
+ * ```typescript
+ * const block = MaterialPropertyBlock.get(mesh);
+ * block.setOverride("lightMap", lightmapTexture);
+ * block.setOverride("lightMapIntensity", 1.5);
+ * ```
+ *
+ * @example See-through effect
+ * ```typescript
+ * const block = MaterialPropertyBlock.get(mesh);
+ * block.setOverride("transparent", true);
+ * block.setOverride("opacity", 0.3);
+ * ```
+ *
+ * @template T The material type this property block is associated with
+ */
+export declare class MaterialPropertyBlock<T extends Material = Material> {
+    private _overrides;
+    private _defines;
+    private _object;
+    /** The object this property block is attached to */
+    get object(): Object3D | null;
+    /**
+     * Creates a new MaterialPropertyBlock
+     * @param object The object this property block is for (optional)
+     */
+    protected constructor(object?: Object3D | null);
+    /**
+     * Gets or creates a MaterialPropertyBlock for the given object.
+     * This is the recommended way to obtain a property block instance.
+     *
+     * @template T The material type
+     * @param object The object to get/create a property block for
+     * @returns The MaterialPropertyBlock associated with this object
+     *
+     * @example
+     * ```typescript
+     * const block = MaterialPropertyBlock.get(myMesh);
+     * block.setOverride("roughness", 0.5);
+     * ```
+     */
+    static get<T extends Material = Material>(object: Object3D): MaterialPropertyBlock<T>;
+    /**
+     * Checks if an object has any property overrides
+     * @param object The object to check
+     * @returns True if the object has a property block with overrides
+     */
+    static hasOverrides(object: Object3D): boolean;
+    /**
+     * Disposes this property block and cleans up associated resources.
+     * After calling dispose, this property block should not be used.
+     */
+    dispose(): void;
+    /**
+     * Sets or updates a material property override.
+     * The override will be applied to the material during rendering.
+     *
+     * @param name The name of the material property to override (e.g., "color", "map", "roughness")
+     * @param value The value to set
+     * @param textureTransform Optional UV transform (only used when value is a Texture)
+     *
+     * @example
+     * ```typescript
+     * // Override a simple property
+     * block.setOverride("roughness", 0.8);
+     *
+     * // Override a color
+     * block.setOverride("color", new Color(0xff0000));
+     *
+     * // Override a texture with UV transform
+     * block.setOverride("map", texture, {
+     *   offset: new Vector2(0, 0),
+     *   repeat: new Vector2(2, 2)
+     * });
+     * ```
+     */
+    setOverride<K extends NonFunctionPropertyNames<T>>(name: K, value: T[K], textureTransform?: TextureTransform): void;
+    setOverride(name: string, value: MaterialPropertyType, textureTransform?: TextureTransform): void;
+    /**
+     * Gets the override for a specific property with type-safe value inference
+     * @param name The property name to get
+     * @returns The PropertyBlockOverride with correctly typed value if it exists, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const block = MaterialPropertyBlock.get<MeshStandardMaterial>(mesh);
+     *
+     * // Value is inferred as number | undefined
+     * const roughness = block.getOverride("roughness")?.value;
+     *
+     * // Value is inferred as Color | undefined
+     * const color = block.getOverride("color")?.value;
+     *
+     * // Value is inferred as Texture | null | undefined
+     * const map = block.getOverride("map")?.value;
+     *
+     * // Explicitly specify the type for properties not on the base material type
+     * const transmission = block.getOverride<number>("transmission")?.value;
+     *
+     * // Or use a more specific material type
+     * const physicalBlock = block as MaterialPropertyBlock<MeshPhysicalMaterial>;
+     * const transmissionTyped = physicalBlock.getOverride("transmission")?.value; // number
+     * ```
+     */
+    getOverride<K extends NonFunctionPropertyNames<T>>(name: K): PropertyBlockOverride<T[K] & MaterialPropertyType> | undefined;
+    getOverride<V extends MaterialPropertyType = MaterialPropertyType>(name: string): PropertyBlockOverride<V> | undefined;
+    /**
+     * Removes a specific property override
+     * @param name The property name to clear
+     */
+    removeOveride<K extends NonFunctionPropertyNames<T>>(name: K | ({} & string)): void;
+    /**
+     * Removes all property overrides from this block
+     */
+    clearAllOverrides(): void;
+    /**
+     * Gets all property overrides as a readonly array
+     * @returns Array of all property overrides
+     */
+    get overrides(): readonly PropertyBlockOverride[];
+    /**
+     * Checks if this property block has any overrides
+     * @returns True if there are any overrides set
+     */
+    hasOverrides(): boolean;
+    /**
+     * Set a shader define that will be included in the program cache key.
+     * This allows different objects sharing the same material to have different shader programs.
+     *
+     * Defines affect shader compilation and are useful for enabling/disabling features per-object.
+     *
+     * @param name The define name (e.g., "USE_LIGHTMAP", "ENABLE_REFLECTIONS")
+     * @param value The define value (typically a boolean, number, or string)
+     *
+     * @example
+     * ```typescript
+     * // Enable a feature for this specific object
+     * block.setDefine("USE_CUSTOM_SHADER", true);
+     * block.setDefine("QUALITY_LEVEL", 2);
+     * ```
+     */
+    setDefine(name: string, value: string | number | boolean): void;
+    /**
+     * Remove a shader define
+     * @param name The define name to remove
+     */
+    clearDefine(name: string): void;
+    /**
+     * Get all defines set on this property block
+     * @returns A readonly record of all defines
+     */
+    getDefines(): Readonly<Record<string, string | number | boolean>>;
+    /**
+     * Generates a cache key based on the current overrides and defines.
+     * This key is used internally to ensure correct shader program selection
+     * when objects share materials but have different property blocks.
+     *
+     * @returns A string representing the current state of this property block
+     * @internal
+     */
+    getCacheKey(): string;
+}
+/**
+ * Checks if an object has a MaterialPropertyBlock attached to it.
+ *
+ * @param object The object to check
+ * @returns True if the object has a property block registered
+ *
+ * @example
+ * ```typescript
+ * if (objectHasPropertyBlock(myMesh)) {
+ *   console.log("This mesh has property overrides");
+ * }
+ * ```
+ */
+export declare function objectHasPropertyBlock(object: Object3D): boolean;
+export {};