VRChat 非公式日本語ドキュメント

Contacts

Contactsは、アバターやワールドが他のContactsとの衝突を検知するためのシステムです。この衝突を利用して、アバターやワールドの挙動を制御し、あらゆる種類のカスタムインタラクションを実行できます。

これらは通常のUnityのコライダーとは別物です。ContactsはSender（送信側）とReceiver（受信側）に分かれています。Senderは検知されるために存在し、ReceiverはSenderを検知して、それに応じてパラメータを更新したりイベントを発生させたりします。

アバターでContactsを使用する場合、使用するContactsの数はアバターのパフォーマンスランクに影響します。

VRCContactSender

Contact Senderコンポーネントは、Contact Receiverと接触した際にContact信号を送信する空間領域を定義します。

  • Root Transform - このContactを配置するTransformです。空の場合、このGameObjectのTransformが使用されます。

Shape

このセクションには、ContactSenderの形状を定義する設定が含まれています。

  • Shape Type - このコンタクトで使用する衝突判定の形状タイプ。SphereとCapsuleから選択できます。
  • Radius - 原点から広がるコライダーのサイズ。
  • Height - Y軸に沿ったカプセルの高さ。両端の半球部分を含みます。Shape TypeがCapsuleに設定されている場合のみ使用されます。
  • Position - ルートトランスフォームからの位置オフセット。
  • Rotation - ルートトランスフォームからの回転オフセット。

コンタクト形状は、半径最大3メートル、高さ最大6メートルに制限されています。コンタクトがスケーリングされたゲームオブジェクトにアタッチされている場合、これらの制限はスケーリングが適用された後に計算されます。

フィルタリング

このセクションには、このContactSenderがContactReceiversとどのように相互作用するかを調整・定義するための設定が含まれています。

  • Local Only - アバター上のContactSenderでのみ利用可能です。このコンタクトの動作をローカルクライアントのみに限定します。これを有効にすると、このコンタクトはアバターのパフォーマンスランクに影響を与えません。
  • Content Types - ワールド内のContact Senderでのみ利用可能です。このContact Senderが、ワールド内、アバター上、あるいはアイテム上のどのContact Receiverをトリガーするかを設定できます。
  • Collision Tags - 何に影響を与えるか、あるいは何から影響を受けるかを指定する文字列のリストです。コリジョンを発生させるには、SenderとReceiverの両方に一致するタグが少なくとも1つ必要です。Collision tagsは大文字と小文字を区別します。1つのContactには最大16個のタグを設定できます。

例として、以下のタグを設定すると、デフォルトの頭部の ContactReceiver、または Face というタグを持つカスタムの ContactReceiver に接触した際に、Senderがコンタクト信号を送信するようになります。Fが大文字であることに注意してください！

タグには任意のテキストを使用できますが、SDKには推奨タグのリストも用意されています。これを使用することで、自分が作成していないアバターやワールドとも連携できるコンタクトシステムを簡単に構築できます。詳細については、Built-In Contact Tagsを参照してください。

カスタムコリジョンタグを使用する場合、組み込みタグの形式に合わせてPascalCaseで記述することをお勧めします。

Standard Colliders

アバターの「Standard Colliders」は、Avatar Descriptor内の「Colliders」セクションで定義されます。このセクションでは、すべてのアバターに存在する標準的なコライダーを定義できます。特に設定を変更しなければ自動的にセットアップされますが、自身のアバターに合わせて微調整することも可能です。なお、これらのコライダーはパフォーマンス評価には影響しません。

  • Head
  • Torso
  • Hands L/R
  • Feet L/R
  • Fingers L/R
    • Index
    • Middle
    • Ring
    • Little

これらのコライダーは、主に他の人が自分のアバターで検知できる組み込みのボディパーツタグを使用したContact Senderとして機能します。しかし、指や手のコライダーは、他の人のPhysBoneやワールド内のPhysBoneに影響を与えるためのグローバルなPhysBoneコライダーを作成する際にも使用されます。

VRCContactReceiver

Contact Receiverコンポーネントは、Contact Senderと接触した際にContact信号を受信する空間のボリュームを定義します。

  • Root Transform - このコンタクトが配置されるTransformです。空の場合、このGameObjectのTransformが使用されます。

