Custom items and magic weapons

FMM registers held items from YAML files in plugins/FreeMinecraftModels/models/. A model can have a sibling .yml definition with the same filename stem. Items can also use vanilla presentation without a .bbmodel file.

Custom items

For flame_blade.yml:

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

Reload FMM, then use /fmm giveitem flame_blade. This command requires freeminecraftmodels.admin. The item ID is the lowercase filename stem, not its display name. Use unique stems across subfolders.

Enchantment entries must be lowercase namespace:id,level strings with a positive integer level. Use minecraft: for native enchantments, freeminecraftmodels: for FMM effects, and elitemobs: for effects supplied by EliteMobs. The provider must be installed and the definition available. See authored enchantments.

Upgrading item content

Equipped-item scripts: lists and unnamespaced entries such as SHARPNESS,3 are retired. FMM skips those item definitions, logs the reason, and leaves the files unchanged. An item whose material is unavailable on the server is also skipped. These cases do not prevent other content from loading.

Prop scripts still use scripts:. Item effects use enchantments:. Do not add an old item script to a new weapon definition.

Bundled wand and staff

FMM installs missing defaults under models/fmm_default_magic/ and preserves existing files:

Item ID	Material	Controls
fmm_default_arcane_wand	BLAZE_ROD	Left-click fires an aim-assisted missile
fmm_default_arcane_staff	WOODEN_SPEAR	Left-click makes a weak melee strike; right-click launches an area fireball

Get them with /fmm giveitem <id>. A plain blaze rod or spear does not become a magic weapon. The staff requires a server version that provides WOODEN_SPEAR; unavailable material definitions are skipped.

The wand searches ahead for a target, then sends a travelling projectile. Acquisition is not a guaranteed hit: the projectile must reach its target and can collide with blocks. Staves launch slower fireballs with an impact radius.

Defining a magic weapon

Add a weapon section to an ordinary item definition:

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

type must be WAND or STAFF. Omitting tuning fields uses these defaults:

Setting	Wand	Staff
projectileSpeed	0.72	0.38
range	18	28
travelTicks	24	74
impactRadius	0	2.75
aimAssistDegrees	45	0

The default wand acquisition cone extends 45 degrees to either side of its forward direction. aimAssistDegrees accepts 0 through 180. Radius may be zero; speed and range must be positive finite numbers, and travel ticks must be a positive integer.

Attack	basePower	reloadTicks
WAND_MISSILE	0.672	11
STAFF_MELEE	0.45	12
STAFF_FIREBALL	1.25	40

An optional weapon.attacks section must contain exactly the attack keys for that weapon type, with both fields for each attack:

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

Unknown weapon fields and malformed values are rejected. basePower is a damage factor interpreted by the combat resolver, not a promise of that many health points of damage.

Magic enchantments

ID	Purpose
freeminecraftmodels:multicast	Additional projectiles with adjusted per-projectile damage
freeminecraftmodels:blast_radius	Staff fireball impact-radius modifier
freeminecraftmodels:ignition	Ignites surviving targets after a staff fireball

Their YAML and Lua files live in plugins/FreeMinecraftModels/enchantments/. The shipped catalog also contains effects for authored content items. Installing an effect definition alone does not give players the corresponding item or model pack.

EliteMobs integration

EliteMobs owns elite combat scaling and skill attribution when installed. FMM owns the weapon identity, input, projectile travel, and impact request. EliteMobs can refuse a cast or impact when the weapon or combat state is invalid.

The Alpha Advanced Combat System uses FMM staves and wands for Spellcaster. Class abilities and magic-weapon attacks are separate inputs. Consuming an F-key class ability selection must not also cast the held weapon.

For pack delivery, regenerate FMM's output and let ResourcePackManager merge and serve it. A registered weapon does not by itself prove that a client has downloaded its model.