Health

This guide explains how the Health plugin works, what every major configuration option means, and how to create diseases, treatments, vaccines, triggers, medical items, and recipes.

Quick answers

What does testable mean?

testable: true allows a condition to be detected by a Diagnostic Sample Kit and analyzer.

When a doctor collects a sample, the plugin records the first active condition on that patient which has testable: true. The analyzer later reports that condition. If the patient has no testable condition, the result is negative.

testable does not control medical records. A player with health.records.medical can see every active condition through /medical records <player>, including conditions marked testable: false.

What does public mean?

public: true marks a condition as a public-policy exception. When staff apply it, the configured public diagnosis message is broadcast. Completing its normal recovery or treatment protocol broadcasts the configured clearance notice.

Leave this false or omit it for ordinary private medical conditions.

What does surgery-required mean?

Successful surgery removes active conditions with surgery-required: true. Conditions with it disabled are not removed by surgery.

Do timers continue while a player is offline?

No. Disease stages, treatment windows, vaccination duration, bleeding, exposure decay, and the other player-health timers advance while the player is online. State is saved across restarts.

Files

| File | Purpose | |---|---| | config.yml | Global timing, unconsciousness, stamina, nutrition thresholds, injuries, analyzer, integrations, and security | | conditions.yml | Diseases, injuries, stages, effects, transmission, death behavior, and treatment protocols | | items.yml | Medical supplies, treatments, vaccines, PPE, components, and bioweapons | | recipes.yml | Crafting recipes and their permissions | | triggers.yml | Food, damage, biome, world, and environmental condition triggers | | nutrition.yml | Tracked foods, food categories, and nutritional quality | | messages.yml | Player-facing MiniMessage text | | data.db | Persistent player health data; do not edit while the server is running |

Use /health reload after changing configuration. Reload validates all files before replacing the live configuration. If validation fails, the current settings remain active.

The database path, scheduler tick length, and integration toggles require a server restart.

General configuration rules

IDs

Condition, item, trigger, and recipe keys may contain lowercase letters, numbers, underscores, and hyphens. Keep keys stable after issuing items or creating player conditions.

Examples include common_cold, leg_splint, and spoiled_food.

Durations

Durations may combine these units:

| Suffix | Meaning | |---|---| | s | seconds | | m | minutes | | h | hours | | d | days | | w | weeks | | mo | 30-day months | | y | 365-day years |

Examples: 30s, 15m, 12h, or 1h30m. Configured durations cannot exceed one year. Vaccine duration also accepts permanent.

Probabilities and multipliers

A probability is written from 0.0 to 1.0: 0.35 means 35%.

A multiplier uses 1.0 as normal strength: 0.5 means half and 1.5 means 50% more.

Materials, effects, sounds, and formatting

• Materials use Bukkit names such as HONEY_BOTTLE and LEATHER_HELMET.
• Potion effects use EFFECT:AMPLIFIER, such as SLOWNESS:0. Amplifiers are zero-based, so 0 is level I and 1 is level II.
• Sounds use Bukkit sound names such as ENTITY_PLAYER_LEVELUP.
• Names, lore, symptoms, GUI labels, and messages support MiniMessage.

Creating and configuring conditions

Every entry under conditions: represents a disease, injury, chronic condition, or recovery effect.

conditions:
  example_condition:
    display-name: "<red>Example Condition"
    category: INFECTIOUS
    testable: true
    public: false
    death-policy: KEEP
    surgery-required: false
    stages:
      - duration: 10m
        transmissibility: 0.0
        stamina-multiplier: 0.9
        periodic-damage: 0.0
        terminal-on-damage: false
        effects: ["WEAKNESS:0"]
        symptoms: ["<gray>You feel unwell."]

Condition fields

| Field | Meaning | |---|---| | display-name | MiniMessage name shown to players and staff | | category | Controls broad condition behavior; see below | | testable | Whether a diagnostic sample can report this condition; defaults to true | | public | Whether staff application and normal recovery use public broadcast notices; defaults to false | | death-policy | What happens to the condition when the player dies | | surgery-required | Whether successful surgery removes it; defaults to false | | transmission | Optional respiratory exposure rules | | treatment-protocol | Optional timed multi-dose treatment rules | | stages | Ordered list of condition stages; at least one is required |

