@needle-tools/engine 4.8.3-next.bc4f9a4 → 4.8.4-experimental.c93e134

package/src/engine/extensions/KHR_materials_variants.ts

@@ -0,0 +1,179 @@
+import { type GLTFLoaderPlugin, GLTFParser } from "three/examples/jsm/loaders/GLTFLoader.js";
+import { MaterialVariants } from "../../engine-components/MaterialVariants.js";
+import { addComponent } from "../engine_components.js";
+import { InstantiateIdProvider } from "../engine_networking_instantiate.js";
+import { GLTF } from "../engine_types.js";
+import { getParam } from "../engine_utils.js";
+
+const debug = getParam("debugmaterialvariants");
+
+export interface MaterialVariant {
+    name: string;
+}
+
+export interface RootMaterialVariantsExtension {
+    variants: MaterialVariant[];
+}
+
+export interface PrimitiveMaterialVariantsExtension {
+    mappings: Array<{
+        variants: number[];
+        material: number;
+    }>;
+}
+
+export class NEEDLE_material_variants implements GLTFLoaderPlugin {
+    get name() { return "KHR_materials_variants"; }
+
+    private parser: GLTFParser;
+    private variants: MaterialVariant[] = [];
+    private loadingMesh = false;
+
+
+    constructor(parser: GLTFParser) {
+        this.parser = parser;
+    }
+
+    beforeRoot(): Promise<void> | null {
+        const parser = this.parser;
+        const json = parser.json;
+
+        if (!json.extensions || !json.extensions[this.name]) {
+            return null;
+        }
+
+        const extension = json.extensions[this.name] as RootMaterialVariantsExtension;
+        this.variants = extension.variants || [];
+
+        if (debug) {
+            console.log("KHR_materials_variants found variants:", this.variants);
+        }
+
+        return null;
+    }
+
+    afterRoot(result: GLTF): Promise<void> | null {
+        if (this.variants.length > 0) {
+            // Store variants data on the GLTF result for components to access
+            if (!result.userData) result.userData = {};
+            result.userData.materialVariants = {
+                variants: this.variants,
+                parser: this.parser
+            };
+
+            if (debug) {
+                console.log("KHR_materials_variants stored variants data:", result.userData.materialVariants);
+            }
+        }
+
+
+        return null;
+    }
+
+    loadMesh(index: number): Promise<any> | null {
+        // Prevent infinite recursion
+        if (this.loadingMesh) {
+            return null;
+        }
+
+        const json = this.parser.json;
+        const meshDef = json.meshes[index];
+
+        if (!meshDef || !meshDef.primitives) {
+            return null;
+        }
+
+        // Check if any primitive has variant mappings
+        const allMappings: Array<{ variants: number[]; material: number; primitiveIndex: number; }> = [];
+
+        meshDef.primitives.forEach((primitive: any, primitiveIndex: number) => {
+            if (primitive.extensions && primitive.extensions[this.name]) {
+                const extension = primitive.extensions[this.name] as PrimitiveMaterialVariantsExtension;
+
+                extension.mappings.forEach(mapping => {
+                    allMappings.push({
+                        ...mapping,
+                        primitiveIndex
+                    });
+                });
+            }
+        });
+
+        // If no variants, let normal loading proceed
+        if (allMappings.length === 0) {
+            return null;
+        }
+
+        // Load the mesh with recursion protection
+        this.loadingMesh = true;
+
+        return this.parser.loadMesh(index).then(mesh => {
+            if (mesh) {
+                // Attach variant data directly to the loaded mesh
+                this.attachVariantDataToMesh(mesh, index, allMappings);
+
+                if (debug) {
+                    console.log(`KHR_materials_variants processed mesh ${index} with ${allMappings.length} variant mappings`);
+                }
+            }
+            return mesh;
+        }).finally(() => {
+            this.loadingMesh = false;
+        });
+    }
+
+
+    private attachVariantDataToMesh(mesh: any, index: number, mappings: Array<{ variants: number[]; material: number; primitiveIndex: number; }>): void {
+        // Store variant mapping data on the mesh
+        if (!mesh.userData) mesh.userData = {};
+        mesh.userData.materialVariants = {
+            mappings: mappings,
+            variants: this.variants,
+            parser: this.parser
+        };
+
+        const idProvider = new InstantiateIdProvider(index);
+
+        // Automatically add the MaterialVariants component
+        try {
+            const component = addComponent(mesh, MaterialVariants, {}, { callAwake: false });
+            component.guid = idProvider.generateUUID();
+            if (debug) {
+                console.log("KHR_materials_variants added MaterialVariants component to mesh:", mesh.name);
+            }
+        } catch (error) {
+            console.warn("Failed to add MaterialVariants component to mesh:", mesh.name, error);
+        }
+
+        if (debug) {
+            console.log("KHR_materials_variants processed mesh with variants:", mesh.name, {
+                variants: this.variants,
+                mappings: mappings
+            });
+        }
+    }
+
+
+
+
+    // /**
+    //  * Get all available variant names
+    //  */
+    // getVariantNames(): string[] {
+    //     return this.variants.map(variant => variant.name);
+    // }
+
+    // /**
+    //  * Get variant by name
+    //  */
+    // getVariantByName(name: string): MaterialVariant | undefined {
+    //     return this.variants.find(variant => variant.name === name);
+    // }
+
+    // /**
+    //  * Get variant by index
+    //  */
+    // getVariantByIndex(index: number): MaterialVariant | undefined {
+    //     return this.variants[index];
+    // }
+}

