@combeenation/3d-viewer 4.0.0-beta4 → 4.0.0-beta5

package/src/api/classes/variant.ts

@@ -1,670 +1,817 @@
-import { AssetContainer } from '@babylonjs/core/assetContainer';
-import '@babylonjs/core/Loading/Plugins/babylonFileLoader';
-import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
-import { Material } from '@babylonjs/core/Materials/material';
-import { Mesh } from '@babylonjs/core/Meshes/mesh';
-import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_transform';
-import '@babylonjs/loaders/glTF/2.0/glTFLoader';
-import { cloneDeep, concat, isEmpty, isEqual, isString, merge } from 'lodash-es';
-import {
-	deactivateTransformNode,
-	getDottedPathForTransformNode,
-	injectTransformNodeMetadata
-} from '../util/babylonHelper';
-import { loadJson, mergeMaps } from '../util/resourceHelper';
-import { DottedPath } from './dottedPath';
-import { Element } from './element';
-import { ElementParameterizable } from './elementParameterizable';
-import { Event } from './event';
-import { Parameter } from './parameter';
-import { Viewer } from './viewer';
-
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_basisu';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_clearcoat';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_sheen';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_ior';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_pbrSpecularGlossiness';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_specular';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_translucency';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_transmission';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_unlit';
-import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_variants';
-
-/**
- * A concrete "Variant". Most of these are handled by either the {@link Viewer} or {@link VariantInstance}.
- */
-export class Variant extends ElementParameterizable {
-
-	public assetContainer: AssetContainer;
-
-	public readonly elements: Element[] = [];
-
-	public structureJson: StructureJson;
-
-	protected _dottedNodes: Map<DottedPath, TransformNode> | undefined;
-
-	protected readonly _children: Map<string, Variant> = new Map();
-
-	protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
-
-	/**
-	 * @internal
-	 */
-	private parametersInitialized: boolean = false;
-
-	/**
-	 * Constructor.
-	 */
-	protected constructor( public readonly name: string,
-	                       protected readonly _structureJson: StructureJson,
-	                       public readonly viewer: Viewer,
-	                       public readonly parent?: Variant ) {
-		super(
-			cloneDeep( _structureJson.parameterDeclaration ),
-			cloneDeep( _structureJson.parameters )
-		);
-		for( const parameter in _structureJson.parameterDeclaration ) {
-			if( !(parameter in (_structureJson.parameters || [])) ) {
-				throw new Error( `No default value for parameter "${parameter}" defined.` );
-			}
-		}
-		this.assetContainer = new AssetContainer( viewer.scene );
-		this.structureJson = cloneDeep( _structureJson );
-	}
-
-	/**
-	 * Creates a {@link Variant} based on given parameters.
-	 *
-	 * @throws Error if "gltf" property is provided without a filename
-	 */
-	public static async create( name: string,
-	                            structureJson: StructureJson,
-	                            viewer: Viewer,
-	                            parent?: Variant ): Promise<Variant> {
-		const variant = new Variant( name, structureJson, viewer, parent );
-		await variant.loadAssets();
-		return variant;
-	}
-
-	/**
-	 * The ancestor {@link Variant}s ordered from top to bottom in the built tree.
-	 */
-	get ancestors(): Variant[] {
-		const ancestors = [];
-		let variant: Variant = this;
-		while( variant.parent ) {
-			ancestors.unshift( variant.parent );
-			variant = variant.parent;
-		}
-		return ancestors;
-	}
-
-	/**
-	 * The root {@link Variant}.
-	 */
-	get root(): Variant {
-		return this.ancestors[0] ?? this;
-	}
-
-	/**
-	 * The {@link DottedPath} in the built tree of {@link Variant}s.
-	 * E.g. "_.top-1.sub-2.sub-sub-3"
-	 */
-	get dottedPath(): DottedPath {
-		const parentIds = this.ancestors.map( ancestor => {
-			return ancestor.name;
-		} );
-		return DottedPath.createFromParts( parentIds ).addPart( this.name );
-	}
-
-	/**
-	 * The id representing a {@link DottedPath}.
-	 */
-	get id(): string {
-		const dottedPath = DottedPath.create( this.dottedPath );
-		dottedPath.shiftPart();  // remove root
-		return dottedPath.path || '_';
-	}
-
-	/**
-	 * The defined glTF Asset.
-	 */
-	get glTF(): Asset | undefined {
-		if( this.structureJson.glTF ) {
-			if( isString( this.structureJson.glTF ) ) {
-				return {
-					rootUrl: this.structureJson.glTF,
-					fileName: undefined
-				};
-			}
-			if( isEmpty( this.structureJson.glTF.rootUrl ) ) {
-				throw new Error( `No "rootUrl" defined in "glTF" definition for variant "${this.id}".` );
-			}
-			return this.structureJson.glTF;
-		}
-	}
-
-	/**
-	 * The defined glTF URI.
-	 */
-	get glTFUri(): string | undefined {
-		if( this.glTF ) {
-			return [this.glTF.rootUrl, this.glTF.fileName].join( '' );
-		}
-	}
-
-	/**
-	 * The inherited defined glTF URI.
-	 */
-	get inheritedGlTFUri(): string | undefined {
-		if( !this.glTFUri && this.parent ) {
-			return this.parent.inheritedGlTFUri;
-		}
-		return this.glTFUri;
-	}
-
-	/**
-	 * The TransformNodes of the {@link Variant}.
-	 */
-	get nodes(): TransformNode[] {
-		const rootNodes = this.assetContainer.getNodes().filter(
-			n => n instanceof TransformNode && !n.parent
-		) as TransformNode[];
-		return rootNodes;
-	}
-
-	/**
-	 * All TransformNodes of the {@link Variant} mapped flat with a {@link DottedPath}.
-	 */
-	get dottedNodes(): Map<DottedPath, TransformNode> {
-		if( ! this._dottedNodes ) {
-			const nodes = this.assetContainer.getNodes().filter( n => n instanceof TransformNode );
-			const dottedNodes = new Map();
-			nodes.forEach( node => {
-				dottedNodes.set( node.metadata.dottedPath, node );
-			} );
-			this._dottedNodes = dottedNodes;
-		}
-		return this._dottedNodes;
-	}
-
-	/**
-	 * The Materials of the {@link Variant}.
-	 */
-	get materials(): Material[] {
-		return this.assetContainer.materials;
-	}
-
-	/**
-	 * All {@link Element}s from this {@link Variant}'s parents.
-	 */
-	get inheritedElements(): Element[] {
-		let elements: Element[] = [];
-		this.ancestors.forEach( ancestor => {
-			elements = concat( elements, ancestor.elements );
-		} );
-		return concat( elements, this.elements );
-	}
-
-	/**
-	 * All TransformNodes inherited from this {@link Variant}'s parents.
-	 */
-	get inheritedNodes(): TransformNode[] {
-		let nodes: TransformNode[] = [];
-		this.ancestors.forEach( ancestor => {
-			nodes = concat( nodes, ancestor.nodes );
-		} );
-		return concat( nodes, this.nodes );
-	}
-
-	/**
-	 * All TransformNodes inherited from this {@link Variant}'s parents mapped flat with a {@link DottedPath}.
-	 */
-	get inheritedDottedNodes(): Map<DottedPath, TransformNode> {
-		let dottedNodes = this.dottedNodes;
-		this.ancestors.forEach( ancestor => {
-			dottedNodes = mergeMaps( dottedNodes, ancestor.dottedNodes );
-		} );
-		return dottedNodes;
-	}
-
-	/**
-	 * The {@link ParameterDeclarations} inherited from this {@link Variant}'s parents.
-	 */
-	get inheritedParameterDeclaration(): ParameterDeclarations {
-		let declaration = {};
-		this.ancestors.forEach( ancestor => {
-			merge( declaration, ancestor.parameterDeclaration );
-		} );
-		return merge( declaration, this.parameterDeclaration );
-	}
-
-	/**
-	 * The {@link ParameterBag} inherited from this {@link Variant}'s parents.
-	 */
-	get inheritedParameters(): ParameterBag {
-		let parameters = {};
-		this.ancestors.forEach( ancestor => {
-			merge( parameters, ancestor.parameters );
-		} );
-		return merge( parameters, this.parameters );
-	}
-
-	/**
-	 * All Materials from this {@link Variant}'s parents.
-	 */
-	get inheritedMaterials(): Material[] {
-		let materials: Material[] = [];
-		this.ancestors.forEach( ancestor => {
-			materials = concat( materials, ancestor.materials );
-		} );
-		return concat( materials, this.materials );
-	}
-
-	/**
-	 * Gets the direct children of the current {@link Variant}.
-	 */
-	public async getChildren(): Promise<Variant[]> {
-		const children: Variant[] = [];
-		for( const name in this.structureJson.variants ) {
-			children.push( await this.getDescendant( name ) );
-		}
-		return children;
-	}
-
-	/**
-	 *  Gets a descendant {@link Variant} of the current {@link Variant} relative to its {@link DottedPath}.
-	 *  If you have the dotted path `_.product_x.variant_blue.with_yellow_highlight` in a tree and you operate on the
-	 *  `product_x`, you can call `this.getDescendant('variant_blue.with_yellow_highlight')` to get the lowermost
-	 *  {@link Variant}.
-	 */
-	public async getDescendant( dottedPath: DottedPathArgument ): Promise<Variant> {
-		const _dottedPath = DottedPath.create( dottedPath );
-		const [name, ...descendantParts] = _dottedPath.parts;
-		let variant;
-		if( this._children.has( name ) ) {
-			variant = this._children.get( name );
-		} else {
-			if( !this.structureJson.variants ) {
-				throw new Error( `Missing key "variants" in JSON structure for variant "${this.id}".` );
-			}
-			if( !this.structureJson.variants[name] ) {
-				throw new Error( `Variant "${_dottedPath.path}" not defined in JSON structure for variant "${this.id}".` );
-			}
-			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 );
-			} else {
-				variant = await Variant.create( name, this.structureJson.variants[name], this.viewer, this );
-			}
-			this._children.set( name, variant );
-		}
-		if( !variant ) {
-			throw new Error( `Variant "${_dottedPath.path}" was not created.` );
-		}
-		if( descendantParts.length > 0 ) {
-			return await variant.getDescendant( DottedPath.createFromParts( descendantParts ) );
-		}
-		return variant;
-	}
-
-	/**
-	 * Gets the desired {@link Element} of the current {@link Variant} relative to its {@link DottedPath}.
-	 * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
-	 */
-	public async getElement( dottedPath: DottedPathArgument ): Promise<Element> {
-		const _dottedPath = DottedPath.create( dottedPath );
-		const elementName = _dottedPath.popPart();
-		let variant: Variant = this;
-		if( _dottedPath.parts.length > 0 ) {
-			variant = await this.getDescendant( _dottedPath );
-		}
-		if( variant.inheritedElements.length === 0 ) {
-			throw new Error( `No elements for variant "${variant.id}" found. ` +
-				`Either none are defined or they are not initialized (are you operating on the appropriate living?).` );
-		}
-		let element;
-		variant.inheritedElements.forEach( _element => {
-			if( _element.name === elementName ) {
-				element = _element;
-			}
-		} );
-		if( !element ) {
-			throw new Error( `Element with name "${elementName}" does not exist for variant "${variant.id}".` );
-		}
-		return element;
-	}
-
-	/**
-	 * A proxy for directly getting a Node from an {@link Element} by its {@link DottedPath}s.
-	 */
-	public async getNode( elementDottedPath: DottedPathArgument, nodeDottedPath: DottedPathArgument ): Promise<TransformNode> {
-		const element = await this.getElement( elementDottedPath );
-		return element.getNode( nodeDottedPath );
-	}
-
-	/**
-	 * A proxy for directly getting a Mesh from an {@link Element} by its {@link DottedPath}s.
-	 */
-	public async getMesh( elementDottedPath: DottedPathArgument, meshDottedPath: DottedPathArgument ): Promise<Mesh|null> {
-		const element = await this.getElement( elementDottedPath );
-		return element.getMesh( meshDottedPath );
-	}
-
-	/**
-	 * Gets the Material defined in one of the variants glTFs by its id.
-	 */
-	public getMaterial( id: string ): Material {
-		for( const material of this.inheritedMaterials ) {
-			if( material.id === id ) {
-				return material;
-			}
-		}
-		// fallback to dynamically created materials on scene
-		for( const material of this.viewer.scene.materials ) {
-			if( material.id === id ) {
-				return material;
-			}
-		}
-		throw new Error( `Material with id "${id}" does not exist for variant "${this.id}".` );
-	}
-
-	/**
-	 * Creates a living clone of this {@link Variant}. Will clone all parent {@link Variant}s in tree.
-	 *
-	 * @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 );
-		parent?._children.set( variant.name, variant );
-		variant.assetContainer = this.assetContainer;
-		variant.parameterObservers = cloneDeep( this.parameterObservers );
-		variant.createElements();
-		variant.addParameterObservers();
-		await variant.bootstrapParameters( parameters );
-		this.broadcastEvent( Event.VARIANT_CREATED, variant );
-		return variant;
-	}
-
-	/**
-	 * Destroys this {@link Variant}, all parents and destroy the {@link Element}s.
-	 */
-	public destroy(): Variant {
-		this.elements.forEach( element => element.destroy() );
-		if( this.parent ) {
-			this.parent.destroy();
-		}
-		this.broadcastEvent( Event.VARIANT_DESTROYED, this );
-		return this;
-	}
-
-	/**
-	 * Places the given {@link ParameterBag} in the {@link Variant}'s parameters, replaces all patterns in the
-	 * {@link StructureJson}, broadcasts all {@link ParameterObserver}s and delegates them to its {@link Element}s.
-	 *
-	 * @emit {@link Event.VARIANT_PARAMETER_COMMITTED}
-	 */
-	public async commitParameters( parameters?: ParameterBag ): Promise<Variant> {
-		parameters = merge( {}, parameters );
-
-		// remember old parameter values for later comparison
-		const oldParameters = cloneDeep( this.inheritedParameters );
-
-		// replace patterns in given parameters
-		let _parameters = JSON.stringify( parameters );
-		for( const parameter in this.inheritedParameters ) {
-			const value = this.inheritedParameters[parameter];
-			const search = new RegExp( `\\$\\{${parameter}\\}`, 'g' );
-			_parameters = _parameters.replace( search, value.toString() );
-		}
-		merge( parameters, JSON.parse( _parameters ) );
-
-		// merge inherited parameters and replaced given parameters
-		const mergedParameters = merge( {}, this.inheritedParameters, parameters );
-
-		// replace patterns in structure parameters
-		const structureParameters = this._structureJson.parameters || {};
-		let _structureParameters = JSON.stringify( structureParameters );
-		for( const parameter in mergedParameters ) {
-			const value = mergedParameters[parameter];
-			const search = new RegExp( `\\$\\{${parameter}\\}`, 'g' );
-			_structureParameters = _structureParameters.replace( search, value.toString() );
-		}
-		const replacedStructureParameters = JSON.parse( _structureParameters );
-
-		// calculate which replaced structure parameters have changed and should overload given parameters
-		const differentStructureParameters: ParameterBag = {};
-		for( const parameter in replacedStructureParameters ) {
-			if( !isEqual(structureParameters[parameter], replacedStructureParameters[parameter]) ) {
-				differentStructureParameters[parameter] = replacedStructureParameters[parameter];
-			}
-		}
-
-		// merge replaced structure parameters and given inherited parameters to structure parameters
-		merge( this.parameters, mergedParameters, differentStructureParameters );
-
-		// inherited parameters are now the new parameters to process
-		const newParameters = this.inheritedParameters;
-
-		// replace all parameter patterns in structure json
-		let structure = JSON.stringify( this._structureJson );
-		for( const parameter in newParameters ) {
-			const value = newParameters[parameter];
-			const search = new RegExp( `\\$\\{${parameter}\\}`, 'g' );
-			structure = structure.replace( search, value.toString() );
-		}
-		this.structureJson = JSON.parse( structure );
-
-		// handle parameter observers
-		let observerPromises: Promise<void | ParameterObserver>[] = [];
-		for( const parameter in newParameters ) {
-			const oldParameterValue = oldParameters[parameter];
-			const newParameterValue = newParameters[parameter];
-			this.assertParameter( this.inheritedParameterDeclaration, parameter, newParameterValue );
-			if( oldParameterValue === newParameterValue && this.parametersInitialized ) {
-				continue;
-			}
-			// parameter changed
-			const parameterObservers = mergeMaps( this._parameterObservers, this.parameterObservers );
-			if( parameterObservers.has( parameter ) ) {
-				const observers = parameterObservers.get( parameter )!;
-				observerPromises = concat(observerPromises, observers.map( observer => {
-					const observerResult = observer( this, oldParameterValue, newParameterValue );
-					return Promise.resolve( observerResult ).then( () => {
-						if( this.parametersInitialized ) {
-							this.broadcastEvent( Event.VARIANT_PARAMETER_COMMITTED,
-								this, parameter, oldParameterValue, newParameterValue );
-						}
-					} );
-				} ) );
-			}
-		}
-		await Promise.all( observerPromises );
-
-		// broadcast that bag has been committed
-		this.broadcastEvent(Event.VARIANT_PARAMETER_BAG_COMMITTED, this, oldParameters, newParameters);
-
-		// commit parameters to elements
-		const elementPromises: Promise<Element>[] = this.elements.map( element => {
-			let _elementDefinition = JSON.stringify( this._structureJson.elements![element.name] );
-			const elementParameters: ParameterBag = {};
-			for( const parameter in newParameters ) {
-				if( DottedPath.create( parameter ).firstPart !== element.name ) {
-					continue;
-				}
-				// we got an element parameter
-				let newParameterValue = newParameters[parameter];
-				const elementParameter = parameter.replace( `${element.name}.`, '' );
-				// If the variant is explicitly hidden, we must not override the visibility with element parameters. We need
-				// an exception for visibility to avoid overloading already applied element parameters with element parameters
-				// defined in the variant spec ("dotted parameters").
-				// @see https://github.com/Combeenation/3d-viewer/issues/44
-				if( elementParameter === Parameter.VISIBLE && newParameters[Parameter.VISIBLE] === false ) {
-					newParameterValue = false;
-				}
-				elementParameters[elementParameter] = newParameterValue;
-				const search = new RegExp( `\\$\\{${elementParameter}\\}`, 'g' );
-				_elementDefinition = _elementDefinition.replace( search, newParameterValue.toString() );
-			}
-			this.structureJson.elements![this.name] = JSON.parse( _elementDefinition );
-			return element.commitParameters( elementParameters );
-		} );
-		await Promise.all( elementPromises );
-
-		// propagate parameters to parent
-		if( this.parent ) {
-			await this.parent.commitParameters( this.parameters );
-		}
-
-		return this;
-	}
-
-	/**
-	 * Adds an observer function for camera matrix changes for given `dottedPath` representing the {@link Element}
-	 * and the `traceable`. The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
-	 */
-	public async addTraceableObserver( dottedPath: DottedPathArgument,
-	                                   observer: CallableFunction,
-	                                   payload?: any  ): Promise<Element> {
-		const _dottedPath = DottedPath.create( dottedPath );
-		const traceableName = _dottedPath.popPart();
-		if( !traceableName ) {
-			throw new Error( `The dottedPath must consist of the element and the name of the defined corresponding ` +
-				`traceable ("${_dottedPath.path}" given).` );
-		}
-		const element = await this.getElement( _dottedPath );
-		return element.addTraceableObserver( traceableName, observer, payload );
-	}
-
-	/**
-	 * Loads {@link glTFUri} with assets, adds them to the {@link Variant}'s `assetContainer` and deactivates the meshes.
-	 * (for further processing).
-	 * @emits {@link Event.ASSET_LOADING_START}
-	 * @emits {@link Event.ASSET_LOADING_END}
-	 */
-	protected async loadAssets(): Promise<Variant> {
-		this.broadcastEvent( Event.ASSET_LOADING_START, this );
-		return new Promise( resolve => {
-			if( !this.structureJson ) {
-				this.broadcastEvent( Event.ASSET_LOADING_END, this );
-				return resolve( this );
-			}
-			if( !this.glTF ) {
-				this.broadcastEvent( Event.ASSET_LOADING_END, this );
-				return resolve( this );
-			}
-			SceneLoader.LoadAssetContainerAsync( this.glTF.rootUrl, this.glTF.fileName, this.viewer.scene ).then( container => {
-				this.assetContainer = container;
-				const nodes = this.assetContainer.getNodes().filter( n => n instanceof TransformNode ) as TransformNode[];
-				nodes.forEach( node => {
-					deactivateTransformNode( node, false );
-					injectTransformNodeMetadata( node, { dottedPath: getDottedPathForTransformNode( node ) }, false );
-				} );
-				this.broadcastEvent( Event.ASSET_LOADING_END, this );
-				resolve( this );
-			} ).catch( reason => {
-				this.broadcastEvent( Event.ASSET_LOADING_END, this );
-				throw new Error( `Error loading assets for variant "${this.id}": ${reason}.` );
-			} );
-		} );
-	}
-
-	/**
-	 * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
-	 */
-	protected async commitParameterToElements( parameter: string, value: ParameterValue ) {
-		const promises = [];
-		for( const element of this.elements ) {
-			promises.push( element.commitParameter( parameter, value ) );
-		}
-		await Promise.all( promises );
-	}
-
-	/**
-	 * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
-	 */
-	protected addParameterObservers(): Variant {
-		this._parameterObservers.set( Parameter.VISIBLE, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.VISIBLE, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.SCALING, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.SCALING, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.MATERIAL, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL_COLOR, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.MATERIAL_COLOR, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL_METALLNESS, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.MATERIAL_METALLNESS, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.MATERIAL_ROUGHNESS, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.MATERIAL_ROUGHNESS, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.HIGHLIGHT_COLOR, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.HIGHLIGHT_COLOR, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.HIGHLIGHTED, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.HIGHLIGHTED, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.POSITION, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.POSITION, newValue );
-			}
-		] );
-		this._parameterObservers.set( Parameter.ROTATION, [
-			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
-				await variant.commitParameterToElements( Parameter.ROTATION, newValue );
-			}
-		] );
-		return this;
-	}
-
-	/**
-	 * Creates {@link Element}s and clones nodes into them.
-	 */
-	protected createElements(): Variant {
-		for( const elementName in this.structureJson.elements || {} ) {
-			this.elements.push( new Element( this, elementName ) );
-		}
-		// 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 => {
-				injectTransformNodeMetadata( node, { variant: this, element: element } );
-			} );
-		} );
-		return this;
-	}
-
-	/**
-	 * Bootstrapping for parameters. It sets the `parametersInitialized` to true for all ancestors.
-	 */
-	protected async bootstrapParameters( parameters?: ParameterBag ): Promise<Variant> {
-		await this.commitParameters( merge( cloneDeep( this.parameters ), parameters ) );
-		concat( this.ancestors, this ).forEach( ancestor => ancestor.parametersInitialized = true );
-		return this;
-	}
-
-}
+import { AssetContainer } from '@babylonjs/core/assetContainer';
+import { Light } from '@babylonjs/core/Lights/light';
+import '@babylonjs/core/Loading/Plugins/babylonFileLoader';
+import { SceneLoader } from '@babylonjs/core/Loading/sceneLoader';
+import { Material } from '@babylonjs/core/Materials/material';
+import { Mesh } from '@babylonjs/core/Meshes/mesh';
+import { TransformNode } from '@babylonjs/core/Meshes/transformNode';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_draco_mesh_compression';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_transform';
+import '@babylonjs/loaders/glTF/2.0/glTFLoader';
+import { cloneDeep, concat, get, isEmpty, isEqual, isString, merge, set } from 'lodash-es';
+import { deactivateTransformNode, getDottedPathForNode, injectNodeMetadata } from '../util/babylonHelper';
+import { loadJson, mergeMaps } from '../util/resourceHelper';
+import { DottedPath } from './dottedPath';
+import { Element } from './element';
+import { Event } from './event';
+import { Parameter } from './parameter';
+import { Parameterizable } from './parameterizable';
+import { ParameterObservable } from './parameterObservable';
+import { VariantParameterizable } from './variantParameterizable';
+import { Viewer } from './viewer';
+import { ViewerLight } from './viewerLight';
+
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_texture_basisu';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_clearcoat';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_sheen';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_ior';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_pbrSpecularGlossiness';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_specular';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_translucency';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_transmission';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_unlit';
+import '@babylonjs/loaders/glTF/2.0/Extensions/KHR_materials_variants';
+
+/**
+ * A concrete "Variant". Most of these are handled by either the {@link Viewer} or {@link VariantInstance}.
+ */
+export class Variant extends Parameterizable {
+
+	public assetContainer: AssetContainer;
+
+	public readonly elements: Element[] = [];
+
+	public readonly viewerLights: ViewerLight[] = [];
+
+	public structureJson: StructureJson;
+
+	protected _dottedNodes: Map<DottedPath, TransformNode> | undefined;
+
+	protected readonly _children: Map<string, Variant> = new Map();
+
+	protected readonly _parameterObservers: Map<string, ParameterObserver[]> = new Map();
+
+	/**
+	 * @internal
+	 */
+	private parametersInitialized: boolean = false;
+
+	/**
+	 * Constructor.
+	 */
+	protected constructor( public readonly name: string,
+	                       protected readonly _structureJson: StructureJson,
+	                       public readonly viewer: Viewer,
+	                       public readonly parent?: Variant ) {
+		super(
+			cloneDeep( _structureJson.parameterDeclaration ),
+			cloneDeep( _structureJson.parameters )
+		);
+		for( const parameter in _structureJson.parameterDeclaration ) {
+			if( !(parameter in (_structureJson.parameters || [])) ) {
+				throw new Error( `No default value for parameter "${parameter}" defined.` );
+			}
+		}
+		this.assetContainer = new AssetContainer( viewer.scene );
+		this.structureJson = cloneDeep( _structureJson );
+	}
+
+	/**
+	 * Creates a {@link Variant} based on given parameters.
+	 *
+	 * @throws Error if "gltf" property is provided without a filename
+	 */
+	public static async create( name: string,
+	                            structureJson: StructureJson,
+	                            viewer: Viewer,
+	                            parent?: Variant ): Promise<Variant> {
+		const variant = new Variant( name, structureJson, viewer, parent );
+		await variant.loadAssets();
+		return variant;
+	}
+
+	/**
+	 * The ancestor {@link Variant}s ordered from top to bottom in the built tree.
+	 */
+	get ancestors(): Variant[] {
+		const ancestors = [];
+		let variant: Variant = this;
+		while( variant.parent ) {
+			ancestors.unshift( variant.parent );
+			variant = variant.parent;
+		}
+		return ancestors;
+	}
+
+	/**
+	 * The root {@link Variant}.
+	 */
+	get root(): Variant {
+		return this.ancestors[0] ?? this;
+	}
+
+	/**
+	 * The {@link DottedPath} in the built tree of {@link Variant}s.
+	 * E.g. "_.top-1.sub-2.sub-sub-3"
+	 */
+	get dottedPath(): DottedPath {
+		const parentIds = this.ancestors.map( ancestor => {
+			return ancestor.name;
+		} );
+		return DottedPath.createFromParts( parentIds ).addPart( this.name );
+	}
+
+	/**
+	 * The id representing a {@link DottedPath}.
+	 */
+	get id(): string {
+		const dottedPath = DottedPath.create( this.dottedPath );
+		dottedPath.shiftPart();  // remove root
+		return dottedPath.path || '_';
+	}
+
+	/**
+	 * The defined glTF Asset.
+	 */
+	get glTF(): Asset | undefined {
+		if( this.structureJson.glTF ) {
+			if( isString( this.structureJson.glTF ) ) {
+				return {
+					rootUrl: this.structureJson.glTF,
+					fileName: undefined
+				};
+			}
+			if( isEmpty( this.structureJson.glTF.rootUrl ) ) {
+				throw new Error( `No "rootUrl" defined in "glTF" definition for variant "${this.id}".` );
+			}
+			return this.structureJson.glTF;
+		}
+	}
+
+	/**
+	 * The defined glTF URI.
+	 */
+	get glTFUri(): string | undefined {
+		if( this.glTF ) {
+			return [this.glTF.rootUrl, this.glTF.fileName].join( '' );
+		}
+	}
+
+	/**
+	 * The inherited defined glTF URI.
+	 */
+	get inheritedGlTFUri(): string | undefined {
+		if( !this.glTFUri && this.parent ) {
+			return this.parent.inheritedGlTFUri;
+		}
+		return this.glTFUri;
+	}
+
+	/**
+	 * The TransformNodes of the {@link Variant}.
+	 */
+	get nodes(): TransformNode[] {
+		const rootNodes = this.assetContainer.getNodes().filter(
+			n => n instanceof TransformNode && !n.parent
+		) as TransformNode[];
+		return rootNodes;
+	}
+
+	/**
+	 * The {@link ViewerLight}s of the {@link Variant}.
+	 */
+	get lights(): Light[] {
+		return this.assetContainer.lights;
+	}
+
+	/**
+	 * All TransformNodes of the {@link Variant} mapped flat with a {@link DottedPath}.
+	 */
+	get dottedNodes(): Map<DottedPath, TransformNode> {
+		if( ! this._dottedNodes ) {
+			const nodes = this.assetContainer.getNodes().filter( n => n instanceof TransformNode );
+			const dottedNodes = new Map();
+			nodes.forEach( node => {
+				dottedNodes.set( node.metadata.dottedPath, node );
+			} );
+			this._dottedNodes = dottedNodes;
+		}
+		return this._dottedNodes;
+	}
+
+	/**
+	 * The Materials of the {@link Variant}.
+	 */
+	get materials(): Material[] {
+		return this.assetContainer.materials;
+	}
+
+	/**
+	 * All {@link Element}s from this {@link Variant}'s parents.
+	 */
+	get inheritedElements(): Element[] {
+		let elements: Element[] = [];
+		this.ancestors.forEach( ancestor => {
+			elements = concat( elements, ancestor.elements );
+		} );
+		return concat( elements, this.elements );
+	}
+
+	/**
+	 * All {@link ViewerLight}s inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedViewerLights(): ViewerLight[] {
+		let viewerLights: ViewerLight[] = [];
+		this.ancestors.forEach( ancestor => {
+			viewerLights = concat( viewerLights, ancestor.viewerLights );
+		} );
+		return concat( viewerLights, this.viewerLights );
+	}
+
+	/**
+	 * All TransformNodes inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedNodes(): TransformNode[] {
+		let nodes: TransformNode[] = [];
+		this.ancestors.forEach( ancestor => {
+			nodes = concat( nodes, ancestor.nodes );
+		} );
+		return concat( nodes, this.nodes );
+	}
+
+	/**
+	 * All TransformNodes inherited from this {@link Variant}'s parents mapped flat with a {@link DottedPath}.
+	 */
+	get inheritedDottedNodes(): Map<DottedPath, TransformNode> {
+		let dottedNodes = this.dottedNodes;
+		this.ancestors.forEach( ancestor => {
+			dottedNodes = mergeMaps( dottedNodes, ancestor.dottedNodes );
+		} );
+		return dottedNodes;
+	}
+
+	/**
+	 * All Lights inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedLights(): Light[] {
+		let lights: Light[] = [];
+		this.ancestors.forEach( ancestor => {
+			lights = concat( lights, ancestor.lights );
+		} );
+		return concat( lights, this.lights );
+	}
+
+	/**
+	 * The {@link ParameterDeclarations} inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedParameterDeclaration(): ParameterDeclarations {
+		let declaration = {};
+		this.ancestors.forEach( ancestor => {
+			merge( declaration, ancestor.parameterDeclaration );
+		} );
+		return merge( declaration, this.parameterDeclaration );
+	}
+
+	/**
+	 * The {@link ParameterBag} inherited from this {@link Variant}'s parents.
+	 */
+	get inheritedParameters(): ParameterBag {
+		let parameters = {};
+		this.ancestors.forEach( ancestor => {
+			merge( parameters, ancestor.parameters );
+		} );
+		return merge( parameters, this.parameters );
+	}
+
+	/**
+	 * All Materials from this {@link Variant}'s parents.
+	 */
+	get inheritedMaterials(): Material[] {
+		let materials: Material[] = [];
+		this.ancestors.forEach( ancestor => {
+			materials = concat( materials, ancestor.materials );
+		} );
+		return concat( materials, this.materials );
+	}
+
+	/**
+	 * Gets the direct children of the current {@link Variant}.
+	 */
+	public async getChildren(): Promise<Variant[]> {
+		const children: Variant[] = [];
+		for( const name in this.structureJson.variants ) {
+			children.push( await this.getDescendant( name ) );
+		}
+		return children;
+	}
+
+	/**
+	 *  Gets a descendant {@link Variant} of the current {@link Variant} relative to its {@link DottedPath}.
+	 *  If you have the dotted path `_.product_x.variant_blue.with_yellow_highlight` in a tree and you operate on the
+	 *  `product_x`, you can call `this.getDescendant('variant_blue.with_yellow_highlight')` to get the lowermost
+	 *  {@link Variant}.
+	 */
+	public async getDescendant( dottedPath: DottedPathArgument ): Promise<Variant> {
+		const _dottedPath = DottedPath.create( dottedPath );
+		const [name, ...descendantParts] = _dottedPath.parts;
+		let variant;
+		if( this._children.has( name ) ) {
+			variant = this._children.get( name );
+		} else {
+			if( !this.structureJson.variants ) {
+				throw new Error( `Missing key "variants" in JSON structure for variant "${this.id}".` );
+			}
+			if( !this.structureJson.variants[name] ) {
+				throw new Error( `Variant "${_dottedPath.path}" not defined in JSON structure for variant "${this.id}".` );
+			}
+			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 );
+			} else {
+				variant = await Variant.create( name, this.structureJson.variants[name], this.viewer, this );
+			}
+			this._children.set( name, variant );
+		}
+		if( !variant ) {
+			throw new Error( `Variant "${_dottedPath.path}" was not created.` );
+		}
+		if( descendantParts.length > 0 ) {
+			return await variant.getDescendant( DottedPath.createFromParts( descendantParts ) );
+		}
+		return variant;
+	}
+
+	/**
+	 * Gets the desired {@link Element} of the current {@link Variant} relative to its {@link DottedPath}.
+	 * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
+	 */
+	public async getElement( dottedPath: DottedPathArgument ): Promise<Element> {
+		const _dottedPath = DottedPath.create( dottedPath );
+		const elementName = _dottedPath.popPart();
+		let variant: Variant = this;
+		if( _dottedPath.parts.length > 0 ) {
+			variant = await this.getDescendant( _dottedPath );
+		}
+		if( variant.inheritedElements.length === 0 ) {
+			throw new Error( `No elements for variant "${variant.id}" found. ` +
+				`Either none are defined or they are not initialized (are you operating on the appropriate living?).` );
+		}
+		let element;
+		variant.inheritedElements.forEach( _element => {
+			if( _element.name === elementName ) {
+				element = _element;
+			}
+		} );
+		if( !element ) {
+			throw new Error( `Element with name "${elementName}" does not exist for variant "${variant.id}".` );
+		}
+		return element;
+	}
+
+	/**
+	 * Gets the desired {@link ViewerLight} of the current {@link Variant} relative to its {@link DottedPath}.
+	 * Uses the mechanism of {@link getDescendant} to resolve the appropriate variant in tree.
+	 */
+	public async getViewerLight( dottedPath: DottedPathArgument ): Promise<ViewerLight> {
+		const _dottedPath = DottedPath.create( dottedPath );
+		const viewerLightName = _dottedPath.popPart();
+		let variant: Variant = this;
+		if( _dottedPath.parts.length > 0 ) {
+			variant = await this.getDescendant( _dottedPath );
+		}
+		if( variant.inheritedViewerLights.length === 0 ) {
+			throw new Error( `No viewerLights for variant "${variant.id}" found. ` +
+				`Either none are defined or they are not initialized (are you operating on the appropriate living?).` );
+		}
+		let viewerLight;
+		variant.inheritedViewerLights.forEach( _viewerLight => {
+			if( _viewerLight.name === viewerLightName ) {
+				viewerLight = _viewerLight;
+			}
+		} );
+		if( !viewerLight ) {
+			throw new Error( `ViewerLight with name "${viewerLightName}" does not exist for variant "${variant.id}".` );
+		}
+		return viewerLight;
+	}
+
+	/**
+	 * A proxy for directly getting a Node from an {@link Element} by its {@link DottedPath}s.
+	 */
+	public async getNode( elementDottedPath: DottedPathArgument, nodeDottedPath: DottedPathArgument ): Promise<TransformNode> {
+		const element = await this.getElement( elementDottedPath );
+		return element.getNode( nodeDottedPath );
+	}
+
+	/**
+	 * A proxy for directly getting a Mesh from an {@link Element} by its {@link DottedPath}s.
+	 */
+	public async getMesh( elementDottedPath: DottedPathArgument, meshDottedPath: DottedPathArgument ): Promise<Mesh|null> {
+		const element = await this.getElement( elementDottedPath );
+		return element.getMesh( meshDottedPath );
+	}
+
+	/**
+	 * Gets the Material defined in one of the variants glTFs by its id.
+	 */
+	public getMaterial( id: string ): Material {
+		for( const material of this.inheritedMaterials ) {
+			if( material.id === id ) {
+				return material;
+			}
+		}
+		// fallback to dynamically created materials on scene
+		for( const material of this.viewer.scene.materials ) {
+			if( material.id === id ) {
+				return material;
+			}
+		}
+		throw new Error( `Material with id "${id}" does not exist for variant "${this.id}".` );
+	}
+
+	/**
+	 * Creates a living clone of this {@link Variant}. Will clone all parent {@link Variant}s in tree.
+	 *
+	 * @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 );
+		parent?._children.set( variant.name, variant );
+		variant.assetContainer = this.assetContainer;
+		variant.parameterObservers = cloneDeep( this.parameterObservers );
+		await variant.createElements();
+		await variant.createViewerLights();
+		variant.addParameterObservers();
+		await variant.bootstrapParameters( parameters );
+		this.broadcastEvent( Event.VARIANT_CREATED, variant );
+		return variant;
+	}
+
+	/**
+	 * Destroys this {@link Variant}, all parents and destroy the {@link Element}s.
+	 */
+	public destroy(): Variant {
+		this.elements.forEach( element => element.destroy() );
+		if( this.parent ) {
+			this.parent.destroy();
+		}
+		this.broadcastEvent( Event.VARIANT_DESTROYED, this );
+		return this;
+	}
+
+	/**
+	 * Places the given {@link ParameterBag} in the {@link Variant}'s parameters, replaces all patterns in the
+	 * {@link StructureJson}, broadcasts all {@link ParameterObserver}s and delegates them to its {@link Element}s.
+	 *
+	 * @emit {@link Event.VARIANT_PARAMETER_COMMITTED}
+	 */
+	public async commitParameters( parameters?: ParameterBag ): Promise<Variant> {
+		parameters = merge( {}, parameters );
+
+		// remember old parameter values for later comparison
+		const oldParameters = cloneDeep( this.inheritedParameters );
+
+		// replace patterns in given parameters
+		let _parameters = JSON.stringify( parameters );
+		for( const parameter in this.inheritedParameters ) {
+			const value = this.inheritedParameters[parameter];
+			const search = new RegExp( `\\$\\{${parameter}\\}`, 'g' );
+			_parameters = _parameters.replace( search, value.toString() );
+		}
+		merge( parameters, JSON.parse( _parameters ) );
+
+		// merge inherited parameters and replaced given parameters
+		const mergedParameters = merge( {}, this.inheritedParameters, parameters );
+
+		// replace patterns in structure parameters
+		const structureParameters = this._structureJson.parameters || {};
+		let _structureParameters = JSON.stringify( structureParameters );
+		for( const parameter in mergedParameters ) {
+			const value = mergedParameters[parameter];
+			const search = new RegExp( `\\$\\{${parameter}\\}`, 'g' );
+			_structureParameters = _structureParameters.replace( search, value.toString() );
+		}
+		const replacedStructureParameters = JSON.parse( _structureParameters );
+
+		// calculate which replaced structure parameters have changed and should overload given parameters
+		const differentStructureParameters: ParameterBag = {};
+		for( const parameter in replacedStructureParameters ) {
+			if( !isEqual(structureParameters[parameter], replacedStructureParameters[parameter]) ) {
+				differentStructureParameters[parameter] = replacedStructureParameters[parameter];
+			}
+		}
+
+		// merge replaced structure parameters and given inherited parameters to structure parameters
+		merge( this.parameters, mergedParameters, differentStructureParameters );
+
+		// inherited parameters are now the new parameters to process
+		const newParameters = this.inheritedParameters;
+
+		// replace all parameter patterns in structure json
+		let structure = JSON.stringify( this._structureJson );
+		for( const parameter in newParameters ) {
+			const value = newParameters[parameter];
+			const search = new RegExp( `\\$\\{${parameter}\\}`, 'g' );
+			structure = structure.replace( search, value.toString() );
+		}
+		this.structureJson = JSON.parse( structure );
+
+		// handle parameter observers
+		let observerPromises: Promise<void | ParameterObserver>[] = [];
+		for( const parameter in newParameters ) {
+			const oldParameterValue = oldParameters[parameter];
+			const newParameterValue = newParameters[parameter];
+			this.assertParameter( this.inheritedParameterDeclaration, parameter, newParameterValue );
+			if( oldParameterValue === newParameterValue && this.parametersInitialized ) {
+				continue;
+			}
+			// parameter changed
+			const parameterObservers = mergeMaps( this._parameterObservers, this.parameterObservers );
+			if( parameterObservers.has( parameter ) ) {
+				const observers = parameterObservers.get( parameter )!;
+				observerPromises = concat(observerPromises, observers.map( observer => {
+					const observerResult = observer( this, oldParameterValue, newParameterValue );
+					return Promise.resolve( observerResult ).then( () => {
+						if( this.parametersInitialized ) {
+							this.broadcastEvent( Event.VARIANT_PARAMETER_COMMITTED,
+								this, parameter, oldParameterValue, newParameterValue );
+						}
+					} );
+				} ) );
+			}
+		}
+		await Promise.all( observerPromises );
+
+		// broadcast that bag has been committed
+		this.broadcastEvent(Event.VARIANT_PARAMETER_BAG_COMMITTED, this, oldParameters, newParameters);
+
+		// commit parameters to elements
+		await this.commitParametersToElements( newParameters );
+
+		// commit parameters to lights
+		await this.commitParametersToViewerLights( newParameters );
+
+		// propagate parameters to parent
+		if( this.parent ) {
+			await this.parent.commitParameters( this.parameters );
+		}
+
+		return this;
+	}
+
+	/**
+	 * Adds an observer function for camera matrix changes for given `dottedPath` representing the {@link Element}
+	 * and the `traceable`. The `observer` gets 2 parameters: the `AbstractMesh` and a `ClientRect` object.
+	 */
+	public async addTraceableObserver( dottedPath: DottedPathArgument,
+	                                   observer: CallableFunction,
+	                                   payload?: any  ): Promise<Element> {
+		const _dottedPath = DottedPath.create( dottedPath );
+		const traceableName = _dottedPath.popPart();
+		if( !traceableName ) {
+			throw new Error( `The dottedPath must consist of the element and the name of the defined corresponding ` +
+				`traceable ("${_dottedPath.path}" given).` );
+		}
+		const element = await this.getElement( _dottedPath );
+		return element.addTraceableObserver( traceableName, observer, payload );
+	}
+
+	/**
+	 * Loads {@link glTFUri} with assets, adds them to the {@link Variant}'s `assetContainer` and deactivates the meshes.
+	 * (for further processing).
+	 * @emits {@link Event.ASSET_LOADING_START}
+	 * @emits {@link Event.ASSET_LOADING_END}
+	 */
+	protected async loadAssets(): Promise<Variant> {
+		this.broadcastEvent( Event.ASSET_LOADING_START, this );
+		return new Promise( resolve => {
+			if( !this.structureJson ) {
+				this.broadcastEvent( Event.ASSET_LOADING_END, this );
+				return resolve( this );
+			}
+			if( !this.glTF ) {
+				this.broadcastEvent( Event.ASSET_LOADING_END, this );
+				return resolve( this );
+			}
+			SceneLoader.LoadAssetContainerAsync( this.glTF.rootUrl, this.glTF.fileName, this.viewer.scene ).then( container => {
+				this.assetContainer = container;
+				const nodes = this.assetContainer.getNodes().filter( n => n instanceof TransformNode ) as TransformNode[];
+				nodes.forEach( node => {
+					deactivateTransformNode( node, false );
+					injectNodeMetadata( node, { dottedPath: getDottedPathForNode( node ) }, false );
+				} );
+				this.assetContainer.lights.forEach( light => {
+					light.setEnabled( false );
+					injectNodeMetadata( light, { dottedPath: getDottedPathForNode( light ) }, false );
+					this.viewer.scene.addLight( light );
+				} );
+				this.assetContainer.cameras.forEach( camera => {
+					camera.setEnabled( false );
+					injectNodeMetadata( camera, { dottedPath: getDottedPathForNode( camera ) }, false );
+					this.viewer.scene.addCamera( camera );
+				} );
+				this.broadcastEvent( Event.ASSET_LOADING_END, this );
+				resolve( this );
+			} ).catch( reason => {
+				this.broadcastEvent( Event.ASSET_LOADING_END, this );
+				throw new Error( `Error loading assets for variant "${this.id}": ${reason}.` );
+			} );
+		} );
+	}
+
+	/**
+	 * Commits given parameters to all {@link Element}s.
+	 */
+	protected async commitParametersToElements( parameters: ParameterBag ) {
+		await Promise.all( this.elements.map(
+			element => this.commitParametersToVariantParameterizable(parameters, element, 'elements')
+		) );
+	}
+
+	/**
+	 * Commits given parameters to all {@link ViewerLight}s.
+	 */
+	protected async commitParametersToViewerLights( parameters: ParameterBag ) {
+		await Promise.all( this.viewerLights.map(
+			viewerLight => this.commitParametersToVariantParameterizable(parameters, viewerLight, 'lights')
+		) );
+	}
+
+	/**
+	 * Commits given parameters to a {@link VariantParameterizable} and updates the according definition with given
+	 * key in the {@link StructureJson}. The `definitionKey` "elements" for example will update the definition in
+	 * `this.structureJson.elements`.
+	 */
+	protected async commitParametersToVariantParameterizable( parameters: ParameterBag,
+	                                                          parameterizable: VariantParameterizable,
+	                                                          definitionKey: string ): Promise<ParameterObservable> {
+		const initialDefinition = get( this._structureJson, definitionKey )[parameterizable.name];
+		let initialDefinitionStr = JSON.stringify( initialDefinition );
+		const _parameters: ParameterBag = {};
+		for( const parameter in parameters ) {
+			const dpp = DottedPath.create( parameter );
+			if( dpp.shiftPart() !== parameterizable.name ) {
+				continue;
+			}
+			// we got a parameterizable ("element") parameter
+			let parameterValue = parameters[parameter];
+			const parameterizableParameter = dpp.path;
+			// If the variant is explicitly hidden, we must not override the visibility with element parameters. We need
+			// an exception for visibility to avoid overloading already applied element parameters with element parameters
+			// defined in the variant spec ("dotted parameters").
+			// @see https://github.com/Combeenation/3d-viewer/issues/44
+			if( parameterizableParameter === Parameter.VISIBLE && parameters[Parameter.VISIBLE] === false ) {
+				parameterValue = false;
+			}
+			_parameters[parameterizableParameter] = parameterValue;
+			const search = new RegExp( `\\$\\{${parameterizableParameter}\\}`, 'g' );
+			initialDefinitionStr = initialDefinitionStr.replace( search, parameterValue.toString() );
+		}
+		const definition = get( this.structureJson, definitionKey );
+		definition[this.name] = JSON.parse( initialDefinitionStr );
+		set( this.structureJson, definitionKey, definition );
+		return await parameterizable.commitParameters( _parameters );
+	}
+
+	/**
+	 * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
+	 */
+	protected async commitParameterToElements( parameter: string, value: ParameterValue ): Promise<Variant> {
+		const promises = [];
+		for( const element of this.elements ) {
+			promises.push( element.commitParameter( parameter, value ) );
+		}
+		await Promise.all( promises );
+		return this;
+	}
+
+	/**
+	 * Commits given {@link Parameter} to the {@link Variant}'s {@link Element}s.
+	 */
+	protected async commitParameterToViewerLights( parameter: string, value: ParameterValue ): Promise<Variant> {
+		const promises = [];
+		for( const viewerLight of this.viewerLights ) {
+			promises.push( viewerLight.commitParameter( parameter, value ) );
+		}
+		await Promise.all( promises );
+		return this;
+	}
+
+	/**
+	 * Adds the default {@link ParameterObserver}s which are called every time {@link commitParameters} is called.
+	 */
+	protected addParameterObservers(): Variant {
+		this._parameterObservers.set( Parameter.VISIBLE, [
+			async ( variant: Variant, oldValue: 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 ) => {
+				await variant.commitParameterToElements( Parameter.SCALING, newValue );
+				await variant.commitParameterToViewerLights( Parameter.SCALING, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.MATERIAL, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL_COLOR, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.MATERIAL_COLOR, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL_METALLNESS, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.MATERIAL_METALLNESS, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.MATERIAL_ROUGHNESS, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.MATERIAL_ROUGHNESS, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.HIGHLIGHT_COLOR, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.HIGHLIGHT_COLOR, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.HIGHLIGHTED, [
+			async ( variant: Variant, oldValue: ParameterValue, newValue: ParameterValue ) => {
+				await variant.commitParameterToElements( Parameter.HIGHLIGHTED, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.POSITION, [
+			async ( variant: Variant, oldValue: 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 ) => {
+				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 ) => {
+				await variant.commitParameterToElements( Parameter.CAST_SHADOW, newValue );
+			}
+		] );
+		this._parameterObservers.set( Parameter.CAST_SHADOW_FROM_LIGHTS, [
+			async ( variant: Variant, oldValue: 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 ) => {
+				await variant.commitParameterToElements( Parameter.RECEIVE_SHADOWS, newValue );
+			}
+		] );
+		return this;
+	}
+
+	/**
+	 * Creates {@link Element}s and clones nodes into them.
+	 */
+	protected async createElements(): Promise<Variant> {
+		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 } );
+			} );
+		} );
+		return this;
+	}
+
+	/**
+	 * Creates {@link ViewerLight}s.
+	 */
+	protected async createViewerLights(): Promise<Variant> {
+		for( const name in this.structureJson.lights || {} ) {
+			this.viewerLights.push( await ViewerLight.create( this, name ) );
+		}
+		this.inheritedViewerLights.forEach( viewerLight => {
+			injectNodeMetadata( viewerLight.light, { variant: this, variantParameterizable: viewerLight } );
+		} );
+		return this;
+	}
+
+	/**
+	 * Bootstrapping for parameters. It sets the `parametersInitialized` to true for all ancestors.
+	 */
+	protected async bootstrapParameters( parameters?: ParameterBag ): Promise<Variant> {
+		await this.commitParameters( merge( cloneDeep( this.parameters ), parameters ) );
+		concat( this.ancestors, this ).forEach( ancestor => ancestor.parametersInitialized = true );
+		return this;
+	}
+
+}