Contact ReceiverがContact Senderから信号を受信したときの動作は、そのContact Receiverが何に属しているかによって決まります。

  • Contact Receiverがアバターの一部である場合、アバター制作者の定義に従ってAnimator Parameterを設定します。
  • Contact Receiverがワールドの一部である場合、代わりにReceiverと同じGameObjectにアタッチされたすべてのUdonビヘイビアに対して、以下のいずれかのイベントがトリガーされます。
    • OnContactEnter(ContactEnterInfo contactInfo) - Contact SenderがContact Receiverに接触を開始したときに発生するイベント。
    • OnContactExit(ContactExitInfo info) - Contact SenderがContact Receiverとの接触を終了したときに発生するイベント。

Shape

このセクションには、ContactReceiverの形状を定義する設定が含まれています。

  • Shape Type - このコンタクトで使用される衝突形状のタイプ。
  • Radius - 原点から広がるコライダーのサイズ。
  • Height - 両端の半球体を含む、Y軸に沿ったカプセルの高さ。Shape TypeがCapsuleに設定されている場合のみ使用されます。
  • Position - ルートトランスフォームからの位置オフセット。
  • Rotation - ルートトランスフォームからの回転オフセット。

Contactシェイプには、最大半径3メートル、最大高さ6メートルという制限があります。スケールが適用されたゲームオブジェクトにContactが取り付けられている場合、これらの制限はスケール適用後に計算されます。

フィルタリング

このセクションでは、このContactReceiverがどのようにContactSenderと相互作用するかを調整および定義するための設定を行います。

  • Allow Self - アバター上のContactReceiverでのみ利用可能です。自分自身によるContactSenderの検知を許可します。
  • Allow Others - アバター上のContactReceiverでのみ利用可能です。他のプレイヤーによるContactSenderの検知を許可します。
  • Local Only - アバター上のContactReceiverでのみ利用可能です。このContactをローカルクライアントでのみ動作するように制限します。有効にすると、このContactはアバターのパフォーマンスランクを低下させません。
    • このオプションを有効にすることで、1体のアバターにつき最大256個のContactコンポーネントを使用できます。この制限を超えると、アバターをアップロードできません。
  • Content Types - ワールド内のContact Receiverでのみ利用可能です。このContact Receiverがワールド、アバター、またはアイテム内のContact Receiverをトリガーするかどうかを設定できます。
  • Collision Tags - 相互作用の対象となる、または対象とする文字列のリストです。衝突を成功させるには、SenderとReceiverの両方に一致する文字列のペアが少なくとも1つ必要です。Collision tagsは、大文字と小文字が区別されます。1つのContactには最大16個のタグを設定できます。

Receiver

このセクションには、信号を受信した際にReceiverがどのように動作するかを定義する設定項目が含まれています。

アバター上のReceiver

アバター上で使用する場合、Contact Receiverは信号を受信すると、アバターのAnimatorにあるAnimator Parameterを設定することで反応します。

Receiver Typeは、信号を受信した際のパラメータ設定の挙動を定義します。

  • Constant - コンタクトが存在している間、常に通知します。コンタクトが検知されなくなるとリセットされます。基本的にはboolパラメータの使用を推奨します。Float型には1.0、Bool型にはTrue、Int型には1を設定します。
  • OnEnter - コンタクトが検知されたフレームにのみ通知します。次のフレームですぐにリセットされます。基本的にはboolパラメータの使用を推奨します。Float型には1.0、Bool型にはTrue、Int型には1を設定します。オプションでMin Velocityを設定できます。
  • Proximity - コンタクトがトリガーの中心にどれだけ近いかに応じて、0.0-1.0のFloat値を返します。これはSenderからReceiverまでの最短距離として計算されます。必ずFloat型を使用してください。複数のコンタクトが検知された場合は、最も近いものの値が返されます。
  • Parameter - Animation Controllerで更新されるパラメータです。このパラメータは、同期されるAvatar Parameterリスト上で定義する必要はありません。使用するReceiver Typeに応じて、Float型、Bool型、またはInt型を選択できます。
  • Value - 衝突が検知された際にパラメータが更新される値です。衝突がない状態になると、パラメータは0にリセットされます。
  • Min Velocity - このトリガーに影響を与えるために必要な、入力コライダーの最小速度です。OnEnterタイプでのみ有効です。

ワールド内のレシーバー

ワールド内のContact Receiverコンポーネントには、設定項目はありません。その代わり、Receiverは常にContact信号に応答し、Receiverと同じGameObjectにアタッチされたUdonスクリプト内のイベントを呼び出します。Udonを使用してContactを操作する方法については、以下のセクションを参照してください。

