Update docs

docs/addons/ar-button.md

@@ -6,7 +6,7 @@ An A-Frame component and primitive for creating buttons. Buttons respond to clic
 
     AR Buttons **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
 
-![AR Buttons](../img/demo-box.gif){ .responsive }
+![AR Buttons](../img/addon-buttons.gif){ .responsive }
 
 ## Properties
 

docs/addons/ar-clickable.md

@@ -6,7 +6,7 @@ An A-Frame component that turns 3D and 2D objects into "clickables" that respond
 
     AR Clickables **require** an [ar-pointer-tracker](../api/plugin-aframe.md#ar-pointer-tracker) in your scene!
 
-![AR Clickables](../img/demo-box.gif){ .responsive }
+![AR Clickables](../img/addon-clickables.gif){ .responsive }
 
 ## Properties
 
@@ -48,7 +48,7 @@ The following special properties are used to further customize the declarative h
 
 !!! question "What about event-set?"
 
-    Declarative handlers are similar to A-Frame's event-set in their usage, but there are differences behind the scenes. Whenever working with AR Clickables, usage of the declarative handlers presented in this page is preferred.
+    Declarative handlers are similar to A-Frame's event-set in their usage, but there are differences behind the scenes. Whenever working with AR Clickables, usage of the declarative handlers presented in this page is recommended.
 
 ### Multiple handlers
 

docs/addons/ar-video-player.md

@@ -1,15 +1,15 @@
 # Video Player
 
-An A-Frame solution for playing videos in AR. `<ar-video-player>` is tailored for AR with encantar.js. Unlike A-Frame's standard `<a-video>`, `<ar-video-player>` handles corner cases for AR and includes easy-to-use controls, so you can focus on creating your projects rather than dealing with the various technicalities and edge cases of video playback on the browser.
-
-<div style="text-align: center">
-<iframe width="560" height="315" src="https://www.youtube.com/embed/sz4Fmf3zyho?si=e4Ry5jcYAvxPfAKe" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
-</div>
+An A-Frame component and primitive for playing videos in AR. `<ar-video-player>` is tailored for encantar.js. Unlike A-Frame's standard `<a-video>`, `<ar-video-player>` handles corner cases for AR and includes easy-to-use controls, so you can focus on creating and designing your projects rather than dealing with the various technicalities of video playback in the browser.
 
 !!! tip "It's easy to use!"
 
     The Video Player Add-On includes a working demo that you can easily modify. This page documents it in depth and is meant to be used as a reference.
 
+<div style="text-align: center">
+<iframe width="560" height="315" src="https://www.youtube.com/embed/sz4Fmf3zyho?si=e4Ry5jcYAvxPfAKe" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+</div>
+
 ## Properties
 
 | Property | Description | Default |
@@ -39,7 +39,7 @@ An A-Frame solution for playing videos in AR. `<ar-video-player>` is tailored fo
     </a-assets>
     ```
 
-!!! tip "Aspect ratio"
+!!! info "Aspect ratio"
 
     Make sure that the `width` and the `height` of your `<ar-video-player>` match the aspect ratio of your video. The default size is appropriate for the commonly used 16:9 widescreen ratio.
 
@@ -54,8 +54,8 @@ Add the `ar-video-control` component to a descendant of `<ar-video-player>` as i
 ```html
 <ar-video-player src="#my-video">
 
-    <!-- The play button is a descendant of ar-video-player -->
-    <ar-button id="play-button" position="0 0.9 0"
+    <!-- The play button is placed inside ar-video-player -->
+    <ar-button id="play-button" position="0 -0.9 0"
         ar-video-control="action: play"
     ></ar-button>
 
@@ -80,6 +80,7 @@ Add the `ar-video-control` component to a descendant of `<ar-video-player>` as i
 | `"mute"` | Mute the video. |
 | `"unmute"` | Unmute the video. |
 | `"toggleAudio"` | Toggle the audio. |
+| `""` | Do nothing. |
 
 ## Declarative handlers
 
@@ -113,7 +114,7 @@ These handlers can be added to `<ar-video-player>` itself or to any of its desce
      Make it disappear when the video ends or is paused. -->
 <ar-video-player src="#my-video">
 
-    <!-- The pause button is a descendant of ar-video-player -->
+    <!-- The pause button is placed inside ar-video-player -->
     <ar-button id="pause-button" position="0 -0.9 0"
         visible="false" enabled="false"
         ar-onvideoplay="visible: true; ar-button.enabled: true"
@@ -136,7 +137,7 @@ The following special properties are used to further customize the declarative h
 
 !!! question "What about event-set?"
 
-    Declarative handlers are similar to A-Frame's event-set in their usage, but there are differences behind the scenes. Whenever working with the Video Player, usage of the declarative handlers presented in this page is preferred.
+    Declarative handlers are similar to A-Frame's event-set in their usage, but there are differences behind the scenes. Whenever working with the Video Player, usage of the declarative handlers presented in this page is recommended.
 
 ### Multiple handlers
 
@@ -171,8 +172,8 @@ The `<ar-video-player>` emits the following events based on the state of the und
 
 | Method | Description |
 | ------ | ----------- |
-| `invoke(action)` | Perform an [action](#video-controls). |
+| `invoke(action)` | Perform an [action](#actions). |
 
 ## Autoplay
 
-Usage of the `autoplay` attribute on the `<video>` tag is discouraged. Video playback may be blocked due to browser policies and the Video Player will not show up in AR as soon as the page is loaded. It's typically better to wait for user input in order to initiate the playback, e.g., have the user click on a play button. If the page receives no user interaction, then you may still play your video as long as it's muted. See also: [artargetfound](../api/plugin-aframe.md#artargetfound) event.
+Usage of the `autoplay` attribute on the `<video>` tag is discouraged. Video playback may be blocked due to browser policies. In addition, the Video Player will not show up in AR at the exact moment the page is loaded. It's typically better to wait for user input in order to initiate the playback, e.g., have the user click on a play button. If the page receives no user interaction, then you may still play your video as long as it's muted. See also: [artargetfound](../api/plugin-aframe.md#artargetfound) event.

docs/addons/asset-manager.md

@@ -0,0 +1,102 @@
+# Asset Manager
+
+A framework-agnostic solution for preloading assets such as: 3D models, video clips, audio files and more. Preloading assets is typically done in the `preload()` method when using the plugins for [babylon.js](../api/plugin-babylon.md#preload) or [three.js](../api/plugin-three.md#preload).
+
+## Methods
+
+### preload
+
+`assetManager.preload(url: string | string[], options?: object): Promise<void>`
+
+Preload one or more assets.
+
+**Arguments**
+
+* `url: string | string[]`. Absolute or relative URL(s) of the asset(s).
+* `options: object, optional`. An object with the following keys (all are optional):
+    * `timeout: number`. Timeout value, in seconds. Defaults to infinity (i.e., no timeout).
+
+**Returns**
+
+A promise that is resolved as soon as all assets are preloaded, or that is rejected on error.
+
+**Example**
+
+```js
+class MyDemo exports ARDemo
+{
+    // ...
+
+    preload()
+    {
+        return this._assetManager.preload([
+            'assets/mage.glb',
+            'assets/cat.glb',
+            'assets/meow.wav',
+        ], { timeout: 30 });
+    }
+
+    // ...
+
+    constructor()
+    {
+        super();
+
+        // ...
+
+        this._assetManager = new AssetManager();
+
+        // ...
+    }
+}
+```
+
+### url
+
+`assetManager.url(filename: string): string`
+
+Gets an [object URL](https://developer.mozilla.org/en-US/docs/Web/API/URL/createObjectURL_static){ ._blank } of a preloaded asset.
+
+**Arguments**
+
+* `filename: string`. The filename of the asset.
+
+**Returns**
+
+An object URL.
+
+**Example**
+
+```js
+// If the asset is located at "assets/mage.glb",
+// then its filename is "mage.glb"
+const mageURL = this._assetManager.url('mage.glb');
+```
+
+### file
+
+`assetManager.file(filename: string): File`
+
+Gets a [File](https://developer.mozilla.org/en-US/docs/Web/API/File){ ._blank } corresponding to a preloaded asset.
+
+**Arguments**
+
+* `filename: string`. The filename of the asset.
+
+**Returns**
+
+A File object.
+
+### has
+
+`assetManager.has(filename: string): boolean`
+
+Checks if an asset has been preloaded.
+
+**Arguments**
+
+* `filename: string`. The filename of the asset.
+
+**Returns**
+
+Returns `true` if an asset with the given `filename` has been preloaded.

docs/addons/index.md

@@ -0,0 +1,77 @@
+# Add-Ons
+
+Add-Ons provide an enriched experience with additional features that enhance the core of encantar.js. They're offered to supporters who purchase the various demos. Become a supporter and get exclusive access to these features!
+
+<style>
+.addon-container { display: flex; flex-direction: row; justify-content: space-between; align-items: center; margin: 4em 0; }
+.addon-container h2 { margin-top: 0; }
+.addon-container img { width: 100%; height: auto; }
+.addon-container:nth-child(2n+1) > div:nth-child(2) { min-width: 426px; margin-left: 32px; }
+.addon-container:nth-child(2n) > div:nth-child(2) { min-width: 426px; margin-right: 32px; order: -1; }
+</style>
+
+<div class="addon-container" markdown>
+  <div markdown>
+
+## Video Player
+
+Enchant your audience with this [easy-to-use and customizable](./ar-video-player.md) Video Player! Videos in AR are suitable for: product marketing, AR business cards, educational materials, interactive art, entertainment, and more!
+
+[I want this!](https://ko-fi.com/s/697a184728){ .md-button ._blank }
+
+  </div>
+  <div>
+    <iframe width="426" height="240" src="https://www.youtube.com/embed/sz4Fmf3zyho?si=1aI6_Odv2iebIjbL" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+  </div>
+</div>
+
+<div class="addon-container" markdown>
+  <div markdown>
+
+## AR Buttons
+
+Add interactivity to your scenes with easy-to-use buttons for AR! You can [customize their images and colors](./ar-button.md). They're bundled with the Video Player.
+
+[I want this!](https://ko-fi.com/s/697a184728){ .md-button ._blank }
+
+  </div>
+  <div markdown>
+
+![AR Buttons](../img/addon-buttons.gif)
+
+  </div>
+</div>
+
+<div class="addon-container" markdown>
+  <div markdown>
+
+## AR Clickables
+
+Turn 3D and 2D objects into "clickables" that respond to touch or mouse input. AR Clickables are the building blocks of AR Buttons and are included with them.
+
+[I want this!](https://ko-fi.com/s/697a184728){ .md-button ._blank }
+
+  </div>
+  <div markdown>
+
+![AR Clickables](../img/addon-clickables.gif)
+
+  </div>
+</div>
+
+<div class="addon-container" markdown>
+  <div markdown>
+
+## Asset Manager
+
+Framework-agnostic solution for preloading assets such as: 3D models, video clips, audio files and more. This Add-On is bundled with the core.
+
+[I want this!](https://ko-fi.com/s/3ee4182cb6){ .md-button ._blank }
+
+  </div>
+  <div markdown>
+
+![Asset Manager](../img/demo-cat.gif)
+
+  </div>
+</div>

docs/addons/more-addons.md

@@ -0,0 +1,49 @@
+# More Add-Ons
+
+Documentation of A-Frame components bundled with the core.
+
+## ar-scan-gimmick
+
+Use `ar-scan-gimmick` to display an image in the [HUD](../api/hud.md) while the physical scene is being scanned (i.e., before an image target is tracked). Make sure to add the entity to [ar-hud](../api/plugin-aframe.md#ar-hud).
+
+*Example*
+
+```html
+<ar-viewport>
+  <ar-hud>
+
+    <!-- ar-scan-gimmick is part of the HUD -->
+    <ar-scan-gimmick></ar-scan-gimmick>
+
+  </ar-hud>
+</ar-viewport>
+```
+
+### Properties
+
+| Property | Description | Default |
+| -------- | ----------- | ------- |
+| `opacity` | Opacity value. | `1` |
+| `src` | URL of an image. If none is provided, a default image is used. | `""` |
+
+## gltf-anim
+
+An easy-to-use component for animating 3D models.
+
+*Example*
+
+```html
+<!-- Animate a 3D model in AR -->
+<ar-root>
+  <a-entity gltf-model="#mage-model" gltf-anim="clip: Idle"></a-entity>
+</ar-root>
+```
+
+### Properties
+
+| Property | Description | Default |
+| -------- | ----------- | ------- |
+| `clip` | The name of an animation clip. | `""` |
+| `loop` | Whether or not the animation should loop. | `true` |
+| `speed` | Multiplier of the playback speed. | `1` |
+| `transitionDuration` | Duration, in seconds, of transitions between clips. | `0` |

docs/index.md

@@ -2,17 +2,28 @@
 
 The Augmented Reality engine that will enchant you!
 
-:heart:{ .heart } encantar.js is an Augmented Reality technology which I develop independently. Support this work by [purchasing your copy](https://ko-fi.com/s/3ee4182cb6). You can also [become a sponsor](https://github.com/sponsors/alemart).
+:heart:{ .heart } encantar.js is an Augmented Reality technology which I develop independently. Support this work by [purchasing your copy](./download.md). You can also [become a sponsor](https://github.com/sponsors/alemart).
 
-[:star2: Try it!](./demos/hello-aframe/poster.html){ .md-button ._blank } [:video_game: Play a game!](./demos/basketball/poster.html){ .md-button ._blank } [:sparkles: Demos](./demos.md){ .md-button ._blank } [:books: Learn](./tutorial/introduction.md){ .md-button }
+<style>
+.md-button { padding-left: 1.5em !important; padding-right: 1.5em !important; }
+#gallery { display: flex; justify-content: center; }
+#gallery img { height: 128px; margin: 0 2px; }
+</style>
 
-[![Demo](./img/mage.gif)](./demos/hello-aframe/poster.html){ ._blank } [![Game](./img/basketball.gif)](./demos/basketball/poster.html){ ._blank }
+[:star2: Try it!](./demos/hello-aframe/poster.html){ .md-button ._blank } [:video_game: Play a game!](./demos/basketball/poster.html){ .md-button ._blank } [:sparkles: Demos](./demos.md){ .md-button ._blank } [:heart_eyes: Add-Ons](./addons/index.md){ .md-button } [:books: Learn](./tutorial/introduction.md){ .md-button }
+
+<div id="gallery">
+  <a href="demos/hello-aframe/poster.html" target="_blank"><img src="img/mage.gif" alt="Demo"></a>
+  <a href="demos/basketball/poster.html" target="_blank"><img src="img/basketball.gif" alt="Game"></a>
+  <a href="addons/"><img src="img/video-player.gif" alt="Video Player"></a>
+</div>
 
 ## Features
 
 * **Image tracking**: track detailed images such as book covers, cartoons and photos. No need of manual training!
 * **Pointer tracking**: create interactive experiences based on touch and mouse input with an easy-to-use API.
-* **Plugins**: use encantar.js with the 3D framework of your choice, including A-Frame, Babylon.js, Three.js and more!
+* **Plugins**: use encantar.js with the 3D framework of your choice, including: A-Frame, Babylon.js, Three.js and more!
+* **Add-Ons**: create rich experiences with additional features that enhance the core of encantar.js!
 
 ## Key points
 

mkdocs.yml

@@ -50,6 +50,7 @@ nav:
     - 'Welcome!': 'index.md'
     - 'Download': 'download.md'
     - 'Demos': 'demos.md'
+    - 'Add-Ons': 'addons/index.md'
     - 'Learn': 'tutorial/introduction.md'
     - 'API Reference': 'api/ar.md'
     - 'Recommendations': 'recommendations.md'
@@ -58,6 +59,13 @@ nav:
     - 'License': 'license.md'
   - 'Download': 'download.md'
   - 'Demos': 'demos.md'
+  - 'Add-Ons':
+    - 'Introduction': 'addons/index.md'
+    - 'AR Button API': 'addons/ar-button.md'
+    - 'AR Clickable API': 'addons/ar-clickable.md'
+    - 'Video Player API': 'addons/ar-video-player.md'
+    - 'Asset Manager API': 'addons/asset-manager.md'
+    - 'More Add-Ons': 'addons/more-addons.md'
   - 'Learn':
     - 'Introduction': 'tutorial/introduction.md'
     - 'Concepts': 'tutorial/concepts.md'
@@ -79,6 +87,10 @@ nav:
       - 'Time': 'api/time-manager.md'
       - 'Settings': 'api/settings.md'
       - 'Resolution': 'api/resolution.md'
+    - 'Plugins':
+      - 'A-Frame': 'api/plugin-aframe.md'
+      - 'Babylon.js': 'api/plugin-babylon.md'
+      - 'Three.js': 'api/plugin-three.md'
     - 'Trackers':
       - 'Image tracker':
         - 'ImageTracker': 'api/image-tracker.md'
@@ -99,6 +111,10 @@ nav:
       - 'VideoSource': 'api/video-source.md'
       - 'PointerSource': 'api/pointer-source.md'
       - 'Source': 'api/source.md'
+    - 'Visualization':
+      - 'Viewport': 'api/viewport.md'
+      - 'HUD': 'api/hud.md'
+      - 'Gizmos': 'api/gizmos.md'
     - 'Geometry':
       - 'Pose': 'api/pose.md'
       - 'Viewer': 'api/viewer.md'
@@ -110,19 +126,11 @@ nav:
       - 'Vector3': 'api/vector3.md'
       - 'Quaternion': 'api/quaternion.md'
       - 'Ray': 'api/ray.md'
-    - 'Visualization':
-      - 'Viewport': 'api/viewport.md'
-      - 'HUD': 'api/hud.md'
-      - 'Gizmos': 'api/gizmos.md'
     - 'Events':
       - 'AREvent': 'api/ar-event.md'
       - 'AREventListener': 'api/ar-event-listener.md'
       - 'AREventTarget': 'api/ar-event-target.md'
       - 'AREventType': 'api/ar-event-type.md'
-    - 'Plugins':
-      - 'A-Frame': 'api/plugin-aframe.md'
-      - 'Babylon.js': 'api/plugin-babylon.md'
-      - 'Three.js': 'api/plugin-three.md'
     - 'Speedy':
       - 'Speedy': 'api/speedy.md'
       - 'SpeedySize': 'api/speedy-size.md'