Writing Code

Uva runs Javascript in an unsandboxed environment, this gives you the freedom to do anything within the limits of JS. Scripts are activated only when the scene is playing.

Scripts attached to objects

Each object in a scene can have an unlimited amount of scripts attached to them. Scripts can be used on multiple objects.

To create or attach a script use the UI:

or use:

// attach a script at runtime, will trigger .init() too
world.attachScript(object, "scriptName.js");

In the script you can use 'this' to reference the object

// init is called after the scene has loaded, before the first frame
this.init = () => {
  this.setup = true;
};

// Any other code written outside a function will execute before init
const text = Text("hi!");

// update is called on each frame
this.update = (event) => {
  this.position.x += velocity * event.delta;
  text.position.x = this.position.x;
};

// This is called when stopping a project
this.onStop = () => {
  // clean up event listeners etc..
};

Differences with three.js

In order to optimise the scene, uva has a few additional things you need to know:

Scene Graph Management

For large scenes (2000+ objects), you'll want precise control over what gets updated.

Here’s how to manually control updates:

// Update the object's transform matrix this frame
// Call this if you change an object's position, rotation or scale
object.matrixUpdate = true;

// Update the object's transform matrix each frame
object.autoUpdateMatrix = true;

// Must be called for proper disposal of object
object.delete();

Updating Materials & Geometry

When making any changes to materials or geometry, use the following methods:

// Updating a material
object.material.update();

// Assigning a new material
object.setMaterial(newMaterial);

// Assigning new geometry
object.setGeometry(newGeometry);

Culling for Dynamic Objects

For highly dynamic scene objects, such as particles, it's usually best to disable culling.

// when creation an object
object.culling = false;

// after creation
object.setCulling(true);

TSL Shaders / Three Node materials

If you use TSL Node materials these will not be used in the standard optimised pipeline. If you have any other objects which use standard materials and you want them to use three's pipeline, set object.optimise = false

Automatic level of detail (LOD)

Uva dynamically adjusts the level of detail on large objects using meshlets. Distant parts of an object are rendered at lower detail automatically.

To disable LOD on a specific object:

object.LOD = false

Uva uses MeshOptimizer to handle this efficiently.

index.js

If you create an index.js file, this will be executed before all other scripts.

This can be useful for handling global state, importing libraries and initialisation.

Importing / Modules

You can import modules from your own scripts, or load ES modules from a URL/CDN.

import { EnterSpace, SelectItem } from "./Logic.js"
import * from "./Items.js"
import * as Tone from 'https://cdnjs.cloudflare.com/ajax/libs/tone/15.1.3/Tone.js'

Local development

When running locally any code you change is synchronised with the editor, and you can create new scripts by adding them in your local file system.