PLATFORM V2

API

Unity

Console

What is the Teleportal Platform?

The Teleportal Platform is a suite of tools and services that make it intuitive to create great Mixed Reality software.

Aimed at freeing up creators to focus on designing revolutionary spatial experiences, the Teleportal Platform bundles AR/VR technologies, data management systems, auto-scaling servers, multi-user networks, geolocation tools, voice chat and more.

It connects seamlessly across all devices (iOS / Android / Magic Leap / VR / Desktop) in real-time, and is extensible, allowing developers to build their own Services that can handle custom logic.

What sorts of experiences can be made with it?

Individuals and studios have built a wide range of spatial applications on the Teleportal Platform, including animation pre-visualization, drone autonomy, games, and interactive art exhibits.


Teleportal Fundamentals

0

Quickstart

Make your first app on Teleportal.

1

Realms

Real-time spatial data

2

TP Objects

Interactive world objects

3

TP Services

Custom logic for IoT and beyond

4

Mobile AR

AR devices, localized

5

Voice Chat

Powered by the Opus codec

6

Live Physics

Sync physics between users.

0

Quickstart

Make your first app on Teleportal.

Quickstart Guide

Welcome! We can’t wait for you to start building with Teleportal. To get started, you can follow this guide through deploying a sample app.

Prerequisites

Make sure to have the latest version of Unity 3D (2019.2 or above) installed. Additionally, download the latest version of Teleportal SDK for Unity.

API Key

While those are downloading, register an account in the Teleportal Creator Console. Then navigate to the Apps tab. Click New App and type in a name for your new App. This will generate an API Key that will soon be typed into Unity, giving your App the ability to initialize Teleportal.

Import SDK

Create a new Unity project with the default settings. Once the project loads, go to the Assets menu and choose Import Package > Custom Package... then navigate to the Teleportal for Unity SDK package.

Sample Scene

We have bundled a sample scene into the Teleportal SDK for Unity package for you to experiment with. Navigate to the Project Assets panel in Unity, then go to Teleportal > Samples > Laser Tag and open the scene.

In the Teleportal Project object, type the API Key you earlier generated in the Teleportal Creator Console.

Run the scene and type in a username. Once the screen disappears, right click to capture the mouse and start looking around, and left click to fire lasers.

Build & Run

It’s time to build and run your new App on Teleportal! Go to the File menu and choose Build Settings. In the window that opens, choose PC, Mac & Linux Standalone then click Build and Run and save the executable.

The standalone App should launch automatically. To simulate multiple users, start the App in Unity, and resize both windows to position them side-by-side. Log in with a different username on both, then start wandering around. Enjoy!

AR/VR

To enable VR, plug in a VR headset, make sure SteamVR is installed and running, then open the app (or press Play in Unity).

To enable mobile AR, follow the instructions in the Mobile AR section.

1

Realms

Real-time spatial data

What are Realms?

Realms represent Earth-scale virtual worlds. Realms are the backing datastores for all information contained or accessed by Apps and TP Services on the Teleportal Network.

In the Teleportal API, Realms are accessed similarly to a standard database or key-value store. However, they are fine-tuned for real-time and distributed updates to massive amounts of spatial data.

Realms provide real-time spatial data to Apps and TP Services. They are distributed and load-balanced automatically by the Teleportal Network.

Creating Realms

Realms are essential for every App. When a User opens your App on their device, they join the Realm defined in your scene. In Unity, Realms are defined on a per-scene basis. To create a Realm, drag the Teleportal Project prefab into your scene. Doing this also initializes Teleportal functionality in this scene. Then modify the Realm ID to something unique. This could be the name of your app + the name of the scene, like lasertag.sample.

Inside this scene, feel free to add all assets you would normally put into a scene. To track individual objects, make sure to add TPObject scripts to them (see section: Objects/Defining)

Realms can also be defined by existing scenes in your App. Simply drag the Teleportal Project prefab into your scene, and modify the Realm ID, just like above.

To create additional Realms, add Teleportal to more scenes using the same method (or duplicate the existing one and modify the Realm ID in the Unity Inspector).

Versioning

Realms are versioned by default. This is similar to a Git version control system, where each change, no matter how minor or major, is tracked and assigned a unique hash.

Versioning can be disabled for a particular Realm Template in the Teleportal Creator Console. This is especially useful for Apps that include temporary or private interactions.

Time Travel

Time Travel is an extension of Realm Versioning. Since Realms are already versioned, all changes can be placed onto a Timeline and play/pause/seek just like a video replay.

Connectivity

