API reference

Documentation Menu

Graph

The main structure handling the data flow between nodes.

graph.sceneContainer: HTMLElement

A reference to the DOM object containing the scene (a section tag).


Note: the graph object is reinitialised when changing graph but the reference is kept.

Node

Nodes are plain JavaScript pieces of code defined as CommonJS-like modules exporting a single function that takes 2 parameters: the node itself and a reference to the global graph object.

module.exports = (node, graph) => {
	// Node body
	const { cool } = require("depedency-name");
	const result = cool("stuff");
	node.log(result);
};

Note that they are currently not fully featured CJS modules but instead Function objects. The require('depedency-name') are simulated through an object map so it is not possible to get dependencies via path but it is instead recommended to use assignment destructuring (eg. do const { cool } = require('depedency-name') and not const cool = require('depedency-name/cool')). It is possible to use dynamic import but no ES Module import yet (eg. await import('https://unpkg.com/lodash-es') but not import { chunk } from 'lodash').

node.in/out/inOut(name: string, defaultValue?: any, options?: PortOptions): Port

Creates a parameter port with an in, out or inOut direction and attaches it to the node.

On compilation, their code will be checked for syntax and compilation errors before adding any port to it.

OptionDescription
nameA unique string identifier for the port.
defaultValue?The default value for the port.
options?See interface PortOptions table below.

interface PortOptions

Port options are all optional and intended to change the appearance in the Inspector component (using slider instead of number box, adding color interface for an array of 4 components…).

OptionTypeDescription
typestringSee enum PortOptionsType table below.
connectable?booleanHides the port in the Graph Editor component. Often used with a defaultValue set as function to create a button in the Inspector component.
min?numberThe minimum value to accept for this port. Ignored unless port is of type number.
max?numberThe maximum value to accept for this port. Ignored unless port is of type number.
step?numberA stepping interval to use when adjusting the port value up and down. Ignored unless port is of type number.
precision?IntegerA number of decimal places to use when adjusting the port value up and down. Ignored unless port is of type number.
filter?string | RegExpFilter assets with a string (fed to assetNames.filter) or a Regex. Ignored unless port is of type asset.
thumbnails?booleanAdds thumbnails preview for images (jpg and png only). Ignored unless port is of type asset.
values?ArraySelectable values for dropdown and multiselect ports.
enum PortOptionsType

Below is a list of all the possible port declaration with their port type, the actual value and the resulting GUI element that appears in the Inspector component.

The following port types are required in order to get specific GUI components 'dropdown' | 'color' | 'multiple' | 'asset' | 'textarea'. Others are generally inferred from the defaultValue but can also be specified for clarity.

Port TypeActual Value TypeGUI WidgetExample Code declarationNotes
anyanytext boxnode.in("name", "")
objectObjectnonenode.in("name", {})
arrayArray<any>list of valuesnode.in("name", [])displays max 4 elements
numberFloatnumber boxnode.in("name", 0.5)
numberFloatslidernode.in("name", 0.5, { min: 0.0, max: 1.0 })
arrayArray<Float>multiple number boxesnode.in("name", [0.5, 0.25])arrays of 2, 3 and 4 elements are supported
numberIntegernumber boxnode.in("name", 64, { precision: 0 })
numberIntegerslidernode.in("name", 64, { precision: 0, min: 0, max: 255 })
arrayArray<Integer>multiple number boxesnode.in("name", [64, 100], { precision: 0 })arrays of 2, 3 and 4 elements are supported
arrayColorcolour pickernode.in("name", [1, 0, 0, 1], { type: "color" })RGBA array of floats (0…1)
stringstringtext boxnode.in("name", "text")
stringstringtext areanode.in("name", "text", { type: "textarea" })
stringstringdropdown menunode.in("name", "option 1", { type: "dropdown", values: ["option 1", "option 2", "option 3"] })
arrayArray<string>multi-selectnode.in("name", ["option 1"], { type: "multiple", values: ["option 1", "option 2", "option 3"] })
boolbooleancheckboxnode.in("name", true)
stringAssetFileUrldropdownnode.in("name", "", { type: "asset" })lists only files from the assets directory
stringAssetFileUrldropdown with filternode.in("name", "", { type: "asset", filter: ".jpg" })filter can be string or Regex
stringAssetFileUrldropdown with thumbnailsnode.in("name", "", { type: "asset", thumbnails: true })
objectFunctionbuttonnode.in("name", () ⇒ { // on Inspector button click })

See Port for the different methods and property of a port.

node.triggerIn/triggerOut(name: string): Port

Creates a trigger port with an in or out direction and attaches it to the node.

OptionDescription
nameA unique string identifier for the port.

node.log(message: string): void

Pushes a log to the log panel. Useful for debugging.

OptionDescription
messageThe message to display. It will be stringified with JSON.stringify before being rendered and limited to 1000 characters.

node.onReady: Function | null

Called after each successful node compilation eg. when opening a graph or compiling new code.

node.onDestroy: Function | null

Called when opening a graph and removing nodes from a graph, or before compiling new code. The important place to clean up any code holding memory eg. remove event listeners, remove any added DOM children, stop requestAnimationFrame loops…

node.comment: string

A string limited to 1000 characters to be displayed on the Graph Editor component.

node.commentImage: CanvasImageSource

An image of type CanvasImageSource to be displayed on the Graph Editor component.

Port

Ports are created by nodes via node.in/out/inOut/triggerIn/triggerOut: they control both the connections between nodes via trigger and the properties of the nodes via parameters.

triggerOutPort.trigger(props?: any)

A function to be called at any time in your node: it will trigger a callback chain to any node connected to the port via a node.triggerIn. Pass props as an arguments for a top down data flow.

triggerInPort.onTrigger(props?: any): void

Called when the parent port calls .trigger. Receive the props arguments from the parent port.

Trigger ports created via in/out/inOut:

portWithDirection.setValue(value: any)

Set the value of a port. Any target port connected to this source port via a node.in/inOut will get its value set to the new one and trigger a onChange callback as a result.

Type mismatch (eg. connecting a port with type array to a type number) will also be checked.

portWithDirection.onChange(newValue: any, oldValue: any)

Called when the parent port calls .setValue. Receive the newValue and oldValue from the parent port.