Save 4 hours! We auto-setup your workflow! Free!

Drop your workflow.json — we handle every dependency, custom node, and model. Just open the link and run.

Auto-Setup Workflow Json (Free) Now!
ComfyUI > Nodes > ComfyUI-Xz3r0-Nodes > XController

ComfyUI Node: XController

Class Name

XController

Category
♾️ Xz3r0/Workflow-Processing
Author
xz3r0-m (Account age: 2335days)
Extension
ComfyUI-Xz3r0-Nodes
Latest Updated
2026-11-08
Github Stars
0.02K

How to Install ComfyUI-Xz3r0-Nodes

Install this extension via the ComfyUI Manager by searching for ComfyUI-Xz3r0-Nodes
  • 1. Click the Manager button in the main menu
  • 2. Select Custom Nodes Manager button
  • 3. Enter ComfyUI-Xz3r0-Nodes in the search bar
After installation, click the Restart button to restart ComfyUI. Then, manually refresh your browser to clear the cache and access the updated list of nodes.

Visit ComfyUI Online for ready-to-use ComfyUI environment

  • Free trial available
  • 16GB VRAM to 80GB VRAM GPU machines
  • 400+ preloaded models/nodes
  • Freedom to upload custom models/nodes
  • 200+ ready-to-run workflows
  • 100% private workspace with up to 200GB storage
  • Dedicated Support

Run ComfyUI Online

XController Description

Configurable knob, fader, toggle, button, or XY pad for controlling values in ComfyUI workflows.

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 Knob or a fader, choose Range, and set min and max to the values your connected node expects. Set step to 0 when you do not want the extra Range rounding shown in the source.
  • For a small set of deliberate choices, select Steps and 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 XYPad and configure the X and Y endpoints separately. Connect X and Y rather than FLOAT; the XY pad branch always sets FLOAT to 0.0.
  • Choose snap intervals that suit the precision you need. Positive step, x_step, and y_step round their respective calculated values; 0 skips 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 read default_value, default_step_index, default_pct, default_state, x_default, or y_default.

XController Common Errors and Solutions:

ValueError: '...' is not a valid ControlType

  • Explanation: The selected control_type does not match a value in the provided ControlType enum. This error would occur when the node attempts to interpret the controller type.
  • Solution: Select one of Knob, FaderH, FaderV, Toggle, Button, or XYPad. 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_mode to 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, and Percentage; 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 ValueError from parse_steps_json and 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 X and Y.
  • Solution: Connect the X and Y sockets 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 XYPad when you need coordinate values; otherwise use FLOAT, INT, or BOOLEAN as 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: INT truncates FLOAT toward zero rather than rounding it to the nearest whole number.
  • Solution: Connect FLOAT when 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 0 to skip the rounding shown in the source.

Toggle reports the opposite of default_state

  • Explanation: Toggle uses the current internal _state during execution. default_state is not read by the shown calculation, and the hidden _state input defaults to False.
  • Solution: Check the visible toggle’s current or saved state. Do not rely on changing default_state alone to force the current output.

XController Related Nodes

Go back to the extension to check out more related nodes.
ComfyUI-Xz3r0-Nodes
RunComfy
Copyright 2025 RunComfy. All Rights Reserved.

RunComfy is the premier ComfyUI platform, offering ComfyUI online environment and services, along with ComfyUI workflows featuring stunning visuals. RunComfy also provides AI Models, enabling artists to harness the latest AI tools to create incredible art.

XController