Flowgraph Base Node

Core base class for all flowgraph nodes. Defines the complete node lifecycle: initialization, pin management, work execution, drawing, serialization, and context menus. Every flowgraph node inherits f

Public Functions

Function	Signature	Returns	Description
`createBase`	`createBase(...)`	node instance	Creates a raw base node. Sets metatable to `C`, calls `C:init(mgr, graph, forceId)`.
`use`	`use(mgr, graph, forceId, derivedClass)`	node instance	Creates a base node, overlays all derived class fields, runs `_preInit()` (creates output pins from schema), calls derived `init()` if overridden, then `_postInit()` (creates input pins, handles categories/behaviors).

Node Lifecycle

createBase/use → init → _preInit → [derived init] → _postInit → postInit
                                                                    │
  ┌─────────────────────────────────────────────────────────────────┘
  │
  execution: __executionStarted → [trigger → work/workOnce per frame] → __executionStopped
  │
  serialization: __onSerialize ↔ __onDeserialized

Key Instance Properties

Property	Type	Default	Description
`id`	number	auto	Unique node ID within the manager.
`name`	string	`'unknown'`	Display name.
`description`	string	`'No Description!'`	Tooltip description text.
`type`	string	`'node'`	Node type: `'node'`, `'simple'`, or `'variable'`.
`category`	string	nil	Functional category determining auto-created pins and behaviors.
`behaviour`	table	`{}`	Active behaviors: `once`, `duration`, `simple`, `singleActive`, `obsolete`.
`dynamicMode`	string	`'repeat'`	`'repeat'` (every frame) or `'once'` (single execution with reset).
`pinIn`	table	metatable	Read-only proxy returning `emptyPin` for missing keys.
`pinInLocal`	table	`{}`	Actual input pin storage.
`pinOut`	table	`{}`	Output pin storage.
`pinList`	table	`{}`	Ordered list of all pins for drawing.
`data`	table	`{}`	Node-specific persistent data.
`triggerCount`	number	`0`	Times this node has been triggered.
`workCount`	number	`0`	Times work has executed.

Pin Management Methods

Method	Signature	Description
`createPin`	`(direction, type, name, default, description, autoNumber, extra, fixed)`	Creates and registers a pin. Returns the pin object.
`removePin`	`(pin)`	Removes a pin and all its links from the graph.
`renamePin`	`(pin, newName)`	Renames an input pin, updating the lookup table.
`shiftPin`	`(idInList, direction)`	Moves a pin's position in `pinList` for display ordering.
`autoCreatePin`	`(direction, type, name, default, description, extra, fixed)`	Creates a pin only if one with the same name doesn't exist. Respects `pinOrder` sorting.
`createResetPin`	`()`	Adds a reset flow input pin and sets `'once'` behavior.
`removeResetPin`	`()`	Removes the reset pin and clears `'once'` behavior.

Work Execution

Method	Description
`_workDynamicRepeat`	Default work wrapper: calls `self:work()` via `xpcall`, increments `workCount`, checks automated flow.
`_workDynamicOnce`	Once-mode wrapper: checks reset pin, calls `workOnce()` first time, then `work()` on subsequent frames.
`work(args)`	Override in derived nodes for per-frame logic.
`workOnce()`	Override for one-shot logic in `'once'` dynamic mode.
`trigger()`	External entry point; increments `triggerCount`, calls `_trigger`.
`checkAutomatedFlow`	Auto-manages `flow`, `incomplete`, `complete`, `completed` output pins based on category.

Additional Methods

Method	Signature	Description
`setDurationState`	`(state)`	Sets duration state (`'inactive'`, `'started'`, `'finished'`) for f_duration nodes.
`toggleDynamicMode`	`()`	Toggles between `'once'` and `'repeat'` dynamic modes (only for dynamic category nodes).
`setDynamicMode`	`(mode)`	Sets dynamic mode to `'once'` or `'repeat'`, creating/removing reset pin as needed.
`getLinks`	`()`	Returns `targets, sources` - tables of links where this node is target/source.
`isFlowActive`	`()`	Checks if any flow input dependency has a value.
`alignToGrid`	`(x, y)`	Snaps the node position to the editor grid (14px spacing).
`toString`	`()`	Returns `"name( nodeType / id) in graphString"`.
`_setupTimeline`	`(beginTime, endTime)`	Configures timeline data for timeline-based execution.

