WYVRN Haptics Configuration

WYVRN 設定は、ハプティクス効果の再生をサポートしています。ハプティクス効果ファイル（.haps）には、Razer Sensa HD Haptics デバイスでハプティクスを再生するためのデータが含まれています。

ツール

WYVRN フォルダーのハプティクス部分を作成するための主なツールは次のとおりです：

Haptic Composer：ハプティクスファイルの作成およびデザインを行うツール。
Synesthesia アプリ：WYVRN SDK の API 呼び出しをインターセプトするデバッグコンソール（InitSDK、SetEventName、UninitSDK。それらは、Synesthesia アプリ上でそれぞれ load、play、unload として表示されます）。

Haptic Composer は、複数のプラットフォームやデバイスに展開できる高精細なハプティクス体験を作成するための強力なデザインツールです。直感的なグラフィカルインターフェースを備えており、タイムラインベースのワークフローにより、ハプティクス効果の作成、編集、テストを行うことができます。

Synesthesia Console は、ゲーム統合用の WYVRN（Chroma - ハプティクス）設定を非常に簡単に作成できるツールです。Synesthesia エンジンは、WYVRN に対応したゲームを各種 Razer Chroma RGB デバイスおよび Sensa ハプティクスデバイスと統合し、ゲーム内イベントに基づいたダイナミックな Chroma とハプティクスの連動による同期型のゲーム体験を提供します。Synesthesia Console は以下のリンクからダウンロードできます：https://github.com/WyvrnOfficial/RazerSensa_DevKit/tree/master

Synesthesia Console アプリは、このリポジトリ内の ReleaseConsole フォルダーにあります。コンソール版は、テストおよび QA 用として提供されています。HapticFolders は、Synesthesia アプリのフォルダー内にも含まれています。このフォルダーの最新バージョンは、Razer Chroma が Razer Synapse 4 とともにインストールされている場合、C:\Program Files (x86)\Interhaptics\HapticFolders に配置されます。

本番版 Synesthesia の代わりにコンソール版（Synapse/Chroma 4 に HapticService バックグラウンドサービスとして含まれる）を使用するには、以下の手順に従ってください。

Razer Chroma を開き、Sensa HD Haptics タブに移動します. Haptic Source が「Sensa HD Games」であることを確認してください。もし「Audio-to-Haptics」になっている場合は「Sensa HD Games」に切り替えます。

Razer Chroma Sensa HD Haptics tab

タスクマネージャーを開き、Haptic Service のバックグラウンドプロセスが動作しているか確認し、動作中なら終了します。

Haptic Service Background Process

Synesthesia アプリを開き(こちらでダウンロード)、WYVRNFakeClient、または任意の WYVRN 対応ゲーム（例：Marvel Rivals）を使用してセットアップをテストします。アプリを起動すると、load、active、play の各コマンドが表示されます。

アプリケーションが起動し Chroma を初期化すると、ハプティクス設定ファイルを load するコマンドが送信されます。SetEventName WYVRN API が呼び出されると、play コマンドが送信されます。

例:

Command Received: "load;Marvel Rivals"
Command Received: "play;Effect1"
...
Command Received: "unload;Marvel Rivals"

ハプティックフォルダーとファイル

ハプティックアセットを管理するために特定のフォルダー構造が使用されます。各ゲームまたはアプリケーションには<Game_ID>で命名された専用フォルダーが用意されており、その中にハプティクスおよび Chroma エフェクトに必要なすべてのファイルが格納されます。

ハプティックフォルダー（Haptic Folder）: フォルダー名が外部コマンドで使用される Game_ID として扱われます。
設定ファイル（Configuration File）: 各ハプティクスフォルダーには、拡張子が .config の設定ファイルを 1 つ含める必要があります。このファイルは JSON 形式で構成されており、外部コマンド ID と対応するハプティクス／Chroma イベントの紐付けを定義します。
ハプティックおよび Chroma ファイル: これらのファイルの拡張子は、それぞれ .haps と .chroma です。これらにはハプティクスまたは Chroma のエフェクトデータが含まれており、Haptic Composer または Chroma Studio を使用して作成されます。これらのファイルは .config ファイルを介してトリガーされます。

外部コマンド

Synesthesia プロセスとの通信は、セミコロン区切りのシンプルなコマンド群を通じて行われます。これにより、ゲームはハプティクスエフェクトを動的にロード／再生／停止できます。

コマンドの一般的な形式は次のとおりです： [COMMAND ID];[ARGUMENT_1];[ARGUMENT_2]

ハプティクス制御に使用できる主要なコマンドは 4 種類です：

コマンド	コマンド ID	引数 1	引数 2
ゲームのハプティクスエフェクトをロード	`load`	Game_ID
ゲームのハプティクスエフェクトをアンロード	`unload`	Game_ID
ハプティクスイベントを再生	`play`	Game_ID	External_Command_ID
ハプティクスイベントを停止	`stop`	Game_ID	External_Command_ID

Load

load コマンドは、ゲームのすべてのハプティクスエフェクトを事前にロードし、初回トリガー時の実行時遅延を防ぎます。ゲーム起動時に呼び出す必要があります。 load;[Game_ID]

Unload

unload コマンドは、ゲームのハプティクスエフェクトをアンロードしてリソースを解放するために使用します。ゲーム終了時、またはユーザーがそのゲームから離れる際に呼び出す必要があります。 unload;[Game_ID]

Play

play コマンドは、ゲームの .config ファイルで定義された特定のハプティクスイベントをトリガーします。該当ゲームの設定がまだロードされていない場合、システムは先にそれをロードします。 play;[Game_ID];[External_Command_ID]