Each Realm has a unique identifier, called a Realm ID. These IDs are typically of the form developer.app.realm where:

Realm data can be downloaded by an App’s Creator from Test Users only.
For privacy, Realm data of production Users is not downloadable.

Privacy

For data security and user privacy, Realms are sandboxed to individual Apps and user groups. By default, Realms are private, but user groups can open their Realm(s) to other users of a specific App if desired.

Realms are currently run on the Teleportal Cloud and protected securely. Realm data is only accessible to authenticated Apps and Services. Contact us for Enterprise installations.

2

TP Objects

Interactive world objects

What are TP Objects?

TP Objects are interactive, shared Realm objects that are defined in the developer’s graphics engine (such as Unity). Objects persist across sessions, synchronize across devices in real-time, and remain in the Realm, regardless of the number of people connected.

Defining Objects

In Unity, you can convert a GameObject into a TP Object simply by attaching the TPObject script to the GameObject.

TP Objects are identified by their names. For this reason, each TP Object must have unique names; they should not have the same name in the Unity inspector.

In the Unity inspector, TP Objects provide 4 options for customization:

Transforming TP Objects

Teleportal automatically stores, tracks, and synchronizes 3D transforms of TP Objects across the Realm and all Users.

Thanks to this support, TP Objects are tracked by Teleportal even when using built-in engine functions to move objects:

TP Object States

States are mutable key-value pairs that provide information about a TP Object. They are automatically saved to the Realm and synchronized across the Network to Users. Whenever a state is set, the Realm saves another version (see section: Realms/Versioning).

By itself with no states, a TP Object is a generic type, and does not even have a renderer. However, a set of default states are automatically set on the TP Object by Teleportal:

Getting & Setting States

To get a State programmatically, use the API call TPObject.GetState(string property)
If the state does not exist, the return value of this method will be null.

To set a State programmatically, use the API call TPObject.SetState(string property, string value)
Teleportal automatically synchronizes this state across the Network.

3

TP Services

Custom logic for IoT and beyond

What are TP Services?

TP Services are logic containers that provide additional functionality to apps on the Teleportal Network. They are created via a Javascript API in a Node JS application, making them highly extensible and able to run on any platform or device. Since Services run on Node JS, they are highly extensible and can run on systems spanning the entire spectrum, from edge computing devices to high-performance servers.

In fact, all logic running on the Teleportal Network is built on the same TP Service API that you have access to. This means that you can build Services with the same power and flexibility as TP Services built in-house by Teleportal.

Connectivity

TP Services connect to the Teleportal Network from anywhere. They can be run on your own computer, embedded device (such as a Raspberry Pi), company web server, or professional hosting on the Teleportal Cloud. TP Services must authenticate to the Teleportal Network with your API key.

Transactions

TP Services use Transactions to communicate with Apps, other Services, and Users. Each Transaction on the Teleportal Network has the following fields:

TCP vs. UDP

Data can be sent over TCP or UDP, all in the form of Teleportal Transactions. For data that is designed to be sent rapidly and frequently, use the UDP call instead.

Examples of TCP Transactions are:

Examples of UDP Transactions are:

TCP transactions are default and initiated with Teleportal.tp.query().
UDP transactions are optional and initiated with Teleportal.tp.queryUdp().

Despite UDP being a connectionless protocol, Transaction responses are still received by clients, regardless of whether the initial call was made over a socket (query()) or UDP (queryUdp()).

UDP Transactions do not guarantee that all data will reach the Network, but they greatly improve network stability and speed for rapid, frequent updates. See this article to learn more about UDP.

Subscribers

Subscribers (also known as Listeners) run pre-defined logic whenever a specific command is received by the TP Service. Most logic on the Teleportal Network is asynchronous, meaning that when a command is sent by a TP Service, that TP Service does not keep a continuous connection open or waste processor cycles waiting for the response. Instead, the response consumes resources only after it is finally received.

This is an asynchronous networking call stack, and is often implemented by the technology industry due to its advantages over other methods in real-time situations.

Privacy

By default, TP Services are locked to be available to all Apps by any developer. This can be changed in the Teleportal Creator Console.

TP Services process requests asynchronously, allowing multiple tasks to occur concurrently.

Use Cases

TP Services are uniquely suited for Internet of Things (IoT) and embedded hardware applications since they can be targeted remotely.

TP Services easily bridge APIs from around the web into your experience. For example, you could write a TP Service that changes the music currently playing on an authenticated user’s Spotify account, right from within that Teleportal App.

Marketplace

The Teleportal Marketplace is coming soon. This will allow you to offer your own TP Services on the Teleportal Network for other Creators to use, while you are compensated for each API call to your TP Service.

