@needle-tools/engine 4.13.1 → 4.14.0-next.31f837e

package/src/engine/engine_materialpropertyblock.ts

@@ -0,0 +1,500 @@
+import { Material, Object3D, Color, Texture, Vector2, Vector3, Vector4, WebGLRenderer, Scene, Camera, BufferGeometry, Group } from "three";
+
+type MaterialPropertyType = number | number[] | Color | Texture | Vector2 | Vector3 | Vector4 | null;
+
+export interface TextureTransform {
+    offset?: Vector2;
+    repeat?: Vector2;
+}
+
+export interface PropertyBlockOverride {
+    name: string;
+    value: MaterialPropertyType;
+    textureTransform?: TextureTransform;
+}
+
+type NonFunctionPropertyNames<T> = {
+    [K in keyof T]: T[K] extends Function ? never : K
+}[keyof T];
+
+// Centralized registry for all property block related data
+class PropertyBlockRegistry {
+    // Map from object to its property block
+    private objectToBlock = new WeakMap<Object3D, MaterialPropertyBlock>();
+
+    // Track which materials belong to which property block (to prevent applying to wrong materials)
+    // Use WeakSet for automatic cleanup when materials are garbage collected
+    private objectToMaterials = new WeakMap<Object3D, WeakSet<Material>>();
+
+    // Track which meshes have callbacks for which property block owners
+    private meshToOwners = new WeakMap<Object3D, Set<Object3D>>();
+
+    // Track original callback functions for cleanup (reserved for future use)
+    private meshToOriginalCallbacks = new WeakMap<Object3D, {
+        onBeforeRender?: ObjectRenderCallback;
+        onAfterRender?: ObjectRenderCallback;
+    }>();
+
+    getBlock(object: Object3D): MaterialPropertyBlock | undefined {
+        return this.objectToBlock.get(object);
+    }
+
+    setBlock(object: Object3D, block: MaterialPropertyBlock): void {
+        this.objectToBlock.set(object, block);
+    }
+
+    deleteBlock(object: Object3D): void {
+        this.objectToBlock.delete(object);
+        this.objectToMaterials.delete(object);
+    }
+
+    addMaterial(object: Object3D, material: Material): void {
+        let materials = this.objectToMaterials.get(object);
+        if (!materials) {
+            materials = new WeakSet();
+            this.objectToMaterials.set(object, materials);
+        }
+        materials.add(material);
+    }
+
+    hasMaterial(object: Object3D, material: Material): boolean {
+        return this.objectToMaterials.get(object)?.has(material) ?? false;
+    }
+
+    isHooked(mesh: Object3D, owner: Object3D): boolean {
+        return this.meshToOwners.get(mesh)?.has(owner) ?? false;
+    }
+
+    addHook(mesh: Object3D, owner: Object3D): void {
+        let owners = this.meshToOwners.get(mesh);
+        if (!owners) {
+            owners = new Set();
+            this.meshToOwners.set(mesh, owners);
+        }
+        owners.add(owner);
+    }
+
+    removeHook(mesh: Object3D, owner: Object3D): void {
+        const owners = this.meshToOwners.get(mesh);
+        if (owners) {
+            owners.delete(owner);
+            if (owners.size === 0) {
+                this.meshToOwners.delete(mesh);
+            }
+        }
+    }
+
+    getOriginalCallbacks(mesh: Object3D): { onBeforeRender?: ObjectRenderCallback; onAfterRender?: ObjectRenderCallback } | undefined {
+        return this.meshToOriginalCallbacks.get(mesh);
+    }
+
+    setOriginalCallbacks(mesh: Object3D, callbacks: { onBeforeRender?: ObjectRenderCallback; onAfterRender?: ObjectRenderCallback }): void {
+        this.meshToOriginalCallbacks.set(mesh, callbacks);
+    }
+}
+
+const registry = new PropertyBlockRegistry();
+
+export class MaterialPropertyBlock<T extends Material = Material> {
+    private _overrides: PropertyBlockOverride[] = [];
+    private _defines: Record<string, string | number | boolean> = {};
+    private _object: Object3D | null = null;
+
+    get object(): Object3D | null { return this._object; }
+
+    constructor(object: Object3D | null = null) {
+        this._object = object;
+    }
+
+    static get<T extends Material = Material>(object: Object3D): MaterialPropertyBlock<T> {
+        let block = registry.getBlock(object);
+        if (!block) {
+            block = new MaterialPropertyBlock(object);
+            registry.setBlock(object, block);
+            attachPropertyBlockToObject(object, block);
+        }
+        return block as MaterialPropertyBlock<T>;
+    }
+
+    dispose() {
+        if (this._object) {
+            registry.deleteBlock(this._object);
+            // TODO: Add cleanup for hooked meshes
+        }
+        this._overrides = [];
+        this._object = null;
+    }
+
+    setOverride<K extends NonFunctionPropertyNames<T>>(name: K, value: T[K], textureTransform?: TextureTransform): void;
+    setOverride(name: string, value: MaterialPropertyType, textureTransform?: TextureTransform): void;
+    setOverride(name: string, value: MaterialPropertyType, textureTransform?: TextureTransform): void {
+        const existing = this._overrides.find(o => o.name === name);
+        if (existing) {
+            existing.value = value;
+            existing.textureTransform = textureTransform;
+        } else {
+            this._overrides.push({ name, value, textureTransform });
+        }
+    }
+
+    getOverride(name: string): PropertyBlockOverride | undefined {
+        return this._overrides.find(o => o.name === name);
+    }
+
+    clearOverride(name: string): void {
+        const index = this._overrides.findIndex(o => o.name === name);
+        if (index >= 0) {
+            this._overrides.splice(index, 1);
+        }
+    }
+
+    clearAllOverrides(): void {
+        this._overrides = [];
+    }
+
+    removeOverride(name: string): void {
+        this.clearOverride(name);
+    }
+
+    get overrides(): PropertyBlockOverride[] {
+        return this._overrides;
+    }
+
+    hasOverrides(): boolean {
+        return this._overrides.length > 0;
+    }
+
+    /**
+     * 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
+     */
+    setDefine(name: string, value: string | number | boolean): void {
+        this._defines[name] = value;
+    }
+
+    /**
+     * Remove a shader define
+     */
+    clearDefine(name: string): void {
+        this._defines[name] = undefined as any;
+    }
+
+    /**
+     * Get all defines set on this property block
+     */
+    getDefines(): Readonly<Record<string, string | number | boolean>> {
+        return this._defines;
+    }
+
+    getCacheKey(): string {
+        const parts: string[] = [];
+
+        // Add defines to cache key
+        const defineKeys = Object.keys(this._defines).sort();
+        for (const key of defineKeys) {
+            const value = this._defines[key];
+            if (value !== undefined) {
+                parts.push(`d:${key}=${value}`);
+            }
+        }
+
+        // Add overrides to cache key
+        for (const o of this._overrides) {
+            if (o.value === null) continue;
+            let val = "";
+            if (o.value instanceof Texture) {
+                val = (o.value as any).uuid || "texture";
+                if (o.textureTransform) {
+                    const t = o.textureTransform;
+                    if (t.offset) val += `;to:${t.offset.x},${t.offset.y}`;
+                    if (t.repeat) val += `;tr:${t.repeat.x},${t.repeat.y}`;
+                }
+            } else if (Array.isArray(o.value)) {
+                val = o.value.join(",");
+            } else if (o.value && typeof o.value === "object" && "r" in o.value) {
+                const c = o.value as any;
+                val = `${c.r},${c.g},${c.b},${c.a !== undefined ? c.a : ""}`;
+            } else if (o.value && typeof o.value === "object" && "x" in o.value) {
+                // Vector2, Vector3, Vector4
+                const v = o.value as any;
+                val = `${v.x},${v.y}${v.z !== undefined ? `,${v.z}` : ""}${v.w !== undefined ? `,${v.w}` : ""}`;
+            } else {
+                val = String(o.value);
+            }
+            parts.push(`${o.name}=${val}`);
+        }
+        return parts.join(";");
+    }
+}
+
+const $originalValues = Symbol("originalValues");
+
+interface OriginalValue {
+    name: string;
+    value: unknown;
+}
+
+interface SavedTextureTransform {
+    name: string;
+    offsetX: number;
+    offsetY: number;
+    repeatX: number;
+    repeatY: number;
+}
+
+const $savedTextureTransforms = Symbol("savedTextureTransforms");
+
+type ObjectRenderCallback = (this: Object3D, renderer: WebGLRenderer, scene: Scene, camera: Camera, geometry: BufferGeometry, material: Material, group: Group) => void;
+
+// Collect all materials from an object and its children
+function collectMaterials(object: Object3D, materials: Set<Material>): void {
+    const obj = object as Object3D & { material?: Material | Material[] };
+    if (obj.material) {
+        if (Array.isArray(obj.material)) {
+            obj.material.forEach(mat => materials.add(mat));
+        } else {
+            materials.add(obj.material);
+        }
+    }
+
+    // For Groups, collect materials from children too
+    if (object.type === "Group") {
+        object.children.forEach(child => collectMaterials(child, materials));
+    }
+}
+
+// Find property block by checking this object and parent (if parent is a Group)
+// Returns both the block and the owner object
+function findPropertyBlockAndOwner(obj: Object3D): { block: MaterialPropertyBlock; owner: Object3D } | undefined {
+    // First check if this object itself has a property block
+    let block = registry.getBlock(obj);
+    if (block) return { block, owner: obj };
+
+    // If not, check if parent is a Group and has a property block
+    if (obj.parent && obj.parent.type === "Group") {
+        block = registry.getBlock(obj.parent);
+        if (block) return { block, owner: obj.parent };
+    }
+
+    return undefined;
+}
+
+// #region OnBeforeRender
+const onBeforeRender_MaterialBlock: ObjectRenderCallback = function (this: Object3D, _renderer: WebGLRenderer, _scene: Scene, _camera: Camera, _geometry: BufferGeometry, material: Material, _group: Group) {
+    const result = findPropertyBlockAndOwner(this);
+    if (!result) {
+        return;
+    }
+
+    const { block: propertyBlock, owner } = result;
+
+    // Only apply if this material was registered with this property block
+    if (!registry.hasMaterial(owner, material)) {
+        return;
+    }
+
+    const overrides = propertyBlock.overrides;
+    const mat = material as any;
+
+    // Apply defines to material - this affects shader compilation
+    const defines = propertyBlock.getDefines();
+    const defineKeys = Object.keys(defines);
+    if (defineKeys.length > 0) {
+        if (!mat.defines) mat.defines = {};
+        for (const key of defineKeys) {
+            const value = defines[key];
+            if (value !== undefined) {
+                mat.defines[key] = value;
+            }
+        }
+    }
+
+    // Still set up cache key even if no overrides (defines affect it)
+    if (overrides.length === 0 && defineKeys.length === 0) {
+        return;
+    }
+
+    // Defines always affect shader compilation → need program change
+    let needsProgramChange = defineKeys.length > 0;
+
+    if (!mat[$originalValues]) {
+        mat[$originalValues] = [];
+    }
+    const originalValues = mat[$originalValues] as OriginalValue[];
+
+    for (const override of overrides) {
+        if (override.value === null) continue;
+
+        const currentValue = mat[override.name];
+
+        const existingOriginal = originalValues.find((o: OriginalValue) => o.name === override.name);
+        if (existingOriginal) {
+            // Update to current value each frame so animations/external changes are preserved
+            existingOriginal.value = currentValue;
+        } else {
+            originalValues.push({ name: override.name, value: currentValue });
+        }
+
+        // Check if this override changes shader features (truthiness change).
+        // E.g. null → Texture enables USE_LIGHTMAP, Texture → null disables it.
+        // Pure uniform changes (red → blue, textureA → textureB) don't need program switch.
+        if (!needsProgramChange && !!currentValue !== !!override.value) {
+            needsProgramChange = true;
+        }
+
+        // Set all material properties including lightMap -
+        // three.js reads material.lightMap to determine shader parameters and upload uniforms
+        mat[override.name] = override.value;
+
+        // Apply per-object texture transform (offset/repeat) if specified
+        if (override.textureTransform && override.value instanceof Texture) {
+            const tex = override.value;
+            if (!mat[$savedTextureTransforms]) mat[$savedTextureTransforms] = [];
+            (mat[$savedTextureTransforms] as SavedTextureTransform[]).push({
+                name: override.name,
+                offsetX: tex.offset.x, offsetY: tex.offset.y,
+                repeatX: tex.repeat.x, repeatY: tex.repeat.y
+            });
+            const t = override.textureTransform;
+            if (t.offset) tex.offset.copy(t.offset);
+            if (t.repeat) tex.repeat.copy(t.repeat);
+        }
+    }
+
+    // Only set needsUpdate when overrides change shader features (truthiness changes
+    // like null↔texture, or defines added). This triggers getProgram() for program switches.
+    // Pure uniform overrides (color, roughness) skip this — no version increment needed.
+    if (needsProgramChange) {
+        mat.needsUpdate = true;
+    }
+    // _forceRefresh triggers uniform re-upload for consecutive objects sharing
+    // the same program and material (without it three.js skips the upload).
+    mat._forceRefresh = true;
+};
+
+// #region OnAfterRender
+const onAfterRender_MaterialBlock: ObjectRenderCallback = function (this: Object3D, _renderer: WebGLRenderer, _scene: Scene, _camera: Camera, _geometry: BufferGeometry, material: Material, _group: Group) {
+    const result = findPropertyBlockAndOwner(this);
+    if (!result) {
+        return;
+    }
+
+    const { block: propertyBlock, owner } = result;
+
+    // Only restore if this material was registered with this property block
+    if (!registry.hasMaterial(owner, material)) {
+        return;
+    }
+
+    const overrides = propertyBlock.overrides;
+
+    const mat = material as any;
+    const originalValues = mat[$originalValues] as OriginalValue[] | undefined;
+
+    // Clean up defines — this affects shader compilation
+    const defines = propertyBlock.getDefines();
+    const defineKeys = Object.keys(defines);
+    let needsProgramChange = false;
+    if (defineKeys.length > 0 && mat.defines) {
+        for (const key of defineKeys) {
+            delete mat.defines[key];
+        }
+        needsProgramChange = true;
+    }
+
+    if (overrides.length === 0) {
+        if (needsProgramChange) {
+            mat.needsUpdate = true;
+            mat._forceRefresh = true;
+        }
+        return;
+    }
+
+    if (!originalValues) return;
+
+    // Restore texture transforms before restoring material properties
+    const savedTransforms = mat[$savedTextureTransforms] as SavedTextureTransform[] | undefined;
+    if (savedTransforms && savedTransforms.length > 0) {
+        for (const saved of savedTransforms) {
+            const override = overrides.find(o => o.name === saved.name);
+            if (override?.value instanceof Texture) {
+                override.value.offset.set(saved.offsetX, saved.offsetY);
+                override.value.repeat.set(saved.repeatX, saved.repeatY);
+            }
+        }
+        savedTransforms.length = 0;
+    }
+
+    for (const override of overrides) {
+        const original = originalValues.find(o => o.name === override.name);
+        if (original) {
+            // Check if restoring changes shader features (truthiness change)
+            if (!needsProgramChange && !!override.value !== !!original.value) {
+                needsProgramChange = true;
+            }
+            mat[override.name] = original.value;
+        }
+    }
+
+    // Only set needsUpdate when restoring affects shader features
+    if (needsProgramChange) {
+        mat.needsUpdate = true;
+    }
+    // Always force uniform refresh so the next object gets correct values
+    mat._forceRefresh = true;
+};
+
+
+// #region Attach Callbacks
+function attachPropertyBlockToObject(object: Object3D, _propertyBlock: MaterialPropertyBlock): void {
+    // Collect and register all materials that belong to this property block
+    const materials = new Set<Material>();
+    collectMaterials(object, materials);
+    materials.forEach(mat => registry.addMaterial(object, mat));
+
+    // Attach callbacks to renderable objects (Mesh, SkinnedMesh)
+    // Groups don't render themselves but we still need to handle child meshes
+    if (object.type === "Group") {
+        object.children.forEach(child => {
+            if (child.type === "Mesh" || child.type === "SkinnedMesh") {
+                attachCallbacksToMesh(child, object);
+            }
+        });
+    } else if (object.type === "Mesh" || object.type === "SkinnedMesh") {
+        attachCallbacksToMesh(object, object);
+    }
+}
+function attachCallbacksToMesh(mesh: Object3D, propertyBlockOwner: Object3D): void {
+    // Check if this specific mesh already has our callbacks attached for this property block owner
+    if (registry.isHooked(mesh, propertyBlockOwner)) {
+        // Already hooked for this property block owner
+        return;
+    }
+
+    registry.addHook(mesh, propertyBlockOwner);
+
+    if (!mesh.onBeforeRender) {
+        mesh.onBeforeRender = onBeforeRender_MaterialBlock;
+    } else {
+        const original = mesh.onBeforeRender;
+        mesh.onBeforeRender = function (renderer, scene, camera, geometry, material, group) {
+            original.call(this, renderer, scene, camera, geometry, material, group);
+            onBeforeRender_MaterialBlock.call(this, renderer, scene, camera, geometry, material, group);
+        };
+    }
+
+    if (!mesh.onAfterRender) {
+        mesh.onAfterRender = onAfterRender_MaterialBlock;
+    } else {
+        const original = mesh.onAfterRender;
+        mesh.onAfterRender = function (renderer, scene, camera, geometry, material, group) {
+            onAfterRender_MaterialBlock.call(this, renderer, scene, camera, geometry, material, group);
+            original.call(this, renderer, scene, camera, geometry, material, group);
+        };
+    }
+}
+//#endregion
+
+export function objectHasPropertyBlock(object: Object3D): boolean {
+    return registry.getBlock(object) !== undefined;
+}

package/src/engine/engine_utils.ts

@@ -589,6 +589,7 @@ declare global {
 
 /**
  * Utility functions to detect certain device types (mobile, desktop), browsers, or capabilities.
+ * @category Utilities
  */
 export namespace DeviceUtilities {