@combeenation/3d-viewer 6.5.0 → 7.0.0-beta1

package/src/api/classes/parameter.ts

@@ -1,6 +1,6 @@
 import { Color3 } from '@babylonjs/core/Maths/math.color';
 import { Vector3 } from '@babylonjs/core/Maths/math.vector';
-import { get, isEmpty, isNumber, isString } from 'lodash-es';
+import { capitalize, get, isEmpty, isNumber, isString } from 'lodash-es';
 
 /**
  * This `Parameter` class defines all parameters that can be consumed and committed by a {@link ParameterObservable}.
@@ -320,35 +320,46 @@ export class Parameter {
    * The {@link ParameterDeclarations} for all parameters in this class.
    */
   public static get declarations(): ParameterDeclarations {
-    const declarations: ParameterDeclarations = {};
-    declarations[Parameter.VISIBLE] = { type: 'boolean', parser: Parameter.parseBoolean };
-    declarations[Parameter.SCALING] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.POSITION] = { type: 'vector', parser: Parameter.parseVector };
-    declarations[Parameter.ROTATION] = { type: 'vector', parser: Parameter.parseVector };
-    declarations[Parameter.HIGHLIGHTED] = { type: 'boolean', parser: Parameter.parseBoolean };
-    declarations[Parameter.MATERIAL] = { type: 'string' };
-    declarations[Parameter.MATERIAL_COLOR] = { type: 'color', parser: Parameter.parseColor };
-    declarations[Parameter.MATERIAL_METALLNESS] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.MATERIAL_ROUGHNESS] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.HIGHLIGHT_ENABLED] = { type: 'boolean', parser: Parameter.parseBoolean };
-    declarations[Parameter.HIGHLIGHT_COLOR] = { type: 'color', parser: Parameter.parseColor };
-    declarations[Parameter.HIGHLIGHTED] = { type: 'boolean', parser: Parameter.parseBoolean };
-    declarations[Parameter.CAST_SHADOW] = { type: 'boolean', parser: Parameter.parseBoolean };
-    declarations[Parameter.CAST_SHADOW_FROM_LIGHTS] = { type: 'csl', parser: Parameter.parseCommaSeparatedList };
-    declarations[Parameter.RECEIVE_SHADOWS] = { type: 'boolean', parser: Parameter.parseBoolean };
-    declarations[Parameter.INTENSITY] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.DIRECTION] = { type: 'vector', parser: Parameter.parseVector };
-    declarations[Parameter.ANGLE] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.EXPONENT] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.DIFFUSE] = { type: 'color', parser: Parameter.parseColor };
-    declarations[Parameter.SPECULAR] = { type: 'color', parser: Parameter.parseColor };
-    declarations[Parameter.ENVIRONMENT] = { type: 'string' };
-    declarations[Parameter.ENVIRONMENT_COLOR] = { type: 'color', parser: Parameter.parseColor };
-    declarations[Parameter.ENVIRONMENT_ROTATION] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.ENVIRONMENT_INTENSITY] = { type: 'number', parser: Parameter.parseNumber };
-    declarations[Parameter.ENVIRONMENT_BACKGROUND] = { type: 'string' };
-    declarations[Parameter.ENVIRONMENT_USEDEFAULT] = { type: 'boolean', parser: Parameter.parseBoolean };
-    return declarations;
+    return {
+      [Parameter.VISIBLE]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.SCALING]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.POSITION]: { type: 'vector', parser: Parameter.parseVector },
+      [Parameter.ROTATION]: { type: 'vector', parser: Parameter.parseVector },
+      [Parameter.HIGHLIGHTED]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.MATERIAL]: { type: 'string' },
+      [Parameter.MATERIAL_COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.MATERIAL_METALLNESS]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.MATERIAL_ROUGHNESS]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.HIGHLIGHT_ENABLED]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.HIGHLIGHT_COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.HIGHLIGHTED]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.CAST_SHADOW]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.CAST_SHADOW_FROM_LIGHTS]: { type: 'csl', parser: Parameter.parseCommaSeparatedList },
+      [Parameter.RECEIVE_SHADOWS]: { type: 'boolean', parser: Parameter.parseBoolean },
+      [Parameter.INTENSITY]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.DIRECTION]: { type: 'vector', parser: Parameter.parseVector },
+      [Parameter.ANGLE]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.EXPONENT]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.DIFFUSE]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.SPECULAR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.ENVIRONMENT]: { type: 'string' },
+      [Parameter.ENVIRONMENT_COLOR]: { type: 'color', parser: Parameter.parseColor },
+      [Parameter.ENVIRONMENT_ROTATION]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.ENVIRONMENT_INTENSITY]: { type: 'number', parser: Parameter.parseNumber },
+      [Parameter.ENVIRONMENT_BACKGROUND]: { type: 'string' },
+      [Parameter.ENVIRONMENT_USEDEFAULT]: { type: 'boolean', parser: Parameter.parseBoolean },
+    };
+  }
+
+  /**
+   * The default {@link ParameterValue}s returned as {@link ParameterBag} for a set of parameters in this class.
+   */
+  public static get defaultValues(): ParameterBag {
+    return {
+      [Parameter.SCALING]: '(1, 1, 1)',
+      [Parameter.POSITION]: '(0, 0, 0)',
+      [Parameter.ROTATION]: '(0, 0, 0)',
+    };
   }
 
   /**
@@ -358,6 +369,13 @@ export class Parameter {
     return Parameter.declarations[parameter];
   }
 
+  /**
+   * Gets the default {@link ParameterValue} for a given {@link Parameter} declared in this class.
+   */
+  public static getDefaultValue(parameter: string): ParameterValue {
+    return Parameter.defaultValues[parameter];
+  }
+
   /**
    * All parameters defined in this class.
    */
