Add Documentation Files

assets_management.md

@@ -0,0 +1,110 @@
+```markdown
+# Asset Management with `<a-assets>`
+
+The `<a-assets>` element is used to preload assets such as images, models, videos, and audio files before the A-Frame scene is rendered. This ensures a smoother user experience by preventing delays or flickering when these assets are used within the scene. The assets are loaded during the `doConnectedCallback` phase of the scene.
+
+## Usage
+
+The `<a-assets>` element must be a direct child of the `<a-scene>` element.  Inside the `<a-assets>` tag, you can define various asset elements, such as `<img>`, `<audio>`, `<video>`, and `<a-asset-item>`.
+
+```html
+<a-scene>
+  <a-assets>
+    <img id="my-image" src="path/to/image.jpg">
+    <audio id="my-sound" src="path/to/sound.mp3" preload="auto"></audio>
+    <video id="my-video" src="path/to/video.mp4" autoplay loop playsinline></video>
+    <a-asset-item id="my-model" src="path/to/model.glb"></a-asset-item>
+  </a-assets>
+
+  <a-entity geometry="primitive: plane; material: src: #my-image"></a-entity>
+  <a-entity gltf-model="#my-model"></a-entity>
+  <a-entity sound="src: #my-sound; autoplay: true; loop: true"></a-entity>
+  <a-entity video="src: #my-video; autoplay: true; loop: true"></a-entity>
+</a-scene>
+```
+
+## Asset Types
+
+### Images (`<img>`)
+
+Standard HTML `<img>` tags can be used to preload images.  A-Frame automatically sets the `crossorigin` attribute if needed when the image is from a different domain.
+
+```html
+<img id="my-image" src="path/to/image.jpg" crossorigin="anonymous">
+```
+
+**Note:** If you don't set the `crossorigin` and the image is cross-origin, A-Frame will re-request the image with `crossorigin="anonymous"`.  It is best practice to set this attribute yourself.
+
+### Audio (`<audio>`) and Video (`<video>`)
+
+Use HTML5 `<audio>` and `<video>` tags to preload audio and video assets. Remember to include `preload="auto"` on audio elements and `playsinline` on video elements for mobile compatibility.
+
+```html
+<audio id="my-sound" src="path/to/sound.mp3" preload="auto"></audio>
+<video id="my-video" src="path/to/video.mp4" autoplay loop playsinline></video>
+```
+
+If `srcObject` is provided as attribute, the `src` attribute is ignored.
+
+### `<a-asset-item>`
+
+The `<a-asset-item>` element is a custom element provided by A-Frame for loading arbitrary assets such as 3D models (GLTF/GLB), JSON files, or text files.  It uses `THREE.FileLoader` internally.  You can specify a `response-type` attribute to control how the asset is loaded.  If no `response-type` is given, the file extension will determine the response type, defaulting to "text", but using `arraybuffer` for ".glb" files.
+
+```html
+<a-asset-item id="my-model" src="path/to/model.glb"></a-asset-item>
+<a-asset-item id="my-json" src="path/to/data.json" response-type="json"></a-asset-item>
+```
+
+## Referencing Assets
+
+Once the assets are preloaded within the `<a-assets>` section, they can be referenced by their `id` in other A-Frame components using the `src` attribute.
+
+```html
+<a-entity geometry="primitive: plane; material: src: #my-image"></a-entity>
+<a-entity gltf-model="#my-model"></a-entity>
+<a-entity sound="src: #my-sound; autoplay: true; loop: true"></a-entity>
+```
+
+## Timeout
+
+The `<a-assets>` element has an optional `timeout` attribute (defaults to 3000ms) that specifies the maximum time to wait for all assets to load. If the assets haven't loaded within the timeout period, the scene will start rendering anyway.  A warning message will be logged to the console.
+
+```html
+<a-assets timeout="5000">
+  </a-assets>
+```
+
+## Events
+
+The `<a-assets>` element emits the `loaded` event when all assets have finished loading (or the timeout has been reached). It also emits the `timeout` event if the timeout is reached before all assets are loaded.  Each `<a-asset-item>` emits `loaded`, `progress`, and `error` events.
+
+```html
+<a-assets id="assets">
+  <img id="texture" src="path/to/texture.jpg">
+  <a-asset-item id="model" src="path/to/model.glb"></a-asset-item>
+</a-assets>
+
+<script>
+  var assetsEl = document.querySelector('#assets');
+  assetsEl.addEventListener('loaded', function () {
+    console.log('All assets loaded');
+  });
+
+  assetsEl.addEventListener('timeout', function () {
+    console.warn('Assets timeout');
+  });
+
+  var modelEl = document.querySelector('#model');
+    modelEl.addEventListener('progress', function (evt) {
+        console.log("Model loading progress:", evt.detail.loadedBytes, "of", evt.detail.totalBytes)
+    });
+</script>
+```
+
+## Best Practices
+
+*   **Always preload assets:** Preloading assets using `<a-assets>` is crucial for a good user experience.
+*   **Use IDs:** Assign unique IDs to each asset for easy referencing.
+*   **Handle Errors:** Listen for the `error` event on `<a-asset-item>` to handle loading failures.
+*   **Consider `crossorigin`:**  Explicitly set the `crossorigin` attribute for cross-origin images.
+*   **Optimize Assets**: Ensure your assets are optimized for web use to reduce loading times.