MCSkylines-Health

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

Health tracks infectious conditions, body-part trauma, unconsciousness, diagnostics, surgery, vaccines, nutrition, hydration, fitness, stamina, and hearing/ballistic protection. Values from config.yml, conditions.yml, items.yml, triggers.yml and nutrition.yml are bundled defaults and are configurable; fixed mechanics are identified separately. Health timers progress while the patient is online and persist across restart.

Gunshot wounds and body parts

WeaponMechanics supplies the hit category. BODY is assigned chest 70% of the time and abdomen 30%; ARMS and LEGS/FEET choose left or right randomly. A missing category becomes chest. These are fixed category assignments, not independent anatomical hitboxes or configurable percentages.

Unprotected ballistic hits have a default 55% wound chance. Head hits also roll a default 18% immediate-death chance. Genuine tactical armor reduces final damage and wound probability; head-death chance is multiplied by the protection factor squared. Tasers/stun guns do not generate ballistic wounds or firearm hearing injury. Creative/god-protected victims are excluded.

Every default bullet wound also has a 60-minute stage, a 0.45 stamina multiplier and 0.5 periodic damage on the health service's ten-second damage cadence. Wound severity is derived from final damage (minimum 0.5); repeated injuries can affect multiple body parts. The stage clock still expires naturally. Surgery removes it earlier. The EMS bag revives or buys time for an unconscious patient; it does not cure their bullet wounds.

New damage injuries are saved immediately but wait through a one-second grace period before initial notices, effects, or bleeding. If the killing hit causes death during that grace, the delayed injury does not reappear after respawn. Surviving then reconnecting preserves the injury and original acquisition time.

Post-mortem trauma and recovery

Death creates post_mortem_trauma only when another active condition with POST_MORTEM_TRAUMA death policy was acquired more than one second before death. Its original qualifying injury is removed. A clean death, immediately fatal shot/fall, or post-mortem trauma alone does not create a fresh penalty. Legacy injuries with unknown acquisition time count as pre-existing.

The default recovery condition lasts 60 online minutes, applies Weakness I and Slowness I, and uses a 0.55 stage stamina factor, making sprinting more exhausting. This factor adds exertion; it does not set maximum stamina to 55%. It is non-contagious and testable: false: an analyzer cannot detect it, but /medical records <player> can. With the current death implementation an existing recovery condition is removed during another death and is replaced only if another qualifying injury exists.

There are three removal paths: finish its online stage; successfully complete surgery; or have staff use /health clear <player> post_mortem_trauma [reason]. Neither ordinary cold medicine, a splint, nor a revival removes it. /health reset resets wellness values and does not clear conditions.

Post-mortem surgery has a 30-second treatment channel, increased to 60 seconds if the qualifying death was FALL or DROWNING. The classification only matters when a qualifying pre-existing injury existed. Other surgery uses a 15-second channel. These surgery channel durations are fixed mechanics rather than configurable condition durations. Those durations follow the procedure steps: ordinary surgery uses sterilize → anesthetize → operate → close; ordinary post-mortem treatment adds another operate → close; high-risk post-mortem treatment repeats all four steps twice.

Emergency response and unconsciousness

The downed settings in config.yml are configurable. With the bundled defaults, lethal damage downs the player for a five-minute bleed-out if their hypothetical post-hit health is at least -4 health (-2 hearts). More severe hits and configured bypass causes VOID, KILL, and WORLD_BORDER kill immediately. Downed players cannot chat and are limited to configured allowed command roots; further attack can execute them. Creative players do not enter ordinary simulated damage/downed behavior.

The following response values are configurable defaults from downed in config.yml and the bag definition in items.yml.

1. Approach with the genuine EMS Medical Bag (internal ID first_aid_kit, ten uses).
2. An ordinary responder can extend bleed-out by one minute, once per down by default.
3. An authorized EMS responder uses the bag's five-second revival channel within three blocks and remains still (default 0.12-block tolerance). Moving or losing a valid target interrupts it.
4. Stabilization marks the patient for a ten-minute transport window. Explicit /medical stabilize and /medical revive are authorized command fallbacks; they are distinct from the bag's timed item interaction.
5. Revival restores four health (two hearts); inspect the remaining conditions and arrange definitive treatment.