package/src/engine/extensions/extensions.ts

@@ -9,6 +9,7 @@ import { type ConstructorConcrete, GLTF, type SourceIdentifier } from "../engine
 import { getParam } from "../engine_utils.js";
 import { NEEDLE_lightmaps } from "../extensions/NEEDLE_lightmaps.js";
 import { EXT_texture_exr } from "./EXT_texture_exr.js";
+import { NEEDLE_material_variants } from "./KHR_materials_variants.js";
 import { NEEDLE_components } from "./NEEDLE_components.js";
 import { NEEDLE_gameobject_data } from "./NEEDLE_gameobject_data.js";
 import { NEEDLE_lighting_settings } from "./NEEDLE_lighting_settings.js";
@@ -105,6 +106,7 @@ export async function registerExtensions(loader: GLTFLoader, context: Context, u
     loader.register(p => new NEEDLE_techniques_webgl(p, url));
     loader.register(p => new NEEDLE_render_objects(p, url));
     loader.register(p => new NEEDLE_progressive(p));
+    loader.register(p => new NEEDLE_material_variants(p));
     loader.register(p => new EXT_texture_exr(p));
     if (isResourceTrackingEnabled()) loader.register(p => new InternalUsageTrackerPlugin(p))
 

package/src/engine/extensions/index.ts

@@ -1,5 +1,6 @@
 export { compareAssociation } from "./extension_utils.js"
 export * from "./extensions.js"
+export * from "./KHR_materials_variants.js"
 export * from "./NEEDLE_animator_controller_model.js"
 export { SceneLightSettings } from "./NEEDLE_lighting_settings.js"
 export * from "./NEEDLE_progressive.js"

package/src/engine/webcomponents/buttons.ts

@@ -218,7 +218,11 @@ export class ButtonsFactory {
             await generateAndInsertQRCode();
             // TODO: make sure it doesnt overflow the screen
             // we need to add the qrCodeContainer to the body to get the correct size
-            document.body.appendChild(qrCodeContainer);
+            // TODO: we would need to search for the right engine element to insert this into if there are more
+            // Insert the QR code overlay inside the needle-engine element
+            const engine_element = document.body.querySelector("needle-engine");
+            const parent = engine_element || document.body;
+            parent.appendChild(qrCodeContainer);
             const containerRect = qrCodeElement.getBoundingClientRect();
             const buttonRect = qrCodeButton.getBoundingClientRect();
             qrCodeContainer.style.left = (buttonRect.left + buttonRect.width * .5 - containerRect.width * .5) + "px";
@@ -245,7 +249,7 @@ export class ButtonsFactory {
                 document.fullscreenElement.appendChild(qrCodeContainer);
             }
             else
-                document.body.appendChild(qrCodeContainer);
+                parent.appendChild(qrCodeContainer);
         }
 
         /** hides to QRCode overlay and unsubscribes from events */

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

@@ -287,6 +287,16 @@ export class NeedleMenuElement extends HTMLElement {
         // TODO: make host full size again and move the buttons to a wrapper so that we can later easily open e.g. foldouts/dropdowns / use the whole canvas space
         template.innerHTML = `<style>
 
+        /** Styling attributes that ensure the nested menu z-index does not cause it to overlay elements outside of <needle-engine> */
+        :host {
+            position: absolute;
+            width: 100%;
+            height: 100%;
+            z-index: 0;
+            top: 0;
+            pointer-events: none;
+        }
+
         #root {
             position: absolute;
             width: auto;

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

@@ -206,7 +206,7 @@ export class EngineLoadingView implements ILoadingViewHandler {
             this._loadingElement.style.display = "flex";
             this._loadingElement.style.alignItems = "center";
             this._loadingElement.style.justifyContent = "center";
-            this._loadingElement.style.zIndex = Number.MAX_SAFE_INTEGER.toString();
+            this._loadingElement.style.zIndex = "0";
             this._loadingElement.style.flexDirection = "column";
             this._loadingElement.style.pointerEvents = "none";
             this._loadingElement.style.color = "white";

package/src/engine-components/MaterialVariants.ts

@@ -0,0 +1,231 @@
+import { Material, Mesh } from "three";
+import { syncField } from "../engine/engine_networking_auto.js";
+
+import { serializable } from "../engine/engine_serialization_decorator.js";
+import { type MaterialVariant } from "../engine/extensions/KHR_materials_variants.js";
+import { Behaviour } from "./Component.js";
+
+export class MaterialVariants extends Behaviour {
+
+    @syncField()
+    @serializable()
+    selectedVariant: string = "";
+
+    @serializable()
+    createMenu: boolean = true;
+
+    private _menu: HTMLElement | null = null;
+
+    private _variants: MaterialVariant[] = [];
+    private _variantMappings: Array<{ variants: number[]; material: number; primitiveIndex: number; }> = [];
+    private _originalMaterials: Material[] = [];
+    private _mesh: Mesh | null = null;
+    private _materialCache = new Map<string, Material>();
+
+    awake() {
+        this._mesh = this.gameObject as any;
+        if (!this._mesh || !this._mesh.isMesh) {
+            console.warn("MaterialVariants component must be attached to a Mesh object", this.gameObject);
+            return;
+        }
+
+        this._initializeVariantData();
+        this._cacheOriginalMaterials();
+
+        if (this.createMenu) this._createVariantSelectionMenu();
+    }
+    onDestroy(): void {
+        this._menu?.remove();
+    }
+
+    private _createVariantSelectionMenu() {
+        const selectElement = document.createElement("select");
+        selectElement.addEventListener("change", (event) => {
+            const selectedVariant = (event.target as HTMLSelectElement).value;
+            this.selectVariant(selectedVariant);
+        });
+
+        // Add options for each variant
+        this._variants.forEach(variant => {
+            const option = document.createElement("option");
+            option.value = variant.name;
+            option.textContent = this.name + ": " + variantNameToDisplayName(variant.name);
+            selectElement.appendChild(option);
+        });
+
+        this._menu = selectElement;
+        this.context.menu.appendChild(selectElement);
+    }
+
+    async start() {
+        if (this.selectedVariant && this.selectedVariant.length > 0) {
+            await this.selectVariant(this.selectedVariant);
+        }
+    }
+
+    private _initializeVariantData() {
+        if (!this._mesh) return;
+
+        // Get variant data from the mesh userData (set by the extension)
+        const variantData = this._mesh.userData.materialVariants;
+        if (variantData) {
+            this._variants = variantData.variants || [];
+            this._variantMappings = variantData.mappings || [];
+        }
+
+        // Also check if the root GLTF has variant data
+        let current = this._mesh.parent;
+        while (current) {
+            if (current.userData.materialVariants) {
+                this._variants = current.userData.materialVariants.variants || [];
+                break;
+            }
+            current = current.parent;
+        }
+    }
+
+    private _cacheOriginalMaterials() {
+        if (!this._mesh) return;
+
+        if (Array.isArray(this._mesh.material)) {
+            this._originalMaterials = [...this._mesh.material];
+        } else {
+            this._originalMaterials = [this._mesh.material];
+        }
+    }
+
+    /**
+     * Get all available variant names
+     */
+    getVariantNames(): string[] {
+        return this._variants.map(variant => variant.name);
+    }
+
+    /**
+     * Get the currently selected variant name
+     */
+    getCurrentVariant(): string {
+        return this.selectedVariant;
+    }
+
+    /**
+     * Select a variant by name
+     * @param variantName The name of the variant to select
+     * @returns Promise that resolves to true if the variant was successfully selected, false otherwise
+     */
+    async selectVariant(variantName: string): Promise<boolean> {
+        if (!this._mesh || !variantName) return false;
+
+        // Find the variant by name
+        const variantIndex = this._variants.findIndex(v => v.name === variantName);
+        if (variantIndex === -1) {
+            console.warn(`Material variant "${variantName}" not found. Available variants:`, this.getVariantNames());
+            return false;
+        }
+
+        return await this.selectVariantByIndex(variantIndex);
+    }
+
+    /**
+     * Select a variant by index
+     * @param variantIndex The index of the variant to select
+     * @returns Promise that resolves to true if the variant was successfully selected, false otherwise
+     */
+    async selectVariantByIndex(variantIndex: number): Promise<boolean> {
+        if (!this._mesh || variantIndex < 0 || variantIndex >= this._variants.length) return false;
+
+        const variant = this._variants[variantIndex];
+
+        // Find mappings that include this variant
+        const applicableMappings = this._variantMappings.filter(mapping =>
+            mapping.variants.includes(variantIndex)
+        );
+
+        if (applicableMappings.length === 0) {
+            console.warn(`No material mappings found for variant "${variant.name}"`);
+            return false;
+        }
+
+        // Apply the variant materials to specific primitives
+        for (const mapping of applicableMappings) {
+            const materialIndex = mapping.material;
+            const primitiveIndex = mapping.primitiveIndex;
+            const material = await this._getMaterial(materialIndex);
+
+            if (material) {
+                if (Array.isArray(this._mesh.material)) {
+                    // For multi-material meshes, update the specific primitive's material
+                    if (primitiveIndex < this._mesh.material.length) {
+                        this._mesh.material[primitiveIndex] = material;
+                    } else {
+                        console.warn(`Primitive index ${primitiveIndex} out of bounds for material array of length ${this._mesh.material.length}`);
+                    }
+                } else {
+                    // Single material mesh - replace the entire material
+                    this._mesh.material = material;
+                }
+            }
+        }
+
+        this.selectedVariant = variant.name;
+        return true;
+    }
+
+    /**
+     * Reset to the original materials
+     */
+    resetToOriginal(): void {
+        if (!this._mesh) return;
+
+        if (Array.isArray(this._mesh.material)) {
+            this._mesh.material = [...this._originalMaterials];
+        } else {
+            this._mesh.material = this._originalMaterials[0];
+        }
+
+        this.selectedVariant = "";
+    }
+
+    private async _getMaterial(materialIndex: number): Promise<Material | null> {
+        // First check if we have it cached
+        const cacheKey = `material_${materialIndex}`;
+        if (this._materialCache.has(cacheKey)) {
+            return this._materialCache.get(cacheKey)!;
+        }
+
+        // Try to get the material from the GLTF parser
+        const variantData = this._mesh?.userData.materialVariants;
+        if (variantData && variantData.parser) {
+            try {
+                const material = await variantData.parser.getDependency('material', materialIndex);
+                this._materialCache.set(cacheKey, material);
+                return material;
+            } catch (error) {
+                console.warn(`Failed to load material at index ${materialIndex}:`, error);
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Check if a variant exists
+     * @param variantName The name of the variant to check
+     * @returns True if the variant exists
+     */
+    hasVariant(variantName: string): boolean {
+        return this._variants.some(v => v.name === variantName);
+    }
+
+    /**
+     * Get the number of available variants
+     */
+    getVariantCount(): number {
+        return this._variants.length;
+    }
+}
+
+function variantNameToDisplayName(name: string) {
+    // Make uppercase after space and beginning (unless number etc)
+    return name.replace(/(?:^|\s)\S/g, (match) => match.toUpperCase());
+}

package/src/engine-components/codegen/components.ts

@@ -86,6 +86,7 @@ export { Light } from "../Light.js";
 export { LODModel } from "../LODGroup.js";
 export { LODGroup } from "../LODGroup.js";
 export { LookAtConstraint } from "../LookAtConstraint.js";
+export { MaterialVariants } from "../MaterialVariants.js";
 export { NeedleMenu } from "../NeedleMenu.js";
 export { NestedGltf } from "../NestedGltf.js";
 export { Networking } from "../Networking.js";