Stop

stop コマンドは、ハプティクスイベントを停止します。挙動は指定する引数によって異なります：

stop;[Game_ID];[External_Command_ID]: 指定したゲームの指定イベントを停止します。
stop;[Game_ID]: そのゲームに関連して現在再生中のハプティクスエフェクトをすべて停止します。
stop;: すべてのデバイス上で、すべてのゲームのハプティクスエフェクトを停止します。

設定ファイル

.config ファイルは JSON ファイルであり、ゲームのハプティクス統合の中核として機能します。ゲームから送信される External_Command_ID を、1 つ以上のハプティクスイベントにマッピングします。

ExternalCommands

ExternalCommands 配列は設定の主要コンポーネントです。各エントリは、ゲーム側の External_Command_ID を、対応する Haptic_Events のセットに紐付けます。

例:

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

Haptic_Events　プロパティ

各ハプティックイベントは、再生動作を制御する複数のプロパティによってカスタマイズできます。

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

Haptic_Effect: 再生する .haps ファイルの名前（拡張子なし）を指定します。
Loop: エフェクトを再生する回数を指定します。特定の回数を指定する場合は整数を使用し、無限ループにする場合は "infinity" を指定します。デフォルトは 1 です。
Priority: 複数のイベントが同時にアクティブな場合、どのイベントを優先的に再生するかを制御します。最も優先度の高いイベントのみが再生されます。利用可能なレベルは VeryHigh、High、 Medium (既定)、 Low、 VeryLowです。
Mixing: 同じ優先度のイベントが同時にアクティブな場合の動作を制御します。既定値の Override Mergeは、他のエフェクトと同時再生を許可します。
Targeting: エフェクトをどの部位に、どのような修正を加えて適用するかを配列形式で指定します。

Targeting　プロパティ

Targeting オブジェクトは、ハプティクスエフェクトを「どこに」「どのように」適用するかを定義します。

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

Target: エフェクトを送信する身体部位（複数も可能）を指定します。利用可能なターゲットには All、Arm、Hand、Leg、Foot、Chest などがあります。親グループ（例：Arm）を指定するとそのサブグループ（Upper_arm、Lower_arm、Hand）も同時に有効になります。
Spatialization: エフェクトの位置を設定します。Left、Right、または既定値の Global を指定できます。
Gain: エフェクトの強度に適用する正規化された倍率です。0（0%）から 1（100%）の範囲で指定し、既定値は 1 です。

高度な割り込み制御

InterruptCommands と Groups を使用することで、エフェクト間の複雑な相互作用を管理できます。

InterruptCommands：ExternalCommand オブジェクト内に配置されるプロパティで、このコマンドがトリガーされた際に即座に停止すべき他の External_Command_ID を一覧で指定します。
Groups：Groups 機能を使用すると、複数の External_Command_ID を 1 つのグループ ID の下にまとめることができます。このグループ ID は InterruptCommands のリスト内で使用できるため、特定カテゴリのエフェクトをまとめて停止することが容易になります。

Groups と InterruptCommands の使用例：

{
"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)

WYVRN 設定は、ハプティクスと Chroma の両方に適用されるフォールバックおよびエイリアスにより、さらなる柔軟性を提供します。

SetEventName フォールバック：API 呼び出し自体にフォールバックを含めることができます。SetEventName("EVENT_A;fallback=EVENT_B") は、まず EVENT_A を検索し、一致するものが見つからない場合は EVENT_B を検索します。

全体構造

{
    "$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 interruptCommand",
            "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"
            }
        }
    }
}

設定ファイル – Group

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

外部コマンド – サブ構造

{
    "$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"
            },
            "InteruptCommands": { 
                "description": "List commands to trigger, must match existing External_Command_ID", 
                "OneOf": [
                    {
         "type": "enum",
         "enum": ["All"] 
     }, 
     { 
         "type": "array", 
         "items": {"type": “string"} 
                    }
                ]
            }
        }
    }
}

ハプティクスイベント – サブ構造

{
    "$schema": "http://json-schema.org/draft-04/schema",
    "title": "Synesthesia.HapticEvent",
    "description": "a link between an external command and haptic events",
    "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 a negative value or “infinity” for a infinity loop.",
            "type": “integer“ (or “infinity”) 
            "default" : 1
        },

        "Targeting": {
            "description": "List of targets to deploy the effect",
            "type": "array",
            "items": {
                "type": "object",
                "$ref": "Synesthesia.Targeting.schema.json"
            }
        }
    }
}

ターゲティングデータ — Target Enum 完全版

グループをターゲットにすると、指定されたグループにラベル付けされたすべてのデバイスでエフェクトが再生されます。一部のグループは複数のサブグループを組み合わせたものであり、すべてのサブグループも同時に有効になります（例：Leg は Upper_leg と 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	第2趾
Middle_toe	第3趾
Ring_toe	第4趾
Pinky_toe	第5趾
First	第1
Second	第2
Third	第3

ツール​

ハプティックフォルダーとファイル​

外部コマンド​

Load​

Unload​

Play​

Stop​

設定ファイル​

ExternalCommands​

Haptic_Events プロパティ​

Targeting プロパティ​

高度な割り込み制御​

フォールバックコマンド (Fallback Commands)​

全体構造​

設定ファイル – Group​

外部コマンド – サブ構造​

ハプティクスイベント – サブ構造​

ターゲティングデータ — Target Enum 完全版​

ツール