MagmaCore Lua スクリプティングエンジン
MagmaCore は、EliteMobs のボスパワーと NPC スクリプト、FreeMinecraftModels のプロップ、カスタムエンチャント効果が使う Lua サンドボックスと ScriptInstance ランタイムを提供します。ファイル検証とインスタンス管理は共通ですが、利用可能なフック、コンテキスト、クールダウンの共有範囲、寿命は提供元に依存します。エンチャントのクエリには制限されたコンテキストと提供元固有の上限があるため、下記の専用リファレンスを参照してください。
FMM プロップと EliteMobs NPC は、MagmaCore の汎用テーブル (context.world、context.zones、context.scheduler、context.cooldowns、context.log、context.event、context.player、context.state) を直接継承し、context.prop または context.npc を追加します。ボスパワーは同じランタイムを使いますが、複数のテーブル (context.world、context.zones、context.cooldowns、context.scheduler、context.log、context.event) にボス固有の機能があり、context.players、context.entities、context.vectors、context.settings、context.script も提供します。
現在、以下のプラグインがこのエンジンを使用しています:
- EliteMobs -- カスタムボスの Lua パワー (
on_boss_damaged_by_player、on_enter_combatなど) と、操作・接近を扱う NPC Lua スクリプト (on_npc_interact、on_npc_proximity_enterなど)。 - FreeMinecraftModels -- プロップの Lua スクリプト (
on_right_click、on_left_clickなど) と、カスタムアイテム用のエンチャント効果。
このページでは FMM が使う汎用エンジン機能と、EliteMobs のボス・NPC との違いを説明します。ボスの正確なコンテキストは EliteMobs の Lua ページ、NPC は NPC Lua スクリプトを参照してください。
ちょっとした Lua 入門
Lua をまったく初めて使う方向けに、Nightbreak プラグインのスクリプトを書くために必要な最小限の構文を紹介します。
変数
値を保存するには local を使います:
local cooldown_key = "fire_burst"
local damage_multiplier = 1.5
local は、その変数がこのファイルやブロックの中だけのものであることを意味します。
関数
関数は再利用可能なロジックのブロックです:
local function warn_player(player)
player:send_message("&cMove!")
end
後で次のように呼び出せます:
warn_player(some_player)
if チェック
特定の条件下でのみ何かを実行したいときは if を使います:
if context.player == nil then
return
end
これは「このフックにプレイヤーがいなければここで終了する」という意味です。
nil
nil は「値がない」ことを意味します。Lua における「何もない」の表現です。
nil を確認するときは次のように書くことがよくあります:
if context.event ~= nil then
-- do something with the event
end
~= は「等しくない」を意味します。
テーブル
Lua ではテーブルが複数の用途に使われます:
- リスト
- 名前付きキーを持つオブジェクト
- 最終的に返されるスクリプト定義
名前付きキーを持つテーブルの例:
local particle = {
particle = "FLAME",
amount = 1,
speed = 0.05
}
スクリプト定義を返す
すべてのスクリプトファイルの末尾では 1 つのテーブルを返します:
return {
api_version = 1,
on_spawn = function(context)
end
}
返したテーブルがスクリプト定義です。ローダーはファイルを評価して検証し、保存したソースをインスタンスごとに再評価します。ファイル内のローカル変数はそのインスタンスに属し、同じファイルを使う全エンティティで共有されません。ファイルを編集しても、ロード済み定義や実行中のインスタンスは変わりません。提供元プラグインの手順で再読み込みしてください。
コメント
人間向けのメモを書くには -- を使います:
-- This cooldown stops the attack from firing every hit
context.cooldowns:set_local(60, "fire_burst")
Lua サンドボックス
すべての Lua スクリプトはサンドボックス化された LuaJ 環境内で実行されます。ファイルシステムや Java ランタイムにアクセスできるグローバルはいくつか除外されています。サンドボックスのルールは、MagmaCore を使用するすべてのプラグインで同一です。
除外されたグローバル
以下の標準 Lua グローバルは nil に設定されており、使用できません:
| 除外対象 | 理由 |
|---|---|
debug | 内部 VM 状態を公開する |
dofile | ファイルシステムアクセス |
io | ファイルシステムアクセス |
load | 任意コードの読み込み |
loadfile | ファイルシステムアクセス |
luajava | Java クラスへの直接アクセス |
module | モジュールシステム(不要) |
os | オペレーティングシステムへのアクセス |
package | モジュールシステム(不要) |
require | モジュールシステム/ファイルシステムアクセス |
利用可能な標準ライブラリ
LuaJ の標準環境では、次の通常の Lua 機能が使えます:
| カテゴリ | 関数 |
|---|---|
| Math | math.abs、math.ceil、math.floor、math.max、math.min、math.random、math.sin、math.cos、math.sqrt、math.pi、その他すべての math.* 関数 |
| String | string.byte、string.char、string.find、string.format、string.gsub、string.len、string.lower、string.match、string.rep、string.sub、string.upper、その他すべての string.* 関数 |
| Table | table.insert、table.remove、table.sort、table.concat、その他すべての table.* 関数 |
| Iterators | pairs、ipairs、next |
| Type | type、tostring、tonumber、select、unpack |
| エラー処理 | pcall、xpcall、error、assert |
| その他 | print、rawget、rawset、rawequal、rawlen、setmetatable、getmetatable |
os ライブラリは利用できませんos は完全に除外されています。汎用 API のワールド時刻には context.world:get_time() を使います。ボスパワーも共有の基底ワールドテーブルからこのメソッドを受け取ります。経過時間を扱うには on_game_tick で context.state に tick カウンタを保存してください。
print はコンソールに出力しますが、context.log:info(msg) を推奨します。すべての種類に context.log があり、FMM と NPC は info、warn、error、ボスパワーは info、warn、debug を提供します。
ファイル契約
すべての Lua スクリプトはテーブルを return しなければなりません。そのテーブルは意図的に厳格です。
必須・任意のトップレベルフィールド
| フィールド | 必須 | 型 | 備考 |
|---|---|---|---|
api_version | Yes | Number | 現状は 1 でなければならない |
priority | No | Number | 既定値 0、整数に変換される。EliteMobs のボスと NPC は小さい順。FMM は検証するが、プロップの実行順は scripts: のリスト順 |
| サポートされたフックキー | No | Function | プラグインがサポートする厳密なフック名を使う必要がある |
バリデーションルール
- ファイルは必ずテーブルを返さなければなりません。
api_versionは必須で、現在は1でなければなりません。priorityは存在する場合、数値でなければなりません。- それ以外のトップレベルキーは、サポートされたフック名でなければなりません。
- 各フックキーは関数を指していなければなりません。
- 未知のトップレベルキーは拒否されます。
MagmaCore の検証はすべてのスクリプトで priority を受け付けます。EliteMobs はボスと NPC の実行順に使いますが、FMM プロップは設定の scripts: 順です。カスタムエンチャントは提供元のカタログとアクション・クエリのライフサイクルに従います。
スクリプトファイルの配置場所
各提供元がディレクトリを選びます。汎用エンジンは .lua を再帰検索し、アーカイブ済み設定のパスを除外します。正規化した絶対パスを大文字小文字を無視して並べ、同順位なら正確なパスで並べます。小文字化したファイル名ごとに最初のものを選び、選んだファイルと内容が異なる重複をログに記録します。選んだファイルが検証に失敗しても、重複ファイルには切り替えません。登録後の参照は選ばれたファイルの実際の表記を保持するため、その表記を使ってください。ボスパワーとエンチャントカタログの探索規則は別で、共通の検証を使ってもディレクトリは交換できません。
スクリプトはパスではなくファイル名をキーとして管理されます。異なるサブフォルダにある2つの door.lua は同じキーとなり、どちらか一方しか登録されません。すべてのスクリプトに固有のファイル名を付けてください。
ヘルパー関数やローカル定数は、実際のフックでない限り、最終的な return の 上 に書き、返されるテーブル内に含めるべきではありません。
local ANIMATION_NAME = "idle"
local function do_something(context)
context.log:info("Doing something!")
end
return {
api_version = 1,
priority = 0,
on_spawn = function(context)
do_something(context)
end
}
共通して使われるフック名
これらの名前は複数のランタイムで使われますが、種類ごとに対応するフックだけが有効です。FMM プロップは下記すべて、ボスは専用のリストを使います。NPC は on_spawn、on_remove、on_game_tick、on_npc_interact、on_npc_proximity_enter、on_npc_proximity_leave、on_zone_enter、on_zone_leave を使います。
| フック | 発火タイミング |
|---|---|
on_spawn | FMM プロップ、EliteMobs ボス・NPC のスポーン処理が発火させる。ScriptInstance の構築だけでは発火しない |
on_game_tick | 初期化済みのインスタンスが有効で一時停止していない間、毎 tick 呼ばれる |
on_zone_enter | 対応するゾーンの入場時。FMM と NPC はプレイヤーの監視、ボスのトップレベルフックは EliteScript のゾーンイベントから発火 |
on_zone_leave | 対応するゾーンの退場時。FMM と NPC はプレイヤーの監視、ボスのトップレベルフックは EliteScript のゾーンイベントから発火 |
メソッド構文: : と .
Lua では、object:method(arg) は object.method(object, arg) の省略形です。MagmaCore のコンテキストテーブルのメソッドは暗黙の第1引数を取り除くため、context.log.info などでは両方の形式が使えます。
context.log:info("hello")
context.log.info("hello") -- same thing
em のグローバル関数は . で呼び出します。例：em.create_location(...)、em.zone.create_sphere_zone(...)、em.location.is_protected(...)。EliteMobs のイベント変更関数 context.event.set_damage_amount(...) と context.event.multiply_damage_amount(...) も . が必須です。このドキュメントではコンテキストテーブルのメソッドに :、通常の関数に . を使用します。
実行バジェット
すべてのフック呼び出し、すべてのスケジュール済みコールバック、そしてスクリプトファイル自体の初回評価は、厳格な実行バジェットの下で実行されます。このバジェットは Lua VM の内部で強制されるため、実行後に時計を確認するのではなく、コードの実行中に適用されます。
通常のランタイムには次の上限があります:
| 制限 | 値 |
|---|---|
| 現在のスレッドの CPU 時間 | 50 ミリ秒 |
| 実行された Lua 命令数 | 250,000 |
超過すると Lua エラーになります。命令数は命令ごと、時計は 1,024 命令ごとと呼び出し完了後に確認します。実行中の Java/Bukkit メソッドを中断するものではなく、CPU 時間 50 ms は実時間 50 ms の期限ではありません。フックやコールバックの未処理エラーはインスタンスを閉じ、初回検証のエラーは定義を拒否します。スレッド CPU 時間が測れない場合は経過時間 250 msと同じ命令数上限を使います。エンチャントのクエリバッチにはさらに小さい枠が適用される場合があります。
VM は Lua 命令の実行中にバジェットを確認するため、while true do end は中断されます。それでもサーバースレッドの CPU 枠を使い切る場合があり、スクリプトも無効になります。この保護を前提に無制限のループを書かないでください。
ネストした呼び出しは、呼び出しチェーン全体で CPU 時間50ミリ秒と250,000命令のバジェットを共有します。各呼び出しに別々の枠は与えられません。
バジェット内に収めるためのコツ:
- フック内で無限ループを避ける。
on_game_tickハンドラは軽量に保つ -- これらは毎 tick 実行される。context.scheduler:run_repeating(...)を使って作業を複数の tick に分散させる。- 重い処理には
context.cooldownsや適切な実行間隔を設ける。
フックやコールバックの未処理エラーはインスタンスを閉じ、所有する処理をキャンセルします。定義を修正して再読み込みし、提供元に新しいインスタンスを作成させてください。ファイルの保存だけでは閉じたインスタンスは直りません。エンチャントの提供元には独自の失敗抑制規則もあります。
context.state
スクリプトインスタンスの生存期間全体にわたって持続するプレーンな Lua テーブル。フラグ、カウンタ、タスク ID、トグル状態、フック間で共有したいデータを格納するために使用します。
return {
api_version = 1,
on_spawn = function(context)
context.state.is_open = false
context.state.click_count = 0
context.state.task_id = nil
end,
on_right_click = function(context)
context.state.click_count = (context.state.click_count or 0) + 1
end
}
context.state はインスタンスのフック間で共有するメモリ上のデータで、再読み込みや再起動では保存されません。他のテーブルは遅延構築され、取得時点の値を含むことがあります。FMM は context.prop をキャッシュしますが、current_location などは遅延取得します。現在値を得るには動的フィールドを再度読んでください。変数に保存したテーブル自体は更新されず、動的フィールドへの代入は getter を隠します。
context.log
すべての種類で使えるコンソールログです。汎用 log.info は [Lua] を付けます。発信元を区別する場合はメッセージにラベルを含めてください。エラー診断にはファイル名が付きますが、通常のログには自動では付きません。FMM と NPC は info、warn、error、ボスは info、warn、debug を提供します。
| メソッド | 備考 |
|---|---|
log:info(message) | 情報メッセージ |
log:warn(message) | 警告メッセージ |
log:error(message) | 警告レベルのメッセージ(log:warn と同じく WARN レベルでログに出力される) |
EliteMobs の context.log は error の代わりに debug を登録します。デバッグ出力には log:debug(message) を使用してください(debug プレフィックス付きの info レベルとして表示されます)。
context.log:info("Script loaded!")
context.log:warn("Something unexpected happened")
-- Generic/FMM/NPC logger:
context.log:error("Critical failure in zone setup")
-- EliteMobs boss logger:
context.log:debug("Boss debug detail")
context.cooldowns
ローカルと汎用グローバルのクールダウンは、設定の 1 tick を単調増加時計の経過時間 50 ms に換算します。一時停止中や低 TPS 時間も含みます。ボスのグローバルクールダウンだけはサーバー tick を数えます。共有範囲は次の 2 種類です:
- ローカルクールダウン は所有者のストア内で完全一致の文字列キーを使います。共有範囲は下記のとおりです。
nilで既定の__lua:とファイル名を連結したキーを選べます。 - グローバルクールダウン は同じオーナーエンティティ上のすべてのスクリプトで共有されます(例: 同じプロップ上のすべてのスクリプト、同じボス上のすべての Lua パワー)。
cooldowns:check_local(key?, duration)
ローカルキーを確認し、使用可能なら開始して true、そうでなければ false を返す単一の同期 Lua 呼び出しです。グローバルの確認や開始は行いません。このストアは別スレッド間のロック API ではありません。
| パラメータ | 型 | 備考 |
|---|---|---|
key | string (任意) | クールダウン識別子。nil で既定のキー |
duration | int | クールダウンの長さ(tick 単位、20 = 1 秒) |
on_right_click = function(context)
-- Only allow this action once every 3 seconds
if not context.cooldowns:check_local("interact", 60) then
return
end
-- ... do the action
end
ボス、NPC、FMM のすべてが check_local(key?, duration) を使います。既定キーなら check_local(nil, 60) としてください。check_local(60) は既定キーの 60 tick を意味しません。旧実験版 NPC の check_local(duration, key?) は現在の順序に修正してください。
cooldowns:local_ready(key?)
ローカルクールダウンが終了していれば(または設定されていなければ)true を、まだ有効なら false を返します。
cooldowns:local_remaining(key?)
ローカルクールダウンの残り tick 数を返します。準備完了なら 0 を返します。
cooldowns:set_local(duration, key?)
すでに有効かどうかを確認せずにローカルクールダウンを設定します。無条件のクールダウンリセットに使います。
| パラメータ | 型 | 備考 |
|---|---|---|
duration | int | tick 単位の期間。0 または負の値でクリア |
key | string (任意) | クールダウン識別子。nil で既定のキー |
cooldowns:global_ready()
グローバルクールダウン(同じエンティティ上のすべてのスクリプトで共有)が終了していれば true を返します。
cooldowns:set_global(duration)
グローバルを設定します。汎用テーブルではゼロ以下で解除します。ボスのグローバルクールダウンは遅い方の期限を保持します。短い期間で有効なグローバルクールダウンが短縮されることはなく、ゼロ以下の期間では何も起こりません。ローカルを設定してもグローバルは設定されず、その逆も同様です。
| パラメータ | 型 | 備考 |
|---|---|---|
duration | int | tick 単位の期間 |
グローバルクールダウンの「オーナー」はスクリプトタイプによって異なります:
- EliteMobs Lua パワー —
EliteEntity単位で共有(ボスごとに 1 バケット)。global_ready()/set_global()はボスに組み込まれたパワークールダウンシステムを使い、ローカルクールダウンも同じボス上のすべてのパワーで共有されます。 - EliteMobs NPC — NPC の単一アダプタを通してグローバルと明示的ローカルキーを共有します。同じキーを使うスクリプトは相互に影響し、省略時のキーはファイル別です。
- FMM プロップ — グローバルは設置されたプロップ単位。各スクリプトは独自のアダプタとローカルストアを持ちます。
- エンチャントアクション — グローバルは提供元内のプレイヤー単位。ローカルはプレイヤーとエンチャント ID に属し、装備交換やアクション終了をまたいで残ります。カスタムエンチャントを参照してください。
context.scheduler
遅延・繰り返しタスクを実行します。この API が作ったタスクはインスタンスに属し、終了時にキャンセルされます。作成したエンティティ、ワールド編集、別の UI・効果ヘルパーのタイマーは元に戻しません。一時停止中、期限を迎えた単発タスクは再開を待ち、繰り返しタスクは停止中の呼び出しを飛ばします。
ここでは MagmaCore の名前 (run_later、run_repeating、cancel) を使います。EliteMobs の名前 (run_after(ticks, callback)、run_every(interval, callback)、cancel_task(taskId)) もすべての種類で使える別名です。
scheduler:run_later(ticks, callback)
遅延後に 1 度だけコールバックを実行します。数値のタスク ID を返します。
| パラメータ | 型 | 備考 |
|---|---|---|
ticks | int | サーバー tick 単位の遅延(20 tick = 1 秒) |
callback | function | 遅延が終了したとき、新しい context と共に呼ばれる |
context.scheduler:run_later(40, function(delayed_context)
delayed_context.log:info("2 seconds have passed!")
end)
scheduler:run_repeating(delay, interval, callback)
固定間隔でコールバックを繰り返し実行します。数値のタスク ID を返します。
| パラメータ | 型 | 備考 |
|---|---|---|
delay | int | 最初の実行までの初期遅延(tick) |
interval | int | その後の各実行の間隔(tick) |
callback | function | 間隔ごとに新しい context と共に呼ばれる |
context.state.particle_task = context.scheduler:run_repeating(0, 20, function(tick_context)
tick_context.log:info("Another second passed!")
end)
scheduler:cancel(taskId)
このインスタンスに属するタスクを ID でキャンセルします。未知の ID や他のインスタンスの ID には何もしません。
| パラメータ | 型 | 備考 |
|---|---|---|
taskId | int | run_later または run_repeating が返したタスク ID |
所有タスクは終了時に自動キャンセルされます。操作や戦闘フェーズが終わってもインスタンスが残る場合は、ボスの on_exit_combat などで先にキャンセルしてください。どちらの名前も使えます。提供元のライフサイクルフックを使い、エラーで閉じたときに独自の後片付けフックが呼ばれるとは考えないでください。
コールバックは元のイベントや実行主体を含まない新しいコンテキストを受け取ります。外側ではなく、その引数を使ってください。元のプレイヤーが必要ならフック内で UUID を保存し、後で再検索して利用可能か確認します。保持した外側のコンテキストは、元のイベント終了後に遅延イベントフィールドを解決してしまう場合もあります。
context.world
ワールドの照会・操作用テーブルです。最初に構築した時点の所有者のワールドを保持し、保存したテーブルは後のワールド移動を追従しません。
ここでは FMM プロップと NPC が受け取る共有テーブルを説明します。ダメージを伴う strike_lightning(...) も含まれます。FMM は任意の EliteMobs 移動・戦利品ヘルパーを追加します。FMM のワールド拡張を参照してください。EliteMobs はロード済みチャンクを確認する視覚的な雷、NPC・ボス生成を共有テーブルに追加し、ボスパワーはさらに独自のメソッドを追加・置換します。ワールドと環境を参照してください。
汎用 API には strike_lightning(x, y, z)、spawn_particle(name, x, y, z, ...) と、strike_lightning_at_location(loc)、spawn_particle_at_location(loc, ...) の両形式があります。ボスも両形式に対応しますが、一部の位置テーブルメソッドはボス固有の動作です。
共有位置引数には x、y、z が必要です。ワールドが省略・解決不能ならテーブルのワールドを使います。共有の位置指定パーティクルは保持したワールドを使うため、同じワールドの位置を渡してください。ボス用変換と em.location.* の規則は別です。
ワールドテーブルの完全なリファレンスには、エンティティ検索、通行可能性・保護の照会、色付きダスト、地形への衝撃、位置テーブル形式もあります。
world.name
ワールド名を保持する文字列フィールドです。
world:get_block_at(x, y, z)
マテリアル名を "stone"、"air" などの小文字で返します。チャンクが未ロードなら強制ロードせず "air" を返します。
| パラメータ | 型 | 備考 |
|---|---|---|
x | int | ブロックの X 座標 |
y | int | ブロックの Y 座標 |
z | int | ブロックの Z 座標 |
world:set_block_at(x, y, z, material)
メインスレッドでブロックを設定し、チャンクの強制ロードを避けます。
| パラメータ | 型 | 備考 |
|---|---|---|
x | int | ブロックの X 座標 |
y | int | ブロックの Y 座標 |
z | int | ブロックの Z 座標 |
material | string | Bukkit Material 名、小文字(例: "stone"、"air"、"oak_planks") |
マテリアルが有効で要求をキューに入れた場合は true、無効なら false です。実行時にチャンクが未ロードなら変更を飛ばします。
地域保護は自動確認しません。ブロックのマテリアルを使い、先に該当する保護クエリを呼んでください。要求の受理は変更完了の証明ではありません。
world:spawn_particle(particle, x, y, z, count, dx, dy, dz, speed)
指定位置にパーティクルを生成します。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
particle | string | 必須 | Bukkit Particle enum 名。検索時に大文字化する ("FLAME"、"HAPPY_VILLAGER" など) |
x | number | 必須 | X 座標 |
y | number | 必須 | Y 座標 |
z | number | 必須 | Z 座標 |
count | int | 1 | パーティクル数 |
dx | number | 0 | X の広がり/オフセット |
dy | number | 0 | Y の広がり/オフセット |
dz | number | 0 | Z の広がり/オフセット |
speed | number | 0 | パーティクル速度 |
DUST や FALLING_DUST などは、この簡易 API が提供しない追加データを必要とします。CLOUD、SMOKE、CAMPFIRE_COSY_SMOKE、SNOWFLAKE、FLAME、HAPPY_VILLAGER、HEART、NOTE、ENCHANT など、データ不要のものを使ってください。色付きダストはワールドテーブルの world:spawn_dust(...) を使います。
追加データ必須のパーティクルは Bukkit 例外を起こしてインスタンスを無効化する場合があります。FMM/MagmaCore スクリプトでは上記のデータ不要の名前を推奨します。
world:play_sound(sound, x, y, z, volume, pitch)
指定位置でサウンドを再生します。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
sound | string | 必須 | Bukkit Sound enum 名(例: "ENTITY_EXPERIENCE_ORB_PICKUP")またはカスタムリソースパックのサウンドキー(例: "mypack:boss.roar") |
x | number | 必須 | X 座標 |
y | number | 必須 | Y 座標 |
z | number | 必須 | Z 座標 |
volume | number | 1.0 | 音量 |
pitch | number | 1.0 | ピッチ |
名前はまず Bukkit の登録済みサウンドと照合されます(大文字小文字は区別されないため、"ENTITY_ARROW_SHOOT" と "entity_arrow_shoot" は同じです)。一致するものがなければ、小文字のネームスペースキーに正規化され、カスタムリソースパックのサウンドとして再生されます。既知のサウンドでも有効なネームスペースキーでもない値は、エラーを発生させるのではなく何も再生しません。つまり、タイプミスはスクリプトを無効化せず、静かに何も起こらないだけです。
同じことが world:play_sound_at_location(loc, sound, volume, pitch) にも当てはまります。
world:strike_lightning(x, y, z)
指定位置に雷を落とします(視覚的効果とダメージあり)。
| パラメータ | 型 | 備考 |
|---|---|---|
x | number | X 座標 |
y | number | Y 座標 |
z | number | Z 座標 |
world:get_time()
現在のワールド時刻を tick 単位で返します。
world:set_time(ticks)
ワールド時刻を設定します。
| パラメータ | 型 | 備考 |
|---|---|---|
ticks | int | ワールド時刻(0 = 夜明け、6000 = 正午、13000 = 夜、18000 = 真夜中) |
world:get_nearby_entities(x, y, z, radius)
指定座標を中心とする軸に平行な箱内のエンティティを、添字 1 からの配列で返します。スクリプト所有者は除外しません。
| パラメータ | 型 | 備考 |
|---|---|---|
x | number | 中心 X |
y | number | 中心 Y |
z | number | 中心 Z |
radius | number | 検索半径(3 軸とも half-extent として使用) |
ドロップアイテムや発射物など生体ではないものも含む、範囲内のすべてのエンティティを返します。生体用メソッドを呼ぶ前に if entity.damage then を確認してください。
world:get_nearby_players(x, y, z, radius)
各軸の半幅を radius とする箱内のプレイヤーを、添字 1 からの配列で返します。ゲームモードでは絞り込みません。
| パラメータ | 型 | 備考 |
|---|---|---|
x | number | 中心 X |
y | number | 中心 Y |
z | number | 中心 Z |
radius | number | 検索半径 |
world:spawn_entity(entity_type, x, y, z)
指定位置にバニラ Minecraft エンティティをスポーンします。
| パラメータ | 型 | 備考 |
|---|---|---|
entity_type | string | Bukkit のエンティティタイプ名、小文字(例: "zombie"、"skeleton"、"pig") |
x | number | X 座標 |
y | number | Y 座標 |
z | number | Z 座標 |
エンティティテーブルを返し、該当すれば生体用メソッドも含みます。未知の enum 名は nil、有効でも生成不能な種類はエラーになる場合があります。チャンクのロード状態は確認しません。
world:get_highest_block_y(x, z)
Bukkit が返す X/Z の最上位ブロックの Y を返します。get_block_at と異なり、ロード済みチャンクの確認はありません。
| パラメータ | 型 | 備考 |
|---|---|---|
x | int | ブロックの X 座標 |
z | int | ブロックの Z 座標 |
world:raycast(from_x, from_y, from_z, dir_x, dir_y, dir_z, [max_distance], [fluid_mode], [blocks_only], [loaded_only])
ある点から方向にレイをキャストし、ヒットした内容に関する情報を返します。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
from_x | number | 必須 | 始点 X |
from_y | number | 必須 | 始点 Y |
from_z | number | 必須 | 始点 Z |
dir_x | number | 必須 | 方向ベクトルの X 成分 |
dir_y | number | 必須 | 方向ベクトルの Y 成分 |
dir_z | number | 必須 | 方向ベクトルの Z 成分 |
max_distance | number | 50 | 最大射程 |
fluid_mode | string | "NEVER" | NEVER、SOURCE_ONLY、ALWAYS |
blocks_only | boolean | false | エンティティを無視してブロックだけを調べる |
loaded_only | boolean | false | レイの外接長方形内に未ロードのチャンクがあれば、追跡せず nil を返す |
loaded_only=true では結果が nil の場合も確認してください。それ以外で何にも当たらなかった場合は、ヒットフィールドが nil のテーブルを返します:
| フィールド | 型 | 備考 |
|---|---|---|
hit_entity | entity table or nil | レイが最初にヒットしたエンティティ。なければ nil |
hit_location | location table or nil | 何かにヒットした正確な点 |
hit_block | table or nil | ヒットしたブロックの {x, y, z, material}。ブロックにヒットしなければ nil |
マテリアル名は小文字です。複合追跡はエンティティのレイサイズ 0.5 を使い、エンティティフィルタはありません。ロード確認は外接長方形全体を調べるため、実際のレイから離れた未ロードのチャンクでも拒否する場合があります。不正な流体モード名はエラーです。
world:spawn_firework(x, y, z, colors, [type], [power])
指定位置に花火ロケットをスポーンします。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
x | number | 必須 | X 座標 |
y | number | 必須 | Y 座標 |
z | number | 必須 | Z 座標 |
colors | table | 必須 | 色文字列の配列。例: {"RED", "BLUE", "WHITE"} |
type | string | "BALL" | 花火形状: "BALL"、"BALL_LARGE"、"STAR"、"BURST"、"CREEPER" |
power | int | 1 | 飛距離パワー、0-127 |
-- Example: red and yellow firework burst
context.world:spawn_firework(loc.x, loc.y, loc.z, {"RED", "YELLOW"}, "BURST", 2)
world:place_temporary_block(x, y, z, material, [ticks], [require_air])
一時ブロックを設置し、正の期間後に保存した BlockData を復元します。完全なブロック状態やインベントリは保存しません。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
x | int | 必須 | ブロックの X 座標 |
y | int | 必須 | ブロックの Y 座標 |
z | int | 必須 | ブロックの Z 座標 |
material | string | 必須 | Bukkit Material 名(例: "stone"、"ice") |
ticks | int | 0 | 復元までの tick 数。ゼロ以下なら追跡せずにブロックを恒久的に設置 |
require_air | boolean | false | true の場合、対象が空気のときだけ設置する |
マテリアルが無効かチャンクが未ロードなら false。それ以外は要求受理時に true を返します。require_air=true で対象が空気でなければ、要求が受理されても置換を行いません。
正の tick を指定すると、マネージャーは元の BlockData を保存し、タイマー終了時、チャンクやワールドのアンロード時、またはプラグインの終了時に復元します。復元するのはブロックがまだ一時ブロックのままである場合だけなので、後からの編集は上書きされません。まだ一時ブロックが置かれているブロックに再度設置すると、タイマーが再開され、最初に保存した元のブロックが維持されます。チェストや看板などのブロックエンティティを持つブロックと、エンチャントの貸し出しなど別の一時ブロック所有者がすでに保持しているブロックはスキップされます。一時ブロックを壊しても何もドロップせず、復元しないまま追跡が終了します。そこにブロックを設置した場合も追跡は終了します。
タイマーは Lua 終了時にキャンセルされず、地域保護も自動では確認しません。
world:drop_item(x, y, z, material, [amount])
指定位置に自然なばらつきを付けてアイテムエンティティをドロップします。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
x | number | 必須 | X 座標 |
y | number | 必須 | Y 座標 |
z | number | 必須 | Z 座標 |
material | string | 必須 | Bukkit Material 名 |
amount | int | 1 | スタックサイズ |
ドロップされたアイテムのエンティティテーブルを返します。マテリアルが無効なら nil を返します。
context.zones
ゾーンを作成し、プレイヤーの出入りを監視します。FMM プロップと NPC はここに記載する create_sphere(...)、create_cylinder(...)、create_cuboid(...)、watch(...)、unwatch(...) を使い、on_zone_enter と on_zone_leave を発火させます。ゾーンはインスタンスに属し、終了時に除去されます。ボスは get_entities_in_zone(...)、get_locations_in_zone(...)、watch_zone(...) などの専用テーブルを使います。ゾーンとターゲティングを参照してください。
zones:create_sphere(x, y, z, radius)
指定座標を中心とした球を作り、数値ハンドルを返します。所有者にワールドがなければ nil です。
| パラメータ | 型 | 備考 |
|---|---|---|
x | number | 中心 X |
y | number | 中心 Y |
z | number | 中心 Z |
radius | number | 球の半径 |
zones:create_cylinder(x, y, z, radius, height)
円柱を作り、数値ハンドルを返します。所有者にワールドがなければ nil です。
| パラメータ | 型 | 備考 |
|---|---|---|
x | number | 中心 X |
y | number | 中心 Y(底面) |
z | number | 中心 Z |
radius | number | 円柱の半径 |
height | number | 円柱の高さ |
zones:create_cuboid(x, y, z, xSize, ySize, zSize)
直方体を作り、数値ハンドルを返します。所有者にワールドがなければ nil です。汎用監視はプレイヤー位置の点を調べるので、サイズは中心からの半幅です。ボスのエンティティ重なり判定やサンプル位置の操作とは異なります。zSize がゼロで xSize が非ゼロなら、共有の形状は Z に xSize を使います。
| パラメータ | 型 | 備考 |
|---|---|---|
x | number | 中心 X |
y | number | 中心 Y |
z | number | 中心 Z |
xSize | number | X 方向の half-extent |
ySize | number | Y 方向の half-extent |
zSize | number | Z 方向の half-extent |
zones:watch(handle, onEnterCallback, onLeaveCallback)
作成済みゾーンの出入りの通知を有効にします。引数は Lua 関数である必要がありますが、本体は呼ばれず、処理は on_zone_enter と on_zone_leave で行います。所属の追跡は作成時から始まるので、後から watch を付けても、既に内部として追跡されているプレイヤーの入場は通知しません。後の watch 呼び出しで nil を渡しても、有効な通知は解除されません。
| パラメータ | 型 | 備考 |
|---|---|---|
handle | int | create_* 呼び出しから得られたゾーンハンドル |
onEnterCallback | function または nil | 関数で on_zone_enter を有効化する。関数本体は無視 |
onLeaveCallback | function または nil | 関数で on_zone_leave を有効化する。関数本体は無視 |
監視の設定に成功すれば true、ゾーンハンドルが無効なら nil を返します。
on_game_tick より前に、所有者の現在のワールド内のプレイヤー位置を点として調べます。プレイヤー全体の箱ではありません。球は半径の厳密な内側、円柱は半径の内側かつ底面を含み上面を除く高さを使います。ゾーンは作成時の座標とワールドを保持します。切断や監視解除で退場フックが発火する保証はありません。ゾーン数は適切に抑えてください。
zones:unwatch(handle)
ゾーンの監視を停止し、リソースをクリーンアップします。
| パラメータ | 型 | 備考 |
|---|---|---|
handle | int | 監視停止対象のゾーンハンドル |
例: 近接トリガーゾーン
return {
api_version = 1,
on_spawn = function(context)
local loc = context.prop.current_location
if loc == nil then return end
local handle = context.zones:create_sphere(loc.x, loc.y, loc.z, 5)
-- Pass placeholder functions to enable on_zone_enter and on_zone_leave hooks.
-- The placeholder bodies are ignored; the actual logic goes in the hooks below.
context.zones:watch(handle, function() end, function() end)
context.state.zone_handle = handle
end,
on_zone_enter = function(context)
context.log:info("Player entered zone!")
end,
on_zone_leave = function(context)
context.log:info("Player left zone!")
end,
on_destroy = function(context)
if context.state.zone_handle then
context.zones:unwatch(context.state.zone_handle)
end
end
}
context.event
フックにイベントか実行主体がある場合に存在します。FMM プロップのクリックはプラグインのキャンセルフラグを使い、NPC 操作や汎用ゾーンは Bukkit イベントなしで実行主体を渡す場合があります。on_game_tick、スケジュール済みコールバック、起点となるプレイヤーがないライフサイクルフックでは存在しません。
FMM プロップの on_projectile_hit フックはキャンセル可能な FreeMinecraftModels の投射物命中イベントを受け取るため、cancel() と uncancel() があります。このフックは FMM が命中を処理した後に実行されるため、キャンセルしても貫通しない投射物が消費されるのは止められません。他のプラグインがすでに命中をキャンセルしている場合は発火しません。context.event.player は、射手が生物エンティティであればその射手（Mob の場合もあります）で、それ以外では存在しません。context.player はプレイヤーが投射物を発射した場合にのみ設定されます。このフックは、投射物のエンティティテーブルとして context.projectile も公開します。
汎用の on_zone_enter と on_zone_leave では、context.player と context.event.player が出入りしたプレイヤーです。キャンセル可能な Bukkit イベントではないため、cancel() と uncancel() はありません。
| フィールド / メソッド | 型 | 備考 |
|---|---|---|
is_cancelled | boolean | イベントサブテーブルを初めて解決した時点の状態。cancel()、uncancel() では更新されない |
cancel() | method | イベントをキャンセルする。キャンセル可能なイベントだけに存在 |
uncancel() | method | キャンセルを取り消す。キャンセル可能なイベントだけに存在 |
player | entity table | イベントに関与するプレイヤー(該当する場合) |
on_right_click = function(context)
if context.event and context.event.cancel then
context.event:cancel() -- prevent the default right-click interaction
end
end
EliteMobs パワースクリプトでは、ダメージ量、ダメージ原因、ダメージ元参照、ダメージ修正メソッドを備えた、より詳細なイベントテーブルが利用できます。EliteMobs のイベントフィールドの全容は Lua API リファレンス を参照してください。
em ヘルパー名前空間
em はファイル読み込み時から使えます。コンストラクタはデータを作るだけで、ワールドのロード、監視登録、完成した形状の検証は行いません。返された setter は自身のテーブルを変更し、渡された位置テーブルを参照として保持します。
| 関数 | 用途 |
|---|---|
em.create_location(x, y, z [, world, yaw, pitch]) | location テーブルを作成する。任意でワールド名、yaw、pitch も指定可能。返されるテーブルには .add(dx, dy, dz) メソッドがあり、location を in-place でオフセットして自身を返すのでチェーン可能。 |
em.create_vector(x, y, z) | vector テーブルを作成する |
em.zone.create_sphere_zone(radius) | 球ゾーン定義を作成する |
em.zone.create_dome_zone(radius) | ドームゾーン定義を作成する |
em.zone.create_cylinder_zone(radius, height) | 円柱ゾーン定義を作成する |
em.zone.create_cuboid_zone(x, y, z) | 直方体ゾーン定義を作成する |
em.zone.create_cone_zone(length, radius) | 円錐ゾーン定義を作成する |
em.zone.create_static_ray_zone(length, thickness) | 静的レイゾーン定義を作成する |
em.zone.create_rotating_ray_zone(length, point_radius, animation_duration) | 回転レイゾーン定義を作成する |
em.zone.create_translating_ray_zone(length, point_radius, animation_duration) | 移動レイゾーン定義を作成する |
em.location.is_in_dungeon(loc) | location が登録済みダンジョンリージョン内かを確認する("dungeon" 種別を報告するすべての所有者を含む) |
em.location.is_protected(loc) | location が保護リージョン内かを確認する(WorldGuard、GriefPrevention、EM リージョンなど) |
em.location.owned_by(loc, namespace) | 特定のプラグイン namespace が location を所有しているかを確認する(例: "EliteMobs") |
em.location.owners(loc) | location を所有する namespace 文字列の配列 |
em.location.kinds_at(loc) | location における種類タグの配列("elitemobs"、"dungeon"、"world_package"、"open_world_dungeon"、ダンジョンサイズカテゴリ) |
em.location.has_kind(loc, kind) | location に指定の種類タグが付いているかを確認する |
MagmaCore は WorldGuard と GriefPrevention のアダプタを同梱します。利用側の有効化時、または保護クエリの遅延初期化で準備します。対象は登録済みの提供元であり、すべての保護プラグインではありません。登録済みリージョンアダプタが失敗した場合は保護ありとします。提供元も保護の所有権もなければ false となり、未登録の提供元は警告で示されます。
em.location.* の world にはロード済みワールド名か {name=...} を指定します。所有者のワールドへの代替はありません。ワールドが欠落・解決不能、または入力が nil なら false か空配列です。座標の省略値はゼロですが、不正な数値フィールドはエラーになる場合があります。所有者の名前空間は大文字小文字を区別し、種類タグは区別しません。所有権だけではダンジョン所属や保護を意味しません。返される配列の順序は保証されません。
ゾーンビルダーは、:set_center(loc)(またはゾーンタイプに応じて :set_origin(loc) / :set_destination(loc))を持つチェーン可能なテーブルを返します:
-- At file scope: create a reusable zone shape
local blast_zone = em.zone.create_sphere_zone(5)
return {
api_version = 1,
on_spawn = function(context)
-- Anchor the zone at call time
blast_zone:set_center(context.boss:get_location())
local entities = context.zones:get_entities_in_zone(blast_zone)
-- ...
end
}
em 名前空間は EliteMobs で特に有用で、context.zones:get_entities_in_zone() や context.script と組み合わせてゾーン定義を扱えます。FreeMinecraftModels では、シンプルな watch ベースのゾーンには context.zones:create_sphere(...) / create_cylinder(...) / create_cuboid(...) メソッドの方が一般的に利用されます。
エンティティテーブル
以下は共通メソッドの概要です。完全な Lua API リファレンスには発射物、移動経路確認、所有権、保護のヘルパーもあります。汎用エンティティテーブルが対象で、ボスパワーの専用ラッパーは別の節に記載しています。
ワールドクエリやイベントデータから返されるエンティティテーブルは、種類に応じたフィールドとメソッドを持ちます。
Entity ベースフィールド
| フィールド | 型 | 備考 |
|---|---|---|
uuid | string | エンティティの UUID |
entity_type | string | エンティティタイプ(例: "player"、"zombie"、"skeleton"、"villager") |
is_valid | boolean | エンティティ参照がまだ有効かどうか |
is_dead | boolean | エンティティが死亡しているか |
is_player | boolean | エンティティがプレイヤーか |
is_hostile | boolean | Bukkit の Monster を実装するか。現在の敵意ではない |
is_passive | boolean | Bukkit の Animals を実装するか。温厚な動作を保証しない |
current_location | location table | エンティティの現在位置(x、y、z、world、yaw、pitch) |
world | string | エンティティがいるワールド名 |
Entity ベースメソッド
| メソッド | 戻り値 | 備考 |
|---|---|---|
teleport(location_table) | void | x、y、z が必須。ワールド省略・解決不能なら自身のワールド。yaw、pitch は既定値ゼロ。移動経路や保護は自動確認しない |
remove() | void | エンティティをワールドから削除する。エンティティがまだ有効な場合のみ動作する。 |
set_silent(flag) | void | エンティティの音を抑制または再有効化する。 |
set_invulnerable(flag) | void | エンティティをダメージに対して無敵または脆弱にする。 |
set_gravity(flag) | void | エンティティの重力を有効/無効にする。 |
set_glowing(flag) | void | エンティティの発光アウトラインエフェクトを切り替える。 |
Living Entity フィールド
Living エンティティ(プレイヤー、モブなど)は、すべての Entity ベースフィールドに加えて以下を持ちます:
| フィールド | 型 | 備考 |
|---|---|---|
health | number | 現在の体力 |
maximum_health | number | 最大体力 |
name | string | 表示名 |
is_alive | boolean | エンティティが生存しているか |
Living Entity メソッド
| メソッド | 戻り値 | 備考 |
|---|---|---|
damage(amount) | void | エンティティに指定量のダメージを与える |
push(x, y, z) | void | 現在の速度にベクトルを即座に加える |
set_facing(x, y, z) | void | 同じ位置へ新しい向きでテレポートする |
add_potion_effect(effect, duration, amplifier) | void | ポーション効果を追加する。effect は文字列(例: "speed"、"slowness"、"regeneration")。duration は tick 単位。amplifier は効果レベル - 1(0 = レベル I)。 |
remove_potion_effect(effect) | void | 名前を指定してポーション効果を除去する |
get_scale() | number | 修正値込みの有効なスケール。利用不能なら 1.0 |
set_scale(value) | void | 利用可能ならスケール属性の基本値を変更する |
get_nearby_entities() から返されるエンティティがすべて living entity とは限りません。カテゴリでフィルタリングするには entity.is_player、entity.is_hostile、entity.is_passive を使えますし、living entity のメソッド(damage()、push()、add_potion_effect() など)を呼ぶ前に if entity.damage then で確認することもできます。
プラグイン統合フィールド
対応する拡張があれば統合フィールドを持ち、なければ存在せず nil として読まれます。追跡フラグ、モデル識別情報、管理者状態、大半の入れ子データは構築時のスナップショットで、その後の追跡変更に追従しません。共有の EliteMobs 体力フィールドは遅延取得で、モデルや権限のメソッドは呼び出し時に実体を調べます。
EliteMobs フィールド
EliteMobs がインストールされている場合に利用可能です。
| フィールド | 型 | 備考 |
|---|---|---|
is_elite | boolean | エンティティが EliteMobs のエリートか |
is_custom_boss | boolean | エンティティが EliteMobs のカスタムボスか(elite サブテーブル内でも参照可能) |
is_significant_boss | boolean | エンティティが体力倍率 1 超のカスタムボスか(つまり、フィラーエリートでない設計された遭遇か) |
elite | table or nil | エリート情報のサブテーブル(下記参照)。エリートでなければ nil。 |
elite サブテーブルには以下が含まれます:
| フィールド | 型 | 備考 |
|---|---|---|
elite.level | int | エリートのレベル |
elite.name | string または nil | エリートの表示名 |
elite.health | number | 現在の体力 |
elite.max_health | number | 最大体力 |
elite.is_custom_boss | boolean | これがカスタムボスか(自然発生のエリートではないか) |
elite.health_multiplier | number | 設定で定義された体力倍率 |
elite.damage_multiplier | number | 設定で定義されたダメージ倍率 |
elite:remove() | void | EliteMobs の除去処理を通す。討伐ではなく、戦利品も保証しない |
例: エリートに別の扱いでダメージを与える
local entities = context.world:get_nearby_entities(x, y, z, 5)
for _, entity in ipairs(entities) do
if entity.is_elite then
-- Deal double damage to elites
entity:damage(20)
context.log:info("Hit elite: " .. entity.elite.name .. " (level " .. entity.elite.level .. ")")
elseif entity.is_hostile then
entity:damage(10)
end
end
FreeMinecraftModels フィールド
FreeMinecraftModels がインストールされている場合に利用可能です。
| フィールド | 型 | 備考 |
|---|---|---|
is_modeled | boolean | エンティティに FMM モデルが付与されているか(DynamicEntity または PropEntity) |
is_prop | boolean | エンティティが FMM プロップ(静的な装飾エンティティ)か |
model | table or nil | モデル情報のサブテーブル(下記参照)。モデルがなければ nil。 |
model サブテーブルには以下が含まれます:
| フィールド | 型 | 備考 |
|---|---|---|
model.model_id | string または nil | モデルのブループリント ID (例: "torch_01") |
model.is_dynamic | boolean | モデル付きエンティティが DynamicEntity(モブ/ボスモデル)か、静的プロップではないか |
model:play_animation(name, [blend], [loop]) | boolean | アニメーション要求を受理する。blend、loop は既定値 false。キュー入りや攻撃の抑制でも、即再生せず true になる場合がある。終端の死亡状態では拒否 |
model:stop_animations() | void | 再生キューを消し、可能なら待機アニメーションに戻す。終端の死亡状態は変わらない |
model:remove() | void | FMM の適切な削除パイプラインを通してモデル付きエンティティを除去する。 |
FMM はプレイヤーテーブルにも次を追加します:
| フィールド / メソッド | 型 | 備考 |
|---|---|---|
is_op | boolean | サーバーのオペレーターか |
has_permission(node) | boolean | 指定の権限があるか |
この 2 つのプレイヤー値は FreeMinecraftModels のスクリプトにのみ存在します。EliteMobs 内で作成される共有テーブルでは、EliteMobs 自身の FreeMinecraftModels アダプタが is_modeled、is_prop、model を追加しますが、is_op と has_permission は追加しません。
FMM プレイヤーテーブルの is_holding_elitemobs_item(filename) は、メインハンドにある EliteMobs のファイル名タグを .yml 込みで確認します。表示名ではありません。空の手、別アイテム、連携不能なら false です。EliteMobs 自身の共有拡張は、データがあるとき戦闘 tier を含む elite_player を別途追加します。FMM の任意の EliteMobs アダプタはこのサブテーブルを追加しません。
モデルブリッジの blend と loop は既定値 false。プロップテーブルの play_animation は両方 true で、キューとループを使います。blend はキュー制御であり、アニメーション間のクロスフェードではありません。
例: エンティティタイプでフィルタリング
local entities = context.world:get_nearby_entities(x, y, z, 10)
for _, entity in ipairs(entities) do
if entity.is_prop then
-- Skip props
elseif entity.is_player then
entity:damage(5)
elseif entity.entity_type == "villager" then
-- Don't hurt villagers
elseif entity.is_elite then
entity:damage(20)
elseif entity.is_hostile then
entity:damage(10)
end
end
プレイヤー固有フィールド
プレイヤーエンティティはすべての entity および living entity フィールドに加えて以下を持ちます:
| フィールド | 型 | 備考 |
|---|---|---|
game_mode | string | プレイヤーのゲームモード("creative"、"survival"、"adventure"、"spectator") |
プレイヤー固有メソッド
API が「カラーコードに対応」と記載している箇所では、Magmacore が文字列を組み込みの MiniMessage パーサーに通します。レガシーの & コード、&#RRGGBB の16進、<#RRGGBB>、<gradient>、<rainbow>、そして MiniMessage のタグセットの残りはすべて機能し、自由に組み合わせられます。Kyori Adventure は依存関係ではなく、Adventure の API はスクリプトから利用できません -- そもそも必要ありません。
Lua のテキストメソッドはレガシーのカラーコード文字列へと変換されるため、カラー、グラデーション、装飾は正しく描画されますが、インタラクティブタグ(<hover>、<click>、<insert>、<font>、<key>、<lang>)は解析はされるものの効果を持ちません。完全なタグ一覧はカラーコードを参照してください。
| メソッド | 戻り値 | 備考 |
|---|---|---|
send_message(msg) | void | プレイヤーにチャットメッセージを送信する。カラーコードに対応。 |
chat(text) | void | 色処理済みテキストを Bukkit のプレイヤーチャットに送る。先頭がスラッシュならそのプレイヤーとしてコマンドを実行 |
get_held_item() | table or nil | メインハンドの {type, amount, display_name}。空なら nil。type は "GOLD_INGOT" など大文字の Bukkit Material 名 |
consume_held_item(amount?) | void | 実行時点のメインハンドからの消費をキューに入れる。既定値 1。確認済みアイテムを保持せず、支払い完了も確認しない。負数は拒否しないので正数を渡す |
has_item(material, amount?) | boolean | プレイヤーのインベントリ内のいずれかに指定マテリアルが少なくとも amount(デフォルト 1)あれば true を返す。 |
get_target_entity([range]) | entity table or nil | 目からブロックとエンティティを追跡し、自分を除外。エンティティのレイサイズは 0.5。液体と通行可能なブロックを無視し、既定射程は 50 |
get_eye_location() | location table | プレイヤーの目の高さでの location テーブルを返す。 |
get_look_direction() | table | プレイヤーが向いている方向の {x, y, z} ベクトルを返す。 |
send_block_change(x, y, z, material, [ticks]) | boolean | クライアント専用ブロックをキューに入れ、正の tick 数後に復元。true はキュー受理。無効またはブロック以外のマテリアルなら false |
reset_block(x, y, z) | boolean | 実際のブロック表示への復元をキューに入れ、true を返す |
sleep(x, y, z) | void | 実物の白いベッドと睡眠の試行をキューに入れる。起床・切断時に BlockData だけを復元し、ブロックエンティティの内容は復元しない |
wake_up() | void | 睡眠中のプレイヤーを起こす。 |
ブロック表示変更と復元は実行時のプレイヤーのワールドを読みます。ワールド移動後に元のブロックを復元できるとは考えないでください。睡眠の後片付けは 20 tick 後、その後は 10 tick ごとに確認します。これらのタスクは context.scheduler の所有対象ではありません。
プレイヤー UI メソッド
以下は共有プレイヤーテーブルのメソッドです。ボスパワーのプレイヤーテーブルはシグネチャが異なり、API リファレンスに記載しています。共有バーは提供元プラグインの MagmaCore コピー内でプレイヤーごとに管理し、スクリプト別ではありません。期限タイマーは自身を開始したバーまたは繰り返しアクションバーだけを削除するため、古い期限が新しいものを消すことはありません。Bukkit タイマーは context.scheduler に属しません。
player:show_boss_bar(text, [color], progress, [ticks])
共有のソリッド型ボスバーを置換します。進捗は 0..1 に制限し、無効な色は白です。色を省略する場合は nil を渡し、進捗を第 3 引数に保ってください。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
text | string | 必須 | 表示するテキスト。& カラーコードに対応。 |
color | string | "WHITE" | バーの色。次のいずれか: "RED"、"BLUE"、"GREEN"、"YELLOW"、"PURPLE"、"PINK"、"WHITE" |
progress | number | 必須 | 0.0(空)から 1.0(満杯)までの充填量 |
ticks | int | -1 | 正数なら削除を予約。それ以外は非表示または置換まで残る |
player:hide_boss_bar()
プレイヤー画面からボスバーを削除します。引数はありません。
player:show_action_bar(text, [ticks])
アクションバー領域(ホットバーの上)にテキストを表示します。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
text | string | 必須 | 表示するテキスト。& カラーコードに対応。 |
ticks | int | -1 | 正数なら期限まで 40 tick ごとに再送。それ以外は一度だけ送る。新しい呼び出しは以前の繰り返しタスクをキャンセル |
player:show_title(title, [subtitle], fade_in, stay, fade_out)
プレイヤーにタイトル画面を表示します。
| パラメータ | 型 | デフォルト | 備考 |
|---|---|---|---|
title | string | 必須 | メインタイトルのテキスト。& カラーコードに対応。 |
subtitle | string | "" | メインタイトルの下に表示されるサブタイトル。任意。 |
fade_in | int | 必須 | フェードインの時間(tick) |
stay | int | 必須 | タイトルが画面に表示され続ける時間(tick) |
fade_out | int | 必須 | フェードアウトの時間(tick) |
次のステップ
プラグイン固有のフック、API、ワークフローについて:
- EliteMobs: はじめに | NPC スクリプト | フックとライフサイクル | ボスとエンティティ | ワールドと環境 | ゾーンとターゲティング
- FreeMinecraftModels: はじめに | プロップ API | 例