Duration State Machine

For f_duration category nodes:

State	`incomplete`	`complete`	`completed`
`inactive`	false	false	false
`started`	true	false	false
`finished`	false	true	true (1 frame)

-- Set duration state from within work():
self:setDurationState('started')   -- begin the duration
self:setDurationState('finished')  -- mark as complete

Serialization

-- __onSerialize returns:
{
  type = "nodeType/path",
  pos = {x, y},
  data = { ... },
  dynamicMode = "repeat",
  customName = "My Node",       -- optional
  customColor = {r, g, b, a},   -- optional
  hardcodedPins = { pinName = { value = v, type = t } },
  quickAccess = { p_in = {}, p_out = {} },
  hiddenPins = { p_in = {}, p_out = {} },
  timeline = { beginTime, endTime, lane },  -- optional
}

Usage Example

-- Creating a derived node type (in a node definition file)
local C = {}
C.name = 'myCustomNode'
C.description = 'Does something cool'
C.category = 'logic'  -- auto-creates flow in/out pins

C.pinSchema = {
  { dir = 'in',  type = 'number', name = 'threshold', default = 10, description = 'Activation threshold' },
  { dir = 'out', type = 'bool',   name = 'exceeded',  description = 'True when threshold exceeded' },
}

function C:work()
  self.pinOut.exceeded.value = (self.pinIn.threshold.value or 0) > self.data.limit
end

function C:init()
  self.data.limit = 50
end

return require('/lua/ge/extensions/flowgraph/basenode').use(mgr, graph, forceId, C)

Additional Exports

M.createBase - (undocumented)
M.use - (undocumented)

Public Functions

Function	Signature	Returns	Description
`createBase`	`createBase(...)`	node instance	Creates a raw base node. Sets metatable to `C`, calls `C:init(mgr, graph, forceId)`.
`use`	`use(mgr, graph, forceId, derivedClass)`	node instance	Creates a base node, overlays all derived class fields, runs `_preInit()` (creates output pins from schema), calls derived `init()` if overridden, then `_postInit()` (creates input pins, handles categories/behaviors).

Node Lifecycle

createBase/use → init → _preInit → [derived init] → _postInit → postInit
                                                                    │
  ┌─────────────────────────────────────────────────────────────────┘
  │
  execution: __executionStarted → [trigger → work/workOnce per frame] → __executionStopped
  │
  serialization: __onSerialize ↔ __onDeserialized

Key Instance Properties

Property	Type	Default	Description
`id`	number	auto	Unique node ID within the manager.
`name`	string	`'unknown'`	Display name.
`description`	string	`'No Description!'`	Tooltip description text.
`type`	string	`'node'`	Node type: `'node'`, `'simple'`, or `'variable'`.
`category`	string	nil	Functional category determining auto-created pins and behaviors.
`behaviour`	table	`{}`	Active behaviors: `once`, `duration`, `simple`, `singleActive`, `obsolete`.
`dynamicMode`	string	`'repeat'`	`'repeat'` (every frame) or `'once'` (single execution with reset).
`pinIn`	table	metatable	Read-only proxy returning `emptyPin` for missing keys.
`pinInLocal`	table	`{}`	Actual input pin storage.
`pinOut`	table	`{}`	Output pin storage.
`pinList`	table	`{}`	Ordered list of all pins for drawing.
`data`	table	`{}`	Node-specific persistent data.
`triggerCount`	number	`0`	Times this node has been triggered.
`workCount`	number	`0`	Times work has executed.

Pin Management Methods