@@ -372,6 +390,36 @@ export class Parameter {
     return all;
   }
 
+  /**
+   * Asserts whether given parameter is declared and valid.
+   */
+  public static assertParameter(parameterDeclaration: ParameterDeclarations, parameter: string, value: ParameterValue) {
+    if (!(parameter in parameterDeclaration)) {
+      // This is a valid case since we are not able to check parameters that are not declared.
+      // We just ignore parameters that are not declared.
+      return;
+    }
+    const declaration = parameterDeclaration[parameter];
+    const genericError = `"${value}" is not a valid value for parameter "${parameter}" of type "${declaration.type}".`;
+    if (declaration.parser) {
+      try {
+        declaration.parser(value);
+      } catch (e: any) {
+        throw Error(`${genericError} ${e.message}`);
+      }
+    }
+    switch (declaration.type) {
+      case 'select':
+        if (!declaration.options) {
+          throw Error(`No options defined for parameter declaration "${parameter}" of type "${declaration.type}".`);
+        }
+        if (declaration.options.indexOf(value) === -1) {
+          throw Error(genericError + ` Valid values are: "${declaration.options.join('", "')}".`);
+        }
+        break;
+    }
+  }
+
   /**
    * Parses given {@link ParameterBag} with given {@link ParameterDeclarations}.
    */
