engine/design/lua – PlaygroundOSS

Luaスクリプトインタフェース ¶

ここでは、タスクとは独立したLuaインタフェース関数について解説します。

汎用タスクマニュアル

スクリプトの実行ルール ¶

スクリプトはロードされた直後、グローバル域とsetup()が実行される
毎フレームP_SCRIPTフェーズにexecute()が呼ばれる。
sysLoad()関数を用いて他のスクリプトに移動することが決定したとき、leave()が呼ばれる。
sysLoad()で指定された移動先のスクリプトがロードされるのは、次のフレームのP_SCRIPTフェーズ。

タスクの実行ルール ¶

タスクは、起動関数を呼ぶことで起動される。
起動関数は、必ずタスクのポインタを返す。
起動中のタスクに対しコマンドを与える際は、sysCommand()関数を使用する。第一引数は対象タスクのポインタ、第二引数が各タスクによって定義されるコマンド値となる。引数が必要な場合は、第三引数以降に続ける。
起動中のタスクを個別に破棄するには、TASK_kill() 関数を用いる。
「ステージタスク」として登録されているタスクは、TASK_StageClear()関数でまとめて破棄することができる。
起動したタスクを「ステージタスク」として登録する場合は、TASK_StageOnly()関数にタスクのポインタを与える。
タスクが起動すると自動的に「ステージタスク」になるように実装されているケースもある。

Luaスクリプト関数リファレンス ¶

システム関数
ID/KeyChain関数
GL関数
GuardBand関数
アプリケーション起動関数
デバッグモード関数
システムリソース情報ダンプ関数
Engine情報関数
フォント情報関数
ASSET情報関数
データセット関数
タスク関数
サウンド関数
ユーティリティ関数
データ変換関数
言語DB関数
SQLiteインタフェース関数
バイナリデータインタフェース関数
マトリクス/ベクトル演算関数

システム関数 ¶

sysReboot

全ゲーム環境を破棄し、起動シーケンスから再実行する

sysReboot
```
   sysReboot()
```

sysLoad

指定されたスクリプトに制御を移す。コールされた時点で、現在定義されているleave()関数を呼び、次のフレームのexecute()実行前に指定されたスクリプトをロード、グローバル域とsetup()を実行する。

sysLoad

   sysLoad(<移行先スクリプトのパス名>)

sysCommand

動作中のタスクに対し、そのタスクが受け付けるコマンドを発行する。第一引数はコマンド実行対象となるタスクのポインタ、第二引数はそのタスクが受け付けるコマンドの値となる。引数がある場合は第三引数以降に指定される。また、コマンドによっては戻り値を持つ。

sysCommand

   [ <戻り値> = ] sysCommand(<タスクポインタ>, <コマンドID> [, ...] )

syslog

デバッグに用いられるログ文字列を出力する。出力先およびその形式は、実行されるプラットフォームに依存する。

syslog
```
   syslog(<出力文字列>)
```

sysExit

ゲームシステムの実行を終了し、OSに制御を戻す。アプリケーションが「自己判断で終了する」という概念を持たないプラットフォームでは対応していない(例:iOS)。

sysExit
```
   sysExit()
```

include

指定されたスクリプトファイルの内容が、さもその場所にあるかのように取り込む。スクリプト間で共通する定義を別ファイルにまとめ、取り込む際などに使用する。

include

   include(<インクルードスクリプトのパス名>)

sysInfo

実行環境についてのシステム情報をテーブルとして返す。現時点で対応しているのは width(画面幅)とheight(画面高)のみ。

sysInfo

   <システム情報テーブルを受け取る変数> = sysInfo()

ID/KeyChain関数 ¶

KEY_genUserID

IDとして使用できる値を自動生成する。

KEY_genUserID
```
   <id-string> = KEY_genUserID()
```

KEY_genUserPW

パスワードとして使用できる値を自動生成する。

KEY_genUserPW

   <password-string> = KEY_genUserPW("<id-string>")

KEY_setSecureID

文字列を指定されたサービス名のIDとして、keychainに登録する。

KEY_setSecureID

   <result> = KEY_setSecureID("<service-name>", "<id-string>")

KEY_setSecurePW

文字列を指定されたサービスのパスワードとして keychain に登録する。

KEY_setSecurePW

   <result> = KEY_setSecurePW("<service-name>", "<password-string>")

KEY_getSecureID

keychainをサービス名で検索し、登録されているIDを返す。IDが登録されていない場合はnilを返す。

KEY_getSecureID

   <id-string> = KEY_getSecureID("<service-name>")

KEY_getSecurePW

keychainをサービス名で検索し、登録されているパスワードを返す。パスワードが登録されていない場合はnilを返す。

KEY_getSecurePW

   <password-string> = KEY_getSecurePW("<service-name>")

KEY_delSecureID

keychain中から指定されたサービス名で登録されているIDを削除し、未登録状態にする。元々登録されていない場合は何もしない。

KEY_delSecureID
```
   KEY_delSecureID("<service-name>")
```

KEY_delSecurePW

keychain中から指定されたサービス名で登録されているパスワードを削除し、未登録状態にする。元々登録されていない場合は何もしない。

KEY_delSecurePW
```
   KEY_delSecurePW("<service-name>")
```

GL関数 ¶

GL_ClearColor

OpenGL ES のglClearColor()と同じ。GLのクリア色を指定する。

GL_ClearColor

   GL_ClearColor(<red>, <green>, <blue>, <alpha>)
   
   ※各要素は 0.0～1.0 で指定する。

GL_SetResolution: 論理描画領域の解像度を指定する。プログラムはその描画面積があるものとして動作するが、表示は物理解像度に合わせ比率を保ったまま拡大または縮小される。デフォルトの状態における論理解像度は物理解像度と一致する。

