Controls and Script Data

CV scripts can read current controller, keyboard, and mouse state. They can also publish a compact byte payload for a supported workflow that expects script data.

Python Controls

python

from helios import controls

Call	Returns
`controls.get_actual(id)`	Current physical input value
`controls.get_val(id)`	Current translated output value
`controls.key_actual(vk)`	Physical keyboard-key state
`controls.key_report(vk)`	Translated keyboard-key state
`controls.mouse_actual()`	Physical mouse state
`controls.mouse_report()`	Translated mouse state
`controls.send_cvdata(data)`	`True` when explicit `bytes` or `bytearray` data was accepted
`controls.list_identifiers()`	Prints the available controller identifiers in the Output Panel

Keyboard modifier and lock-state helpers are also available:

keyboard_actual_modifiers() and keyboard_report_modifiers()
keyboard_actual_caps_lock() and keyboard_report_caps_lock()
keyboard_actual_num_lock() and keyboard_report_num_lock()
keyboard_actual_scroll_lock() and keyboard_report_scroll_lock()

Controller constants include BUTTON_1 through BUTTON_21, STICK_1_X through STICK_2_Y, touch points, accelerometers, gyroscopes, and paddles. Buttons normally use 0..100; stick axes normally use -100..100.

Publishing Script Data

Call controls.send_cvdata(data) from process(frame):

python

from helios import controls


class CVWorker:
    def __init__(self, width, height):
        self.payload = bytearray(3)

    def process(self, frame):
        source_pressed = controls.get_actual(controls.BUTTON_5) > 50
        axis_x = int(controls.get_actual(controls.STICK_1_X))

        self.payload[0] = 1 if source_pressed else 0
        self.payload[1] = axis_x & 0xFF
        self.payload[2] = 1  # Payload version

        controls.send_cvdata(self.payload)

Keep payloads at or below 255 bytes. Define and version your own byte layout so the producing CV script and consuming GPC script agree on the meaning of every byte.

Mouse Values

mouse_actual() and mouse_report() return:

text

(delta_x, delta_y, wheel_y, wheel_x, buttons,
 absolute_x, absolute_y, coordinate_mode, dpi, screen_width, screen_height)

Mouse-button constants are bit flags: MOUSE_LEFT, MOUSE_RIGHT, MOUSE_MIDDLE, MOUSE_X1, and MOUSE_X2.

C++

CV C++ provides the same concepts under Helios::Controls:

cpp

const bool sourcePressed =
    Helios::Controls::getActual(
        Helios::Controls::Controller::BUTTON_5) > 50.0f;

const std::array<std::uint8_t, 2> payload{
    sourcePressed ? std::uint8_t{1} : std::uint8_t{0},
    std::uint8_t{1},
};

Helios::Controls::sendCvData(payload);

Use Helios::Controls::getActual(...) for physical state and getVal(...) for translated state. The C++ SDK also provides borrowed state views through controllerInputState(), controllerReportState(), keyboardInputState(), keyboardReportState(), mouseInputState(), and mouseReportState(). Use isKeyDown() and isMouseButtonDown() with those views.

State-view pointers are borrowed. Read them during the current callback and do not retain them.