Helper Reference

This page covers the Creative helper calls intended for user-created scripts. The API is intentionally small: use the frame entry points, attach the current output handles, and write button or stick values through Combo.

Import

python
from creative_helper import Combo
from helios import controls

Combo is the public helper for controller output. Use helios.controls for controller constants and read helpers in Creative scripts.

Combo

python
combo = Combo()

Create one Combo instance at module scope and reuse it for every frame. The helper stores the output handles used by set_val() and precision stick writes.

Frame Outputs

Attach the current frame's output handles at the beginning of iterate() before setting values:

python
def iterate(button_bytes, stick_bytes, **kwargs):
    combo.buttons = button_bytes
    combo.sticks = stick_bytes

Pass button_bytes and stick_bytes through exactly as received; treat stick_bytes as an opaque output handle, not an array. Reattach both on each call and only write while that callback is running.

set_val

python
combo.set_val(button, value)

Sets a button, trigger, or stick output for the current frame.

  • 0 to 16: button or trigger output.
  • Use controls.STICK_1_X, controls.STICK_1_Y, controls.STICK_2_X, and controls.STICK_2_Y for the four stick axes (21–24). The older 17–20 identifiers address those same four axes.
  • Button values are usually 0 for released and 100 for pressed.
  • Stick values should normally stay in the -100 to 100 range.
python
def iterate(button_bytes, stick_bytes, **kwargs):
    combo.buttons = button_bytes
    combo.sticks = stick_bytes

    if controls.get_actual(controls.BUTTON_14):
        combo.set_val(controls.BUTTON_1, 100)
        combo.set_val(controls.STICK_1_X, 50)

set_val() accepts fractional stick values and clamps them to -100.0 through 100.0. Button values are clamped to 0 through 100. Unsupported identifiers raise ValueError.

Precision Stick Output

python
combo.set_precision_stick(button_code, value)

Writes a fractional stick-axis value for the current frame. set_val() also preserves fractional stick values; use either call with a valid stick identifier.

  • button_code uses the same stick/axis identifiers as set_val(), normally 17 to 24.
  • value is clamped to the -100.0 to 100.0 range.
  • Most scripts should call set_val() for stick output unless they specifically need fractional precision.
python
def iterate(button_bytes, stick_bytes, **kwargs):
    combo.buttons = button_bytes
    combo.sticks = stick_bytes

    if controls.get_actual(controls.BUTTON_14):
        combo.set_precision_stick(controls.STICK_1_X, 37.5)

Script Entry Points

python
def scan(button_bytes, stick_bytes, **kwargs):
    return

def iterate(button_bytes, stick_bytes, **kwargs):
    return

Creative scripts can expose two frame entry points.

scan

scan(button_bytes, stick_bytes, **kwargs) runs at the beginning of the frame, before the rest of the script logic. It sees the unaltered input/frame state.

Use scan() when a script needs to inspect the original frame state or prepare state before other logic runs.

python
last_pressed = False

def scan(button_bytes, stick_bytes, **kwargs):
    global last_pressed
    last_pressed = controls.get_actual(controls.BUTTON_14) > 0

iterate

iterate(button_bytes, stick_bytes, **kwargs) runs at the end of the frame, after script logic has already run and before the frame returns. It sees the current frame after other script logic has iterated on it.

Use iterate() for normal output writes and frame-result behavior.

python
def iterate(button_bytes, stick_bytes, **kwargs):
    combo.buttons = button_bytes
    combo.sticks = stick_bytes

    if last_pressed:
        combo.set_val(controls.BUTTON_1, 100)

Runtime Context

Keep **kwargs in both entry point signatures. Runtime context can include shared live-state objects for the current frame.

Live-state keys and fields depend on the active script, so use the script GUI for the specific values available to that script. A common use is reacting to a condition the script runtime already detected for the current frame.

python
def iterate(button_bytes, stick_bytes, **kwargs):
    combo.buttons = button_bytes
    combo.sticks = stick_bytes

    state = kwargs.get("live_state_key")
    if state and getattr(state, "condition_active", False):
        combo.set_val(controls.BUTTON_1, 100)

Use the live-state key and field names shown by the script GUI.

Notes

  • Prefer set_val() for normal button, trigger, and stick output.
  • Use set_precision_stick() only when fractional stick precision matters.
  • Keep Creative scripts small and explicit. Use GPC3 when you need dedicated controller timing/combo syntax.
← PreviousGetting Started