borderlessがオプションですが、設定をtrueにすると論理描画と物理画面の比率が会わない場合、右左や上下に枠が描画可能になり、

左や上に描画したい場合、理論座標システムは次になります。

[-borderHorizontal, -borderHorizontal] .. [width + borderHorizontal, height + borderVertical]

つまり、borderlessをtrue/falseにしても、[0,0]-[width,height]は同じ場所にあります。
   GL_SetResolution(<width>, <height> [,<borderless = false>])

See also : GL_GetHorizontalBorder, GL_GetVerticalBorder.

   -- Sample Code : Bordeless when screen is larger than logical screen.
   GL_SetResolution(width, height)
   if (GL_GetHorizontalBorder() != 0) then
     GL_SetResolution(width, height, true)

GL_Unloadtexture

GL_Unloadtextureを使って、すべてのOpenGLのtextureを開放する。

　GL_Unloadtexture()

GL_Reloadtexture: GL_Reloadtextureを使って、GL_Unloadtextureに開放されたTextureを回復する。

WARNING:GL_Unloadtextureと一緒にセットで使ってください。しないとリークします！

分かれているの存在理由はOSが勝手に開放された場合、復活させる関数もほしかったので、機能がわかれているが、基本ではセットで使ってください！
　GL_Reloadtexture()

SG関数 ¶

SG_GetGuardBand

現在のGuardBand情報を返す。X0,Y0,X1,Y1

SG_GetGuardBand
```
   x0,y0,x1,y1 = SG_GetGuardBand()
```

SG_SetGuardBand: 描画・計算処理を軽くするため、ノードの座標がGuardBand外に移動した場合、処理をしない事になります。

おかしいな描画・描画に表れない事につながる事になります。

GuardBandの座標は画面の空間でピクセルで設定する。

例えば：SG_SetGuardBand(-500.0, -400.0, 1500.0, 1400.0) この場合、(-500, -400)を以下に物置いた場合、処理・描画が行わない。同じく、+1500,+1400を超えた場合にも、処理・描画が行わない。

ノードにつながっている描画オブジェクトのサイズや中心もあるため、ぎりぎりなサイズで使わない方が良い。基本的に大変横・立ての長いのリスト・物の一覧があった時に利用する。

   SG_SetGuardBand(<x0>, <y0>, <x1>, <y1>)

アプリケーション起動関数 ¶

APP_CallApplication

指定された機能を持つ、プラットフォーム上のアプリケーションを起動する。起動されるアプリケーションそのものや、機能の対応状況、アプリケーション起動時の状態はプラットフォームに依存する。

APP_CallApplication

   <result> = APP_CallApplication(<app-type>, ... )

   <app-type> アプリケーション機能のタイプ。
      APP_MAIL  メールアプリケーション
        APP_CallApplication(APP_MAIL, <address>, <subject>, <body>)

      APP_BROWSER Webブラウザ
        ※現在未対応

      APP_UPDATE アプリケーションのアップデートを行うシステムアプリ(例: iOSの場合は AppStore が該当)
        APP_CallApplication(APP_UPDATE, <search-key>)

   <result> 指定されたアプリケーションの起動に成功したら true, 失敗したり非対応である場合は false

デバッグモード関数 ¶

DEBUG_SetCallback

デバッグモード終了時に設定値を受け取るLuaのコールバック関数を指定する。

DEBUG_SetCallback

   DEBUG_SetCallback("<コールバック関数名>")

DEBUG_AddItem

デバッグモードのセクションと、セクションに属する刻目を追加する。

DEBUG_AddItem

   DEBUG_AddItem("<セクション名>", "<セクションkey名>", {
       { DBG_M_SWITCH, "<項目名>", "<項目key名>", <デフォルト値(true/false)> }.
       { DBG_M_SELECT, "<項目名>", "<項目key名>", "<デフォルト値>", { "<項目1>", "<項目2>", ... , "<項目n>" }},
       { DBG_M_NUMBER, "<項目名>", "<項目key名>", <下限値>, <上限値>, <デフォルト値> }
   })

     項目は、ON/OFF型(DBG_M_SWITCH)、選択型(DBG_M_SELECT)、整数型(DBG_M_NUMBER) の三種類が作れる。
     DBG_M_SELECT の <デフォルト値> は、その後の項目リスト中に存在する文字列である必要がある。
     項目内に存在しない<デフォルト値>を指定した場合、先頭の項目がデフォルトとなる。

DEBUG_DelItem

指定されたkey名を持つセクションを削除する

DEBUG_DelItem

   DEBUG_DelItem("<セクションkey名>")

デバッグモード生成の流れ ¶

DEBUG_SetCallback("debugCallback")  -- コールバックの設定

DEBUG_AddItem("Default enemy parameters", "enemy", {  -- 敵の設定
    { DBG_M_SWITCH, "Phisical attack", "phisical" true },  -- 物理攻撃の使用(on/off)
    { DBG_M_SWITCH, "Use magic",       "magic",   true },  -- 魔法の使用(on/off)
    { DBG_M_SWITCH, "Use skill",       "skill",   true },  -- スキルの使用(on/off)
    { DBG_M_SELECT, "Tactics",         "tactics", "normal", { "normal", "power", "defence", "away" } }, -- 使用戦術(通常/攻撃重視/防御重視/逃亡)
    { DBG_M_NUMBER, "HitPoint",        "hp",      1000, 30000, 2500 }, -- HPの値
    { DBG_M_NUMBER, "MagicPoint",      "mp",      0, 500, 300 }        -- MPの値
})

