cluster Scriptable Item で「クリックしたら色が変わるキューブ」を作るメモ

（Item Material Set List + MaterialHandle）

Cluster では、従来のコンポーネント操作だけでなく
**スクリプト（Scriptable Item）**が使えるようになりました。

「スクリプトでどこまでできるの？」を確認するために、まずは

クリックしたら色が変わるキューブ

を作ってみたメモです。
やりたいことだけに絞って書いています。

公式ドキュメント

詳しい仕様は公式を見てください。この記事は「まず動かしたい人向けの最短ルート」です。

clusterでスクリプト（JavaScript）を使ってみよう！【ドキュメントリンク集】

Script 全体のリファレンス
- Cluster Creator Kit Script Reference
Scriptable Item コンポーネント
Item Material Set List コンポーネント
ベータ機能：マテリアルプロパティ操作 API（setBaseColor など）

ゴールと前提

ゴール

シーン上の Cube をクリックすると
- Item Material Set List に登録したマテリアルの BaseColor が変わる

前提

Unity 2021.3 LTS
Cluster Creator Kit 2.9.0 以降
Script は C# ではなく JavaScript
- Scriptable Item コンポーネントに紐づいた JS の中で、$.～ という形で API を呼び出す

手順

やることはシンプルで 4 ステップです。

キューブに Item / Item Material Set List を付ける
操作したい Material を作って、Item Material Set List に登録
Scriptable Item で $.material("Id").setBaseColor(...) を書く
ワールドをアップロードして、cluster 側でクリックして確認

以下はその詳細です。

1. シーンにテスト用の Cube を置く

GameObject ▸ 3D Object ▸ Cube で Cube を追加。
Cube に以下のコンポーネントが付いていることを確認：
- BoxCollider（自動で付いているはず）
- MeshRenderer
Add Component から Item Material Set List を追加。
（このとき Item コンポーネントも自動で追加されます）

✅ ポイント
色をスクリプトからいじりたい Material は、必ず
「Item + Item Material Set List の組み合わせ」で扱うことになります。

2. マテリアルを作成して Item Material Set List に登録

2-1. 色変更用マテリアルを作る

Project の Assets で右クリック → Create ▸ Material
適当な名前（例：Mat_PaintSample）を付ける
Albedo を白 or グレー にしておく
→ クリックしたときに赤に変わるのが分かりやすいように

Cube を選択し、MeshRenderer ▸ Materials のスロットに
作成した Mat_PaintSample をドラッグ＆ドロップ。

2-2. Item Material Set List に登録

Cube に追加した Item Material Set List の + を押して要素を 1 つ追加。
Id に paint と入力。
Material に作成した Mat_PaintSample をアタッチ。

この Id 文字列（ここでは "paint"）が、
スクリプト側からマテリアルを取得するときのキーになります。

※ここで Material が Renderer に設定されていないとアップロード時にエラーになります。

🔺エラー例
「MaterialはこのItem及び子孫要素のRendererに割り当てられている必要があります。(Id: paint)」

と言われたら、Cube か子オブジェクトの MeshRenderer で
その Mat_PaintSample をちゃんと使っているか確認してください。

3. Scriptable Item で「クリックしたら色が変わる」スクリプトを書く

3-1. スクリプトアセットを作成

Project の Assets で右クリック
→ Create ▸ Cluster ▸ Scriptable Item Script をクリック
ColorChangeOnInteract.js などの名前を付ける。
中身を以下のように編集：

"use strict";

// 変化後の色（少し明るめの赤）
const targetColor = { r: 1.0, g: 0.2, b: 0.2, a: 1.0 };

// プレイヤーがこのアイテムをインタラクトしたときに呼ばれる
$.onInteract(player => {
  // Item Material Set List で Id = "paint" に登録したマテリアルを取得
  const mh = $.material("paint");

  // Base Color を上書き
  mh.setBaseColor(targetColor.r, targetColor.g, targetColor.b, targetColor.a);

  // 動作確認用ログ
  $.log("Cube interacted by: " + player.name);
});

$.material("paint") :
Item Material Set List に登録した Id "paint" の MaterialHandle を取得
mh.setBaseColor(...) :
そのマテリアルの BaseColor をスクリプトから変更

3-2. Scriptable Item コンポーネントに割り当て

Cube を選択。
Add Component から Scriptable Item を追加。
Source Code Asset に、さきほどの ColorChangeOnInteract.js を指定。

これで準備完了です。
Unity 上では何も起きないので、次の手順で cluster 側で確認します。

4. アップロードして cluster でテスト

重要: ClusterScript は Unity の再生では動きません。
必ずスペースにアップロードして cluster アプリ内で試します。

Unity メニューの Cluster ▸ ワールドをアップロード から、
「テスト用にアップロードする」にチェックを入れてアップロード。
cluster デスクトップアプリで、そのスペースに入室。
シーン内の Cube にカーソルを合わせて クリック（Interact）。
Cube のマテリアルが 白 → 赤 に変われば成功。
右上のログにも "Cube interacted by: プレイヤー名" が出ているはずです。

下の 2 枚は Before / After のイメージ：

5. おまけ：クリックするたびに「白 ↔ 赤」をトグルする

変化が分かりやすいように、クリックごとに色を切り替える版も置いておきます。

"use strict";

const white = { r: 1.0, g: 1.0, b: 1.0, a: 1.0 };
const red   = { r: 1.0, g: 0.2, b: 0.2, a: 1.0 };

// このアイテム固有の状態を保存
$.state.isRed = false;

$.onInteract(() => {
  const mh = $.material("paint");

  const c = $.state.isRed ? white : red;
  mh.setBaseColor(c.r, c.g, c.b, c.a);

  $.state.isRed = !$.state.isRed;
});

$.state は「そのアイテム専用の保存領域」みたいなものです。
$.state.isRed に bool を持たせておいて、
onInteract のたびに白 / 赤を反転させています。

6. ハマりポイントメモ

やってみて詰まりやすかったところだけピックアップします。

6-1. Material が Renderer で使われていないとアップロードエラー

Item Material Set List に登録した Material は
その Item または子孫の Renderer で必ず使われている必要あり。
使っていない場合、アップロード時に
「MaterialはこのItem及び子孫要素のRendererに割り当てられている必要があります。(Id: xxx)」
というダイアログが出ます。

6-2. Unity の再生ではスクリプトは動かない

ClusterScript（$.onInteract など）は cluster アプリ側でのみ実行されます。
Unity 上で再生してクリックしても一切反応しないので、挙動確認は必ずスペースで。

6-3. Interact Item Trigger と競合しないようにする

同じ Item に Interact Item Trigger を付けると、
そちらのギミックが優先されてスクリプトの $.onInteract が動かないことがあります。
「全部スクリプトでやる」場合は、Interact 系コンポーネントは外しておくとシンプルです。

まとめ

Scriptable Item ＋ Item Material Set List を使うと、
「クリックしたら色が変わるキューブ」 は数行の JS で実装できます。
ここまでできれば、
- 銃の弾が当たったらブロックの色を変える
- ダメージ量に応じて色や Emission を変える
- 時間経過で点滅させる
  など、色を絡めたギミックにそのまま発展できます。

次は、この onInteract を 弾の On Collide からの send で呼ぶようにして、
「撃ったオブジェクトの色が変わるワールド」を作っていく予定です。