Flowgraph Pin

Overview

File: extensions/flowgraph/pin.lua

The Pin class represents a single input or output connection point on a flowgraph node. Pins carry typed values (flow, number, string, vec3, etc.) and manage links, drawing, tooltips, and value tracking.

Exports

Returns a constructor function function(graph, node, direction, type, name, default, description) that creates a new Pin instance.

Constructor Parameters

Parameter	Type	Description
`graph`	object	The parent graph.
`node`	object	The parent node.
`direction`	string	`'in'` or `'out'`.
`type`	string/table	Pin type (e.g. `'number'`, `'flow'`, `'vec3'`, or a table of accepted types).
`name`	string	Display name.
`default`	any	Default value.
`description`	string	Tooltip description.

Key Methods

Method	Signature	Description
`init`	`(graph, node, dir, type, name, default, desc)`	Initialises the pin with ID, type, links, and usage tracking metatables.
`getFirstConnectedLink`	`()` → link	Returns the first link object connected to this pin.
`isUsed`	`()` → bool	True if the pin has any links or is hardcoded.
`isActive`	`()` → bool	True if the pin can accept new links (during link creation).
`_onLink`	`(link)`	Called when a link is connected. For non-flow inputs, replaces the single link.
`_onUnlink`	`(link)`	Called when a link is disconnected.
`valueSetVec3`	`(v)`	Sets the value from a vec3 object as `{x, y, z}`.
`valueSetQuat`	`(v)`	Sets the value from a quat object as `{x, y, z, w}`.
`draw`	`(builder, style, isHeader, constValue, outWidth)`	Renders the pin in the editor.
`drawTooltip`	`(mgr)`	Renders the hover tooltip with type, value, and description.
`highlightLinks`	`()`	Marks all connected links for highlight rendering.
`showContextMenu`	`(menuPos, main)`	Renders right-click context menu (hide, show/hide links, quick access).
`getTypeWithImpulseAndChain`	`()` → string	Returns effective type including impulse/chain variants.
`getTableType`	`()` → string	Returns the table subtype (e.g. `"generic"`) for table-typed pins.

Internals

Usage Tracking

When enableUsageTracking is true (default), the pin uses metatables to intercept .value reads and writes:

-- Reading pin.value updates _frameLastUsed
pin.value  -- actually reads pin._value and stamps the frame

-- Writing pin.value also stamps the frame
pin.value = 42  -- actually writes pin._value

This allows isUsed() and frame-based optimisation (nodes can skip computing unused outputs).

Link Behaviour

Input pins (non-flow): Only one link allowed - new link replaces old.
Output pins and flow pins: Multiple links supported (fan-out).

How It Works

Pins are created by nodes during graph construction.
Each pin gets a unique ID from the manager's ID allocator.
Value access is tracked via metatables for performance optimisation.
Drawing is handled separately for input (_draw_in) and output (_draw_out) directions.
Links are managed as arrays; input pins enforce single-link constraints.

Usage Example

-- Creating a pin (done internally by flowgraph):
local pin = require('/lua/ge/extensions/flowgraph/pin')(graph, node, 'in', 'number', 'speed', 0, 'Vehicle speed')

-- Reading a pin value in a node's work() method:
function C:work()
  local speed = self.pinIn.speed.value  -- triggers usage tracking
  self.pinOut.result.value = speed * 2  -- triggers usage tracking
end

-- Setting vec3 values efficiently:
self.pinOut.position:valueSetVec3(someVec3)

Key Dependencies

ui_flowgraph_editor - type colours, icons, editor preferences
editor_flowgraphEditor - tooltip permission checks
Flowgraph manager - ID allocation, frame counting

Overview

File: extensions/flowgraph/pin.lua

Exports

Returns a constructor function function(graph, node, direction, type, name, default, description) that creates a new Pin instance.

Constructor Parameters

Parameter	Type	Description
`graph`	object	The parent graph.
`node`	object	The parent node.
`direction`	string	`'in'` or `'out'`.
`type`	string/table	Pin type (e.g. `'number'`, `'flow'`, `'vec3'`, or a table of accepted types).
`name`	string	Display name.
`default`	any	Default value.
`description`	string	Tooltip description.

Key Methods

Method	Signature	Description
`init`	`(graph, node, dir, type, name, default, desc)`	Initialises the pin with ID, type, links, and usage tracking metatables.
`getFirstConnectedLink`	`()` → link	Returns the first link object connected to this pin.
`isUsed`	`()` → bool	True if the pin has any links or is hardcoded.
`isActive`	`()` → bool	True if the pin can accept new links (during link creation).
`_onLink`	`(link)`	Called when a link is connected. For non-flow inputs, replaces the single link.
`_onUnlink`	`(link)`	Called when a link is disconnected.
`valueSetVec3`	`(v)`	Sets the value from a vec3 object as `{x, y, z}`.
`valueSetQuat`	`(v)`	Sets the value from a quat object as `{x, y, z, w}`.
`draw`	`(builder, style, isHeader, constValue, outWidth)`	Renders the pin in the editor.
`drawTooltip`	`(mgr)`	Renders the hover tooltip with type, value, and description.
`highlightLinks`	`()`	Marks all connected links for highlight rendering.
`showContextMenu`	`(menuPos, main)`	Renders right-click context menu (hide, show/hide links, quick access).
`getTypeWithImpulseAndChain`	`()` → string	Returns effective type including impulse/chain variants.
`getTableType`	`()` → string	Returns the table subtype (e.g. `"generic"`) for table-typed pins.

Internals

Usage Tracking

When enableUsageTracking is true (default), the pin uses metatables to intercept .value reads and writes:

-- Reading pin.value updates _frameLastUsed
pin.value  -- actually reads pin._value and stamps the frame

-- Writing pin.value also stamps the frame
pin.value = 42  -- actually writes pin._value

This allows isUsed() and frame-based optimisation (nodes can skip computing unused outputs).

Link Behaviour

Input pins (non-flow): Only one link allowed - new link replaces old.
Output pins and flow pins: Multiple links supported (fan-out).

How It Works

Pins are created by nodes during graph construction.
Each pin gets a unique ID from the manager's ID allocator.
Value access is tracked via metatables for performance optimisation.
Drawing is handled separately for input (_draw_in) and output (_draw_out) directions.
Links are managed as arrays; input pins enforce single-link constraints.

Usage Example

-- Creating a pin (done internally by flowgraph):
local pin = require('/lua/ge/extensions/flowgraph/pin')(graph, node, 'in', 'number', 'speed', 0, 'Vehicle speed')

-- Reading a pin value in a node's work() method:
function C:work()
  local speed = self.pinIn.speed.value  -- triggers usage tracking
  self.pinOut.result.value = speed * 2  -- triggers usage tracking
end

-- Setting vec3 values efficiently:
self.pinOut.position:valueSetVec3(someVec3)

Key Dependencies

ui_flowgraph_editor - type colours, icons, editor preferences
editor_flowgraphEditor - tooltip permission checks
Flowgraph manager - ID allocation, frame counting

Flowgraph Pin

Overview

Exports

Constructor Parameters

Key Methods

Internals

Usage Tracking

Link Behaviour

How It Works

Usage Example

Key Dependencies

See Also

On this page

Flowgraph Pin

Overview

Exports

Constructor Parameters

Key Methods

Internals

Usage Tracking

Link Behaviour

How It Works

Usage Example

Key Dependencies

See Also

On this page