Appearance
@bendyline/molen-tooling
Molen agent tooling: molen CLI and MCP server over a shared ops library.
ts
import { /* … */ } from '@bendyline/molen-tooling';Interfaces
ApplyUvPaintInput
Properties
dilationPx?
ts
optional dilationPx?: number;islandMapPath
ts
islandMapPath: string;Island map (flat-filled islands on a transparent/black background).
maskToIslands?
ts
optional maskToIslands?: boolean;outPath
ts
outPath: string;paintedPath
ts
paintedPath: string;Painted texture (from an image model).
ApplyUvPaintOutput
Properties
error?
ts
optional error?: string;height?
ts
optional height?: number;imagePath?
ts
optional imagePath?: string;ok
ts
ok: boolean;width?
ts
optional width?: number;AssetShotInput
Properties
angles?
ts
optional angles?: number;Number of turntable angles (default 4: front/right/back/left, slightly elevated).
assetVariant?
ts
optional assetVariant?: string;Render this packed variant (e.g. "ktx2") instead of the canonical main GLB.
clearColor?
ts
optional clearColor?: string;clip?
ts
optional clip?: string;Play this clip and pose it at clipTime seconds (default: bind pose).
clipTime?
ts
optional clipTime?: number;outDir
ts
outDir: string;projectPath?
ts
optional projectPath?: string;ref
ts
ref: string;Project asset id, or a sidecar path.
reflections?
ts
optional reflections?: boolean;Enable the viewer's shared procedural sky/ground reflection environment.
size?
ts
optional size?: [number, number];AssetShotOutput
Properties
error?
ts
optional error?: string;frames?
ts
optional frames?: object[];name
ts
name: string;path
ts
path: string;renderStats?
ts
optional renderStats?: RenderStats;ok
ts
ok: boolean;triangles?
ts
optional triangles?: number;CameraSpec
Properties
lookAt?
ts
optional lookAt?: Vec3;position
ts
position: Vec3;CheckTypesOutput
Properties
codegenStale?
ts
optional codegenStale?: boolean;error?
ts
optional error?: string;issues?
ts
optional issues?: ValidationIssue[];ok
ts
ok: boolean;DiffSnapshotsInput
Properties
a
ts
a: string;Two keyframe JSON file paths (before, after).
b
ts
b: string;DiffSnapshotsOutput
Properties
diffs?
ts
optional diffs?: ComponentDiff[];error?
ts
optional error?: string;ok
ts
ok: boolean;DocHit
Properties
design
ts
design: boolean;excerpt
ts
excerpt: string;path
ts
path: string;score
ts
score: number;DriveAction
Properties
at
ts
at: number;Tick this action applies at (actions are processed in ascending order).
camera?
ts
optional camera?: CameraSpec;Camera for this and subsequent frames (default: the scene's camera block).
command?
ts
optional command?: object;Submit a command (envelope is filled: source "drive", auto seq, tick = at).
payload?
ts
optional payload?: JsonValue;type
ts
type: string;screenshot?
ts
optional screenshot?: string;Capture a named frame once the world reaches this tick.
DriveFrame
Properties
name
ts
name: string;path
ts
path: string;renderStats?
ts
optional renderStats?: RenderStats;tick
ts
tick: number;DriveInput
Properties
actions
ts
actions: DriveAction[];assertDoc?
ts
optional assertDoc?: AssertionDoc;assertPath?
ts
optional assertPath?: string;assetVariant?
ts
optional assetVariant?: string;Render packed asset variants (e.g. "ktx2" from molen asset pack) where present.
clearColor?
ts
optional clearColor?: string;outDir
ts
outDir: string;Directory frames are written to (<name>.png).
projectPath?
ts
optional projectPath?: string;scene?
ts
optional scene?: SceneManifest | Record<string, unknown>;scenePath?
ts
optional scenePath?: string;setup?
ts
optional setup?: WorldSetup;setupModule?
ts
optional setupModule?: string;size?
ts
optional size?: [number, number];until?
ts
optional until?: number;Step to this tick after the last action (default: the last action's tick).
DriveOutput
Properties
assertionResults?
ts
optional assertionResults?: AssertionResult[];assertionsFormatted?
ts
optional assertionsFormatted?: string;error?
ts
optional error?: string;events?
ts
optional events?: object[];payload
ts
payload: JsonValue;tick
ts
tick: number;type
ts
type: string;frames?
ts
optional frames?: DriveFrame[];ok
ts
ok: boolean;stateHash?
ts
optional stateHash?: string;tick?
ts
optional tick?: number;ExperiencePlayDiagnostic
Properties
actionIndex
ts
actionIndex: number;kind
ts
kind: "console" | "page-error" | "request-failed";level?
ts
optional level?: string;text
ts
text: string;url?
ts
optional url?: string;ExperiencePlayFrame
Properties
actionIndex
ts
actionIndex: number;name
ts
name: string;path
ts
path: string;probes
ts
probes: Record<string, string>;ExperiencePlayInput
Properties
appDir
ts
appDir: string;Built browser-app directory containing index.html and its static assets.
headed?
ts
optional headed?: boolean;outDir
ts
outDir: string;scenario
ts
scenario:
| Record<string, unknown>
| ExperiencePlayScenario;ExperiencePlayOutput
Properties
diagnostics?
ts
optional diagnostics?: ExperiencePlayDiagnostic[];error?
ts
optional error?: string;frames?
ts
optional frames?: ExperiencePlayFrame[];manifestPath?
ts
optional manifestPath?: string;ok
ts
ok: boolean;scenario?
ts
optional scenario?: string;ExperiencePlayScenario
Properties
actions
ts
actions: ExperiencePlayAction[];format
ts
format: "molen/experience-play@1";name
ts
name: string;path?
ts
optional path?: string;probes?
ts
optional probes?: object[];name
ts
name: string;selector
ts
selector: string;viewport?
ts
optional viewport?: [number, number];ExportFramesInput
Properties
assetVariant?
ts
optional assetVariant?: string;Render packed asset variants (e.g. "ktx2" from molen asset pack) where present.
camera?
ts
optional camera?: CameraSpec;clearColor?
ts
optional clearColor?: string;from
ts
from: number;Inclusive tick range and stride.
outDir
ts
outDir: string;Directory frames are written to (frame_0000.png, …).
projectPath?
ts
optional projectPath?: string;Explicit project.json (default: discovered by walking up from the scene).
scene?
ts
optional scene?: SceneManifest | Record<string, unknown>;scenePath?
ts
optional scenePath?: string;Scene file path, or a scene NAME from the surrounding project.json.
setup?
ts
optional setup?: WorldSetup;setupModule?
ts
optional setupModule?: string;size?
ts
optional size?: [number, number];step?
ts
optional step?: number;to
ts
to: number;track?
ts
optional track?: CameraTrackDoc;A camera track (inline or path) followed over the range; else a fixed camera.
trackPath?
ts
optional trackPath?: string;ExportFramesOutput
Properties
dir?
ts
optional dir?: string;error?
ts
optional error?: string;frameCount?
ts
optional frameCount?: number;frames?
ts
optional frames?: string[];ok
ts
ok: boolean;FrameRegion
A rectangle as fractions of the frame (0 to 1), so a check reads the same at any size.
Properties
height
ts
height: number;width
ts
width: number;x
ts
x: number;y
ts
y: number;FrameStats
Properties
background
ts
background: [number, number, number];The frame's most common color, taken as its backdrop: the clear color or an even sky.
colors
ts
colors: number;Distinct colors among the measured pixels, each channel quantized to 32 levels.
coverage
ts
coverage: number;Fraction of the measured pixels that differ from the background by more than tolerance.
height
ts
height: number;luminance
ts
luminance: number;Mean of (r + g + b) / 3 over the measured pixels, 0-255.
mean
ts
mean: [number, number, number];Mean color of the measured pixels.
width
ts
width: number;FrameStatsOptions
Properties
region?
ts
optional region?: FrameRegion;Measure only this part of the frame. The background is still the whole frame's.
tolerance?
ts
optional tolerance?: number;Channel difference above which a pixel counts as content, not background (default 24).
GenerateTypesInput
Properties
check?
ts
optional check?: boolean;Compare only — exit stale without writing (CI / types check).
cwd?
ts
optional cwd?: string;out?
ts
optional out?: string;Override the output path (default: project.codegen.out).
projectPath?
ts
optional projectPath?: string;GenerateTypesOutput
Properties
componentCount?
ts
optional componentCount?: number;error?
ts
optional error?: string;ok
ts
ok: boolean;outPath?
ts
optional outPath?: string;scriptArtifacts?
ts
optional scriptArtifacts?: GeneratedScriptArtifact[];Ambient script types written (or checked) beside each scripts directory.
stale?
ts
optional stale?: boolean;True when --check found the committed file out of date (or missing).
typeCount?
ts
optional typeCount?: number;written?
ts
optional written?: boolean;GetComponentOutput
Properties
description?
ts
optional description?: string;docsRef?
ts
optional docsRef?: string;error?
ts
optional error?: string;examples?
ts
optional examples?: unknown[];jsonSchema?
ts
optional jsonSchema?: unknown;name?
ts
optional name?: string;ok
ts
ok: boolean;owner?
ts
optional owner?: string;GetSchemaOutput
Properties
docsRef?
ts
optional docsRef?: string;error?
ts
optional error?: string;examples?
ts
optional examples?: unknown[];id?
ts
optional id?: string;jsonSchema?
ts
optional jsonSchema?: unknown;ok
ts
ok: boolean;GoldenOptions
Properties
maxDiffRatio?
ts
optional maxDiffRatio?: number;Maximum fraction of differing pixels tolerated (default 0.003).
GoldenResult
Properties
created
ts
created: boolean;diffRatio?
ts
optional diffRatio?: number;ok
ts
ok: boolean;reason?
ts
optional reason?: string;ImageDiff
Properties
diffPixels
ts
diffPixels: number;diffRatio
ts
diffRatio: number;match
ts
match: boolean;reason?
ts
optional reason?: string;ImportAssetInput
Properties
assetDir?
ts
optional assetDir?: string;Exact bundle directory, relative to cwd when not absolute. Mutually exclusive with outDir. Without either override, reimports preserve the project-registered asset directory; new assets use <project dir>/assets/<dotted-id-as-path> (or ./assets without a project).
cwd?
ts
optional cwd?: string;Directory the discovery starts from (default: process.cwd()).
force?
ts
optional force?: boolean;Replace files in an existing asset directory. Default false.
id?
ts
optional id?: string;Asset id (default: slugged filename). Dotted ids fall under namespace reservations.
optimize?
ts
optional optimize?: boolean;Skip the normalize pass (dedup/prune/weld/quantize).
outDir?
ts
optional outDir?: string;Output assets root; explicit overrides retain the <root>/<dotted-id-as-path> layout.
path
ts
path: string;Source model file (.glb / .gltf).
projectPath?
ts
optional projectPath?: string;Explicit project.json (default: discovered; import still works without one).
trimesh?
ts
optional trimesh?: boolean;Also extract a whole-asset collision trimesh into collision.bin.
ImportAssetOutput
Properties
dir?
ts
optional dir?: string;error?
ts
optional error?: string;id?
ts
optional id?: string;ok
ts
ok: boolean;projectPath?
ts
optional projectPath?: string;The project.json that was (or would have been) updated — always report it.
registered?
ts
optional registered?: boolean;True when the asset was registered into a project manifest.
sidecar?
ts
optional sidecar?: AssetSidecar;sidecarPath?
ts
optional sidecarPath?: string;warnings?
ts
optional warnings?: string[];InspectAssetInput
Properties
cwd?
ts
optional cwd?: string;projectPath?
ts
optional projectPath?: string;ref
ts
ref: string;Sidecar path, or a project asset id.
verify?
ts
optional verify?: boolean;Re-hash files.main / collision.bin and compare against the sidecar.
InspectAssetOutput
Properties
error?
ts
optional error?: string;ok
ts
ok: boolean;sidecar?
ts
optional sidecar?: AssetSidecar;sidecarPath?
ts
optional sidecarPath?: string;verified?
ts
optional verified?: boolean;verifyErrors?
ts
optional verifyErrors?: string[];ListAssetsOutput
Properties
assets?
ts
optional assets?: object[];id
ts
id: string;kind?
ts
optional kind?: string;sidecar
ts
sidecar: string;triangles?
ts
optional triangles?: number;error?
ts
optional error?: string;ok
ts
ok: boolean;ListTemplatesOutput
Properties
error?
ts
optional error?: string;ok
ts
ok: boolean;templates
ts
templates: TemplateEntry[];ListTypesOutput
Properties
error?
ts
optional error?: string;ok
ts
ok: boolean;types?
ts
optional types?: object[];doc?
ts
optional doc?: string;extends?
ts
optional extends?: string;id
ts
id: string;source
ts
source: string;LoadedScene
Properties
manifest
ts
manifest: SceneManifest;notices
ts
notices: ValidationIssue[];Non-fatal advisories from validation (e.g. deprecated_format after a v1 auto-upgrade).
project?
ts
optional project?: ProjectContext;scenePath
ts
scenePath: string;LoadSceneOptions
Properties
cwd?
ts
optional cwd?: string;projectPath?
ts
optional projectPath?: string;Explicit project.json path; otherwise discovered by walking up from the scene/cwd.
OpDescriptor
Properties
cli?
ts
optional cli?: string;CLI invocation form, if exposed on the CLI.
mcpTool?
ts
optional mcpTool?: string;MCP tool name, if exposed over MCP.
name
ts
name: string;Stable op name (matches the MCP tool name where one exists).
params
ts
params: OpParam[];summary
ts
summary: string;OpParam
Properties
cliOnly?
ts
optional cliOnly?: boolean;True for a parameter that exists only on the CLI — the MCP tool derives it (for example an output directory the tool allocates and returns images from). test/catalog.test.ts requires every other param to match the MCP tool's input schema exactly.
description
ts
description: string;name
ts
name: string;required
ts
required: boolean;type
ts
type: string;PackAssetInput
Properties
all?
ts
optional all?: boolean;Pack every asset registered in the project manifest.
cwd?
ts
optional cwd?: string;etc1sQuality?
ts
optional etc1sQuality?: number;ETC1S quality 1..255 (default 128).
maxSize?
ts
optional maxSize?: number;Longest texture side after resizing (default 2048).
mode?
ts
optional mode?: "auto" | PackTextureMode;Force one codec for every texture; "auto" (default) picks per slot / color space.
powerOfTwo?
ts
optional powerOfTwo?: boolean;Snap each texture side to the nearest power of two (default true; mip-friendly).
projectPath?
ts
optional projectPath?: string;ref?
ts
optional ref?: string;Project asset id, or a sidecar path. Omit with all: true to pack every project asset.
uastcQuality?
ts
optional uastcQuality?: number;UASTC pack quality 0..4 (default 2; higher is slower and slightly better).
variant?
ts
optional variant?: string;Variant name recorded in the sidecar (default "ktx2"); the file is model.<variant>.glb.
PackAssetOutput
Properties
assets?
ts
optional assets?: PackedAsset[];error?
ts
optional error?: string;ok
ts
ok: boolean;warnings?
ts
optional warnings?: string[];PackedAsset
Properties
bytes
ts
bytes: object;File sizes of the canonical main GLB and the packed variant.
main
ts
main: number;variant
ts
variant: number;gpuBytesEstimate
ts
gpuBytesEstimate: object;Estimated GPU texture memory (with mips) before/after: RGBA8 source vs. 8 bits per texel (ASTC 4x4 / BC7). Real ETC1S transcode targets (BC1/ETC1) are half that on some GPUs.
compressed
ts
compressed: number;rgba8
ts
rgba8: number;id
ts
id: string;path
ts
path: string;Absolute path of the written variant GLB.
sidecarPath
ts
sidecarPath: string;textures
ts
textures: PackedTexture[];variant
ts
variant: string;PackedTexture
Properties
colorSpace
ts
colorSpace: "srgb" | "linear";mode
ts
mode: PackTextureMode;name
ts
name: string;packed
ts
packed: object;bytes
ts
bytes: number;height
ts
height: number;levels
ts
levels: number;width
ts
width: number;slots
ts
slots: string[];Material slots the texture feeds (e.g. baseColorTexture, normalTexture).
source
ts
source: object;bytes
ts
bytes: number;height
ts
height: number;mimeType
ts
mimeType: string;width
ts
width: number;ProjectContext
Properties
componentRegistry
ts
componentRegistry: ComponentRegistry;content
ts
content: ContentIdentity;Which pack content the project's worlds are built from; empty without packs.
dir
ts
dir: string;manifest
ts
manifest: ProjectManifest;packs
ts
packs: PackSet;Content packs the project uses (project.json packs, then MOLEN_PACKS).
path
ts
path: string;resolvedTypes
ts
resolvedTypes: ResolvedTypes;Flattened type id -> final component map (what the kernel consumes).
typeIssues
ts
typeIssues: ValidationIssue[];Project-level cross-check issues (duplicates, ownership, dangling refs).
typeScriptFiles
ts
typeScriptFiles: object[];File-backed scripts declared by registry types, before their paths are inlined.
config
ts
config: JsonObject;declaration
ts
declaration: string;file
ts
file: string;scriptId
ts
scriptId: string;typeId
ts
typeId: string;typesDocs
ts
typesDocs: object[];doc
ts
doc: TypesDoc;source
ts
source: string;Methods
resolveScenePath()
ts
resolveScenePath(nameOrPath): string;Resolve a scene name (from manifest.scenes) or a path into an absolute scene path.
Parameters
nameOrPath
string
Returns
string
ProjectInfoInput
Properties
cwd?
ts
optional cwd?: string;projectPath?
ts
optional projectPath?: string;ProjectInfoOutput
Properties
assets?
ts
optional assets?: Record<string, string>;defaultScene?
ts
optional defaultScene?: string;error?
ts
optional error?: string;issues?
ts
optional issues?: ValidationIssue[];name?
ts
optional name?: string;ok
ts
ok: boolean;path?
ts
optional path?: string;reservations?
ts
optional reservations?: NamespaceReservation[];scenes?
ts
optional scenes?: Record<string, string>;setup?
ts
optional setup?: string;typeIds?
ts
optional typeIds?: string[];RasterizeInput
Properties
inline?
ts
optional inline?: unknown;outPath
ts
outPath: string;Output PNG path for the baseColor slot.
path?
ts
optional path?: string;Path to a material doc (*.matgraph.json, *.pixelgrid.json, or *.svg) or inline doc.
ref?
ts
optional ref?: string;Or a "palette:#rrggbb" / "#rrggbb" inline material ref.
size?
ts
optional size?: number;Optional override size for palette refs / SVG raster width.
RasterizeOutput
Properties
error?
ts
optional error?: string;height?
ts
optional height?: number;imagePath?
ts
optional imagePath?: string;ok
ts
ok: boolean;slots?
ts
optional slots?: string[];width?
ts
optional width?: number;RenderStats
Properties
drawCalls
ts
drawCalls: number;entitiesRendered
ts
entitiesRendered: number;triangles
ts
triangles: number;ReserveNamespaceInput
Properties
cwd?
ts
optional cwd?: string;namespace
ts
namespace: string;note?
ts
optional note?: string;owner
ts
owner: string;projectPath?
ts
optional projectPath?: string;ReserveNamespaceOutput
Properties
alreadyReserved?
ts
optional alreadyReserved?: boolean;True when the same owner already held the namespace (no-op).
conflict?
ts
optional conflict?: NamespaceReservation;Set on conflict: who holds the overlapping namespace.
error?
ts
optional error?: string;ok
ts
ok: boolean;reservations?
ts
optional reservations?: NamespaceReservation[];RunReplayInput
Properties
path
ts
path: string;Path to a *.replay.json fixture.
projectPath?
ts
optional projectPath?: string;Explicit project.json for the fixture's scene (default: discovered from the scene path).
record?
ts
optional record?: boolean;Regenerate expected.stateHash + expected.tickHashes from the current build and write them back to the fixture (run after an intentional engine/content change).
setupModule?
ts
optional setupModule?: string;Module providing systems + command handlers (default/named setup).
RunReplayOutput
Properties
actualEventCount?
ts
optional actualEventCount?: number;actualHash?
ts
optional actualHash?: string;deterministic?
ts
optional deterministic?: boolean;True when the build reproduces itself run-to-run (only checked on a hash mismatch).
diff?
ts
optional diff?: ComponentDiff[];Component-level diff at the divergent tick (available for non-deterministic builds).
divergence?
ts
optional divergence?: "non-deterministic" | "behavior-drift";Classifies a mismatch so the fix is obvious.
error?
ts
optional error?: string;Set when something failed before running (bad fixture/scene).
expectedEventCount?
ts
optional expectedEventCount?: number;expectedHash?
ts
optional expectedHash?: string;firstDivergentTick?
ts
optional firstDivergentTick?: number;First tick at which state diverged (from the self-determinism check or tickHashes).
ok
ts
ok: boolean;report?
ts
optional report?: string;Agent-facing summary of what happened and what to do.
ticks?
ts
optional ticks?: number;ScaffoldInput
Properties
dir?
ts
optional dir?: string;Parent directory (default: cwd).
force?
ts
optional force?: boolean;Replace scaffold-owned files that already exist. Default false.
name
ts
name: string;Experience name; also the output folder name and the type namespace.
template?
ts
optional template?: string;Copy a shipped sample instead of the built-in starter: a template id from listTemplates() (molen templates), e.g. cubes or top-down-arena.
ScaffoldOutput
Properties
dir?
ts
optional dir?: string;error?
ts
optional error?: string;files?
ts
optional files?: string[];nextSteps?
ts
optional nextSteps?: string[];ok
ts
ok: boolean;ScreenshotInput
Properties
assetVariant?
ts
optional assetVariant?: string;Render packed asset variants (e.g. "ktx2" from molen asset pack) where present.
camera?
ts
optional camera?: CameraSpec;clearColor?
ts
optional clearColor?: string;Background clear color; defaults to sky-blue with terrain, else dark.
outPath
ts
outPath: string;projectPath?
ts
optional projectPath?: string;Explicit project.json (default: discovered by walking up from the scene).
reflections?
ts
optional reflections?: boolean;Enable the viewer's shared procedural sky/ground reflections for PBR metals and glass.
scene?
ts
optional scene?: SceneManifest | Record<string, unknown>;A full manifest or any raw scene doc (it is validated and defaulted internally).
scenePath?
ts
optional scenePath?: string;Scene file path, or a scene NAME from the surrounding project.json.
setup?
ts
optional setup?: WorldSetup;setupModule?
ts
optional setupModule?: string;size?
ts
optional size?: [number, number];terrain?
ts
optional terrain?: TerrainShot;ticks
ts
ticks: number;ScreenshotOutput
Properties
error?
ts
optional error?: string;imagePath?
ts
optional imagePath?: string;ok
ts
ok: boolean;renderStats?
ts
optional renderStats?: RenderStats;stateHash?
ts
optional stateHash?: string;tick?
ts
optional tick?: number;ScriptDiagnostic
Properties
code
ts
code: string;column
ts
column: number;file
ts
file: string;Project-relative script path.
line
ts
line: number;message
ts
message: string;SearchDocsInput
Properties
baseDir?
ts
optional baseDir?: string;Override the base dir to search from (defaults to the located bundle root).
includeDesign?
ts
optional includeDesign?: boolean;Also search the historical design plan in docs/, which may lag the code. Off by default — those hits describe intent, not the shipped engine. When on, they are tagged.
k?
ts
optional k?: number;query
ts
query: string;SearchDocsOutput
Properties
formatted
ts
formatted: string;hits
ts
hits: DocHit[];ok
ts
ok: boolean;root?
ts
optional root?: string;SimulateInput
Extended by
Properties
assertDoc?
ts
optional assertDoc?: AssertionDoc;assertPath?
ts
optional assertPath?: string;commands?
ts
optional commands?: Command[];commandsPath?
ts
optional commandsPath?: string;projectPath?
ts
optional projectPath?: string;Explicit project.json (default: discovered by walking up from the scene).
scene?
ts
optional scene?: SceneManifest;scenePath?
ts
optional scenePath?: string;Scene file path, or a scene NAME from the surrounding project.json.
setup?
ts
optional setup?: WorldSetup;Programmatic setup (systems + command handlers); takes precedence over setupModule.
setupModule?
ts
optional setupModule?: string;Path to a module exporting setup(world, manifest) or a defineExperience(...) result.
ticks
ts
ticks: number;SimulateOutput
Properties
ambient?
ts
optional ambient?: object;Ambient life at the final tick, when the scene has an ambient block.
agents
ts
agents: Record<string, number>;despawned
ts
despawned: number;lanes
ts
lanes: number;spawned
ts
spawned: number;assertionResults
ts
assertionResults: AssertionResult[];assertionsFormatted?
ts
optional assertionsFormatted?: string;content?
ts
optional content?: ContentIdentity;The pack content the world was built from (project.json packs, MOLEN_PACKS).
error?
ts
optional error?: string;Set when something failed before running (bad scene, etc.).
eventCount
ts
eventCount: number;events
ts
events: RecordedEvent[];notices?
ts
optional notices?: ValidationIssue[];Non-fatal advisories (e.g. deprecated scene format).
ok
ts
ok: boolean;physics?
ts
optional physics?: "none" | "kinematics" | "platformer" | "rapier";The scene's physics engine, when declared (kinematics = cross-platform deterministic).
stateHash
ts
stateHash: string;tick
ts
tick: number;SimWatchHandle
Methods
close()
ts
close(): void;Returns
void
SimWatchInput
Extends
Properties
assertDoc?
ts
optional assertDoc?: AssertionDoc;Inherited from
assertPath?
ts
optional assertPath?: string;Inherited from
commands?
ts
optional commands?: Command[];Inherited from
commandsPath?
ts
optional commandsPath?: string;Inherited from
projectPath?
ts
optional projectPath?: string;Explicit project.json (default: discovered by walking up from the scene).
Inherited from
scene?
ts
optional scene?: SceneManifest;Inherited from
scenePath?
ts
optional scenePath?: string;Scene file path, or a scene NAME from the surrounding project.json.
Inherited from
setup?
ts
optional setup?: WorldSetup;Programmatic setup (systems + command handlers); takes precedence over setupModule.
Inherited from
setupModule?
ts
optional setupModule?: string;Path to a module exporting setup(world, manifest) or a defineExperience(...) result.
Inherited from
ticks
ts
ticks: number;Inherited from
watchPaths?
ts
optional watchPaths?: string[];Extra files/directories to watch (transitive project/scene inputs are automatic).
Methods
onRun()
ts
onRun(result, diff): void;Called after every completed run with the result + a diff line against the previous run.
Parameters
result
diff
string
Returns
void
StageAssetsInput
Properties
clean?
ts
optional clean?: boolean;Remove a previous staging output first (only a directory holding assets.index.json).
cwd?
ts
optional cwd?: string;outDir
ts
outDir: string;Output directory (created).
projectPath?
ts
optional projectPath?: string;requireVariant?
ts
optional requireVariant?: boolean;Require the variant on every asset instead of falling back to the main file.
variant?
ts
optional variant?: string;Prefer this packed variant (e.g. "ktx2"); assets without it stage their main file.
StageAssetsOutput
Properties
assets?
ts
optional assets?: StagedAsset[];error?
ts
optional error?: string;index?
ts
optional index?: Record<string, string>;indexPath?
ts
optional indexPath?: string;ok
ts
ok: boolean;outDir?
ts
optional outDir?: string;warnings?
ts
optional warnings?: string[];StagedAsset
Properties
bytes
ts
bytes: number;file
ts
file: string;Staged model URL relative to outDir (also the index entry).
id
ts
id: string;variant?
ts
optional variant?: string;The variant that was staged, when one was.
TemplateEntry
Properties
description
ts
description: string;One line on what the sample shows.
id
ts
id: string;Template id: the sample's directory name in the engine repository (e.g. cubes).
TestTypesInput
Properties
cwd?
ts
optional cwd?: string;only?
ts
optional only?: string[];Only test these type ids (default: all).
projectPath?
ts
optional projectPath?: string;ticks?
ts
optional ticks?: number;Ticks to simulate each type for (default 30).
TestTypesOutput
Properties
error?
ts
optional error?: string;ok
ts
ok: boolean;results?
ts
optional results?: TypeTestResult[];TypeTestResult
Properties
error?
ts
optional error?: string;id
ts
id: string;issues?
ts
optional issues?: ValidationIssue[];ok
ts
ok: boolean;ValidateInput
Properties
inline?
ts
optional inline?: unknown;kind?
ts
optional kind?: string;Force a schema kind (any registered kind); otherwise detected from the envelope.
path?
ts
optional path?: string;Path to a JSON document, or inline data. One of the two is required.
projectPath?
ts
optional projectPath?: string;Explicit project.json giving a scene its registry types (default: discovered by walking up from path). With a project, entity/prefab type references are checked too.
verifyFiles?
ts
optional verifyFiles?: boolean;For terrain-package files, stream-check declared paths, sizes, and SHA-256 hashes.
ValidateOutput
Properties
formatted?
ts
optional formatted?: string;Present when not ok: the agent-facing formatted error block.
issues?
ts
optional issues?: unknown[];kind?
ts
optional kind?: string;ok
ts
ok: boolean;value?
ts
optional value?: unknown;Present when ok: the parsed (defaults-applied) value.
verifiedFiles?
ts
optional verifiedFiles?: number;WorldgenBakeInput
Properties
batchPath?
ts
optional batchPath?: string;A molen/worldgen-batch@1 document; or give outline (+ styleId) for one building.
force?
ts
optional force?: boolean;Replace an existing asset directory.
ground?
ts
optional ground?: "flat" | "slope";id?
ts
optional id?: string;Asset id (default: the batch name, slugged).
outDir
ts
outDir: string;Assets root the baked asset directory is created under.
outline?
ts
optional outline?: string;"x,z;x,z;..." in meters, one building.
packPath?
ts
optional packPath?: string;Style pack manifest or directory (default: the shipped default pack).
projectPath?
ts
optional projectPath?: string;styleId?
ts
optional styleId?: string;Force every building onto this style id (required with outline).
WorldgenBakeOutput
Properties
dir?
ts
optional dir?: string;error?
ts
optional error?: string;glbBytes?
ts
optional glbBytes?: number;hash?
ts
optional hash?: string;id?
ts
optional id?: string;ok
ts
ok: boolean;placements?
ts
optional placements?: object[];Instanced placements the mesh does not contain (roof props, scatter).
count
ts
count: number;modelRef
ts
modelRef: string;sidecar?
ts
optional sidecar?: AssetSidecar;sidecarPath?
ts
optional sidecarPath?: string;stats?
ts
optional stats?: WorldgenStats;warnings?
ts
optional warnings?: string[];WorldgenPreviewInput
Properties
angles?
ts
optional angles?: number;Turntable angles (default 1).
batchPath?
ts
optional batchPath?: string;A molen/worldgen-batch@1 document (default: the built-in lineup of every shape class).
clearColor?
ts
optional clearColor?: string;ground?
ts
optional ground?: "flat" | "slope";outPath
ts
outPath: string;PNG path; with several angles the index is appended before the extension.
packPath?
ts
optional packPath?: string;Style pack manifest or directory (default: the shipped default pack).
scatterId?
ts
optional scatterId?: string;size?
ts
optional size?: [number, number];styleId?
ts
optional styleId?: string;Force every building onto this style id (default: the pack's own rules).
stylePath?
ts
optional stylePath?: string;A standalone molen/archstyle@1 document to preview (injected into the pack).
WorldgenPreviewOutput
Properties
error?
ts
optional error?: string;frames?
ts
optional frames?: WorldgenPreviewFrame[];hash?
ts
optional hash?: string;materialFailures?
ts
optional materialFailures?: string[];Material references the page could not bake (rendered flat).
ok
ts
ok: boolean;renderStats?
ts
optional renderStats?: WorldgenPreviewRenderStats;stats?
ts
optional stats?: WorldgenStats;WorldgenStatsInput
Properties
atlasPath?
ts
optional atlasPath?: string;auto?
ts
optional auto?: boolean;Search the 9x9 tiles around the center for the one with the most buildings.
dumpPath?
ts
optional dumpPath?: string;Write the adapted batch document here.
packagePath
ts
packagePath: string;terrain-package.json path.
packPath?
ts
optional packPath?: string;quality?
ts
optional quality?: WorldgenQualityPreset;styleId?
ts
optional styleId?: string;Force every building onto this style id.
tile?
ts
optional tile?: string;"z/x/y" tile address; omit to use the tile at the package center (auto searches around it).
WorldgenStatsOutput
Properties
buildingsWithoutIds?
ts
optional buildingsWithoutIds?: number;Buildings whose identity came from a quantized centroid (no feature id in the source).
clippedPieces?
ts
optional clippedPieces?: number;deterministic?
ts
optional deterministic?: boolean;dumpPath?
ts
optional dumpPath?: string;error?
ts
optional error?: string;generateMs?
ts
optional generateMs?: object;first
ts
first: number;second
ts
second: number;hash?
ts
optional hash?: string;ok
ts
ok: boolean;placements?
ts
optional placements?: object[];count
ts
count: number;modelRef
ts
modelRef: string;region?
ts
optional region?: string;scatter?
ts
optional scatter?: string;skippedByOwnership?
ts
optional skippedByOwnership?: number;source?
ts
optional source?: object;buildings
ts
buildings: number;landcover
ts
landcover: number;roads
ts
roads: number;water
ts
water: number;stats?
ts
optional stats?: WorldgenStats;tile?
ts
optional tile?: object;level
ts
level: number;x
ts
x: number;y
ts
y: number;warnings?
ts
optional warnings?: string[];Type Aliases
ExperiencePlayAction
ts
type ExperiencePlayAction = ExperiencePlayActionBase &
| {
durationMs: number;
type: "wait";
}
| {
selector: string;
text?: string;
timeoutMs?: number;
type: "wait-for";
}
| {
selector: string;
stableMs?: number;
text?: string;
timeoutMs?: number;
type: "wait-for-stable";
}
| {
durationMs: number;
keys: string[];
type: "keys";
}
| {
keys: string[];
type: "key-down";
}
| {
keys: string[];
type: "key-up";
}
| {
durationMs?: number;
from: [number, number];
selector: string;
steps?: number;
to: [number, number];
type: "drag";
}
| {
selector: string;
type: "click";
}
| {
selector: string;
type: "select";
value: string;
}
| {
path: string;
type: "navigate";
}
| {
fullPage?: boolean;
name: string;
settleMs?: number;
timeoutMs?: number;
type: "screenshot";
};PackTextureMode
ts
type PackTextureMode = "etc1s" | "uastc";Variables
ASSET_INDEX_FILE
ts
const ASSET_INDEX_FILE: "assets.index.json" = "assets.index.json";OPS_CATALOG
ts
const OPS_CATALOG: OpDescriptor[];Machine-readable contract for every agent-facing operation. The CLI help and the MCP describe_op tool both render this, so an agent can discover I/O without reading source.
TOOLING_PACKAGE
ts
const TOOLING_PACKAGE: "@bendyline/molen-tooling" = "@bendyline/molen-tooling";Functions
applyUvPaintOp()
ts
function applyUvPaintOp(input): Promise<ApplyUvPaintOutput>;Import a painted UV template: mask it to the island map and dilate the gutters (docs-src/guide/materials.md, "Rung 5 — UV paint-by-numbers"). The MCP apply_uv_paint tool. (Template/sidecar generation from a mesh via xatlas is a separate, heavier Node toolchain step.)
Parameters
input
Returns
Promise<ApplyUvPaintOutput>
assetFileIndex()
ts
function assetFileIndex(project, opts?): Promise<Record<string, string>>;Resolve asset ids to their sidecar-declared primary files for browser renderers. With variant, a packed variant (molen asset pack) replaces the main file where present.
Parameters
project
opts?
variant?
string
Returns
Promise<Record<string, string>>
bakeWorldgen()
ts
function bakeWorldgen(input): Promise<WorldgenBakeOutput>;Parameters
input
Returns
Promise<WorldgenBakeOutput>
buildContentPack()
ts
function buildContentPack(input): Promise<BuildPackOutput>;Parameters
input
BuildPackInput
Returns
Promise<BuildPackOutput>
checkScripts()
ts
function checkScripts(input): Promise<CheckScriptsOutput>;Typecheck every file-backed scene or registry-type script in the project.
Parameters
input
CheckScriptsInput
Returns
Promise<CheckScriptsOutput>
checkTypesOp()
ts
function checkTypesOp(input): Promise<CheckTypesOutput>;Parameters
input
Returns
Promise<CheckTypesOutput>
compareGolden()
ts
function compareGolden(
candidatePath,
goldenPath,
diffPath,
opts?
): Promise<GoldenResult>;Compare a freshly rendered candidate PNG against a committed golden. Records the golden only when UPDATE_GOLDENS=1. Tolerance: per-pixel threshold 0.1, max maxDiffRatio differing pixels (default 0.3%).
A missing golden fails. Silently adopting the candidate would make "this test has no reference image" indistinguishable from "this test passed" — and in a fresh CI checkout every uncommitted golden would take that branch, so a suite could report green while comparing nothing.
Parameters
candidatePath
string
goldenPath
string
diffPath
string
opts?
Returns
Promise<GoldenResult>
describeOps()
ts
function describeOps(name?): OpDescriptor[];Return the full catalog, or just the entry whose name/cli/mcpTool matches name.
Parameters
name?
string
Returns
diffImages()
ts
function diffImages(
aPath,
bPath,
diffPath,
maxDiffRatio?
): Promise<ImageDiff>;Pixel-diff two PNGs; writes a diff image. Per-pixel threshold 0.1.
Parameters
aPath
string
bPath
string
diffPath
string
maxDiffRatio?
number
Returns
Promise<ImageDiff>
diffSnapshots()
ts
function diffSnapshots(input): Promise<DiffSnapshotsOutput>;Diff two keyframe snapshots at the component level.
Parameters
input
Returns
Promise<DiffSnapshotsOutput>
driveScene()
ts
function driveScene(input): Promise<DriveOutput>;Drive a scene: commands in, frames out, deterministically.
Parameters
input
Returns
Promise<DriveOutput>
exportFrames()
ts
function exportFrames(input): Promise<ExportFramesOutput>;Render a sequence of frames over a tick range, optionally following a camera track (machinima). Builds the world once and steps incrementally so every frame is from the same timeline.
Parameters
input
Returns
Promise<ExportFramesOutput>
extractContentPack()
ts
function extractContentPack(input): Promise<ExtractPackOutput>;Parameters
input
ExtractPackInput
Returns
Promise<ExtractPackOutput>
fetchContentPack()
ts
function fetchContentPack(input): Promise<FetchPackOutput>;Download packs into a project so it runs offline, and pin them in project.json packs with their contentHash. Nothing is fetched implicitly anywhere else: this is the explicit step.
Parameters
input
FetchPackInput
Returns
Promise<FetchPackOutput>
findProjectFile()
ts
function findProjectFile(startDir): Promise<string | undefined>;Walk from startDir up to the fs root looking for a project.json with the right envelope.
Parameters
startDir
string
Returns
Promise<string | undefined>
formatOp()
ts
function formatOp(op): string;Render one descriptor as agent-facing help text.
Parameters
op
Returns
string
frameStats()
ts
function frameStats(path, options?): Promise<FrameStats>;Measure a rendered frame without a reference image: how much of it is content, how varied it is, and its mean color, for the whole frame or a region. Checks built on these (the frame is not blank, the model covers its part of the view, a lit room is brighter than an unlit one) hold on any machine, where a pixel comparison needs a reference recorded on the machine that compares.
Parameters
path
string
options?
Returns
Promise<FrameStats>
generateTypes()
ts
function generateTypes(input): Promise<GenerateTypesOutput>;Generate (or verify with check) the project's typed component/type-id module.
Parameters
input
Returns
Promise<GenerateTypesOutput>
getComponentOp()
ts
function getComponentOp(name, registry?): GetComponentOutput;Get one component's schema + examples.
Parameters
name
string
registry?
ComponentRegistry
Returns
getSchemaOp()
ts
function getSchemaOp(kind): GetSchemaOutput;Get one schema kind: JSON Schema + examples + docs reference.
Parameters
kind
string
Returns
importAsset()
ts
function importAsset(input): Promise<ImportAssetOutput>;Import a glTF/GLB into the project's asset store: validate + normalize (dedup/prune/weld/ quantize; Draco always decoded, never re-encoded — the canonical GLB needs no external decoders), extract bounds + per-node convex hulls (+ optional whole-asset trimesh) for headless physics, write the molen/asset@1 sidecar, and register into project.json.
Parameters
input
Returns
Promise<ImportAssetOutput>
inspectAsset()
ts
function inspectAsset(input): Promise<InspectAssetOutput>;Read + validate a sidecar (by path or project asset id); optionally verify file hashes.
Parameters
input
Returns
Promise<InspectAssetOutput>
inspectContentPack()
ts
function inspectContentPack(input): Promise<InspectPackOutput>;Parameters
input
InspectPackInput
Returns
Promise<InspectPackOutput>
lineupBatchDoc()
ts
function lineupBatchDoc(spacing?): WorldgenBatchDoc;One of each footprint class in a row along +x (40 m apart), generic labels, flat ground.
Parameters
spacing?
number
Returns
WorldgenBatchDoc
listAssets()
ts
function listAssets(input): Promise<ListAssetsOutput>;List the assets registered in the surrounding project.
Parameters
input
cwd?
string
projectPath?
string
Returns
Promise<ListAssetsOutput>
listComponentsOp()
ts
function listComponentsOp(registry?): ComponentSummary[];List the known component vocabulary (name + description + owning layer).
Parameters
registry?
ComponentRegistry
Returns
ComponentSummary[]
listSchemasOp()
ts
function listSchemasOp(): SchemaSummary[];List every registered asset schema kind.
Returns
SchemaSummary[]
listTemplates()
ts
function listTemplates(): Promise<ListTemplatesOutput>;The sample templates molen new --template <id> can scaffold.
Returns
Promise<ListTemplatesOutput>
listTypes()
ts
function listTypes(input): Promise<ListTypesOutput>;Parameters
input
Returns
Promise<ListTypesOutput>
loadProject()
ts
function loadProject(path): Promise<ProjectContext>;Load + validate a project manifest and every types document it references. Throws on invalid.
Parameters
path
string
Returns
Promise<ProjectContext>
loadSceneDocument()
ts
function loadSceneDocument(ref, opts?): Promise<LoadedScene>;Load a scene by path or by project scene name: validate (legacy versions auto-upgrade), resolve scripts[].path file refs into inline code (scene-file-relative), and thread the surrounding project (for registry types). Throws with a formatted message on invalid input.
Parameters
ref
string
opts?
Returns
Promise<LoadedScene>
loadSetupLike()
ts
function loadSetupLike(modulePath): Promise<WorldSetup>;Load a setup module: accepts export default setup, export setup, or a defineExperience result.
Parameters
modulePath
string
Returns
Promise<WorldSetup>
loadStylePackFromDisk()
ts
function loadStylePackFromDisk(packPath?, options?): Promise<LoadedStylePackFiles>;Load a style pack from packPath (a stylepack.json, a directory holding one, a content pack file, URL or source directory) or, without one, from the content packs the project uses.
Parameters
packPath?
string
options?
PackOptions
Returns
Promise<LoadedStylePackFiles>
locateDocsRoot()
ts
function locateDocsRoot(start?): Promise<string>;Locate the docs bundle root by walking up from a start dir until a folder containing docs-src/llms.txt is found. Falls back to the start dir. This makes search_docs work regardless of the cwd the MCP server / CLI was launched from.
Parameters
start?
string
Returns
Promise<string>
packAsset()
ts
function packAsset(input): Promise<PackAssetOutput>;Pack one or every project asset into a KTX2 runtime variant (see module comment).
Parameters
input
Returns
Promise<PackAssetOutput>
parseExperiencePlayScenario()
ts
function parseExperiencePlayScenario(value): ExperiencePlayScenario;Parameters
value
| Record<string, unknown> | ExperiencePlayScenario
Returns
playExperience()
ts
function playExperience(input): Promise<ExperiencePlayOutput>;Play a built browser experience: browser inputs in, screenshots and diagnostics out.
Parameters
input
Returns
Promise<ExperiencePlayOutput>
previewWorldgen()
ts
function previewWorldgen(input): Promise<WorldgenPreviewOutput>;Parameters
input
Returns
Promise<WorldgenPreviewOutput>
projectInfo()
ts
function projectInfo(input): Promise<ProjectInfoOutput>;Parameters
input
Returns
Promise<ProjectInfoOutput>
rasterizeMaterial()
ts
function rasterizeMaterial(input): Promise<RasterizeOutput>;Bake a material (graph or palette) to a PNG. The MCP rasterize_material tool.
Parameters
input
Returns
Promise<RasterizeOutput>
registerExperiencePlaySchema()
ts
function registerExperiencePlaySchema(): void;Register the play-scenario schema into the shared registry (idempotent).
Returns
void
renderTypesModule()
ts
function renderTypesModule(project): string;Render the generated module (deterministic given the registry + project types).
Parameters
project
Returns
string
reserveNamespace()
ts
function reserveNamespace(input): Promise<ReserveNamespaceOutput>;Parameters
input
Returns
Promise<ReserveNamespaceOutput>
runReplayFile()
ts
function runReplayFile(input): Promise<RunReplayOutput>;Replay a recorded fixture and compare the final state hash. On a mismatch, localize the divergence instead of just reporting "hash differs":
- re-run the build against itself — if it diverges from itself, the build is NON-DETERMINISTIC; report the first divergent tick + a component-level diff.
- otherwise the build is deterministic but its result drifted from the recording (an intentional engine/content change, or a regression). If the fixture stored per-tick hashes, report the first tick that differs from the recording.
Parameters
input
Returns
Promise<RunReplayOutput>
runSimulation()
ts
function runSimulation(input): Promise<SimulateOutput>;Run a scene headlessly for N ticks, applying commands and evaluating assertions.
Parameters
input
Returns
Promise<SimulateOutput>
scaffoldExperience()
ts
function scaffoldExperience(input): Promise<ScaffoldOutput>;Scaffold a complete, runnable project: the built-in starter (manifest + scene + types + scripts
- setup + browser app), or with
templatea copy of one of the shipped samples. Either way the project gets an AGENTS.md pointing a coding agent at the version-locked docs and its loop.
Parameters
input
Returns
Promise<ScaffoldOutput>
schemaToTsType()
ts
function schemaToTsType(schema, indent?): string;Print a JSON Schema node as a TS type expression. Unknown constructs degrade to unknown.
Parameters
schema
unknown
indent?
string
Returns
string
screenshotAsset()
ts
function screenshotAsset(input): Promise<AssetShotOutput>;Render turntable views of an imported asset.
Parameters
input
Returns
Promise<AssetShotOutput>
screenshotScene()
ts
function screenshotScene(input): Promise<ScreenshotOutput>;Simulate a scene to tick N in Node, serialize a keyframe, then render exactly one deterministic frame in headless Chromium (SwiftShader) and save a PNG with a stats block (docs-src/guide/agent-loop.md, "Screenshot"). The capture page boots a snapshot viewer — no live kernel. gltf renderables are served to the page over an ephemeral localhost HTTP server.
Parameters
input
Returns
Promise<ScreenshotOutput>
searchDocs()
ts
function searchDocs(input): Promise<SearchDocsOutput>;Lexical doc search (term-frequency ranking) over the shipped bundle.
Parameters
input
Returns
Promise<SearchDocsOutput>
simWatch()
ts
function simWatch(input): Promise<SimWatchHandle>;Run once, then rerun (debounced) on every change to any transitive input.
Parameters
input
Returns
Promise<SimWatchHandle>
stageAssets()
ts
function stageAssets(input): Promise<StageAssetsOutput>;Stage registered assets (+ optional packed variant) into a browser-servable directory.
Parameters
input
Returns
Promise<StageAssetsOutput>
testTypes()
ts
function testTypes(input): Promise<TestTypesOutput>;Spawn + simulate every registry type in isolation; report per-type verdicts.
Parameters
input
Returns
Promise<TestTypesOutput>
updateProjectFile()
Call Signature
ts
function updateProjectFile(path, mutate): Promise<ProjectManifest>;The single write path for project.json: lockfile (O_EXCL, stale after 30s, bounded retry), re-read, mutate, validate, write temp + atomic rename. Concurrent agents (asset import, types reserve) serialize here instead of clobbering each other.
Parameters
path
string
mutate
(manifest) => void
Returns
Promise<ProjectManifest>
Call Signature
ts
function updateProjectFile(path, mutate): Promise<ProjectManifest>;The single write path for project.json: lockfile (O_EXCL, stale after 30s, bounded retry), re-read, mutate, validate, write temp + atomic rename. Concurrent agents (asset import, types reserve) serialize here instead of clobbering each other.
Parameters
path
string
mutate
(manifest) => ProjectManifest
Returns
Promise<ProjectManifest>
validateAsset()
ts
function validateAsset(input): Promise<ValidateOutput>;Validate an asset document against its schema (kind auto-detected when omitted).
Parameters
input
Returns
Promise<ValidateOutput>
verifyContentPack()
ts
function verifyContentPack(input): Promise<VerifyPackOutput>;Read every file (checking CRC and sha256), validate each JSON document whose format is a registered schema, and check that asset sidecars' hashes match their models.
Parameters
input
InspectPackInput
Returns
Promise<VerifyPackOutput>
worldgenStats()
ts
function worldgenStats(input): Promise<WorldgenStatsOutput>;Parameters
input
Returns
Promise<WorldgenStatsOutput>