-
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
-
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
- Unity 3.5.7 or later
- Windows Editor / Standalone
Import UnityChromaSDK.unitypackage into your project.
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
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.
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
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();
});
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);
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 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;
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.
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);
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);
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();
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();
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);
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);
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);
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);
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);
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.
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
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);
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);