Custom hearts

Custom hearts are extra heart items you define yourself. A player right-clicks one to consume it, which can add or remove hearts, grant potion effects, and run commands. They live in custom-hearts.yml.

The plugin ships with two examples you can copy: a Strength Heart and a Sellable Heart.

How a custom heart works

Each custom heart has an id (the key in the file) and these parts:

Part	What it controls
`enabled`	Whether the heart can be used
`item`	The item look: material, name, lore, glow, custom model data
`consume`	Cooldown, whether the item is used up, and conditions
`hearts`	Hearts to add and hearts to remove on use
`effects`	Potion effects to apply
`commands`	Commands to run as the player or from console

Example: Strength Heart

This one costs the player 2 hearts and grants Strength II for 30 seconds.

custom-hearts:
  strength_heart:
    enabled: true
    item:
      material: NETHER_STAR
      amount: 1
      glow: true
      custom-model-data: 0
      name: '&#ff4d4d&lStrength Heart'
      lore:
        - '&7A dangerous source of power.'
    consume:
      remove-item: true
      cooldown: 60
      conditions:
        allow-at-max: true
    hearts:
      add: 0
      remove: 2
    effects:
      - type: INCREASE_DAMAGE
        amplifier: 1 # 0 is level 1, 1 is level 2
        duration: 30 # seconds
    commands:
      player:
        - 'msg %player% &cPower surges through your body!'

Example: Sellable Heart

This one removes 2 hearts and runs console commands to pay the player. It needs an economy plugin for the eco command to work.

  sell_heart:
    enabled: true
    item:
      material: EMERALD
      name: '&#f39c12&lSellable Heart'
      glow: true
    consume:
      remove-item: true
      cooldown: 5
      conditions:
        allow-at-max: true
    hearts:
      add: 0
      remove: 2
    effects: []
    commands:
      console:
        - 'eco give %player% 5000'
        - 'msg %player% &aYou sold a heart fragment for $5,000!'

Field reference

consume

Key	Meaning
`remove-item`	Use up the item when consumed
`cooldown`	Seconds before the player can use this heart again
`conditions.allow-at-max`	Allow use even when the player is at max hearts

hearts

Key	Meaning
`add`	Hearts to give on use
`remove`	Hearts to take on use

effects

A list of potion effects. Each has a type (a Spigot potion effect name like INCREASE_DAMAGE), an amplifier (0 is level 1), and a duration in seconds.

commands

player: commands run as the player who consumed the heart.
console: commands run from the server console.

Use %player% in any command to insert the player's name.

Giving custom hearts

Hand a custom heart to a player with:

/ls give <player> custom <heart_id> <amount>

The <heart_id> is the key from custom-hearts.yml, such as strength_heart.

Custom hearts support custom-model-data so they can have their own texture from a resource pack.

On this page