@bendyline/molen-materials

Molen materials: pixel grids, SVG and procedural material graphs (rungs 2-4). No three.js.

import { /* … */ } from '@bendyline/molen-materials';

Interfaces

ApplyUvPaintOptions

Properties

dilationPx?

optional dilationPx?: number;

maskToIslands?

optional maskToIslands?: boolean;

---

BakedMaterial

Properties

meta

meta: object;

alphaCoverage?

optional alphaCoverage?: boolean;

alphaTest?

optional alphaTest?: number;

filter

filter: "nearest" | "linear";

slots

slots: Partial<Record<MaterialSlot, RGBAImage>>;

---

BakedMaterialStore

Persistent storage for baked materials (e.g. IndexedDB), keyed by baker and document.

Methods

get()

get(key): Promise<BakedMaterial | undefined>;

Parameters

key

string

Returns

Promise<BakedMaterial | undefined>

prune()?

optional prune(keep): Promise<void>;

Delete every entry keep rejects: output from a baker that has since changed.

Parameters

keep

(key) => boolean

Returns

Promise<void>

set()

set(key, material): Promise<void>;

Parameters

key

string

material

BakedMaterial

Returns

Promise<void>

---

MaterialBaker

Methods

bake()

Call Signature

bake(kind, doc): Promise<BakedMaterial>;

Parameters

kind

"matgraph"

doc

MatGraphDoc

Returns

Promise<BakedMaterial>

Call Signature

bake(kind, doc): Promise<BakedMaterial>;

Parameters

kind

"pixelgrid"

doc

PixelGridDoc

Returns

Promise<BakedMaterial>

---

MaterialBakeWorker

Methods

addEventListener()

addEventListener(type, listener): void;

Parameters

type

"message" | "error"

listener

(event) => void

Returns

void

postMessage()

Call Signature

postMessage(message): void;

Parameters

message

unknown

Returns

void

Call Signature

postMessage(message, transfer): void;

Parameters

message

unknown

transfer

ArrayBuffer[]

Returns

void

removeEventListener()?

optional removeEventListener(type, listener): void;

Parameters

type

"message" | "error"

listener

(event) => void

Returns

void

terminate()?

optional terminate(): void;

Returns

void

---

MatGraphDoc

Properties

alphaCoverage?

optional alphaCoverage?: boolean;

Filter base-color alpha as fractional surface coverage (e.g. fine metal mesh). Mutually exclusive with alphaTest. Rendered with mipmapped alpha blending.

alphaTest?

optional alphaTest?: number;

Optional cutout threshold for the baked base-color alpha; omitted graphs remain opaque.

format

format: "molen/matgraph@1";

nodes

nodes: MatNode[];

outputs

outputs: Partial<Record<MaterialSlot, string>>;

seed

seed: number;

size

size: [number, number];

---

PixelGridDoc

Properties

filter

filter: "nearest" | "linear";

format

format: "molen/pixelgrid@1";

palette

palette: Record<string, string>;

Single-code-point key -> "transparent" or "#rrggbb"/"#rrggbbaa".

rows

rows: string[];

Exactly size[1] rows of exactly size[0] characters.

size

size: [number, number];

slots

slots: object;

baseColor

baseColor: boolean;

emissive

emissive: boolean;

---

RampStop

Properties

color

color: string;

t

t: number;

---

RGBAImage

Properties

data

data: Uint8ClampedArray;

RGBA8, row-major, length = width * height * 4.

height

height: number;

width

width: number;

---

SvgMeta

Properties

rasterSize?

optional rasterSize?: [number, number];

Output raster size; defaults to 512×512 (POT).

---

SvgWasmUrl

Structural stand-in for the global URL — this package declares no DOM or Node lib types, so a real URL (or anything else carrying an href) matches it.

Properties

href

readonly href: string;

Type Aliases

MaterialSlot

type MaterialSlot = "baseColor" | "roughness" | "metalness" | "normal" | "emissive" | "ao";

---

MatNode

type MatNode = 
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object
  | NodeCommon & object;

---

SvgWasmSource

type SvgWasmSource = ArrayBuffer | ArrayBufferView | SvgWasmUrl | string;

Where the resvg WASM module comes from: raw bytes (Uint8Array/ArrayBuffer) or a URL — a URL object or a plain string — that is fetched. Browsers and other non-Node runtimes must supply one; Node loads its own by default.

Functions

applyUvPaint()

function applyUvPaint(
   painted, 
   islandMap, 
   opts?
): RGBAImage;

Full import: mask the painted image to the islands, then dilate to fill the gutters.

Parameters

painted

RGBAImage

islandMap

RGBAImage

opts?

ApplyUvPaintOptions

Returns

RGBAImage

---

bakeMatGraph()

function bakeMatGraph(doc): BakedMaterial;

Bake a validated material graph into per-slot RGBA textures.

The document must have been through the schema (validateByKind('matgraph', doc)) so every parameter default is applied — an unvalidated document is rejected rather than baked into a silently wrong (usually flat) texture.

