VCIストレージ#

Room only

VCIストレージ機能を使うことで、VCIスクリプトの変数を永続的に保存できます。

概要#

VCIストレージはアセットごとに1つ#

VirtualCastにアップロードされたそれぞれのVCIアセットには、VCIに埋め込まれたスクリプトからアクセスできる記憶領域がサーバー上に割り当てられます。この記憶領域はVCIストレージAPIを使用して読み込み・書き込みができます。たとえば、あるVCIアセットが複数のルームで生成されていたり、ひとつのルームで複製がいくつも生成されていたとしても、生成されたVCIインスタンスたちはひとつの記憶領域を共有して利用します。

1つのVCIストレージはKey-Valueペアの集まり#

記憶領域はKey-Value Store形式を取ります。ストレージに書き込む際は、保存したい値（Value）と識別子（Key）のペアをVCIストレージAPIに渡します。ストレージから値を読む際は、書き込む際に与えたKeyをVCIストレージAPIに渡します。1つのVCIストレージには最大1000個のKey-Valueペアを保存できます。

Key-ValueペアはTagを持つ#

ストレージに書き込む際、KeyとValueのペアに加えてTagと呼ばれる識別子を付与できます。これは複数のKey-Valueペアをまとまった意味のあるデータとして扱いたい場合に役立ちます。複数のKey-Valueペアに同一のTagを与えて書き込んでおくと、Tagを指定して複数のKey-Valueペアを一括で取得できます。

特徴#

✅ VCIを再読込したりルームから削除してもデータが消えない#

VCIスクリプトの変数を永続化する仕組みにはVCIストレージの他にアイテム内同期変数があります。アイテム内同期変数との大きな違いは、「保存したデータがどこに紐づくか」です。アイテム内共有変数は生成されたVCIに紐づくため、VCIを再読込したりルームから削除したりするとデータが揮発します。一方でVCIストレージに保存したデータはVirtualCastにアップロードされたアセットに紐づけて保存され、ルーム上のVCIを再読込したり削除してもデータは保持されます。

✅ ルームをまたいでデータを共有できる#

VCIストレージに保存したデータは、ルームではなくVirtualCastにアップロードされたアセットに紐づけて保存されます。そのため、別々のルームに置いた同一のVCIアセットは同一のVCIストレージを共有します。この仕組みを利用することで、ルームをまたいでデータを共有できます。

⚠️ 利用にはコールバック関数の理解が必要#

VCIストレージAPIは通信を伴うAPIです。APIを呼んでから実際にVCIストレージに値が書き込まれたり、読み込んだ値がスクリプトで利用可能になるまでの間には、サーバーにリクエストを送り、その結果が返ってくるまでのレイテンシが存在します。このレイテンシに対処するために、VCIストレージAPIの各APIは引数にコールバック関数を与える設計をとります。このコールバック関数はサーバーからのレスポンスが到着すると結果を引数に実行されます。この設計により、APIの結果を利用した任意の処理を記述できます。

⚠️ リアルタイム通信は不得意#

VCIストレージはゲームのランキング機能やセーブデータ機能を想定して設計されており、即時性を要求する用途には向いておりません。VCIストレージAPIを呼ぶとその要求はバッチに登録され、一定時間ごとにバッチ単位で通信が実行されます。そのため、VCIスクリプトのAPI呼び出しから通信の開始までには最大10秒程度のレイテンシが発生します。また、サーバーとの通信においてもレイテンシが発生します。即時性を要する通信には、アイテム内同期変数やメッセージを使用してください。

⛔ アトミック操作は不可能#

たとえば、あるVCIアセットを元にして生成したVCIがルームに2つにあると仮定します。それぞれのVCIがあるKeyに対し異なる値をVCIストレージに書き込んだ時、どちらの値がVCIストレージに保存されるかについては不定です。同一Keyに値を書き込むスクリプトを記述する際は、この点に注意して記述してください。

使い方#

VCIスクリプトでは、VCIストレージを操作するAPIとして ExportStorageを提供しています。
サンプルコードでは通信の結果を表す ExportStorageResult のハンドリングを省略していますが、実際には必要に応じてハンドリングを行ってください。

VCIストレージに値を書き込む#

-- "key1" に "value1" を書き込む
vci.storage.Set("key1", "value1")

VCIストレージから値を読み込む#

-- "key1" の値を読み込む
vci.storage.Get("key1", function(r, v)
    -- v に値が入っている
    print(v)
end)

VCIストレージからKey-Valueペアを削除する#

-- "key1" のKey-Valueペアを削除する
vci.storage.Delete("key1")

注釈

VCIストレージに保存されたデータはVCIスクリプトから1件ずつ削除できますが、すべてのデータを削除したい場合は、VirtualCastのアセット情報のページからまとめて削除できます。この操作ができるのはVCIの投稿者のみです。

VCIストレージにタグを指定して値を書き込む#

-- "key2" にタグ "tag1" を指定して "value2" を書き込む
vci.storage.SetWithTag("key2", "value2", "tag1")

-- "key3" にタグ "tag1" を指定して "value3" を書き込む
vci.storage.SetWithTag("key3", "value3", "tag1")

VCIストレージからタグを指定して値を読み込む#

vci.storage.GetValuesFromTag("tag1", function(r, t)
    -- t はタグ "tag1" に紐づく Key-Value ペアのTable
    for i, kv in ipairs(t) do
        print("key:"..kv.key..",value:"..kv.value)
    end
end)