自定义物品与魔法武器

FMM 从 plugins/FreeMinecraftModels/models/ 中的 YAML 文件注册手持物品。模型可以在同一目录中配有主文件名相同的 .yml 定义。物品也可以采用原版外观，不使用 .bbmodel 文件。

自定义物品

flame_blade.yml 示例：

isEnabled: true
material: DIAMOND_SWORD
name: "&6Flame Blade"
lore:
  - "&7Burns enemies on hit"
enchantments:
  - "minecraft:fire_aspect,2"
  - "minecraft:unbreaking,3"

重载 FMM，然后执行 /fmm giveitem flame_blade。此命令需要 freeminecraftmodels.admin 权限。物品 ID 是去掉扩展名后的小写文件名，而非显示名称。不同子目录中的主文件名也必须唯一。

要为皮革盔甲染色，请在材质后添加不带 # 的 RGB 十六进制颜色，写法与 EliteMobs 装备相同：material: LEATHER_CHESTPLATE:ff8800。该后缀只对 LEATHER_ 材质有效。已在物品栏中的物品保持原来的颜色。

物品会保留其创建时所用的显示模型。对于没有显示模型的 FMM 物品，FMM 会添加已注册的显示模型：玩家加入时，处理其物品栏中所有此类物品；玩家切换手持栏位、交换双手物品或捡起物品后，处理其手中的物品。这可以修复在模型存在之前就已发放的物品，例如显示为普通烈焰棒的魔杖。已经指定了模型的物品不会被改动。

附魔条目必须使用小写的 namespace:id,level 字符串，等级必须为正整数。原版附魔使用 minecraft:，FMM 效果使用 freeminecraftmodels:，EliteMobs 提供的效果使用 elitemobs:。必须安装对应的提供方，并且相应定义可用。请参阅内容附魔。携带套装附魔的物品，会在包含 $itemSet 的描述行处显示该套装的部件，没有这样的行时则显示在描述之后。

升级物品内容

装备物品的 scripts: 列表以及 SHARPNESS,3 这类没有命名空间的条目已经废弃。FMM 会跳过这些物品定义、记录原因，并保留原文件不变。服务器不支持其材质的物品也会被跳过。这些情况不会阻止其他内容加载。

摆件脚本仍然使用 scripts:。物品效果使用 enchantments:。不要把旧物品脚本添加到新武器定义中。

内置魔杖与法杖

FMM 会在 models/fmm_default_magic/ 下安装缺失的默认内容。如果现有内置魔杖或法杖定义缺少 weapon.type，FMM 会添加对应的 WAND 或 STAFF 声明，同时保留其他设置：

物品 ID	材质	操作
`fmm_default_arcane_wand`	`BLAZE_ROD`	左键发射带辅助瞄准的飞弹
`fmm_default_arcane_staff`	`WOODEN_SPEAR`	左键进行较弱的近战攻击；右键发射范围火球

使用 /fmm giveitem <id> 获取。普通烈焰棒或长矛不会自动成为魔法武器。法杖需要提供 WOODEN_SPEAR 的服务器版本；不支持的材质定义会被跳过。

两件武器都附带各自的模型和显示模型 JSON。魔杖还附带 fmm_default_arcane_wand_particles.particle.json 及其纹理：魔杖握在任意一只手中时，其 held 动画会在宝石周围循环播放闪光效果。参见粒子。FMM 只复制缺失的文件，因此已存在编辑过的内置 .yml 的服务器会保留该文件，同时获得新的模型文件。

魔杖先搜索前方目标，再发射飞行弹体。锁定不代表必定命中：弹体必须到达目标，也可能撞到方块。法杖发射较慢、具有冲击半径的火球。

魔杖施法会短暂施加 20 刻的缓慢 I，但不会替换已有的更强或更持久的缓慢效果。魔杖伤害会抑制自身的原版击退。被法杖火球直接击中的实体会承受火球的全额伤害。爆炸中的其他目标需要与冲击点之间有视线，且其中心离冲击点越远，受到的伤害越低，从冲击点的全额伤害递减到边缘的 35%。点燃只在伤害被接受后生效，并遵守燃烧事件的处理结果。

