(シリーズ2)」24日の記事です。2.7.0で外部通信機能がベータ機能としてリリースベータ機能についてベータ機能は正式リリース前のフィードバックを目的とした、正式リリース前の機能を試すための機能です。ベータ機能の使用により、動作が不安定になったり、仕様変更により動作しなくなる可能性があることを理解したうえで使用する必要があります。https://docs.cluster.mu/creatorkit/beta/ベータ機能の制限ベータ機能としてリリースされている機能を使用するには、いくつかの制限があります。ワールドの初回アップロード時点で、ベータ機能が有効にしておく必要がある。Kitの設定から、ベータ機能を有効にしておく必要があります。アップロードしたワールドでベータ機能を有効にしたり、すでにベータ機能が有効なワールドを後から無効にすることができない点に注意してください。ベータ機能が有効なワールドでは、入室するときにベータ機能が有効であることを示す警告が表示され、ワールドタイトルにアイコンが表示されます。ワールドクラフトでも、ベータ機能を使用したアイテムを使用する場合は、ワールドクラフトを作る際に、ベータ機能を有効化する必要があります。こちらも同様に、後から無効化・有効化することができません。イベント会場では使用できないベータ機能が有効なワールドはイベント会場として使用することができません。(callExternal)ってなぁに?公式noteではこのように書かれています。1kB以下となります。゚д゚)ポカーンとなった人が大多数かと思われます。APIを理解しようこの外部通信機能について理解するために、APIという概念を理解しておきましょう。日本語の文章を英語に翻訳するとしましょう。和英辞典を開いて、日本語の単語それぞれを英語に訳して、組み立てると、英語の文章になりました。長い文章や難しい文章をこの方法であなたは翻訳できるでしょうか...?あなたの知識(プログラムしている範囲内)で英語の文法が完全にカバーできているレベルではない場合、間違った結果を示す可能性もあります。そこで、専門家の方をお呼びしましょう。アメリカ人と日本人のハーフで、英語も日本語もしゃべることができるマイクです。マイクに英文を言ったら、すぐに英文を返してくれました。?効率的でしょう?このマイクの存在こそ、APIです。APIは、決まった形式の呼びかけをして、APIは決まった形式で返事をします。Penという訳文を返します。APIには、以下の構文で翻訳を依頼します。APIは以下のように返事をします。APIのように、世の中には公開されているAPIがたくさんあります。公開されているAPIを活用することで、技術的に実装が難解になる機能の実装ハードルがとても低くなります。API様々な気象情報を取得することができるAPIですhttps://openweathermap.org/api!APIは誰でも使えるの?APIは誰でも使えるものと、そうでないものがあります。その会社のサービスのために、自社内で使用するための非公開なAPIもありますし、そのAPIを誰でも使用できるようにしているケースもあります。APIは無料?公開APIには有料のものも存在します。サブスクリプションで使用できるものや、APIを使用した回数で金額が決まる従量課金のものもあります。APIを使用しすぎないマナーなんてのもあったりします。APIを使用すると、他のAPI利用者へ迷惑になる可能性もあります。なんてのもありました。「カタコトなAPIくん」APIを使用してどのようにソフトなどが動いているかを見ていきましょう。天気の情報を見ることができるウェブサイトがあるとしましょう。ユーザーがウェブサイトにアクセスして、東京の天気を見ていますね。このウェブサイトの裏側の動きを紐解いてみましょう。ユーザーがウェブサイトにアクセスするユーザーがブラウザで、東京の天気のページを開いて読み込みが始まりました。ウェブサイトのサーバーが天気APIに天気の情報を問い合わせるウェブサイトのサーバーがお天気APIに問い合わせて、東京の天気の情報を取得しています。APIはプログラムが理解しやすいような文章で返すので、カタコトです。人からすると読みにくいです。ウェブサイトのサーバーが天気APIからの返事を紐解いて、ユーザーにウェブサイトを届けるAPIのカタコトな表現をウェブサーバーが紐解いて、ユーザーが理解しやすい形式に変換します。それをブラウザに送信して、ページが表示されました。ウェブサイトなどのサービスの裏では、このようにAPIが絡んでいるものがあります。APIはカタコトです。APIは、誰でも汎用的に使えるように設計されているため、APIの返事を我流にアレンジして、使用する必要があります。今回の場合は、ウェブサーバーがAPIのカタコトを解釈して、ユーザーに分かりやすい画面を作ってくれました。話を戻して、外部通信機能でなにができる?ここまでAPIとはなにか?ということを話してきました。ここからはいよいよ外部通信機能の概要などに触れていきます。なにができる?まずはなにができるか、いくつか考えてみたのでメモ書きで書いておきます。ワールド間、スペース間での通信ワールドやスペースの垣根を越えて通信をすることができます。以前にリリースされたテキスト入力・出力機能を使用することで、スペース間で誰とでもチャットができるシステムを組んだりできると思います。https://note.com/cluster_official/n/nfb2ead17b6b4(clusterのチャット機能をスクリプトから扱う機能が欲しいですね...)公開APIと連携したワールド外部の公開APIと連携して、ワールドの機能を作ることができます。Webhook)を使うDiscordへチャットを送信したり、チャットを取得できますginjakeさんがResoniteとチャットできるシステム作ってました。仕事が早い!https://x.com/sirojake/status/1737772384982389192?s=20https://zenn.dev/ginjake/articles/f06f9e95fb103cスプレッドシートと連携して、ワールド内にあるギミックのメッセージを編集できるようにするゲームワールドのバランス調整などなど、パラメータの調整のために再アップロードが不要に!イベント用ワールドで、イベント開催中のみドアを開けたいというときに、スプレッドシートから、開け閉めできるドアを作るなんてことも可能です。ゲームワールドのハイスコアを保存するゲームワールドのグローバルのハイスコアを保存して、次にワールドに入った時もハイスコアを表示できます。今までのセーブ機能とは異なり、プレイヤーごとのハイスコアではなく、全ユーザーランキングでのハイスコアを保存することができます。APIをワールドから使用できる機能というわけです。うまくいく話はありません。この外部通信機能は、ワールド制作者が用意したAPIサーバーとのみ通信が可能です。この外部通信機能を使用するために、考慮しなければならない制限がいくつかあります。ユーザーごとに1つの接続先(エンドポイント)しかAPIに使用できないAPIからの返信を使用するには、認証が必要になるデータの送受信は文字列でしか行うことができない送受信できるデータは1kb以下APIを呼び出す回数の制限(5回/分)ユーザーごとに1つの接続先(エンドポイント)しかAPIに使用できない・APIからの返信を使用するには、認証が必要になる外部通信機能に使用するURLを事前にアカウントへ登録しておく必要があります。Kitを導入したUnity上から行うことができます。注意点として、アカウントに一つしかURLを登録することができません。そのため、複数のワールドで外部通信機能を使用したい場合は、APIにリクエストするときに、APIのどの機能を使用したいかという情報を含めてあげる必要があります。verify用トークンが発行されます。アイテムにAPIから返された値をスクリプトから取得したい場合は、このトークンを含める必要があります。"文字列"}ここが、公開APIをワールドから触ることを難しくしている要因です。ワールドでは、トークンが含まれている返答しか受信できないので、公開APIにアクセスできても、そのAPIの返答をスクリプトで受け取ることができません。外部通信機能はAPIリクエスト、レスポンス共に、値は文字列でやりとりされます。複数の値を扱いたい場合は、JSONを文字列化したうえで、外部通信機能に通すことが望ましいです。parseを使用することで、jsonと文字列の相互変換が可能です。//文字列をjsonに変換する送受信できるデータは1kb以下という制限もあり、文字列化したjsonは、1kbに収めてjsonのフォーマットが崩れないようにする必要があります。clusterスクリプトで外部通信機能を使用するために、1kb以下であるかをチェックする機能を設けることが推奨されます。1kbの中にできるだけ多くの文字列を入れることができるように、jsonのオブジェクトの名前は1文字にするのも効果的です。このコードは、Discordにメッセージを送信するためのAPIに、ユーザー名とメッセージを送る外部通信機能の例です。$.log("----\nDiscordにメッセージを送信しました。JSON.stringify(msg));}APIを呼び出す回数の制限(5回/分)外部通信機能はアイテムごとに1分あたり5回しか実行できない制限があります。そのため、その回数を超えて外部通信機能を使用しないようにコードを組む必要があります。Itemで生成して使用するなど、複数のアイテムで外部通信機能を使用することで回避が可能です。Item更新を検知したら、検知したことをSignalで通知して、メインとなるアイテムで外部通信を行うこのような実装も考えられます。ほかにできないこと基本的には文字でやりとりすることができ、前述の外部通信機能の制限をクリアできれば、ほとんどの情報をやり取りすることができます。この機能を使って開発をするときは、以下のことを覚えておきましょう。APIから情報を受け取っても、ワールドのギミックの先に実装できないものもあるAPIから情報を受け取った後、ワールド内でギミックによる処理も作る必要があり、現時点のギミックでカバーできる範囲で作る必要があります。画像(映像)・音を扱うことはできないスクリプト機能にはまだ画像や音を扱うための機能がないため、画像や音を扱うAPIを使用することができません。サーバーをつくろうさいごに、外部通信機能を触ってみたい!という人は、まずGASから触ることをおすすめします。clusterのPMのSmithさんが入門向けに記事を書いてくれています!参考になる!https://zenn.dev/smith/articles/cluster-easy-serverまた今度詳細は触れるとして、今回は最低限のスクリプトを載せておきます。railsバッジを贈って著者を応援しようバッジを受け取った著者にはZennから現金やAmazonギフトカードが還元されます。Proよくある質問LinksX(Twitter)GitHubメディアキットLegal利用規約プライバシーポリシ。