Headless Automation

Run SpatialEngine without a GPU for data processing and other workflows that use statements without a rendered viewport.

Native engine

SpatialEngine --no-gpu

Connect through the Python SDK. This engine runs statements without drawing or streaming a viewport. Rendering and GPU-dependent work require a GPU-enabled engine.

Node.js

Use Node.js 22 or newer. Install the npm package, save this as automation.mjs, and run node automation.mjs.

Load the WebAssembly bytes from the installed package. Node’s fetch cannot read a local file: URL.

import { readFile } from "node:fs/promises";
import init, { statements } from "@fslabs/spatialengine";

try {
  const wasm = await readFile(new URL("./spatialengine.wasm", import.meta.resolve("@fslabs/spatialengine")));
  await init({ module_or_path: wasm, noGpu: true });
  const client = await statements();
  console.log(await client.std.print({ message: "Automation ready" }));
  process.exit(0);
} catch (error) {
  console.error(error);
  process.exit(1);
}

The engine keeps Node’s event loop alive. Exit after all required statements finish, including when a statement fails.

Web workers

In a web worker, pass the served WebAssembly URL to initialization:

import init, { statements } from "@fslabs/spatialengine";

await init({ module_or_path: new URL("./spatialengine.wasm", import.meta.url), noGpu: true });
const client = await statements();
console.log(await client.std.print({ message: "Automation ready" }));

Serve spatialengine.wasm beside the worker module or use its actual URL. noGpu defaults to true when the host has no document.

Ordering and completion

Await dependent statements in sequence. After project edits, use std.project.wait_for_scene_sync in Python or std.project.waitForSceneSync in TypeScript before reading scene state that depends on those edits.

Wait for all submitted transaction operations before committing. Independent calls can run concurrently.

Background pages

An in-page engine reduces updates when its page is inactive. Set continuousUpdates: true in init when background work needs subsequent frames to complete. This keeps the engine updating while the page is hidden.