Categories

| Category | Behavior | |---|---| | INFECTIOUS | A disease. Uses “contracted” messaging and can use respiratory transmission. | | TRAUMA | A physical injury. Multiple instances of the same trauma are allowed and body-part effects apply. | | CHRONIC | A persistent condition. Its final stage does not recover automatically. | | RECOVERY | A temporary recovery condition such as post-mortem trauma. | | FICTIONAL_STD | A fictional venereal condition. Uses disease messaging and is suitable for a timed treatment protocol. |

Only TRAUMA allows multiple simultaneous instances of the same condition key. Other categories ignore attempts to add a duplicate active condition.

Death policies

| Policy | Result on death | |---|---| | KEEP | The condition remains after respawn. This prevents death from being used as a cure. | | CLEAR | The condition is removed on death. | | POST_MORTEM_TRAUMA | The condition is removed and the configured post_mortem_trauma condition is applied once. |

Stage fields

| Field | Meaning | |---|---| | duration | Online time before advancing to the next stage | | transmissibility | Respiratory exposure multiplier during this stage; 0 means non-contagious | | stamina-multiplier | Lower values make sprinting with the condition more exhausting; multiple active conditions stack | | periodic-damage | Health points of damage applied every ten seconds; 2 health points equal one heart | | terminal-on-damage | If true, taking any damage during this stage immediately kills the player | | effects | Potion effects refreshed while the stage is active | | symptoms | One random message shown when the condition begins or enters this stage |

When the last stage ends, ordinary conditions recover automatically. CHRONIC conditions and conditions with a treatment protocol remain in their final stage until explicitly cleared or cured.

Trauma body effects

Body-part wounds add effects independently of the configured stage effects:

| Body part | Added effect | |---|---| | Head | Nausea and Darkness | | Arm | Weakness II and Mining Fatigue I | | Leg | Slowness II | | Chest or abdomen | Weakness I |

Respiratory transmission

transmission:
  mode: RESPIRATORY
  radius: 8.0
  exposure-per-check:
    mean: 12.0
    standard-deviation: 2.4
  exposure-decay:
    mean: 1.5
    standard-deviation: 0.4
    severity-factor: 1.25
  blocked-exposure-multiplier: 0.05
  infection-threshold: 100.0

• mode: RESPIRATORY enables proximity exposure; NONE disables it.
• radius: maximum three-dimensional transmission distance in blocks.
• exposure-per-check.mean: average base exposure generated per transmission pass.
• exposure-per-check.standard-deviation: random variation around the mean.
• exposure-decay.mean: average exposure removed per pass.
• exposure-decay.standard-deviation: random variation in decay.
• severity-factor: divides decay. Higher values make exposure persist longer.
• blocked-exposure-multiplier: multiplier used when a wall, floor, closed door, or other collision block intersects the eye-to-eye path. 0.05 allows 5% of normal exposure.
• infection-threshold: accumulated exposure needed to contract the disease.

Gaussian gain and decay rolls are clamped to four standard deviations from their mean and cannot be negative. Decay occurs before new gain on each pass. Exposure is saved across restarts but does not decay while offline.

Distance, source PPE, target PPE, vaccination protection, hospital regions, barriers, and the source's current stage all modify exposure. Multiple infected players each add a separate exposure roll.

See the transmission sections in this guide for formulas and detailed balancing examples.

Timed treatment protocols

Use a protocol when a condition requires repeated doses at specific intervals.

treatment-protocol:
  item: art_dose
  initial-required-doses: 7
  minimum-interval: 10m
  maximum-interval: 15m
  added-doses-per-miss: 2
  terminal-after-misses: 2

| Field | Meaning | |---|---| | item | Key of an item whose action is PROTOCOL_DOSE and whose treats list includes this condition | | initial-required-doses | Successful doses required to cure the condition | | minimum-interval | Doses taken sooner than this are consumed but ineffective | | maximum-interval | The dose must be taken by this time | | added-doses-per-miss | Additional successful doses required after each missed window | | terminal-after-misses | Number of misses that forces the condition into its final stage |

