Documentation

Learn how to get started

or Go to API Docs

Quick Setup

Getting started adding Simbol to your site is very easy. First, install it:

npm install --save simbol

Then import it into your project:

import {Simbol} from 'simbol';

Create a Simbol instance with the scene information:

const simbol = new Simbol({
	hand: 'left',
	scene: {
		canvas: document.querySelector('canvas'),
		sceneToLoad: 'path/to/my/scene.gltf'
	}
});
				

Instantiate the Simbol instance:

simbol.init();

Here is a full list of all configuration options

Running a multiVP server

You need to run a WebSockets server and CoTurn for this to work. We provide an example repository using Simbol and simbol-server in a Docker container.

simbol-server provides an HTTP and WebSockets server, while the Docker container also adds CoTurn so yo don't need to worry about anything. Check out the Readme to set it up.

With your server set up, you can now feed that information into Simbol via the configuration object:

const simbol = new Simbol({
	scene: {
		canvas: document.querySelector('canvas'),
		sceneToLoad: 'path/to/my/scene.gltf'
	},
	virtualPersona: {
		multiVP: {
			socketURL: 'wss://yourdomiain/ws',
			socketPort: '80',
			iceServers: [
				{urls:'stun:stun.l.google.com:19302'},
				{urls:'stun:stun1.l.google.com:19302'}, // Google offers some free STUN servers
				{urls:'stun:yourdomain:3478'},
				{
					urls: 'turn:yourdomain:3478',
					username: 'test',
					credential: 'mysecretpassword'
				}
			]
		}
	}
});

simbol.init();

User Guide

The first time you visit a Simbol site you can either decide ignore the log in and visit it anonymously, or use the uPort app to scan the log in QR code.

Once logged in, your avatar loads and you can start moving around the virtual world and interact with it.

Locomotion

For desktop, there is smooth locomotion and teleportation. You can move your avatar around using the WASD keys. For teleportation, use mouse clicks.

For mobile, there is smooth locomotion. If you tap once and rotate, you will look around the virtual world. If you tap twice and rotate, you will move in the direction you are rotating.

In VR, there is teleportation. To activate it, press the corresponding trigger button of your headset's controller.

All teleportation implementations work as follows:

  • Click once to activate teleportation
  • You will see a hit cylinder in either green or red depending on whether you can teleport there or not
  • Once you've picked where you would like to teleport, hold the position for 0.5 seconds and the teleportation will occur
  • While you move the hit cylinder, teleportation will not occur
Interactions

For selection, there's a reticle. With a 3DOF controller (in VR) or 0DOF controller (desktop and mobile), the reticle is tied to your head position. With a 6DOF controller (in VR), the reticle is tied to your preferred hand's controller.

Creating a Virtual Persona

With Simbol, you can have your own identity (or multiple) to move around all Simbol sites. This is not necessary to use Simbol, if you don't sign in to a Simbol site, you'll be able to use the default Anonymous avatar

If you wish to use your own identity, head over to Identity to create and manage your Virtual Persona. This must be done at least once before visiting Simbol sites with your identity

The process is always the same whether it's your first time or not:

  1. Check that you have the uPort app installed
  2. Press the sign in button and scan the QR pre with the uPort app
  3. You can then choose a displayname which will be shown to other users only if you decide to once that's implemented
  4. Choose your height so we can position the avatar accordingly
  5. Add the URL that points to the GLTF/GLB file for your avatar
  6. Click 'Save Virtual Persona' which will trigger the mobile app asking you to confirm the new configuration
Avatar Spec

When creating your avatar, there are a few guidelines to follow to make sure it works seamlessly with all Simbol sites

  • The head object MUST be called VirtualPersonaHead
  • The head object MUST have a bone called VirtualPersonaHeadBone
  • The bone for each hand MUST be called VirtualPersonaHandRight and VirtualPersonaHandLeft respectively
  • There MUST be a bone right between both eyes called VirtualPersonaEyeBone
  • Simbol can handle several hand gestures. To support them, each hand must have an animation corresponding to each pose. The names of the animations are the following (e.g. "HandLeftOpen" or "HandRightThumb"):
    • Hand${'Left' or 'Right'}Open
    • Hand${'Left' or 'Right'}Fist
    • Hand${'Left' or 'Right'}Okay
    • Hand${'Left' or 'Right'}Point
    • Hand${'Left' or 'Right'}Thumb
    • Hand${'Left' or 'Right'}ThumbPoint

The animations mentioned above correspond to the following 6 gestures that Simbol currently supports:

API Docs