Create AR / VR experiences in Teleportal.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Server
Unity/TeleportalSamples
.gitignore
README.md

README.md

Teleportal SDK

Developer Preview 3

Create AR / VR experiences in Teleportal.

What is Teleportal?

Teleportal is a platform that allows XR developers and content creators to create shared, persistent experiences that are networked in real-time. It bridges worlds across platforms (iOS / Android / VR / PC / Mac) and interfaces with the Unity game engine. The magic of the platform is that it abstracts networking, coordinate system alignment, and other technical challenges in XR, allowing developers and content creators to focus on their creative apps.

Getting Involved / Feedback

Welcome to the early access preview of Teleportal! We love engaging with our community of XR content creators, developers, and users. Please join us on the Teleportal Discord server. See you there!

Tutorials

  • We are working on tutorials to build these samples from scratch.
  • In the meantime, please check out the documentation below!

Also, feel free to reach out to us for any assistance with your Teleportal projects. Thanks! :)

System Architecture

Teleportal consists of three main components.

Client

Any app that includes and runs the Teleportal Client SDK.

  • Teleportal clients can build and run on iOS, Android, VR, PC, and Mac.
  • You can integrate the Teleportal Client SDK into your existing Unity 3D project, or create a new one.
  • Unity support is available now (we are working on Unreal support).

Teleportal Server

Our cloud-based service for geospatial functions and networking between devices.

App Server

A special type of client that provides additional logic to a Teleportal app.

  • You can integrate the Teleportal AppServer SDK into your existing Node application, or create a new one.
  • Teleportal AppServers are not required (you can use your own server for custom logic).
  • However, they can simplify the development process.

See more in the Networking section below.

SDK Download Links

Project Setup (Unity)

  1. Login to the Teleportal Developer Dashboard.
  2. Create a new Teleportal Project and copy your new API Key.
  3. Import the Teleportal SDK UnityPackage into your Unity project.
  4. Open Teleportal Settings (Window menu > XR > Teleportal).
  5. Click the Initialize button.
  6. Paste your API Key and Project ID inside the text boxes.
  7. Go to the Edit Menu > Project Settings > Tags and Layers.
  8. On one of the empty lines, type XR.
  9. On another empty line, type VirtualWorld.

Now your app is ready to go with the primary functionality of Teleportal, including crossplatform AR/VR and networked multiplayer! :)

Note: Avoid modifying the scene that is called "Teleportal", as it is only meant to be included in the build as a library; it does not run standalone. Instead, craft your app or game inside your own Unity scenes.

Crossplatform AR / VR

Teleportal supports a wide range of devices and platforms. Teleportal Apps are accessible and interoperable across all platforms.

Viewport Modes

Teleportal has 3 Viewport Mode: AR, VR, and CG.
Users can choose whichever Viewport Mode they prefer.
All 3 of these Viewport Modes are interoperable and only affect each User indiviudally.

Platform support for each Viewport Mode depends on the hardware capabilities of each platform:

Mode iOS Android Mac PC VR Headset
AR Augmented Reality ✔ Default ✔ Default
VR Virtual Reality On Roadmap On Roadmap ✔ with VR headset
CG Computer Generated ✔ Default ✔ Default

Mobile Device UX

There are some user experience tweaks made by Teleportal when deploying to and running on mobile devices, such as iOS and Android.

Gestures

To interact with advanced functionality in Teleportal, use the following gestures:

  • Swipe Up ↑ to open the Teleportal Map.
  • Aim your Reticle at a virtual User and Swipe Down ↓ to sync location with that User (see the section on Localization).
  • Aim at an XR Item and Swipe ← Left to delete that item from the world.
  • Swipe → Right to toggle between AR and CG modes (see the section on Crossplatform AR / VR).

XR Items

Shared, virtual, persistent objects that are placed and interacted with in the world.

GameObject Properties

  • In Unity, XR Items are composed of a standard GameObject with the XRItem script attached.
  • They are named with the following format: P_item.prefab.
  • They can contain any components that you would add to a standard GameObject.

Spawning / Removing

  • XR Items are spawned into the world when a User taps the screen (or clicks the mouse) while they are holding an Item.
  • Alternatively, Items can be spawned by your server, with no user interaction required.
  • All XR Items have a unique ID that you can reference in spawning/removing/modifying commands.

Location

  • XR Items are positioned at specific geographic coordinates.
  • These coordinates usually come from the User's current location when they spawn an Item into the world.
  • Alternatively, if you spawn an Item on your server, your code defines the exact location for the Item.

Synchronization

  • XR Items are synchronized between clients and your server.
  • Position/rotation data is always synchronized to a specific latitude/longitude position & heading/pitch rotation.
  • You can transmit custom XR Item states, between clients.
  • Examples of this include:
    • Opening and closing a door.
    • Increasing the number of particles in a particle system.
  • XR Items can also be stored and retrieved persistently in the Teleportal Cloud.
  • To enable or disable this behavior on a per-item basis, go to the Teleportal Developer Dashboard.

Declaration

To create and use an XR Item, first add it to Teleportal.

  1. Login to the Teleportal Developer Dashboard.
  2. Tap the XR Item tab.
  3. Tap the + button to create a new entry.
  4. When you are finished, Teleportal will give you a unique ID that your app can use for creating and using XR Items.

Preparing Custom Assets

XR Items require the following custom assets:

  • 3D Model to render the Item in the virtual world. (Main)
  • 3D Model to show the Item being held by the user. (Hand)
  • Square Image Texture for the Inventory Item Bar. (Image Texture)

Before moving to the next section, make sure you have imported these 3 assets.

Important: After importing the 3rd item above (the texture), change its Compression to None, and enable Advanced > Read/Write in the Unity Inspector panel.

