add docs (#6)

* add docs

* add docs

* add docs

* add docs

* add docs

* add docs

* add docs

Author: evanmcarlson

docs/.gitkeep

@@ -0,0 +1,4 @@
+{
+  "label": "API Reference",
+  "position": 4
+}

docs/api/_category_.json

@@ -0,0 +1,31 @@
+# API Introduction
+
+This section provides a detailed look at the APIs available for building immersive WebAR experiences with 8th Wall Studio.
+
+The 8th Wall API reference is organized into two main groups:
+
+## Studio API
+
+The Studio API provides everything you need to build structured, dynamic experiences in Studio.
+
+The Studio API includes:
+
+- [**Entity-Component System (ECS)**](/docs/api/studio/ecs) — API for working with Studio’s ECS architecture, allowing you to create, modify, and organize entities and components at runtime.
+- [**World**](/docs/api/studio/world) — Core functions and utilities for managing the overall scene graph, including entity hierarchies, transforms, and spaces. The world is the container for all spaces, entities, queries, and observers in your project.
+- [**Events**](/docs/api/studio/events) — A rich system for sending and responding to runtime events within Studio.
+
+Use the Studio API to create immersive, stateful experiences that respond to player input, world changes, and real-time interactions.
+
+[Explore the Studio API →](/docs/api/studio)
+
+
+## Engine API
+
+The Engine API provides lower-level access to 8th Wall’s underlying AR engine, including:
+
+- **8th Wall Camera Pipeline Modules** — Camera pipeline modules developed by 8th Wall.
+- **Custom Camera Pipeline Modules** — Interface for working with the camera frame processing pipeline.
+
+Use the Engine API when you need fine-grained control over camera input, frame processing, or when integrating custom WebGL or computer vision workflows into your project.
+
+[Explore the Engine API →](/docs/api/engine)

docs/api/api.md

@@ -0,0 +1,4 @@
+{
+    "label": "Engine",
+    "position": 2
+}

docs/api/engine/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "AFrame",
+  "position": 3
+}

docs/api/engine/aframe/_category_.json

