Skip to content

Setup

Jump to bottom
Mitality edited this page Nov 28, 2025 · 26 revisions

This assumes you already have a Minecraft server set up using Spigot-based software (such as Paper or Purpur) and you have access to its file structure!

Installation

  • Download the latest release version of BodyHealth either from GitHub, Spigot, or Modrinth.
  • If you want to make use of BodyHealth's Betterhud integration to display health per body part via a head up display in game, you also want to download BetterHud and PlaceholderAPI if you haven't already. With just PAPI, you may also build your own display by using placeholders from BodyHealth's PlaceholderAPI expansion.
  • Drop the downloaded .jar files into the plugins folder of your server and (re)start it.
  • Navigate to plugins/BodyHealth/ and edit the config.yml file there

Configuration

Caution

If you are using a permissions plugin like LuckPerms and you have groups/users with a * wildcart (permission shortcut for all permissions), you immediately want to deny the permission node bodyhealth.bypass.* to all groups/users that have all permissions per default, as players with bypass permissions don't naturally take damage to body parts or regenerate their respective health!

MaxHealth Values

First, you want to decide how much health each body part should be able to have. Scroll down to where it says body-health: and adjust the given settings to match your imagination. You can even have the health of a body part depend on the players vanilla max health as shown with HEAD and BODY on default settings.

# Specify the maximum health for each body part
# (can use %PlayerMaxHealth% as placeholder)
body-health:

  # Default health values
  HEAD: "%PlayerMaxHealth% * 0.5"
  TORSO: "%PlayerMaxHealth% / 2"
  ARM_LEFT: 10.0
  ARM_RIGHT: 10.0
  LEG_LEFT: 7.5
  LEG_RIGHT: 7.5
  FOOT_LEFT: 5
  FOOT_RIGHT: 5

  # Permission overrides
  overrides:
    - permission: bodyhealth.health.tough
      enabled: false
      HEAD: "%PlayerMaxHealth% * 0.75"
      TORSO: "%PlayerMaxHealth% * 0.75"
      ARM_LEFT: 15
      ARM_RIGHT: 15
      LEG_LEFT: 10
      LEG_RIGHT: 10
      FOOT_LEFT: 7.5
      FOOT_RIGHT: 7.5

You can add permission overrides as shown, for example, giving players with the permission bodyhealth.health.tough a bit more max health. You can imagine BodyHealth first loading the default max health values and then applying all overrides from top to bottom. So an override doesn't have to contain values for all eight parts (only the permission is mandatory) and overrides can overwrite other overrides above them when a player has the permissions of both.

Damage Control (literally)

The next section we will be taking a look at is body-damage. It's located right beneath the max health settings and allows you to fine-tune how much damage should be applied under what circumstances. This section is mainly for controlling where damage that doesn't hit you on a specific pert (e.g. drowning damage) is applied, but it also allows you to control how much damage should be applied from any DamageCause:

# You can fine-tune all kinds of damage per body-part and damage-cause here. Defaults to 100% if not specified otherwise.
# Even if damage is only applied to specific body parts, the system still checks how much damage to deal with this list.
# Available types: https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/event/entity/EntityDamageEvent.DamageCause.html
body-damage:

  # Default damage values
  HEAD:
    - KILL 0%
    - DROWN 90%
    - IN_FIRE 60%
    - LAVA 60%
    - MAGIC 70%
    - ON_FIRE 60%
    - FALL 0%
  TORSO:
    - KILL 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - IN_FIRE 80%
    - LAVA 80%
    - ON_FIRE 80%
    - FALL 0%
  ARM_LEFT:
    - KILL 0%
    - DROWN 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - IN_FIRE 80%
    - LAVA 80%
    - MAGIC 70%
    - ON_FIRE 80%
    - FALL 0%
  ARM_RIGHT:
    - KILL 0%
    - DROWN 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - IN_FIRE 80%
    - LAVA 80%
    - MAGIC 70%
    - ON_FIRE 80%
    - FALL 0%
  LEG_LEFT:
    - KILL 0%
    - DROWN 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - MAGIC 70%
    - FALL 75%
  LEG_RIGHT:
    - KILL 0%
    - DROWN 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - MAGIC 70%
    - FALL 75%
  FOOT_LEFT:
    - KILL 0%
    - DROWN 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - MAGIC 50%
  FOOT_RIGHT:
    - KILL 0%
    - DROWN 0%
    - FALLING_BLOCK 0%
    - FALLING_STALACTITE 0%
    - FLY_INTO_WALL 0%
    - MAGIC 50%

  # Permission overrides
  overrides:
    - permission: bodyhealth.damage.helmet
      enabled: false
      HEAD:
        - FALLING_BLOCK 0%
        - FALLING_STALACTITE 0%
        - FLY_INTO_WALL 0%

