Constraints API

このページでは、VRChat Constraintsのアプリケーションプログラマー向けインターフェースについて説明します。ワールド開発におけるUdonや、SDKツール開発におけるC#から利用可能な、公開されているプロパティおよびメソッドが含まれています。

要件

このAPIを使用する前に、VRChat Constraintsの基本的な概念を理解しておく必要があります。

このページに記載されていないプロパティやメソッドは、将来的に公開インターフェースから削除される可能性があるため、使用は避けてください。

コンストレイントの種類

このAPIは、VRChat Constraints向けに以下のユーザー向け型を提供しており、すべて VRC.SDK3.Dynamics.Constraint.Components 名前空間に含まれています。

• VRCAimConstraint
• VRCLookAtConstraint
• VRCParentConstraint
• VRCPositionConstraint
• VRCRotationConstraint
• VRCScaleConstraint

VRC.Dynamics 名前空間には、以下のサポートクラスも含まれています：

• VRCConstraintSource - SourceTransform と Weight を保持する、単一のコンストレイントソースです。
• VRCConstraintSourceKeyableList - コンストレイントによって使用されるソースのリストです。

コンストレイントのプロパティとメソッド

汎用プロパティとメソッド

すべてのVRChatコンストレイントは、以下に記載するプロパティを公開しています。これらは基本的にUnity constraintsで利用可能なプロパティと同じものですが、注意点として、これら2つのインターフェースは同一ではなく、VRChatクライアントの動作をサポートするための構造的な違いがいくつか存在します。

ApplyConfigurationChanges()

このメソッドは、スクリプトを介してコンストレイントに加えられた変更を適用します。スクリプトでコンストレイントのプロパティを変更した後は、必ずこのメソッドを呼び出してください！そうしないと、変更内容がコンストレイントに反映されない可能性があります。

複数のプロパティを同時に変更する必要がある場合は、パフォーマンスへの影響を最小限に抑えるため、すべての変更を行った後にこのメソッドを一度だけ呼び出すようにしてください。

IsActive

• bool: true であればコンストレイントは現在評価中であり、false であれば評価されていません。

機能的には Unity の constraintActive プロパティと同一です。

GlobalWeight

• float: このコンストレイントのグローバルウェイトです。すべてのソース（それぞれ個別のウェイトを持ちます）に対して上乗せされる形で適用されます。

機能的には Unity の weight プロパティと同一です。

Locked

• bool: true であればコンストレイントは現在ロックされており、 false であればロック解除されています。

Unityの locked プロパティと機能的に同一です。

コンストレイントはプレイモード中、常にロックされた状態として扱われます。

Sources

• VRCConstraintSourceKeyableList: このコンストレイントに属するソースのリストです。

例として、以下のコードサンプルでは、特定のコンストレイントに割り当てられた各ソースを反復処理してウェイトを変更し、リストに再度割り当てることで、すべてのソースのウェイトをランダム化しています：

for (int i = 0; i < constraint.Sources.Count; i++)
{
    VRCConstraintSource source = constraint.Sources[i];
    source.Weight = UnityEngine.Random.value;
    constraint.Sources[i] = source;
}

ソースのリストを取得し、そのリストに対して Add() を呼び出すことで、プログラムからコンストレイントにソースを追加できます：

// Create a new constraint source targeting this transform with a weight of one.
VRCConstraintSource source = new VRCConstraintSource(transform, 1.0f);

// Add this source to a constraint.
constraint.Sources.Add(source);

ソースを削除するには、追加時と同じソース構造体を使用して Remove() を呼び出すか、インデックスで特定の既存ソースを特定して RemoveAt() を使用します。

// Remove a specific source...
constraint.Sources.Remove(source);

// ...Or remove a source at a particular index i.
constraint.Sources.RemoveAt(i);

TargetTransform

• Transform: このコンストレイントコンポーネントの結果によって影響を受けるTransformです。

nullに設定した場合、コンストレイントはそのコンポーネントがアタッチされているTransformに対して結果を適用します。

SolveInLocalSpace

• bool: true の場合、このコンストレイントはローカル空間で計算され、false の場合はワールド空間で計算されます。

Unityのコンストレイントは常にワールド空間で計算されます。

FreezeToWorld

• bool: true の場合、このコンストレイントは現在ワールド空間上の固定された位置・回転・スケールを維持しようとします。false の場合は維持しません。

このプロパティが false から true に切り替わった瞬間の現在のポーズをコンストレイントが記録し、次に false に戻るまでその状態を維持しようとします。

RebakeOffsetsWhenUnfrozen

• bool: true の場合、コンストレイントがアンフリーズ（凍結解除）された時にソースからオフセットを再計算します。false の場合、元のオフセットを維持します。

