コールバック

charatbeatHDXのスキンはスクリプトにより実装されています。このため、ゲームを起動すると最初はこのスクリプトを解析するところから始まりますが、もしこのファイルが存在しなかったり解析に失敗すると、ゲームはエラーを出して終了してしまいます。スクリプトを記述する際は、まずはエラー無くゲームが起動することが前提となります。
コールバック関数
スキン処理はcharatbeatHDXから必要があるときにだけ特定の関数が呼び出される仕様となります。この呼び出される関数のことをコールバック関数といい、これはシーン(タイトル画面や曲選択画面などの各状態)ごとに決められた名前の関数となっています。スクリプト上ではこのコールバック関数を定義して、その中身を記述することでスキン処理を行います。

なお、charatbeatHDXでは全てのシーンをデザインする必要はなく、特定のシーンだけデザインすることが出来るようになっています。これはシーンごとに呼び出されるコールバック関数が実装されているかどうかにより判断されます。

コールバック関数は基本的に「On」から始まる関数として定義され、各コールバック関数は以下のようにLua上に定義されている必要があります。 
function OnInitSystem()
    // システム初期化処理
end

　　　　　：
function OnStartTitle()
    // タイトルシーン構築
end

function OnRunTitle( upd_frm )
    // タイトルシーン処理
end

function OnEndTitle()
    // タイトルシーン終了
