• このエントリーをはてなブックマークに追加
RPGアツマール ゲームAPI仕様書
閉じる
閉じる

新しい記事を投稿しました。シェアして読者に伝えましょう

×

RPGアツマール ゲームAPI仕様書

2016-12-27 18:35
  • 2
『RPGアツマール』には『RPGアツマール ゲームAPI』と呼ばれるゲーム側から利用できるAPIが存在します。
RPGツクールMVで高度なゲームを作りたい人や、HTML5で独自のゲームを作りたい人に向けてその仕様を解説します。

RPGアツマールの運営方針はこちら / 技術者向けslackの案内はこちら(記事中段)

■RPGアツマール ゲームAPIとは何か
  • 『RPGアツマール ゲームAPI』はゲームからRPGアツマールの機能を利用するためのものです。2016年12月27日時点ではサーバーセーブ、コメント機能、バーチャルコントローラーが提供されています。
  • このAPIはアップロードされた index.html に rpgatsumaru.js を挿入することで実現しています。
  • APIの仕様はまだ暫定であり、追加・更新の可能性があります。

■API利用ガイドライン
  • APIの利用によるサーバーへのネットワークアクセスは負荷を避けるために基本的に「10秒に1回」より緩やかにしてください。ユーザーアクションによる短期的なアクセスは許容します。
  • オートセーブのような定期的にサーバーアクセスを行う処理は、「ゲームを長時間プレイしていないとき」に行わないようにしてください。
  • APIはゲームプレイのために提供しています。ゲームに関係ないデータアクセスのために利用しないでください。

更新履歴

  • 2017/12/20
    • VolumeAPI を追加
  • 2017/9/8 
    • window.RPGAtsumaru.comment.changeScene(sceneName)に「シーン名は64文字までのascii限定」を追記
    • window.RPGAtsumaru.comment.setContext(context) に「context の値は、ascii 64文字以下推奨」を追記
■StorageAPI
StorageAPIはサーバーセーブを可能にするAPIです。Stringを保存するシンプルなKVS(Key-Valueストア)になっています。セーブはゲームID(gm123等)ごとに独立しています。
セーブデータの保存領域にはニコニコユーザーIDごとに上限があります。1kbで1ブロックとして、90ブロックまで保存ができます。セーブデータは保存時に自動的に圧縮され、圧縮後のファイルサイズを見ています。
StorageAPIは複数端末からセーブされることを想定しています。

window.RPGAtsumaru.storage.getItems()
引数: 無し
戻り値: Thenable<{key: string, value: string}[]>

  • このゲームの最新のセーブデータを全件取得する。
  • サーバーアクセスが発生します。

window.RPGAtsumaru.storage.setItems(items)
引数: 更新する対象のセーブ情報。型は {key: string, value: string}[]
戻り値: Thenable<void>

  • セーブデータを保存する。 

複数端末からのセーブ時に楽観的ロックをしています。
A端末とB端末で同時にゲームをプレイしていた場合にAとBがほぼ同時にsetItems()をした場合、先にsetItems()したもののみが受理されます。後のものは一度getItems()で最新のセーブデータを取得した後で受け付けとなります。
サーバーアクセスが発生します。

window.RPGAtsumaru.storage.removeItem(key)
引数:削除対象のセーブのキー。型はstring
戻り値: Thenable<void>

  • 指定したセーブデータを削除する
  • サーバーアクセスが発生します。

保存のkeyについて

推奨のkeyは「system」と「dataN(Nは数字)」です。この2種のキーはRPGアツマール側のセーブ管理画面で、それぞれ「システムファイル」と「ファイル N」として扱われます。この二つ以外はゲーム上で「その他」と表示されます。

RPG Global, RPG Config, RPG FileN(Nは数字)はRPGツクールMV用にカスタマイズされているため、RPGツクールMV以外ではセーブのキーとしては使わないでください。


■ControllerAPI
RPGアツマールではスマートフォンでゲームをプレイする際に、バーチャルコントローラーを表示しています。その入力を受け取るAPIです。バーチャルコントローラーは設定によりOFFになっていることがあります。

window.RPGAtsumaru.controllers.defaultController.subscribe(observer)
引数: RPGアツマールのコントローラーの入力情報({type: string, key: string})を受け取るObserver
戻り値: subscription

  • RPGアツマールのスマホ版にあるコントローラーの入力情報を取得できるAPIです。
  • Observer, subscriptionについてはESNextのObservableを参照してください。

window.RPGAtsumaru.controllers.defaultController.subscribe(next)

引数: RPGアツマールのコントローラー入力情報({type: string, key: string})を受け取るコールバック
戻り値: subscription

  • 上記のAPI(RPGアツマールのスマホ版にあるコントローラーの入力情報を取得できるAPI)の引数に、コールバック関数を受け付けられるようにしたものです。

fbac9f8ad7c100f7f69367d186826a995bdc7779


■CommentAPI
『RPGアツマール』ではユーザーのゲーム体験を共有するためにコメント機能を提供しています。設計はRPGツクールMVでの利用を想定していますがAPIは汎用的にも利用可能です。

コメント機能は「コメントシステム」にゲーム状態を伝えると、コメントがゲーム上に流れてくるというものです。動画と異なり時系列のようなプレイヤー全員が共有しているコンテンツの内部状態が存在しないため、ゲームでは逐次ゲーム状態をコメントシステムに伝える必要があります。「とあるゲーム状態」のことを本システムではgame position(gpos)と呼んでいます。

