Globals

The scene runtime ensures the existence of certain objects and functions inside the sandboxed Javascript environment, in addition to the standard utilities such as Promise, Date or Math.

Globals #

The runtime injects 6 definitions in the scene’s global scope:

1. console: a simplified version of the typical console object.
2. exports: an object where the scene can add its public interface.
3. module: a container for the exports object.
4. require: a function to load runtime-provided modules by name.
5. fetch: a restricted implementation of the browser fetch function.
6. WebSocket: a restricted implementation of the browser WebSocket class.

All of these are defined as read-only properties, so they cannot be reassigned. Some will throw exceptions when used unless certain permissions are granted to the scene.

Console #

Scenes have access to a console object, much like the one provided by a browser or Node environment, though limited to only some of the methods you would normally find.

type Console = {
  log(...args: any): void
  info(...args: any): void
  debug(...args: any): void
  warning(...args: any): void
  error(...args: any): void
}

Just like their standard counterparts, each method takes variable arguments of any type and renders them as human-readable messages. For example, this is valid:

console.log("The thing just appeared", { thing: "foo" }, [1, 2, 3])

The precise behavior of these methods depends on the provider, but the messages must be accessible to scene developers debugging their code.

Imports and Exports #

Scenes can import and export objects using the traditional CommonJS module interface.

exports: Object
require(moduleName: string): Object

The require function allows scenes to access runtime-provided modules (such as EngineApi or RestrictedActions), and nothing else (it does not access NPM packages or modules by path).

Properties added to the exports object are the scene’s public interface and will be exposed to the runtime. In fact, scenes must expose at least one method to run properly (see execution).

HTTP and WebSockets #

The fetch and WebSocket globals work exactly like their well-known counterparts (see fetch and WebSocket in MDN), but with some restrictions enforced by the runtime.

When calling the fetch function:

• An error is thrown if the URL doesn’t begin with https://.
• An error is thrown if the scene doesn’t have the USE_FETCH permission.
• An implementation-defined timeout can abort the request.

When using the WebSocket class:

• An error is thrown if the URL doesn’t begin with wss:
• An error is thrown if the scene doesn’t have the USE_WEBSOCKET permission.

Apart from these differences, both cases follow standard behavior.