The first dose starts the protocol and counts as successful. Each successful dose resets the interval clock. Protocol timing advances only while the player is online.

config.yml reference

Database

| Field | Meaning | |---|---| | database.file | SQLite filename inside the Health plugin folder; paths cannot escape that folder | | database.busy-timeout-ms | How long SQLite waits for a temporary lock | | database.backup-on-startup | Creates a timestamped backup during startup | | database.backup-retention | Number of Health backups retained |

Simulation

| Field | Meaning | |---|---| | tick-seconds | Base simulation interval; changing it requires restart | | autosave-seconds | Interval between persistent state saves | | transmission-check-seconds | Interval between respiratory exposure and decay passes | | maximum-transmission-radius | Validation and performance cap for individual disease radii; it does not itself increase their range | | hospital-transmission-multiplier | Exposure multiplier when either player is in a health-hospital region | | maximum-active-conditions-per-player | Safety cap on simultaneous condition instances |

Unconsciousness and revival

| Field | Meaning | |---|---| | enabled | Enables knockouts instead of ordinary immediate death within the configured health window | | immediate-death-below-health | Projected health below this value dies immediately. The default -4 health is negative two hearts. Projected health from 0 through -4 is downed. | | bleed-out-seconds | Initial online bleed-out timer | | first-aid-extension-seconds | Time added by ordinary first aid | | first-aid-once-per-down | Limits ordinary first aid to one successful use per downing | | stabilized-transport-seconds | Timer assigned by command stabilization | | revival-health | Health restored when revived | | revive-channel-seconds | How long physical EMS revival takes | | revive-range | Maximum responder-to-patient distance | | revive-movement-tolerance | How far the responder may move from their starting point before cancellation | | revive-countdown-sound | Sound during the channel | | revive-complete-sound | Successful revival sound | | revive-cancel-sound | Interrupted revival sound | | block-chat | Prevents downed players from chatting | | allowed-command-roots | Commands a downed player may still use, without the leading slash | | bypass-damage-causes | Damage causes that use normal death instead of the downed system |

A downed player is prone, immobile, unable to interact, and can be executed by further damage. Their execution reserve depends on how far the original hit was from the immediate-death boundary.

Any player with health.firstaid may right-click the patient with an EMS Medical Bag to add time, subject to the one-use-per-down setting. A responder with health.ems.stabilize instead starts the configured stationary revival channel. Successful revival consumes one bag charge and does not remove serious wounds.

Stamina

| Field | Meaning | |---|---| | enabled | Enables custom sprint stamina | | own-experience-bar | Displays stamina through vanilla XP and disables XP gain, Mending, enchanting, and anvil output | | maximum | Maximum stamina points | | sprint-cost-per-second | Stamina spent while sprinting | | recovery-per-second | Base recovery while not sprinting | | exhausted-restart-threshold | Stamina required before sprinting can restart after depletion | | nutrition-recovery-minimum | Minimum nutrition multiplier applied to stamina recovery |

Fitness also affects stamina recovery. Conditions can add further exertion through their stage stamina-multiplier. health.bypass.stamina bypasses this system.

Nutrition and fitness

| Field | Meaning | |---|---| | history-size | Number of recent configured foods retained | | diversity-target | Number of distinct food categories needed for maximum diversity credit | | update-seconds | Periodic nutrition update interval | | high-fitness-threshold | Fitness required for Strength I | | strength-nutrition-threshold | Nutrition also required for Strength I | | deconditioned-threshold | Fitness at or below this value applies Slowness I | | heart-condition-threshold | Cardiac risk that applies the heart_disease condition |

Nutrition is based 65% on average food quality and 35% on category diversity, then blended gradually into the player's existing score. A history dominated by protein and grain, or very poor nutrition, increases cardiac risk. Varied good-quality food reduces it.

Sprinting increases fitness. Fitness slowly deconditions over time. Poor nutrition combined with low fitness raises body composition; very high body composition also applies Slowness I.

Injury generation

Fall injuries:

| Field | Meaning | |---|---| | fall.enabled | Enables automatic broken_leg injuries | | fall.minimum-blocks | Fall distance before fracture probability begins | | fall.probability-growth | Controls how quickly fracture probability rises beyond the minimum | | fall.maximum-probability | Hard probability cap |

