WYVRN Haptics Configuration

The WYVRN configuration supports haptic effect playback. Haptic effect files (.haps) contain the data for playing haptics on Razer Sensa HD Haptics devices.

How It Works

The game does not send haptic data. It names events through the WYVRN SDK, and the Haptic Service (installed with Razer Synapse 4 / Razer Chroma) plays the matching effects:

1. The game calls InitSDK. The Haptic Service loads the haptic folder whose name matches the application title.
2. The game calls SetEventName. The Haptic Service looks the event name up in the folder's .config file and plays the haptic events mapped to it.
3. The game calls UninitSDK. The Haptic Service unloads the folder.

WYVRN SDK call	Haptic Service event	Effect
InitSDK	load	Pre-loads all haptic effects of the game, so the first playback has no delay.
SetEventName("EVENT")	play	Plays the haptic events mapped to EVENT in the .config file.
SetEventName("")	stop	Stops the haptic effects of the game.
UninitSDK	unload	Frees the game's haptic effects.

These events can be watched live in the Haptic Service Dashboard.

Tools

• Haptic Composer: design tool for creating and editing the .haps haptic effect files through a timeline-based workflow.
• WYVRN Configuration Editor: editor for the .config file.
• Haptic Service Dashboard: local debug interface showing the events received from the WYVRN SDK, the loaded configurations, the connected devices and the service logs.

Setup

1. Install Razer Synapse 4 with the Chroma option enabled.
2. Open Razer Chroma and open the Sensa HD Haptics tab. Check that Haptic Source is Sensa HD Games. If it is Audio-to-Haptics, switch it to Sensa HD Games.

3. Check that the game is switched on in the Chroma Apps list.

Example haptic folders, including a Game Sample Application folder for WYVRN developers, are available in the Razer Sensa DevKit repository.

Haptic Folders and Files

Each game or application has a dedicated haptic folder which contains all the files for its haptic and Chroma effects. The folders are located in:

C:\Program Files (x86)\Interhaptics\HapticFolders\<Game_ID>\

• Haptic Folder: the folder name is the Game_ID. It must match the application title the game registers with in InitSDK.
• Configuration File: each haptic folder must contain a single configuration file with a .config extension (for example Wyvrn.config). This JSON file links the event names sent by the game to haptic and Chroma events.
• Haptic and Chroma Files: files with .haps and .chroma extensions, created with the Haptic Composer or Chroma Studio. They are triggered through the .config file.

Copying the folder to this location is enough; there is no separate registration step.

Configuration File

The .config file is a JSON file that acts as the brain for your game's haptic integration. It maps the External_Command_ID sent from the game to one or more haptic events.

ExternalCommands

The ExternalCommands array is the primary component of the configuration. Each entry links an External_Command_ID from the game to a corresponding set of Haptic_Events.

Example:

{
  "ExternalCommands": [
    {
      "External_Command_ID": "PlayerRunning",
      "Haptic_Events": [
        ...
      ]
    }
  ]
}

Haptic Event Properties

Each haptic event can be customized with several properties that control its playback behavior.

{
  "Haptic_Effect": "footsteps",
  "Mixing": "Merge",
  "Priority": "Medium",
  "Loop": -1,
  "Targeting": [
    ...
  ]
}

• Haptic_Effect: The name of the .haps file to play (without the extension).
• Loop: The number of times the effect should be played. Only integer values are accepted: use a positive integer for a specific count or -1 for an endless loop. The default is 1.
• Priority: Determines which effects are rendered when multiple events are active. Only the event with the highest priority will play. The levels are VeryHigh, High, Medium (default), Low, and VeryLow.
• Mixing: Used when two events of the same priority are active. Override (default) stops all other effects on the target, while Merge allows both to play simultaneously.
• Targeting: An array specifying which body parts should play the effect and with what modifications.

Targeting Properties

The Targeting object defines where and how a haptic effect is applied.

{
  "Target": "Leg",
  "Spatialization": "Global",
  "Gain": 0.5
}

