Asset Management System
Note: This documentation is for the old 0.4.0 version of A-Frame. Check out the documentation for the current 0.8.0 version
A-Frame has an asset management system that allows us to place our assets in one place and to preload and cache assets for better performance.
Games and rich 3D experiences traditionally preload their assets, such as models or textures, before rendering their scenes. This makes sure that assets aren’t missing visually, and this is beneficial for performance to ensure scenes don’t try to fetch assets while rendering.
We place assets within
<a-assets>, and we place
<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:
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.,
<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
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
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-asset-item> are nodes in A-Frame, they will emit
loaded event when they say they have finished loading.
|loaded||All assets were loaded, or assets timed out.|
|timeout||Assets timed out.|
<a-asset-item> invokes the three.js
XHRLoader. We can use
<a-asset-item> for any file type. When finished, it will set its
member with the text response.
|error||Fetch error. Event detail contains
|progress||Emitted on progress. Event detail contains
|loaded||Asset pointed to by
Images are a standard DOM element so we can listen to the standard DOM events.
|load||Image was loaded.|
Audio and video assets are
HTMLMediaElements. The browser triggers
particular events on these elements; noted here for convenience:
|error||There was an error loading the asset.|
A-Frame uses these progress events, comparing how much time the browser buffered with the duration of the asset, to detect when the asset becomes loaded.
Every element in A-Frame inherits from
ANode controls load and initialization order. For an element to
initialize (whether it be
<a-entity>), its children must have already initialized. Nodes initialize
<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
THREE.XHRLoader to fetch files. three.js stores the
returned data in
THREE.Cache. Every three.js loader inherits from
THREE.XHRLoader, whether they are a
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
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.XHRLoader, then caching will automatically work.
To access the three.js
XHRLoader if we want to listen more closely:
To access the cache that stores XHR responses: