WYVRN Unity SDK

The WYVRN SDK has a C# API to integrate with AI, Chroma, and haptics.

About

The WYVRN SDK is a runtime game plugin that is shared to provide a common API for naming events and triggering external AI, Chroma playback and haptic events.

Getting Started With Unity SDK

This WYVRN SDK plugin requires Unity 2021.3.15f1 or higher.

Requirements and Setup

To import the WYVRN SDK into Unity using the Unity Package Manager, follow these steps:

Open the Unity Package Manager, then click the + button in the toolbar.

Add the WYVRN SDK package from disk or by URL

Option 1) Add package from disk

Select Add package from disk... from the menu.

Download this repository and browse to package.json file of the local copy.

Option 2) Add package from git URL

Select Add package from git URL from the menu.

In the text box that appears, enter the URL https://github.com/WyvrnOfficial/Unity_WyvrnSDK.git and click Add.

If either installation option is successful, the Razer WYVRN SDK package will appear in the package list.

Security

To avoid a 3rd party injecting malicious code, the plugin checks for a valid signature on the Razer Chromatic Library. The DLL issuer is validated to be Razer USA Ltd. Init and InitSDK will return RZRESULT_DLL_INVALID_SIGNATURE if the signature check fails.

General

The WYVRN SDK allows an application or game to set the details in the Chroma Apps list within the Chroma App.

This document provides a guide to integrating AI, Chroma, and haptics using the WYVRN C++ SDK. Here is the list of available methods from the API:

Initialize SDK: Initialize the WYVRN SDK to use the library.
Set Event Name: Name a game event or game trigger to add Chroma and haptics.
Uninitialize SDK: Cleanaly uninitialize the WYVRN SDK when done.

WYVRN SDK

The WYVRN SDK is the combination of AI, Chroma, and Razer Sensa HD Haptics in a single SDK. By integrating AI, RGB lighting and haptics into game environments and events, players can enjoy a truly immersive gaming experience. The WYVRN SDK is capable of playing Chroma animations and haptics on the Razer Sensa HD Haptics devices. SetEventName() can trigger AI interaction, RGB lighting, or haptics or all of the above.

Downloads

SDKs

WYVRN SDK

	Engine	Git Repo	Download Link	Git Repo	Download Link	Git Repo	Download Link
Encoding		UNICODE		ASCII		MULTI-BYTE
	WYVRN Design Template	Git	Download
	WYVRN C++ SDK	Git	Download	Git	Download	Git	Download
	WYVRN Unreal SDK	Git	Download
	WYVRN Unity SDK	Git	Download

Namespace

Add the WYVRN SDK namespace to use the API.

using WyvrnSDK;

API Class

The WyvrnAPI class provides a wrapper for the WYVRN SDK Library.

Initialize SDK

Initialize the WYVRN SDK in order to utilize the API. The InitSDK method takes an AppInfo parameter which defines the application or game details that will appear in Synapse and the Chroma App within the Chroma Apps tab. The expected return result should be RZRESULT_SUCCESS which indicates the API is ready for use. If a non-success result is returned, the WYVRN implementation should be disabled until the next time the application or game is launched. Reasons for failure are likely to be the user does not have the Synapse or the Chroma App installed. After successfully initializing the WYVRN SDK, wait approximately 100 ms before setting events.

private int _mResult = 0;

public IEnumerator Start()
{
    if (!WyvrnAPI.IsWyvrnSDKAvailable())
    {
        _mResult = RazerErrors.RZRESULT_DLL_NOT_FOUND;
        yield break;
    }

    WyvrnSDK.APPINFOTYPE appInfo = new APPINFOTYPE();
    appInfo.Title = "Razer WYVRN Unity Game Sample Application";
    appInfo.Description = "A sample application using Razer WYVRN SDK";

    appInfo.Author_Name = "Razer";
    appInfo.Author_Contact = "https://WYVRN.com";

    //    0x01 | // Utility. (To specify this is an utility application)
    //    0x02   // Game. (To specify this is a game);
    appInfo.Category = 2;

    _mResult = WyvrnAPI.CoreInitSDK(ref appInfo);
    if (_mResult == RazerErrors.RZRESULT_SUCCESS)
    {
        // Init Success! Ready to use the WYVRN SDK!
    }
    else
    {
        // Init Failed! Stop using the WYVRN SDK until the next game launch!";
    }
}

Set Event Name

Game events can be named to add supplemental technology to your lighting experience. By naming game events and game triggers, the event name can be used as a lookup to do things for AI, Chroma, and haptics. SetEventName("Jump") could be used to play a Chroma animation for the jump game event. The Jump event can also use A corresponding haptic effect to enhance emersion for the title. No other APIs are required to add Chroma and haptics other than to invoke SetEventName(). Some game events can have lighting or haptics or both. It just depends on the game design to create an experience that makes sense.

// Trigger AI, Chroma, and haptics
WyvrnAPI.CoreSetEventName("Jump");

