【サンプル付き】ギミックで商品をプレゼントできる「商品付与API」を使ってみよう

Cluster Creator Kit v2.33.0（以下、CCK）から、「商品付与 API」を使うことができるようになりました。

このAPIを使うと、クラフトアイテム・アクセサリー・アバターなどの商品をプレゼントすることができます。例えば、クイズや迷路を制覇した人だけにプレゼントしたり、イベント来場者だけに思い出の品をプレゼントしたりすることができるようになります。

そこで今回の記事では、シンプルな例として「プレゼントボックス」のサンプルを配布します。
サンプルアイテムは、インタラクトすることで設定した商品をプレゼントすることができます。商品付与APIはクラフトアイテムにも使えるので、クラフトが許可されたワールド・イベントであれば、どこでもプレゼントすることが可能になります。

ぜひ使ってみてください!

Table of Contents

すぐに使えるサンプルアイテムのダウンロードはこちらから

この記事では、すぐに使えるサンプルアイテムを配布しています。
まずは使ってみたいという方は下記からダウンロードしてください。本記事では、サンプルアイテムについて解説していきます。

クリックして、サンプルアイテムをダウンロードする

商品付与するために必要な設定

付与したい商品をストアに公開する

商品付与APIで付与できる商品は、基本的には自分でストアに公開した商品のみとなります（詳細は公式ドキュメントをご覧ください）。
クラフトアイテムやアクセサリーをストアに公開するまでの手順は下記の記事で解説しているので、ご覧ください。

自作のモデルをアイテムとして商品登録してみよう
- https://creator.cluster.mu/2022/08/18/craftitem/
自作のアクセサリーをclusterで使えるようにしてみよう！
- https://creator.cluster.mu/2022/12/07/accessoryitem/
ワールド・イベント内でアバター販売ができる！商品ディスプレイアイテムを使ってみよう
- https://creator.cluster.mu/2024/09/09/avatar-productdisplayitem/

CCKで制作する場合は、商品付与ギミックを置くためのワールドも自分で用意する必要がありますが、クラフトアイテムとしてアップロードすれば、クラフトが許可されていれば他の人がつくったワールドでも使えることができます。また、そのクラフトアイテムを購入したユーザーも、商品を付与することができます。

限定アイテム的に使える「公開（商品販売ディスプレイのみ）」

v3.29のアップデートで商品の公開設定で「公開（商品ディスプレイ販売）」が選択できるようになりました。

「公開（商品ディスプレイ販売）」を選択すると、ストアに表示されず、Webサイト等の商品ページからは購入できません。商品付与APIと組み合わせることで、ワールドやイベントに訪れた人だけが手に入れることができる限定アイテムなどをつくることもできます。例えば、迷路やクイズだけをクリアした人だけがもらえる商品なども実現できます。

公開設定は、商品の詳細ページ内の「公開設定を選択」から変更できます。一度ストアに公開した商品は、後から公開設定を変更しても付与できます。

スクリプトに付与したい商品のIDを記載する

商品を付与するためには、その商品のIDが必要になります。
商品IDは商品詳細ページ内の「商品IDをコピー」から取得することができます。

商品IDを取得できたら、取得した商品IDをサンプルアイテムのスクリプトに記載します。
スクリプトの改変方法については、下記の記事で解説しているので、もし分からない方がいたら、ぜひご一読ください。

サンプルのスクリプトを改変する手順

🕒️2025-03-10

Cluster Creator KitとUnityを使ったclusterのワールド制作では、Cluster Creator Kitのコンポーネントの他に「Cluster Script」というスクリプトを使ってギミックを制作することができます。Creators Guideでは、誰でも使えるサンプルを、カテゴリ「サンプルプロジェクト付き」やCreators Guideベータ版などでサンプル付きの記事として公開しています。ですが、サンプルがあっても「そもそもどこから改変すればいいんだ……？」という方もいるかもしれません。そこで、今回はサンプルのスクリプトを改変したい場合の基本的な手順を紹介...

変更する部分は一点だけです。
スクリプト内の一番上にある下記の””の中の部分を、先に説明した商品IDに書き換えると、その商品を付与することができます。

const productId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

スクリプト全文

今回のサンプルアイテムは「インタラクトすることで設定した商品をプレゼントすることができる」という実装になっています。

const productId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx";

// PlayerHandle.requestGrantProductの結果を受け取れるようにする
$.onRequestGrantProductResult((result) => {
    $.log(`status: ${result.status}, productId: ${result.productId}, productName: ${result.productName}, playerId: ${result.player.id}, meta: ${result.meta}, errorReason: ${result.errorReason}`);
    const status = result.status;
    switch (status) {
        case "Granted":
        case "AlreadyOwned":
            if (result.player.exists()) {
                $.log(`${result.player.userDisplayName} granted product: ${result.productName}`);
            }
            break;
        default:
            $.log(`status: ${status}, errorReason: ${result.errorReason}`);
            break;
    }
});

// インタラクトしたプレイヤーに商品を付与する
$.onInteract((player) => {
    player.requestGrantProduct(productId, `${productId}_${player.id}`);
});

スクリプトの解説

インタラクトしたプレイヤーに商品を付与するギミックは下記のスクリプトで実装できます。requestGrantProduct でプレイヤーに商品付与をしています。

// インタラクトしたプレイヤーに商品を付与する
$.onInteract((player) => {
    player.requestGrantProduct(productId, `${productId}_${player.id}`);
});

また、 onRequestGrantProductResult で商品付与を実施した際の色々な結果を受け取ることができます。こちらの結果を使って、商品付与をした際の演出を作成したりすることもできます。商品付与の結果は、以下の4種類があります。

“Unknown” .. ネットワークエラーなどの理由で、付与が行われたかどうかが判定できないことを示します
“Granted” .. プレイヤーに商品が付与されたことを示します
“AlreadyOwned” .. プレイヤーがすでに商品を所持していたことを示します
“Failed” .. 商品付与を実施しようとしたが、付与に失敗したことを示します

こちらのスクリプトでは、商品付与をした際の各種結果などをコンソールに表示し、特定の結果の時にコンソールに表示される内容が変わるようにしています。

// PlayerHandle.requestGrantProductの結果を受け取れるようにする
$.onRequestGrantProductResult((result) => {
    $.log(`status: ${result.status}, productId: ${result.productId}, productName: ${result.productName}, playerId: ${result.player.id}, meta: ${result.meta}, errorReason: ${result.errorReason}`);
    const status = result.status;
    switch (status) {
        case "Granted":
        case "AlreadyOwned":
            if (result.player.exists()) {
                $.log(`${result.player.userDisplayName} granted product: ${result.productName}`);
            }
            break;
        default:
            $.log(`status: ${status}, errorReason: ${result.errorReason}`);
            break;
    }
});

特定の人のみに向けて商品を付与したい場合、そのギミックが入ったクラフトアイテムを誰でも使えるようにしてしまうと、誰でも商品を入手できるようになってしまいます。
また、PlayerHandle.requestTextInputで入力された商品IDを元に商品を配るようなギミックも制作できますが、誰でもそれを入力できるような状態にしてしまった場合、公開しているすべての商品が無償で手に入るようになってしまうため、注意が必要です。