UnityChromaSDK - the Unity C# library for the Chroma Rest API

Deprecated

• Note: Visit the Chroma Animation Guide to find the latest supported plugin for Chroma RGB.

• Note: This version of the Unity plugin is deprecated.

• Note: Go to Unity_SampleApp for the latest Unity plugin.

---

Table of Contents

• Related
• Frameworks supported
• Dependencies
• Packaging
• Getting Started
• Assets
• Plugins
• Documentation for API Endpoints
• Examples
• Chroma Initialization
• Chroma Heartbeat
• Destroy the Chroma Session
• PUT vs POST
• PUT Effect
• Remove Effect
• PUT CHROMA_NONE Effect
• POST CHROMA NONE Effect
• Colors
• PUT CHROMA_STATIC Effect
• POST CHROMA_STATIC Effect
• PUT CHROMA_CUSTOM Effect
• POST CHROMA_CUSTOM Effect
• EffectType
• PUT EffectType
• POST EffectType

Related

• CChromaEditor - C++ Native MFC Library for playing and editing Chroma animations

• GameMakerChromaExtension - GameMaker Extension to control lighting for Razer Chroma

• HTML5ChromaSDK - JS Library for playing Chroma animations

• UE4ChromaSDK - Unreal Engine 4 (UE4) Blueprint library to control lighting for Razer Chroma

• UnityNativeChromaSDK - Unity native library for the ChromaSDK

• UnityChromaSDK - Unity C# library for the Chroma Rest API

Frameworks supported

• Unity 3.5.7 or later
• Windows Editor / Standalone

Dependencies

• RestSharp - 105.1.0 or later
• Json.NET - 7.0.0 or later

Packaging

Import UnityChromaSDK.unitypackage into your project.

Getting Started

1 Install Unity3d

2 Open Unity and start with an existing project or open a new project

3 Download the UnityChromaSDK.unitypackage file

4 Import the UnityChromaSDK.unitypackage using the Assets->Import Package->Custom Package... and select the downloaded file

5 Select all the files and click the Import button

6 Open the example scene Assets/ChromaSDK/Examples/Scenes/Example01.unity

7 Be sure to select Run in background in the player settings, so that Chroma still works when Unity doesn't have focus

8 Hit play

9 Customize the example script Assets/ChromaSDK/Examples/Scripts/ChromaExample01.cs

Assets

Use the GameObject->ChromaSDK menu to create 1D and 2D animations.

Once created, the gameobjects can be renamed and dragged to the Object Hierarchy to turn into prefab assets.

1D assets have a custom inspector that can be used to view, edit, and paint animation frames.

2D assets also have a custom inspector with the ability to paint specific keys (keyboard) and leds (mouse).

The custom inspectors set the device type and allow the color animation frames to be edited. 1D animations support ChromaLink, Headset, and Mousepad devices. 2D animations support Keyboard, Keypad, and Mouse devices. The device preview shows a grid and clicking the elements will set the color from the color swatches. The Curve adjusts the timings for each animation frame.

In the Example01 scene, the 1D and 2D prefab assets are referenced. The ChromaExample01.cs script uses public ChromaSDKAnimation1D[] and ChromaSDKAnimation2D[] arrays as meta references to the prefabs. In order for the animations to play in play-mode, the prefabs need to be instantiated. This allows the monobehaviour update event to fire.

Animation assets rely on the ChromaConnectionManager to maintain the REST client connection. If the REST server connection is lost, the ChromaConnectionManager should reconnect. The ChromaConnectionManager also has a custom inspector where the Chroma details can be specified.

Plugins

The following plugins should be included in the game build to allow the REST client to function.

Assets/Plugins/Newtonsoft.Json.dll - JSON encoding/decoding library for Unity 3.X/4.X/5.X

Assets/Plugins/RestSharp.dll - REST client library for Unity 3.X/4.X/5.X