// Stop haptic playback
WyvrnAPI.CoreSetEventName("");

The API can use event names with a fallback parameter so that if the WYVRN configuration doesn't match on the event name, an alternative event name can be used. EVENT_A;fallback=EVENT_B will search the WYVRN configuration for EVENT_A and if not matched will fallback to the EVENT_B. EVENT_A will test for matches with external commands and fallback commands before attempting a fallback for EVENT_B. If neither event matches, nothing will happen. If both fallback methods are used meaning fallback=EVENT_B is provided with SetEventName and the configuration specifies the fallback event, the result will prioritize the configuration over the SetEventName fallback.

WyvrnAPI.CoreSetEventName("EVENT_A;fallback=EVENT_B")

Hotkeys

Hotkeys light individual keyboard keys in a colour of your choice, on top of whatever Chroma animation is playing. Use them to show the player which keys matter at a given moment, such as the movement keys, an ability that is ready, or a key to press during a quick-time event, without replacing the rest of the keyboard lighting.

Add the hotkeys parameter to the event name. The event gives the colour and the parameter lists the keys. The full-colour @Idle_* events of the WYVRN Effects Library are the simplest source of colour: they are already distributed to players, so no configuration is needed.

<event>;hotkeys=<key>[,<key>...][;hotkey_cooldown=<n>]

// Light W, A, S, D in green until removed
WyvrnAPI.CoreSetEventName("@Idle_Green;hotkeys=W,A,S,D");

// Light the ability key in red for about one second
WyvrnAPI.CoreSetEventName("@Idle_Red;hotkeys=Q;hotkey_cooldown=30");

// Change the colour of a key: the new hotkey replaces the old one
WyvrnAPI.CoreSetEventName("@Idle_Yellow;hotkeys=Q");

// Remove the hotkeys from W, A, S, D
WyvrnAPI.CoreSetEventName("@Idle_Green;hotkeys=W,A,S,D;hotkey_cooldown=0");

When hotkeys is present the event is not played as a full animation. Only the listed keys take the colour of the event's keyboard animation; the other keys keep showing the animation that is playing.
Hotkeys apply to keyboards only.
A key holds one hotkey at a time. Setting a new hotkey on a key replaces the previous one, so a key can change colour by sending another @Idle_* event for it.
Parameters are separated by ;, can appear in any order and combine with fallback.
Key names are not case sensitive. Names that are not recognised are ignored.

Hotkey Colours

The main colours offered by the library. The gradient and rainbow events colour each key according to its position on the keyboard.

Event	Hotkey colour
`@Idle_Red`	Red
`@Idle_Green`	Green
`@Idle_Blue`	Blue
`@Idle_Yellow`	Yellow
`@Idle_Purple`	Purple
`@Idle_GreenBlue`	Green to blue
`@Idle_YellowRed`	Yellow to red
`@Idle_Rainbow`	Rainbow

Any other event with a keyboard animation can be used the same way, including events from a game-specific WYVRN configuration.

Hotkey Cooldown

hotkey_cooldown controls how long the hotkeys stay.

`hotkey_cooldown`	Meaning
omitted or `-1`	No expiry. The hotkeys stay until they are removed or replaced.
`0`	Removes the listed hotkeys immediately.
`N` greater than 0	Keeps the hotkeys for `N` Chroma animation frames, then removes them.

The cooldown is counted in Chroma animation frames, not in milliseconds. It decreases by one each time a playing animation, or the idle animation, advances to a new frame. Playback is 30 frames per second at most, so hotkey_cooldown=30 is about one second with a 30 FPS animation. The cooldown does not decrease while no animation is advancing.

To remove every hotkey at once, send @ClearHotkeys from the WYVRN Effects Library:

WyvrnAPI.CoreSetEventName("@ClearHotkeys");

Hotkeys Example

The keyboard idles in purple. Pressing W starts the poison effect and lights W, A, S, D in green. Releasing W stops the poison effect. Pressing S plays a kick and removes the hotkeys with hotkey_cooldown=0.

using UnityEngine;
using WyvrnSDK;

public class HotkeysExample : MonoBehaviour
{
    // Call once after CoreInitSDK succeeded (wait about 100 ms first)
    public void OnGameStart()
    {
        WyvrnAPI.CoreSetEventName("@Idle_Purple");
    }

    void Update()
    {
        if (Input.GetKeyDown(KeyCode.W))
        {
            WyvrnAPI.CoreSetEventName("@PoisonDamage_ON");
            WyvrnAPI.CoreSetEventName("@Idle_Green;hotkeys=W,A,S,D");
        }
        if (Input.GetKeyUp(KeyCode.W))
        {
            WyvrnAPI.CoreSetEventName("@PoisonDamage_OFF");
        }
        if (Input.GetKeyDown(KeyCode.S))
        {
            WyvrnAPI.CoreSetEventName("@Kick");
            WyvrnAPI.CoreSetEventName("@Idle_Green;hotkeys=W,A,S,D;hotkey_cooldown=0");
        }
    }
}