Surgery workflow

1. Give the surgeon health.surgery. Define an operating region with WorldGuard health-surgery allow (see Region rules below).
2. Both patient and surgeon must remain in an allowed surgery area, in the same world, within four blocks.
3. Run /medical records Patient, then /medical surgery Patient.
4. Left-click the procedure actions in sequence: sterilize, anesthetize, operate, close; follow any repeated sequence required by the recovery case. Decoration is inert. A wrong medical step or prematurely closing the screen fails the procedure.
5. Remain together in the allowed area through the channel. Leaving, disconnecting, or moving beyond range fails it and can cause temporary nausea.
6. Success removes all active conditions whose definition has surgery-required: true. It does not clear unrelated infections or every chronic condition.

Injury and disease directory

The table below enumerates every bundled condition’s configurable defaults from conditions.yml; operators can change durations, effects, stamina, damage, treatment requirements and death policy. Durations are stage sequences in online time; periodic damage is the configured amount on the ten-second damage cadence before health simulation modifiers. Effects in this configuration table use zero-based amplifier notation (0 is level I, 1 is level II). IDs are the arguments to staff apply/clear commands and treatment configuration.

Diagnostics and medical records

Use a genuine Diagnostic Sample Kit on a patient to create a sealed serialized sample. Insert it into a standalone configured analyzer (BREWING_STAND by default), which uses configurable analyzer.processing-seconds (default 10 seconds). The sample captures the first active testable condition at collection; it is not a complete current-condition scan. No testable condition produces a negative result. Medical records list all active conditions, stage and body part, even non-testable ones, and access is audited when configured.

Respiratory exposure, PPE, and vaccination

Common Cold, Influenza-like Illness, and Red Lung accumulate respiratory exposure from nearby infected online players. Each stage has its own transmissibility. Radius, Gaussian exposure and decay, infection threshold, and severity factor are per-condition. Walls/floors attenuate to 5% by default; configurable simulation.hospital-transmission-multiplier defaults to 1.5. PPE multiplies incoming/outgoing exposure for genuine equipped items. Coughing is a player action. Exposure thresholds and vaccines determine infection risk, rather than every cough guaranteeing infection.

The configurable Influenza vaccine defaults in items.yml are 68–88% initial protection, 12 online hours and a 98% booster maximum. It reduces exposure risk rather than curing an existing illness. Cold Relief Medicine’s configurable items.yml defaults are a 45% cure chance for Common Cold and a 20% wrong-treatment side-effect chance. A failed roll need not mean the item was invalid.

AVS treatment protocol

AVS is a fictional public-policy condition: staff diagnosis/normal clearance use configured public announcements. The configurable protocol in conditions.yml defaults to seven successful `art_dose` doses, a 10–15 online minute dose interval, two added doses per missed window and two misses before terminal behavior. The following timing examples use those defaults. After a dose, wait at least ten and at most fifteen online minutes for the next accepted dose. Each missed window adds two doses; two misses advance terminal behavior. Early doses do not satisfy the next window. The terminal stage can kill on subsequent damage. Ordinary medicine and surgery are not substitutes for the configured protocol. Public status does not make the condition respiratory.

Splints, hearing, and tactical armor

A Leg Splint can treat yourself or another player for broken_leg, with a default 100% cure chance. Default sword/trident hits can create stab wounds; falls above five blocks have a rising fracture chance capped at 90%. Burns and smoke conditions can be supplied by Fire.

The firing listener’s fixed, non-configurable hearing-injury mechanics give each unprotected firearm shot a 2.5% chance of tinnitus (configurable condition duration; default 45 online minutes). While tinnitus is active, each further unprotected shot rolls a 1% chance of hearing loss (configurable condition duration; default six online hours), which replaces tinnitus. Tinnitus plays a high-pitched beacon ambient sound every two seconds; hearing loss repeatedly stops the affected player’s sounds. These bundled conditions expire naturally, or an authorized configured treatment/staff clearance can remove them. Genuine hearing protection and integrated tactical helmets protect the shooter. The fixed tactical armor factors are 0.22 for head hits and 0.95 elsewhere; chestplate 0.34 for chest/abdomen/arms and 0.95 elsewhere; leggings 0.48 for legs and 0.95 elsewhere; boots 0.95. Factors multiply for equipped qualifying pieces. Names/lore alone do not provide protection.