• Target: The body part(s) to send the effect to. The available targets are extensive, including All, Arm, Hand, Leg, Foot, Chest, and more. Targeting a parent group (e.g., Arm) will also activate its subgroups (Upper_arm, Lower_arm, Hand).
• Spatialization: Sets the position of the effect. Can be Left, Right, or Global (default).
• Gain: A normalized multiplier for the effect's intensity, from 0 (0%) to 1 (100%). The default is 1.

Advanced Interruption Control

You can manage complex interactions between effects using Interrupts_Commands and Groups.

• Interrupts_Commands: This property, placed within an ExternalCommand object, lists other External_Command_IDs that should be stopped immediately when this command is triggered.
• Groups: The Groups feature allows you to bundle multiple External_Command_IDs under a single group ID. This group ID can then be used in an Interrupts_Commands list, making it easy to stop a whole category of effects at once.

Example of using Groups and Interrupts_Commands:

{
  "Groups": [
    {
      "ID": "AllMotor",
      "Members": [
        "Engine_Start",
        "MotorRPM_Heavy",
        "MotorRPM_Light",
        "MotorRPM_Medium"
      ]
    }
  ],
  "ExternalCommands": [
    {
      "External_Command_ID": "Engine_Stop",
      "Interrupts_Commands": [
        "AllMotor"
      ],
      "Haptic_Events": [...]
    }
  ]
}

Fallback Commands

The WYVRN configuration provides additional flexibility through fallbacks and aliases, which apply to both haptics and Chroma.

• SetEventName Fallback: The API call itself can include a fallback. SetEventName("EVENT_A;fallback=EVENT_B") will first search for EVENT_A, and if no match is found, it will then search for EVENT_B.

Configuration File - General Structure

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "Synesthesia.GameConfiguration",
    "description": "List links between external commands and haptic events",
    "type": "object",
    "properties": {
        "Groups": {
            "description": "Group of externalCommand you can re-use in Interrupts_Commands",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "Synesthesia.Groups.schema.json"
            }
        },
        "ExternalCommands": {
            "description": "List of links between external commands and haptic events",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "Synesthesia.ExternalCommand.schema.json"
            }
        }
    }
}

Configuration File - Group

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "Synesthesia.Groups",
    "description": "Group of externalCommand you can re-use in Interrupts_Commands",
    "type": "object",
    "properties": {
        "ID": {
            "description": "ID of the group you can use in Interrupts_Commands",
            "type": "string"
        },
        "Members": {
            "description": "List of the actual External_Command_ID contained in the group",
            "type": "array",
            "items": {
                "type": "string"
            }
        }
    }
}

External Command - Substructure

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "Synesthesia.ExternalCommand",
    "description": "a link between an external command and haptic events",
    "type": "object",
    "properties": {
        "External_Command_ID": {
            "description": "External command ID that will trigger the following haptic events",
            "type": "string"
        },
        "Haptic_Events": {
            "description": "List of haptic events to triggers",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "Synesthesia.HapticEvent.schema.json"
            }
        },
        "Interrupts_Commands": {
            "description": "List commands to interrupt, must match existing External_Command_ID or group ID",
            "oneOf": [
                {
                    "type": "string",
                    "enum": ["All"]
                },
                {
                    "type": "array",
                    "items": { "type": "string" }
                }
            ]
        }
    }
}

Haptic Event - Substructure

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "Synesthesia.HapticEvent",
    "description": "a haptic event triggered by an external command",
    "type": "object",
    "properties": {
        "Haptic_Effect": {
            "description": "Name of the haptic effect to play. Should be the same as the related .haps file",
            "type": "string"
        },
        "Mixing": {
            "description": "Used mixing strategy for this event. Override will stop all haptic events on the given targets before playing",
            "type": "string",
            "enum": ["Override", "Merge"],
            "default": "Override"
        },
        "Priority": {
            "description": "Priority of this event. Only the event with the higher priority are rendered, even before looking at mixing strategy.",
            "type": "string",
            "enum": ["VeryLow", "Low", "Medium", "High", "VeryHigh"],
            "default": "Medium"
        },
        "Loop": {
            "description": "Number of time the effect must be played. Use -1 for an infinite loop.",
            "type": "integer",
            "default": 1
        },
        "Targeting": {
            "description": "List of targets to deploy the effect",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "Synesthesia.Targeting.schema.json"
            }
        }
    }
}

