Skip to content

Scene Runtime

Jump to bottom
Mateo Miccino edited this page Sep 5, 2023 · 9 revisions

Abstract

The SceneRuntime is responsible for running scenes that use SDK7.

To allow that, we're using ClearScript which is a V8 Wrapper (V8 is the most popular JavaScript Engine developed by Google).

The JavaScript context starts evaluating the code in the Init.js to provide the following functionality:

  • require
  • console (logging)
  • fetch (not implemented yet)
  • websocket (not implemented yet)

Then it evaluates the SDK7 Source Code from the User.

scene_runner

An SDK7 Scene exposes two methods that must be called from who manages the SceneRunner.

  • onStart(): called before the first frame.
  • onUpdate(deltaTime): called once per frame.

Then the Scene can call require to load modules.

Modules

(aka Kernel API)

The modules are the exchange of data between the Explorer and the SDK7, to provide the functionality for the SDK7. Those modules are defined in the protocol.

To load a module, the JavaScript code calls require(moduleName).

Example: If a content creator wants to teleport the user that is running the scene, they can use the function TeleportTo from the RestrictedActionsService module. That function is part of the SDK7 and the Explorer must implement it and provide the functionality for it.

Engine API Implementation

The Engine API is the main module where the CRDT messages are exchanged between the Explorer and the Scene Runtime to sync the entities and components.

Going deep in require(moduleName) function

The SDK7 scenes uses the require function for loading modules.

require

When an SDK7 scene calls require, the first entry point is the Init.js. There we can see that we call UnityOpsApi.LoadAndEvaluateCode(moduleName) that is calling the C# Implementation. That is evaluating the compiled V8 Code for that module, which is loaded in the GetJsModuleDictionary and those JavaScript codes can be found in the streaming assets javascript modules.

After the require, the scene can call the function for that module. The following diagram explains how it works using the ReadFile function from the Runtime Module

calling-module

How to implement a module

(recommended to read going deep in require before)

To implement a module, you need to:

  • Create the interface for it. (Example)
  • Create the implementation of the Interface. (Example)
  • Create the wrapper (that is used by JavaScript). That uses the interface mentioned above. (Example)
  • Create the JavaScript Module. (Example)
  • Adding the JavaScript Module to the list of the JS modules. (here)
  • Register the module in the Scene Runtime Implementation. (Example)

Implementation Flow

image

Scene downloading is initiated from Unity's ECS systems. The downloading itself is performed via the usual UnityWebRequest. ISceneFactory is responsible for doing this in an async manner. ISceneFactory exposes additional overloads to create scenes from files for testing purposes.

Apart from initiating Unity's web requests the scene lifecycle is thread agnostic and, thus, executes in a separate thread. It's a vital constituent of the performance the project is able to achieve:

  • Each instance of SceneEngine is relying on the thread pool
  • When the call to Engine is awaited its continuation is scheduled on the thread pool

⚠️ A single scene does not utilize a single thread. Threads will be changed according to the thread pool after each await. It means a developer can't make any assumptions about thread consistency.

  • API implementations must be thread-agnostic
  • Resources shared between them must be thread-safe

The scene itself is represented by ISceneFacade. It has the following capabilities:

  • StartUpdateLoop
  • SetTargetFPS: the update frequency of JS Scene is controlled from C#
  • DisposeAsync

When the scene is created its life cycle is controlled by ECS. ISceneFacade is added as a component to the entity representing the scene.

The process of scene downloading is described in detail in a separate section.

When the scene code along the modules is loaded SceneRuntimeImpl is responsible for creating a separate instance of the execution engine via ClearSript.

⚠️ There is no such concept as engine pooling: every scene creates a unique instance, and when it goes out of scope the instance is disposed of. It creates a considerable GC pressure but ScriptEngine is not reusable. ClearScript takes care of disposing of unmanaged resources.

Proceed to Systems to familiarize yourself with the ECS systems that manage the scenes' life cycle.

Scene Downloading

TODO insert a principle scheme

CRDT

We have our own custom allocation-free highly-performance implementation of the CRDT protocol.

Core characteristics:

  • The process executes off the main thread
  • PoolableCollections based on ArrayPool<T>.Shared hide the complexity of having individual pools for different collection types and provide thread-safety out of the box
  • No temporary allocations: Messages processing is driven by the implementation of IMemoryOwner<byte> that uses prewarmed pools under the hood. When the message is disposed of the rented buffer returns to the pool. This pool is thread-safe
  • State storing is based on structures that are designed to be as lightweight as possible
  • Messages deserialization is based on ReadOnlyMemory<byte> that is continuously advanced forward to prevent allocations
  • Deserialization uses ByteUtils to slice memory regions into typed structures in an unsafe manner. This process is much faster than the managed one and is close to reinterpret_cast from C

CRDT - ECS Bridge

Messages Reconciliation

SDK components

Synchronization with ECS

SDK7 to SDK6 Adaptation Layer

The Adaptation Layer is a bridge to adapt scenes from SDK6 to SDK7. Basically, it's an SDK7 Scene that implements SDK6. You can see that project here.

Injection Code

In order to run the Adaptation Layer, the Explorer is required to inject the SDK7 Source Code when it tries to download an SDK6 Scene.

We can see the difference in the following diagram:

adaptation_layer (1)

Going a bit deep into how it works, the SDK7 Adaptation Layer loads the SDK6 Source Code of the Scene (using RequireFile from the Runtime Module), and then it evaluates it, and starts adapting the SDK6 behavior to SDK7.

There is no need to take any other consideration of how the Adaptation Layer works after you load the SDK7 Adaptation Layer for the SDK6 Scene. The Explorer is running an SDK7 Scene like any other scene.

Clone this wiki locally