The fall probability curve is 1 - e^(-growth × excess blocks), capped by maximum-probability.

Melee injuries:

| Field | Meaning | |---|---| | melee.enabled | Enables automatic stab_wound injuries | | melee.base-stab-probability | Chance for a qualifying hit to create the wound | | melee.materials | Held weapon materials that qualify |

WeaponMechanics injuries:

| Field | Meaning | |---|---| | weaponmechanics.enabled | Enables body-point integration when WeaponMechanics is available | | weaponmechanics.bullet-wound-probability | Chance for a hit to create bullet_wound | | weaponmechanics.head-instant-death-probability | Independent chance for a WeaponMechanics head hit to kill immediately |

These systems expect the default condition keys broken_leg, stab_wound, and bullet_wound to exist.

Analyzer

| Field | Meaning | |---|---| | material | Block material treated as an analyzer; every placed block of this material qualifies | | processing-seconds | Countdown before the result appears |

There is no laboratory region. A collector with health.test.collect right-clicks a patient with a Diagnostic Sample Kit. An analyst with health.test.analyze right-clicks the configured analyzer block with the resulting sample.

Samples are serialized, expire after 24 hours, and work only once. Copying one does not create another valid test.

Integrations

| Field | Meaning | |---|---| | worldguard | Enables Health's WorldGuard region rules when WorldGuard is installed | | gsit | Allows Health to clear conflicting GSit poses; the prone KO pose is still enforced by Paper | | weaponmechanics | Enables the WeaponMechanics 4.3.1 injury listener when installed | | oraxen | Reserved compatibility toggle; Health items currently remain native, PDC-authoritative items |

Changing an integration toggle requires restart. Missing optional plugins do not stop Health from loading.

Security

| Field | Meaning | |---|---| | allow-command-blocks | Allows Health commands from command blocks; disabled by default | | max-reason-length | Maximum stored length of staff apply/clear reasons | | audit-staff-record-access | Audits /medical records access |

Apply and clear reasons are optional. Staff actions remain audited when no reason is supplied.

Configuring items

Every custom Health item has a stable key and namespaced identity. Renaming lore or display text does not grant Health behavior to an ordinary vanilla item.

Common fields:

| Field | Meaning | |---|---| | material | Vanilla base material | | color | Optional six-digit hex dye for leather armor only | | name | MiniMessage display name | | lore | MiniMessage lore lines | | action | Behavior type | | treats | Condition keys accepted by treatments, splints, or protocol doses | | uses | Number of charges; currently used by FIRST_AID bags |

Item actions

| Action | Purpose and relevant fields | |---|---| | FIRST_AID | Multi-use EMS bag. Uses uses. Ordinary use extends bleeding; EMS use performs physical revival. | | SAMPLE_KIT | Consumed when collecting a diagnostic sample. | | SAMPLE | Serialized analyzer input generated by the plugin. Keep the default key blood_sample. | | TREATMENT | Consumable ordinary medicine. Uses treats, cure-chance, and wrong-treatment-side-effect-chance. | | SPLINT | Right-click treatment usable on self or another player. Uses the same treatment fields. | | VACCINE | Consumable vaccination. Uses the vaccine fields below. | | PROTOCOL_DOSE | Consumable timed-protocol dose. Uses treats and wrong-treatment side-effect chance. | | PPE | Worn respiratory protection. Uses ppe-multiplier. | | COMPONENT | Inert controlled crafting component. | | BIOWEAPON | Right-click release item. Uses the bioweapon fields below. |

Treatments

action: TREATMENT
treats: [common_cold]
cure-chance: 0.45
wrong-treatment-side-effect-chance: 0.20

The item is consumed whenever used. If the patient has a listed condition, cure-chance is the probability that the condition is removed. If no listed condition is active, the treatment is wrong and wrong-treatment-side-effect-chance controls a 20-second Nausea side effect.

Vaccines

action: VACCINE
vaccine-condition: influenza_like
protection-minimum: 0.68
protection-maximum: 0.88
booster-maximum: 0.98
vaccine-duration: 12h

The first dose rolls protection between the minimum and maximum. Each booster closes 75% of the remaining gap between current protection and booster-maximum. A booster also resets the configured online duration.