Additionally, add a Collider (can be of any type) to only the 1st item above (the Main model).

Creating an XR Item

  1. Open Teleportal Settings (Window menu > XR > Teleportal).
  2. Under the XR Item Wizard section, drag-and-drop the 3 assets listed above in-order (Main > Hand > Image Texture).
  3. Click Create +.

Note: Avoid adding XR Items to the scene directly. Items are only meant to be spawned by Teleportal, at runtime, on behalf of either Users or your server.

Adding XR Items to User Inventory

  • Users can spawn XR Items from their inventory into the world.
  • You can specify a default set of XR Items for your users by adding the Item ID(s) to the Teleportal Project's inspector. This prefab is at the root of your scene.
  • To send an XR Item to a user's inventory programmatically, add this line in your code: TeleportalInventory.Shared.RequestAdd("NAME", "itemID");
  • Replace "NAME" by your desired name of the XR Item, and replace "itemID" by the ID you received in the Declaration step.

Setting XR Item State

When this is paired with the Listening section below, Teleportal synchronizes tracked changes to XR Items in real time.

  1. Create a new script and attach it to your XR Item.
  2. Define an XR Item reference at the top of your script: private XRItem XRI;
  3. In the Start() function, connect to the XR Item component: this.XRI = GetComponent<XRItem>();
  4. Set a custom state on the XR Item (this example changes the intensity of a light): this.XRI.SetState("intensity", 50);

Listening for XR Item State Changes

  1. Create a callback function: public void OnStateChange { }
  2. Add a listener for that callback function: this.XRI.OnStateChange += OnStateChange;
  3. In the callback function, add a check for your property state: if (this.XRI.LastStateProperty == "intensity") { }
  4. In the if statement, add your custom logic (this example changes the intensity of a light): this.Light.intensity = int.Parse(this.XRI.LastStateValue);

Networking

  • Teleportal provides a custom networking layer that simplifies the synchronization of shared XR experiences.

  • Using it, you can define functionality that is transferred between Users and your server.

  • To provide custom networked logic in your Teleportal experience, you can either integrate the Server SDK into your existing server code, or derive a new one from the sample in this repository.

Custom Servers

  • This guide is made for the Teleportal networking stack.
  • You can definitely route these commands via your existing protocol.
  • However, XR Items and Players can be easier to implement if you use Teleportal networking for these commands.

Declaring Commands

To create and use your own commands, first add them to Teleportal.

  1. Login to the Teleportal Developer Dashboard.
  2. Tap the Netcode tab.
  3. Tap the + button to create a new entry.

Adding Listeners (Client)

  1. Create a callback function: public void MyCommand(List<String> args) { }
  2. Register your callback function with the Teleportal Project object: TeleportalProject.Shared.RegisterCommand("MyCommand", MyCommand);
  3. Add custom logic in the function. args start at 1; args.Get(1); retrieves the first parameter.

Sending Data (Client)

Call the following function to send data to your AppServer: TeleportalProject.Shared.Send(data);

Adding Listeners (AppServer)

In the parse() function, there is a switch statement.

  1. Add a case statement for your command: case "MyCommand":
  2. Add custom logic below the case. args start at 0; args[0] retrieves the first parameter.

Sending Data (AppServer)

Call the following function to send data to a specific user: teleportalSend(userName, data);

Client API Reference

Please see the Teleportal for Unity - API Reference

Server API Reference

  • Server API reference is coming soon.
  • In the meantime, please reach out to us with any questions.

Standalone App

We have built a standalone app for you to experiment with Teleportal. We automatically spawn some items into your Inventory for you to play with, such as a Laser, Chicken, and Wall.

Download Links

Usage Example: 1 Desktop, 1 iOS device, 1 Android device

  1. Open Teleportal on each device and have everyone type a unique username.
  2. Authenticate with each person's Google account, then switch back to Teleportal.
  3. Rotate your device to find your friend's avatar.
  4. Aim at your friend's avatar (the reticle should turn red) then swipe down on the screen.
  5. A message will appear asking you to Sync with your friend's device.
  6. Position your device next to your friend's device, with both devices facing directly forward.
  7. Tap the screen to sync.
  8. Back on the Desktop, press the "M" key on the keyboard, which will open the Teleportal Map.
  9. Zoom out until you can see the geolocation of your mobile devices, then click one of the icons to Teleport there.
  10. Switch back to Teleportal, and enjoy! :)

Build Instructions (Unity)

  1. Clone this repository.
  2. Open Unity, then open the Unity/TeleportalSamples project directory.
  3. Click the Play button to run the sample application in the editor.
  4. Open Build Settings (Ctrl+Shift+B on Windows, Cmd+Shift+B on Mac) and choose your platform for exporting a binary.
  5. If deploying to mobile, follow the instructions given by the Unity team for iOS and/or Android.
  6. (iOS only) Set the following values in iOS build settings: bundle identifier, location permission description, camera permission description, requires ARKit support, minimum iOS 11.0+.
  7. (Android only) Set the following values in Android build settings: bundle identifier, location permission description, camera permission description, minimum Android OS 7.0+, multi-threaded rendering disabled, ARCore support enabled.

Build Instructions (AppServer)

  1. Clone this repository.
  2. Open a command shell.
  3. Navigate to the Server/ directory in this repository.
  4. Type npm i to install all dependencies.
  5. Type node hardcorechicken to start the "Hardcore Chicken" sample appserver on your local machine.

You can choose to host a Teleportal AppServer on your local machine, or run it on a managed service like Heroku. It connects to the Teleportal Network either way.

Soon, Teleportal Apps will require your own API key, which can be generated from the Teleportal Developer Dashboard.

Credit

Copyright 2018 WiTag Inc.