魔法命中会忽略原版的受伤冷却，因此魔杖弹体、法杖打击或火球仍然能命中刚刚被击中的目标，例如被队友的剑击中不久的目标。FMM 之后会恢复目标的冷却；魔法命中的频率由武器自身的装填限制。

用魔杖或法杖直接击打怪物视为左键攻击：FMM 会取消原版近战命中，改为执行武器的左键攻击。玩家手持魔杖或法杖时，插件以该玩家身份通过 MagmaCore 显式伤害路径施加的伤害（例如 EliteMobs 附魔伤害）不受影响，也不会触发施法。攻击处于冷却时点击只会播放一声轻微的咔哒声，不会产生其他效果。

冷却在施法或近战动作成功发起后开始。内容重载期间，重建定义时会暂停新施法；已发射的弹体保留发射时捕获的武器与修正项。移除已注册的战斗解析器会取消所有未结束的弹体，防止它们在飞行中切换战斗规则。

定义魔法武器

在普通物品定义中添加 weapon 节：

isEnabled: true
material: BLAZE_ROD
name: "&dArcane Wand"
weapon:
  type: WAND
enchantments:
  - "freeminecraftmodels:multicast,1"

type 必须为 WAND 或 STAFF。省略调节字段时使用以下默认值：

设置	魔杖	法杖
`projectileSpeed`	`0.72`	`0.48`
`range`	`18`	`28`
`travelTicks`	`24`	`74`
`impactRadius`	`0`	`2.75`
`aimAssistDegrees`	`45`	`0`

默认魔杖的目标捕捉锥体向正前方两侧各延伸 45 度。aimAssistDegrees 接受 0 至 180。半径可以为零；速度与射程必须为正的有限数，飞行刻数必须为正整数。

攻击	`basePower`	`reloadTicks`
`WAND_MISSILE`	`0.672`	`11`
`STAFF_MELEE`	`0.45`	`12`
`STAFF_FIREBALL`	`1.25`	`40`

可选的 weapon.attacks 节必须完整且仅包含该武器类型的攻击键，每种攻击都必须提供两个字段：

weapon:
  type: STAFF
  attacks:
    STAFF_MELEE:
      basePower: 0.45
      reloadTicks: 12
    STAFF_FIREBALL:
      basePower: 1.25
      reloadTicks: 40

未知武器字段和格式错误的值会被拒绝。basePower 是由战斗解析器解释的伤害系数，不保证造成同等数值的生命值伤害。

魔法附魔

ID	用途
`freeminecraftmodels:multicast`	增加弹体，并调整每个弹体的伤害
`freeminecraftmodels:blast_radius`	调整法杖火球的冲击半径
`freeminecraftmodels:ignition`	点燃被法杖火球击中后存活的目标

这些附魔的 YAML 与 Lua 文件位于 plugins/FreeMinecraftModels/enchantments/。内置目录还包含供自定义内容物品使用的效果。仅安装效果定义不会向玩家提供相应物品或模型包。

施法者穿戴的套装在每个部件都穿戴时，也适用于魔杖和法杖。套装的施法修正每次施法只计算一次。魔法命中时，套装的 on_attack_entity 钩子对法杖打击运行，on_projectile_hit 钩子则对魔杖弹体或火球运行。

EliteMobs 集成

安装 EliteMobs 后，精英战斗数值缩放和技能归属由 EliteMobs 负责。FMM 负责武器身份、输入、弹体飞行和冲击请求。武器或战斗状态无效时，EliteMobs 可以拒绝施法或冲击。

Alpha Advanced Combat System 的施法者使用 FMM 法杖与魔杖。职业能力与魔法武器攻击使用不同输入。处理 F 键职业能力选择时，不应同时发射手持武器。

分发资源包时，重新生成 FMM 输出，并让 ResourcePackManager 合并和提供下载。武器已注册本身不能证明客户端已下载其模型。