Nutrition, hydration, fitness, and stamina

Configurable nutrition.history-size and nutrition.diversity-target default to the last 20 foods and five categories. Configured food quality, diversity and activity affect nutrition, fitness, body composition and cardiovascular risk; defaults evaluate nutrition/fitness every minute. Disease stages and trauma can further reduce stamina. Water/hydration state is visible to authorized status tools.

The configurable stamina settings in config.yml default to using the XP bar, seven units/second sprint cost and five units/second recovery before modifiers. With configurable stamina.maximum: 100 and stamina.fitness-capacity-bonus: 1.0 defaults, capacity is 100 at fitness 0.5 and 200 at maximum fitness. Exhaustion stops sprinting until the configurable stamina.exhausted-restart-threshold is reached (default 12 units); walking, jumping and normal actions remain possible. Ordinary jump/food restrictions are not imposed by this exhaustion latch. /health status [player] is staff-only, not a universal player health dashboard.

Medical item directory

Issue genuine items through /skylines give health:<item> [player] [amount]. Medical recipes have granular crafting permissions. Persistent item identity, rather than material/display name, selects the action.

The listed medical item uses, treatments and PPE properties are configurable bundled defaults in items.yml.

Files

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:

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.

Condition configuration reference

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

Categories

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

Death policies

Stage fields

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:

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 respiratory transmission calculations below 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

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

Simulation

Unconsciousness and revival

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

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

Hydration gives stamina recovery a small additional multiplier. Drinking a potion, milk, or honey restores it; when low, fitness declines slowly and a thirst reminder appears about every ten minutes. Hydration does not cause direct damage. Sprint input remains blocked at exhaustion even if control is held; recovery pauses while the player keeps attempting to sprint.

Nutrition and fitness

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:

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

Melee injuries:

WeaponMechanics injuries:

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

Analyzer

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

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

Security

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:

Item actions

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]

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.

Region rules

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 timed operation. Ordinary surgery takes 15 seconds. Post-mortem trauma lasts one hour and is surgically curable: the operation takes 30 seconds after ordinary death, or 60 seconds after fall or drowning death.

swat_helmet, swat_chestplate, swat_leggings, swat_boots and the matching militant_* items are tactical armor. Both helmets include hearing protection. Armor reduces WeaponMechanics damage, wounds, and headshot death chance according to the protected body part, plus a smaller reduction for other entity attacks. Issue with /core give health:<item_id>. Stable IDs and dyed leather colors provide a usable fallback while custom item models and worn textures are prepared.

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.

Respiratory transmission calculations

Respiratory transmission is configured separately for each disease in conditions.yml. The system uses accumulated exposure rather than a percentage chance: a player contracts a disease when their stored exposure reaches its infection-threshold.

Transmission: Complete example

conditions:
    example_disease:
        display-name: '<red>Example Disease'
        category: INFECTIOUS
        testable: true
        death-policy: KEEP
        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
        stages:
            - duration: 10m
              transmissibility: 0.35
              stamina-multiplier: 0.9
              effects: []
              symptoms: ['<gray>You feel unwell.']
            - duration: 30m
              transmissibility: 1.0
              stamina-multiplier: 0.6
              effects: ['WEAKNESS:0']
              symptoms: ['<red>Your symptoms are getting worse.']

Transmission: Field reference

mode

• RESPIRATORY enables proximity transmission.
• NONE disables respiratory transmission.

Conditions without a transmission section do not spread between players.

radius

The maximum three-dimensional distance between the infected player and the target, measured in blocks. Players beyond this distance receive no exposure.

Exposure also decreases inside the radius:

distance multiplier = max(0.15, 1 - distance / (radius × 1.25))

At point-blank range the multiplier is 1.0. At the configured radius it is 0.2. Chunks are only used to find nearby players efficiently; chunk borders do not block transmission.