As you can see, it already contains values that make sense, so you don't have to change anything. Just note that you can, if you ever feel like something should deal more or less damage. What isn't on the list defaults to 100%. Also note that it uses the same kind of permission overrides as the max health settings.

Effect Configuration

Right beneath the damage control section is a section for effects. This section contains a list of all eight body parts and the five states they can be in. Due to this list containing every possible combination of a state and a body part, configuring effects is very easy! You just choose one ore more effects from the sections description (e.g. PREVENT_JUMP) and add it/them to the right list. For example, if you wanted players who broke their left leg to be unable to jump, you could add PREVENT_JUMP to effects.LEFT_LEG.BROKEN. In BodyHealth v3 and newer, this section also already contains default values that make sense in a survival environment, so you don't have to change anything, but I'm still listing this section here, as it's one of the most important and impactful sections there is and you should know that it exists and how it works.

Tip

You may want to apply the same effect at multiple states of a body part. For example BROKEN in addition to DAMAGED to preserve the effect on 0% health

# Configure effects per body part and body part state:
#
#   Effects (<> = required, [] = optional):
#
#      Persistent effects (active as long as conditions are met):
#
#         POTION_EFFECT / <EFFECT> / [AMPLIFIER]   ...apply a specific potion effect (amplifier defaults to 1 if not specified)
#         PREVENT_INTERACT / <HAND> / [MESSAGE]    ...prevent the player from interacting with a given hand (HAND / OFF_HAND)
#         PREVENT_SPRINT / [MESSAGE]               ...prevent the player from sprinting (sets sprint speed to walk speed)
#         PREVENT_WALK                             ...prevent the player from walking at all (player can still be knocked back)
#         PREVENT_JUMP                             ...prevent the player from jumping (player can still climb stairs etc.)
#
#      One-time effects (activate once when conditions are met):
#
#         COMMAND / cmd args[...]                  ...execute a command (can use %PlayerName%, %PlayerUUID% and %BodyPart%)
#         COMMAND_UNDO / cmd args[...]             ...execute a command when the condition is no longer met (to undo stuff)
#         SOUND / <ID> / [VOLUME] / [PITCH]        ...play a vanilla or custom sound (namespace optional) to only the player
#         MESSAGE / <MESSAGE>                      ...send a message to the target player to notify them of their status
#         KILL_PLAYER                              ...you guessed it, this kills the player when the condition is met
#
#      Meta effects (logic-based triggers for non-persistent effects):
#
#         REPEATING / <delay> / <interval> / <EFFECT[...]>   ...repeats effect at the specified interval (e.g. 5s for 5 seconds)
#         DELAYED / <delay> / <EFFECT[...]>               ...executes effect after the specified delay (e.g. 10t for 10 ticks)
#         WHEN_DAMAGED / <EFFECT[...]>                 ...triggers effect when the condition is met due to taking damage
#         WHEN_HEALED / <EFFECT[...]>               ...triggers effect when the condition is met due to regeneration
#
#   <MESSAGE> (or [MESSAGE]) can be the following:
#
#      actionbar:this will be displayed in the actionbar
#      title:this is a title; this is a subtitle
#      this is a normal chat message
#
#   All message variants can use MiniMessage formatting and legacy colorcodes like &c (=red).
#   You may also use PlaceholderAPI placeholders everywhere in this plugin, including here.
#
#   FULL » Health is at maximum
#   NEARLYFULL » Health is between 50% and full
#   INTERMEDIATE » Health is between 25% and 50%
#   DAMAGED » Health is below 25%
#   BROKEN » No health left
#
# Some examples have already been configured for you:
effects:
  HEAD:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - WHEN_DAMAGED / MESSAGE / actionbar:&cYour head is pounding
      - POTION_EFFECT / NAUSEA / 1
    BROKEN:
      - POTION_EFFECT / NAUSEA / 1
      - KILL_PLAYER
  TORSO:
    FULL:
      - WHEN_HEALED / DELAYED / 1s / MESSAGE / actionbar:&aYou feel a little better
      - COMMAND / attribute %PlayerName% minecraft:oxygen_bonus modifier add bodyhealth_configured_effect 1 add_value
      - COMMAND_UNDO / attribute %PlayerName% minecraft:oxygen_bonus modifier remove minecraft:bodyhealth_configured_effect
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - WHEN_DAMAGED / MESSAGE / actionbar:&cYour heart is pounding
      - REPEATING / 10t / 10t / SOUND / entity.warden.heartbeat / 1 / 0.75
    BROKEN:
      - KILL_PLAYER
  ARM_LEFT:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - WHEN_DAMAGED / MESSAGE / actionbar:&cYou arm hurts
      - POTION_EFFECT / WEAKNESS / 1
    BROKEN:
      - PREVENT_INTERACT / OFF_HAND / actionbar:&cYou arm hurts badly
      - POTION_EFFECT / WEAKNESS / 2
  ARM_RIGHT:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - WHEN_DAMAGED / MESSAGE / actionbar:&cYou arm hurts
      - POTION_EFFECT / WEAKNESS / 1
    BROKEN:
      - PREVENT_INTERACT / HAND / actionbar:&cYou arm hurts badly
      - POTION_EFFECT / WEAKNESS / 2
  LEG_LEFT:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - PREVENT_SPRINT
      - PREVENT_JUMP
    BROKEN:
      - POTION_EFFECT / SLOWNESS / 3
      - PREVENT_JUMP
  LEG_RIGHT:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - PREVENT_SPRINT
      - PREVENT_JUMP
    BROKEN:
      - POTION_EFFECT / SLOWNESS / 3
      - PREVENT_JUMP
  FOOT_LEFT:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - PREVENT_SPRINT
    BROKEN:
      - PREVENT_WALK
      - SOUND / minecraft:entity.bogged.hurt / 1 / 1.3
      - MESSAGE / actionbar:&cYou sprained your ankle
  FOOT_RIGHT:
    FULL: []
    NEARLYFULL: []
    INTERMEDIATE: []
    DAMAGED:
      - PREVENT_SPRINT
    BROKEN:
      - PREVENT_WALK
      - SOUND / minecraft:entity.bogged.hurt / 1 / 1.3
      - MESSAGE / actionbar:&cYou sprained your ankle

