SteelSeries GameSense SDK Documentation

The Flasher prototype allows you to create complex, logic-driven visual effects like flashing bars. You can define a custom frame using proto*: Flasher and override specific behaviors:

• compute-period: A function that returns the flash interval (in ms) based on a value.
• compute-color: A function that returns the color based on a value.
• update-color: A function that handles the actual device update (e.g., on-device).
• cleanup-function: A function to run when the effect is stopped.

Example of a hunger flasher that flashes faster when hunger is low:

(define hunger-flasher {
    proto*: Flasher
    auto-enable: #f
    ;; Flash faster when really hungry. 
    compute-period: (lambda (hunger-percent)
                        (if (< hunger-percent 20) 250 100))
    compute-color: (lambda (hunger-percent) brown-color)
    update-color: (lambda (color hunger-percent)
                        (on-device 'keyboard show-percent-on-zone: color hunger-percent number-keys:))
    cleanup-function: (lambda (value)
                        (update-color color value))})

(handler "HUNGERLEVEL"
    (lambda (data)
        (let ((hungerlevel (value: data)))
            (send hunger-flasher set-value: hungerlevel))))

GoLisp handlers allow for complex logic to be executed on-device in response to GameSense™ events.

Data Mapping

When an event is received, the data parameter in the handler function contains the payload. The conversion from JSON to GoLisp follows these rules:

• JSON Objects $\rightarrow$ Frames
• JSON Arrays $\rightarrow$ Lists
• Strings/Numbers $\rightarrow$ Strings/Numbers

To access specific slots within a frame, you can use the values: shorthand (e.g., (values: data) is equivalent to get-slot for the values key in the data frame).

Hardware Control

To control hardware like RGB lighting, use the on-device primitive.

• Device Class: Specifies the target hardware type (e.g., "rgb-per-key-zones").
• Message Type: Specifies the command (e.g., show-on-keys: for per-key illumination).
• Arguments: The data required by the message (e.g., a list of HID codes and a corresponding list of colors).

Finally, you must register the event's scope using add-event-per-key-zone-use "EVENT_NAME" "ZONE" to tell GameSense™ which parts of the device are affected by the event.

The rate key enables repetition of the vibration effect. Repetition is defined by frequency (how many times the effect repeats per second).

Static Frequency

• frequency: A static value. 0 means the effect never repeats (default if rate is omitted).

Frequency Ranges

An array of objects defining sub-ranges for frequency:

• low / high: Inclusive bounds (mandatory).
• frequency: A static frequency or another range definition (mandatory).

Repeat Limit

Use repeat_limit within the rate object to stop the effect after a certain number of repetitions.

• repeat_limit: A static value or a range definition (optional).

Note: Set frequency low enough to prevent vibration effects from constantly queuing up, as vibrations take time to complete.

// Example: Static frequency of 1Hz with a limit of 5 repeats
"rate": {
  "frequency": 1,
  "repeat_limit": 5
}

// Example: Ranged frequency (3Hz for 0-10, 1Hz for 11-20)
"rate": {
  "frequency": [
    { "low": 0, "high": 10, "frequency": 3 },
    { "low": 11, "high": 20, "frequency": 1 }
  ]
}

// Example: Ranged repeat limit (repeats more as value decreases)
"rate": {
  "frequency": 5,
  "repeat_limit": [
    { "low": 0, "high": 10, "repeat_limit": 3 },
    { "low": 11, "high": 20, "repeat_limit": 2 },
    { "low": 21, "high": 100, "repeat_limit": 1 }
  ]
}

The bitmap mode allows you to individually control every key on an RGB per-key-illuminated keyboard simultaneously.

To use this mode:

1. Set device-type to 'rgb-per-key-zones'.
2. Set mode to 'bitmap'.
3. In your event data, include a frame object containing a bitmap key.

The bitmap value must be a 132-length array of colors. Each color is a 3-length array representing [R, G, B] values. This array is interpreted as a 22x6 grid mapped to the keyboard (starting from the top-left). Any array elements that do not map to a physical key on the user's device are ignored.

Tip: When registering the event, set the value_optional flag so you can omit the standard value key and only send the bitmap data in the frame.

{
  "game": "MY_GAME",
  "event": "BITMAP_EVENT",
  "data": {
    "frame": {
      "bitmap": [
        [255,0,0],   // Color for top left
        [255,255,0], // Color for second part of top row
        // ... 130 more colors
      ]
    }
  }
}

The color key determines how the LED color is calculated based on event values.

Static Color

Specifies a single color. The zone will be this color for any non-zero event value.

"color": { "red": 255, "green": 0, "blue": 255 }

Linear Gradient

Specifies a gradient between a zero color (0%) and a hundred color (100%). The event value (0-100) selects the color along this gradient.

"color": {
  "gradient": {
    "zero": { "red": 255, "green": 0, "blue": 0 },
    "hundred": { "red": 0, "green": 255, "blue": 0 }
  }
}

Color Based on Ranges

Divides the event value range into discrete sub-ranges. Each sub-range has a low (inclusive) and high (inclusive) bound and an associated color (which can be static, gradient, or another range).

"color": [
  { "low": 0, "high": 10, "color": { "red": 255, "green": 0, "blue": 0 } },
  { "low": 11, "high": 100, "color": { "gradient": { ... } } }
]