Luaスクリプティング:行動プログラム
行動プログラムは、モブのネイティブAIをLuaのビヘイビアに置き換え、モブがどこへ移動し、何を見て、どのエンティティをターゲットにし、いつ攻撃するかを決めます。EliteMobsはこれらのプログラムを、MagmaCoreのMindランタイムを通じてMinecraftのネイティブBrainシステム上で実行します。
行動プログラムはLuaパワーではありません。Luaパワーはon_boss_damaged_by_playerなどのボスイベントに反応しますが、行動プログラムは毎tick実行され、モブの移動制御を所有します。ボスは両方を使えます。ビヘイビアはon_mind_actionを通じて、ボスのパワーにアクションの実行を依頼できます。
FreeMinecraftModelsのペットの行動は、同じ形式のai.moduleファイルであり、同じルールに従います。c.petやc.settingsのコンテキストフィールドなど、ペット固有の部分はペット行動モジュールを参照してください。FreeMinecraftModelsのMob行動は、プラグインがスポーンしていないMobを乗っ取るもので、やはり同じ種類のファイルであり、c.overlayとc.settingsを持ちます。
FreeMinecraftModelsのMob行動には、2.15.0の次のFreeMinecraftModelsリリースが必要です。
ボスの作成で説明しているとおり、カスタムボスファイル、またはエンティティタイプのモブプロパティファイルでbehaviorを設定します。behavior: nativeはバニラのAIを維持します。サーバーのバージョンがネイティブMindに対応していない場合、EliteMobsは起動時にNative Mind interface is unavailable on this Minecraft version.をログに出力します。その場合、プログラムを選択したカスタムボスはスポーンせず、Cannot spawn <boss file>: ...がログに出力されます。behaviorに存在しないプログラムや無効なプログラムを指定したボスは、どのバージョンでも同じように失敗します。
ファイル
行動ファイルはplugins/EliteMobs/behaviors/に置きます。EliteMobsは、次の同梱ファイルが存在しない場合に書き出します。
plugins/
EliteMobs/
behaviors/
basic_melee.lua
modules/
target.lua
pursuit.lua
melee.lua
wander.lua
modulesという名前のフォルダ内にある.luaファイルはモジュールです。それ以外の.luaファイルはすべてプログラムです。- ボスは
behaviors/からの相対パスでプログラムを参照します。例:basic_melee.luaやguards/patrol_guard.lua。 - EliteMobsはMindサービスの起動時に行動ファイルを読み込みます。検証に失敗したファイルはスキップされ、コンソールに理由とともに
Could not load behavior <file>またはCould not load behavior module <file>が出力されます。 - プログラムとモジュールのIDは、
elitemobs:behavior/basic_meleeのようにelitemobs名前空間を使います。IDは小文字で、a-z、0-9、.、_、-を使え、コロンの後には/も使えます。2つのプログラムが同じIDを共有することはできず、各モジュールIDは1つのファイルでのみ宣言してください。 - 1つの名前空間に含められるモジュールは最大256個です。モジュールが列挙できる依存関係は最大32個、プログラムが解決できるモジュールは最大64個で、各ソースファイルは1,000,000文字までに制限されます。
サンドボックスと読み込み
他のLuaスクリプトと同じサンドボックスのルールが適用されます。Luaサンドボックスを参照してください。行動ファイルには2つの違いがあります。
coroutineは使えません。xpcallはメッセージハンドラーを呼び出しません。falseとプレーンなエラーメッセージを返すため、pcallを使ってください。
各ファイルは、モブごとではなく読み込み時に1回コンパイルされ、その際にトップレベルのコードが検証のため実行されます。プログラムを実行する各モブは独自のLua環境を持ち、プログラムとそのモジュールのトップレベルのコードを再度実行するため、ファイルローカルの変数はモブ間で共有されません。ファイルが設定したグローバル変数は、そのファイルからのみ参照できます。どの実行でも、同じid、revision、modulesまたはdependenciesを返す必要があります。
プログラムとそのすべてのモジュールのトップレベルのコードは、250,000回のLua命令と50ミリ秒のCPU時間という1つの許容量を共有します。プログラムの開始時に別のLua呼び出しがすでに実行中の場合(たとえばモブをスポーンさせるスクリプトなど)、トップレベルのコードはその呼び出しの残りの許容量を使用します。トップレベルのコードは、定義と定数だけにとどめてください。
プログラムファイル
プログラムファイルはai.program { ... }を返します。
return ai.program {
id = 'elitemobs:behavior/basic_melee', revision = 1,
modules = {
'elitemobs:behavior/target', 'elitemobs:behavior/pursuit',
'elitemobs:behavior/melee', 'elitemobs:behavior/wander'
},
budget = {
callback_micros = 2000, entity_micros = 4000, server_micros = 5000,
max_callbacks = 20, max_instructions = 12000, max_action_requests = 2
}
}
| フィールド | 型 | 備考 |
|---|---|---|
id | string | 必須。名前空間付きのID。behaviors/内のファイルではelitemobs:...です。プログラムのモジュールのIDと同じにはできません。 |
revision | 正の整数 | 必須。 |
modules | 文字列の配列 | 任意。メモリ、センサー、ビヘイビアをプログラムに加えるモジュールのID。依存関係は、それを必要とするモジュールより先に読み込まれます。重複と依存関係の循環は拒否されます。 |
memories、sensors、behaviors | テーブル | 任意。プログラムはモジュールと同じ形式で独自のものを宣言できます。 |
budget | テーブル | 任意のソフトなスケジューリング制限。バジェットを参照してください。 |
runaway | テーブル | 任意のコールバックごとのハードな制限。バジェットを参照してください。 |
モジュールファイル
モジュールファイルはai.module { ... }を返し、再利用できるメモリ、センサー、ビヘイビアをまとめます。
| フィールド | 型 | 備考 |
|---|---|---|
id | string | 必須。名前空間付きのモジュールID。 |
revision | 正の整数 | 必須。 |
dependencies | 文字列の配列 | 任意。このモジュールが必要とする他のモジュールのID。 |
memories | テーブル | 任意。メモリを参照してください。 |
sensors | 配列 | 任意。ai.sensor { ... }のエントリー。 |
behaviors | 配列 | 任意。ai.behavior { ... }のエントリー。 |
settings | テーブル | 任意。ホストプラグインがクリーチャーごとに上書きできる、名前付きのデフォルト値。モジュール設定を参照してください。 |
sensors、behaviors、modules、dependenciesは、欠番や名前付きキーのない単純な配列である必要があります。センサー、ビヘイビア、メモリの名前は、プログラム内のすべてのモジュールを通じて一意である必要があります。
モジュール設定
settingsは、モジュールの調整可能な値とそのデフォルトを宣言します。
settings = {
radius = 8,
glow = true,
mode = 'circle',
foods = { 'minecraft:apple', 'minecraft:carrot' }
}
| 値 | 例 |
|---|---|
| 有限の数値 | radius = 8 |
trueまたはfalse | glow = true |
| テキスト | mode = 'circle' |
| テキストのリスト | foods = { 'minecraft:apple' } |
すべてのキーは名前である必要があります。リストは、欠番や名前付きキーのない、テキストだけの単純な配列である必要があります。関数や名前付きの値のテーブルなど、それ以外の値があるとモジュールは拒否されます。テーブルは記述されたとおりに読み取られ、そのテーブルに付いたメタテーブルは無視されます。
MagmaCoreはデフォルト値を検証してホストプラグインに渡すだけで、スクリプトからどう見えるかはホストプラグインが決めます。EliteMobsはモジュール設定を読み取らないため、behaviors/のファイルでは効果がありません。FreeMinecraftModelsのペットは、クリーチャーごとの値をデフォルトの上に統合し、モジュールのコールバックに、そのモジュール自身の設定をc.settingsとして渡します。ペット行動モジュールを参照してください。2.15.0の次のFreeMinecraftModelsリリースが必要なFreeMinecraftModelsのMob行動は、上書きが与える値で同じことを行います。Mob行動を参照してください。
メモリ
メモリは、1体のモブについてセンサーとビヘイビアが共有する型付きの値です。それぞれ名前を付けて宣言します。
memories = {
candidate = { type = 'uuid', persistent = false },
next_attack = 'integer'
}
| 型 | Luaの値 |
|---|---|
string | 文字列 |
boolean | 真偽値 |
integer | 整数 |
number | 数値 |
uuid | UUID文字列 |
position | { world = 'world', x = 0, y = 64, z = 0 } |
コロンを含まない名前は、プログラムの名前空間に置かれます。persistentのデフォルトはfalseで、trueにするとそのメモリはMindの保存状態とともにシリアライズされる対象になります。メモリの読み書きにはc.memory:get(name)、c.memory:set(name, value, ttl_ticks)、c.memory:forget(name)、c.memory:contains(name)を使います。setの3番目の引数は省略可能で、指定するとその値はそのtick数の後に期限切れになります。宣言していない名前を使うとエラーになります。
センサー
センサーは情報を収集し、通常はメモリに格納します。センサーはビヘイビアより先に実行されます。
ai.sensor {
id = 'elitemobs:behavior/find_target', interval = 20,
sense = function(c)
local target = c.perception:nearest_player(35)
if target then c.memory:set('candidate', target.uuid, 21)
else c.memory:forget('candidate') end
end
}
| フィールド | 型 | デフォルト | 備考 |
|---|---|---|---|
id | string | 必須。 | |
interval | 正の整数 | 1 | 実行間隔のtick数。 |
sense | function | 必須。Mindコンテキストを受け取ります。 |
センサーはc.actuatorを使えません。センサーからアクチュエーターのメソッドを呼び出すとエラーになります。
センサーのタイミング
センサーは、そのモブのボディが最初にtickされたtick(スポーン、チャンクの読み込み、プログラムの変更の後)に実行されます。その後はintervaltickごとに、モブごとに固有の位相で実行されるため、同時に作成されたモブがすべて同じtickに感知することはありません。2回目の実行は、1回目から最大でintervaltick後になります。モブがバジェットに達したためにスキップされた実行は、次のtickに再試行され、その後は元の位相に戻ります。
ビヘイビア
ビヘイビアは、宣言したコントロールを保持している間、モブに対して動作します。
ai.behavior {
id = 'elitemobs:behavior/attack', priority = 10,
controls = { ai.controls.attack },
can_start = function(c) return c.perception:current_target() ~= nil end,
can_continue = function(c) return c.perception:current_target() ~= nil end,
tick = function(c)
local target = c.perception:current_target()
if target then c.actuator:attack(target) end
end
}
| フィールド | 型 | デフォルト | 備考 |
|---|---|---|---|
id | string | 必須。 | |
priority | integer | 0 | 数値が小さいほど優先されます。 |
controls | array | なし | このビヘイビアが実行中に確保するコントロール。 |
probe_interval | 整数 | 1 | ビヘイビアが停止中にcan_startを確認する間隔のtick数。最小は1で、200を超える値は200として扱われます。プローブ間隔を参照してください。 |
can_start | function | 常にtrue | trueまたはfalseを返す必要があります。 |
can_continue | function | can_startと同じ | trueまたはfalseを返す必要があります。 |
start | function | なし | ビヘイビアの開始時に1回実行されます。 |
tick_interval | 整数 | 1 | ビヘイビアの実行中に、can_continueとtickを実行する間隔のtick数。最小は1で、200を超える値は200として扱われます。EliteMobs 10.9.14より後のリリース、またはFreeMinecraftModels 2.15.0より後のリリースが必要です。 |
tick | function | 必須。ビヘイビアの実行中、毎tick、またはtick_intervaltickごとに実行されます。 | |
stop | function | なし | function(c, reason)。ビヘイビアの停止時に実行されます。 |
ライフサイクル
- 停止中、ビヘイビアは毎tick、または
probe_intervaltickごとにcan_startを確認します。trueが返り、宣言したすべてのコントロールを確保できると、startが実行されます。 - 実行中は毎tick、または
tick_intervaltickごとに、そして開始したtickには必ず、まずcan_continueが実行されます。falseが返るとビヘイビアは理由completedで停止し、それ以外の場合はtickが実行されます。 stop(c, reason)は、completed、preempted、program_replaced、entity_removed、callback_failed、handle_closedのいずれかを受け取ります。停止するとビヘイビアのコントロールが解放され、保持していた移動、ターゲット、攻撃が止まります。
can_continue、start、tickでLuaエラーが発生すると、ビヘイビアはcallback_failedで停止します。can_startやcan_continueから真偽値以外を返すとエラーになります。失敗ごとに、コンソールにMind <program> callback <callback> failed with ...が出力されます。
プローブ間隔
デフォルトでは、停止中のビヘイビアは毎tickcan_startを確認します。probe_interval = Nを指定すると、代わりにNtickごとに、モブごとに固有の位相で確認します。そのため、同じビヘイビアを持つ多数のモブや、1体のモブの複数のビヘイビアが、すべて同じtickに確認することはありません。開始条件の負荷が高い場合や、正確なtickでの結果が不要な場合に使用してください。
- ボディのtickが始まってから最初の確認は、ビヘイビアの位相まで、最大N - 1tick待ちます。
- ビヘイビアの開始や、他のビヘイビアからのコントロールの奪取は、本来可能だったタイミングより最大N - 1tick遅れます。
- 停止したビヘイビアは、次の位相のtickで再び確認されます。最大でNtick後です。
- モブがバジェットに達したためにスキップされた確認や、バジェットによって延期された開始は、次のtickに再試行され、その後は位相に戻ります。
- ビヘイビアの実行中は何も変わりません。
can_continueとtickは引き続き毎tick、またはtick_intervaltickごとに実行され、stopも遅れません。can_continueのないビヘイビアは、can_continueのデフォルトがcan_startであるため、実行中も毎tickcan_startを呼び出します。
値は小数部のない1以上の数値である必要があり、それ以外の値を指定するとファイルは拒否されます。200(10秒)を超える値は200として扱われます。
コントロール
| コントロール | 許可される操作 |
|---|---|
ai.controls.move | c.actuator:move_to(...)、c.actuator:flee(...)、c.actuator:stop_moving() |
ai.controls.look | c.actuator:look_at(...) |
ai.controls.moveとai.controls.lookの両方 | c.actuator:steer_flight(...) |
ai.controls.jump | c.actuator:jump() |
ai.controls.target | c.actuator:set_target(...)、c.actuator:clear_target() |
ai.controls.attack | c.actuator:attack(...)、c.actuator:shoot(...) |
ai.controls.action | c.actions:request(...) |
ai.controls.use_item | 予約済み。Luaのアクチュエーターにはアイテム用のメソッドがありません。 |
各コントロールは、一度に1つの実行中ビヘイビアだけが保持します。priorityの数値が小さいビヘイビアは、数値が大きいビヘイビアからコントロールを奪い、奪われた側は理由preemptedで停止します。数値が小さいビヘイビアが保持しているコントロールは奪えません。優先度が同じ場合は、idがアルファベット順で先になるビヘイビアがコントロールを得ます。コントロールを保持せずにアクチュエーターのメソッドを呼び出すとエラーになります。c.actuator:stop_all()は、そのビヘイビアが保持しているものだけを停止します。
同梱モジュールでは、ターゲット選択が優先度5、近接攻撃が10、追跡が20、待機中の徘徊が50を使います。そのため、ターゲットが存在するとすぐに追跡が徘徊から移動を奪います。
逃走、射撃、ダメージの指定
この3つの呼び出しにはEliteMobs 10.9.14より後のリリースが必要です。
c.actuator:flee(location, speed)は、その地点から離れていく約10ブロックの経路を計画し、それをたどります。ボディが経路を計画できない、それだけの長さの逃げ道が見つからない、または別のシステムが移動を制御している場合はfalseを返します。計画では複数の逃げ道を試すため、数tickごとに呼び出してください。その間は経路をたどります。c.actuator:shoot(target)は、スケルトンの矢、ウィッチのポーション、ピリジャーのクロスボウ(空なら先に装填される)など、ボディの種類自身の遠距離攻撃を行います。遠距離攻撃を持たない種類ではfalseを返します。c.actuator:attack(target, damage)は、ボディ自身の攻撃ダメージの代わりに、そのダメージを与える一振りを行い、ダメージはボディが与えたものとして扱われます。
飛行の操舵
c.actuator:steer_flight(x, y, z)は、飛行するボディを、そのtickに限り、指定した速度(1tickあたりのブロック数)で動かします。モブに飛行を続けさせたいtickごとに呼び出してください。呼び出さなかったtickでは、ボディは再び通常のナビゲーションで動きます。この呼び出しはmove_toで開始した経路を停止し、ブロックと衝突し、ボディを水平方向の進行方向に向けて1tickあたり最大8度まで回転させます。1tickあたり4ブロック(毎秒80ブロック)を超える速度は、同じ向きのまま4に縮小されます。
ビヘイビアはai.controls.moveとai.controls.lookの両方を保持している必要があります。コントロールが不足している場合や、値が有限の数値でない場合はエラーになります。ボディが飛行できない場合や、他のシステムが移動を制御している場合、呼び出しはfalseを返して何もせず、それ以外の場合はtrueを返します。EliteMobsは、コウモリ、ブレイズ、ガスト、ファントム、ヴェックスなどの飛行するMobタイプに、飛行できるボディを与えます。
ボスのアクションの要求
ai.controls.actionを保持しているビヘイビアは、c.actions:request(identifier, payload)を呼び出せます。EliteMobsはこの要求を、on_mind_actionを通じてボスのLuaパワーに送ります。識別子は'elitemobs:slam'のような、128文字以内の小文字の名前空間付きキーである必要があります。ペイロードに含められるエントリーは最大16個で、キーは64文字以内の小文字、文字列の値は256文字までに制限されます。無効な識別子やペイロードはエラーになります。呼び出しはaccepted、deferred、rejectedのいずれかを返し、1tick内でプログラムのmax_action_requestsを超えた要求はdeferredを返します。ペイロードの形式はMindアクションのコンテキストを参照してください。
バジェット
budgetはソフトなスケジューリング制限を設定します。あるtickでモブがいずれかの制限に達すると、Mindランタイムは次のtickまでそのモブの残りのコールバックをスキップします。すでに実行中のコールバックは必ず最後まで実行されます。スキップされたセンサーの実行やcan_startの確認は、次のtickに再試行されます。
| キー | デフォルト | 備考 |
|---|---|---|
callback_micros | 2000 | これより長く実行されたコールバックがあると、そのtickのモブのコールバックは終了します。 |
entity_micros | 4000 | モブ1体・1tickあたりのコールバックの合計時間。 |
server_micros | 20000 | すべてのMindプログラムの合計使用時間がこの値に達すると、そのtickのモブのコールバックは停止します。 |
max_callbacks | 128 | モブ1体・1tickあたりのコールバック数。 |
max_action_requests | 8 | モブ1体・1tickあたりのアクション要求数。最大64。 |
すべての値は正である必要があり、callback_microsはentity_microsを、entity_microsはserver_microsを超えられません。
runawayは、1つのコールバックを中断するハードな制限を設定します。
| キー | デフォルト | 最大値 | 備考 |
|---|---|---|---|
cpu_micros | 50000 | 50000 | コールバックごとのスレッドCPU時間。 |
max_instructions | 50000 | 250000 | コールバックごとのLua命令数。 |
同梱のbasic_melee.luaのように、budgetでもmax_instructionsを指定できます。budgetとrunawayのどちらか一方で宣言し、両方には書かないでください。どちらの制限も正の値である必要があります。最大値より大きな値も読み込まれますが、警告なしに最大値まで引き下げられます。
これらの制限は実行中のコールバックを停止させるため、終わらないループはサーバーをフリーズさせずに失敗します。命令は実行されるたびにカウントされ、CPU時間は1,024命令ごとと、コールバックの終了時に確認されます。サーバーがスレッドのCPU時間を計測できない場合、cpu_microsは経過時間をその値の5倍に制限します。runawayの制限を超えたコールバックは、他のコールバックエラーと同じように失敗し、コンソールの行はfailed with RUNAWAY_LIMIT_EXCEEDEDとなります。
次のステップ
- ボスの作成:behavior -- ボスのプログラムを選択する
- Lua APIリファレンス:Mindプログラムのコンテキスト --
c.memory、c.perception、c.actuator、c.actionsのすべてのメソッド - フックとライフサイクル --
on_mind_actionとその他のLuaパワーフック - FreeMinecraftModelsペット行動モジュール -- ペット行動モジュールと、その
c.petおよびc.settingsフィールド