The following plugins are editor only plugins and should be stripped from the final game build.

Assets/Plugins/UnityImageNativePlugin3.dll - Windows native library handles BMP/GIF/JPG/PNG image imports for Unity 3.X

Assets/Plugins/x64/UnityImageNativePlugin.dll - (64-bit) Windows native library handles BMP/GIF/JPG/PNG image imports for Unity 4.X/5.X

Assets/Plugins/x86/UnityImageNativePlugin.dll - (32-bit) Windows native library handles BMP/GIF/JPG/PNG image imports for Unity 4.X/5.X

Documentation for API Endpoints

• The RazerApi endpoint creates the Chroma session.
• The ChromaApi endpoint controls Chroma lighting.

Examples

Add the Chroma namespace.

// Access to Chroma data structures
using ChromaSDK.ChromaPackage.Model;

// Access to the Chroma API
using ChromaSDK.Api;

// Access to the Session data structures
using RazerSDK.ChromaPackage.Model;

// Access to the Session API
using RazerSDK.Api;

Calls to the Chroma API should be done in a separate thread to avoid blocking the main thread and to avoid reducing the rendering frame rate.

ChromaUtils.RunOnThread(() =>
{
    // Make calls to the Chroma API in a separate thread to avoid blocking the main thread
    Initialize();
});

Chroma Initialization

Create an instance of the RazerAPI which will be used to create the Chroma session.

 // use the Razer API to get the session
_mApiRazerInstance = new RazerApi();

Populate the input to initialize the Chroma session.

var input = new ChromaSdkInput();
input.Title = "UnityPlugin";
input.Description = "This is a REST interface Unity client";
input.Author = new ChromaSdkInputAuthor();
input.Author.Name = "Chroma Developer";
input.Author.Contact = "www.razerzone.com";
input.DeviceSupported = new List<string>
{
    "keyboard",
    "mouse",
    "headset",
    "mousepad",
    "keypad",
    "chromalink",
};
input.Category = "application";

PostChromaSdk creates a Chroma session which is used to control the Chroma lighting.

// create the Chroma session, the result contains the session and base uri for the Chroma API
PostChromaSdkResponse result = _mApiRazerInstance.PostChromaSdk(input);

Use the response from creating the Chroma session to create an instance of the Chroma API.

// setup the api instance with the session uri
_mApiChromaInstance = new ChromaApi(result.Uri);

Chroma Heartbeat

After the Chroma instance has been created, repeatedly call Heartbeat to keep the Chroma session alive.

while (true)
{
    // The Chroma API uses a heartbeat every 1 second
    _mApiChromaInstance.Heartbeat();

    // Wait for a sec
    Thread.Sleep(1000);
}

Destroy the Chroma session

Destroy the Chroma session from OnDisable and OnApplicationQuit to return lighting control to the system.

// destroy the Chroma session
DeleteChromaSdkResponse result = _mApiChromaInstance.DeleteChromaSdk();

// clear the references
_mApiRazerInstance = null;
_mApiChromaInstance = null;

PUT vs POST

In the Chroma API there are two kinds of methods. PUT applies the lighting effect immediately. POST creates an Effect identifier that can be reused instead of applying the lighting effect.

PUT Effect

PutEffect activates an effect or effects. An effect is a string identifier. The EffectIdentifierInput constructor takes a single effect string or a list of effect strings.

// use a string effect
var input = new EffectIdentifierInput(effect, null);

// use a list of string effects
var input = new EffectIdentifierInput(null, effects);

// activate the effect or effects
EffectIdentifierResponse result = _mApiChromaInstance.PutEffect(input);

REMOVE Effect

RemoveEffect takes the same EffectIdentifierInput as PutEffect. Effects can be deleted for a string effect or a list of string effects.

// use a string effect
var input = new EffectIdentifierInput(effect, null);

// use a list of string effects
var input = new EffectIdentifierInput(null, effects);

