Documentation / scene / ScriptRegistry

Class: ScriptRegistry

Defined in: libs/scene/src/app/scriptregistry.ts:129

Resolves and builds VFS scripts. Editor mode transpiles TypeScript and bundles local graphs into data URLs; runtime mode returns script URLs directly. Bundles from one registry share module instances, while content-derived versions preserve unchanged instances and invalidate changed dependency graphs.

Constructors

Constructor

new ScriptRegistry(vfs, scriptsRoot): ScriptRegistry

Defined in: libs/scene/src/app/scriptregistry.ts:141

Parameters

vfs

VFS

The virtual file system for existence checks, reads, and path ops.

scriptsRoot

string

Root directory for script resolution (used with #/ specifiers).

Returns

ScriptRegistry

Accessors

VFS

Get Signature

get VFS(): VFS

Defined in: libs/scene/src/app/scriptregistry.ts:155

The active virtual file system.

Assigning a new VFS clears the build cache.

Returns

VFS

Set Signature

set VFS(vfs): void

Defined in: libs/scene/src/app/scriptregistry.ts:158

Parameters

vfs

VFS

Returns

void

---

scriptsRoot

Get Signature

get scriptsRoot(): string

Defined in: libs/scene/src/app/scriptregistry.ts:176

The root path used by #/ specifiers.

Returns

string

Set Signature

set scriptsRoot(path): void

Defined in: libs/scene/src/app/scriptregistry.ts:179

Parameters

path

string

Returns

void

Methods

invalidate()

invalidate(moduleId?): void

Defined in: libs/scene/src/app/scriptregistry.ts:191

Invalidates cached built module output for one logical module id, or clears the full cache.

Pass the same logical id shape that callers use with ScriptRegistry.resolveRuntimeUrl, for example /assets/scripts/foo.ts, /assets/scripts/foo.js, or /assets/scripts/foo.

Parameters

moduleId?

string

Optional logical module id to invalidate. Omit to clear the entire build cache.

Returns

void

---

fetchSource()

protected fetchSource(id): Promise<{ code: string; type: "js" | "ts"; path: string; }>

Defined in: libs/scene/src/app/scriptregistry.ts:236

Fetches raw source for a logical module id by probing known extensions.

Search order:

• If id already ends with .ts, .js, or .mjs and is a file -> return it.
• Else try .id.ts, then .id.js, then .id.mjs.

Parameters

id

string

Logical module identifier (absolute or logical path-like).

Returns

Promise<{ code: string; type: "js" | "ts"; path: string; }>

Source code, resolved path, and type ('js' | 'ts'), or undefined if not found.

---

resolveRuntimeUrl()

resolveRuntimeUrl(entryId): Promise<string>

Defined in: libs/scene/src/app/scriptregistry.ts:290

Resolves a module entry to a URL suitable for dynamic import.

Behavior:

• In editor mode, builds the module to a data URL.
• Otherwise, returns .js or .mjs URL directly:
  • If id ends with .js: return as-is.
  • If id ends with .mjs: return as-is.
  • If id ends with .ts: map to .js (assumes pre-built file exists).
  • Else: append .js.

Parameters

entryId

string

Entry module identifier (logical or path-like).

Returns

Promise<string>

A URL string that can be used in import(...).

---

getDependencies()

getDependencies(entryId, fromId, dependencies): Promise<void>

Defined in: libs/scene/src/app/scriptregistry.ts:315

Recursively gathers direct static and dynamic import dependencies for a module.

Only relative specifiers (./ or ../) are followed. Absolute, special, and bare module specifiers are ignored here.

Parameters

entryId

string

The starting (possibly relative) specifier from fromId.

fromId

string

The logical id of the module containing entryId.

dependencies

Record<string, string>

Output map of resolvedSourcePath -\> file contents.

Returns

Promise<void>

---

resolveLogicalId()

resolveLogicalId(spec, fromId?): Promise<string>

Defined in: libs/scene/src/app/scriptregistry.ts:731

Resolves a specifier to a logical id suitable for further processing.

Resolution rules:

• #/path: resolved against scriptsRoot via VFS join/normalize.
• ./ or ../: resolved relative to fromId directory (requires fromId).
• /absolute: treated as absolute from root (normalized).
• Bare module in editor mode: if /deps.lock.json exists and contains an entry, map to the dependency's entry path; otherwise return as-is.
• Else (non-editor bare module): return spec unchanged (external).

Parameters

spec

string

Import specifier string.

fromId?

string

Optional base logical id used for relative resolution.

Returns

Promise<string>

A normalized logical id or an external specifier string.

Throws

If a relative import is provided without fromId.

---

resolveSourcePath()

resolveSourcePath(logicalId): Promise<{ type: "js" | "ts"; path: string; }>

Defined in: libs/scene/src/app/scriptregistry.ts:769

Resolves a logical id to a concrete source path and type by probing extensions.

Rules:

• If logicalId ends with .ts or .js/.mjs and is a file, return it.
• Else probe logicalId.ts, logicalId.js, logicalId.mjs in that order.
• Maps .mjs to type 'js'.

Parameters

logicalId

string

The normalized logical module id (path-like).

Returns

Promise<{ type: "js" | "ts"; path: string; }>

{ type, path } or null if not found.