ワールドにおけるUdonアクセス

  • VRCContactSenderおよびVRCContactReceiver型を使用して、ワールド内のContact SenderやContact Receiverを参照するフィールドや変数を作成できます。これらのクラスは両方ともVRC.SDK3.Dynamics.Contact.Components名前空間にあります。ContactEnterInfoおよびContactExitInfo引数型はVRC.Dynamics名前空間にあります。
  • Contact SenderとContact Receiverが接触したことを検知するには、Contact Receiverコンポーネントと同じゲームオブジェクトにUdonGraphまたはUdonSharpのビヘイビアをアタッチし、以下のイベントを使用します。
    • OnContactEnter(ContactEnterInfo contactInfo) - Contact SenderがContact Receiverに接触し始めた時に呼び出されます。引数には、接触に関する以下の情報を含むデータ構造が渡されます。
      • ContactSenderProxy contactSender - この衝突に関与したContact Senderコンポーネントへの参照。
      • ContactReceiverProxy contactReceiver - この衝突に関与したContact Receiverコンポーネントへの参照。
      • Vector3 enterVelocity - 接触地点における、Contact Receiverに対するContact Senderの相対速度。
      • Vector3 contactPoint - Contact Receiverの表面における接触地点の推定位置（ワールド空間）。
      • string[] matchingTags - Contact SenderとContact Receiverで共通するタグの配列。
    • OnContactExit(ContactExitInfo contactInfo) - Contact SenderがContact Receiverから離れた時に呼び出されます。enterイベントと同様に、引数には衝突に関する情報を持つデータ構造が渡されます。
      • ContactSenderProxy contactSender - この衝突に関与したContact Senderコンポーネントへの参照。
      • ContactReceiverProxy contactReceiver - この衝突に関与したContact Receiverコンポーネントへの参照。
      • string[] matchingTags - Contact SenderとContact Receiverで共通するタグの配列。
  • 上記の各イベントにおいて、contactSenderとcontactReceiverは、衝突に関与したContact SenderおよびContact Receiverを参照するproxy_オブジェクトです。==または!=を使用して2つのオブジェクトを比較することで、それらがワールド内のVRCContactSenderまたはVRCContactReceiverと一致するかどうかを確認できます。proxy_オブジェクト自体には、以下のプロパティが含まれています。
    • bool isValid - このproxy_オブジェクトが有効なContactコンポーネントを参照している場合はtrue、そうでない場合はfalseを返します。他のプロパティにアクセスする前に、これがtrueであることを確認する必要があります。
    • VRCPlayerApi player - 該当する場合、そのContactコンポーネントを所有するプレイヤーへの参照です。ワールド内のContactコンポーネントの場合、この値はnullになります。
    • DynamicsUsage usage - Contactコンポーネントがどのようなコンテンツに属しているかを示します。ワールドの一部であるContactの場合はWorld、アバターの一部である場合はAvatarとなります。
    • Vector3 position - Contactコンポーネントのルートトランスフォームのワールド空間における位置です。
    • Quaternion rotation - Contactコンポーネントのルートトランスフォームのワールド空間における回転です。
    • Vector3 scale - Contactコンポーネントのルートトランスフォームのlossy scale（グローバルスケール）です。
  • Contact SenderやContact Receiverのradius、height、position、rotationといったプロパティは、各フィールドを取得・設定することで読み取りや変更が可能です。
    • これらのプロパティを変更した場合は、すべての変更を終えた後に必ずContactのApplyConfigurationChanges()を呼び出してください。呼び出さない場合、変更内容はContactに反映されません。
    • Contactの設定変更は負荷が高くなる可能性があります！ 頻繁に行うとワールドのパフォーマンスが低下し、プレイヤーにとって快適な環境を損なう恐れがあります。これらのプロパティを頻繁に変更することは避け、適用前には可能な限り変更をまとめて実行するようにしてください。
  • ReceiverのCalculateProximity()メソッドを使用すると、いつでもReceiverとSenderの間の近接度を計算できます。このメソッドは、SenderがReceiverの中心にどれだけ近いかを示す0.0-1.0の浮動小数点値を返します。
  • Contactで許可されるコンテンツタイプやコリジョンタグのセットは、UpdateContentTypes(DynamicsUsageFlags newContentTypes)メソッドやUpdateCollisionTags(string[] newCollisionTags)メソッドを使用して変更できます。
    • Contactには16個までのタグという上限があることに注意してください。16個を超えるタグを設定しようとした場合、最初の16個のみが適用されます。

最終更新: