mruby for Pad Game System C++実装部ドキュメント

トップレベルメソッド

loadscript(String filename)

mrubyスクリプトを読み込んで実行します。requireはありませんので、これを使ってください。
スクリプトのファイル位置は(exeのあるフォルダ)/dataからの相対パスで指定します。

loadtext(String filename) → String

テキストファイルを読み込んで文字列として返します。素材以外の外部データの読み込み関数はこれだけです。JSONなどと組み合わせて処理してください。
ファイル位置は(exeのあるフォルダ)/dataからの相対パスで指定します。

sjis(String utf8str) → String

UTF-8の文字列をSHIFT-JISに変換した文字列を返すトップレベルメソッドです。
外部関数でSHIFT-JISを必要とする場合に使ってください。

utf8(String sjisstr) → String

SHIFT-JISの文字列をUTF-8に変換した文字列を返すトップレベルメソッドです。
mruby内部の文字列は基本的にUTF-8(BOMなし)であることを想定していますので、外部からSHIFT-JISの文字列を得た時等に使ってください。

uputs (...)

putsのUTF-8対応版です。UTF-8の日本語文字列を渡しても正しく表示します。
なお、事前にConsole.openを実行していない場合、表示する先がないので何も起きません。

uprint (...)

printのUTF-8対応版です。UTF-8の日本語文字列を渡しても正しく表示します。
なお、事前にConsole.openを実行していない場合、表示する先がないので何も起きません。

uprintf (String fmt,...)

printfのUTF-8対応版です。UTF-8の日本語文字列を渡しても正しく表示します。
なお、事前にConsole.openを実行していない場合、表示する先がないので何も起きません。

Gameモジュール

Game.window(Fixnum w,Fixnum h)

ウィンドウを指定した大きさで画面中央に作成します。単位はピクセルです。
ここで指定する大きさは素材の実サイズと対応する「論理サイズ」です。フルスクリーンモードの際には、画面は縦横比率を保った上での最大サイズに拡大され、余白は黒で埋められます。
この関数は一度しか呼んではいけません。二度目以降はエラーになります。
この関数を呼ぶと、そこでウィンドウのメインルーチンが始まります。
Game.initializeをまず呼び出し、その後Game.updateをフレーム更新時間ごとに呼びます。終了時にはGame.finalizeを呼びます。
つまり、この関数を呼ぶ前にGame.initialize Game.update Game.finalizeの定義は済ませておく必要があります。
このメインルーチンからは戻ってきませんので、これより下にスクリプトを書いても実行されません、ご注意ください。
このみっつの関数は自分で用意してください（内容がない場合でも空の関数が必要です）。引数も戻り値もありません。
このメソッドで表示したウィンドウを閉じると、プログラム自体が終了します。

Game.getwidth→Fixnum

画面の幅を得ます。

Game.getheight→Fixnum

画面の高さを得ます。

Game.okbox(String text,String caption)

「ＯＫ」のボタンがあるダイアログを表示し、入力がされるまで待ちます。その間ゲームの時間は停止します。

Game.yesnobox(String text,String caption) → Boolean

「はい」「いいえ」のボタンがあるダイアログを表示し、入力がされるまで待ちます。その間ゲームの時間は停止します。
「はい」を押せばtrue、「いいえ」を押せばfalseが戻ります。

Game.setscreenmode(Boolean isfull)

スクリーンモードを設定します。trueでフルスクリーンモード、falseでウィンドウモードです。

Game.getscreenmode → Boolean

スクリーンモードを返します。trueでフルスクリーンモード、falseでウィンドウモードです。

Game.caption(String caption)

ウィンドウタイトルを設定します。

Game.shell(String shellstr)

シェルで指定した文字列が表すURLもしくはファイルを開きます。URLを渡せばインターネットブラウザ、ファイル名を渡せばエクスプローラに登録されているソフトを使って開かれます。
ファイルは絶対パス名もしくはexeのあるフォルダからの相対パスで指定してください(./dataではありません)

Game.license([Boolean dontdelete])

ライセンス情報を表示します。ウィンドウが出ている時にAlt+Lで出るライセンス情報と同じものが表示されます。
dontdeleteは省略できますが、trueを指定するとライセンスのHTMLが消されなくなります（外部ツールから参照する時用です）

Game.gettimer → Fixnum

分解能の細かいタイマーです。ミリ秒単位でWindowsが起動してからどれだけ経過したかを返します。
このエンジンは固定フレームレートなので、アニメーション上の時間はフレーム数で測るべきですが、それ以外の時間計測で手軽に使うために用意されています。
なお、Windowsのタイマの返す値がunsigned intでありFixnumの範囲を超えているため、0x80000000で割った余りを返しています。

