內容附魔
EliteMobs 與 FreeMinecraftModels 透過共用的 MagmaCore 系統提供自訂附魔。每個插件在自己的 enchantments/ 目錄中管理定義和 Lua 效果。Minecraft 原版附魔仍使用 minecraft: 命名空間。
更新內建定義
目錄會還原缺少的內建 YAML 與 Lua 檔案，並向現有內建定義加入缺少的預設欄位。已有設定值和 Lua 原始碼會保留。即使 enchantments/ 目錄已經存在，此機制仍會生效。
所屬插件可能先封存符合已停用格式的檔案。例如，EliteMobs 會先保存含有 maxLevelV2 的附魔 YAML，再產生目前的預設內容。EliteMobs 也會封存先前內建附魔腳本的未編輯副本（例如舊的 grappling_hook.lua），以便在原處寫入目前的預設版本；你編輯過的腳本則會保留。在設定封存中檢查自訂設定，並使用目前的欄位重新套用。更新的 DLC 或自訂效果仍需要各自相符的定義與 Lua 原始碼。
物品引用
自訂效果使用小寫的命名空間 ID 與正整數等級。以下是 FMM 物品定義範例：
enchantments:
- "minecraft:unbreaking,3"
- "elitemobs:critical_strikes,2"
例如，EliteMobs 附魔目錄中的 critical_strikes.yml 定義 elitemobs:critical_strikes。FMM 定義使用 freeminecraftmodels:。子目錄不會成為 ID 的一部分；內容檔案應使用唯一檔名。
EliteMobs 自訂物品 YAML 對原版附魔保留 UNBREAKING,3 等 Bukkit 名稱，對自訂效果則要求命名空間 ID。請勿在未檢查其他插件物品格式的情況下，直接複製 FMM 的原版附魔語法。
已安裝的提供者必須識別該 ID。相容性、物品類型、欄位、衝突和必要能力都來自定義。移除提供者不會將其自訂效果變成原版附魔。
定義格式
以下是 FMM 內建的 Ignition 定義，與同一附魔目錄中的 ignition.lua 配套使用：
isEnabled: true
name: Ignition
description: Sets surviving targets on fire after a staff fireball hits.
maxLevel: 3
curse: false
validSlots: [MAINHAND]
itemTypes: [STAFF]
attackKinds: [STAFF_FIREBALL]
requires: []
conflicts: []
stacking: source_item
script: ignition.lua
parameters:
base_ticks: 20
ticks_per_level: 20
return {
api_version = 1,
on_ignition_ticks = function(context)
return math.max(0, math.min(200, context.parameters.base_ticks
+ context.parameters.ticks_per_level * context.enchantment.level))
end
}
此查詢向 FMM 傳回點燃時間。它不以擺設腳本或裝備物品腳本的方式執行。
| 欄位 | 含義 |
|---|---|
isEnabled | 預設為 true；停用的定義不會加入目錄 |
name | 必填的純文字顯示名稱 |
description | 選填說明，預設為空 |
maxLevel | 正的附魔等級上限；明確製作的物品可以超過此值 |
curse | 是否為詛咒；預設為 false |
validSlots | 裝備欄位：HEAD, CHEST, LEGS, FEET, MAINHAND, OFFHAND |
itemTypes | 接受的類別：SWORD, AXE, PICKAXE, SHOVEL, HOE, BOW, CROSSBOW, TRIDENT, MACE, SPEAR, HELMET, CHESTPLATE, LEGGINGS, BOOTS, SHIELD, FISHING_ROD, SHEARS, ELYTRA, WAND, STAFF, OTHER |
attackKinds | 選用的魔法攻擊篩選：WAND_MISSILE, STAFF_MELEE, STAFF_FIREBALL |
requires | 對提供者能力的要求 |
conflicts | 其他小寫的命名空間附魔 ID |
stacking | 預設為 source_item，也可為 sum_equipped_levels |
script | 必填的小寫 .lua 檔名，不包含目錄 |
parameters | 命名純量值或依等級排列的純量清單 |
set | 選填。將此附魔設為物品套裝 |
依等級排列的清單必須恰好有 maxLevel 個項目。超過該等級時使用清單最後一個值，但腳本仍會收到實際附魔等級。參數屬於特定效果；在這裡隨意加入一個鍵不會建立新機制。
未知的頂層欄位、重複 ID、缺少腳本與不支援的掛鉤會導致候選目錄被拒絕。重新載入前，先修正錯誤中指出的檔案。失敗的候選目錄不會覆蓋目前使用中的目錄。
效果歸屬
以將來負責新定義的插件所附帶的效果為起點。它支援的掛鉤與領域操作決定了效果能做什麼。查詢掛鉤傳回飛彈數量、暴擊率或威脅加成等數值。動作掛鉤處理已接受的物品輸入，可以管理持續一段時間的效果。
舊 FMM context.item API 及其裝備、卸下生命週期不適用於這裡。附魔腳本使用自己的 context.enchantment、context.parameters、擷取的來源資訊與動作操作。請勿僅重新命名舊物品腳本，就假設其上下文相容。
附魔書與鐵砧
自訂附魔書與裝備物品使用相同的提供者定義。鐵砧會驗證來源物品、附魔書與完整結果，包括原版附魔。相同自訂等級合併後升一級；不同等級保留較高值。每個發生變化的自訂附魔會將結果等級加到原版修復成本上。結果等級必須通過定義的鐵砧等級限制、欄位、類型、能力及衝突檢查。
混合附魔書必須同時轉移伺服器接受的全部原版項目與自訂項目。如果伺服器拒絕某個原版項目，整個自訂操作會被拒絕，不會悄悄丟棄書中的那部分。無效或不可用的定義也會使預覽被拒絕。取出結果時會再次檢查輸入與提供者狀態；已顯示的預覽並不保證在目錄變更後仍然有效。
Lua 查詢參考
數值查詢執行全新的腳本實例，並在取得結果後立即關閉。傳回一個有限數；沒有貢獻時傳回 nil。狀態與排程工作不會在查詢結束後保留。失敗的定義會被隔離，直到目錄成功重新載入；耗盡呼叫端剩餘預算本身不會導致定義被隔離。
| 上下文 | 內容 |
|---|---|
context.enchantment | id 與實際 level |
context.parameters | 依該等級解析後的定義值 |
context.input | 所屬機制提供的純量資訊；確切鍵名請參考內建效果 |
context.target | 目標 Entity 或 Living Entity 表，也可為 nil |
context.player | 查詢包含觸發玩家時，提供該玩家 |
FMM 提供 on_missile_count、on_missile_damage_factor、on_blast_radius_factor 與 on_ignition_ticks。其他提供者公開各自的數值掛鉤。定義只能宣告其提供者接受的掛鉤。
Lua 動作參考
動作腳本使用共用的排程器、冷卻、世界、區域、玩家與事件表。它們針對一次已接受的輸入或攻擊執行，後續回呼使用擷取的來源。聊天會在聊天事件中保存訊息快照，然後在伺服器執行緒派送時擷取裝備。選用的 parameters.lifetime_ticks 必須為正整數；未設定時啟動實例的存活時間為一刻。排程效果需要設定足以完成的存活時間。
啟動實例會在以下情況停止：存活時間結束、執行者死亡、斷線或換世界、所屬世界卸載、包含其管理實體的區塊卸載，或提供者重新載入或停用。當最後輸入已無剩餘管理工作時，也可以提前結束。parameters.stop_on_unequip: true 還會在擷取的物品不再裝備時停止實例。區域冷卻屬於玩家與附魔 ID；全域冷卻屬於該提供者內的玩家。兩種冷卻都會在換裝備、實例結束、換世界及有效重新載入後保留，並在斷線或提供者關閉時清除。
| 掛鉤 | 接受的輸入 |
|---|---|
on_attack_entity | 使用主手物品成功造成的正值原版近戰傷害，或插件明確負責的攻擊 |
on_projectile_hit | 擷取的弓箭彈體對活體目標成功造成傷害，每個彈體與目標組合僅派送一次；或插件明確負責的衝擊 |
on_take_damage | 玩家受到正值傷害；檢查符合條件的裝備欄位 |
on_right_click, on_left_click | 未潛行時的手部互動 |
on_shift_right_click, on_shift_left_click | 潛行時的手部互動；取代對應的普通點擊掛鉤 |
on_break_block | 玩家使用主手物品進行的已接受方塊破壞 |
on_chat | 已接受的聊天，攜帶訊息快照在伺服器執行緒派送 |
on_sneak | 開始潛行；依定義收集裝備貢獻 |
on_projectile_launch | 已消耗的附魔彈藥透過弓事件作為箭發射 |
on_game_tick | 此啟動實例仍有效時的每刻 |
on_zone_enter, on_zone_leave | 玩家跨越此啟動實例監視的區域邊界 |
這些掛鉤不會建立裝備、卸下腳本執行環境。僅處理每刻的定義仍需要輸入掛鉤來啟動實例。原版攻擊、受傷、聊天與挖掘掛鉤觀察的是已接受輸入，不能取消原始事件。四種互動掛鉤提供同步取消旗標：context.event:cancel() 拒絕相關物品與方塊互動。排程回呼不能追溯取消輸入。
| 上下文 | 內容 |
|---|---|
context.enchantment | id, level |
context.parameters | 依等級解析的定義參數 |
context.player | 目前執行者的 Player Table |
context.target | 目前受影響的 Living Entity Table，也可為 nil |
context.source | 擷取的資訊：item, slot, inventory_slot, equipment, attack_kind, providers；部分輸入還提供 ammunition, projectile, message, block, drop_items, sneaking 或 equipped_levels |
context.item | 物品欄中的物品仍可定位時，提供擷取欄位的耐久與消耗方法；參閱物品方法 |
context.action | id（攻擊 UUID）、instance（啟動權杖）、actor（UUID）、world（世界 UUID）及下列方法 |
context.set | 對於物品套裝：id、name、level 與 pieces；否則為 nil |
物品快照包含 material、amount 與 enchantments。它們是資料，不是即時物品欄物件。來源資訊中的 UUID 是字串。挖掘的 source.block 包含 x、y、z 與小寫的 material。
| 動作方法 | 傳回值 | 行為 |
|---|---|---|
stop() | nil | 停止此啟動實例並清理其管理的工作 |
has_previous() | bool | 檢查同一玩家是否存在此附魔的其他活動實例 |
replace_previous() | nil | 停止先前實例，保留目前實例 |
damage_target(target_uuid, amount) | bool | 請求提供者依擷取的來源歸屬套用正的有限傷害；拒絕時傳回 false |
own_entity(uuid) | bool | 將同世界中的有效非玩家實體登記為清理時移除的對象；在生成後使用 |
launch_projectile(location, direction, speed, range, ticks, impact, visual?, protected_path?=false) | bool | 發射受管理的腳本彈體；速度與射程必須為正的有限數，ticks 至少為 1 |
attribute_projectile(uuid, callback, protect?=false) | bool | 將受管理的原版彈體傷害繫結到自訂回呼 |
place_block(x, y, z, expected_material, block_data) | bool | 僅在目前材質相符時，透過玩家方塊操作驗證放置方塊 |
break_block(x, y, z, expected_material, drop_material?, amount?=1) | bool | 透過玩家方塊操作驗證破壞方塊，可指定自訂物品掉落 |
break_naturally(x, y, z, expected_material) | bool | 使用擷取的工具及來源破壞事件的掉落原則破壞方塊 |
temporary_block(x, y, z, block_data, ticks?=0) | bool | 暫時管理已載入方塊，清理時或正數 ticks 後還原；零表示持續到清理 |
can_own_block(x, y, z) | bool | 檢查座標是否已載入，以及能否暫時管理 |
temporary_gravity(uuid, enabled) | bool | 暫時管理重力狀態，清理時還原 |
restore_gravity(uuid) | bool | 提前還原此啟動實例暫時管理的重力 |
temporary_scale(uuid, scale) | bool | 暫時管理活體實體的縮放，持續到清理 |
temporary_potion(uuid, type, ticks, amplifier) | bool | 暫時管理藥水效果，ticks 為正數，amplifier 非負 |
restore_potion(uuid, type) | bool | 提前還原此啟動實例暫時管理的藥水效果 |
ride_rails(speed) | bool | 讓玩家坐進只有用戶端看得見的礦車，並使它沿著玩家所在方塊的相連鐵軌，朝玩家面對的一端，以每刻 speed 格（大於 0，至多 2）的速度行駛；若該處沒有鐵軌、玩家已在騎乘中，或伺服器的 NMS 轉接器不可用，則傳回 false |
鐵軌騎乘屬於該啟動實例所管理的工作。潛行、軌道盡頭、傳送、死亡、離線，或任何其他讓玩家離開礦車超過一格的情況，都會結束騎乘，接著結束該啟動實例；除了傳送、死亡或離線之外，玩家會被安置在礦車停下的位置。停止該啟動實例（包括透過 replace_previous()）同樣會讓玩家下車。該啟動實例的 lifetime_ticks 仍然適用，因此請為最長的軌道留出足夠的時間。
彈體衝擊回呼收到 (fresh_context, target_or_nil, location)；視覺回呼收到 (fresh_context, location)。原版彈體傷害回呼在下一刻收到 (fresh_context, target, native_damage)。它們取代原版傷害套用，必須明確套用預期傷害，通常透過 fresh_context.action:damage_target(target.uuid, amount)。原版彈體設定 protect=true 時，會過濾受保護的爆炸方塊與點燃。腳本彈體設定 protected_path=true 時，穿過受保護或未載入位置的彈體會被吸收。
自動清理僅適用於登記了管理歸屬的操作。普通 world:spawn_entity、entity:set_gravity 與 world:set_block_at 不會自動納入動作清理。暫時狀態方法負責還原，不能取代對敵對效果或方塊編輯是否獲准的檢查。
物品套裝
set 區段會把附魔變成物品套裝。請把同一個附魔放在每一件部件上。當 pieces 列出的每個欄位都裝有帶著該附魔的物品時，這套裝備就算完整。完整的套裝每次事件只會執行一次它的掛鉤。只要缺少任何一件，就不會執行任何東西。
name: Crooked's Full Set
maxLevel: 1
validSlots: [HEAD, CHEST, LEGS, FEET]
itemTypes: [HELMET, CHESTPLATE, LEGGINGS, BOOTS]
script: crooked_set.lua
parameters:
lifetime_ticks: 620
stop_on_unequip: true
set:
pieces:
HEAD: Crooked's Hex-Brim
CHEST: Crooked's Warded Wrap
LEGS: Crooked's Bent Hosen
FEET: Crooked's Wayward Soles
lore:
- "&5Crooked's Full Set &7($equippedPieces/$totalPieces)"
- "$setPieces"
- "&7When damaged, has a 5% chance to grant Regeneration I."
return {
api_version = 1,
on_take_damage = function(context)
-- Runs only while all four pieces are worn, once per hit.
context.action:temporary_potion(context.player.uuid, "REGENERATION", 100, 0)
end
}
| 套裝欄位 | 含義 |
|---|---|
pieces | 必填。將裝備欄位對應到部件名稱。設定了 validSlots 時，它必須包含每個部件的欄位 |
name | $setName 使用的名稱。預設為附魔的 name，並接受 & 顏色代碼 |
lore | 套裝的說明文字行。預設為套裝名稱加上部件數量，接著每個部件一行 |
equippedPiece | 已穿戴部件的那一行。預設為 &a✔ $pieceName |
missingPiece | 缺少部件的那一行。預設為 &c✘ $pieceName |
套裝說明文字可使用下列佔位符：
| 佔位符 | 顯示內容 |
|---|---|
$setName | 套裝名稱 |
$equippedPieces | 玩家穿戴了幾件部件 |
$totalPieces | 套裝共有幾件部件 |
$setPieces | 依欄位順序，每個部件一行，取自 equippedPiece 或 missingPiece。佔位符前後的文字會在每一行重複 |
$pieceName, $pieceSlot | 在 equippedPiece 與 missingPiece 內，表示部件名稱及其欄位，例如 Head 或 Main Hand |
$ifSetComplete | 只有在每個部件都穿戴時才顯示該行 |
$ifSetIncomplete | 只有在缺少部件時才顯示該行 |
套裝物品會顯示這個區段，而不是自訂附魔清單中的一行。在 EliteMobs 中，請把 $itemSet 放進 ItemSettings.yml 的 itemLoreStructureV2，或放進自訂物品自己的 lore。兩處都沒有時，套裝會接在物品的自訂說明文字之後。$ifItemSet 只會在套裝物品上顯示結構行。FMM 自訂物品會把套裝顯示在含有 $itemSet 的說明文字行，否則顯示在它們的說明文字之後。
這個區段顯示的是持有該物品的玩家目前穿戴的內容，並會在玩家裝上或卸下部件時重新繪製。存放在玩家物品欄之外的物品，會維持它離開時顯示的狀態。
套裝掛鉤與一般附魔掛鉤有幾處不同：
- 上表中的每個動作掛鉤都會作用於完整的套裝，無論它的部件使用哪些欄位。護甲套裝也可以回應
on_attack_entity或on_break_block。 - 完整與否是在事件發生時檢查。彈體會在落地時才檢查當下穿戴的套裝，而且任何彈體都算，不限於弓射出的箭。
on_take_damage在有攻擊者時，會把context.target設為攻擊者。context.source.item與context.item是依欄位順序的第一個部件：HEAD、CHEST、LEGS、FEET、MAINHAND、OFFHAND。若要取得手持的武器或工具，請讀取context.source.equipment.MAINHAND。context.set.level是各部件之中最低的等級。context.set.pieces以欄位為鍵，並包含每個部件的name與inventory_slot。stop_on_unequip: true會在任何部件被卸下時停止套裝的啟動實例。- 數值查詢（例如 EliteMobs 的威脅與暴擊率，或 FMM 的施法修正）會把一套裝備只算一次，而且只在它完整時才計入。
升級現有內容
FMM 會略過含有非空 scripts: 或已停用的無命名空間附魔項目的自訂物品。將這些物品定義改為使用命名空間附魔；擺設腳本仍受支援。
EliteMobs 自訂效果現在於提供者 YAML 中使用 maxLevel 和效果專屬的 parameters。原版及精英等級附魔設定是另一種格式。請遵循 EliteMobs 附魔參考，不要將舊 maxLevelV2 檔案複製到提供者定義中。