// Remove the effect or effects
EffectIdentifierResponse result = _mApiChromaInstance.RemoveEffect(input);

PUT CHROMA_NONE Effect

Set the CHROMA_NONE effect to clear the device lighting effects.

ChromaLink

EffectResponse result = _mApiChromaInstance.PutChromaLinkNone();

Headset

EffectResponse result = _mApiChromaInstance.PutHeadsetNone();

Keyboard

EffectResponse result = _mApiChromaInstance.PutKeyboardNone();

Keypad

EffectResponse result = _mApiChromaInstance.PutKeypadNone();

Mouse

EffectResponse result = _mApiChromaInstance.PutMouseNone();

Mousepad

EffectResponse result = _mApiChromaInstance.PutMousepadNone();

POST CHROMA_NONE Effect

Create an effect identifier with the CHROMA_NONE effect to clear the device lighting effects.

ChromaLink

EffectResponseId result = _mApiChromaInstance.PostChromaLinkNone();

Headset

EffectResponseId result = _mApiChromaInstance.PostHeadsetNone();

Keyboard

EffectResponseId result = _mApiChromaInstance.PostKeyboardNone();

Keypad

EffectResponseId result = _mApiChromaInstance.PostKeypadNone();

Mouse

EffectResponseId result = _mApiChromaInstance.PostMouseNone();

Mousepad

EffectResponseId result = _mApiChromaInstance.PostMousepadNone();

Colors

The Chroma API takes colors in the BGR (blue-green-red) format as an integer. Unity Color objects can be converted to BGR integers with ToBGR.

// Create a Unity Color object
Color color = Color.red;

// Convert Unity Color object to BGR integer
int bgrInteger = ChromaUtils.ToBGR(color);

BGR integers can be converted to Unity Color objects with ToRGB.

// Create a BGR integer
int bgrInteger = 255; //red

// Convert BGR integer to Unity Color object
Color color = ChromaUtils.ToRGB(bgrInteger);

PUT CHROMA_STATIC Effect

Set the STATIC effect to set the device lighting effects to use a static color. PUT with CHROMA_STATIC takes a BGR integer to set the static color.

ChromaLink

EffectResponse result = _mApiChromaInstance.PutChromaLinkStatic(bgrInteger);

Headset

EffectResponse result = _mApiChromaInstance.PutHeadsetStatic(bgrInteger);

Keyboard

EffectResponse result = _mApiChromaInstance.PutKeyboardStatic(bgrInteger);

Keypad

EffectResponse result = _mApiChromaInstance.PutKeypadStatic(bgrInteger);

Mouse

EffectResponse result = _mApiChromaInstance.PutMouseStatic(bgrInteger);

Mousepad

EffectResponse result = _mApiChromaInstance.PutMousepadStatic(bgrInteger);

POST CHROMA_STATIC Effect

Create an effect identifier with the CHROMA_STATIC effect to set the device lighting effects to use a static color. POST with CHROMA_STATIC takes a BGR integer to set the static color.

ChromaLink

EffectResponseId result = _mApiChromaInstance.PostChromaLinkStatic(bgrInteger);

Headset

EffectResponseId result = _mApiChromaInstance.PostHeadsetStatic(bgrInteger);

Keyboard

EffectResponseId result = _mApiChromaInstance.PostKeyboardStatic(bgrInteger);

Keypad

EffectResponseId result = _mApiChromaInstance.PostKeypadStatic(bgrInteger);

Mouse

EffectResponseId result = _mApiChromaInstance.PostMouseStatic(bgrInteger);

Mousepad

EffectResponseId result = _mApiChromaInstance.PostMousepadStatic(bgrInteger);

PUT CHROMA_CUSTOM Effect

Set the CUSTOM effect to set the device lighting effects to use multiple colors. Depending on the device PUT with CHROMA_CUSTOM takes a one-dimensional array or two-dimensional array of BGR integers to set colors on a grid. Razer Chroma™ LED Profiles has a guide to see the device grid layouts.