Method	Signature	Description
`createPin`	`(direction, type, name, default, description, autoNumber, extra, fixed)`	Creates and registers a pin. Returns the pin object.
`removePin`	`(pin)`	Removes a pin and all its links from the graph.
`renamePin`	`(pin, newName)`	Renames an input pin, updating the lookup table.
`shiftPin`	`(idInList, direction)`	Moves a pin's position in `pinList` for display ordering.
`autoCreatePin`	`(direction, type, name, default, description, extra, fixed)`	Creates a pin only if one with the same name doesn't exist. Respects `pinOrder` sorting.
`createResetPin`	`()`	Adds a reset flow input pin and sets `'once'` behavior.
`removeResetPin`	`()`	Removes the reset pin and clears `'once'` behavior.

Work Execution

Method	Description
`_workDynamicRepeat`	Default work wrapper: calls `self:work()` via `xpcall`, increments `workCount`, checks automated flow.
`_workDynamicOnce`	Once-mode wrapper: checks reset pin, calls `workOnce()` first time, then `work()` on subsequent frames.
`work(args)`	Override in derived nodes for per-frame logic.
`workOnce()`	Override for one-shot logic in `'once'` dynamic mode.
`trigger()`	External entry point; increments `triggerCount`, calls `_trigger`.
`checkAutomatedFlow`	Auto-manages `flow`, `incomplete`, `complete`, `completed` output pins based on category.

Additional Methods

Method	Signature	Description
`setDurationState`	`(state)`	Sets duration state (`'inactive'`, `'started'`, `'finished'`) for f_duration nodes.
`toggleDynamicMode`	`()`	Toggles between `'once'` and `'repeat'` dynamic modes (only for dynamic category nodes).
`setDynamicMode`	`(mode)`	Sets dynamic mode to `'once'` or `'repeat'`, creating/removing reset pin as needed.
`getLinks`	`()`	Returns `targets, sources` - tables of links where this node is target/source.
`isFlowActive`	`()`	Checks if any flow input dependency has a value.
`alignToGrid`	`(x, y)`	Snaps the node position to the editor grid (14px spacing).
`toString`	`()`	Returns `"name( nodeType / id) in graphString"`.
`_setupTimeline`	`(beginTime, endTime)`	Configures timeline data for timeline-based execution.

Duration State Machine

For f_duration category nodes:

State	`incomplete`	`complete`	`completed`
`inactive`	false	false	false
`started`	true	false	false
`finished`	false	true	true (1 frame)

-- Set duration state from within work():
self:setDurationState('started')   -- begin the duration
self:setDurationState('finished')  -- mark as complete

Serialization

-- __onSerialize returns:
{
  type = "nodeType/path",
  pos = {x, y},
  data = { ... },
  dynamicMode = "repeat",
  customName = "My Node",       -- optional
  customColor = {r, g, b, a},   -- optional
  hardcodedPins = { pinName = { value = v, type = t } },
  quickAccess = { p_in = {}, p_out = {} },
  hiddenPins = { p_in = {}, p_out = {} },
  timeline = { beginTime, endTime, lane },  -- optional
}

Usage Example

-- Creating a derived node type (in a node definition file)
local C = {}
C.name = 'myCustomNode'
C.description = 'Does something cool'
C.category = 'logic'  -- auto-creates flow in/out pins

C.pinSchema = {
  { dir = 'in',  type = 'number', name = 'threshold', default = 10, description = 'Activation threshold' },
  { dir = 'out', type = 'bool',   name = 'exceeded',  description = 'True when threshold exceeded' },
}

function C:work()
  self.pinOut.exceeded.value = (self.pinIn.threshold.value or 0) > self.data.limit
end

function C:init()
  self.data.limit = 50
end

return require('/lua/ge/extensions/flowgraph/basenode').use(mgr, graph, forceId, C)

Additional Exports

M.createBase - (undocumented)
M.use - (undocumented)

Flowgraph Base Node

Public Functions

Node Lifecycle

Key Instance Properties

Pin Management Methods

Work Execution

Additional Methods

Duration State Machine

Serialization

Usage Example

Additional Exports

See Also

On this page

Flowgraph Base Node

Public Functions

Node Lifecycle

Key Instance Properties

Pin Management Methods

Work Execution

Additional Methods

Duration State Machine

Serialization

Usage Example

Additional Exports

See Also

On this page