@@ -453,16 +501,25 @@ export class Parameter {
    * Parses a string of format `'#rrggbb'` or `'(r,g,b)'` to a `Color3`.
    */
   public static parseColor(value: ParameterValue): Color3 {
-    let cleanedValue = value.toString().split(' ').join('');
+    const cleanedValue = value.toString().split(' ').join('');
     if (cleanedValue.startsWith('#')) {
       return Color3.FromHexString(value.toString());
     }
     if (cleanedValue.startsWith('(') && cleanedValue.endsWith(')')) {
-      cleanedValue = cleanedValue.substring(1, cleanedValue.length - 1);
-      const [r, g, b] = cleanedValue.split(',').map(value => parseFloat(value));
+      const rgb = cleanedValue.substring(1, cleanedValue.length - 1);
+      const [r, g, b] = rgb.split(',').map(value => parseFloat(value));
       return Color3.FromInts(r, g, b);
     }
-    throw new Error(`Unable to parse "${value}" to a Color: expected "#rrggbb" or "(r,g,b)".`);
+    const humanReadable = capitalize(cleanedValue);
+    // disable lint for this rule as there is no smoother option for checking static class functions (eg Color.Red())
+    // eslint-disable-next-line no-prototype-builtins
+    if (Color3.hasOwnProperty(humanReadable)) {
+      // @ts-ignore same as above
+      return Color3[humanReadable]();
+    }
+    throw new Error(
+      `Unable to parse "${value}" to a Color: expected "#rrggbb", "(r,g,b)" or any human readable property implemented in Color3.`
+    );
   }
 
   /**

package/src/api/classes/parameterObservable.ts

@@ -1,5 +1,6 @@
 import { uuidv4 } from '../util/stringHelper';
 import { EventBroadcaster } from './eventBroadcaster';
+import { Parameter } from './parameter';
 import { merge } from 'lodash-es';
 
 export abstract class ParameterObservable extends EventBroadcaster {
@@ -67,34 +68,6 @@ export abstract class ParameterObservable extends EventBroadcaster {
    * Asserts whether given parameter is declared and valid.
    */
   public assertParameter(parameterDeclaration: ParameterDeclarations, parameter: string, value: ParameterValue) {
-    if (!(parameter in parameterDeclaration)) {
-      // This is a valid case since we are not able to check parameters that are not declared.
-      // We just ignore parameters that are not declared.
-      return;
-    }
-    const declaration = parameterDeclaration[parameter];
-    const genericError =
-      `"${value}" is not a valid value for parameter "${parameter}" of type. ` +
-      `"${declaration.type}" for ${this.constructor.name} "${this.id}".`;
-    if (declaration.parser) {
-      try {
-        declaration.parser(value);
-      } catch (e: any) {
-        throw Error(genericError + e.message);
-      }
-    }
-    switch (declaration.type) {
-      case 'select':
-        if (!declaration.options) {
-          throw Error(
-            `No options defined for parameter declaration "${parameter}"` +
-              `of type "${declaration.type}" for ${this.constructor.name} "${this.id}".`
-          );
-        }
-        if (declaration.options.indexOf(value) === -1) {
-          throw Error(genericError + ` Valid values are: "${declaration.options.join('", "')}".`);
-        }
-        break;
-    }
+    Parameter.assertParameter(parameterDeclaration, parameter, value);
   }
 }

package/src/api/classes/variant.ts

@@ -1,4 +1,10 @@
-import { deactivateTransformNode, getDottedPathForNode, injectNodeMetadata } from '../util/babylonHelper';
+import {
+  deactivateTransformNode,
+  getDottedPathForNode,
+  injectNodeMetadata,
+  intersectingNodeNames,
+  reportDuplicateNodeNames,
+} from '../util/babylonHelper';
 import { loadJson, mergeMaps } from '../util/resourceHelper';
 import { DottedPath } from './dottedPath';
 import { Element } from './element';
