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 expires naturally outside an active surgical case. Surgery removes the wound after its required treatment and closure. The EMS bag revives an unconscious patient; the separate civilian kit buys time; 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 normally creates post_mortem_trauma 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 or immediately fatal hit normally creates no penalty; suicide-classified deaths also create whole-body post-mortem trauma without a pre-existing injury. The classification follows explicit SUICIDE, self-kills, and the suite forensic convention of FALL without a recorded killer; accidental falls can therefore receive this classification. 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 xray <player> can. With the current death implementation an existing recovery condition is removed during another death and is replaced if another qualifying injury or a suicide classification 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 requires whole-body treatment and two different games at every site; suicide-classified cases require all three. There is no fixed surgery-completion channel.

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. Use first_aid_kit (Civilian First Aid Kit, one use) with health.firstaid to add one minute to an unconscious patient's bleed-out, once per down by default. It cannot revive or cure injuries.
2. Use ems_medical_bag (EMS Medical Bag, ten charges) with health.ems.revive to perform the five-second stationary revival within three blocks; the default movement tolerance is 0.12 blocks. It cannot perform civilian first aid. There is exactly one EMS bag ID and no medical_bag alias.
3. Revival restores four health (two hearts), removes unconsciousness and permits normal movement. It preserves injuries, infections and post-mortem trauma. /medical revive Patient remains an authorized command fallback and no longer requires a separate stabilization step. Definitive surgical treatment is still required for surgical injuries.
4. Leg splints provide two minutes of Resistance I support for a broken leg; the fracture remains and still needs surgery. Neither the civilian kit nor the EMS bag cures it.

Surgery workflow

1. Give clinicians health.xray and surgeons health.surgery. Define an X-ray room with /rg flag xray_room health-xray allow and an operating room with /rg flag operating_room health-surgery allow. Both clinician and patient must be within four blocks, in the same world, in the appropriate allowed area. X-rays require WorldGuard; surgery retains its anywhere fallback when WorldGuard is absent.
2. Run /medical xray Patient. It reports every exact condition, stage and affected body part, including conditions with testable: false, surgical failures and outstanding antibiotic courses. Whole-body post-mortem trauma requires treatment of head, chest, abdomen, both arms and both legs. /medical records and /medical stabilize are unavailable.
3. Bring genuine health: supplies, issued through /skylines give health:<id> or crafted with the corresponding health.craft.<id> recipe permission. Supplies are disinfection_kit, anesthetic_vial, surgical_syringe, surgical_stitches, scalpel, forceps, bone_setter and cautery. Tools are retained; disinfection kits, syringes, vials and stitch packets are spent by their actions. Craft one disinfection kit from one genuine surgical_alcohol and one genuine sterile_gauze using health.craft.disinfection_kit. Vanilla ingredients or renamed items do not substitute for those components.
4. Run /medical surgery Patient. Select a body part on the anatomy panel, or right-click the standing patient's actual body part after closing the panel. Use the panel for prone patients because their rendered pose and interaction hitbox can differ. Left/right labels refer to the patient's anatomy. Multiple conditions at one site require separate operation and closure cycles; select that site again for the next condition.
5. Close the menu and hold disinfection_kit in the main hand. Right-click the body part being treated. One kit disinfects that site and is consumed. There is no separate gauze action; alcohol and gauze are crafting ingredients. The action gives chat feedback without opening a menu. Preparation can be omitted, but an unsterile incision immediately rolls the infection table at an 85% risk multiplier when the operation actually begins. Preparation cannot retroactively sterilize an open incision. For prone patients, select the anatomy in /medical surgery first; that selected site is used for supply clicks.
6. No IV is required. Equip surgical_syringe, keep anesthetic_vial in the inventory, right-click the patient and hold right-click. Each started attempt spends one syringe and one vial, including early release and interruption. A missing vial prevents the attempt and preserves the syringe. The syringe remains visible during the hold and is removed when the dose resolves; a used syringe cannot start another dose. Release at 3.5 seconds, shown at the boss bar's center; ±0.25 seconds is safe. The bar turns green in the safe window and red above it. Item changes or interruption resolve the partial dose. Holding to twice the target resolves an overdose automatically. These are fictional game timings, not medical instructions.
7. Anesthesia lasts 240 online seconds. Under the safe dose, the normalized shortfall scales the default 85% maximum chance of surgical_stress when operation begins; missing or expired anesthesia uses the full shortfall. Above the safe dose, the normalized excess scales a configurable death probability; surviving an overdose still counts as one failure. surgical_stress is a persistent chronic condition with nausea, darkness and a 0.6 stamina factor; staff or an operator-configured treatment can clear it.
8. Choose Operate on the selected site. Before each mini-game, choose Read instructions to open its handbook, or Begin to skip the book and start. Close the book and right-click the patient to return to the preparation screen. No incision or game timer starts until Begin, and reading or leaving this screen is safe. Ordinary surgery randomly selects one game; post-mortem cases require two different games per site; suicide post-mortem cases require all three per site. Choices remain stable when a case is reopened. Surgical tissue-damage complications require two games. Extensive cases add repair actions, longer patterns and more tracing passes.
9. Choose Close incision for each operated site. Its preparation screen also offers an instruction book. Begin spends one stitch packet and starts the timer. Click the next stitch every 1.5 seconds, within ±0.35 seconds. Ordinary closure needs three stitches; extensive cases and repair work require more. The action bar turns green in the timing window. A rushed, late, wrong-position, interrupted or abandoned stitch produces a poor closure; its normalized error controls infection probability. Failure to act by twice the target produces maximum error.
10. After every required site has been operated on and closed, run /medical finish Patient. Completion removes only the treated surgical conditions and starts antibiotic aftercare. Unrelated infections and chronic conditions remain. An early finish command is rejected without adding a failure.