Protection multiplies respiratory exposure and bioweapon infection chance by 1 - protection. For example, 80% protection leaves 20% of normal exposure. Use permanent for a vaccine that does not expire.

PPE

ppe-multiplier is the fraction of respiratory exposure remaining. Smaller numbers protect more. Every worn Health PPE piece multiplies together, and both the infected source's and target's PPE are considered.

For bioweapons, only the target's PPE applies.

Bioweapons

action: BIOWEAPON
bioweapon-condition: red_lung
bioweapon-radius: 8.0
bioweapon-infection-chance: 0.90

Right-clicking consumes the item and rolls immediate infection separately for every player in range, including the user unless protected. Target PPE and vaccination reduce the chance. WorldGuard bioweapon and quarantine rules apply. Respiratory walls and exposure thresholds do not apply to the direct bioweapon roll.

Bioweapon use has no permission; control access through recipes, components, regions, and item supply. Every release is audited.

Crafting recipes

Shaped recipe:

recipes:
  example_treatment:
    type: shaped
    output: example_treatment
    permission: health.craft.example_treatment
    shape: [" P ", "GHG", " P "]
    ingredients:
      P: PAPER
      G: GOLD_NUGGET
      H: HONEY_BOTTLE

Shapeless recipe:

recipes:
  example_kit:
    type: shapeless
    output: example_kit
    permission: health.craft.example_kit
    ingredients: [GLASS_BOTTLE, PAPER, IRON_NUGGET]

• type is shaped or shapeless.
• output references an item key from items.yml.
• permission is checked during recipe preview and crafting completion.
• Shaped recipes use one to three rows and one-character ingredient symbols.
• A vanilla ingredient is a material such as PAPER.
• An exact Health item ingredient uses item:<key>, such as item:bioagent_component.

health.craft.* grants all Health recipes. Recipe-specific nodes grant only the exact configured recipe.

Condition triggers

triggers:
  spoiled_food:
    type: FOOD_CONSUMED
    condition: food_poisoning
    probability: 0.35
    cooldown: 20m
    materials: [ROTTEN_FLESH, CHICKEN]
    worlds: [world]
    biomes: [minecraft:swamp]

| Field | Meaning | |---|---| | type | FOOD_CONSUMED, DAMAGE, or ENVIRONMENT | | condition | Condition key to apply | | probability | Chance each eligible trigger evaluation succeeds | | cooldown | Online time before this trigger may evaluate again for that player | | materials | Optional qualifying materials; primarily used by food triggers | | damage-causes | Optional Bukkit damage-cause names for damage triggers | | worlds | Optional lowercase world-name allowlist | | biomes | Optional namespaced biome allowlist |

Empty filter lists mean “any.” Environment triggers are evaluated every ten seconds. A trigger does nothing when the player already has that non-trauma condition or has health.bypass.exposure.

Nutrition foods

foods:
  APPLE:
    category: fruit
    quality: 0.85

• The key is a Bukkit food material.
• category is an arbitrary lowercase grouping used for diet diversity.
• quality ranges from 0.0 to 1.0.

Only foods listed in nutrition.yml affect Health nutrition or fire FOOD_CONSUMED triggers through the tracked-food path. Add every food you want the system to recognize.

Protein and grain are specifically treated as the repetitive meat-and-bread groups for cardiac-risk calculations. Other category names contribute normally to diversity.

Commands

| Command | Purpose | |---|---| | /health or /health status | Personal stamina, nutrition, fitness, cardiac risk, and condition count | | /health system | Plugin version, loaded state, database queue, and hook status | | /health reload | Validate and activate configuration changes | | /health apply <player> <condition> [reason] | Apply a condition to an exact online player; regions are intentionally ignored | | /health clear <player> <condition> [reason] | Remove all instances of that condition key | | /health reset <player> | Set stamina, nutrition, and fitness to 100%, cardiac risk to 0%, body composition to neutral, and clear diet history without clearing medical conditions | | /medical records <player> | View active conditions, stages, and body parts | | /medical stabilize <player> | Command-based stabilization fallback | | /medical revive <player> | Command-based revival fallback after stabilization | | /medical surgery <player> | Open the surgery sequence | | /skylines give health:<item> [player] [amount] | Issue authoritative Health supplies through Core |

