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.

To dye leather armor, add an RGB hex color after the material without #, as in EliteMobs equipment: material: LEATHER_CHESTPLATE:ff8800. The suffix only works on LEATHER_ materials. Items already in inventories keep their old color.

An item keeps the display model it had when it was created. FMM adds the registered display model to FMM items that have none: to every such item in a player's inventory when they join, and to the items in their hands after they change the held slot, swap hands or pick something up. This fixes items handed out before their model existed, such as wands that showed as plain blaze rods. Items that already name a model are left alone.

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/. If an existing bundled wand or staff definition lacks weapon.type, FMM adds the matching WAND or STAFF declaration while preserving its other settings:

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.

Both weapons ship with their own model and display model JSON. The wand also ships fmm_default_arcane_wand_particles.particle.json and its texture: its held animation loops a sparkle effect around the gem while the wand is in either hand. See Particles. FMM copies missing files only, so a server that already has an edited bundled .yml keeps it and gains the new model files.

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.

Wand casts briefly apply Slowness I for 20 ticks without replacing a stronger or longer existing slowness effect. Wand damage suppresses its own native knockback. Staff blasts check line of sight for nearby targets and reduce damage with distance, from full impact damage at the center to 35% at the edge. Ignition only follows accepted damage and respects the combustion event.

Hitting a mob directly with a wand or staff counts as the left-click attack: FMM cancels the vanilla melee hit and runs the weapon's left-click attack instead. Damage that a plugin applies as the player through MagmaCore's explicit-damage path while they hold a wand or staff, such as EliteMobs enchantment damage, is left alone and does not trigger a cast. Clicking while the attack is on cooldown plays a quiet click and does nothing else.

Cooldowns start after a cast or melee action launches successfully. A content reload pauses new casts while definitions rebuild; launched projectiles retain their captured weapon and modifiers. Removing the registered combat resolver cancels outstanding projectiles so they cannot switch combat rules mid-flight.

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.