Preparation uses physical item interactions; the selected-site menu contains only Operate and Close incision. Sterilization uses a crafted disinfection kit; anesthesia uses a single-use syringe and an inventory vial. There is no separate gauze application or IV placement step. Right-clicking with a preparation supply can start the case directly when the surgeon and patient meet the normal operating-room, permission and distance checks. The anesthetic vial stays in the inventory and is spent through the syringe; clicking with a vial explains that requirement. Duplicate entity events from one click never consume a second supply.

Surgeons may choose an incorrect or healthy body part. It allows the normal operation and closure puzzles but treats no underlying injury; the actual affected sites still need treatment before /medical finish succeeds. The menu does not reject a wrong selection or reveal the correct anatomy. Opening any incision still carries the normal preparation, anesthesia, complication and closure risks. Merely selecting or disinfecting an incorrect area creates no incision and does not prevent finishing the real treatment.

The three operation games

Clinical knowledge: scalpels expose tissue, forceps extract foreign objects/remove damaged tissue, bone setters align fractures, and cautery controls bleeding. The editable procedures in surgery.yml pair each clinical clue with the required tool; a default procedure covers additional surgical conditions. These clues describe game actions.

Mini-game timing settings

puzzles in surgery.yml controls timing at 20 ticks per second. Missing keys use these defaults; existing custom values are preserved. Restart after installing the update; /health reload applies subsequent setting edits and safely interrupts active sessions.

Books display the configured timings for that surgical session. Every game and each closure attempt offers the book before Begin. Reading between extensive-case games does not reset completed games or add a failure.

Failures, complications and persistence

An operation mistake adds surgical_complication at the affected part and extra repair steps to the original incision. Repairing the complication requires additional surgery and closure. Poor closure adds infection risk without creating tissue damage. Surviving an overdose also counts as a failure. The third surgical failure kills the patient. The counter belongs to the unfinished patient case and persists across reconnects, restarts and surgeon changes; finishing the case clears it for future cases.

After Begin, closing a running mini-game, leaving range/region, disconnecting or losing surgery permission interrupts the action and counts one failure. Preparation screens and instruction books are untimed game phases and can be closed without a failure; the ordinary two-minute idle session lock still applies. Closing an idle preparation/anatomy panel to obtain supplies does not fail surgery. Idle session locks expire after two minutes; an interrupted active puzzle still fails. Server shutdown preserves completed steps without an administrative-interruption failure. Case progress and open incisions are stored in the Health SQLite transaction with conditions and aftercare. A patient cannot have concurrent surgeons, and one surgeon cannot treat several patients at once. Surgical condition stage clocks pause while their unfinished case remains active; their symptoms and damage remain.

Infection probability table and antibiotic aftercare

surgery.yml defines an ordered infections map of condition IDs to absolute percentages. The defaults are surgical_wound_infection: 45, surgical_systemic_infection: 25, and surgical_resistant_infection: 15. One roll selects at most one infection; the remaining 15% means none. Values must be finite, nonnegative, total at most 100, and reference defined, nonsurgical conditions. The map is configurable; it is not a set of independent rolls or normalized weights.