DEBUG_AddItem("World flags",  "world", {  -- ワールド設定
    { DBG_M_SWITCH, "Castle Pass",  "castle", true },  -- 城の通行証(on/off)
    { DBG_M_SWITCH, "River bridge", "bridge", false },  -- 川の橋(on/off)
    { DBG_M_SWITCH, "Cave door",    "cave",   false },  -- 洞窟の扉(on/off)
    { DBG_M_SWITCH, "Hell Gate",    "hell",   false },  -- 地獄の門(on/off)
})


function debugCallback(tbl)

   --[[
      上記のデバッグモード設定でメニューを生成した場合、
      デフォルト状態で渡されるテーブルの値は次のようになります。
   ]]
   tbl = {
     "enemy" = {
       "phisical" = true,
       "magic" = true,
       "skill" = true,
       "tactics" = "normal",
       "hp" = 2500,
       "mp" = 300
     },
     "world" = {
       "castle" = true,
       "bridge" = false,
       "cave" = false,
       "hell" = false
     }
   }
end

システムリソース情報ダンプ関数 ¶

RES_DumpSceneGraph

SceneGraph のツリー情報をコンソールに出力する。引数を与えない場合はrootノードから、 UIタスクのポインタを与えた場合はそのタスクが持つコントロールノード以下のツリー情報を出力する。

RES_DumpSceneGraph()

   RES_DumpSceneGraph( [ <UI-task-pointer> ] )

RES_DumpRendering

RES_DumpRendering

RES_DumpAsset

使用中の asset をコンソールにダンプする。

RES_DumpAsset
```
   RES_DumpAsset()
```

RES_DumpTexturePacker

RES_DumpTexturePacker

RES_DumpGeometryCost

RES_DumpGeometryCost

Engine情報関数 ¶

ENG_isRelease

現在動作しているEngineがReleaseビルド版であるかどうかを返す。 Releaseビルドの場合は true, それ以外の場合は false を返す。

ENG_isRelease
```
   <result> = ENG_isRelease()
```

ENG_getPlatform

現在Engineが動作しているOSとそのバージョン情報、および設定されているTIMEZONEを返す。 Releaseビルドの場合は true, それ以外の場合は false を返す。

ENG_getPlatform

   <version string> = ENG_getPlatform()

   version string は、下記フォーマットで与えられる。
　　　"<OS名>;<version>;<timezone>"

   例) "iOS;5.1;JST"

ENG_getNanoTime

porting layer で実装されている、システムのナノ秒単位カウンタ値を取得する。 epoch はシステム依存だが、2回以上の呼び出しで得られた値の差分から経過時間の計測を行える。

ENG_getNanoTime

   <milli-second-time>, <nano-second-time> = ENG_getNanoTime()

   <milli-second-time>  ミリ秒単位の時間
   <nano-second-time>   ナノ秒単位の時間。0～999999の範囲をとる。

ENG_getFrameID: タスクマネージャが各フレームに対し発行している FrameID の値を取得する。この値は毎フレームインクリメントされる16bitの値であり、0xffffの次は 0x0000 となる。隣り合うフレームではこの値が異なることが保証される。

ENG_getFrameID
```
   <frame-id> = ENG_getFrameID()
```

ENG_startNanoTime

ナノ秒単位の時間計測を開始する。最大10個までのタイマーを用いることができる。

ENG_startNanoTime

   ENG_startNanoTime(<timer-id>)

   <timer-id> 0～9が指定可能

ENG_endNanoTime

指定した<timer-id>において、最後の ENG_startNanoTime() もしくは ENG_endNanoTime() の呼び出しから経過した時間をナノ秒単位で取得する。

ENG_endNanoTime

   <milli-sec>, <nano-sec> = ENG_endNanoTime(<timer-id>)

ENG_getElapsedTime

OSの起動からの経過時間を秒単位で取得する。

ENG_getElapsedTime
```
   <sec> = ENG_getElapsedTime()
```

ENG_forbidSleep

端末画面の無操作ロックタイムアウトを無効/解除する。

ENG_forbidSleep

   ENG_forbidSleep(<is_forbidden: true / false>)

フォント情報関数 ¶

フォント情報関数は、フォント描画に関連する値の取得に使用されます。

FONT_load

フォントファイルをロードして利用可能になります。

FONT_load

  bResult = FONT_load("<logicalName>","<asset://...ttf>")

FONT_create

フォント情報オブジェクトを生成する。取得したフォント情報は、フォントによる描画情報の計算に使用される。

FONT_create

  <font-object> = FONT_create(<font-size>, "<font-name>")

FONT_release

フォント情報オブジェクトを破棄する。

FONT_release

   nil[, nil, ... ] = FONT_release(<font-object> [, <font-object>, ... ])

FONT_getTextInfo

フォント情報と文字列を指定して「その文字列を描画するために必要な位置と面積の情報」を取得する。

FONT_getTextInfo

   <draw-info> = FONT_getTextInfo(<font-object>, "<string>")

   <draw-info> = {
       "width" = <draw-width>,
       "height" = <draw-height>,
       "ascent" = <ascent>,
       "descent" = <descent>,
       "top" = <top>,
       "bottom" = <bottom>
   }

ASSET情報関数 ¶

ASSET_getImageSize

指定された画像assetの元画像サイズを返す。

ASSET_getImageSize

   <width>, <height> = ASSET_getImageSize("<asset-path>")

ASSET_getBoundSize

指定された画像assetが持つ全頂点のバウンディングボックスサイズを返す

ASSET_getBoundSize

   <width>, <height> = ASSET_getBoundSize("<asset-path>")

ASSET_getAssetInfo

指定された画像assetのサイズ情報をまとめて取得する。

ASSET_getAssetInfo

   <img-width>, <img-height>, <bound-width>, <bound-height> = ASSET_getAssetInfo("<asset-path>")

データセット関数 ¶

データセットは、個々のタスクに代わってデータを保持し続けるための仕組み。データセットを使用するタスクは、あらかじめデータセットを使用するものとして実装されている必要がある。