Note

An empty list ([]) means no effects are applied.

Display Options

The last config section is dedicated to controlling BetterHud, making an in-game display possible. These options only activate when you have both BetterHud and PlaceholderAPI installed, but the whole display thing is completely optional.

display:

  #   Use BetterHud to display your body health in game:
  #
  #      To make this work, you need to install two plugins, if you don't have them already:       <--
  #      PlaceholderAPI -> https://www.spigotmc.org/resources/placeholderapi.6245/               <-- DON'T OVERLOOK THIS PART
  #      ...and obviously BetterHud -> https://modrinth.com/plugin/betterhud2                      <--
  #
  #   When both plugins are installed, the following options activate:
  betterhud:
  # Automatically reload BetterHud with BodyHealth to apply changes
  auto-reload: true
  # Automatically configure BetterHud to display BodyHealth's HUD
  inject-config: true
  # Show BodyHealth's HUD to all players **IN SURVIVAL/ADVENTURE MODE**
  as-default: true
  # Position BodyHealth's HUD on your screen (REQUIRES REGENERATING THE RESOURCE PACK)
  position:
    # Chose one of nine possible anchor points (TOP_, MIDDLE_, BOTTOM_ & _LEFT, _CENTER, _RIGHT)
    anchor-point: BOTTOM_RIGHT
    # Horizontal shift from the default position (positive moves right, negative moves left)
    horizontal-offset: 0
    # Vertical shift from the default position (positive moves down, negative moves up)
    vertical-offset: 0
    # Scale of the hud (also automatically and individually scales with your GUI-size)
    scale: 1.5
  # Disable parts of BetterHuds default configuration that could get annoying
  disable:
    # Disable BetterHud's default entity popup (seems to still be W.I.P.)
    entity-popup: true
    # Disable BetterHud's default hud (a moving example hud, not that beautiful)
    default-hud: true
    # Disable BetterHud's default compass (compass HUD at the top of your screen)
    compass: true
  # Add stuff to BetterHud to make your life easier
  add:
    # Add a mcmeta file to BetterHud's output directory
    mcmeta: true
    # Add an icon to BetterHud's output directory
    icon: true
  # Leave the above add-options set to true when using the zip option below!
  package:
    # Zip BetterHud assets to a usable resource pack located at plugins/BodyHealth/output/<name>.zip
    compress: true
    # Customize how the file should be named (without the .zip, that will be added automatically)
    filename: resource_pack

As with the above sections, you also don't have to change anything here if you don't want to, however, if you are using ItemsAdder or Nexo, read here to prevent them from interfering and learn how to merge the two packs automatically.

...and that's the most essential setup done!

Hope this helped - if it didn't, feel free to ask questions here, or join our Discord Server to receive further assistance :)

Navigation

Spigot Page

Modrinth Page

Configuration

Language

Assets

Setup Guide

Effects

Addons

API

Clone this wiki locally