Skip to main content

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

  1. 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:

  1. 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>

  1. 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)

ComponentTypeDefaultDescription
cameraDirectionString'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;.`
allowedDevicesString'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.
mirroredDisplayBooleanfalseIf 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.
disableXrTabletBooleanfalseDisable the tablet visible in immersive sessions.
xrTabletStartsMinimizedBooleanfalseThe tablet will start minimized.
disableDefaultEnvironmentBooleanfalseDisable the default "void space" background.
disableDesktopCameraControlsBooleanfalseDisable WASD and mouse look for camera.
disableDesktopTouchEmulationBooleanfalseDisable desktop fake touches.
disableXrTouchEmulationBooleanfalseDon’t emit touch events based on controller raycasts with the scene.
disableCameraReparentingBooleanfalseDisable camera -> controller object move
defaultEnvironmentFloorScaleNumber1Shrink or grow the floor texture.
defaultEnvironmentFloorTextureAssetSpecify an alternative texture asset or URL for the tiled floor.
defaultEnvironmentFloorColorHex Color#1A1C2ASet the floor color.
defaultEnvironmentFogIntensityNumber1Increase or decrease fog density.
defaultEnvironmentSkyTopColorHex Color#BDC0D6Set the color of the sky directly above the user.
defaultEnvironmentSkyBottomColorHex Color#1A1C2ASet the color of the sky at the horizon.
defaultEnvironmentSkyGradientStrengthNumber1Control 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)

ComponentTypeDefaultDescription
scaleString'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.
disableWorldTrackingBooleanfalseIf true, turn off SLAM tracking for efficiency.
enableVpsBooleanfalseIf 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.
projectWayspotsArray[]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:

  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.
<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

ComponentTypeDefaultDescription
nameString''The layer name. Should correspond to a layer from XR8.LayersController. Only supported layer at this time is sky.
invertLayerMaskBooleanfalseIf true, content you place in your scene will occlude non-sky areas. If false, content you place in your scene will occlude sky areas.
edgeSmoothnessNumber0Amount 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

ComponentTypeDefaultDescription
meshGeometryArray['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]Number1The 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]BooleanfalseIf 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

ComponentTypeDefaultDescription
enableWrists [Optional]BooleanfalseIf 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

FunctionDescription
xrconfigComponentCreates an A-Frame component for configuring the camera which can be registered with AFRAME.registerComponent(). Generally won't need to be called directly.
xrwebComponentCreates 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.
xrlayersComponentCreates an A-Frame component for Layers tracking which can be registered with AFRAME.registerComponent(). Generally won't need to be called directly.
xrfaceComponentCreates an A-Frame component for Face Effects tracking which can be registered with AFRAME.registerComponent(). Generally won't need to be called directly.
xrlayersceneComponentCreates 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>