共有セーブを利用する

編集
この機能は実験的な機能であり、将来仕様が変更される可能性があります。予めご了承ください。

前提

このAPIを利用する際は、APIの活用方法のヒントや使い分け方などについてまとめたAPIのセオリーも合わせてご参照ください。

概要

指定ユーザーの特定キー(Atsumaru Shared)のサーバーセーブデータを取得できる機能です。
このセーブデータのことを「共有セーブ」と呼びます。

なにができるのか

指定ユーザーの共有セーブを取得できます。この機能だけでは誰からデータを取得すればいいのかわかりませんが、他APIと組み合わせることにより、非同期通信型のゲームが制作可能になります。
例えば、ユーザー情報APIで、そのゲームを最近プレイしたユーザーがわかるので、そのユーザーの共有セーブに保存されたデータ(例えばアイテムなど)を取得することで、疑似的なすれ違い通信のようなゲームが作成できます。 なお、未ログインユーザーは共有セーブをサーバーに保存できませんが、他人の共有セーブを取得することについては問題なく行えます。

利用想定/利用例

この機能は、以下のような使い方を想定しています。

  • 選択したアバターと一言メッセージを保存し、表示する広場
  • 作成したモンスターキャラクターのデータ共有

例えば、次のサンプルゲームではこの機能を利用し、選択したアバターと一言メッセージを共有セーブに保存しています。

また、こちらのサンプルゲームでは、作成したスライムの情報を共有セーブに保存し、ほかのユーザーの作成したスライムと戦わせています。(バトルの結果は、ユーザーシグナルで送信しています)

機能詳細

  • 共有対象のデータは、Atsumaru Shared というkeyで保存されたサーバーセーブデータです。
    • セーブの保存についてはこちらを参照ください。
    • 共有対象にしたくないデータは、このkeyを使わないようにご注意ください。
  • 本機能でできるのは共有セーブの 取得のみ で、共有元への書き込みはできません。
  • 一度に取得できるデータは100件までで、それ以上のデータを一度に取得しようとするとエラーになります。

他のゲームの共有セーブへのアクセス禁止条件

取得先のゲームと取得元のゲームが同じ場合、共有セーブへのアクセスは必ず認められます。一方で他のゲームの共有セーブを取得する場合は、以下の条件のうちいずれかに該当した場合、アクセス禁止となり FORBIDDEN エラーが返されます。

  • 取得先のゲームが公開されていない
    • ただし取得先のゲームの作者本人は、取得先のゲームが公開されていなくても例外的に共有セーブを取得できます
  • 取得先のゲームと取得元のゲームの作者が違う

共有セーブ取得の絞り込み条件

前節にかかわらず、以下の条件を満たした共有セーブは取得できません。その場合、取得できるユーザーの共有セーブのみに絞り込まれて返されます。

  • 指定したユーザーが存在しない
  • 指定したユーザーの共有セーブが無い
  • 指定したユーザーがプレイヤー間通信の有効化をしていない
    • ただし、自分自身の共有セーブはプレイヤー間通信の有効化をしていなくてもセーブを取得できます

利用方法

共有セーブ機能は次の方法で利用できます。

方法場所
公式プラグインGithub
ゲームAPI以下の「APIでの利用方法」を参考に、直接APIを呼び出してください

公式プラグインの利用方法

プラグイン設置方法

  1. プロジェクトのプラグインフォルダに AtsumaruSharedSaveExperimental.js を右クリックし「保存」して設置。
  2. プロジェクトのプラグイン設定で AtsumaruSharedSaveExperimental プラグインをONにする。

共有セーブの保存

自分のデータを共有セーブとして保存する場合、プラグインコマンドは次のいずれかのように指定します。(どちらでも動作は同じです)

SetSharedSave
共有セーブ保存

プラグイン設定画面の 共有セーブの保存範囲(開始)共有セーブの保存範囲(終了) に設定した範囲のツクール変数が、自分の共有セーブデータとして保存されます。

共有セーブの取得

他人の共有セーブを取得して変数に代入する場合、プラグインコマンドは次のいずれかのように指定します。(どちらでも動作は同じです)

GetSharedSave {userIdVariableId} {startVariableId}
共有セーブ取得 {userIdVariableId} {startVariableId}

{userIdVariableId} で指定した変数からユーザーIDを読み取り、そのユーザーの共有セーブを {startVariableId} を先頭にして代入します。

例:変数1番からユーザーIDを読み取り、そのユーザーの共有セーブを変数201番以降に展開(たとえば共有セーブの保存範囲が101-150で計50個の場合、201-250に代入)

共有セーブ取得 1 201

ただし、読み取る相手がプレイヤー間通信の有効化をしていないと、共有セーブを取得できないことにご注意ください。

APIでの利用方法

共有セーブの取得

メソッドwindow.RPGAtsumaru.experimental.storage.getSharedItems(userIds: number[], gameId?: number)
説明指定したユーザの Atsumaru Shared というキーで保存したセーブデータを取得する。
引数
  • userIds : 共有セーブを取得したいユーザーのニコニコユーザーIDの配列を自然数で、最大100件まで指定します。
  • gameId : 現在プレイ中のゲーム以外からセーブデータを取得する場合、ゲームのIDを自然数で指定します。
戻り値Promise<SharedSaveItems>
リリース日2018/12/17
更新日2018/12/17
  • userIds で指定したユーザーのセーブデータユーザーのデータを取得できます。
  • 第二引数の gameId を指定することで、別のゲームの共有セーブを取得できます。
戻り値の型 SharedSaveItems について

戻り値で取得できる SharedSaveItems は以下のような型です。

interface SharedSaveItems {
  [userId: number]: string;
}

プロパティの内容は次のようになっています。

プロパティ名内容
[userId: number]stringuserId のIDのユーザーの共有セーブデータを収納します。
戻り値の例
// window.RPGAtsumaru.experimental.storage.getSharedItems([123, 456, 789]).then(function(v) { console.log(v) }) を実行
{
  123: "ユーザー123の共有データ",
  456: "ユーザー456の共有データ"
  // 789 のユーザーが取得先のゲームで「プレイヤー間通信の有効化」されていない場合は結果に含まれません!
}
起こりうるエラーの種類
名前説明
BAD_REQUEST引数として不正な値を指定している
FORBIDDENgameId にアクセス不能なゲームのIDを指定した場合
INTERNAL_SERVER_ERRORRPGアツマールのサービス側で何らかの問題が発生しているか、または通信に失敗した
API_CALL_LIMIT_EXCEEDED短時間にゲームAPIを利用しすぎて、一時的に利用を制限されている