ChromaLink

ChromaLink uses a 1D array with 5 elements for CUSTOM effects.

// generate colors
EffectArray1dInput elements = ChromaUtils.CreateRandomColors1D(ChromaDevice1DEnum.ChromaLink));
// Set the custom effect
EffectResponse result = _mApiChromaInstance.PutChromaLinkCustom(elements);

Headset

Headset uses a 1D array with 5 elements for CUSTOM effects. Note: Not all Chroma headsets are compatible with CUSTOM effects where some devices will not apply the custom effect.

// generate colors
EffectArray1dInput elements = ChromaUtils.CreateRandomColors1D(ChromaDevice1DEnum.Headset));
// Set the custom effect
EffectResponse result = _mApiChromaInstance.PutHeadsetCustom(elements);

Keyboard

Keyboard uses a 2D array with 6 rows of 22 columns for CUSTOM effects.

// generate colors
EffectArray2dInput rows = ChromaUtils.CreateRandomColors2D(ChromaDevice2DEnum.Keyboard));
// Set the custom effect
EffectResponse result = _mApiChromaInstance.PutKeyboardCustom(rows);

Keypad

Keypad uses a 2D array with 4 rows of 5 columns for CUSTOM effects.

// generate colors
EffectArray2dInput rows = ChromaUtils.CreateRandomColors2D(ChromaDevice2DEnum.Keypad));
// Set the custom effect
EffectResponse result = _mApiChromaInstance.PutKeypadCustom(rows);

Mouse

Mouse uses a 2D array with 9 rows of 7 columns for CUSTOM effects.

// generate colors
EffectArray2dInput rows = ChromaUtils.CreateRandomColors2D(ChromaDevice2DEnum.Mouse));
// Set the custom effect
EffectResponse result = _mApiChromaInstance.PutMouseCustom(rows);

Mousepad

Mousepad uses a 1D array with 15 elements for CUSTOM effects.

// generate colors
EffectArray1dInput elements = ChromaUtils.CreateRandomColors1D(ChromaDevice1DEnum.Mousepad));
// Set the custom effect
EffectResponse result = _mApiChromaInstance.PutMousepadCustom(elements);

POST CHROMA_CUSTOM Effect

Create an effect identifier with the CUSTOM effect to set the device lighting effects to use multiple colors. Depending on the device POST with CHROMA_CUSTOM takes a one-dimensional array or two-dimensional array of BGR integers to set colors on a grid. Razer Chroma™ LED Profiles has a guide to see the device grid layouts.

ChromaLink

ChromaLink uses a 1D array with 5 elements for CUSTOM effects.

// generate colors
EffectArray1dInput elements = ChromaUtils.CreateRandomColors1D(ChromaDevice1DEnum.ChromaLink));
// Set the custom effect
EffectResponseId result = _mApiChromaInstance.PostChromaLinkCustom(elements);

Headset

Headset uses a 1D array with 5 elements for CUSTOM effects. Note: Not all Chroma headsets are compatible with CUSTOM effects where some devices will not apply the custom effect.

// generate colors
EffectArray1dInput elements = ChromaUtils.CreateRandomColors1D(ChromaDevice1DEnum.Headset));
// Set the custom effect
EffectResponseId result = _mApiChromaInstance.PostHeadsetCustom(elements);

Keyboard

Keyboard uses a 2D array with 6 rows of 22 columns for CUSTOM effects.

// generate colors
EffectArray2dInput rows = ChromaUtils.CreateRandomColors2D(ChromaDevice2DEnum.Keyboard));
// Set the custom effect
EffectResponseId result = _mApiChromaInstance.PostKeyboardCustom(rows);

Keypad

Keypad uses a 2D array with 4 rows of 5 columns for CUSTOM effects.