@@ -0,0 +1,72 @@
+# XR8.AFrame
+
+A-Frame (<https://aframe.io>) is a web framework designed for building virtual reality experiences.
+By adding 8th Wall Web to your A-Frame project, you can now easily build **augmented reality**
+experiences for the web.
+
+## Components
+Component | Description
+--------- | -----------
+[xrconfig](/docs/api/engine/aframe/xrconfig) | Used to configure the camera feed
+[xrweb](/docs/api/engine/aframe/xrweb) | Used to configure world tracking
+[xrface](/docs/api/engine/aframe/xrface) | Used to configure face effects
+[xrlayers](/docs/api/engine/aframe/xrlayers) | Used to configure sky effects
+[xrlayerscene](/docs/api/engine/aframe/xrlayers) | Used to configure sky effects
+
+## Functions
+
+Function | Description
+-------- | -----------
+[xrconfigComponent](/docs/api/engine/aframe/xrconfig#xrconfigcomponent) | Creates an A-Frame component for configuring the camera which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrwebComponent](/docs/api/engine/aframe/xrweb#xrwebcomponent) | Creates an A-Frame component for World Tracking and/or Image Target tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrfaceComponent](/docs/api/engine/aframe/xrface#xrfacecomponent) | Creates an A-Frame component for Face Effects tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrlayersComponent](/docs/api/engine/aframe/xrlayers#xrlayerscomponent) | Creates an A-Frame component for Layers tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+[xrlayersceneComponent](/docs/api/engine/aframe/xrlayers#xrlayerscenecomponent) | Creates an A-Frame component for a Layer scene which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
+
+## Examples
+
+#### Example - SLAM enabled (default) {#example---slam-enabled-default}
+
+```html
+<a-scene xrconfig xrweb>
+```
+
+#### Example - SLAM disabled (image tracking only) {#example---slam-disabled-image-tracking-only}
+
+```html
+<a-scene xrconfig xrweb="disableWorldTracking: true">
+```
+
+#### Example - Front camera (image tracking only) {#example---front-camera-image-tracking-only}
+
+```html
+<a-scene xrconfig="cameraDirection: front" xrweb="disableWorldTracking: true">
+```
+
+#### Example - Front camera Sky Effects {#example---front-camera-sky-effects}
+
+```html
+<a-scene xrconfig="cameraDirection: front" xrlayers>
+```
+
+#### Example - Sky + SLAM {#example---sky--slam}
+
+```html
+<a-scene xrconfig xrweb xrlayers>
+  <a-entity xrlayerscene="name: sky; edgeSmoothness:0.6; invertLayerMask: true;">
+    <!-- Add your Sky Effects content here. -->
+  </a-entity>
+</a-scene>
+```
+
+#### Example - Face Effects {#example---face-effects}
+
+```html
+<a-scene xrconfig xrface>
+```
+
+#### Example - Face Effects with Ears {#example---face-effects-ears}
+
+```html
+<a-scene xrconfig xrface="enableEars:true">
+```

docs/api/engine/aframe/aframe.md

@@ -0,0 +1,46 @@
+# Camera Configuration
+
+To configure the camera feed, add the `xrconfig` component to your `a-scene`:
+
+`<a-scene xrconfig>`
+
+## xrconfig Attributes (all optional) {#xrconfig-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+cameraDirection | `String` | `'back'` | Desired camera to use. Choose from: `back` or `front`. Use `cameraDirection: front;` with `mirroredDisplay: true;` for selfie mode. Note that world tracking is only supported with `cameraDirection: back;`.`
+allowedDevices | `String` | `'mobile-and-headsets'` | Supported device classes. Choose from: `'mobile-and-headsets'` , `'mobile'` or `'any'`. Use `'any'` to enable laptop or desktop-type devices with built-in or attached webcams. Note that world tracking is only supported on `'mobile-and-headsets'` or `mobile`.
+mirroredDisplay | `Boolean` | `false` | If true, flip left and right in the output geometry and reverse the direction of the camera feed. Use `'mirroredDisplay: true;'` with `'cameraDirection: front;'` for selfie mode. Should not be enabled if World Tracking (SLAM) is enabled.
+disableXrTablet | `Boolean` | `false` | Disable the tablet visible in immersive sessions.
+xrTabletStartsMinimized | `Boolean` | `false` | The tablet will start minimized.
+disableDefaultEnvironment | `Boolean` | `false` | Disable the default "void space" background.
+disableDesktopCameraControls | `Boolean` | `false` | Disable WASD and mouse look for camera.
+disableDesktopTouchEmulation | `Boolean` | `false` | Disable desktop fake touches.
+disableXrTouchEmulation | `Boolean` | `false` | Don’t emit touch events based on controller raycasts with the scene.
+disableCameraReparenting | `Boolean` | `false` | Disable camera -> controller object move
+defaultEnvironmentFloorScale | `Number` | `1` | Shrink or grow the floor texture.
+defaultEnvironmentFloorTexture | Asset | | Specify an alternative texture asset or URL for the tiled floor.
+defaultEnvironmentFloorColor | Hex Color | `#1A1C2A` | Set the floor color.
+defaultEnvironmentFogIntensity | `Number` | `1` | Increase or decrease fog density.
+defaultEnvironmentSkyTopColor | Hex Color | `#BDC0D6` | Set the color of the sky directly above the user.
+defaultEnvironmentSkyBottomColor | Hex Color | `#1A1C2A` | Set the color of the sky at the horizon.
+defaultEnvironmentSkyGradientStrength | `Number` | `1` | Control how sharply the sky gradient transitions.
+
+Notes:
+
+* `cameraDirection`: When using `xrweb` to provide world tracking (SLAM), only the `back` camera is
+supported. If you are using the `front` camera, you must disable world tracking by setting
+`disableWorldTracking: true` on `xrweb`.
+
+## xrconfigComponent()
+
+`XR8.AFrame.xrconfigComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrconfig', XR8.AFrame.xrconfigComponent())
+```

docs/api/engine/aframe/xrconfig.md

@@ -0,0 +1,34 @@
+# Face Effects
+
+If you want Face Effects tracking, add the `xrface` component to your `a-scene`:
+
+`<a-scene xrconfig xrface>`
+
+## xrface Attributes {#xrface-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+meshGeometry | `Array` | `['face']` | Comma separated strings that configures which portions of the face mesh will have returned triangle indices. Can be any combination of `'face'`, `'eyes'`, `'iris'` and/or `'mouth'`.
+maxDetections [Optional] | `Number` | `1` | The maximum number of faces to detect. The available choices are 1, 2, or 3.
+uvType [Optional] | `String` | `[XR8.FaceController.UvType.STANDARD]` | Specifies which uvs are returned in the facescanning and faceloading event. Options are: `[XR8.FaceController.UvType.STANDARD, XR8.FaceController.UvType.PROJECTED]`
+enableEars [Optional] | `Boolean` | `false` | If true, runs ear detection simultaneosly with Face Effects and returns ear attachment points.
+
+
+Notes:
+
+* `xrface` and `xrweb` cannot be used at the same time.
+* `xrface` and `xrlayers` cannot be used at the same time.
+* Best practice is to always use `xrconfig`; however, if you use `xrface` without `xrconfig` then `xrconfig` will be added automatically. When that happens all attributes which were set on `xrface` will be passed along to `xrconfig`.
+
+## xrfaceComponent()
+
+`XR8.AFrame.xrfaceComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrface', XR8.AFrame.xrfaceComponent())
+```

docs/api/engine/aframe/xrface.md

@@ -0,0 +1,58 @@
+# Sky Effects
+
+If you want Sky Effects:
+
+1. Add the `xrlayers` component to your `a-scene`
+2. Add the `xrlayerscene` component to an `a-entity` and add content you want to be in the sky under that `a-entity`.
+
+```html
+<a-scene xrconfig xrlayers>
+  <a-entity xrlayerscene="name: sky; edgeSmoothness:0.6; invertLayerMask: true;">
+    <!-- Add your Sky Effects content here. -->
+  </a-entity>
+</a-scene>
+```
+
+## xrlayers Attributes {#xrlayers-attributes}
+
+None
+
+Notes:
+
+* `xrlayers` and `xrface` cannot be used at the same time.
+* `xrlayers` and `xrweb` can be used at the same time. You must use `xrconfig` when doing so.
+  * Best practice is to always use `xrconfig`; however, if you use `xrlayers` without `xrface` or `xrweb` or `xrconfig`, then `xrconfig` will be added automatically. When that happens all attributes which were set on `xrweb` will be passed along to `xrconfig`.
+
+## xrlayerscene Attributes {#xrlayerscene-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+name | `String` | `''` | The layer name. Should correspond to a layer from [`XR8.LayersController`](../layerscontroller/layerscontroller.md). Only supported layer at this time is `sky`.
+invertLayerMask | `Boolean` | `false` | If true, content you place in your scene will occlude non-sky areas. If false, content you place in your scene will occlude sky areas.
+edgeSmoothness | `Number` | `0` | Amount to smooth the edges of the layer. Valid values between 0-1.
+
+## xrlayersceneComponent()
+
+`XR8.AFrame.xrlayersceneComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrlayersceneComponent', XR8.AFrame.xrlayersceneComponent())
+```
+
+## xrlayersComponent()
+
+`XR8.AFrame.xrlayersComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrlayers', XR8.AFrame.xrlayersComponent())
+```

docs/api/engine/aframe/xrlayers.md

@@ -0,0 +1,36 @@
+# World Tracking & Image Targets
+
+If you want World Tracking or Image Targets, add the `xrweb` component to your `a-scene`:
+
+`<a-scene xrconfig xrweb>`
+
+## xrweb Attributes (all optional) {#xrweb-attributes}
+
+Component | Type | Default | Description
+--------- | ---- | ------- | -----------
+scale | `String` | `'responsive'` | Either `'responsive'` or `'absolute'`. `'responsive'` will return values so that the camera on frame 1 is at the origin defined via [`XR8.XrController.updateCameraProjectionMatrix()`](../xrcontroller/updatecameraprojectionmatrix). `'absolute'` will return the camera, image targets, etc in meters. The default is `'responsive'`. When using `'absolute'` the x-position, z-position, and rotation of the starting pose will respect the parameters set in [`XR8.XrController.updateCameraProjectionMatrix()`](../xrcontroller/updatecameraprojectionmatrix) once scale has been estimated. The y-position will depend on the camera's physical height from the ground plane.
+disableWorldTracking | `Boolean` | `false` | If true, turn off SLAM tracking for efficiency.
+
+Notes:
+
+* `xrweb` and `xrface` cannot be used at the same time.
+* `xrweb` and `xrlayers` can be used at the same time. You must use `xrconfig` when doing so.
+  * Best practice is to always use `xrconfig`; however, if you use `xrweb` without `xrface` or
+  `xrlayers` or `xrconfig`, then `xrconfig` will be added automatically. When that happens all
+  attributes which were set on `xrweb` will be passed along to `xrconfig`.
+* `cameraDirection`: World tracking (SLAM) is only supported on the `back` camera. If you are using
+  the `front` camera, you must disable world tracking by setting `disableWorldTracking: true`.
+* World tracking (SLAM) is only supported on mobile devices.
+
+## xrwebComponent()
+
+`XR8.AFrame.xrwebComponent()`
+
+Creates an A-Frame component which can be registered with `AFRAME.registerComponent()`. This,
+however, generally won't need to be called directly. On 8th Wall Web script load, this component
+will be registered automatically if it is detected that A-Frame has loaded (i.e if `window.AFRAME`
+exists).
+
+```javascript
+window.AFRAME.registerComponent('xrweb', XR8.AFrame.xrwebComponent())
+```