Asset Loading & Dynamic Content

Dynamically load 3D assets, models, and content into your virtual spaces to create customizable and interactive environments. Asset loading is essential for creating personalized experiences, product configurators, and dynamic virtual showrooms.

loadAssetContainer

loadAssetContainer(rootUrl: string, filename: string, options?: object, [callback: Function])

Loads an asset container with multiple 3D objects, materials, and textures. This function is ideal for loading complete scenes or complex multi-part objects.

Parameters:

• rootUrl: string - Base URL path for the scene and its resources
• filename: string - Filename of the asset or "data:" string for inline content
• options?: object - Optional loading configuration (see IImportMeshOptions)

Returns: Array of root mesh IDs from the imported asset container

// Load a furniture set asset container
api.loadAssetContainer(
  'https://assets.example.com/furniture/',
  'living-room-set.glb',
  {
    transform: {
      position: [0, 0, 0],
      rotation: [0, 0, 0],
      scaling: [1, 1, 1]
    },
    cloneMaterials: true
  },
  function(meshIds) {
    console.log('Asset container loaded with meshes:', meshIds);
    
    // Enable interaction with loaded objects
    meshIds.forEach(meshId => {
      enableObjectInteraction(meshId);
    });
  }
);

---

importMesh

importMesh(rootUrl: string, filename: string, options?: object, [callback: Function])

Imports a single 3D mesh or model into the virtual space. Perfect for adding individual objects, products, or decorative elements.

Parameters:

• rootUrl: string - Base URL path for the mesh and its resources
• filename: string - Filename of the mesh or "data:" string for inline content
• options?: object - Optional import configuration (see IImportMeshOptions)

Returns: Unique ID of the imported root mesh

// Import a single product model
api.importMesh(
  'https://products.example.com/models/',
  'chair-modern.glb',
  {
    transform: {
      position: [2, 0, -1],
      rotation: [0, 45, 0],
      scaling: [1.2, 1.2, 1.2]
    },
    playAnimation: true
  },
  function(meshId) {
    console.log('Mesh imported with ID:', meshId);
    
    // Add the mesh to product catalog
    addToProductCatalog(meshId, 'Modern Chair');
  }
);

Import Options Configuration

The options parameter supports the following configuration:

interface IImportMeshOptions {
  meshNames?: string[];           // Specific mesh names to import
  skeletonsEnabled?: boolean;     // Enable skeletal animations
  playAnimation?: string | boolean; // Auto-play animations
  transform?: {                   // Initial transformation
    position?: [number, number, number];
    rotation?: [number, number, number];
    scaling?: [number, number, number];
  };
  instanceTransforms?: object[];  // Multiple instance transforms
  cloneMaterials?: boolean;       // Clone materials for independent editing
  doNotInstantiate?: boolean;     // Load without instantiating
}

Dynamic Asset Loading Examples

Product Configurator:

class ProductConfigurator {
  constructor() {
    this.loadedProducts = new Map();
  }
  
  loadProduct(productId, modelUrl) {
    api.importMesh(
      'https://products.mystore.com/',
      modelUrl,
      {
        transform: { position: [0, 0, 0] },
        cloneMaterials: true
      },
      (meshId) => {
        this.loadedProducts.set(productId, meshId);
        this.enableProductCustomization(meshId);
      }
    );
  }
  
  enableProductCustomization(meshId) {
    // Enable material swapping, scaling, etc.
    console.log('Product customization enabled for:', meshId);
  }
}

Dynamic Room Builder:

function buildCustomRoom(roomConfig) {
  const furniturePromises = roomConfig.furniture.map(item => {
    return new Promise((resolve) => {
      api.importMesh(
        item.assetUrl,
        item.filename,
        {
          transform: {
            position: item.position,
            rotation: item.rotation,
            scaling: item.scale
          }
        },
        (meshId) => {
          resolve({ id: meshId, type: item.type });
        }
      );
    });
  });
  
  Promise.all(furniturePromises).then(loadedItems => {
    console.log('Room built with items:', loadedItems);
    enableRoomInteractions(loadedItems);
  });
}

Asset Streaming System:

class AssetStreamer {
  constructor() {
    this.loadQueue = [];
    this.loadedAssets = new Set();
  }
  
  queueAsset(assetInfo) {
    this.loadQueue.push(assetInfo);
    this.processQueue();
  }
  
  processQueue() {
    if (this.loadQueue.length === 0) return;
    
    const asset = this.loadQueue.shift();
    
    api.loadAssetContainer(
      asset.rootUrl,
      asset.filename,
      asset.options,
      (meshIds) => {
        this.loadedAssets.add(asset.id);
        console.log(`Asset ${asset.id} loaded:`, meshIds);
        
        // Continue processing queue
        setTimeout(() => this.processQueue(), 100);
      }
    );
  }
}

Performance Considerations

Optimization Tips:

• Load assets progressively based on user proximity or interaction
• Use doNotInstantiate: true for pre-loading without immediate display
• Clone materials only when independent customization is needed
• Consider file size and complexity when loading multiple assets

Memory Management:

• Remove unused assets to free memory
• Use asset containers for related objects to optimize loading
• Monitor loading progress and provide user feedback