Skip to content

Setup

Jump to bottom
Mitality edited this page Aug 8, 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 extension.
  • 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!

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"
  BODY: "%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
      HEAD: "%PlayerMaxHealth% * 0.75"
      BODY: "%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.

Now, scroll further down to where it says 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, this section 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
  BODY:
    FULL: []
    NEARLYFULL:
      - WHEN_HEALED / DELAYED / 1s / MESSAGE / actionbar:&aYou feel a little better
      - DELAYED / 1s / COMMAND / attribute %PlayerName% minecraft:oxygen_bonus base set 1
      - COMMAND_UNDO / attribute %PlayerName% minecraft:oxygen_bonus base set 0
    INTERMEDIATE: []
    DAMAGED:
      - WHEN_DAMAGED / MESSAGE / actionbar:&cYour heart is pounding
      - REPEATING / 10t / 10t / SOUND / entity.warden.heartbeat / 1 / 0.75
    BROKEN:
      - KILL_PLAYER
      - COMMAND / attribute %PlayerName% minecraft:scale base set 2
      - COMMAND_UNDO / attribute %PlayerName% minecraft:scale base set 1
  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.



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

  • If you chose to use BodyHealth's BetterHud integration and you have installed both dependencies necessary for it to work, you will now find a resource pack at plugins/BodyHealth/resource_pack.zip. Without this, players just see a yellow bossbar and weird rectangle characters above it, so make sure to either give it to anyone who plays with you or use a resource pack management plugin to auto-apply it.

Now, you can choose to either enjoy already or take a closer look at the configuration to tweak the heck out of this plugin :P

Hope this helped - if it didn't feel free to open a ticket here to receive further assistance :)

Navigation

Spigot Page

Modrinth Page

Configuration

Language

Assets

Setup Guide

Effects

Addons

API

Clone this wiki locally