Game.sleep(Fixnum milisec)

エンジンの実行をスリープさせるメソッドです。単位はミリ秒です。すべての動きが止まります。

Game.movie(String filename,Boolean canskip[,Float volume])

画面全体にムービーを再生します。現在描画されているフレームがあれば無視され、エンジンはムービーの再生終了を待つモードに入ります。
canskipにtrueを指定すると、ムービーを入力で飛ばせます。falseを指定すると飛ばせません。
ボリュームは、指定しなければ0になります（最大です）。
このメソッドはNMVファイルを再生した時とその他のムービーを再生した時で動作が違います。
NMVファイルは通常と同様(exeのあるフォルダ)/dataからの相対パスで指定されます。NMVファイルと同名のOggファイルが同じフォルダにある場合、それをムービーの音声だと認識します。
NMVファイル以外（例えばMPEG-1）を再生した場合は、ファイル名は(exeのあるフォルダ)/movieからの相対パスです(dataではないので注意してください！)
NMVファイル以外のムービーファイルは、アーカイブに含めることが出来ません（だから別フォルダにしてあります）、メディアプレイヤーは外部プログラムなので様々なコーデックのインストール状況で不具合が生じうる、MPEG-1以外はインストールされているとは限らない、処理が重い、などの理由で、NMV形式よりも使いづらいのですが、NMV形式はモーションJPEGの都合上どうしてもファイルサイズは大きくなるので、サイズへの制約が厳しい場合はこちらを使ってください。

Game.update

画面を更新し、メッセージ処理をします。スクリプトは毎度なるべく一フレーム時間以内にこの関数を呼ぶ必要があります。

Drawモジュール

Draw.put(Texture)

フレームにテクスチャを描画します。これを実行する前に他のメソッドで描画設定をしておいてください。このエンジンのフレームへの描画命令はこれだけです。
描画設定はDraw.putを一回実行するごとに初期設定に戻ります。

Draw.reset

描画設定をリセットします。全部デフォルトになります。何かを描画すると自動でリセットされますが、描画せずにリセットしたい場合に使ってください。

Draw.to(Fixnum dx,Fixnum dy)

書き込み先を指定します。（通常は左上の）座標とα値です。α値は0～255です。指定しなければ0,0,255です。

Draw.from(Fixnum sx,Fixnum sy,Fixnum sw,Fixnum sh)

テクスチャ側の座標を指定します。sx,syを左上とし幅sw,shであることを指定します。指定しなければ0,0,(テクスチャの幅),(テクスチャの高さ)です。

Draw.lt(Float xs,Float ys,Float rot)

回転拡大縮小モード(ltモード)を指定します。回転拡大縮小モードを指定すると、Draw.toで指定したdx,dyの意味が画像の中心座標に変わります。

Draw.fill

フィルモードを指定します。Draw.ltと同時には使えません。テクスチャを均等に縦横に並べてフレームを埋めます。dx,dyの意味は、座標のずらし幅に変わります。フォグなどに使います。

Draw.blend(Fixnum blendmode)

ブレンドモードを設定します。デフォルトではDraw::DEFAULTです。

Draw::DEFAULT

通常の合成

Draw::ADD

加算合成

Draw::NEGA

反転合成

Draw.color(Float color0,Float color1,Float color2,Float color3)

頂点カラー左上、右上、左下、右下の順に0xAARRGGBBで指定します。デフォルトでは全部0xFFFFFFFFです。
αブレンディングは画像のα値とこの頂点のα値が反映されます。

Draw.alpha(Fixnum alpha)

α値を設定します。0xαFFFFFFを四頂点に設定します。
つまり、alphaに0x45を渡せば、Draw.color(0x45FFFFFF,0x45FFFFFF,0x45FFFFFF,0x45FFFFFF)と同じです。

Fontクラス

Font.new(Fixnum w,Fixnum h[,Fixnum weight,String facename]) → Font

フォントを作成します。

Font.style(Fixnum style[,...])

フォントのスタイルを設定します。これを使わなければ通常スタイル、白色が使われます。スタイルによって残りの引数が変わります。

フォントスタイル

Font::NORMAL

通常のスタイルです。文字色を渡してください。

Font::SHADOW

影付き文字です。文字色,影色,影位置x,影位置yを渡してください。影位置は元の字からの相対座標です。

Font::OUTLINE

袋文字です。文字色,外側の色を渡してください。

Font::GRADATION

グラデーションです。左上の文字色と右下の文字色を指定してください。

