index file template

Javascript/CSS XR+ API

The XR+ javascript API let developpers add front-end functionalities that do not exist in XR+, it also allows for a deeper UI / screens customization.

How it works?

The API is a project module to enable in the studio

The API allows javascript file and CSS files to be loaded in the <body> of the project web document, with the usual <script> and <style> tags.

You must host those files, they are not hosted by XR+.

We provide a simple example – a javascript class – on how we recommend to communicate with the XR+ elements of the experience.

You can register and listen to particular events such as when the experience starts, or when an image marker is found/lost.

You can also setup your own events with the XR+ studio action editor. By doing so you can trigger an action on a composition item to call a function you have defined in your script.

download the javascript API class example

Libraries included in the core project js code

Those libraires are loaded by all projects and ready to use with the API:

Javascript reference

considering: var XRAPI = new XRAPI_V1({});

XRAPI.getIsLibraryLoaded();check if project library is fully loadedboolean
XRAPI.getIsStarted();check if experience already startedboolean
XRAPI.getThreejsScene();get threejs scenethreejs scene
XRAPI.getCompositionItemByName(“my item name”);get a composition item threejs root object by its namethreejs object
XRAPI.getCompositionParent();get parent off all threejs objects on the scenethreejs object
XRAPI.getDesktopScreenDomElement();get web dom element: desktop screendom element
XRAPI.getLoadingScreenDomElement();get web dom element: loading screendom element
XRAPI.getStartScreenDomElement();get web dom element: start screendom element
XRAPI.getMainScreenDomElement();get web dom element: main screendom element
XRAPI.goToScene(index);change scene. Use index 1 for the first scene
XRAPI.goToState(index);change state. Use index 1 for the first state

Using three.js

the three.js library is currently available at the global scope ( but may only be available as a module import in future updates ).

You can use it directly this way:

const geometry = new THREE.BoxGeometry( 0.2, 0.2, 0.2 ); ...

Contact

for questions regarding the API, email us at: contactus@xr.plus

States engine tutorial

Let’s learn how to add advanced interactions to XR.+ projects using the states engine.

For this tutorial we’ll be using 3 3D primitives: a cube, a sphere and a cylinder.

This tutorial will explain how to create states and buttons to hide and show those 3 objects.

Create a new project in the studio, and add the first primitive: a cube.

1. Add 3D primitives

Set its scale to 5 and change its color to orange

Add a sphere and a cylinder. Set their scale to 5, edit their color, and move them, away from the cube

2. Activate the state engine

In the top area, click the ‘States engine’ button to open the states engine, and activate it.

3. The default state

For now there is only one state, the default one. This defaut state is applied as soon as the project is started. States actions are applied when a project switches into the corresponding state.

On this first state, we’ll only show the cube and hide the sphere and the cylinder. To do so, we need 2 actions.

The first action will show the cube, the second one will hide the 2 other items.

4. The other states

Let’s create another state, this new state will only show the sphere. Again, we need 2 actions: one to show, another one to hide. Finally, the third state will show only the cylinder.

The 3 states now look like this, each with 2 actions:

5. Overlay Buttons

Now that we have created our 3 states add added action to each of them, we will use overlays buttons to switch between them.

Go the ‘Scene overlays’ and add a first button to switch to the state 1.

Edit its position, text, and assign it an action

We need 3 buttons: one for each state. The second button will switch to state 2, and the third button will switch to state 3.

6. all set

You can now test your project in the mobile simulator, in your computer web browser or in your phone browser by scanning the QR code.

Or you can test directly this tutorial project: https://xr.plus/bp3

Tracking modes

There are several possible webAR tracking modes in XR+ studio

Fixed tracking

With the fixed tracking mode, the AR composition for your project is always visible, centered in the middle of the phone screen.

Image tracking

In the image tracking mode, the composition of the project is displayed on top of a specific image target trained and recognized by the system.

To learn more about training an image target as an AR marker, see the AR image markers section.

Floating (3DOF)

The 3 DOF floating tracking uses the phone gyroscope to let the user look around him. This is the recommended tracking mode for projects based on 360 photos/video.

Open 360° photo panoramas demo

Surface tracking (6DOF SLAM)

With surface tracking, the project composition can be anchored on a flat surface. The user can move around and take a close look at the composition, that’s 6 degrees of freedom (6DOF).

Face tracking

Add accessories to people faces, with the help of the studio mannequin head, place items on their correct position.

Open webAR face tracking demo