We place assets within <a-assets>, and we place <a-assets> within <a-scene>. Assets include:

• <a-asset-item> - Miscellaneous assets such as 3D models and materials
• <audio> - Sound files
• <img> - Image textures
• <video> - Video textures

The scene won't render or initialize until the browser fetches (or errors out) all the assets or the asset system reaches the timeout.

We can define our assets in <a-assets> and point to those assets from our entities using selectors:

<a-scene>
  <!-- Asset management system. -->
  <a-assets>
    <a-asset-item id="horse-obj" src="horse.obj"></a-asset-item>
    <a-asset-item id="horse-mtl" src="horse.mtl"></a-asset-item>
    <a-mixin id="giant" scale="5 5 5"></a-mixin>
    <audio id="neigh" src="neigh.mp3"></audio>
    <img id="advertisement" src="ad.png">
    <video id="kentucky-derby" src="derby.mp4"></video>
  </a-assets>

  <!-- Scene. -->
  <a-plane src="advertisement"></a-plane>
  <a-sound src="#neigh"></a-sound>
  <a-entity geometry="primitive: plane" material="src: #kentucky-derby"></a-entity>
  <a-entity mixin="giant" obj-model="obj: #horse-obj; mtl: #horse-mtl"></a-entity>
</a-scene>

The scene and its entities will wait for every asset (up until the timeout) before initializing and rendering.

Since A-Frame fetches assets using XHRs, browser security requires the browser to serve assets with cross-origin resource sharing (CORS) headers if the asset is on a different domain. Otherwise, we'd have to host assets on the same origin as the scene.

For some options, GitHub Pages serves everything with CORS headers. We recommend GitHub Pages as a simple deployment platform. Or you could also upload assets using the A-Frame + Uploadcare Uploader, a service that serves files with CORS headers set.

Given that CORS headers are set, <a-assets> will automatically set crossorigin attributes on media elements (e.g., <audio>, <img>, <video>) if it detects the resource is on a different domain.

Audio and video assets will only block the scene if we set autoplay or if we set preload="auto":

<a-scene>
  <a-assets>
    <!-- These will not block. -->
    <audio src="blockus.mp3"></audio>
    <video src="loadofblocks.mp4"></video>

    <!-- These will block. -->
    <audio src="blocky.mp3" autoplay></audio>
    <video src="blockiscooking.mp4" preload="auto"></video>
  </a-assets>
</a-scene>

We can set a timeout that when reached, the scene will begin rendering and entities will begin initializing regardless of whether all the assets have loaded. The default timeout is 3 seconds. To set a different timeout, we just pass in the number of milliseconds to the timeout attribute:

If some assets are taking a long time to load, we may want to set an appropriate timeout such that the user isn't waiting all day in case their network is slow.

<a-scene>
  <a-assets timeout="10000">
    <!-- You got until the count of 10 to load else the show will go on without you. -->
    <img src="bigimage.png">
  </a-asset>
</a-scene>

Content fetched by <a-asset-item> will be returned as plain text. If we want to use a different response type such as arraybuffer, use <a-asset-item>'s response-type attribute:

<a-asset-item response-type="arraybuffer" src="model.gltf"></a-asset-item>

Every element in A-Frame inherits from <a-node>, the AFRAME.ANode prototype. ANode controls load and initialization order. For an element to initialize (whether it be <a-assets>, <a-asset-item>, <a-scene>, or <a-entity>), its children must have already initialized. Nodes initialize bottom up.

<a-assets> is an ANode, and it waits for its children to load before it loads. And since <a-assets> is a child of <a-scene>, the scene effectively must wait for all assets to load. We also added extra load logic to <a-entity> such that they explicitly wait for <a-assets> to load if we have defined <a-assets>.

<a-asset-item> uses THREE.FileLoader to fetch files. three.js stores the returned data in THREE.Cache. Every three.js loader inherits from THREE.FileLoader, whether they are a ColladaLoader, OBJLoader, ImageLoader, etc. And they all have access and are aware of the central THREE.Cache. If A-Frame already fetched a file, A-Frame won't try to fetch it again.

Thus, since we block entity initialization on assets, by the time entities load, all assets will have been already fetched. As long as we define <a-asset-item>s, and the entity is fetching files using some form THREE.FileLoader, then caching will automatically work.

Accessing the FileLoader and Cache

To access the three.js FileLoader if we want to listen more closely:

console.log(document.querySelector('a-assets').fileLoader);

To access the cache that stores XHR responses:

console.log(THREE.Cache);