Unity Runtime

Introduction

Umbra Unity Runtime API provides a method for Unity developers to integrate rendering of Umbrafied models to their own application. Umbra can also be used in Unity without custom scripts, by creating a Umbra GameObject from editor and using the Unity Editor to render Umbra scenes.

Prerequisites

  • Unity 2018.1 or newer
  • Windows, MacOS (x86-64), iOS or Android
  • Umbra SDK for Unity

Getting Started

Before getting started you should make sure that the Umbra plugin is installed correctly by loading an Umbrafied model to the Unity Editor. Please see installation and usage instructions for help with this.

Overview

The Umbra Unity Runtime system consists of multiple types of gameObjects and attached components:

  • Runtime script
    • One instance per project, created by user
  • Scene Objects with attached SceneData script
    • Managed by runtime

If colliders are enabled, there are some additional objects and scripts:

  • CollisionController scripts attached to scenes (when colliders are enabled)
    • Attached to Scene object by user
  • Collision gameObjects
    • Managed by CollisionController

To render a scene using the Umbra Runtime, you need to do these steps:

  1. Create a gameObject and attach Runtime component to it
  2. Create a Scene to which you'll connect the Model
  3. Connect the Scene to the desired Model

Creating the Umbra Runtime

The main internal Umbra state in Unity is handled by the Runtime script. This can be created by attaching the script "Runtime" to any GameObject. This can be done either from the Unity Editor UI, or from script:

var runtime = gameObject.AddComponent<UmbraForUnity.Runtime>();

Note: Only one runtime script can be active in your project. Use a single runtime with multiple scenes to render multiple Umbra scenes at the same time.

Creating Scenes

Using this Runtime script we can create different scenes, each connecting to a model. Creating new scenes is done by using the runtime.

var scene = runtime.CreateScene();

Currently attached scenes can also be queried from the runtime:

var scenes = runtime.Scenes;

After a scene is created, the scene must be connected to a Model. Connecting a scene to a Model is done with the Scene method ConnectLocal, which takes a file or folder path representing a single Umbrafied model, called a "repository".

scene.ConnectLocal(path);

Note: Umbra scenes do not contain the mesh data itself, the streaming and rendering of meshes is handled by the Runtime.

Note: For easy deployment of the Unity application, it is preferable to store the repository under Application.streamingAssetsPath. More information is available in the Unity documentation.

Setting scene transform

Scene transforms are controlled by the Transform component of the gameObject the Scene script is connected to. Each scene is a child gameObject of the Runtime, so the transform is determined by the combined transform.

Full source listing

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using System.Linq;

[ExecuteInEditMode]
public class RuntimeExample : MonoBehaviour
{
    // Start is called before the first frame update
    void Start()
    {

    }

    void OnEnable()
    {
        // Assumes we have already added a Runtime script to this gameObject. Use AddComponent to add it if not.
        var runtime = gameObject.GetComponent<UmbraForUnity.Runtime>();
        var scenes = runtime.Scenes.ToList();
        var scene = scenes.Count > 0 ? scenes[0] : runtime.CreateScene();
        scene.ConnectLocal("<path here>");
    }

    // Update is called once per frame
    void Update()
    {
    }
}