Abilities¶

An ability is what makes an item do something: a gun that fires, a wand that heals, food that grants an effect. Imported packs bring models and names only — the mechanics lived in the plugin they were written for. Ember Forge supplies that layer itself, in YAML, so any item from any format becomes functional.

Abilities live in plugins/EmberForge/behaviours.yml, keyed by item, and apply on top of whatever the source pack declared. The pack itself is never edited, so a pack update cannot undo your changes.

iaweapons:hand_gun:
  abilities:
    - trigger: RIGHT_CLICK
      cooldown: 0.35
      ammo: "iaweapons:clip"
      actions:
        - "shoot: arrow, 4.0, 7"
        - "sound: entity.generic.explode, 0.5, 1.9"
        - "particle: SMOKE, 8"
        - "durability: 1"

Reload with /emberforge reload.

Works on items that already exist

An item is recognised by its base material and model id, not only by a tag Ember Forge writes. A gun handed out by the plugin this pack used to belong to, or pulled from a crate months ago, fires exactly like a new one.

Derived from the pack¶

Some packs already describe what an item does. Where they do, Ember Forge builds the ability for you, so an imported gun fires the moment the pack is dropped in:

[EmberForge] Derived working abilities for 4 item(s) from their pack declarations.

An ItemsAdder behaviours.gun block becomes a right-click ability: the declared projectile item is both what the shot looks like and what it consumes (off hand first), the gun_shot event supplies the pack's own sound and particle, and a crossbow flagged multishot fires three. The pack's attribute_modifiers become real attribute modifiers, so a sword declared at 9 attack damage hits for 9.

Anything you write in behaviours.yml for the same item replaces the derived ability entirely.

Triggers¶

Trigger	Fires
`RIGHT_CLICK`	on right-click
`LEFT_CLICK`	on left-click
`SNEAK_RIGHT_CLICK`	sneak + right-click
`SNEAK_LEFT_CLICK`	sneak + left-click
`ATTACK`	when you hit something with it
`KILL`	when you kill something with it
`DEFEND`	when you are hit while holding it
`CONSUME`	when it is eaten or drunk
`BLOCK_BREAK`	when you break a block with it
`BLOCK_PLACE`	when you place a block with it
`DROP`	when you drop it
`EQUIP`	when it is worn
`HELD`	continuously, while held

Gates¶

Every ability can carry any of these. All are checked in one place, so a gun and a wand follow exactly the same rules.

Key	Default	Meaning
`chance`	`1.0`	Probability it fires, 0–1
`cooldown`	`0`	Seconds before it can fire again, per player
`ammo`	none	Item consumed each use — a custom key or a vanilla material
`ammo-amount`	`1`	How many are consumed
`permission`	none	Node the player must hold
`cancel`	`false`	Cancel the underlying event, e.g. stop a block being placed

Ammo¶

ammo: "iaweapons:clip"     # a custom item
ammo: ARROW                # or a vanilla material

Ammo is taken from the off hand first, then the rest of the inventory. That is where players expect a magazine to sit, and it keeps the weapon in the main hand. A custom item never satisfies a vanilla ammo requirement — several custom items share one base material, and any of them would otherwise load the weapon.

Out of ammo shows on the action bar and the ability does not fire.

Actions¶

Written as verb: a, b, c, run in order, top to bottom.

Combat¶

Action	Arguments	Effect
`shoot`	kind, speed, damage, item	Fire a projectile. Damage is applied on hit, overriding vanilla. An optional item key skins a throwable (snowball, egg…) so a bullet looks like a bullet
`damage`	amount	Hurt the target
`aoe`	radius, damage	Hurt everything within radius
`explode`	power, `fire`, `break`	Explosion at the target
`ignite`	seconds	Set the target alight
`launch`	power, min-lift	Throw the player in the direction they face

Projectile kinds: arrow (or bullet), fireball, small_fireball, snowball, egg, ender_pearl, trident, wind_charge. Only throwables can wear an item model — an arrow always looks like an arrow — so for a gun use shoot: snowball, 4, 7, iaweapons:projectile.

Player¶

Action	Arguments	Effect
`heal`	amount	Restore health
`feed`	amount	Restore hunger
`potion`	effect, seconds, level, `self`	Apply an effect. Targets the hit entity unless `self`

Item¶

Action	Arguments	Effect
`durability`	amount	Wear the held item
`consume_item`	amount	Use up the held item
`give`	key, amount	Give another item

Presentation¶

Action	Arguments	Effect
`sound`	key, volume, pitch	Play a sound
`particle`	name, count	Spawn particles
`message`	text	Chat message, MiniMessage
`actionbar`	text	Action-bar text

Flow and integration¶

Action	Arguments	Effect
`delay`	ticks	Pause before the rest of the list
`command`	text	Run as the player
`console`	text	Run from console

%player% is substituted in text and commands.

Examples¶

A shotgun: several projectiles, kickback, longer cooldown, its own ammo.

iaweapons:shotgun:
  abilities:
    - trigger: RIGHT_CLICK
      cooldown: 1.0
      ammo: "iaweapons:shotgun_cartridge"
      actions:
        - "shoot: arrow, 3.0, 4"
        - "shoot: arrow, 3.2, 4"
        - "shoot: arrow, 2.8, 4"
        - "sound: entity.generic.explode, 0.9, 1.2"
        - "launch: -0.3, 0"
        - "durability: 2"

A healing staff with a long cooldown and a permission.

mypack:healing_staff:
  abilities:
    - trigger: SNEAK_RIGHT_CLICK
      cooldown: 30
      permission: mypack.staff
      actions:
        - "heal: 8"
        - "potion: regeneration, 6, 1, self"
        - "particle: HEART, 12"
        - "sound: block.beacon.activate, 0.8, 1.6"

Food that grants an effect when eaten.

ax_food_pack:golden_stew:
  abilities:
    - trigger: CONSUME
      actions:
        - "potion: absorption, 30, 1, self"
        - "feed: 6"