通常、各アセットはリファレンスカウンタによる管理で使用者がいなくなると自動的に解放される。同じアセットを繰り返し使いまわしたい場合、そのアセットを使用するタスクが一時不在になった後、再度同じアセットを使用すると再ロードが発生するため、処理負荷が大きくなる。

これを防ぐため、各タスクの代理としてアセットを保持し続けるのがデータセットであり、データセットを利用するタスクは、指定されたデータセットからデータを借りてくる形で実装される。

DATA_create

指定されたIDでデータセットを生成し、そのポインタを返す。

DATA_create

   <データセットポインタ受取変数> = DATA_create(<データセットに与えるID>)

DATA_register

指定されたデータセットのポインタに対し、データを個別に登録する。データセットのポインタとアセットのパス名、データに与える名称を指定する。

DATA_register

   DATA_register(<データセットポインタ>, <アセットパス名>, <データセット内でアセットに与える名称>)

DATA_regtable

指定されたデータセットのポインタに対し、複数のデータを一括で登録する。与えるデータはLuaのテーブルで指定する。

DATA_regtable

   -- 登録データ配列
   assetList = {
      { <アセットパス名>, <データセット内でアセットに与える名称> },
       :
   }

   DATA_regtable(<データセットポインタ>, assetList )

DATA_delete

生成済みのデータセットを破棄する。データセットに登録されたデータを使用中のタスクがある場合はエラーとなる。

DATA_delete

   DATA_delete(<データセットポインタ>)

タスク関数 ¶

タスク関数は、基本的にタスクの生成/破棄を管理する。また、タスクがスクリプトからアクセス可能なプロパティを持つ場合、アクセス手段を提供する。起動されている特定のタスクに対して処理を行うものが多いため、タスク関数で扱いたいタスクについては、起動関数の戻り値として返されるタスクのポインタを保持しておく必要がある。

TASK_kill

タスクポインタで指定されたタスクに対し、破棄指令を出す。破棄指令が出されたタスクは、そのフレームの最後に破棄される。 TASK_kill() は必ずnil値を返す。また、破棄対象のタスクポインタとしてnil値が渡された場合は何もしない。

TASK_kill

   [ <nil値を受け取る変数> = ] TASK_kill( <破棄対象となるタスクのポインタ> )

   例)
   pTask = TASK_kill(pTask)

   上の例はpTaskが示すタスクに破棄指令を出した後、pTaskの値がnilになるので、
   複数回実行された場合の事故防止になる。

TASK_registerkill

タスクポインタで指定されたタスクに対し、killが発生した時のコールバックを設定出来る仕組みです。

TASK_registerkill

   TASK_registerkill( <タスクのポインタ>, <コールバック関数名> )

TASK_isKilled

ポインタで指定されたタスクが、すでに破棄指令を何らかの形で出されているか否かを返す。「何らかの形」とは、TASK_kill()関数のほか、TASK_StateClear() による破棄や、親タスクの破棄による連鎖破棄なども含まれる。

TASK_isKilled

   <is-killed-status> = TASK_isKilled( <破棄対象となるタスクのポインタ> )

   <is-killed-status> (bool)   破棄指令が出されている場合は true, まだ出されていない場合は false

TASK_StageOnly

タスクポインタで指定されたタスクを「ステージタスク」として登録する。「ステージタスク」は「現在のステージでのみ使用されるタスク」という概念で、ステージの終了を告げる TASK_StageClear() のタイミングで破棄対象とされる。 TASK_StageOnly()でステージタスクにしたタスクを TASK_kill() で破棄しても、特に問題はない。

TASK_StageOnly

   TASK_StageOnly( <ステージタスクにするタスクのポインタ> )

TASK_StageClear

この関数が呼ばれたフレームの最後に、TASK_StageOnly()でステージタスク登録されたタスク全てに対し破棄指令を出す。これは、TASK_StageClear()を呼んだ後に起動され、TASK_StageOnly()で登録されたタスクも対象となる。つまり、そのフレームの最後までにステージタスクとして登録され、破棄されていないタスクはすべて破棄対象となる。

TASK_StageClear
```
   TASK_StageClear()
```

TASK_getProperty

タスクがスクリプトに対し公開プロパティを持つ場合、その値をLuaテーブルとして取得する。公開プロパティを持たないタスクの場合はエラーとなる。

TASK_getProperty

   <受取Luaテーブル> = TASK_getProperty( <プロパティを取得するタスクのポインタ> )

TASK_setProperty

TASK_getProperty() で取得したのと同じ形式のLuaテーブルをタスクの新たなプロパティ値として受け取り、指定されたタスクに設定する。公開プロパティを持たないタスクや、プロパティがread onlyであるタスクに対してはエラーとなる。また、指定されたLuaテーブルが、タスクのプロパティリストにない名称のメンバを持つ場合もエラーとなる。

TASK_setProperty

   TASK_setProperty( <プロパティを設定するタスクのポインタ>, <プロパティ値を持つLuaテーブル> )

TASK_Pause

特定のタスクをpause状態を操作する。 pause状態にあるタスクは、毎フレームの execute() 呼び出しが行われなくなる。

TASK_Pause

   TASK_Pause( <対象タスクのポインタ>, <pause状態(true/false)>[, <再帰指定(true/false)>] )

   上記の<pause状態>をtrueにすることでpause、falseでpause解除となる。
   子タスクを持つタスクを指定した場合、再帰指定がtrueだと子タスクも同じpause状態を与えられる。
   再帰指定がfalseの場合子の状態は変化しない。再帰指定は省略でき、省略時の値はtrueとなる。

サウンド関数 ¶

SND_Open

サウンドデータを開いて再生準備を行う。また、そのサウンドデータを操作するためのハンドルを返す。

