XController:
XController is a configurable control node for adjusting values in a workflow. You can present it as a knob, horizontal or vertical fader, toggle, button, or XY pad, then connect its results to other nodes. For continuous controls, it can translate a position into a value on a range, select from a set of steps, or apply a percentage offset to a base value. The toggle provides an on/off state, while the XY pad provides two independently adjustable coordinates. This lets you use one node for several kinds of hands-on control without changing the rest of your workflow.
XController Input Parameters:
control_type
Chooses the controller type and determines which calculation XController performs. The documented options are Knob, FaderH, FaderV, Toggle, Button, and XYPad; the default is Knob. Knob, either fader, and Button use the selected value mode; Toggle uses the current on/off state; XYPad calculates separate X and Y values. No numeric minimum or maximum applies.
value_mode
Chooses how a normalized position becomes a value for Knob, either fader, or Button. The source identifies Range, Steps, and Percentage modes, with Range as the default. Range uses the configured endpoints, Steps selects from a JSON list, and Percentage uses a base value and percentage offsets. This setting does not affect Toggle or XYPad. The complete enum definition is not included in the provided source, so these are the documented modes rather than a verified exhaustive option list.
min
Sets the lower value supplied to the Range calculation for Knob, either fader, or Button. The default is 0.0. It also describes the low end used by the button configuration, although the button’s interactive behavior is outside the provided execution code. No enforced minimum or maximum for this input is shown; the displayed input increment is 0.01.
max
Sets the upper value supplied to the Range calculation for Knob, either fader, or Button. The default is 1.0. Together with min, it defines the intended value span; the exact mapping is performed by an imported function whose implementation is not provided. No enforced minimum or maximum for this input is shown; the displayed input increment is 0.01.
step
Sets the snap interval applied to a Range result for Knob, either fader, or Button. The default is 0.01; values greater than zero round the calculated result to a multiple of this interval, while 0 or a negative value skips snapping in the shown execution code. The tooltip also identifies it as a hold-button increment, but the frontend behavior is not shown here. No enforced minimum or maximum is specified; the displayed input increment is 0.001.
default_value
Specifies the intended starting or reset value for Range controls. The default is 0.5. It is declared as an input but is not read by the shown execute method, so changing it alone does not change the value calculated during that execution; current position arrives through _normalized. No enforced minimum or maximum is shown, and the displayed input increment is 0.01.
steps
Provides the discrete values for Steps mode as a JSON array, such as [0, 0.25, 0.5, 1]. The default text is [0.0, 0.25, 0.5, 0.75, 1.0]. The node passes parsed values to its value calculation; if parsing raises ValueError, it silently substitutes [0.0, 1.0]. This is a string input, so no numeric minimum or maximum is specified.
default_step_index
Identifies the intended starting or reset entry in steps, counting from zero. The default is 2, which refers to the third entry in the default list. The tooltip says the button moves one index per repeat, but the shown execute method does not read this parameter; the live result uses the current normalized position instead. No enforced minimum or maximum is shown.
base_value
Provides the starting amount used by Percentage mode before its percentage offset is applied. The default is 100.0. It is passed to the imported value-calculation function for Knob, either fader, or Button; the exact percentage formula is not visible in the supplied source. No enforced minimum or maximum is shown, and the displayed input increment is 0.01.
pct_min
Sets the lower percentage offset passed to the Percentage calculation. The default is -50.0; negative offsets are described as reducing the base value. It matters when Percentage mode is active for Knob, either fader, or Button. No enforced minimum or maximum for the input is shown, and the displayed input increment is 0.1.
pct_max
Sets the upper percentage offset passed to the Percentage calculation. The default is 50.0; positive offsets are described as increasing the base value. It matters when Percentage mode is active for Knob, either fader, or Button. No enforced minimum or maximum for the input is shown, and the displayed input increment is 0.1.
default_pct
Specifies the intended starting or reset percentage offset. The default is 0.0. Although it appears in the configuration, the shown execute method does not read it, so it does not directly alter a calculated result. No enforced minimum or maximum is shown, and the displayed input increment is 0.1.
shape
Selects the visual shape of a knob or the handle shape of a fader. The default is the circle enum value. This is a presentation setting: the shown execute method does not read it, so changing it alone does not change the calculated outputs. The full KnobShape option list is absent from the provided source; no numeric minimum or maximum applies.
toggle_style
Selects the toggle’s visual style, with switch as the default enum value. The toggle’s calculated state comes from _state, not this styling choice; the shown execute method does not read toggle_style. The full ToggleStyle option list is absent from the provided source, and no numeric minimum or maximum applies.
default_state
Specifies the intended default toggle state when no saved state exists. The default is True, displayed as Enabled rather than Disabled. The shown execute method does not read this input: its live toggle result comes from _state. This is a Boolean setting, so its possible values are True and False rather than a numeric range.
button_mode
Configures the button interaction described by the interface: increase raises a value while held, decrease lowers it while held, and toggle switches between the configured endpoints. The default is increase. The full ButtonMode enum definition and frontend interaction code are not provided; in the shown execute method, button_mode is not read and Button follows the same value-calculation branch as Knob and the faders. No numeric minimum or maximum applies.
button_style
Selects the button’s visual shape, with rounded as the default enum value. It does not affect the calculations shown in execute. The full ButtonStyle option list is absent from the provided source, and no numeric minimum or maximum applies.
x_min
Sets the lower endpoint used to calculate the XY pad’s X output. The default is 0.0. It is passed with the current X position and x_max to the imported range-mapping function; the resulting X value may then be snapped. No enforced minimum or maximum for this input is shown, and the displayed input increment is 0.01.
x_max
Sets the upper endpoint used to calculate the XY pad’s X output. The default is 1.0. Together with x_min, it defines the X value span supplied to the imported range-mapping function. No enforced minimum or maximum for this input is shown, and the displayed input increment is 0.01.
x_step
Sets the XY pad’s X snap interval. The default is 0.01; when it is greater than zero, the calculated X value is rounded to a multiple of the interval. Setting it to 0 or a negative value skips that rounding in the shown code. No enforced minimum or maximum is shown, and the displayed input increment is 0.001.
x_default
Specifies the intended starting or reset X value for the XY pad. The default is 0.5. The shown execute method does not read it; the current X position used for calculation comes from _x_normalized. No enforced minimum or maximum is shown, and the displayed input increment is 0.01.
y_min
Sets the lower endpoint used to calculate the XY pad’s Y output. The default is 0.0. It is passed with the current Y position and y_max to the imported range-mapping function; the resulting Y value may then be snapped. No enforced minimum or maximum for this input is shown, and the displayed input increment is 0.01.
y_max
Sets the upper endpoint used to calculate the XY pad’s Y output. The default is 1.0. Together with y_min, it defines the Y value span supplied to the imported range-mapping function. No enforced minimum or maximum for this input is shown, and the displayed input increment is 0.01.
y_step
Sets the XY pad’s Y snap interval. The default is 0.01; when it is greater than zero, the calculated Y value is rounded to a multiple of the interval. Setting it to 0 or a negative value skips that rounding in the shown code. No enforced minimum or maximum is shown, and the displayed input increment is 0.001.
y_default
Specifies the intended starting or reset Y value for the XY pad. The default is 0.5. The shown execute method does not read it; the current Y position used for calculation comes from _y_normalized. No enforced minimum or maximum is shown, and the displayed input increment is 0.01.
crosshair_visible
Controls whether guide lines are shown through the current XY point. The default is True or Enabled; False means Disabled. This is a visual setting and is not read by the shown calculation code, so it does not change X or Y values. As a Boolean, it has no numeric minimum or maximum.
grid_visible
Controls whether a positioning grid is shown behind the XY pad. The default is True or Enabled; False means Disabled. This is a visual setting and is not read by the shown calculation code, so it does not change X or Y values. As a Boolean, it has no numeric minimum or maximum.
_normalized
Holds the current normalized position for Knob, either fader, or Button. It is an internal, hidden, socketless input intended to be written by the frontend; the default is 0.5 and its declared range is 0.0 to 1.0, with a 0.0001 input increment. Changing this position changes the value passed to the selected value mode’s calculation.
_state
Holds the current internal Boolean state, with False as the default. It is hidden and socketless. For Toggle, it directly determines the on/off result and whether the numeric value is zero or one; for Knob, either fader, and Button, it is passed through as the Boolean output. Its possible values are True and False, not a numeric range.
_x_normalized
Holds the XY pad’s current normalized X position. It is an internal, hidden, socketless input intended to be written by the frontend; the default is 0.5 and its declared range is 0.0 to 1.0, with a 0.0001 input increment. The node maps this position through the configured X endpoints to produce X.
_y_normalized
Holds the XY pad’s current normalized Y position. It is an internal, hidden, socketless input intended to be written by the frontend; the default is 0.5 and its declared range is 0.0 to 1.0, with a 0.0001 input increment. The node maps this position through the configured Y endpoints to produce Y.
XController Output Parameters:
FLOAT
The main numeric result. For Knob, either fader, or Button, it is the value calculated from the current normalized position and selected mode, with Range snapping applied when step is positive. For Toggle, it is 1.0 when on and 0.0 when off. For XYPad, it is always 0.0 in the shown implementation, so use X and Y for that controller.
INT
A whole-number version of FLOAT, produced with int(result) for Knob, either fader, or Button. Conversion truncates toward zero: for example, 2.9 becomes 2 and -2.9 becomes -2. Toggle produces 1 or 0; XYPad produces 0. Use this output when a connected node needs an integer rather than a fractional value.
BOOLEAN
The state output. Toggle reports the current _state directly; Knob, either fader, and Button also pass through _state. XYPad always reports False in the shown implementation. For a Button, this socket can convey the state supplied by the frontend, but the supplied source does not show when that frontend sets or clears it.
X
The XY pad’s calculated horizontal coordinate, derived from _x_normalized and the configured X endpoints, then snapped when x_step is positive. For Knob, either fader, Button, and Toggle, this output is 0.0. Connect it when you need one independently controlled value from an XY pad.
Y
The XY pad’s calculated vertical coordinate, derived from _y_normalized and the configured Y endpoints, then snapped when y_step is positive. For Knob, either fader, Button, and Toggle, this output is 0.0. Connect it alongside X when you need to control two values at once.
XController Usage Tips:
- For a smooth single-value adjustment, select
Knobor a fader, chooseRange, and setminandmaxto the values your connected node expects. Setstepto0when you do not want the extra Range rounding shown in the source. - For a small set of deliberate choices, select
Stepsand enter a valid JSON array such as[0, 0.25, 0.5, 1]. Check the JSON carefully: a parsing error falls back to[0.0, 1.0]without an error message. - For two independent adjustments, select
XYPadand configure the X and Y endpoints separately. ConnectXandYrather thanFLOAT; the XY pad branch always setsFLOATto0.0. - Choose snap intervals that suit the precision you need. Positive
step,x_step, andy_stepround their respective calculated values;0skips that rounding. Because rounding occurs after calculation, inspect the actual output if an exact endpoint is important. - Treat the
default_*settings as intended starting or reset configuration, not as live overrides. The shown execution reads current positions and state from the hidden inputs; it does not readdefault_value,default_step_index,default_pct,default_state,x_default, ory_default.
XController Common Errors and Solutions:
ValueError: '...' is not a valid ControlType
- Explanation: The selected
control_typedoes not match a value in the providedControlTypeenum. This error would occur when the node attempts to interpret the controller type. - Solution: Select one of
Knob,FaderH,FaderV,Toggle,Button, orXYPad. Check spelling and capitalization if the value was supplied programmatically.
ValueError: '...' is not a valid ValueMode
- Explanation: For Knob, either fader, or Button, the node converts
value_modeto an enum before calculating a result. An unrecognized value can stop execution; Toggle and XYPad do not perform that conversion in the shown code. - Solution: Choose a mode offered by the node’s dropdown. The provided source describes
Range,Steps, andPercentage; if setting a value programmatically, use the exact value exposed by the installed enum.
Invalid steps JSON produces unexpected values without an error message
- Explanation: The node catches a
ValueErrorfromparse_steps_jsonand substitutes[0.0, 1.0]. Consequently, a malformed Steps list may appear to work while producing different values than you intended; the parser’s full validation rules are not provided. - Solution: Enter a JSON array with brackets and comma-separated numbers, such as
[0, 0.25, 0.5, 1], then verify the connected output.
FLOAT stays at 0.0 with XYPad
- Explanation: This is the defined XY pad result in the shown implementation, not evidence that its coordinates failed. The XY pad places its calculated values on
XandY. - Solution: Connect the
XandYsockets to the nodes you want to control.
X and Y stay at 0.0 with another controller
- Explanation: Knob, either fader, Button, and Toggle explicitly return zero for both coordinate outputs.
- Solution: Select
XYPadwhen you need coordinate values; otherwise useFLOAT,INT, orBOOLEANas appropriate.
Changing a default does not change the current output
- Explanation: The shown execution does not read the
default_*inputs. It calculates from the current hidden position or state instead. - Solution: Move the visible control or update its saved current position or state through the interface that manages it. Use default settings for their intended starting or reset behavior, where supported by that interface.
INT differs from the displayed fractional value
- Explanation:
INTtruncatesFLOATtoward zero rather than rounding it to the nearest whole number. - Solution: Connect
FLOATwhen fractions matter. If you need whole-number results, account for truncation when configuring the value range and snap interval.
Snapped output differs slightly from an expected endpoint
- Explanation: In Range and XYPad calculations, a positive snap interval rounds the computed result to a multiple of that interval. This can change a value when an endpoint is not aligned to the interval.
- Solution: Use an interval that divides your intended values cleanly, or set the relevant snap interval to
0to skip the rounding shown in the source.
Toggle reports the opposite of default_state
- Explanation: Toggle uses the current internal
_stateduring execution.default_stateis not read by the shown calculation, and the hidden_stateinput defaults toFalse. - Solution: Check the visible toggle’s current or saved state. Do not rely on changing
default_statealone to force the current output.