これは FreezeToWorld のサブプロパティであり、コンストレイントがアンフリーズされた際（つまり FreezeToWorld が true から false に切り替わった時）の挙動を制御します。

ActivateConstraint()

コンストレイントに対してこのメソッドを呼び出すと、現在のオフセットを維持したままコンストレイントがアクティブ化およびロックされます。エディタのインスペクターでコンストレイントの「Activate」ボタンを押すのと同じ動作です。

ZeroConstraint()

コンストレイントに対してこのメソッドを呼び出すと、オフセットをデフォルト値にリセットした上でコンストレイントがアクティブ化およびロックされます。エディタのインスペクターでコンストレイントの「Zero」ボタンを押すのと同じ動作です。

At-Rest（静止）およびオフセット値

各タイプのコンストレイントはそれぞれ異なる方法でTransformに影響を与えるため、コンストレイントごとに独自の「AtRest（静止時）」および「Offset（オフセット）」値が設定されており、それぞれ適切に命名されたプロパティからアクセスできます。例えば、Position Constraintには PositionAtRest と PositionOffset があり、それぞれソースからの距離を表します。一方、Rotation Constraintには RotationAtRest と RotationOffset があり、それぞれ一連のオイラー角を表します。

Parent Constraintは特殊で、コンストレイント全体に影響するオフセットが1つあるのではなく、ソースごとにオフセット値を持っています。Parent Constraintに適用されるオフセットを変更するには、Sources リストから対象のソースにアクセスし、その中の ParentPositionOffset および ParentRotationOffset プロパティを修正します。

Aim Constraintの整列

これらはVRChatのAim Constraintに固有のプロパティであり、ターゲットに対してどのように整列するかを制御します。

AimAxis

• Vector3: ソースに向けるべき軸です。

これは、どの方向を前方として扱うかを実質的に定義します。

UpAxis

• Vector3: このコンストレイントにおいて上方向として扱われる軸です。

コンストレイントは、この方向を後述する WorldUp で指定された上方向と一致させようとします。

WorldUpTransform

• Transform: コンストレイントの上方向ベクトルを決定するために使用されるTransformです。

これは、後述する WorldUp の特定の値を使用する場合にのみ使用されます。

WorldUpVector

• Vector3: コンストレイントの上方向ベクトルを決定するために使用される方向です。

これは、後述する WorldUp の特定の値を使用する場合にのみ使用されます。

WorldUp

このAimコンストレイントにおいて、どの方向を上方向として扱うかを決定する列挙型です。選択肢は以下の通りです：

• WorldUpType.SceneUp: シーンの正のY軸（Vector3.up）を上方向として扱います。
• WorldUpType.ObjectUp: コンストレイントのターゲットTransformから、WorldUpTransform プロパティで指定されたTransformへ向かうベクトルを上方向として扱います。
• WorldUpType.ObjectRotationUp: WorldUpTransform で指定されたTransformのローカル空間における WorldUpVector 軸を上方向として扱います。
• WorldUpType.Vector: ワールド空間における WorldUpVector を上方向として扱います。
• WorldUpType.None: 上方向を定義しません。

WorldUpはVRC.Dynamics名前空間の列挙型であるVRCConstraintBase.WorldUpType型です。

Look-At Constraintのアライメント

Aim Constraintと同様に、Look-At Constraintにはターゲットに対してどのように自身を整列させるかを制御するプロパティがいくつかあります。Look-At Constraintは、実質的にAim Constraintを簡略化したものです。

Roll

• float: コンストレイントのZ軸周りの角度（度単位）を定義し、これを使用して上方向を決定します。

このプロパティは、UseUpTransformがfalseの場合にのみ有効です。

WorldUpTransform

• Transform: コンストレイントを向ける先のTransformです。

このプロパティは、UseUpTransformがtrueの場合にのみ有効です。

UseUpTransform

• bool: falseの場合、コンストレイントはRollの値を使用して傾きを決定します。trueの場合、コンストレイントの正のY軸がWorldUpTransformで指定されたTransformを向くように回転します。

コンストレイント変換フック

コンストレイント変換機能は、SDKがUnityのコンストレイントをVRChatのコンストレイントに自動変換する際に実行されます。SDKのコンストレイント変換機能と連携するカスタムのC#エディタツールを作成することも可能です。

このセクションでは概要のみを説明しているため、詳細については各ユーティリティのインラインドキュメントを参照してください。

変換メソッド

SDKのクラス AvatarDynamicsSetup には、Unityのコンストレイントを同等のVRChatコンストレイントに変換するためにSDKが使用する変換メソッドが含まれています。ユーザー用のツール作成向けに、以下のコンストレイント変換メソッドが公開されています。

変換デリゲート

上記のメソッドを補完するために、AvatarDynamicsSetupクラスではツールがコンバーターの動作を制御できるデリゲート関数も提供しています。以下のデリゲートが利用可能です：