@@ -58,6 +64,7 @@ export class Variant extends Parameterizable {
    * Constructor.
    */
   protected constructor(
+    protected readonly _variantInstance: VariantInstance | null,
     public readonly name: string,
     protected readonly _structureJson: StructureJson,
     public readonly viewer: Viewer,
@@ -73,18 +80,26 @@ export class Variant extends Parameterizable {
     this.structureJson = cloneDeep(_structureJson);
   }
 
+  /**
+   * Creates the root {@link Variant}.
+   */
+  public static async createRoot(structureJson: StructureJson, viewer: Viewer): Promise<Variant> {
+    return Variant.create(null, '_', structureJson, viewer);
+  }
+
   /**
    * Creates a {@link Variant} based on given parameters.
    *
    * @throws Error if "gltf" property is provided without a filename
    */
   public static async create(
+    variantInstance: VariantInstance | null,
     name: string,
     structureJson: StructureJson,
     viewer: Viewer,
     parent?: Variant
   ): Promise<Variant> {
-    const variant = new Variant(name, structureJson, viewer, parent);
+    const variant = new Variant(variantInstance, name, structureJson, viewer, parent);
     await variant.loadAssets();
     return variant;
   }
@@ -120,6 +135,15 @@ export class Variant extends Parameterizable {
     return DottedPath.createFromParts(parentIds).addPart(this.name);
   }
 
+  /**
+   * Gets the {@link VariantInstance} this variant was created for. There are variants without an instance (the "ghost"
+   * ones used for bootstrapping instances). The usage of {@link Variant}s without an instance is an absolute edge-case
+   * when deeply using the viewer api and working abroad best practices.
+   */
+  get variantInstance(): VariantInstance | null {
+    return this._variantInstance;
+  }
+
   /**
    * The id representing a {@link DottedPath}.
    */
@@ -205,6 +229,20 @@ export class Variant extends Parameterizable {
     return this.assetContainer.materials;
   }
 
+  /**
+   * The cloned TransformNodes of all {@link Element}s created for this {@link Variant}.
+   */
+  get elementNodes(): TransformNode[] {
+    return this.elements.reduce((a, c) => a.concat(c.nodes), [] as TransformNode[]);
+  }
+
+  /**
+   * The cloned TransformNodes of all {@link Element}s created for this {@link Variant} flattened.
+   */
+  get elementNodesFlat(): TransformNode[] {
+    return this.elements.reduce((a, c) => [...a, ...c.nodesFlat], [] as TransformNode[]);
+  }
+
   /**
    * All {@link Element}s from this {@link Variant}'s parents.
    */
@@ -325,9 +363,21 @@ export class Variant extends Parameterizable {
       }
       if (this.structureJson.variants[name].file) {
         const file = this.structureJson.variants[name].file as string;
-        variant = await Variant.create(name, await loadJson<StructureJson>(file), this.viewer, this);
+        variant = await Variant.create(
+          this.variantInstance,
+          name,
+          await loadJson<StructureJson>(file),
+          this.viewer,
+          this
+        );
       } else {
-        variant = await Variant.create(name, this.structureJson.variants[name], this.viewer, this);
+        variant = await Variant.create(
+          this.variantInstance,
+          name,
+          this.structureJson.variants[name],
+          this.viewer,
+          this
+        );
       }
       this._children.set(name, variant);
     }
@@ -426,9 +476,9 @@ export class Variant extends Parameterizable {
    * @emit {@link Event.VARIANT_CREATED}
    * @ignore
    */
-  public async createLiving(parameters?: ParameterBag): Promise<Variant> {
-    const parent = await this.parent?.createLiving();
-    const variant = new Variant(this.name, this._structureJson, this.viewer, parent);
+  public async createLiving(variantInstance: VariantInstance, parameters?: ParameterBag): Promise<Variant> {
+    const parent = await this.parent?.createLiving(variantInstance);
+    const variant = new Variant(variantInstance, this.name, this._structureJson, this.viewer, parent);
     parent?._children.set(variant.name, variant);
     variant.assetContainer = this.assetContainer;
     variant.parameterObservers = cloneDeep(this.parameterObservers);
@@ -436,7 +486,7 @@ export class Variant extends Parameterizable {
     await variant.createViewerLights();
     variant.addParameterObservers();
     await variant.bootstrapParameters(parameters);
-    this.broadcastEvent(Event.VARIANT_CREATED, variant);
+    this.viewer.broadcastEvent(Event.VARIANT_CREATED, variant);
     return variant;
   }
 
@@ -589,8 +639,7 @@ export class Variant extends Parameterizable {
    */
   protected async loadAssets(): Promise<Variant> {
     this.broadcastEvent(Event.ASSET_LOADING_START, this);
-
-    const promisifiedLoader = new Promise<Variant>((resolve, reject) => {
+    return new Promise<Variant>(resolve => {
       if (!this.structureJson) {
         this.broadcastEvent(Event.ASSET_LOADING_END, this);
         return resolve(this);
@@ -607,18 +656,21 @@ export class Variant extends Parameterizable {
         container => {
           this.assetContainer = container;
           const nodes = this.assetContainer.getNodes().filter(n => n instanceof TransformNode) as TransformNode[];
+          reportDuplicateNodeNames(
+            intersectingNodeNames(nodes, this.viewer.scene.getNodes(), n => n instanceof TransformNode)
+          );
           nodes.forEach(node => {
             deactivateTransformNode(node, false);
-            injectNodeMetadata(node, { dottedPath: getDottedPathForNode(node) }, false);
+            injectNodeMetadata(node, { dottedPath: getDottedPathForNode(node), originalName: node.name }, false);
           });
           this.assetContainer.lights.forEach(light => {
             light.setEnabled(false);
-            injectNodeMetadata(light, { dottedPath: getDottedPathForNode(light) }, false);
+            injectNodeMetadata(light, { dottedPath: getDottedPathForNode(light), originalName: light.name }, false);
             this.viewer.scene.addLight(light);
           });
           this.assetContainer.cameras.forEach(camera => {
             camera.setEnabled(false);
-            injectNodeMetadata(camera, { dottedPath: getDottedPathForNode(camera) }, false);
+            injectNodeMetadata(camera, { dottedPath: getDottedPathForNode(camera), originalName: camera.name }, false);
             this.viewer.scene.addCamera(camera);
           });
           this.assetContainer.materials.forEach(material => this.viewer.scene.materials.push(material));
@@ -634,7 +686,6 @@ export class Variant extends Parameterizable {
         }
       );
     });
-    return await promisifiedLoader;
   }
 
   /**
@@ -758,71 +809,71 @@ export class Variant extends Parameterizable {
    */
   protected addParameterObservers(): Variant {
     this._parameterObservers.set(Parameter.VISIBLE, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.VISIBLE, newValue);
         await variant.commitParameterToViewerLights(Parameter.VISIBLE, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.SCALING, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.SCALING, newValue);
         await variant.commitParameterToViewerLights(Parameter.SCALING, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.MATERIAL, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.MATERIAL, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.MATERIAL_COLOR, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.MATERIAL_COLOR, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.MATERIAL_METALLNESS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.MATERIAL_METALLNESS, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.MATERIAL_ROUGHNESS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.MATERIAL_ROUGHNESS, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.HIGHLIGHT_COLOR, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.HIGHLIGHT_COLOR, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.HIGHLIGHTED, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.HIGHLIGHTED, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.POSITION, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.POSITION, newValue);
         await variant.commitParameterToViewerLights(Parameter.POSITION, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.ROTATION, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.ROTATION, newValue);
         await variant.commitParameterToViewerLights(Parameter.ROTATION, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.CAST_SHADOW, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.CAST_SHADOW, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.CAST_SHADOW_FROM_LIGHTS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.CAST_SHADOW_FROM_LIGHTS, newValue);
       },
     ]);
     this._parameterObservers.set(Parameter.RECEIVE_SHADOWS, [
-      async (variant: Variant, oldValue: ParameterValue, newValue: ParameterValue) => {
+      async (variant: Variant, oldValue: Undefinable<ParameterValue>, newValue: ParameterValue) => {
         await variant.commitParameterToElements(Parameter.RECEIVE_SHADOWS, newValue);
       },
     ]);
@@ -832,18 +883,16 @@ export class Variant extends Parameterizable {
   /**
    * Creates {@link Element}s and clones nodes into them.
    */
-  protected async createElements(): Promise<Variant> {
+  protected async createElements(forInstance?: string): Promise<Variant> {
     this.createElementDefinitionsIfNotExist();
     for (const name in this.structureJson.elements || {}) {
       this.elements.push(await Element.create(this, name));
     }
     // inject node meta to all inherited elements
     // we do this to inject the deepest and most concrete variant information to all cloned nodes in the tree
-    this.inheritedElements.forEach(element => {
-      element.nodes.forEach(node => {
-        injectNodeMetadata(node, { variant: this, variantParameterizable: element });
-      });
-    });
+    this.inheritedElements.forEach(element =>
+      element.nodes.forEach(node => injectNodeMetadata(node, { variant: this, variantParameterizable: element }))
+    );
     return this;
   }
 

package/src/api/classes/variantInstance.ts

@@ -9,13 +9,29 @@ import { Mesh } from '@babylonjs/core/Meshes/mesh';
  * Class VariantInstance.
  */
 export class VariantInstance extends EventBroadcaster {
+  protected _variant: Variant | null = null;
+
   /**
    * Constructor
    */
-  public constructor(public variant: Variant, public name: string) {
+  protected constructor(public name: string) {
     super();
   }
 
+  /**
+   * Creates a living clone of the given source {@link Variant} and instances a {@link VariantInstance} with given name
+   * and {@link ParameterBag}.
+   */
+  public static async createLiving(
+    sourceVariant: Variant,
+    name: string,
+    parameters?: ParameterBag
+  ): Promise<VariantInstance> {
+    const variantInstance = new VariantInstance(name);
+    variantInstance._variant = await sourceVariant.createLiving(variantInstance, parameters);
+    return variantInstance;
+  }
+
   /**
    * WORK IN PROGRESS
    */
@@ -47,6 +63,16 @@ public translate(
 }
   */
 
+  /**
+   * Gets the {@link Variant} attached to the {@link VariantInstance}.
+   */
+  get variant(): Variant {
+    if (!this._variant) {
+      throw new Error(`Variant has not been properly set for instance.`);
+    }
+    return this._variant;
+  }
+
   /**
    * A proxy for {@link Variant.getElement}.
    */