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

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

スクリプトの実行ルール

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

タスクの実行ルール

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

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

システム関数

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_GetHorizontalBorder
GL_SetResolutionを使って、borderlessにした場合、立て枠のピクセルサイズを返す関数です。
 GL_GetHorizontalBorder()
GL_GetVerticalBorder
GL_SetResolutionを使って、borderlessにした場合、横枠のピクセルサイズを返す関数です。
 GL_GetVerticalBorder()

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()
    

フォント情報関数

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

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         ・・・  サウンドのサスペンド処理をエンジンで制御しない
    

AI関数

AIシステムの制御や利用に際して用いられます。

AI_setProp
AIオブジェクトのプロパティを設定する。プロパティは別途指定されるindex定数で指定する。
  • AI_setProp
       AI_setProp(<AI-object>, <index>, <value>)
    
AI_getProp
AIオブジェクトからプロパティ値を取得する。プロパティは別途指定されるindex定数で指定する。
  • AI_getProp
       <prop-value> = AI_getProp(<AI-object>, <index>)
    
AI_newQuery
AIシステムにおいて他のユニットを検索する条件をまとめ、Queryオブジェクトとして生成する。
  • AI_newQuery
       <query-object> = AI_newQuery("<unit-class>", <unit-mask>, <query-table>)
    
       <unit-class> Sincで定義されるユニットクラス名。
    
       <unit-mask> GAME_Unit タスクの UNIT_TYPE コマンドで指定されたtype値とANDを取り、
                   結果が0にならないものを検索対象とするために用いられる。
                   このため、UNIT_TYPEでtype値を指定されていないユニットは検索対象にならない。
    
       <query-table> = {
          { <operator>, <src-type>, <src-param>, <dst-type>, <dst-param> },
          { <operator>, <src-type>, <src-param>, <dst-type>, <dst-param> },
            :
       }
    
       <query-type> に指定できる条件は最大4つまで。それ以上指定した場合は無視5つ目以降が無視される。
    
       <operator> src を左辺、dst を右辺とおいた場合の条件演算子を指定する。
         OP_NE  != 条件 src Not Equal dst
         OP_EQ  == 条件 src EQual dst
         OP_GT  >  条件 src Greater Than dst
         OP_GE  >= 条件 src Greater then or Equal to dst
         OP_LT  <  条件 src Less Than dst
         OP_LE  <= 条件 src Less then or Equal to dst
    
       <src-type>,<dst-type>  値の種別を指定する。<src-param>/<dst-param>をどのように解釈するかの指定。
         AIT_UNITP  ユニットのプロパティ名文字列として解釈する。
         AIT_AIP    AIプロパティのインデックス値として解釈する。別途定義される定数シンボルを使用すること。
         AIT_GLOBAL AIシステムグローバルプロパティ値として解釈する。別途定義される定数シンボルを使用すること。
         AIT_CONST  定数として解釈する。32bit符号付き整数として扱える値を指定すること。
    
       <src-param>,<dst-param> <src-type>/<dst-type>で指定されたタイプの値として解釈可能な値を与える。
    
AI_delQuery
生成済みのQueryオブジェクトを破棄する。同時に複数破棄可能。破棄対象として指定した数だけnilを返す。
  • AI_delQuery
       nil [, nil [, ...]] = AI_delQuery(<query-object> [, <query-object> [, ... ] ])
    
AI_delQueryAll
生成したすべてのQueryオブジェクトを破棄する。
  • AI_delQueryAll
       AI_delQueryAll()
    
AI_resetRule
AIオブジェクトのルールフラグをすべてリセットする。
  • AI_resetRule
       AI_resetRule(<AI-object>)
    
AI_setActive
AIのアクティブ状態を設定する。非アクティブ状態の時、AIは処理を進行させない。
  • AI_setActive
       AI_setActive(<AI-object>, <active-flag>)
    

ユーティリティ関数

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 と同じ値を持つマトリクスオブジェクトになる。
       また、pUnit, 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 に受け取っている。
    
       同じ形式、同じ要素数で変換結果が返される。
    

Rise to the Throne 専用関数

RTTT_getPlatformID

今のPlatformが何であるかを示す識別子を返す.

  • RTTT_getPlatformID
      local platform = RTTT_getPlatformID()
    
      -- 戻り値の識別子は以下の通りで内部的には整数.
      -- RTTT_PLATFORM_UNKNOWN
      -- RTTT_PLATFORM_WIN32
      -- RTTT_PLATFORM_IOS
      -- RTTT_PLATFORM_ANDROID