Parameters

doc

MatGraphDoc

Returns

BakedMaterial

---

bakePalette()

function bakePalette(ref, size?): BakedMaterial | undefined;

Rung 1: a flat palette color → a solid baseColor texture. Accepts "palette:#rrggbb" or "#rrggbb".

Parameters

ref

string

size?

number

Returns

BakedMaterial | undefined

---

bakePixelGrid()

function bakePixelGrid(doc): BakedMaterial;

Rasterize a pixel-grid document into every slot its slots block enables (rung 2). One char = one texel; nearest filter; transparent palette entries become an alphaTest cutout. Validation errors quote row/column.

The enabled slots share one image: nothing in the pipeline mutates a baked slot (the client copies the buffer into a DataTexture, the bake worker de-duplicates buffers before transfer, the PNG writer only reads), so one grid is rasterized once however many slots point at it.

Parameters

doc

PixelGridDoc

Returns

BakedMaterial

---

bakeSvg()

function bakeSvg(svgText, meta?): Promise<BakedMaterial>;

Rasterize an SVG document to a baseColor texture. Requires initSvg() first outside Node.

Parameters

svgText

string

meta?

SvgMeta

Returns

Promise<BakedMaterial>

---

createImage()

function createImage(width, height): RGBAImage;

Parameters

width

number

height

number

Returns

RGBAImage

---

createMaterialBakeWorkerPool()

function createMaterialBakeWorkerPool(workers, options?): MaterialBaker & object;

A bounded caller-owned pool. One graph at a time per worker; dispose terminates owned workers.

Parameters

workers

readonly MaterialBakeWorker[]

options?

onTiming?

(milliseconds) => void

Returns

MaterialBaker & object

---

dilate()

function dilate(img, px): RGBAImage;

Push opaque colors outward into transparent gutters by px rings (nearest-valid flood).

Parameters

img

RGBAImage

px

number

Returns

RGBAImage

---

fbm()

function fbm(
   base, 
   x, 
   y, 
   seed, 
   octaves, 
   lacunarity, 
   gain
): number;

Fractal Brownian motion over a base noise.

Parameters

base

(x, y, seed) => number

x

number

y

number

seed

number

octaves

number

lacunarity

number

gain

number

Returns

number

---

gradientNoise()

function gradientNoise(
   x, 
   y, 
   seed
): number;

Gradient (Perlin-style) noise remapped to [0,1]; used for the "simplex" node kind.

Parameters

x

number

y

number

seed

number

Returns

number

---

initSvg()

function initSvg(wasm?): Promise<void>;

Initialize the resvg WASM runtime. Idempotent: the first successful call wins and later calls (with or without a source) resolve against it.

Parameters

wasm?

SvgWasmSource

Explicit WASM source — bytes (Uint8Array/ArrayBuffer) or a URL to fetch (a URL or a string). Required in the browser and in any other non-Node runtime; omit it in Node to load the copy shipped with @resvg/resvg-wasm.

Returns

Promise<void>

---

installMaterialBakeWorker()

function installMaterialBakeWorker(port): void;

Validated graph documents in, exactly the synchronous baker's pixels out.

Parameters

port

Pick<MaterialBakeWorker, "postMessage" | "addEventListener">

Returns

void

---

maskToIslands()

function maskToIslands(painted, islandMap): RGBAImage;

Clip a painted image to the island map: pixels outside any island become transparent.

Parameters

painted

RGBAImage

islandMap

RGBAImage

Returns

RGBAImage

---

materialBakerFingerprint()

function materialBakerFingerprint(): string;

Identifies the rasterizers' current output, so stored results from a changed baker are never served. Computed in this thread; worker bakers run the same bundled code.

Returns

string

---

rectIslandMap()

function rectIslandMap(
   width, 
   height, 
   x0, 
   y0, 
   x1, 
   y1
): RGBAImage;

A trivial island map for tests/demos: a filled rectangle island on a transparent background.

Parameters

width

number

height

number

x0

number

y0

number

x1

number

y1

number

Returns

RGBAImage

---

registerMaterialSchemas()

function registerMaterialSchemas(): void;

Register the material schemas into the shared registry (idempotent).

Returns

void

---

valueNoise()

function valueNoise(
   x, 
   y, 
   seed
): number;

Value noise in [0,1].

Parameters

x

number

y

number

seed

number

Returns

number

---

withBakedMaterialStore()

function withBakedMaterialStore(baker, store): MaterialBaker;

Serve bakes from store when this baker has produced them before (on any earlier visit), and store new results. Store failures fall back to baking; they never fail a material.

Parameters

baker

MaterialBaker

store

BakedMaterialStore

Returns

MaterialBaker

---

worley()

function worley(
   x, 
   y, 
   seed, 
   jitter, 
   output
): number;

Worley/cellular noise: distance to the nearest jittered feature point.

Parameters

x

number

y

number

seed

number

jitter

number

output

"f1" | "f2" | "f2-f1"

Returns

number