Cluster Script関係メモ（βもあり）
[公式リファレンス]
Cluster Cluster Creator Kit ドキュメント
Cluster Creator Kit Script Reference
[Cluster Creator Kit Scriptの基本概念など(Index)]
[Cluster Creator Kit Script の詳細説明(Module)]
[Cluster Creator Kit Script の詳細説明(ClusterScript)]
ClusterScriptは、「$.～」で表記。
アイテムに対する処理がメイン。
[Cluster Creator Kit Script の詳細説明(PlayerScript)]
PlayerScriptは、アイテムをつかむなどしたPlayerに対してScriptからが操作・設定が可能になる。
Player全員に勝手にScriptが付与されるわけではなく、ClusterScriptにある、「$.setPlayerScript」を使って、PlayerHandle（後述）を与えることで、対象のPlayerにPlayerScriptを当てることが出来る。
PlayerScriptの操作は、「_.～」で呼び出す。
Cluster Creator Kit Script(cluster-script-types)を書くに当たり、
npmでTypeScript型定義ファイルを公開しているサイト。
Visual Studio Codeなど対応しているエディタで読み込めば、
エディタの入力補完してくれる。
上記の型定義は古いため設定終了後、
「型定義ファイル(index.d.ts)」を下記ページからダウンロードし、
上書きをする必要がある。（2025/1/3現在）
[公式ガイド：ベータ機能]
【参考補助情報】VisualStudioCodeでのインテリセンス(入力補完)の設定
ClusterScriptの保存文字コード
「UTF-8（BOMなし）」にした方がよい。
※VisualStudioCodeを使っていれば意識する必要はない。
Handleの識別
ClusterScriptには、ItemHandleとPlayerHandleがある。
時には、共通Objectプロパティのhandleを参照する必要があるため、
そのhandleがどちらのモノなのかを識別する必要がある。
その識別には、「ItemHandle.type」と「PlayerHandle.type」で区別が可能。
詳しくは下記を参照。
後述する、PlayerScriptのItemIdとPlayerIdも同様の方法で区別できる。
PlayerHandle関連
このハンドルを使うと、Playerが存在しているかや各プレイヤー位置や向きの参照／変更などが可能。
各ボーンの位置や回転も参照可能（HumanoidBone）。
（getHumanoidBonePosition／getHumanoidBoneRotation）
※プレーヤー間で直接データのやりとりするI/Fは、
相互のplayer情報を取得出来ている場合にかぎり、
「PlayerScriptSendable」型であれば、
「PlayerScript」の「sendTo」/「onReceive」を使うことで可能。
※「ItemHandle」の「send」/「onReceive(ClusterScript)」を使うことで、
アイテム間のPlayerHandleのやりとりも可能。
PlayerHandle取得方法
下記のClusterScriptメソッドで取得可能。
「getGrabbingPlayer」（返値：playerHandle）
「getOverlaps」
（返値：Overlap[].handle ※ItemHandleかPlayerHandle識別が必要）「getOwner」（返値：playerHandle）
「getPlayersNear」（返値：PlayerHandle[]）
「getRidingPlayer」（返値：playerHandle）
「onCollide」
（引き数：Collision.handle ※ItemHandleかPlayerHandle識別が必要）「onGetOwnProducts」
（引き数(callback)：OwnProduct[].player）「onGrab」（引き数(callback)：playerHandle）
「onInteract」（引き数(callback)：playerHandle）
「onPurchaseUpdated」（引き数(callback)：playerHandle）
「onReceive」
（引き数(callback)：sender ※ItemHandleかPlayerHandle識別が必要）「onRequestPurchaseStatus」（引き数(callback)：playerHandle）
「onRide」（引き数(callback)：playerHandle）
「onSteer」（引き数(callback)：playerHandle）
「onSteerAdditionalAxis」（引き数(callback)：playerHandle）
「onUse」（引き数：playerHandle）
「raycast」
（返値：RaycastResult.handle
※ItemHandleかPlayerHandle識別が必要）「raycastAll」
（返値：RaycastResult[].handle
※ItemHandleかPlayerHandle識別が必要）
ItemHandle関連
このハンドルを使うと、Itemが存在しているかや各Itemに対して重心や重力などの値を設定可能。
sendを使うとItemHandleがわかれば、
別のアイテムに対して配列などの値（参照：Sendable）を送信可能。
※アイテム間でデータのやりとりが可能。
sendで送られた値はonReceiveで受け取れる。
ItemHandle取得方法
下記のClusterScriptメソッドで取得可能。
「createItem」（返値：ItemHandle）
※このメソッドでクラフトアイテムを使う場合は、
cluster Cluster Creator Kit ドキュメント
「クラフトアイテムの情報取得」を事前に参照。
（itemTemplateIdに関する内容）
※このメソッドでワールドアイテムを使う場合に使用する、
「WorldItemTemplateId」については、
「World Item Template List」、「ワールドアイテムテンプレート」を
参照。「getItemsNear」（返値：ItemHandle[]）
「getOverlaps」
（返値：Overlap[].handle ※ItemHandleかPlayerHandle識別が必要）「onCollide」
（引き数：Collision.handle ※ItemHandleかPlayerHandle識別が必要）「onReceive」
（引き数(callback)：sender ※ItemHandleかPlayerHandle識別が必要）「raycast」
（返値：RaycastResult.handle
※ItemHandleかPlayerHandle識別が必要）「raycastAll」
（返値：RaycastResult[].handle
※ItemHandleかPlayerHandle識別が必要）
ApiAudio
Scriptから$.audio経由でApiAUdioを呼びだしAudioを使う場合は、
シーンに対して事前に
「Item Audio Set List」に音を一通り登録しておく必要がある。
シーンに仕込んだIDを与えることで、その音に対して制御が出来る。
参考ガイド
humanoidAnimation
ScriptからHumanoid Animationアニメーションのポーズを取得したい場合は、シーンに対して事前に「HumanoidAnimationList」に
AnimationClipを一通り登録しておく必要がある。
$.humanoidAnimationの引き数に、シーンに仕込んだIDを与えることで、
そのアニメーションデータを取得できる出来る。
姿勢などの情報も取得可能。
（値の型は「HumanoidPose」）
// HumanoidAnimationListで設定したIDから目的のアニメーションデータを取得。
const humanoid_anim = $.humanoidAnimation(ID);
// アニメーションデータから、指定した時間のアニメーションサンプルを取得
// ※アニメーションの最大秒数は、「humanoid_anim.getLength()」で取得可能。(型：number）
// （小数点を設定できるので、1秒以下なども0.5などと指定可能）
// 返値の型は、「HumanoidPose」
const humanoid_pose = humanoid_anim.getSample(姿勢を取得したいアニメーションタイム);
// 取得した、「HumanoidPose」のポーズデータmusclesのFrontBackの値を表示。
$.log(humanoid_pose.muscles.chestFrontBack);
【参考】
【Tips】
humanoidAnimationで取得したアニメーションデータをPlayerに設定する。
PlayerHandleにある、「setHumanoidPose」を使用する。
// アイテムを掴んでいる間、ポーズを変更する。（そのポーズに固定されるので実用性はない。。。）
$.onGrab((isGrab, isLeftHande, player) => {
if (isGrab) {
// HumanoidAnimationListに登録したIDを指定して、アニメーションデータ取得(HumanoidPose)
const humanoid_anim = $.humanoidAnimation(ID);
if (humanoid_anim.getLength() >= 0.5) {
// 取得したアニメーションデータの0.5秒目のアニメデータ取得
const humanoid_pose = humanoid_anim.getSample(0.5);
if (humanoid_pose.muscles != null)
{
// 取得したアニメーションポーズを反映する
player.setHumanoidPose(humanoid_pose);
}
} else {
player.setHumanoidPose(null); // ポーズを元に戻す。
}
});【Tips】
Playerの各ボーンの位置や回転情報を取得する
PlayerHandleにある
---
ポーズ：getHumanoidBonePosition
回転 ：getHumanoidBoneRotation
---
を使用する。
引数に指定する、取得するボーンの位置値指定は、
「HumanoidBone」を使って指定する。
※HumanoidBoneは、Cluster Creator Kit Scriptで事前に定義された
固定値の集まり(Enumeration)。
※
「HumanoidBone」(固定値：Enumeration)
と
「HumanoidPose」(クラス：Class)
は、名称は似てるけど、まったく別物なので要注意。
// IntractしたPlayerのHeadボーンの位置や回転情報を取得する
$.onInteract(player => {
// Headボーンの位置情報を取得（返ってくる型：Vector3 or null）
const bone_pos = player.getHumanoidBonePosition(HumanoidBone.Head);
// Headボーンの回転情報を取得（返ってくる型：Quaternion or null)
const bone_ret = player.getHumanoidBoneRotation(HumanoidBone.Head);
});【参考】
【Tips】
回転系のVector3とQuaternionの変換
Quaternion -> Vector3
→ $.getRotation().createEulerAngles()
Vector3 -> Quaternion
→ (new Quaternion()).setFromEulerAngles("回転を表すVector3データ")
【Tips】
移動量（ベクトルの長さ）
[2点間]
「(new Vector2(x,y)).length」
[3次元空間]
「(new Vector3(x,y,z)).length」
で、ベクトルの長さが求まる。
（三角関数などの手間が省ける）