LuaAPIの仕様
はじめに
こちらは譜面制作において、自身の書いたプログラムを実行させたい方向けの記事になっております。
.dlファイルの#LUA
タグにluaファイルを指定することでゲームプレイ時にluaを実行します。
(Luaファイルの拡張子は「.lua」推奨です。)
これにより、要素を操作したり画像を追加したりして所謂「Modchart」を作成できます。
Luaを書くに当たって、下記の知識が混合します。
- ・Luaの文法
- ・UnityAPI
- ・ダンカグライクのLuaAPI(このページ)
コーディングについて
まず、Windows のメモ帳ではなく、より優れたテキストエディタを使用する必要があります。 個人的には「Visual Studio Code」をお勧めします。 なぜなら、本当に便利な機能とショートカットがあるからです。 iPadやiPhoneで使用できるブラウザ版VSCodeもあります。 また、Notepad++やSublimeTextもあるので、ご自身が使いやすいものをお使いください。
VSCode拡張機能の導入について
バージョン0.0.7 更新日時: 2024/05/07
「DankagLike LuaAPI」を公開しました。(初版 2023/08/25)インストール方法はzipに同梱しています。
[機能]
- ・入力補完
- ・型チェック
- ・イベント関数、グローバル変数のスニペット
- ・ホバーするとドキュメントが表示されます
[その他]
- ・「lua-language-server」の依存インストール
- ・型定義ファイルを指定する設定項目は拡張機能が行ってくれます
Luaチュートリアル
サンプルコード & スライド資料
準備中です
■ Luaから使用できるUnityEngineのクラスについて
基本的にはCS.UnityEngine.(クラス名)
で使用できます。
型を変数に入れておく
毎回名前空間付きの型を指定するのは面倒なので、以下のように型を変数に入れて使うことができます。-- 型を変数に入れておく
local GameObject = CS.UnityEngine.GameObject
local gameObj = GameObject()
local gameObj2 = GameObject("example")
static変数、static関数
static変数へのアクセス、static関数の呼び出しは以下のように行います。local UnityEngine = CS.UnityEngine
local Color = UnityEngine.Color
local GameObject = UnityEngine.GameObject
-- static変数にアクセス
local white = Color.white
print(white)
-- static関数呼び出し
local lane = GameObject.Find("Lane")
print(lane)
メンバにアクセス
メンバへのアクセスは以下のように行います。メンバ関数の呼び出しはコロン「:」になります。
local UnityEngine = CS.UnityEngine
local GameObject = UnityEngine.GameObject
local Vector3 = UnityEngine.Vector3
-- 譜面プレビューで「D」キーを押すとシーンのGameObjectの名前を確認できます
local laneObj = GameObject.Find("Lane")
-- メンバ変数
laneObj.transform.localPosition = Vector3.right
-- メンバ関数
laneObj:SetActive(false)
型を取得
LuaからC#の型を取得するには以下のようにします。local type = typeof(CS.UnityEngine.MeshRenderer)
print(type)
UnityAPIの詳細についてはUnityスクリプトリファレンスをご参考下さい。コードストリッピングによってアプリで使用していないメソッドやクラスがビルドに含まれないため、一部使用できないUnityEngineのクラスがあるようです。
■ Unity(C#)とLuaの型の比較
UnityAPIやLuaAPIを呼び出す際には対応した型に変換されます。
C# | Lua |
---|---|
void | 戻り値なし |
int (整数) | number(64bit) |
float (実数32bit) | number |
double (実数64bit) | number |
string (文字列) | string |
bool (真偽値) | boolean |
Action | function |
null | nil |
[] (配列) | 配列としてのテーブル |
■ デバッグについて
画面上部にメッセージを表示する機能を用意しています。
変数の中身を確認したり、コードに到達しているか確認できます。
SCREENMAN:SystemMessage("表示したいもの")
また、譜面プレビューのバージョンv1.36以降にデバッグツールを追加しています。「1」~「4」キーでデバックメニューを開いて、
Consoleを選ぶとシステムのログが確認できます。
Consoleに出力するのみであればLuaの標準出力のprint関数もあります。
print("表示したいもの")
譜面プレビューのゲーム画面で「D」キーを押すと、ゲーム内の要素やパラメータのウィンドウが表示されます。
Luaから操作した時の様子を確認できます。
初回表示時に時間が掛かるので、開始を押す前か、ポーズしてから開くと良さそうです。
Luaの実行中にエラーが起きた際にはダイアログが表示されます。
メッセージ内容からエラーの発生したLuaの行番号が出力されるため、
これを手掛かりに修正を行なえます。
■ LuaからLuaファイルを読み込む
require "mylib.lua"
外部から読み込むLuaファイルに汎用処理を記述して、それを呼び出して使えるようにすると便利です。requireを使用して譜面フォルダからの相対パスの文字列を指定します。
拡張子が付いていない文字列を渡すと.luaが付いているものとして解釈されます。
■ コルーチンについて
コルーチン(Coroutine)とは、関数を途中で中断・再開できる機能を持つ構造の名称です。
それぞれの関数を中断したいところで、coroutine.yield関数を記述して処理を中断し、 再開する場合はそこから処理を続行します。coroutine.yield関数に渡す引数によって再度呼び出されるタイミングを変更します。
コルーチンは非同期処理を行うための方法の一つになります。
local cs_coroutine = require "cs_coroutine"
Time = CS.UnityEngine.Time
-- コルーチンとして実行する関数
function CountTimeRoutine(waitTime, message)
local elapseTime = 0.0
while (elapseTime < waitTime) do
elapseTime = elapseTime + Time.deltaTime
SCREENMAN:SystemMessage(elapseTime)
-- 1フレーム待機
coroutine.yield(nil)
end
SCREENMAN:SystemMessage(message)
end
function start()
-- コルーチン開始
_coroutine = cs_coroutine.start(CountTimeRoutine, 5, "Finish Coroutine")
end
LuaからUnityのコルーチンを実行できるようにする機能をrequireを使用して読み込みます。cs_coroutineのファイルは事前にアプリ内に組み込まれています。
local cs_coroutine = require "cs_coroutine"
コルーチンとして扱う関数内でcoroutine.yield()
を使用すると処理を中断します。 引数にはUnityのyield returnで返せる値を入れることができます。 引数が無い場合はnilを渡したことになり、次のフレームで再開します。コルーチンの開始・停止は下記の関数を使用します。
■ Tweenライブラリについて
LuaAPI ver1.1からTweenライブラリであるDOTweenをLua上で使用できるようになりました。クラスのメンバ関数の呼び出しに「:」を使用する事、C#の型アクセスに「CS.」を付ける事でUnityと同様に使用出来ます。DOTweenの使用方法については公式ドキュメントや検索で多数の記事があります。
_transform:DOLocalMove(CS.UnityEngine.Vector3(1, 0, 5), 1.0)
:SetEase(CS.DG.Tweening.Ease.InOutQuad)
:OnComplete(MyCompleteFunction)
■ LuaAPIバージョンについて
LuaAPIのバージョン管理について、各APIに対応したバージョンのタグを記載します。
また、LuaAPIバージョンに対応した各アプリのバージョンをこちらに記載していきます。
LuaAPIのバージョン | アプリ本体のバージョン | 譜面プレビューのバージョン |
---|---|---|
- | v1.50 | |
#68 | v1.48 | |
#66 | v1.46 | |
#64 | v1.44 | |
#62 | v1.42 | |
#61 | v1.40 | |
#60 | v1.39 | |
#59 | v1.38 | |
#58 | v1.37 |
■ イベント関数
イベント関数(ゲーム側から呼ばれる関数)の一覧です。
引数のあるイベント関数はゲーム側から値が渡ってきます。
■ LuaAPI (クラスと関数)
ダンカグライクのLuaAPI(予め用意しているLuaのソースファイル中で使用できる関数)についてここで説明します。
これらの関数を使用するには
クラスの変数名:関数名
の形で書く必要があります。また、グローバルテーブル変数に定義されているクラスについては大文字で呼び出すことができます。
詳しくは、後述の各API中の記述例を参照ください。
・ScreenManクラス
クラスのグローバル変数名:SCREENMAN
・GameStateクラス
クラスのグローバル変数名:GAMESTATE
・PlayerStatsクラス
クラスのグローバル変数名:PLAYERSTATS
・SongManクラス
クラスのグローバル変数名:SONGMAN
・CameraManクラス
クラスのグローバル変数名:CAMERAMAN
・PostEffectクラス
・AssetManクラス
・AppManクラス
クラスのグローバル変数名:APPMAN
・Utilクラス
クラスのグローバル変数名:UTIL
[]で囲われた引数はデフォルト引数を表しています。
・ActorFactoryクラス
クラスのグローバル変数名:ACTORFACTORY
ActorFactoryは各Actorを生成するためのクラスです。
Create〇〇関数でActorを継承したクラスを持つゲームオブジェクトが生成されます。
Luaファイルを指定してActorにLuaテーブルを持たせることで、
読み込んだLuaファイルのイベント関数がActorから呼び出されます。
LuaAPI Ver1.3からLuaファイルの指定が必須でなくなりました。
Actorの種類は今後も増やす予定です。
・Actor2Dクラス
画像を表示する機能を持つ、Actorを継承したクラスです。
ActorFactoryクラスのCreate2D関数から生成されます。
読み込んだLuaファイルのイベント関数が呼び出されます。
読み込んだLuaファイルから自身のActor2Dには「self」でアクセスできます。
・ActorAudioクラス
音声再生の機能を持つ、Actorを継承したクラスです。
ActorFactoryクラスのCreateAudio関数から生成されます。
読み込んだLuaファイルのイベント関数が呼び出されます。
読み込んだLuaファイルから自身のActorAudioには「self」でアクセスできます。
・ActorVideoCanvasクラス
動画再生の機能を持つ、Actorを継承したクラスです。
ActorFactoryクラスのCreateVideoCanvas関数から生成されます。
読み込んだLuaファイルのイベント関数が呼び出されます。
読み込んだLuaファイルから自身のActorVideoCanvasには「self」でアクセスできます。
動画の音声は再生しない仕様です。変更したい場合はVideoPlayerを取得して、UnityAPIを介して変更してください。
また、権利を有しない動画ファイルの自動公衆送信はお控えください。
・ActorUITextクラス
テキストを表示する機能を持つ、Actorを継承したクラスです。
ActorFactoryクラスのCreateUIText関数から生成されます。
読み込んだLuaファイルのイベント関数が呼び出されます。
読み込んだLuaファイルから自身のActorUITextには「self」でアクセスできます。
・DanmakuStageクラス
クラスのグローバル変数名:DSTAGE または DANMAKUSTAGE
ダンマクステージを構築するAPIです。
こちらの機能は現在Beta版になります。
・BulletBuilderクラス
DanmakuStageクラスのGetBulletBuilder関数から取得されます。
弾の設定をメソッドチェーンで記述して、最後にBuild関数を呼ぶことで弾を発射します。
・EnemyBulletクラス
弾幕ステージの敵弾クラスです
BulletBuilderに設定した呼び出し関数の引数として取得されます
■ 取得のみ可能なプロパティ
- Transform Transform:弾のTransform
- SpriteRenderer SpriteRenderer:弾のSpriteRenderer
- Vector2 Velocity:弾の速度
- Vector2 Acceleration:弾の加速度
- float AngularVelocity:弾の角速度
- float AngularAcceleration:弾の角加速度
- float Size:弾のサイズ
- int Damage:弾のダメージ量
- bool IsPersistence:プレイヤーに当たっても消えない弾か
- int ReleaseType:破棄タイプのint
- bool IsReleased:アクティブ状態から解放したか
・DanmakuPlayerクラス
弾幕ステージの自機クラスです
DanmakuStageクラスのGetPlayer関数から取得できます
■ 取得のみ可能なプロパティ
- Vector2 Position:プレイヤー(自機)の位置
・DanmakuEnemyクラス
弾幕ステージの敵機クラスです
DanmakuStageクラスのGetEnemy関数から取得できます
将来的にDanmakuBossに名前が変わるかもしれません
■ 取得のみ可能なプロパティ
- Vector2 Position:敵機の位置
■ LuaAPI (Enum)
列挙型のLuaAPIについて記載します。
アクセスやキャストは以下のように行ないます。
-- 直接指定
local enum1 = CS.DifficultyType.Easy
-- 値からキャスト
local enum2 = CS.DifficultyType.__CastFrom(0)
-- 名前からキャスト
local enum3 = CS.DifficultyType.__CastFrom("Easy")
・enum DifficultyType
Name | Value |
---|---|
Easy | 0 |
Normal | 1 |
Hard | 2 |
Extra | 3 |
Lunatic | 4 |
・enum PlatformType
Name | Value |
---|---|
Other(その他) | 0 |
Windows | 1 |
MacOS | 2 |
Android | 3 |
iOS | 4 |
・enum NoteType
Name | Value |
---|---|
None | 0 |
Normal | 1 |
LongStart | 2 |
LongRelay | 3 |
LongEnd | 4 |
Fuzzy | 5 |
FuzzyLongStart | 6 |
FuzzyLongRelay | 7 |
FuzzyLongEnd | 8 |
・enum LongType
Name | Value |
---|---|
Long | 0 |
FuzzyLong | 1 |
■ Injection (グローバル変数)
アプリ側で事前に用意しているオブジェクトにアクセスする変数を記載します。
- 型:DummyNote(Prefab)
- LuaAPI Ver1.3からGameObjectではなく、DummyNoteクラスが取得されるようになりました。
以下のように記述してダミーノーツを生成した後、dummyNoteローカル変数にはDummyNoteクラスの参照が入ります。local dummyNote = CS.UnityEngine.GameObject.Instantiate(DummyNote)
- 記述例:
local GameObject = CS.UnityEngine.GameObject local Vector3 = CS.UnityEngine.Vector3 function start() -------------------------------------- -- LuaAPI Ver1.3以降のDummyNoteの場合 -------------------------------------- -- ダミーノーツを生成 (PrefabはGameObject.Instantiate関数で実体が生成されます) local dummyNoteClass = GameObject.Instantiate(DummyNote) -- ロング開始ノーツのTextureを取得 local longStartTexture = PLAYERSTATS:GetNoteTexture(CS.NoteType.LongStart) -- ロング開始ノーツのTextureに差し替える dummyNoteClass:SetTexture(longStartTexture) -- ダミーノーツのZ座標を判定まで0.5拍の座標に設定する dummyNoteClass:SetBeatPosition(0.5) -- ダミーノーツのX座標を6レーン目に設定する dummyNoteClass:SetLanePosition(5) -------------------------------------- -- LuaAPI Ver1.2以前のDummyNoteの場合 -------------------------------------- -- ダミーノーツを生成 (PrefabはGameObject.Instantiate関数で実体が生成されます) local dummyNote = GameObject.Instantiate(DummyNote) -- ファジーのTextureを取得 local noteTexture = PLAYERSTATS:GetNoteTexture(CS.NoteType.Fuzzy) -- ファジーのTextureに差し替える local meshRenderer = dummyNote:GetComponent(typeof(CS.UnityEngine.MeshRenderer)) meshRenderer.material:SetTexture("_MainTex", noteTexture) -- ダミーノーツの位置を判定まで0.5拍の座標に設定する local posZ = UTIL:CalculateBeatToNotePositionZ(0.5) dummyNote.transform.localPosition = Vector3(0, 0, posZ) -- ダミーノーツの角度をZ座標から取得して設定する dummyNote.transform.localRotation = UTIL:CalculateNoteRotation(posZ) end
- 型:Material
- 内容:PostEffectで使用できるマテリアルです。Shaderプロパティにfloat型の「_Strength」を持ち、0~1の範囲でグレースケールの強さを調整できます。
- 記述例:
function onloaded() -- PostEffectを取得 local postEffect = CAMERAMAN:GetPostEffect() -- PostEffectにグレースケールのMaterialを設定する postEffect:SetMaterial(Greyscale) -- グレースケールの強さを設定 Greyscale:SetFloat("_Strength", 1.0) -- PostEffectを有効にする postEffect:SetEnable(true) end
- 型:LaneSprite(Prefab)
- 内容:レーンの上または下に被せてレーンの見た目の色を変更するためのオブジェクト(Prefab)です。PrefabはCS.UnityEngine.GameObject.Instantiate関数を使用してシーン上に生成することができます。
- 記述例:
local GameObject = CS.UnityEngine.GameObject function onloaded() -- LaneSprite型のインスタンスが返ります local laneSprite = GameObject.Instantiate(LaneSpritePrefab) laneSprite:SetColor(1, 0, 0, 0.5) laneSprite:SetLanePosition(1) -- GameObjectを取得したい場合は.gameObjectを付ける local laneSpriteObject = laneSprite.gameObject end
ライセンス
MITライセンスのオープンソースを使用させていただきました
「xLua」ライセンスのページへ
解説/実装:na24ddr