RPGツクールMVにおいては、イベントコマンドごとにgposをコメントシステムに伝達しています。そのため、ヒロインのセリフなど特定の状態をプレイヤー間で共有できます。もし、あなたがアクションゲームをつくるなら「敵を倒した」「アイテムを得た」などのイベントをgposとしてコメントシステムに伝えることになるでしょう。

gposはsceneとcontextfactorとminorcontextという3つのパラメーターで表現します。プログラム的に書けば以下のようになるでしょう。
gpos(scene, context(contextfactor[0,-1,-2],minorcontext))

sceneはコメントデータ群を表しています。scene一つあたりで最新1000件(変更可能性有り)で、直近5つのsceneをAPI側でキャッシュします。一般的なゲームではマップや戦闘画面、メニュー画面に相当します。

sceneのコメントを、contextの値で指定し取得することでコメントが描画されます。
condextは状態遷移マシンになっており、contextfactorをpushすることで状態が一つ進みます。状態はcontextfactor3つの複合キーで表されています。
一つの状態内でさらに細かく分割する場合、たとえば「あるイベント内の時間」などを示すにはminorcontextが便利です。minorcontextをpushするごとに状態が細かく進み、それに応じたコメントが描画されます。

RPGツクールMVにおいてはsceneはmapのidに対応します
contextfactorは「セリフ」コマンドと「選択肢」コマンドで、minercontextは「ウェイト」コマンドと、コマンド内のwaitに対応します。minercontextがあることで、「セリフのあとにキャラクターが移動して演技する」ような演出に対して細かくコメントができます。

3cef2f96fabe29d20904ce9d5fb7beb18342e650



window.RPGAtsumaru.comment.changeScene(sceneName)
引数: シーン名を表す文字列
戻り値: 無し

  • コメントシステムのシーンを設定する。
  • シーンが切り替わると、そのシーンのコメント空間に切り替わる。
  • ツクールでは基本的にマップID=シーン名となる。
  • サーバーアクセスが発生する。(ただし直近5つのsceneはキャッシュされ、再アクセスには発生しない)。
  • シーン名は64文字までのascii限定。(2017/9/8 追記)
※なお、アンダースコア2つで始まるシーン名は特殊用途として予約されています。
予約されている中で現在利用可能なシーン名は __titleと__gameoverの2つで、__titleば内部状態の初期値になっています。

window.RPGAtsumaru.comment.resetAndChangeScene(sceneName)
引数: シーン名を表す文字列
戻り値: 無し

  • changeSceneと違い、context(contextfactorとminorcontext)による内部状態をリセットしつつシーンを切り替える
  • サーバーアクセスが発生する。(ただし直近5つのsceneはキャッシュされ、再アクセスには発生しない)
  • ツクールではタイトルとゲームオーバーで全員同じコメントが流れる機能のために使用しています

window.RPGAtsumaru.comment.pushContextFactor(factor)
引数: コメントシステムにpushするコンテキストを表す文字列
戻り値: 無し

  • コメントシステムにContextFactorとなる値(ツクールでいうセリフと選択肢)をpushして、contextを更新する。
  • contextが更新されたことでgposが更新され、文脈にあわせたコメントが流れる。
  • また、minor contextを初期化する。

window.RPGAtsumaru.comment.pushMinorContenxt()
引数: 無し
戻り値: 無し

  • コメントシステムのgposを更新する。
  • contextが更新されたことでgposKeyが更新され、文脈にあわせたコメントが流れる。
  • 内部的にminor context値を持っており、それを+1することでgposを更新している。pushContextFactorを使うと、minor context値は初期値に戻される
  • MinorContenxtは「ContextFactorのさらに細かい状態」を想定している。
  • ツクールではエンジンにwaitがかかるような命令で使用している。

window.RPGAtsumaru.comment.setContext(context)
引数: コンテキスト値を表す文字列
戻り値: 無し

  • pushContextFactorと違い、contextを引数に渡した値で直接書き換える。
  • 特定のScene内でまったく同じゲーム状態を厳密に作りたい場合に使う。
  • このときの context の値は、ascii 64文字以下推奨。(2017/9/8 追記)

VolumeAPI

VolumeAPI はマスターボリューム設定を可能にするAPIです。このAPIを利用することで、ゲームページのボリュームボタンが有効になります。
マスターボリュームは全体共通のボリューム設定で、RPGツクールMVのゲーム内オプションで設定できるパラメータとは別です。

window.RPGAtsumaru.volume.getCurrentValue()

引数: 無し
戻り値:  0~1の実数で表されるマスターボリューム

  • 現在のRPGアツマールのマスターボリューム値を取得する。

window.RPGAtsumaru.volume.changed.subscribe(observer)

引数: マスターボリューム情報を受け取るObserver
戻り値: subscription

  • RPGアツマールのマスターボリューム情報の変更を取得できるAPIです。
  • Observer, subscriptionについてはESNextのObservableを参照してください。

window.RPGAtsumaru.volume.changed.subscribe(next)

引数: マスターボリューム情報を受け取るコールバック
戻り値: subscription

  • 上記のAPI(RPGアツマールのマスターボリューム情報の変更を取得できるAPI)の引数に、コールバック関数を受け付けられるようにしたものです。
コメントを書く
コメントをするには、
ログインして下さい。