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.

Adding 8th Wall Web to A-Frame

Cloud Editor

Simply add a "meta" tag in head.html to include the "8-Frame" library in your project. If you are cloning from any of 8th Wall's A-Frame based templates or self-hosted projects, it will already be there. Also, there is no need to manually add your AppKey.

<meta name="8thwall:renderer" content="aframe:1.4.1">

Self Hosted

8th Wall Web can be added to your A-Frame project in a few easy steps:

Include a slightly modified version of A-Frame (referred to as "8-Frame") which fixes some polish concerns:

<script src="//cdn.8thwall.com/web/aframe/8frame-1.4.1.min.js"></script>

Add the following script tag to the HEAD of your page. Replace the X's with your app key:

<script src="//apps.8thwall.com/xrweb?appKey=XXXXX"></script>

Configuring the Camera: `xrconfig`

To configure the camera feed, add the xrconfig component to your a-scene:

<a-scene xrconfig>

xrconfig Attributes (all optional)

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.

World Tracking, Image Targets, and/or Lightship VPS: `xrweb`

If you want World Tracking Image Targets, or Lightship VPS, add the xrweb component to your a-scene:

<a-scene xrconfig xrweb>

xrweb Attributes (all optional)

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()`. `'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()` 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.
enableVps	`Boolean`	`false`	If true, look for Project Locations and a mesh. The mesh that is returned has no relation to Project Locations and will be returned even if no Project Locations are configured. Enabling VPS overrides settings for `scale` and `disableWorldTracking`.
projectWayspots	`Array`	`[]`	Comma separated strings of Project Location names to exclusively localize against. If unset or an empty string is passed, we will localize all nearby Project Locations.

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.

Sky Effects: `xrlayers` and `xrlayerscene`

If you want Sky Effects:

Add the xrlayers component to your a-scene
Add the xrlayerscene component to an a-entity and add content you want to be in the sky under that a-entity.

<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

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

Component	Type	Default	Description
name	`String`	`''`	The layer name. Should correspond to a layer from `XR8.LayersController`. 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.

Face Effects: `xrface`

If you want Face Effects tracking, add the xrface component to your a-scene:

<a-scene xrconfig xrface>

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.

Hand Tracking: `xrhand`

If you want Hand Tracking, add the xrhand component to your a-scene:

<a-scene xrconfig xrhand>

xrhand Attributes

Component	Type	Default	Description
enableWrists [Optional]	`Boolean`	`false`	If true, runs wrist detection simultaneosly with Hand Tracking and returns wrist attachment points.

None

Notes:

xrhand and xrweb cannot be used at the same time.
xrhand and xrlayers cannot be used at the same time.
xrhand and xrface cannot be used at the same time.

Functions

Function	Description
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	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.
xrlayersComponent	Creates an A-Frame component for Layers tracking which can be registered with `AFRAME.registerComponent()`. Generally won't need to be called directly.
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.
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.

Example - SLAM enabled (default)

<a-scene xrconfig xrweb>

Example - SLAM disabled (image tracking only)

<a-scene xrconfig xrweb="disableWorldTracking: true">

Example - Enable VPS

<a-scene xrconfig xrweb="enableVps: true; projectWayspots=location1,location2,location3">

Example - Front camera (image tracking only)

<a-scene xrconfig="cameraDirection: front" xrweb="disableWorldTracking: true">

Example - Front camera Sky Effects

<a-scene xrconfig="cameraDirection: front" xrlayers>

Example - Sky + SLAM

<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

<a-scene xrconfig xrface>

Example - Face Effects with Ears

<a-scene xrconfig xrface="enableEars:true">

Example - Hand Tracking

<a-scene xrconfig xrhand>

Adding 8th Wall Web to A-Frame​

Cloud Editor​

Self Hosted​

Configuring the Camera: xrconfig​

xrconfig Attributes (all optional)​

World Tracking, Image Targets, and/or Lightship VPS: xrweb​

xrweb Attributes (all optional)​

Sky Effects: xrlayers and xrlayerscene​

xrlayers Attributes​

xrlayerscene Attributes​

Face Effects: xrface​

xrface Attributes​

Hand Tracking: xrhand​

xrhand Attributes​

Functions​

Example - SLAM enabled (default)​

Example - SLAM disabled (image tracking only)​

Example - Enable VPS​

Example - Front camera (image tracking only)​

Example - Front camera Sky Effects​

Example - Sky + SLAM​

Example - Face Effects​

Example - Face Effects with Ears​

Example - Hand Tracking​

Adding 8th Wall Web to A-Frame

Cloud Editor

Self Hosted

Configuring the Camera: `xrconfig`

xrconfig Attributes (all optional)

World Tracking, Image Targets, and/or Lightship VPS: `xrweb`

xrweb Attributes (all optional)

Sky Effects: `xrlayers` and `xrlayerscene`

xrlayers Attributes

xrlayerscene Attributes

Face Effects: `xrface`

xrface Attributes

Hand Tracking: `xrhand`

xrhand Attributes

Functions

Example - SLAM enabled (default)

Example - SLAM disabled (image tracking only)

Example - Enable VPS

Example - Front camera (image tracking only)

Example - Front camera Sky Effects

Example - Sky + SLAM

Example - Face Effects

Example - Face Effects with Ears

Example - Hand Tracking