Hotkey Key Names

ESC, F1 to F12, 0 to 9, A to Z, TAB, CAPSLOCK, BACKSPACE, ENTER, SPACE, LSHIFT, RSHIFT, LCTRL, RCTRL, LALT, RALT, LWIN, RMENU, FN, UP, DOWN, LEFT, RIGHT, INSERT, DELETE, HOME, END, PAGEUP, PAGEDOWN, PRINTSCREEN, SCROLL, PAUSE, NUMLOCK, NUMPAD0 to NUMPAD9, NUMPAD_DIVIDE, NUMPAD_MULTIPLY, NUMPAD_SUBTRACT, NUMPAD_ADD, NUMPAD_ENTER, NUMPAD_DECIMAL, MACRO1 to MACRO5, OEM_1 to OEM_11, EUR_1, EUR_2, JPN_1 to JPN_5, KOR_1 to KOR_7

Generic Database

Games can provide a WYVRN configuration that SetEventName will use to find a match. If a match is not found, the system then looks at the GenericEvent WYVRN configuration to make a match. If neither the game or GenericEvent WYVRN configurations match, nothing will happen.

Fallback Commands

The WYVRN configuration includes a FallbackCommands array that uses the same schema as the ExternalCommands array. Both FallbackCommands and ExternalCommands support a Chroma_Events array and Haptic_Events array.

{
  "ExternalCommands": [
    {
      "External_Command_ID": "EXTERNAL_ID",
      "Chroma_Events": [],
      "Haptic_Events": []
    }
  ],
  "FallbackCommands": [
    {
      "External_Command_ID": "FALLBACK_ID",
      "Chroma_Events": [],
      "Haptic_Events": []
    }
  ]
}

ExternalCommands use exact string matches where FallbackCommands use regular expression matching. The .* string is a wildcard that can be used to match partial event names. The ".*FALLBACK_ID" pattern will match any string that ends with "FALLBACK_ID". The "FALLBACK_ID.*" pattern will match any string that starts with "FALLBACK_ID". The ".*FALLBACK_ID.*" pattern will match on an event name that contains the "FALLBACK_ID" string.

{
  "FallbackCommands": [
    {
      "External_Command_ID": ".*FALLBACK_ID.*"
    }
  ]
}

Uninitialize SDK

Applications should uninitialize the WYVRN SDK with Uninit() for a clean exit. Uninitialization is only needed if the WYVRN SDK was successfully initialized. The expected successful return result should be RZRESULT_SUCCESS.

if (_mResult == RazerErrors.RZRESULT_SUCCESS)
{
    int result = WyvrnAPI.CoreUnInit();
    if (result == RazerErrors.RZRESULT_SUCCESS)
    {
        // WYVRN has been uninitialized!
    }
    else
    {
        // WYVRN uninitialization was unsuccessful!
    }
}

Getting Started

Frameworks supported

Windows WyvrnSDK (32-bit)
Windows WyvrnSDK (64-bit)

Assets

A game uses SetEventName to name game triggers. No other assets need to be included in the game to add haptics and lighting effects. Playback is controlled from the external Events.config for the named events.

Full API

WYVRN SDK Library Methods:

PluginCoreInitSDK

Direct access to low level API.

// DLL Interface
EXPORT_API RZRESULT PluginCoreInitSDK(
    ChromaSDK::APPINFOTYPE* AppInfo);

// Class Plugin
int result = WyvrnAPI.CoreInitSDK(ref appInfo);

PluginCoreSetEventName

Direct access to low level API.

// DLL Interface
EXPORT_API RZRESULT PluginCoreSetEventName(LPCTSTR Name);

// Class Plugin
int result = WyvrnAPI.CoreSetEventName("Effect1");

PluginCoreUnInit

Direct access to low level API.

// DLL Interface
EXPORT_API RZRESULT PluginCoreUnInit();

// Class Plugin
int result = WyvrnAPI.CoreUnInit();

About​

Getting Started With Unity SDK​

Requirements and Setup​

Security​

General​

WYVRN SDK​

Downloads​

Namespace​

API Class​

Initialize SDK​

Set Event Name​

Hotkeys​

Hotkey Colours​

Hotkey Cooldown​

Hotkeys Example​

Hotkey Key Names​

Generic Database​

Fallback Commands​

Uninitialize SDK​

Getting Started​

Frameworks supported​

Assets​

Full API​

About

Getting Started With Unity SDK

Requirements and Setup

Security

General

WYVRN SDK

Downloads

Namespace

API Class

Initialize SDK

Set Event Name

Hotkeys

Hotkey Colours

Hotkey Cooldown

Hotkeys Example

Hotkey Key Names

Generic Database

Fallback Commands

Uninitialize SDK

Getting Started

Frameworks supported

Assets

Full API