@combeenation/3d-viewer 20.0.0 → 21.0.0-alpha1

package/src/global-types.d.ts

@@ -9,7 +9,7 @@ interface Window {
   Cbn:
     | undefined /* window.Cbn is only available when viewer runs inside Combeenation configurator */
     | {
-        Assets: {
+        Assets?: {
           /**
            * Retrieve material definition from configurator.
            * Implementation depends on the Combeenation environment the viewer is used in
@@ -19,20 +19,20 @@ interface Window {
            * @return Undefined if no definition for the given material name exists, otherwise an "JSON object" which can
            *         be passed to `BABYLON.Material.Parse` to create a runtime material object.
            */
-          getMaterial(materialId: string): Promise<object | undefined>;
+          getMaterial?(materialId: string): Promise<object | undefined>;
 
           /**
-           * Checks if a definition for a given material name exists in the configurator and issues a warning if not
+           * Checks if a definition for a given material name exists in the configurator and issues a warning if not.\
            */
-          assertMaterialExists(materialId: string): boolean;
+          assertMaterialExists?(materialId: string): boolean;
         };
-        utils: {
-          Viewer3dHelper: {
+        utils?: {
+          Viewer3dHelper?: {
             /**
              * Returns parent DOM element of a Combeenation configurator, which can be used as root for the inspector.
              * Also adjusts styling of some configurator parent sub elements to fix the inspector layout.
              */
-            getCfgrParentDomElementForInspector(): HTMLElement | undefined;
+            getCfgrParentDomElementForInspector?(): HTMLElement | undefined;
           };
         };
       };

package/src/index.ts

@@ -1,4 +1,3 @@
-/// <reference path="global-types.d.ts" />
 // Babylon.js extensions
 // All gltf extensions to support maximum feature set
 import '@babylonjs/loaders/glTF/2.0/Extensions';

package/src/internal/cbn-custom-babylon-loader-plugin.ts

@@ -165,7 +165,7 @@ function _addMissingMaterialMetadata(dataParsed: unknown, container: AssetContai
     const materialOnOriginalMesh = parsedMesh?.materialId;
 
     if (materialOnOriginalMesh && materialOnImportedMesh !== materialOnOriginalMesh) {
-      window.Cbn?.Assets.assertMaterialExists(materialOnOriginalMesh);
+      window.Cbn?.Assets?.assertMaterialExists?.(materialOnOriginalMesh);
       setInternalMetadataValue(importedMesh, 'deferredMaterial', materialOnOriginalMesh);
     }
   });
@@ -230,7 +230,7 @@ function _createDecals(dataParsed: unknown, container: AssetContainer): void {
 
     // optionally set material and tags directly
     if (materialId) {
-      window.Cbn?.Assets.assertMaterialExists(materialId);
+      window.Cbn?.Assets?.assertMaterialExists?.(materialId);
       setInternalMetadataValue(decalMesh, 'deferredMaterial', materialId);
     }
 

package/src/internal/parameter/texture-parameter-helper.ts

@@ -2,6 +2,7 @@ import {
   BaseTexture,
   BuiltInParameter,
   Material,
+  MaterialManager,
   PBRMaterial,
   ParameterManager,
   Scene,
@@ -50,7 +51,11 @@ export const ParameterTextureChannels = {
 };
 export type ParameterTextureChannelsKeys = keyof typeof ParameterTextureChannels;
 
-export function createBuiltInTextureParameter(parameterManager: ParameterManager, scene: Scene): void {
+export function createBuiltInTextureParameter(
+  parameterManager: ParameterManager,
+  materialManager: MaterialManager,
+  scene: Scene
+): void {
   // create parameter observer for each channel
   (Object.values(ParameterTextureChannels) as ParameterTextureChannelsKeys[]).forEach(channel => {
     parameterManager.setParameterObserver(
@@ -100,7 +105,7 @@ export function createBuiltInTextureParameter(parameterManager: ParameterManager
           } else if (url) {
             // no texture, or wrong type => create texture from scratch
             // first we check if some settings were provided in the material definition
-            const addMatSettings = await window.Cbn?.Assets.getMaterial(pbrMaterial.id);
+            const addMatSettings = await materialManager.getMaterialDefinition(pbrMaterial.id);
             const textureSettings = addMatSettings ? _getTextureObjFromParameterChannel(addMatSettings, channel) : {};
 
             // overwrite the name with the url, as this is what the texture parser expects

package/src/manager/debug-manager.ts

@@ -25,6 +25,7 @@ export class DebugManager {
 
   protected _axesViewer: AxesViewer | null = null;
   protected _showBoundingSphereForAutofocus: boolean = false;
+  protected _parentDomElementForInspector: HTMLElement | null = null;
 
   /** @internal */
   public constructor(protected viewer: Viewer) {}
@@ -40,7 +41,16 @@ export class DebugManager {
   }
 
   /**
-   * Enables the Babylon.js [Inspector](https://doc.babylonjs.com/legacy/inspector/).\
+   * Registers a parent DOM element to use as root for the Babylon.js inspector.
+   * When set and no explicit `options` are passed to {@link showInspector}, this element will be used
+   * as `globalRoot`, which avoids interference with the surrounding application layout.
+   */
+  public registerParentDomElementForInspector(el: HTMLElement): void {
+    this._parentDomElementForInspector = el;
+  }
+
+  /**
+   * Enables the Babylon.js [Inspector](https://doc.babylonjs.com/legacy/inspector()).\
    * Due to the additional size of the inspector, this function is only available in "development" builds!
    *
    * @returns Signalizes if inspector could be loaded
@@ -49,12 +59,16 @@ export class DebugManager {
     if (process.env.NODE_ENV === 'development') {
       const inspModule = await import(/* webpackChunkName: "inspector"*/ '@babylonjs/inspector');
 
-      if (!options && window.Cbn) {
+      const parentEl =
+        this._parentDomElementForInspector ??
+        // fallback to legacy `window.Cbn` call to support "old" cfgrs (pre Editor V2)
+        window.Cbn?.utils?.Viewer3dHelper?.getCfgrParentDomElementForInspector?.();
+
+      if (!options && parentEl) {
         // special case for usage in Combeenation configurator:
         // if no options are set the inspector will be rendered into the parent element of the configurator
         // in this way the configurator layout itself will not be affected by the inspector
-        const cfgrParentEl = window.Cbn.utils.Viewer3dHelper.getCfgrParentDomElementForInspector();
-        inspModule.Inspector.Show(this.viewer.scene, { globalRoot: cfgrParentEl });
+        inspModule.Inspector.Show(this.viewer.scene, { globalRoot: parentEl });
       } else {
         inspModule.Inspector.Show(this.viewer.scene, options ?? {});
       }

package/src/manager/material-manager.ts

@@ -30,12 +30,17 @@ export class MaterialManager {
    */
   public static readonly CBN_FALLBACK_MATERIAL_NAME = '$fallback';
 
+  protected _materialDefinitions: { [materialId: string]: object } = {};
   protected _clonedMaterials: { [name: string]: Material } = {};
   protected _createMaterialPromises: { [materialId: string]: Promise<Material | null> } = {};
 
   /** @internal */
   public constructor(protected viewer: Viewer) {}
 
+  public registerMaterials(materialDefinitions: { [materialId: string]: object }): void {
+    this._materialDefinitions = materialDefinitions;
+  }
+
   /**
    * Assigns material with certain id to desired mesh.\
    * Creates the material if not already available (see {@link getOrCreateMaterial}).
@@ -56,9 +61,9 @@ export class MaterialManager {
 
   /**
    * Returns material with certain id if already available in the scene.\
-   * If this is not the case material is created from a
-   * "[Material asset](https://docs.combeenation.com/docs/howto-create-and-use-babylon-and-material-asset)"
-   * on the Combeenation server.\
+   * If this is not the case, material is created from registered material definitions, which are most likely coming
+   * from "[Material assets](https://docs.combeenation.com/docs/howto-create-and-use-babylon-and-material-asset)" on the
+   * Combeenation server.\
    * Waits until textures of material are fully loaded and shader is compiled. In this way "flickering" effects
    * will be avoided, since the material would be incomplete without its loaded textures.
    *
@@ -78,7 +83,7 @@ export class MaterialManager {
         this.viewer.eventManager.fireEvent(ViewerEvent.MaterialCreationStart, materialId);
 
         // request not pending, call the dedicated function
-        const newCreationProm = this._createFromMaterialAsset(materialId, mesh);
+        const newCreationProm = this._createFromMaterialDefinition(materialId, mesh);
         // store the promise in a global map, so that subsequent requests can reference it
         this._createMaterialPromises[materialId] = newCreationProm;
         chosenMaterial = await newCreationProm;
@@ -153,7 +158,28 @@ export class MaterialManager {
     Object.keys(this._clonedMaterials).forEach(materialId => this.deleteClonedMaterial(materialId));
   }
 
-  protected async _createFromMaterialAsset(materialId: string, mesh?: AbstractMesh): Promise<Material | null> {
+  /**
+   * Get material defintion from registered material definitions or from legacy `Cbn.Assets.getMaterial` call
+   *
+   * @internal
+   */
+  public async getMaterialDefinition(materialId: string): Promise<object | undefined> {
+    let definition: object | undefined = this._materialDefinitions[materialId];
+    if (!definition && window.Cbn?.Assets?.getMaterial) {
+      // fallback to legacy `Cbn.Assets.getMaterial` call to support "old" cfgrs (pre Editor V2)
+      definition = await window.Cbn.Assets.getMaterial(materialId);
+    }
+
+    if (!definition) {
+      console.warn(
+        `Material definition for "${materialId}" couldn't be found. Material might not be registered or Material Asset from Combeenation server does not exist or is not connected to the configurator.`
+      );
+    }
+
+    return definition;
+  }
+
+  protected async _createFromMaterialDefinition(materialId: string, mesh?: AbstractMesh): Promise<Material | null> {
     if (materialId === MaterialManager.CBN_FALLBACK_MATERIAL_NAME) {
       const fallbackMaterial = new StandardMaterial(MaterialManager.CBN_FALLBACK_MATERIAL_NAME, this.viewer.scene);
       fallbackMaterial.disableLighting = true;
@@ -161,16 +187,8 @@ export class MaterialManager {
       return fallbackMaterial;
     }
 
-    if (!window.Cbn) {
-      return null;
-    }
-
-    const materialDefinition = await window.Cbn.Assets.getMaterial(materialId);
-
+    const materialDefinition = await this.getMaterialDefinition(materialId);
     if (!materialDefinition) {
-      console.warn(
-        `Trying to create material "${materialId}" from Combeenation asset but according asset does not exist or is not connected to the configurator.`
-      );
       return null;
     }
 

package/src/manager/parameter-manager.ts

@@ -584,7 +584,7 @@ export class ParameterManager {
    */
   protected _addBuiltInParameterObservers(): void {
     createBuiltInParameter(this, this.viewer.materialManager);
-    createBuiltInTextureParameter(this, this.viewer.scene);
+    createBuiltInTextureParameter(this, this.viewer.materialManager, this.viewer.scene);
     createPaintableParameter(this, this.viewer.scene);
   }
 

package/src/utils/viewer-utils.ts

@@ -5,6 +5,7 @@ import {
   MorphTarget,
   MorphTargetManager,
   Node,
+  Nullable,
   Tags,
   TransformNode,
   Vector3,
@@ -17,7 +18,7 @@ export type BakeGeometrySettings = {
 };
 
 export type CreateTransformNodeSettings = {
-  parentNode?: TransformNode;
+  parentNode?: Nullable<Node>;
   position?: Vector3;
   rotation?: Vector3;
   scaling?: Vector3;
@@ -111,7 +112,7 @@ export class ViewerUtils {
 
   /**
    * Get a `TransformNode` by name or create one if not already available.\
-   * Optionally set a parent node for the new `TransformNode` right away.
+   * Optionally set some settings of the existing or new `TransformNode` right away.
    */
   public getOrCreateTransformNode(nodeName: string, settings?: CreateTransformNodeSettings): TransformNode {
     const { parentNode, position, rotation, scaling } = settings ?? {};
@@ -122,10 +123,10 @@ export class ViewerUtils {
       node = new TransformNode(nodeName, scene);
     }
 
-    node.parent = parentNode ?? null;
-    node.position = position ?? Vector3.Zero();
-    node.rotation = rotation ?? Vector3.Zero();
-    node.scaling = scaling ?? Vector3.One();
+    if (parentNode !== undefined) node.parent = parentNode;
+    if (position !== undefined) node.position = position;
+    if (rotation !== undefined) node.rotation = rotation;
+    if (scaling !== undefined) node.scaling = scaling;
 
     return node;
   }