// generate colors
EffectArray2dInput rows = ChromaUtils.CreateRandomColors2D(ChromaDevice2DEnum.Keypad));
// Set the custom effect
EffectResponseId result = _mApiChromaInstance.PostKeypadCustom(rows);

Mouse

Mouse uses a 2D array with 9 rows of 7 columns for CUSTOM effects.

// generate colors
EffectArray2dInput rows = ChromaUtils.CreateRandomColors2D(ChromaDevice2DEnum.Mouse));
// Set the custom effect
EffectResponseId result = _mApiChromaInstance.PostMouseCustom(rows);

Mousepad

Mousepad uses a 1D array with 15 elements for CUSTOM effects.

// generate colors
EffectArray1dInput elements = ChromaUtils.CreateRandomColors1D(ChromaDevice1DEnum.Mousepad));
// Set the custom effect
EffectResponseId result = _mApiChromaInstance.PostMousepadCustom(elements);

EffectType

Set the EffectType to set the device lighting effects to use one of the built-in effects. PUT and POST support CHROMA_BREATHING, CHROMA_REACTIVE, CHROMA_SPECTRUMCYCLING, and CHROMA_WAVE to set the lighting effect. Note: Not all effect types are supported on all devices.

EffectTypes

CHROMA_BREATHING

CHROMA_BREATHING transitions between two colors.

var effectInput = new EffectInput(EffectType.CHROMA_BREATHING);
effectInput.Param = new EffectInputParam();
effectInput.Param.Color1 = ChromaUtils.ToBGR(Color.red);
effectInput.Param.Color2 = ChromaUtils.ToBGR(Color.green);
effectInput.Param.Type = 1; //1 or 2

CHROMA_REACTIVE

CHROMA_REACTIVE reacts to device presses to show a color for a duration. A duration of 1 is shorter than 3.

var effectInput = new EffectInput(EffectType.CHROMA_REACTIVE);
effectInput.Param = new EffectInputParam();
effectInput.Param.Color = ChromaUtils.ToBGR(Color.red);
effectInput.Param.Duration = 1; // 1, 2, or 3

CHROMA_SPECTRUMCYCLING

CHROMA_SPECTRUMCYCLING is a built-in effect that cycles between spectrum colors.

var effectInput = new EffectInput(EffectType.CHROMA_SPECTRUMCYCLING);
effectInput.Param = new EffectInputParam();

CHROMA_WAVE

var effectInput = new EffectInput(EffectType.CHROMA_WAVE);
effectInput.Param = new EffectInputParam();
effectInput.Param.Direction = 1; //1 or 2

PUT EffectType

The following PUT endpoints use the EffectInput objects defined above.

ChromaLink

EffectResponse result = _mApiChromaInstance.PutChromaLink(effectInput);

Headset

EffectResponse result = _mApiChromaInstance.PutHeadset(effectInput);

Keyboard

EffectResponse result = _mApiChromaInstance.PutKeyboard(effectInput);

Keypad

EffectResponse result = _mApiChromaInstance.PutKeypad(effectInput);

Mouse

EffectResponse result = _mApiChromaInstance.PutMouse(effectInput);

Mousepad

EffectResponse result = _mApiChromaInstance.PutMousepad(effectInput);

POST EffectType

The following POST endpoints use the EffectInput objects defined above to create an effect identifier.

ChromaLink

EffectResponseId result = _mApiChromaInstance.PostChromaLink(effectInput);

Headset

EffectResponseId result = _mApiChromaInstance.PostHeadset(effectInput);

Keyboard

EffectResponseId result = _mApiChromaInstance.PostKeyboard(effectInput);

Keypad

EffectResponseId result = _mApiChromaInstance.PostKeypad(effectInput);

Mouse

EffectResponseId result = _mApiChromaInstance.PostMouse(effectInput);

Mousepad

EffectResponseId result = _mApiChromaInstance.PostMousepad(effectInput);