SND_Open

   <sound-handle> = SND_Open("<sound asset>" [, <BGM-mode(true/false)> ])

   <sound asset>に指定するファイル名は拡張子抜きで指定してください。
     × SND_Open( "soundtest.mp3" )
     ○ SND_Open( "soundtest" )

   <BGM-mode>をtrueにすると、ループ再生されるBGMとして扱われる。再生開始が遅いのでSEには不向き。
   <BGM-mode>をfalseにすると、SEとしてサウンドデータをロードし、オンメモリでの待機状態になる(プラットフォームによって異なることがある)。

   <BGM-mode>のデフォルトは false

SND_setBufSize

サウンドデータをBGM再生する際のバッファサイズを三段階(大中小)から選択する。具体的にどのような値が再生系に与えられるかは、プラットフォームによって異なる(場合によっては特に何も行わないプラットフォームも考えられる)。

SND_setBufSize

    SND_setBufSize(<sound-handle>, <buffer-size-level>)

    <buffer-size-level>
      SND_BUF_SMALL   [小]時刻取得の分解能がより細かくなることが期待できる。
      SND_BUF_MEDIUM  [中]標準。デフォルトのサイズ。
      SND_BUF_LARGE   [大]標準より大きなサイズ。iOSでは標準の2倍。

SND_Close

SND_Openによって得られた<sound-handle>を解放し、nilを返す。

SND_Close

   nil[,...] = SND_Close(<sound-handle> [, ... ] )

   同時に複数の <sound-handle> を解放できる。引数として与えられた個数分、
   戻り値として nil を返す。

SND_Play

SND_Openによって得られた<sound-handle>で指定されるサウンドデータの再生を開始する

SND_Play

   SND_Play(<sound-handle>, <mili-sec>, <terget-vol>, <volume>)

   以下の項目は入力スキップ可能
  <mili-sec>       フェードにかかる時間(ミリ秒) デフォルト:0
  <terget-vol>    フェード終了時の音量0.0~1.0で指定。 デフォルト:1.0
  <volume>        サウンドの再生開始時のボリューム

SND_Stop

<sound-handle>で指定される再生中のサウンドデータについて、再生を停止する。

SND_Stop

   SND_Stop(<sound-handle>, <mili-sec>, <terget-vol>)

   以下の項目は入力スキップ可能
  <mili-sec>       フェードにかかる時間(ミリ秒) デフォルト:0
  <terget-vol>    フェード終了時の音量0.0~1.0で指定。 デフォルト:0.0

SND_Pause

<sound-handle>で指定される再生中のサウンドデータについて、再生を一時停止する。

SND_Pause

   SND_Pause(<sound-handle>, <mili-sec>, <terget-vol>)

   以下の項目は入力スキップ可能
  <mili-sec>       フェードにかかる時間(ミリ秒) デフォルト:0
  <terget-vol>    フェード終了時の音量0.0~1.0で指定。 デフォルト:0.0

SND_Resume

<sound-handle>で指定される一時停止中のサウンドデータについて、再生を再開する。

SND_Resume

   SND_Resume(<sound-handle>, <mili-sec>, <terget-vol>)

   以下の項目は入力スキップ可能
  <mili-sec>       フェードにかかる時間(ミリ秒) デフォルト:0
  <terget-vol>    フェード終了時の音量0.0~1.0で指定。 デフォルト:1.0

SND_Fade

<sound-handle>で指定される再生中のサウンドデータについて、<mili-sec>分の時間でフェード音量を<terget-vol>の値にする。

SND_Fade

   SND_Fade(<sound-handle>, <mili-sec>, <terget-vol>)

  <mili-sec>       フェードにかかる時間(ミリ秒) 
  <terget-vol>    フェード終了時の音量0.0~1.0で指定。

SND_Seek

<sound-handle>で指定されるサウンドデータについて再生位置をミリ秒で指定する。

SND_Seek

   SND_Seek(<sound-handle>, <milli-sec>)

SND_Tell

<sound-handle>で指定されるサウンドデータについて再生位置をミリ秒で取得する。

SND_Tell

   <milli-sec> = SND_Tell(<sound-handle>)

SND_getLength

<sound-handle>で指定されるサウンドデータについて総演奏時間をミリ秒で取得する。

SND_getLength

   <milli-sec> = SND_getLength(<sound-handle>)

SND_Volume

<sound-handle>で指定されるサウンドデータについて、音量を設定する。

SND_Volume

   SND_Volume(<sound-handle>, <volume>)

   <volume> 0.0(無音) ～ 1.0(最大) の間で指定

SND_Pan

<sound-handle>で指定されるSEデータについて、パン位置を設定する。

SND_Pan

   SND_Pan(<sound-handle>, <pan>)

   <pan> 中央を 0.0 とし、左最大が -1.0, 右最大が 1.0

SND_VolumeBGM

SND_Open()関数の<BGM-mode>をtrueとしてオープンされたBGMサウンド全体に対するマスターボリュームを設定する。 <BGM-mode>がfalseであるSEサウンドは影響を受けない。

SND_VolumeBGM

   SND_VolumeBGM(<volume>)

   <volume> 0.0(無音)～1.0(最大) の範囲で指定。

   実際の再生音量は、ここで指定された<volume>と、サウンド個別に指定された<volume>を掛けた値となる。

SND_VolumeSE

SND_Open()関数の<BGM-mode>をfalseとしてオープンされたSEサウンド全体に対するマスターボリュームを設定する。 <BGM-mode>がtrueであるBGMサウンドは影響を受けない。

SND_VolumeSE

   SND_VolumeSE(<volume>)

   <volume> 0.0(無音)～1.0(最大)の範囲で指定。

   実際の再生音量は、ここで指定された<volume>と、サウンド個別に指定された<volume>を掛けた値となる。

SND_VolumeFormSE