Apply and clear reasons are optional. Targets receive confirmation when conditions are applied or cleared.

Permissions

| Permission | Purpose | |---|---| | health.admin | Operator-default parent for shipped admin and medical permissions; excludes bypasses | | health.status.self | Personal status; defaults to everyone | | health.reload | Reload configuration | | health.status.admin | System status | | health.condition.apply.* | Apply every condition | | health.condition.apply.<key> | Apply one specific condition | | health.condition.clear | Clear conditions | | health.values.reset | Reset an online player's wellness values | | health.records.medical | View medical records | | health.records.audit | Reserved audit-history permission | | health.test.collect | Collect diagnostic samples | | health.test.analyze | Analyze samples | | health.firstaid | Use ordinary medical-bag first aid; defaults to everyone | | health.treatment.splint | Apply splints; defaults to everyone | | health.ems.stabilize | Perform physical medical-bag revival and use stabilization fallback | | health.ems.revive | Use the explicit revive fallback command | | health.ems.transport | Reserved for transport integrations | | health.surgery | Perform surgery | | health.craft.* | Craft all Health recipes | | health.craft.<key> | Configured recipe-specific permission | | health.bypass.exposure | Ignore transmission, natural triggers, and bioweapons | | health.bypass.stamina | Ignore stamina depletion |

Operators receive health.admin, but do not automatically receive either bypass permission.

Creative-mode players do not accumulate diet history or undergo nutrition, fitness, cardiac-risk, or body-composition changes. Their stamina is kept full. Diseases, wounds, stages, and treatment protocols still operate normally.

WorldGuard regions

| Flag | Default | Purpose | |---|---:|---| | health-transmission | allow | Deny to prevent players in the region from sending or receiving respiratory exposure | | health-bioweapons | allow | Deny to prevent activation and protect targets in the region | | health-hospital | deny | Allow to apply the configured increased hospital transmission multiplier | | health-surgery | deny | Allow to create an operating room where surgery can begin and continue | | health-quarantine | deny | Allow to isolate transmission and bioweapons to players sharing the same quarantine region ID |

Examples:

/rg flag out_of_rp health-transmission deny
/rg flag out_of_rp health-bioweapons deny
/rg flag central_hospital health-hospital allow
/rg flag operating_room_1 health-surgery allow
/rg flag quarantine_a health-quarantine allow

A denied transmission region wins over the increased hospital multiplier. Staff /health apply always works regardless of region.

Surgery requires both doctor and patient to remain within four blocks of each other and inside a health-surgery allow region. The surgeon must click Sterilize, Anesthetize, Operate, and Close in order, then remain eligible through the 15-second operation.

Without WorldGuard, transmission and bioweapons are unrestricted and surgery is allowed anywhere.

Messages and placeholders

Every top-level entry in messages.yml, except config-version, is a MiniMessage template. <prefix> inserts the configured prefix.

Other placeholders depend on the message and include values such as <player>, <condition>, <seconds>, <time>, <required>, <protection>, <stage>, <body>, <stamina>, and <error>.

Keep required message keys present. User-supplied player names and staff reasons are inserted as literal text and cannot inject MiniMessage formatting.

Adding a new ordinary disease

1. Add the condition and its stages to conditions.yml.
2. Add a transmission section if it should spread by proximity.
3. Add a treatment or vaccine to items.yml if desired.
4. Add recipes and granular crafting permissions.
5. Add natural triggers if the disease should also come from food, damage, biome, or environment.
6. Run /health reload and correct any validation error before testing.
7. Test stage progression, analyzer behavior, correct treatment, wrong treatment, death policy, PPE, vaccination, and region behavior on a staging server.

Important built-in key dependencies

Some mechanics currently refer to these default keys directly:

• broken_leg for fall fractures and the default leg splint
• stab_wound for qualifying melee injuries
• bullet_wound for WeaponMechanics injuries
• heart_disease for cardiac-risk progression
• post_mortem_trauma for traumatic death penalties
• blood_sample for analyzer samples

You may change their presentation and mechanics, but do not remove or rename them while the corresponding system is enabled.