Getting Started

To start building a TP Service that can interface on the Teleportal network, create a NodeJS application. At the top of a JS file, download and import the Teleportal library:

import { Teleportal, TPTransaction } from 'teleportal';

Create an API Key for your new TP Service in the Teleportal Creator Console. This API Key must be different than the one used in your App, but it is generated the same way. (see section: Quickstart/API Key)

Your TP Service will automatically connect to the Teleportal Network when you run it via Node.

Querying your Service

Once your TP Service is running on the Teleportal Network, your App (and other TP Services) can communicate with it via Transactions, which are initiated by calling Teleportal.tp.query() in your App (C# Unity) code.

TPTransaction transaction = await Teleportal.tp.query("myLEDService", "power", "on", "color", "blue");

Since these calls are asynchronous, make sure the calling method has the "async" keyword in its signature.

public async void DoSomething() {

To parse the data that was responded from your TP Service, read the transaction.data array.

4

Mobile AR

AR devices, localized

AR Platform Support

In addition to Desktop and VR platforms, Teleportal also supports mobile augmented reality devices that run iOS, Android, and Lumin (Magic Leap).

Just like on Desktop or VR, Users with AR devices have full agency in the Realm. This means that they are free to move around and interact with all elements of your App on any device.

Enabling iOS / Android

To enable augmented reality capabilities with Teleportal on iOS and Android:

Enabling Magic Leap

To enable augmented reality capabilities with Teleportal on Magic Leap:

Location Sync

Location Sync gives devices the power to "localize" themselves in the physical space. This is crucial for AR devices running iOS, Android, and Lumin OS (Magic Leap).

Location Sync provides the device with an absolute coordinate system that is consistent between different tracking sessions and devices, regardless of manufacturer, platform, or time at which it the tracking session occurs. This ties in with the Realm, continuously placing Objects and Users in the correct locations.

Choosing a Location Sync method

Different Location Sync methods are preferable for different use cases. In general, we recommend to set it to the default setting in the Teleportal SDK. It can be changed in the Teleportal Project / Users object.

Teleportation

Teleportation is the most basic form of Location Sync. Users can "teleport" to a different location, measured in geographic coordinates (latitude and longitude).

Heading

In Heading sync, Users put their phones together in parallel, facing forward. This is prompted automatically by Teleportal when the device needs to be synced.

This is similar to High Five sync, but the devices are facing forward, instead of back-to-back.

High Five

In High Five sync, Users put their phones back-to-back (as if they are "high fiving" the devices together) to synchronize their locations. This is prompted automatically by Teleportal when the device needs to be synced.

This is similar to Heading sync, but the devices are back-to-back, instead of facing forward.

Pointcloud

Pointcloud uses the camera to acquire a shared map of the environment. When another device comes near the same area, Teleportal is able to understand the overlapping Pointclouds and pinpoint the User to a specific part of the area.

Nearby User

Nearby User sync uses High Five sync as its base, but adds the ability to scan for nearby users first, and then automatically prompt the User to sync with one of them.

Wideband Essential Elevated Device

This is an experimental sync method that is designed for wide-area experiences such as live events, concerts, studios, and galleries. If you are developing Apps for these types of venues, please contact us to use this sync method!

5

Voice Chat

Powered by the Opus codec

Experimental Feature.

What is Voice Chat?

Voice Chat gives your Users the ability to talk with each other in real-time. It is lightweight and works across all Teleportal-supported devices with a microphone.

Spatial Audio

All audio is spatialized, meaning that Users’ voices sound like they are actually coming from their avatars while in your App. For example, if one User stands beside another User, they will hear each other mostly in one ear.

Enabling Voice Chat

To enable Voice Chat on your App, simply select the Voice Enabled checkbox in the Teleportal Project / Voice object.

Each User must agree to the Microphone permission on their device in order to enable Voice Chat transmission; if a User does not enable this permission, they will be able to hear other Users, but not transmit their own voice.

Push to Talk

To transmit voice in this mode, Users hold down the R key. When the key is not held down, no voice is being transmitted. In the standard (push-to-talk disabled) mode, voice is transmitted continuously.

On mobile, there is a microphone button that appears on-screen. A Push to Talk user interface for VR and Magic Leap is coming soon.

Push to Talk can be turned on or off in the Teleportal Project / Voice object.

6

Live Physics

Sync physics between users

Coming Soon

Live Physics is Teleportal’s solution to the challenge of networked physics. It is currently in early-access preview, and we will be rolling it out to more Creators soon.