end
　　　　　：
コールバック関数一覧
初期化
OnInitSystem() スクリプトロード時に一度だけ呼び出される。
外部デバイスによる入力処理に対応するため、ここでhdxSysSetTouchArea()を使用して各画面のタッチエリア情報を登録する。
[この関数内で使用出来るAPI]
　hdxSysSetTouchArea()
レーン処理系
※レーンコールバックは、メインゲームの他にキャリブレーション画面でも使用されます
OnInitLane() ゲーム開始などでレーン処理が必要になると呼び出されるので、使用するレーンのオブジェクトデータなどを初期化する。
※ここではシングル時やダブル時の共通のレーンのデザイン情報を設定するが、内部的には今回使用する要素だけが参照される
[この関数内で使用出来るAPI]
　hdxSysLoadImage()、hdxSysSetRange()、hdxSysLoadAnime()、hdxSysSetObject()
OnUpdateLane( tick,delta ) レーンの描画の前に呼び出されるので、現在のチックを参照して設定したアニメオブジェクトのフレーム値など更新したり、
キーの入力情報を取得してレーンの背景ライトなどの制御を行う。
通常は1フレームに1回呼びされるので、前回からの経過時間を参照してアニメフレーム数を進めることでループアニメなどを行う。
　tick ： 内部チック値(1小節9600)
　delta ： 前回のフレームからの経過時間(秒)
[この関数内で使用出来るAPI]
　hdxSysGetAnimeMaxFrame()、hdxSysCtrlObject()、hdxSysGetInput()
OnOneshotExplosion( side,lane,sid ) ワンショット爆発が必要になると呼び出される。
ワンショット爆発は同一レーン内で複数重なることがあるため、次の爆発に使用するサブIDが一緒に渡される。
このサブIDをhdxSetCtrlObjectにそのまま渡すことで、簡単に複数の爆発を表示することが出来る。
表示可能な最大数はグローバル変数に指定したLANE_MAX_EXPLOSION分となる。
　side ： 1P側か2P側か(0=1P、1=2P)
　lane ： レーン番号(0～6=白黒鍵盤、7=スクラッチ)
　sid　： サブID(0～LANE_MAX_EXPLOSION-1の値が自動的にインクリメントループされる)
OnBeginLong( side,lane,type ) ロング系オブジェの開始時に呼び出される。
ここで連続爆発アニメやレーン上のロングライティングなどの演出を開始する。
なおHCN時は回復から減衰、または減衰から回復に切り替わる場合でも、
その前に必ずOnEndLongExplosionが呼び出されため、
自前で以前のアニメを停止させてから新しいアニメを再生するといった制御は必要ない。
　side ： 1P側か2P側か(0=1P、1=2P)
　lane ： レーン番号(0～6=白黒鍵盤、7=スクラッチ)
　type ： ロングタイプ(LONGTYPE_CN=チャージノート、LONGTYPE_HCN_HEAL=ヘルチャージ回復、LONGTYPE_HCN_DMG=ヘルチャージ減衰)
OnEndLong( side,lane,type ) ロング系オブジェの終了時に呼び出される。
ここで連続爆発アニメを停止したりロングライティングを終了する。
必ずOnBeginLongExplosionと対で呼び出されるため、
他のロングタイプのアニメの表示・非表示を制御する必要は無い。
　side ： 1P側か2P側か(0=1P、1=2P)
　lane ： レーン番号(0～6=白黒鍵盤、7=スクラッチ)
　type ： ロングタイプ(LONGTYPE_CN=チャージノート、LONGTYPE_HCN_HEAL=ヘルチャージ回復、LONGTYPE_HCN_DMG=ヘルチャージ減衰)
タイトル画面
OnStartTitle() タイトル画面が始まる際に呼び出される。
OnRunTitle( upd_frm ) タイトル画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnEndTitle() タイトル画面でスタートボタンが押されたら呼び出される。
※ボタンが押されるたびに呼ばれるため、まだ開始させたくない場合は無視してもよい
ログイン・プレイモード選択画面
OnStartLogin() ログイン画面が呼び出される際に呼び出される。
OnRunLogin( upd_frm ) ログイン画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnStartPlayMode( login,pmode ) ログイン画面でログインが成功したか、ログインせずに開始された際に呼び出される。
　login ： 0=未ログイン、1=ログイン済み
　pmode ： プレイモードの初期値(0=シングル1P、1=シングル2P、2=ダブル)
OnRunPlayMode( upd_frm ) プレイモード画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnChangePlayMode( pmode ) プレイモードが選択されるごとに呼び出される。
　pmode ： プレイモード(0=シングル1P、1=シングル2P、2=ダブル)
OnEndPlayMode( pmode ) プレイモードが確定した際に呼び出される。
　pmode ： プレイモード(0=シングル1P、1=シングル2P、2=ダブル)
ゲームモード選択画面
OnStartGameMode( gmode ) ゲームモード画面が始まる際に呼び出される。
　gmode ： ゲームモードの初期値(0=BEGINNER、1=STANDARD、2=EXPERT、3=CLASS、4=FREE)
OnRunGameMode( upd_frm ) ゲームモード画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnChangeGameMode( gmode ) ゲームモードが選択されるごとに呼び出される。
　gmode ： 0=BEGINNER、1=STANDARD、2=EXPERT、3=CLASS、4=FREE
OnEndGameMode( gmode ) ゲームモードが確定した際に呼び出される。
　gmode ： 0=BEGINNER、1=STANDARD、2=EXPERT、3=CLASS、4=FREE
曲選択画面
OnStartMusicSelect( exp ) 選曲画面が始まる際に呼び出される。
　exp ： エキスパートモードの場合はTRUEが入る
[この関数内で使用出来るAPI]
　hdxSetListInfo()
OnRunMusicSelect( upd_frm ) 曲選択画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnSelectMusicList( frm_type ) リストを決定すると呼び出される。
この後に曲のDLが必要な場合はOnStartDownload()、そのまま始められる場合はOnEndMusicList()が呼び出される。
これらの関数までの呼び出しには多少ラグがあるため、決定時の音を出す場合はこの関数で行うと良い。
　frm_type ： フレームタイプ
　　　　　　　　FRAMETYPE_UNKNOWN=未定義(非表示とする)
　　　　　　　　FRAMETYPE_BACK=戻る
　　　　　　　　FRAMETYPE_SUBDIR=階層に入る
　　　　　　　　FRAMETYPE_MESSAGE=メッセージのみ
　　　　　　　　FRAMETYPE_SONG=曲
　　　　　　　　FRAMETYPE_SONGERROR=エラー曲
　　　　　　　　FRAMETYPE_COURSE=コース
OnChangeMusicList(
　frm_type,
　title,
　genre,
　artist,
　level,
　bpm,
　info,
　dl_point,
　dl_count,
　course_id,
　first )		 リストがスクロールされて次のリストが選択されると呼び出される。
ここで選択された楽曲の情報の詳細表示などを行う。
※コース内の曲リストはhdxGetCourseList()にコースIDを指定して取得できる
　frm_type　　： フレームタイプ
　　　　　　　　FRAMETYPE_UNKNOWN=未定義(非表示とする)
　　　　　　　　FRAMETYPE_BACK=戻る
　　　　　　　　FRAMETYPE_SUBDIR=階層に入る
　　　　　　　　FRAMETYPE_MESSAGE=メッセージのみ
　　　　　　　　FRAMETYPE_SONG=曲
　　　　　　　　FRAMETYPE_SONGERROR=エラー曲
　　　　　　　　FRAMETYPE_COURSE=コース
　title　　　　： タイトル名(全タイプで何かしらの文字が入る)
　genre　　　： ジャンル名(楽曲の場合のみ存在)
　artist　　　　： アーティスト名(楽曲の場合のみ存在)
　level　　　　： レベル値
　bpm　　　　： テンポ値(楽曲の場合のみ存在)
　info　　　　　： その他情報(特に無ければ空文字)
　dl_point　　　： DLに必要なポイント数(-1=フリー曲、0=購入済の曲、1以上=未購入曲)
　dl_count　　： DLカウント数
　course_id　　： コースID(コース以外は-1)
　first　　　　　： リスト構築直後の選択なら1、通常の選択時は0
OnDrawMusicList(
　x,y,
　frm_type,
　level,bpm,
　flag,
　lamp_type,
　clear,fullcombo,
　best_jadge,
　best_exscore,
　dl_point,
　dl_count,
　course_count )		 hdxDrawMusicList()を呼び出した際に、曲リストの表示が必要になると呼び出される。
リスト１つに付き1回呼び出されるため、通常は1フレームに画面内に表示される分だけ呼び出される。
　x,y　　　　　： リストの左上座標
　frm_type　　　： フレームタイプ
　　　　　　　　FRAMETYPE_BACK=戻る
　　　　　　　　FRAMETYPE_SUBDIR=階層に入る
　　　　　　　　FRAMETYPE_MESSAGE=メッセージのみ
　　　　　　　　FRAMETYPE_SONG=曲
　　　　　　　　FRAMETYPE_SONGERROR=エラー曲
　　　　　　　　FRAMETYPE_COURSE=コース
　level　　　　　： レベル値(曲の場合のみ有効)
　bpm　　　　　： 初期テンポ値(曲の場合のみ有効)
　flag　　　　　： 曲解析フラグ(bit0=シングル譜面か、1=ダブル譜面か、2=MIDI使用曲、3=ムービー使用曲)
　lamp_type　　： ランプタイプ(CLEARLAMP_NO=無し、CLEARLAMP_ASSIST=ASSIST、
　　　　　　　　　　　　　　　CLEARLAMP_EASY=EASY、CLEARLAMP_NORMAL=NORMAL、CLEARLAMP_HARD=HARD)
　clear　　　　　： 現在のランプタイプでのクリア状態(FALSE=未クリア、TRUE=クリア済み)
　fullcombo　　： 現在のランプタイプでフルコンボしたか(FALSE=フルコンボではない、TRUE=フルコンボした)
　best_jadge　　： 今までのベスト時の判定値(0=F、1=E、2=D、3=C、4=B、5=A、6=AA、7=AAA)
　best_exscore　： ベスト判定時のEXスコア値
　dl_point　　　： DLに必要なポイント数(-1=フリー曲、0=購入済の曲、1以上=未購入曲)
　dl_count　　　： DLカウント数
　course_count　： コース内の曲数
OnStartDownload() 楽曲のDLが必要な場合に最初に呼び出される。
OnDownloadStatus( per ) 楽曲DL中に進行度が変化した場合に呼び出される。
　per ： DLパーセント値(0～100)
OnEndDownload( err ) 楽曲のDLが完了したり失敗した場合に呼び出される。
※エラー表示はシステムが行うため独自でエラー表示を出す必要はないが、
　エラー演出だけを行うといったことは可能
　err ： エラー時はtrueが入る
OnEndMusicList() 楽曲が選択されてプレイ可能になると呼び出される。
ダウンロードが必要ない場合はこの関数が即座に呼び出されるため、リスト選択は必ずこの関数で終了させる。
OnStartOption() Startボタンが押されてオプション変更が開始されると呼び出される。
現在のプレイモードはhdxGetGameInfo()にて確認し、1P側か2P側、または両方にオプション画面を表示する。
OnChangeOption( opt_id ) オプションが変更されるごとに呼び出される。
変化後の値はhdxGetGameInfo()にて取得する。
　opt_id ： 変化のあったオプションID
　　　　　　(OPTID_SHUFFLE_1P,OPTID_SHUFFLE_2P,OPTID_DIFFICULT,OPTID_ASSIST,OPTID_COVER,OPTID_DOUBLE,OPTID_SPEED)
OnEndOption() Startボタンが離されてオプション変更が終了されると呼び出される。
spd = OnChangeScrollSpeed(
　scene,
　cur_spd,
　digital,
　analog )		 スクロールスピードの変更指示があると呼び出される。
最終的なスピードを返すことで実際にその速度に変化する。
　spd ： 最終的に確定した速度
　scene ： 呼び出した画面(0=曲選択内、1=ゲーム中)
　cur_spd ： 設定される前の速度
　digital ： 上昇か下降かのデジタル値(-1=下降、0=変化なしかアナログ値を使用、1=上昇)
　analog ： 上昇か下降するかのアナログ値(小数値)
　　　　　　　(下降時は負の数、上昇時は正の数となるので、現在の速度にそのまま加算してもよい)
※アナログ時でもボタンによる上下が行えるため、digitalが0の場合のみアナログ値を使用する
※返された値が不正だった場合は内部で補正されるため、表示を行う場合はここで算出した速度ではなく、
　hdxGetGameInfo()のopt_scroll_speedを参照する
※曲選択中は基本的に上昇しかしないため、限界まで上昇したら次は最低値に戻す処理が必要となる
※ゲーム中にも呼び出される
メインゲーム画面
OnStartMainGame() ゲーム画面が開始されると呼び出される。
シングルかダブルかはhdxGetGameInfo()にて取得する。
OnRunGame( upd_frm ) ゲーム中に毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnGameLoading( event,per ) BMSの解析状態が変化するごとに呼び出される。
タイトル用の画像が存在しない場合は直接文字列を、存在する場合はそのテクスチャを指定して描画を行う。
　event ： BMSデータロードイベント
　　　　　　　LOADEVENT_BMS_ANALYZE　　: BMSの解析開始
　　　　　　　LOADEVENT_BMS_SUCCESS　　: BMSの解析終了(hdxGetGameData()にてタイトルやテンポ情報が参照可能)
　　　　　　　LOADEVENT_SOUND_LOADING　: BMS内で使用しているWAVのロード中
　　　　　　　LOADEVENT_IMAGE_LOADING　: BMS内で使用しているBGAのロード中
　　　　　　　LOADEVENT_COMPLETE　　　　: 全てのBMSデータがロード完了(ゲーム開始待ち)
　per : 全体の進行度(％)
　　　　　　　0～10　　: BMSの解析～解析終了
　　　　　　　10～50　: WAVのロード中
　　　　　　　50～90　: BGAのロード中
　　　　　　　100　　　: 完了
OnGameJadge( side,always,jadge,combo,timing ) 判定処理が行われると呼び出されるので、ここで判定文字の表示を行う。
ロング中にミスなどで失敗判定が発生した場合は連続表示が解除され、
ワンショット表示としてその判定文字に切り替える。
　side　　： 1P側か2P側か(0=1P、1=2P)
　always　： 連続表示するか
　jadge　　： 判定(0=ピカグレート、1=グレート、2=グッド、3=バッド、4=空プア、5=プア)
　combo　： 現在のコンボ数(1以上ならコンボ数を一緒に表示／0なら判定文字のみ表示)
　timing　： ベスト位置からのズレ時間がミリ秒で入る(FAST=早い、SLOW=遅い)
OnDrawLane( state,side,x,y,w,h ); レーン描画状態が変更されるごとに呼び出される。
緑数字や白数字など、必要ならばレーン表示途中に独自の描画処理を行う。
　state　　： 描画中のステート(DRAWSTATE_****)
　side　　： 1P側か2P側か(0=1P、1=2P)
　x,y,w,h　： 現在のビューポート値
OnFullCombo() フルコンボ達成時に呼び出される。
OnEndGame( retire ) ゲームが終了すると呼び出される。
　retire ： HARDモードやEXPERT、段位認定で途中でゲームオーバーになったか
　　　　　　(FALSE=クリア、TRUE=ゲームオーバー)
OnStartGameOption() ゲーム中にStartボタンが押されてゲームオプションが変更可能になると呼び出される。
OnEndGameOption() ゲーム中にStartボタンが離されてゲームオプションが変更不可になると呼び出される。
ゲーム結果画面
OnStartResult() 結果画面の開始時に呼び出される。
OnRunResult( upd_frm ) 結果画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnEndResult() 結果画面内で次の表示に遷移したい場合に呼び出される。
通常はSTARTボタンを押したときに呼び出されるので、このタイミングで結果画面を切り替えていく。
コース結果画面
OnStartCourseResult() コース結果画面の開始時に呼び出される。
OnRunCourseResult( upd_frm ) コース結果画面で毎フレーム呼び出されるので、ここで演算と描画処理を行う。
　upd_frm : 60fpsごとにTRUEになる
OnCourseResultNext() コース結果画面内で次の表示に遷移したい場合に呼び出される。
通常はSTARTボタンを押したときに呼び出されるので、このタイミングで結果画面を切り替えていく。
シーン別コールバック
スキンを適用するために、シーンごとに必要なコールバック関数が決められています。これらの関数が１つも実装されていない場合、そのシーンはシステムスキンが使用されます。正しくスキンが使用されない場合はDEBUG.TXTにエラーが出力されていないか確認してください。

