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.

Option	Description
name	A 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…).

Option	Type	Description
type	string	See `enum PortOptionsType` table below.
connectable?	boolean	Hides the port in the Graph Editor component. Often used with a defaultValue set as function to create a button in the Inspector component.
min?	number	The minimum value to accept for this port. Ignored unless port is of type number.
max?	number	The maximum value to accept for this port. Ignored unless port is of type number.
step?	number	A stepping interval to use when adjusting the port value up and down. Ignored unless port is of type number.
precision?	Integer	A number of decimal places to use when adjusting the port value up and down. Ignored unless port is of type number.
filter?	string \| RegExp	Filter assets with a string (fed to `assetNames.filter`) or a Regex. Ignored unless port is of type asset.
thumbnails?	boolean	Adds thumbnails preview for images (jpg and png only). Ignored unless port is of type asset.
values?	Array	Selectable 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 Type	Actual Value Type	GUI Widget	Example Code declaration	Notes
any	any	text box	`node.in("name", "")`
object	Object	none	`node.in("name", {})`
array	Array<any>	list of values	`node.in("name", [])`	displays max 4 elements
number	Float	number box	`node.in("name", 0.5)`
number	Float	slider	`node.in("name", 0.5, { min: 0.0, max: 1.0 })`
array	Array<Float>	multiple number boxes	`node.in("name", [0.5, 0.25])`	arrays of 2, 3 and 4 elements are supported
number	Integer	number box	`node.in("name", 64, { precision: 0 })`
number	Integer	slider	`node.in("name", 64, { precision: 0, min: 0, max: 255 })`
array	Array<Integer>	multiple number boxes	`node.in("name", [64, 100], { precision: 0 })`	arrays of 2, 3 and 4 elements are supported
array	Color	colour picker	`node.in("name", [1, 0, 0, 1], { type: "color" })`	RGBA array of floats (0…1)
string	string	text box	`node.in("name", "text")`
string	string	text area	`node.in("name", "text", { type: "textarea" })`
string	string	dropdown menu	`node.in("name", "option 1", { type: "dropdown", values: ["option 1", "option 2", "option 3"] })`
array	Array<string>	multi-select	`node.in("name", ["option 1"], { type: "multiple", values: ["option 1", "option 2", "option 3"] })`
bool	boolean	checkbox	`node.in("name", true)`
string	AssetFileUrl	dropdown	`node.in("name", "", { type: "asset" })`	lists only files from the assets directory
string	AssetFileUrl	dropdown with filter	`node.in("name", "", { type: "asset", filter: ".jpg" })`	filter can be string or Regex
string	AssetFileUrl	dropdown with thumbnails	`node.in("name", "", { type: "asset", thumbnails: true })`
object	Function	button	`node.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.

Option	Description
name	A unique string identifier for the port.

node.log(message: string): void

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

Option	Description
message	The 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.