The table is scaled by the event's risk multiplier: 0.85 for an unsterile incision, the closure error for poor closure, and the saved case risk for missed antibiotic windows. Thus an unsterile incision has a default 72.25% overall infection probability. Aftercare risk is min(1, 0.10 + (unsterile ? 0.65 : 0) + closure_error * 0.65 + failures * 0.08), using the worst site. Timely antibiotics prevent missed-window rolls; they do not erase an already acquired infection.

After finishing, the patient has three postoperative antibiotic windows, each 10–15 online minutes after surgery or the previous dose/window. Right-click postoperative_antibiotic during a window to use one opportunity safely; early doses are rejected without consumption. A missed window silently rolls the infection table and also uses up one opportunity. After three taken or missed windows combined, the course ends: missed doses never add replacement windows, and a patient can avoid infection by chance even after missing all three. There are no automatic due or missed-dose reminders. Window progress and risk persist through reconnect/restart. Separate operations can create separate courses; one accepted dose satisfies one due course.

Diagnosed infections use infection_antibiotic on a separate protocol: three successful doses for wound/systemic infections or five for resistant infection, at 10–15 minute intervals; a missed infection-treatment window adds one dose. Postoperative prophylaxis and infection treatment are distinct items. All these counts, intervals, disease effects, procedure tool lists, anesthesia settings, closure settings and infection percentages are configurable in surgery.yml, items.yml and conditions.yml. The 1/2/3 game rule, third-failure death, four-block distance, two-minute idle lock, operation controls are fixed game mechanics; mini-game timing is configurable through the puzzles section.

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.

1. Use first_aid_kit (Civilian First Aid Kit, one use) with health.firstaid to add one minute to an unconscious patient's bleed-out, once per down by default. It cannot revive or cure injuries.
2. Use ems_medical_bag (EMS Medical Bag, ten charges) with health.ems.revive to perform the five-second stationary revival within three blocks; the default movement tolerance is 0.12 blocks. It cannot perform civilian first aid. There is exactly one EMS bag ID and no medical_bag alias.
3. Revival restores four health (two hearts), removes unconsciousness and permits normal movement. It preserves injuries, infections and post-mortem trauma. /medical revive Patient remains an authorized command fallback and no longer requires a separate stabilization step. Definitive surgical treatment is still required for surgical injuries.
4. Leg splints provide two minutes of Resistance I support for a broken leg; the fracture remains and still needs surgery. Neither the civilian kit nor the EMS bag cures it.

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 recent nutrient balance, 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, with gains scaled by nutrition. 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.

Vanilla foods listed in nutrition.yml and successful Agriculture meal profiles affect Health nutrition and fire FOOD_CONSUMED triggers through their respective tracked-food paths. 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 uses separate preparation, timed anesthesia, per-site operation puzzles and careful closure. See Surgery workflow for supply IDs, risks and the finish command.

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>. The matching pack supplies inventory models and worn textures; stable IDs and dyed leather colors provide a fallback.

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, patrol body armor and tasers

Issue patrol body armor with /skylines give health:police_body_armor. It uses the matching pack's compact navy body-armor item model and chest-only worn equipment texture. Existing servers receive the missing item definition automatically; customized definitions are preserved. Reissue an item to obtain its latest visual components.

The complete Oraxen installer includes these five files under Oraxen/pack/assets/mcskylines/. To restore only the patrol vest in an existing custom pack, add or replace these paths under its assets/mcskylines/ directory:

• items/health_police_body_armor.json
• models/item/health_police_body_armor.json
• textures/item/health_police_body_armor.png
• equipment/police_body_armor.json
• textures/entity/equipment/humanoid/police_body_armor.png

Preserve all unrelated pack files. The item definition and equipment definition are required alongside the model and textures for inventory and worn appearance. Regenerate and distribute the server's merged pack using its normal workflow, then check the vest both in inventory and while worn. The suite-only client ZIP contains the same five files; retain custom server content when preparing the final client pack.

Genuine Health SWAT (swat_*) and militant (militant_*) armor blocks 99% of taser/stun-gun projectile impacts on the covered slot: helmet for head, chestplate for body/arms, leggings for legs, and boots for feet. Patrol body armor blocks 49.5% of body/arm taser hits, half the SWAT chestplate probability, and protects no other slot. Unblocked hits retain the weapon's normal stun mechanics. Names, lore, ordinary leather and items in the wrong slot grant no tactical bonuses. Taser interception requires the Health WeaponMechanics integration.