UI_FormでオープンされたSEサウンド全体に対するマスターボリュームを設定する。

SND_VolumeFormSE

   SND_VolumeFormSE(<volume>)

   <volume> 0.0(無音)～1.0(最大)の範囲で指定。

   実際の再生音量は、ここで指定された<volume>と、SEのマスターボリュームと、サウンド個別に指定された<volume>を掛けた値となる。

SND_State

<sound-handle>で指定されるサウンドの状態を取得する。

SND_State

   <state> = SND_State(<sound-handle>)

   <state> サウンドハンドルで指定したサウンドの状態、戻り値の定数は以下の通りです。
                SND_STATE_PLAY                      ・・・  再生中
                SND_STATE_PAUSE                    ・・・  一時停止中
                SND_STATE_STOP                      ・・・  停止中
                SND_STATE_INVALID_HANDLE   ・・・  無効なハンドルです。

SND_MultiProcess

SND_MultiProcess

   SND_MultiProcess(<process-type>)    

   <process-type> で指定したタイプによってミュージックアプリとの挙動を変更します。(2013/4/8現在iPhoneのみ対応)
                SND_MULTIPROCESS_MUSIC_CUT                      ・・・  ゲームアプリのサウンドがミュージックアプリより優先(ゲーム起動時デフォルト)
                SND_MULTIPROCESS_SOUND_CUT                    ・・・  ミュージックアプリ再生中はゲームアプリのサウンドが全てOFF
                SND_MULTIPROCESS_SOUND_BGM_CUT            ・・・  ミュージックアプリ再生中はゲームアプリのBGMサウンドのみOFF

SND_PauseOnInterruption

SND_PauseOnInterruption

   SND_PauseOnInterruption(<bInterruption>)    

   <bInterruption> で指定したbool値によってアプリのサスペンド時にエンジンでサウンドの一時停止などを制御するかを設定(2013/6/10現在iPhoneのみ対応)
                true          ・・・  サウンドのサスペンド処理をエンジンで制御する(ゲーム起動時デフォルト)
                false         ・・・  サウンドのサスペンド処理をエンジンで制御しない

ユーティリティ関数 ¶

bitOR

引数すべてを整数とみなし、そのすべてのビットごとの OR をとった値を返す。整数とみなすことができない値を引数として与えた場合はエラーとなる。

bitOR

   <ORの結果> = bitOR(<int値> [, <int値>[, ... ] ] )

bitAND

引数すべてを整数とみなし、そのすべてのビットごとの AND をとった値を返す。整数とみなすことができない値を引数として与えた場合はエラーとなる。

bitAND

   <ANDの結果> = bitAND(<int値> [, <int値>[, ... ] ] )

データ変換関数 ¶

各種データをLuaから扱いやすい形式に変換する機能を提供している。

CONV_Lua2Json

Luaテーブルを同じ構造を持つJSON文字列に変換する。

CONV_Lua2Json

   <JSON文字列> = CONV_Lua2Json( <構造を表現するLuaテーブル> )

CONV_Json2Lua

JSONの文字列を、同じ構造を持つLuaテーブルに変換する。

   <Luaテーブル> = CONV_Json2Lua( <元になるJSON文字列> )

CONV_JsonFile2Lua

ファイルパス形式で指定されたJSONファイルを、同じ構造を持つLuaテーブルに変換する。

CONV_JsonFile2Lua

   <Luaテーブル> = CONV_JsonFile2Lua( <JSONファイルのパス> )

言語DB関数 ¶

各言語の文字列DBアクセス手段を提供する。

LANG_addString

idと文字列の組を登録する。

LANG_addString
```
   LANG_addString( <id>, "<string>" )
```

LANG_getString

id指定されたidに対応する文字列を返す。

LANG_getString
```
   <string> = LANG_getString(<id>)
```

LANG_removeString

指定されたidに対応する文字列を削除する。

LANG_removeString
```
   LANG_removeString(<id>)
```

SQLiteインタフェース関数 ¶

ローカルストレージ中にあるSQLite3のDBファイルをSQLでアクセスする手段を提供する。ただし、システムのルール上書き込み禁止のディレクトリにあるDBファイルに対し、 INSERT/UPDATE/DELETEなどの更新を伴うクエリを投げてはならない。

DB_open

DBファイルパスを指定することで、そのDBにアクセスするためのコネクションインスタンスを返す。指定されたDBファイルのオープンが失敗した場合、戻り値はnilとなる。

DB_open

   <コネクションインスタンス> = DB_open( <DBファイルパス名> [, <書き込み許可>, <DBファイル作成許可> ] )

   <書き込み許可>        true でDBへの書き込みを許可する。
                         デフォルトはtrue。read only のDBとして扱う場合、false にする。

   <DBファイル作成許可>  true でDBファイルが見つからない場合の作成を許可する。
                         デフォルトはtrueだが、<書き込み許可>がfalseの場合自動的にfalseとなる。

DB_close

DB_open()で返されたコネクションインスタンスのDBをクローズする。コネクションインスタンスとしてnilが渡された場合は何もしない。

DB_close

   DB_close(<コネクションインスタンス>)

DB_query

コネクションインスタンスで指定されたDBに対し、SQL文字列でクエリを発行し、クエリ実行の成否と結果を返す。戻り値が二つあるので注意。クエリがselectionを返すSELECT文である場合は、第二戻り値はselectionをまとめたLuaテーブルとなる。戻されるLuaテーブルは、selection各行を{ カラム名=値, ... }の形式でまとめ、この行単位のテーブルを配列にしたもの。

DB_query

   <成否>, <値> = DB_query(<コネクションインスタンス>, <SQL文字列>)
   
   <成否> boolean 成功時 true / 失敗時 false
   <値> 成功時 セレクション結果のテーブルまたは空のテーブル
        失敗時 エラーコード