Targeting Data - Target Enum Complete

Targeting a group will play an effect on all devices labelled in the given groups. Some groups are a combination of multiple ones and will activate all subgroups (for example Leg will activate Upper_leg and Lower_leg).

All, Top, Down, Arm, Head, Chest, Waist, Leg, Upper_arm, Lower_arm, Hand, Skull, Neck, Upper_leg, Lower_leg, Foot, Palm, Finger, Sole, Toe, Thumb, Index, Middle, Ring, Pinky, Hallux, Index_toe, Middle_toe, Ring_toe, Pinky_toe, First, Second, Third

Haptic Service Dashboard

The Haptic Service Dashboard is a web interface built into the Haptic Service. It runs locally and shows what the service receives from the WYVRN SDK and what it plays.

caution

The dashboard is a diagnostic and integration tool. Do not enable it on end-user machines and disable it when it is not needed.

Enabling the Dashboard

From an elevated command prompt, in the folder containing HapticService.exe (C:\Program Files (x86)\Interhaptics\HapticService):

HapticService.exe enabledashboard

Restart the Haptic Service so the change takes effect:

HapticService.exe restart

Then open http://localhost:8787 in a browser. To disable it:

HapticService.exe disabledashboard

The dashboard only binds to the local machine (127.0.0.1) and cannot be reached from another computer. To use another port, create a file named debug.flag next to HapticService.exe containing the line port=<number> (1 to 65535), then restart the service with HapticService.exe restart.

Checking an Integration

The header shows the connection status (Live, Connecting… or Reconnecting…). The control bar starts, stops and restarts the service and its subsystems, and enables or disables the logs. Tables refresh every two seconds.

Event Log tab: live stream of the service logs. Launch the game and check that a load appears at InitSDK and a play at each SetEventName.

• Filter by level (INFO, WARN, ERROR), by subsystem tag, or by text search.
• Export TXT saves the visible rows to a haptic-service-<timestamp>.txt file to attach to a bug report.
• If the log is empty, press Enable in the Logs group of the control bar.

Synesthesia tab: the event engine view.

• Active Game is the game whose configuration is currently loaded.
• Loaded Games lists every game configuration in memory with its number of events, plus the Generic Library available to any game. Click a game to list its events. Use it to check that the haptic folder was found and that the .config file declares the expected events.
• Send Command triggers an event without running the game. Click an event to pre-fill the payload, then press Enter or Send:

{"eventType":"play","gameName":"MyGame","eventID":"footstep"}

A game does not need to be running to test its events. The example below sends the Start event of Marvel Rivals:

Field	Required	Description
eventType	Yes	play, stop, load, etc.
gameName	No	Target game (Game_ID). Omit for generic events.
eventID	No	Event identifier (External_Command_ID).
gamePID	No	Scopes the event to a specific running game instance.

Haptic Mixer tab: what is being rendered.

• Type Volumes: master volumes for Audio to Haptics, Synesthesia (haptics triggered by game events) and Native (titles integrating directly with the SDK).
• Programs: programs producing haptic commands, with mute, volume and Last Buffer (how long ago the program last sent haptics).
• Devices: detected haptic devices, with a per-device volume and a Report button showing the full device report.

Troubleshooting

Symptom	What to try
Dashboard does not load at http://localhost:8787	The dashboard is not enabled, or a debug.flag file overrides the port. Run HapticService.exe enabledashboard from an elevated prompt, then HapticService.exe restart.
Header shows Reconnecting…	The service is stopped or restarting. Check that HapticService is running in services.msc.
Event Log is empty	Logs are disabled. Press Enable in the Logs group.
No load when the game starts	Check that the game is switched on in the Chroma Apps list and that the haptic folder name matches the application title.
play is received but nothing is felt	Check that the event is listed for the game in the Synesthesia tab, that Haptic Source is Sensa HD Games, and the mute and volumes in the Haptic Mixer tab.
A device does not appear in Devices	Check that it is connected and powered, then restart the Haptic Mixer from the control bar.