exposure-per-check

The exposure points generated every transmission pass. The default pass interval is configured by simulation.transmission-check-seconds in config.yml and is currently three seconds.

Each source-to-target exposure uses a new Gaussian roll:

rolled exposure = mean + random Gaussian value × standard-deviation

The random value is clamped to four standard deviations in either direction, and the final result cannot be negative. A mean of 10 and standard deviation of 2 therefore produces values between 2 and 18, with most rolls close to 10.

This is not an infection percentage. It is the starting number of exposure points before other multipliers are applied.

exposure-decay

Accumulated exposure decreases once per transmission pass while the player is online. Decay happens even when the player is still receiving new exposure.

mean and standard-deviation use the same Gaussian rules as exposure gain. The actual reduction is:

exposure removed = rolled decay / severity-factor

The stored exposure cannot fall below zero. Exposure does not decay while the player is offline, and the remaining amount is saved across restarts.

severity-factor

Controls how long exposure to this disease remains in a player's system:

• 1.0 applies the rolled decay normally.
• Above 1.0 slows decay and makes exposure persist longer.
• Below 1.0 accelerates decay and clears exposure faster.

For example, a decay roll of 2 removes:

blocked-exposure-multiplier

Applied when a solid collision block intersects the eye-to-eye path between the two players. This covers full walls, floors between vertically separated players, closed doors, and similar barriers.

• 0.05 allows 5% of normal exposure, a 95% reduction.
• 0.0 blocks exposure completely.
• 1.0 makes barriers provide no protection.

This multiplier is applied in addition to distance, PPE, vaccination, and hospital modifiers.

infection-threshold

The accumulated exposure required to contract the disease. When the total reaches this value, the exposure is cleared and the condition is applied.

Keeping thresholds at 100 makes the other values easy to reason about, but thresholds can differ between diseases.

Stage transmissibility

Each disease stage multiplies the rolled exposure:

• 0.0 means the stage is not contagious.
• 0.5 produces half exposure.
• 1.0 uses normal exposure.
• 1.25 produces 25% more exposure.

Existing accumulated exposure remains when the source changes stages.

Transmission: Complete gain calculation

For every infected source near a target, the plugin calculates:

gain = Gaussian exposure roll
     × stage transmissibility
     × distance multiplier
     × blocked-path multiplier, when blocked
     × source PPE multiplier
     × target PPE multiplier
     × hospital multiplier, when either player is in a hospital
     × (1 - target vaccination protection)

Decay is applied first during the transmission pass, followed by exposure from every nearby infected player. Multiple infected sources therefore add separate exposure rolls to the same target.

WorldGuard transmission denial and incompatible quarantine regions prevent the gain entirely. The health.bypass.exposure permission also prevents the player from acquiring exposure.

Transmission: Estimating timing

Without distance, walls, PPE, vaccination, or hospital modifiers:

average gain per pass = exposure mean × stage transmissibility
average decay per pass = decay mean / severity-factor
approximate net gain = total gain from all sources - average decay

If net gain is positive, approximate time to infection is:

(infection threshold - current exposure) / net gain × transmission-check-seconds

If net gain is zero or negative, exposure will generally stabilize or clear rather than reaching the threshold. Gaussian variation means actual timing will vary.

To estimate clearing time after leaving the infected area:

current exposure / (decay mean / severity-factor) × transmission-check-seconds

For example, 60 exposure with a decay mean of 1.5, severity factor of 1.25, and a three-second check interval takes approximately 150 online seconds to clear:

60 / (1.5 / 1.25) × 3 = 150 seconds

Transmission: Default diseases

At 60 stored exposure and no new contact, their approximate average clearing times are 68 seconds, 150 seconds, and 360 seconds respectively.

Transmission: Tuning recipes

To make a disease spread faster:

• Increase exposure mean.
• Increase stage transmissibility.
• Increase radius.
• Lower infection threshold.
• Lower decay mean or increase severity factor.

To make infection timing less predictable, increase the exposure standard deviation. A standard deviation around 15–25% of the mean gives noticeable variability without making outcomes excessively erratic.

