• このエントリーをはてなブックマークに追加
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.htmにrpgatsumaru.jsを挿入することで実現しています。
APIの仕様はまだ暫定であり、追加・更新の可能性があります。

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

■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種のキーはアツマール側のセーブ管理画面で、それぞれ「システムファイル」と「ファイル N」として扱われます。この二つ以外はゲーム上で「その他」と表示されます。

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


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

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

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


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

上記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 追記)
コメントを書く
コメントをするには、
ログインして下さい。