The patrol vest uses the SWAT chestplate's gun protection: damage and wound factors are multiplied by 0.34 for chest/abdomen/arm impacts and 0.95 elsewhere. Its protection against ordinary entity attacks also matches that chestplate.

Each correctly equipped SWAT or militant piece adds five percentage points to the wearer's Justice tackle success and subtracts five points from an opponent's success. Patrol body armor grants 2.5 points of defensive resistance, half one SWAT chestplate, with no offensive bonus. Four tactical pieces total 20 points; equally equipped opponents cancel each other's bonuses. The ordinary 55–95% contest is adjusted by equipment afterward and capped at 95% (35% minimum with the currently available gear).

A full matching four-piece SWAT or militant suit blocks new pepper-spray hits and adds two accepted baton hits before incapacitation: 4/5/6 hits, weighted 20%/60%/20%. Partial suits, mixed SWAT/militant sets and the patrol vest grant no pepper or baton bonus. Officers still share the same suspect's baton streak and base roll; equipment changes use current protection without resetting progress. Equipping armor does not clear pepper effects from an earlier unprotected hit.

Each tactical piece or patrol vest subtracts 1% of base movement speed while worn (4% for a full suit). Health maintains its own transient attribute modifier; equipment swaps and removal update it on the next server tick, without replacing other speed modifiers. The penalty is removed on logout and module shutdown. A full matching suit also costs one extra stamina point per sprint simulation cycle, in addition to stamina.sprint-cost-per-second. At the default one-second cycle that is 8 instead of 7 points. Partial/mixed suits and the patrol vest add no sprint cost; normal disabled/creative/stamina-bypass exemptions remain.

HealthApi.armorProfile(player) is a main-thread equipment snapshot for Justice and other modules. Its default is unarmored when the provider has no armor data.

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 and baton incapacitation do not mark a player medically unconscious; pepper spray impairs vision, movement and aim without incapacitation. 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.

Agriculture meal integration

Agriculture submits one nutrient profile per successfully consumed serving through HealthApi. A profile contains fractional ingredient groups summing to one and a bounded food-quality value. Existing single-category food history remains readable without resetting players. Recent nutrient shares determine diversity credit: token additions and renamed meat dishes cannot generate full balance. Nutrition remains 65% average quality and 35% balance, blended gradually. Grain/protein concentration still contributes to the existing risk model. Sprint fitness gains scale with nutrition; meals do not directly grant fitness or stack effects. Agriculture-owned food is excluded from vanilla material tracking so it is counted exactly once. Existing hydration, downed restrictions, stamina exhaustion and medical food triggers remain active.

Oraxen Atlas download troubleshooting

The Oraxen asset ZIP is an installer bundle. Merge its Oraxen/pack/ payload into plugins/Oraxen/pack/; do not send the installer ZIP as a client pack. Keep all unrelated custom server assets. A direct client ZIP needs pack.mcmeta and assets/ at its root. The compact patrol vest uses five small native item/model, equipment and texture files; it does not require a custom armor shader.

When players cannot download the pack, record the installed Oraxen version, client Minecraft version, Oraxen generation/upload error and the affected client's latest.log error. Distinguish an HTTP/download/hash failure from a successful download followed by a resource reload error. Do not assume cached players prove that the current upload is healthy. Keep private Atlas URL query strings and credentials out of public reports.

On the server, rebuild with /oraxen reload pack, confirm upload success, and resend using /oraxen pack send <player> (syntax depends on the installed version). Compare the exact generated client ZIP with the bytes downloaded from its advertised Atlas URL: the request must return ZIP data, and its SHA-1 must match the pack hash sent to the client. A host error page, stale upload or hash mismatch needs delivery repair, not removal of armor assets. If HTTP delivery succeeds, test that exact ZIP as a local resource pack on the affected Minecraft version and inspect resource reload errors for missing assets or incompatible formats. Preserve the old working pack while investigating; do not change hosting providers or clear everyone's cache as an unverified fix.

See Oraxen's command reference and pack hosting guide. Live Atlas delivery must be verified against the server's generated ZIP and client logs; validating a suite archive alone cannot establish that the hosted download works.

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 xray Alex; /medical surgery Alex; /health clear Alex post_mortem_trauma Staff treatment. All medical commands require an in-game responder. X-ray scans require WorldGuard and /rg flag xray_room health-xray allow; ordinary sample analyzers retain their independent item interaction. 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.