To make brief encounters matter for longer, increase severity factor or reduce decay mean. To make players recover quickly after leaving an infected area, do the opposite.

To make walls more protective, lower blocked-exposure-multiplier. A value of 0.05 is already a dramatic reduction; use 0.0 for total obstruction.

After editing conditions.yml, run /health reload. The plugin validates the complete candidate configuration before activating it, so an invalid value will not partially replace the live settings.

Tactical armor and tasers

Genuine Health SWAT (swat_*) and military (militant_*) armor has a fixed 99% chance per taser/stun-gun projectile hit to block the impact and its WeaponMechanics stun effects. Protection follows the impact location: helmet for head, chestplate for body/arms, leggings for legs, boots for feet. A full set covers every impact; a partial set leaves uncovered areas vulnerable. Armor IDs are checked through the Health item tags, so ordinary renamed leather armor does not qualify. The remaining 1% of protected hits and all uncovered hits use the weapon's normal mechanics. This applies when the Health WeaponMechanics integration is enabled and does not change firearm damage, injuries, or ordinary potion effects.

Restrained unconscious vehicle transport

Justice's authorized passenger transport now brackets Health's unconscious floor anchor with HealthApi.beginVehicleTransport(player) and endVehicleTransport(player). These main-thread scopes nest. A downed patient retains bleed-out, injuries and unconscious state while a vehicle owns their position. Movement/pose enforcement skips authorized seat transfers and seated patients. On exit, Health restores a supported unconscious pose at the current position instead of teleporting back to the pre-transport floor. Walking custody escorts remain disabled for unconscious people. Restrained patients keep cuffs or zipties while being placed, driven and removed.

HealthApi.currentStamina(player) exposes the loaded current value for Justice's tackle contest; maximumStamina and consumeStamina retain their existing behavior. Tackle applies a capped half-heart loss without generating a gun wound. Tasing, spray and baton incapacitation do not mark a player medically unconscious. Health's downed.block-chat and unconscious command restrictions remain applicable to actual downed patients.

Impact stamina penalties

Justice tackles now spend 40 stamina per attempt by default, including failures, and accepted successful tackles drain 25 stamina from the defender. Penalties stop at zero and apply even to someone recovering from exhaustion. The ordinary exhaustion/recovery rules still govern when another exertion can begin.

The main-thread Health API adds drainStamina(player, amount), returning the actual amount lost. Unlike voluntary consumeStamina, it permits a partial debit and does not reject an already exhausted player. Disabled stamina, creative mode and health.bypass.stamina keep their existing exemptions. Invalid amounts and unloaded or downed players cause no debit. State and the stamina display update together; existing Health autosave/logout persistence retains the changed stamina.

Reading command syntax

Configuration defaults: Values shown for operator-configurable settings are the bundled defaults, and can be changed in the module’s configuration or definitions. The server’s active settings take precedence, so costs, speeds, ranges, durations, chances, effects, recipes, limits and enabled features may differ. Command examples illustrate syntax; fixed mechanics and validation bounds are not configuration defaults.

<argument> is required; [argument] is optional. Replace the placeholder, including its brackets, with your value. Choices separated by a vertical bar mean choose one. ... accepts the remaining words. Do not type quotation marks around multiword names unless the command specifically requires them. A bare command has no required arguments. Examples use sample players/IDs: substitute entries from your server and use Tab for configured IDs.

player means a username; operational actions usually require that player online. amount and price are currency values such as 25.00, unless the row specifies items, levels, or units. reason, memo, message, name, and statement accept text where supported. duration uses the module's duration format (for example 10m, 2h, or 7d); it is not a bare number of minutes unless stated. id is the exact identifier displayed by that system, not its friendly name. Permissions and ownership/state/location checks both apply.

Health commands

Examples: /medical records Alex; /medical surgery Alex; /health clear Alex post_mortem_trauma Staff treatment. All medical commands require an in-game responder. Command blocks are rejected unless explicitly enabled in Health security configuration.

Root commands and aliases

These are the registered command entry points. The subcommand tables above describe their complete operations. Alias names use the same arguments as their root.