以下はシーンごとに必要なコールバック関数のリストになります。
タイトル画面 OnStartTitle()
OnRunTitle()
OnEndTitle()
ログイン・プレイモード選択画面 OnStartLogin()
OnRunLogin()
OnStartPlayMode()
OnRunPlayMode()
OnChangePlayMode()
OnEndPlayMode()
ゲームモード選択画面 OnStartGameMode()
OnChangeGameMode()
OnRunGameMode()
OnEndGameMode()
曲選択画面 OnStartMusicSelect()
OnRunMusicSelect()
OnSelectMusicList()
OnChangeMusicList()
OnDrawMusicList()
OnStartDownload()
OnDownloadStatus()
OnEndDownload()
OnEndMusicList()
OnChangeScrollSpeed()
メインゲーム画面
(キャリブレーションのレーン)		 OnStartMainGame()
OnRunGame()
OnGameLoading()
OnGameJadge()
OnDrawLane()
OnChangeScrollSpeed()
OnFullCombo()
OnEndGame()
OnStartGameOption()
OnEndGameOption()
OnInitLane()
OnUpdateLane()
OnOneshotExplosion()
OnBeginLong()
OnEndLong()
ゲーム結果画面 OnStartResult()
OnRunResult()
OnEndResult()
コース結果画面 OnStartCourseResult()
OnRunCourseResult()
OnCourseResult()