Font::FANCY

袋文字+文字色グラデーションです。左上文字色,右下文字色,外側の色を渡してください。左上～右下でグラデーションします。

fnt.delete

フォントを削除します。

fnt.put(Texture tex,String text,Fixnum x,Fixnum y)→Fixnum

設定されているフォントで指定された文字列をテクスチャに書き込みます。改行はしてくれませんので注意してください。
表示テキストは普通の文字列ですが、&だけは下で紹介する外字指定のように特殊な意味を持ちます。
戻り値に表示した字数を返します。

fnt.ext(String filename)

pngファイルを読み込んで、外字として設定します。pngはどんな形式でも構いませんが、色味は無視されますので256階調のpngが便利だと思います。
文字の大きさと同じ外字フォント画像を、左上から右下まで隙間なく並べてください（１列でも構いません）外字番号は、左上から0 1 2 3...右端まで行ったら下に降りて数えていきます。

fnt.icon(String filename)

pngファイルを読み込んで、アイコンとして設定します。pngはどんな形式でも構いません。色もそのまま表示されます（フォント色は反映されません）。
文字の大きさと同じアイコン画像を、左上から右下まで隙間なく並べてください（１列でも構いません）アイコン番号は、左上から0 1 2 3...右端まで行ったら下に降りて数えていきます。

Font.escape(String ext_char,String icon_char)

外字とアイコンとを表すのに使うエスケープ文字を一文字ずつ指定します（全角文字でも構いません）
例えば&を外字、@をアイコンに指定したとすると、&0 &1 &2...で外字0,1,2～、@0 @1 @2でアイコン0,1,2～を表示できます。
その文字そのものを表示したい場合は&&や@@のようにしてください。
このクラスメソッドを実行しておかないと、外字やアイコンは使えません。

Font.getwidth→Fixnum

画面の幅を得ます。

Font.getheight→Fixnum

画面の高さを得ます。

Font.split(text)→[char,char,char,...]

現在のフォントエスケープ文字設定も考慮した上で、文字列を一文字単位に分解して配列にして戻します。
一文字ずつ表示するのに使います。

Inputモジュール

Input.getpad(Fixnum padnum,Fixnum inputtype) → Fixnum