バイナリデータインタフェース関数 ¶

ファイルをバイナリデータとして読み込み、指定のオフセットにあるバイトデータを読み込む手段を提供する。

BIN_open

ファイルパスを指定することで、そのファイルをバイナリデータとみなし、バイナリアレイインスタンス返す。指定されたファイルのオープンが失敗した場合、戻り値はnilとなる。

BIN_open

   <バイナリアレイインスタンス> = BIN_open( <ファイルパス名> )

BIN_close

BIN_open()で返されたバイナリアレイインスタンスを破棄する。バイナリアレイインスタンスとしてnilが渡された場合は何もしない。

BIN_close

   BIN_close(<バイナリアレイインスタンス>)

BIN_peek

バイナリアレイインスタンスの持つデータの、指定されたオフセットにある値を返す。指定されたオフセットが負の値や元のファイルサイズを超えるなどの場合はnilを返す。

BIN_peek

   <値> = BIN_peek(<バイナリアレイインスタンス>, <オフセット>)

BIN_peekU16

バイナリアレイインスタンスの持つデータの、指定されたオフセットから 2 バイトを16bit整数として取得し、その値を返す。取得される値のバイトオーダーは、第三引数の <big-endian-mode> が true の場合はビッグエンディアン(上位-下位)、 falseの場合および指定されない場合はリトルエンディアン(下位-上位)となる。

BIN_peekU16

   <値> = BIN_peekU16(<バイナリアレイインスタンス>, <オフセット> [ , <big-endian-mode> ])

BIN_peekU32

バイナリアレイインスタンスの持つデータの、指定されたオフセットから 4 バイトを32bit整数として取得し、その値を返す。取得される値のバイトオーダーは、第三引数の <big-endian-mode> が true の場合はビッグエンディアン(上位->下位)、 falseの場合および指定されない場合はリトルエンディアン(下位->上位)となる。

BIN_peekU32

   <値> = BIN_peekU32(<バイナリアレイインスタンス>, <オフセット> [ , <big-endian-mode> ])

マトリクス/ベクトル演算関数 ¶

簡易的な3D計算をサポートするため、マトリクス/ベクトルの計算ライブラリが用意されている。

GEO_CreateMatrix: Luaのテーブル(配列)で与えらえた値を持つマトリクスオブジェクトを与えられたテーブルの個数だけ生成する。テーブルの代わりに nil を与えると、単位行列を生成する。戻り値の数は、引数として与えられたテーブルとnilの個数の合計と等しい。

テーブルを与えずに呼び出すと、単位行列の値を持つマトリクスオブジェクトを一つだけ生成して返す。

マトリクスオブジェクトは、扱いを高速にするためC++のnativeコードから扱えるバイナリ構造体として表現されたマトリクス情報。 Luaの実数が double で表現されている場合は double/float間の変換のため、実際に生成される値は丸め誤差が生じる。

GEO_CreateMatrix

   local tblMat1 = {
    1.0, 2.0, 0.0, -1.0,
    -1.0, 1.0, 2.0,  0.0,
    2.0, 0.0, 1.0,  1.0,
    1.0, -2.0, -1.0, 1.0
   }
   local tblMat2 = {
     0.0, 1.0, 0.0, 0.0,
     1.0, 0.0, 0.0, 0.0,
     0.0, 0.0, 1.0, 0.0,
     0.0, 0.0, 0.0, 1.0
   }
   pMat1, pMat2, pUnit = GEO_CreateMatrix(tblMat1, tblMat2, nil)

   pUnitMat = GEO_CreateMatrix()

   上記の例で、pMat1 と pMat2 はそれぞれ tblMat1, tblMat2 と同じ値を持つマトリクスオブジェクトになる。
   また、ｐUnit, pUnitMat は単位行列として生成される。

GEO_DeleteMatrix: マトリクスオブジェクトを破棄する。一度に複数のマトリクスオブジェクトを破棄することができる。

与えられた引数のうち、値が nil のものについては何も行わない。値がnilであったものも含め、引数として与えられた数と同じだけの nil を返す。

GEO_DeleteMatrix

   local tblMatrix = { (省略) }

   pMatrix = GEO_CreateMatrix( tblMatrix )
   pUnitMatrix = GEO_CreateMatrix()

   pMatrix, pUnitMatrix = GEO_DeleteMatrix( pMatrix, pUnitMatrix )

   上記の例で、生成した二つのマトリクスオブジェクトを破棄している。
   呼び出しの引数が二つであるため、戻り値として二つの nil が返される。
   これを用いてマトリクスオブジェクトの保持に使用した変数を初期化している。

GEO_RevertMatrix: マトリクスオブジェクトから、同じ値を持つLuaのテーブルを返す。返されたLuaテーブルは、GEO_CreateMatrix()で使用する形式と同じとなる。

GEO_RevertMatrix

   local tblMatrix = { (省略) }

   pMatrix = GEO_CreateMatrix( tblMatrix )

   local tblMat2 = GEO_RevertMatrix(pMatrix)

   上記の例で、tblMat2 はtblMatrix と同じ値の配列となる。
   ただし、Luaでの実数が double で扱われている環境では double と float の
   相互変換を経由するため、丸め誤差が生じる可能性がある。

GEO_CopyMatrix: 引数で指定されたマトリクスオブジェクトをコピーし、新しいマトリクスオブジェクトを生成する。内部でコピーされるため、マトリクスオブジェクトとしては全く同じ値を持つ。

ただし両者は異なるポインタを持つため、Luaの演算子で比較しても同じ値とは見做されない。

GEO_CopyMatrix

   local tblMatrix = { (省略) }

   pMatrix = GEO_CreateMatrix( tblMatrix )
   pMat2 = GEO_CopyMatrix(pMatrix)

   上記例で、pMat2 は pMatrix と同じ値を持つマトリクスオブジェクトとなる。

GEO_TransposedMatrix

指定されたマトリクスオブジェクトを、転置行列に変換する。

   pMatrix = GEO_CreateMatrix()
   GEO_TransposedMatrix(pMatrix)

   上記例で、pMatrix の内容は GEO_TransposedMatrix() 実行前の内容を転置行列に変換した値になる。
   再度実行することで元に戻すことができる。

GEO_OverwriteMatrix: 既存のマトリクスオブジェクトの値を、Luaテーブルの値で上書きする。マトリクスオブジェクトとして与えられた値が nil である場合には何も行わない。

GEO_OverwriteMatrix

   pMatrix = GEO_CreateMatrix()

   local tblNew = {
     1.0, 2.0, 0.0, -1.0,
     -1.0, 1.0, 2.0,  0.0,
     2.0, 0.0, 1.0,  1.0,
     1.0, -2.0, -1.0, 1.0
   }

   GEO_OverwriteMatrix(pMatrix, tblNew)

   上記の例では、GEO_CreateMatrix() で単位行列として生成したマトリクスオブジェクトの値を、
   GEO_OverwriteMatrix() で上書きしている。

GEO_DeleteAllMatrix: 生成方法を問わず、これまで生成されたマトリクスオブジェクト全てを破棄する。変数を上書きしてアクセスできなくなったマトリクスオブジェクトも含まれる。

GEO_DeleteAllMatrix

   local tblMat = { (省略) }
   pMatrix = GEO_CreateMatrix(tblMat)

   pMatrix = 100

   GEO_DeleteAllMatrix()

   上記の例では生成したマトリクスオブジェクトのポインタ値を受け取った pMatrix 変数を、
   数値で上書きすることによってマトリクスへのアクセス手段が失われてしまっているが、
   このようなマトリクスオブジェクトも GEO_DeleteAllMatrix()によって破棄できる。

   ただし、システム起動以来生成したすべてのマトリクスオブジェクトが対象となるため、
   使用に際しては注意が必要となる。

GEO_MulMatrix: 第二引数以降のマトリクスオブジェクト同士を順次乗算し、結果を第一引数のマトリクスオブジェクトに書き込む。二つ以上のマトリクス乗算を一度の手続きで行うことができる。

GEO_MulMatrix

   local tblMat1 = { (省略) }
   local tblMat2 = { (省略) }
   local tblMat3 = { (省略) }
   local tblMat4 = { (省略) }
   local tblMat5 = { (省略) }

   pMat1 = GEO_CreateMatrix(tblMat1)
   pMat2 = GEO_CreateMatrix(tblMat2)
   pMat3 = GEO_CreateMatrix(tblMat3)
   pMat4 = GEO_CreateMatrix(tblMat4)
   pMat5 = GEO_CreateMatrix(tblMat5)

   pAns = GEO_CreateMatrix()  -- 結果受け取り用
 
   GEO_MulMatrix(pAns, pMat1, pMat2, pMat3, pMat4, pMat5)

   上記の例ではtblMat1～tblMat5までの配列から生成した pMat1～pMat5を番号順に乗算し、
   結果を pAns に格納している。行列の計算なので、引数を与える順番に注意。

GEO_InverseMatrix: 与えられたマトリクスの内容を、逆行列に変換する。変換に成功した場合は true, 失敗した場合は false を返す。

いずれの場合も元の内容は破壊されるため注意。

GEO_InverseMatrix

   local tblMat = { (省略) }

   pMat = GEO_CreateMatrix(tblMat)
   pInvMat = GEO_CopyMatrix(pMat)

   if GEO_InverseMatrix(pInvMat) then
     -- 逆行列生成成功
   else
     -- 逆行列生成失敗
     -- pInvMatの内容は無効なので破棄する
     pInvMat = GEO_DeleteMatrix(pInvMat)
   end

   上記の例ではLuaテーブルから生成したマトリクスオブジェクト pMat を pInvMat にコピーし、
   GEO_INverseMatrix() で逆行列に変換している。

GEO_VecConv: Luaテーブルとして表現されるベクトルにマトリクスオブジェクトをかけ、結果のベクトルを同じ形式のLuaテーブルとして返す。

GEO_VecConv

   local tblMat = { (省略) }

   pMat = GEO_CreateMatrix(tblMat)

   local tblVec = GEO_VecConv(pMat, { x1, y1, z1, w1 })

   上記の例では(x1, y1, z1, w1)の値を持つベクトルをLuaテーブルとして与え、
   pMat が持つマトリクスをかけた変換結果を tblVec に受け取っている。

   変換結果を (x2, y2, z2, w2) とした場合、tblVec の値は { x2, y2, z2, w2 }
   というテーブルになる。

GEO_VecArrayConv: GEO_VecConv()に与える形式のベクトルを配列として同時に複数与え、そのすべてに対しマトリクスオブジェクトをかけた結果を、同じ要素数/同じ形式のLuaテーブルとして返す。複数のベクトルに対し、同じマトリクスでまとめて変換をかける際に使用する。

GEO_VecArrayConv

   local tblMat = { (省略) }

   pMat = GEO_CreateMatrix(tblMat)

   local tblVecArray {
     { x1, y1, z1, w1 },
     { x2, y2, z2, w2 },
     { x3, y3, z3, w3 },
     { x4, y4, z4, w4 },
      :
     (中略)
      :
     { xn, yn, zn, wn },
   }

   local retVecArray = GEO_VecArrayConv(pMat, tblVecArray)

   上記の例では複数のベクトルをLuaテーブルとして与え、
   pMat が持つマトリクスをかけた変換結果を retVecArray に受け取っている。

   同じ形式、同じ要素数で変換結果が返される。