XBOXパッドからそのフレームでの入力を取得します。ボタンの場合は0=押されていない 1=押されている 2=押していたボタンを離した。
デジタル方向入力の場合は-1 0 1、アナログ方向入力の場合は-32768～32767、L2とR2はアナログトリガで、0～255です。
アナログ方向入力は、Y軸は上方向が正です(これはXInputの仕様です。画面座標系と反対ですのでご注意ください）。
アナログ方向入力のデッドゾーンの処理は適切に行なっていますので、スクリプト側では考慮しなくても大丈夫です。
デジタル方向入力は、Y軸は下方向が正です。これは画面座標系と合わせてあります。アナログと逆なのでご注意ください。
なお、キーボードからの入力の場合は、方向は８方向で絶対値の一番大きな数字が入ります。L2R2も最大値です。
種類に指定出来る値は以下のとおりです。

Input.getpadに指定できる値

Input::LX Input::LY

アナログ左スティック

Input::RX Input::RY

アナログ右スティック

Input::DX Input::DY

デジタル方向ボタン

Input::A B X Y L1 R1 L3 R3 START BACK

各ボタン(L3 R3は押し込みです)

Input:L2 Input:R2

アナログトリガ（後ろにあるほう）

Input::VX Input::VY

デジタル方向とアナログ方向をまとめてどれでも方向入力として受け取ります。DX DYと同様の-1 0 1です（正負も同じです）。アナログ入力を使わないゲームで、どのスティックでもデジタル方向入力させたいときに便利です。

なお、このエンジンではキーボード入力もパッドに割り当てて取得します。詳細はマニュアルのほうに記載されています。

Input.setpad(Fixnum padnum,Fixnum lmotor,Fixnum rmotor)

振動機能がある場合、パッドを振動させます。左モーター（低周波）と右モーター（高周波）のスピードを0～65535で指定します。

Input.getmouse(Fixnum inputtype) → Fixnum

マウス入力を得ます。ボタンの場合は0=押されていない 1=押されている 2=押していたボタンを離した。座標の場合は座標の値、ホイールWは-1 0 1 上が正です。
種類に指定できる値は以下のとおりです。Input::MX Input::MY……マウス座標（クライアント座標） Input::ML Input::MR……マウス左右ボタン
Input::MW……ホイール入力 Input::MM……マウス中ボタン（ホイールの押し込みがたいてい割り当てられています）
ここで戻るのは「ウィンドウに対する論理座標」です。フルスクリーンモードの場合、ちゃんとウィンドウモードの拡大率1:1であった場合の値に換算して戻ってきます。
なお、マウスが画面外に出ている場合、画面サイズからはみ出した値が戻ります。ご注意ください。

Input.setmouse(Fixnum x,Fixnum y)

マウスを指定した座標に移動します。

Textureクラス

Texture.new(Fixnum w,Fixnum h) → Texture
Texture.new(String filename) → Texture

テクスチャを作成します。引数２個の場合はサイズ、引数一個の場合はファイル名です。画像ファイルは(exeのあるフォルダ)/data/からの相対パスで指定します。

tex.fill(Float color)

テクスチャを指定色で塗りつぶします。α値も有効です。色は0xAARRGGBBで指定してください。
mrubyのWindows版のFloat型はdoubleなので、誤差なく受け取れます。

tex.delete

テクスチャを削除します。nilを代入したりスコープから外れたりであとでGCに回収されてもちゃんと削除されますが、解放タイミングがGC任せになるので、手動で先にハードウェアのリソースだけは開放できるようにしてあります。
deleteしたオブジェクトはそれ以降使ってはいけません（これは他のクラスも同じです）

tex.monotone(Float color)

指定した色でテクスチャをモノトーン化します。なお、色に指定したα値は無視されます。

tex.alpha()

テクスチャを「アルファチャンネル」に変えます。α値だけが取り出された白の塗りつぶし画像になります。
これを頂点カラーを変えて元の絵に加算合成することによって色付きの明滅等を表現できます。他にも使い方はいろいろあるかと思います。

tex.render

※注意※これは、テクスチャ「に」描画するメソッドです。テクスチャ「を」何かに描画するにはDraw.putメソッドを使います。
ここまでフレームに描画した内容をテクスチャに反映します。テクスチャはあらかじめフレームと同じ大きさで作られている必要があります。いわばスクリーンショットを取る機能です。
このメソッドでは画面は更新されません。これまでの描画内容は失われますので、また別の絵を画面のために描画してください。

tex.save(String filename)

テクスチャ内容をpngファイルに保存する命令です。デバッグ用に用意されています。

tex.getwidth → Fixnum

テクスチャの幅を得ます。

tex.getheight → Fixnum

テクスチャの高さを得ます。

Soundクラス

Sound.new → Ogg

空のサウンドオブジェクトを作成します。これはチャンネルのようなものです。作ったオブジェクトにボリューム等を設定し、音声ファイルを別途loadで読み込み、再生することが出来るようになります。

snd.delete

サウンドオブジェクトを削除します。

snd.load(String filename)

サウンドオブジェクトに音声ファイル(Ogg形式)をロードします。(exeのあるフォルダ)/dataからの相対パスです。

snd.play(Boolean isloop[,Boolean isfadein,Fixnum milisecond])

サウンドオブジェクトを再生します。
isloop=trueでループします。isfadein=trueでフェードインします。その場合milisecondに時間を指定してください（単位はミリ秒です）。後ろ２つは省略できます。

snd.stop

サウンドオブジェクトの再生を即時停止します。

snd.fadeout(Fixnum milisecond)

サウンドオブジェクトの再生をフェードアウトによって停止します。

snd.pause

サウンドオブジェクトの再生を一時停止します。あとでresumeで再開が可能です。

snd.resume

pauseで止めていたサウンドオブジェクトの再生を再開します。

ogg.volume(Float vol)

サウンドのボリュームを変更します。ボリュームは1で録音通り、0で無音、負の数は反転するようです(XAudio2の仕様)

snd.isplaying → Boolean

サウンドが再生中であればtrue、停止もしくはまだ再生していなければfalseを返します。

NMVクラス

NMV.new(String filename) → NMV

NMV形式のムービーファイルを指定してムービーオブジェクトを作ります。(exeのあるフォルダ)/dataからの相対パスです。
NMV形式は動画のみを扱い音声を扱いません。sceneメソッド以外では、音声は別途Soundオブジェクトを作って読み込み、同時にplayを掛けてください。

nmv.play(Boolean isloop,Boolean hasalpha)

ムービーの再生を開始します。α値付きの場合はhasalphaにtrueを、そうでない場合はfalseを指定してください。

nmv.delete

ムービーを停止し、オブジェクトを削除します。

nmv.totexture(Texture t)

ムービーの現在のフレームを指定したテクスチャにコピーします。大きさが動画と同じである必要があります。
もしムービーが新しいフレームをまだ描画していない場合は何もせずに戻ります。

nmv.totexturewait(Texture t)

ムービーの現在のフレームを指定したテクスチャにコピーします。大きさが動画と同じである必要があります。
もしムービーが新しいフレームをまだ描画していない場合は、描画するまで待ちます。作ったばかりのテクスチャに最初にフレームを取得するときに使うといいでしょう。

nmv.getwidth → Fixnum

ムービーの幅を得ます。

nmv.getheight → Fixnum

ムービーの高さを得ます。

nmv.isplaying → Boolean

ムービーが再生中ならtrue、停止しているか再生されていなければfalseを返します。

Databaseモジュール

Database.get(String key) → String

キーを指定して、保存されている値を得ます。値がない場合はnilです。

Database.set(String key,String value)

キーを指定して、値を保存します。値に許されるのはStringだけですので、JSONと組み合わせて使ってください。

Database.delete(String key)

データベースの指定したキーの値を削除します（nilになります）

Database.clear

データベースのすべてのキーを削除します。

Database.save

データベースを明示的に保存します。この命令を使わなくても正常終了時、もしくはたいていのエラー終了時にはファイルに保存されますが、電源ごと落としたりＯＳごとハングアップしたりした場合は保存されませんので、データベースへの書き込みの直後などにこの関数を呼んでおくと安全です。
データベースが大きいゲームだと多少の実行時間がかかるかもしれません。

Consoleモジュール

Console.open([Boolean license_safe])

デバッグコンソールを開きます。コンソールを使う命令を使う前にこれを使わないと、何も表示されません。
あくまでデバッグ用の機能ですので、リリースする商品ではコンソールは開かないほうがいいと思います。
なお、print、printf、putsについては、UTF対応していませんので、代わりにUTF-8対応版であるuprint uprintf uputs があります。こちらを使ってください。
引数のlicense_safeは省略できます。普通の動作ではGUIウィンドウがないときにConsole.openするとライセンス情報を表示するのですが、license_safeにtrueを指定すると表示しなくなります（別の方法でライセンスは表示するようにしてください）

Console.pause

デバッグコンソールで「続行するには何かキーを押してください．．．」を表示して入力待ちを実行します。
デバッグコンソールに何か表示した後、プログラムを終了する前に待たせたい場合に使います。

Console.readline → String

デバッグコンソールから一行テキストを読み込んで返します。文字列はUTF-8に変換されます。改行文字は削られます。

Shareモジュール

Share.create(String name,Fixnum size)

プロセス間通信用のメモリマップドファイルを作成します。sizeはメモリマップドファイルのサイズです。
メモリマップドファイル名はname+"_mem"、同期処理用のMutexの名前はname+"_mutex"です。
なお、メモリマップドファイルを開いている場合、プログラム終了時にそれを他のプログラムに伝えるために"exit"を書き込みます。
"exit"を読み出したら終了したと判断して、必要な処理をしてください。

Share.open(String name)

他のプロセスで作成されたプロセス間通信用のメモリマップドファイルを開きます。
メモリマップドファイル名はname+"_mem"、同期処理用のMutexの名前はname+"_mutex"です。

Share.read → String

メモリマップドファイルを読み込みます。

Share.write(String data)

メモリマップドファイルに書き込みます。

Share.delete

createで作ったメモリマップドファイルを削除します。

Developモジュール

Develop.getcommandline → Array

コマンドライン引数を文字列の配列で得ます。

Develop.ns2(String filename,String dirname)

指定したディレクトリをfilenameで指定したNS2アーカイブにまとめます。
普通はdataフォルダを指定して00～99.ns2にすることになると思います。大抵の場合は00.ns2のはずです(01.ns2～99.ns2は追加データです)

Develop.nmvjpeg(String filename,String dirname,Float fps)

指定したディレクトリにある連番のjpegファイルを連結してfilenameで指定したNMVムービーファイルにします。

Develop.nmvpng(String filename,String dirname,Float fps,Fixnum quality)

指定したディレクトリにある連番のPNGファイルを連結してfilenameで指定したNMVムービーファイルにします。
こちらは透過度が反映されます（透過度がいらない場合は連番jpegを使ってnmvjpegに掛けてください。
qualityには動画圧縮の際の画像品質を指定してください。これは普通のJPEGの圧縮品質と同じです。

ファイル名指定について

ファイル名の頭に|をつけると、それはdataフォルダの中ではなくフルパス名で指定されているとみなします。
ツール類を作るのに便利なのでこういう仕様にしていますが、ゲームを作るときには使わないでください。
ゲームの素材はdataの中に全部格納して、扱いを統一したいからです。