mr01sam
Adds fully customizable diseases to Rust for tormenting your players with outbreaks

Supported Games
works with

Update: I created a Master List for the community to share their custom made disease files. If you are a server admin looking for a pre-made, tested, and balanced disease or if you have a disease file you made and want to share, head on over to this link here and check out the list!

Features

  • Fully Customizable Diseases
    • Every factor of a disease is customizable
    • Import a disease from the community or easily create your own
  • Spreads Between Players
    • Diseases can spread realistically between players through a variety of different ways
    • Masks and face coverings can be configured to resist infection from spreading
  • Launch Outbreaks
    • Diseases can be spread from infected players, but they can also be configured to spontaneously infect random players who qualify
    • Outbreaks can be trigger automatically at a set interval or manually with console commands
  • Become a Doctor
    • There are ways to fight back the impending pandemic. Cures and treament options can be made available, and those that know of these options can provide care to others.
    • Items can be set to be "cure items" that will instantly relieve players of symptoms, and give them immunity to further infection for some time.
    • Other items can be "treament items" that will accelerate recovery from a disease.
  • Balance It How You Like
    • Whether you want just one disease thats a minor inconvenience, or a dozen of deadly viruses is up to you.
    • You can change and tweak all the settings to make this plugin work for your server

FAQ


  • What does this plugin do?
    • This plugin adds customizable diseases to the game that can infect players through a variety of methods and provide some sort of debuff for a set amount of time.

  • How do players get infected?
    • It depends on the disease, but players can become infected through the following ways:
      • Spreading from other infected players
      • Using an item (such as a particular food) that causes infection
      • Becoming infected from a random event (called an outbreak)
      • Being hit by an entity or player that causes infected

  • How do infected players get cured?
    • Once again it depends on the disease, but in general these are the following ways a player can be cured:
      • Simply waiting it out, diseases have a set time range they can infect a player for. Once this time range is met, the player will become "Immune". Meaning that they technically still have the disease, but will not have symptoms and cannot spread it to other players.
      • Using a "cure item" which has a chance to instantly cause the player to skip to the immune state.
      • Using a "treatment item" which will speed up recovery of the disease by a set amount of time.
      • When a player dies while infected, they will spawn without the disease.

  • Can non-player entities become infected?
    • As of v2.0.0, non-player entities technically cannot become infected. This way done as a way to increase performance and to shift the focus to the players. That being said, entities can be specified to inflict the disease on players, even though they don't technically carry it themselves.

  • What is an 'Outbreak'?
    • Outbreaks are a term used to describe random events that occur peroidcally to randomly infect players will a disease. Outbreaks are typically meant to be infrequent and their primary purpose it to start spreading a disease across the server.

  • How do I add custom diseases?
    • Once you install the plugin on your server a new file called Norovirus.json will be created in the */oxide/data/Diseases/ directory. This file is simply an example that you can use to create your own disease. See the Customization section of this documentation for more information.

  • How do I import a disease that someone else made?
    • All you have to do to import a community made disease is to place the .json file in the */oxide/data/Diseases/ directory. You can then add the disease name to the Loaded diseases on startup list located in the configuration file or use the in game chat command /disease load <disease> to load the disease.

Installation & Updates

Updating the Plugin

When a new version of this plugin is released there may be significant changes to the config file, language file, or diseases data files. To avoid errors you will want to make sure to verify these files are in the correct format:

  • The files in oxide/data/Diseases/ likely will be out of date with a new release. It is recommended you remove all files from this directory and make sure Generate default disease (true/false) is set to true, then reload the plugin. This will load the default disease file Norovirus.json, you can use this as a template to update your previous disease files. Attempting to load an outdated disease file will give you errors on initialization.
  • An outdated config file located in oxide.config/Diseases.json likely won't give you errors, but it may have unexpected settings if not properly updated. You should make a copy of your previous config file, remove it from the directory, reload the plugin, then change the parameters of the newly generated config to your preferences.
  • The language file is updated infrequently, but it is recommended that you also delete this file & reload the plugin after a new version to make sure you have the most up to date messages.
Disease File Updates

Disease file updates occur only on Major and Minor updates. Patch updates will not require you to update your disease file (though it is recommended you change the Version attribute).


  • v2.1.0
    • Changed property name from "Spread distance (1.0 = 4ft)" to "Spread distance (4.0 = 1 foundation)" to accurately reflect the distance.
    • Make sure to update your old disease files to reflect this change.

Permissions

  • diseases.use -- Required to become infected and utilize user commands
  • diseases.admin -- Allows use of the admin commands

Commands

User Commands
  • /disease help
    • Shows a list of all commands available to the player for this plugin.
  • /disease list
    • Prints a list of the names of all currenlty loaded diseases.
  • /disease info <disease>
    • Provides a brief description of the specified disease.
  • /disease stats <disease>
    • Shows stats pertaining to the specified disease.
Admin Commands
  • /disease infect <player> <disease>
    • Infects if the player with the given disease if they are elligible.
  • /disease cure <player> <disease>
    • Instantly cures the player from the disease without providing immunity.
  • /disease outbreak <disease> <attempts?>
    • Starts an outbreak with the given disease, the outbreak will be constrained to only elligible players based on the disease file.
    • You can optionally specify a number of attempts, for example if given the value 5 it will attempt an outbreak 5 times.
  • /disease eradicate <disease>
    • Cures all currently infected players of the disease.
  • /disease config <disease>
    • Prints the disease config file to the screen (useful for debugging a custom disease).
  • /disease load <disease>
    • Loads a disease file with the same name located in the */oxide/data/Diseases/ directory.
  • /disease unload <disease>
    • Unloads a currently loaded disease.

Note:/disease infect, /disease cure, /disease outbreak, and /disease eradicate can all also be called without the /disease prefix as /infect, /cure, /outbreak and /eradicate.

Configuration

{
  "Generate default disease (true/false)": true,
  "Loaded diseases on startup": [
    "Norovirus"
  ],
  "Max number of infected entities": 100,
  "Disease name color in messages": "green",
  "Face covering items": [
    "mask.bandana",
    "burlap.headwrap",
    "clatter.helmet",
    "coffeecan.helmet",
    "heavy.plate.helmet",
    "hazmatsuit",
    "hazmatsuit.spacesuit",
    "metal.facemask",
    "halloween.surgeonsuit"
  ],
  "Show status chat messages": true,
  "Infections can spread in safe zones": true,
  "Broadcast disease death messages": false,
  "Broadcast outbreaks": false,
  "HUD indicator list": {
    "Anchor min": "0.84 0.6",
    "Anchor max": "0.985 0.9",
    "Entry height": 0.1,
    "Anchor min (image)": "0.03 0.1",
    "Anchor max (image)": "0.14 0.85",
    "Show image (requires ImageLibrary)": true
  }
}
General Settings
  • Generate default disease
    • If set to true the default disease file Norovirus.json will be generated and will be generated and override any previous file of the same name.
  • Loaded diseases on startup
    • A list of diseases (by name) that will be loaded upon initialization.
    • The disease names should also be in Title Case format with spaces if necessary.
    • Additional diseases can be loaded or unloaded in game with commands (see Commands section).
  • Max number of infected entities
    • Can specify a number that will limit the amount of entities that can be infected at once by all diseases.
    • Useful for servers that want to limit resource usage, as the intensiveness scales with the number of infected players.
  • Disease name color in messages
    • The color of the disease name when it appears in chat status messages.
  • Face covering items
    • A list of items (by their shortName) that count as face covering items that reduce infection.
    • See this link for a list of shortNames for items.
  • Infections can spread in safe zones
    • If set to false then players that are in safe zones will not be able to be infected by spreading or outbreaks.
  • Broadcast disease death messages
    • If set to true then a message will be sent to all players when a player has died of a disease they are inflicted with.
  • Broadcast outbreaks
    • If set to true then a message will be sent to all players when an outbreak is occurring.
HUD Indicator Settings
  • Anchor min
    • The anchor min for the HUD indicator list.
  • Anchor max
    • The anchor max for the HUD indicator list.
  • Entry height
    • The height of each entry in the HUD indicator list.
  • Anchor min (image)
    • The anchor min for the image shown in the HUD indicator list.
  • Anchor max (image)
    • The anchor max for the image shown in the HUD indicator list.
  • Show image
    • If set to true an image will be shown on the entries.
    • This requires ImageLibrary to be installed in order to be shown.

Localization

{
  "StatusInfected": "You are infected with {0}",
  "StatusRecovered": "You have recovered from {0}",
  "StatusTreated": "You treated the {0} and will recover faster",
  "StatusCured": "You are not longer suffering from {0}",
  "StatusOutbreak": "An outbreak of {0} has started",
  "Infect": "Infected {0} with {1}",
  "NoInfect": "{0} is already infected with {1} or is immune",
  "Cure": "Cured {0} of {1}",
  "NoCure": "{0} is not infected with {0} or cannot be cured",
  "Outbreak": "Outbreak of {0} infected {1} players",
  "Eradicate": "Cured all players of {0}",
  "NoEradicate": "No players are infected with {0}",
  "Load": "Loaded disease {0}",
  "NoLoad": "Failed to load disease {0}, it is either already loaded or file is invalid",
  "Unload": "Unloaded disease {0}",
  "NoUnload": "Failed to unload disease {0}, it is not currently loaded",
  "List": "Loaded diseases: {0}",
  "NoExist": "The disease {0} is not currently loaded or doesn't exist on this server",
  "NoPlayer": "There is no active player with the name {0}",
  "StatInfected": "Players infected: {0}",
  "StatInfectedTotal": "Total players infected: {0}",
  "StatKilled": "Total players killed: {0}",
  "Death": "{0} died from {1}",
  "Invalid": "Invalid command, try /disease help for a list of commands",
  "Treated": "Treated"
}

Customization

You can create your own disease by adding a JSON file in the /oxide/data/Diseases folder and naming it what you wish. The disease Norovirus is generated by default, and you will see it in the data folder. It is recommended that you make a copy of this file and edit the parameters. NOTE: The disease name you choose must be unique and the file name must match the name specified within the file.

Here is an example of the Norovirus.json file, field definitions can be found below.

{
  "Disease name": "Norovirus",
  "Description": "Highly contagious disease that causes vomitting and is caused by eating rotten food. Can be treated with tea and cured with pills.",
  "Min time immune after recovery (seconds)": 180,
  "Max time immune after recovery (seconds)": 600,
  "Min time infected (seconds)": 180,
  "Max time infected (seconds)": 600,
  "Min time between symptoms (seconds)": 5,
  "Max time between symptoms (seconds)": 45,
  "Spread distance (4.0 = 1 foundation)": 2.0,
  "Spread chance with mask (0-100)": 0.0,
  "Spread chance without mask (0-100)": 85.0,
  "Symptom damage effects": [
    {
      "Stat name": "health",
      "Min damage": 1.0,
      "Max damage": 5.0
    },
    {
      "Stat name": "calories",
      "Min damage": 100.0,
      "Max damage": 125.0
    },
    {
      "Stat name": "hydration",
      "Min damage": 50.0,
      "Max damage": 85.0
    }
  ],
  "Items that cause infection on consumption": [
    {
      "Infection chance on consumption (0-100)": 10.0,
      "Short prefab name": "chicken.raw"
    },
    {
      "Infection chance on consumption (0-100)": 85.0,
      "Short prefab name": "chicken.spoiled"
    },
    {
      "Infection chance on consumption (0-100)": 10.0,
      "Short prefab name": "humanmeat.raw"
    },
    {
      "Infection chance on consumption (0-100)": 85.0,
      "Short prefab name": "humanmeat.spoiled"
    }
  ],
  "Items that cure on consumption": [
    {
      "Cure chance on consumption (0-100)": 50.0,
      "Short prefab name": "antiradpills"
    }
  ],
  "Items that reduce infection time on consumption": [
    {
      "Min infection time decreased (seconds)": 5,
      "Max infection time decreased (seconds)": 10,
      "Delay between reusing treament (seconds)": 10,
      "Short prefab name": "healingtea"
    },
    {
      "Min infection time decreased (seconds)": 10,
      "Max infection time decreased (seconds)": 40,
      "Delay between reusing treament (seconds)": 40,
      "Short prefab name": "healingtea.advanced"
    },
    {
      "Min infection time decreased (seconds)": 40,
      "Max infection time decreased (seconds)": 160,
      "Delay between reusing treament (seconds)": 160,
      "Short prefab name": "healingtea.pure"
    }
  ],
  "Entities that cause infection on hit": [
    {
      "Short prefab name": "boar",
      "Infection chance on hit (0-100)": 5.0
    }
  ],
  "Random outbreak settings": {
    "Outbreaks enabled": true,
    "Outbreak chance (0-100)": 25.0,
    "Time interval (seconds)": 300,
    "Only outbreak on players with the following stats": [
      {
        "Stat name": "health",
        "Min value": 0.0,
        "Max value": 50.0
      }
    ]
  },
  "Symptom effects": [
    {
      "Asset path": "assets/bundled/prefabs/fx/gestures/drink_vomit.prefab",
      "Local only": false
    },
    {
      "Asset path": "assets/bundled/prefabs/fx/water/midair_splash.prefab",
      "Local only": false
    },
    {
      "Asset path": "assets/prefabs/weapons/cake/effects/strike_screenshake.prefab",
      "Local only": true
    }
  ],
  "Symptom screen effects": [
    {
      "Sprite asset path": "assets/content/ui/overlay_poisoned.png",
      "Opacity (0-1.0)": 1.0,
      "Duration (seconds)": 1.0,
      "Fade out (seconds)": 1.0,
      "Material asset path (optional)": ""
    }
  ],
  "Version": {
    "Major": 2,
    "Minor": 1,
    "Patch": 0
  }
}
Field Definitions

  • Disease name
    • The name of the disease, must match with the file name.
    • Should be in Title Case format with spaces. e.g: "My Disease Name".

  • Min time immune after recovery
    • The minimum time (in seconds) in which you cannot be infected again after recovering

  • Max time immune after recovery
    • The maximum time (in seconds) in which you cannot be infected again after recovering

  • Min time infected
    • The minimum time (in seconds) an entity will be infected with a disease.

  • Max time infected
    • The maximum time (in seconds) an entity will be infected with a disease.

  • Min time between symptoms
    • The minimum time (in seconds) between symptoms occurring.

  • Max time between symptoms
    • The maximum time (in seconds) between symptoms occurring.

  • Spread distance
    • The distance at which an entity can become infected by spreading from an already infected entity.
    • For reference, 4.0 is about 1 foundation block, 8.0 is 2 foundation blocks, 16.0 is 4 foundations, ect...

  • Spread chance with mask
    • The chance of an infection spreading to an entity who is wearing face covering gear (defined in the configuration file).

  • Spread chance without mask
    • The chance of an infection spreading to an entity who is NOT wearing face covering gear.

  • Symptom damage effects
    • A list of damage effects that are applied every time a symptom occurs.
    • The following values can be specified for each item in the list:
    • Stat name
      • The stat that the damage is applied to
      • Valid values are: health, bleeding, calories, hydration, oxygen, radiation, temperature, or poison.
    • Min damage
      • The minimum value for the damage that will be applied
    • Max damage
      • The maximum value for the damage that will be applied
      • The damage will be randomly selected between the Min and Max values

  • Items that cause infection on consumption
    • Infection chance on consumption
      • The percent change from 0-100 of this item causing infection upon consumption.
    • Short prefab name
      • The shortName of the item.
      • See this link for a list of shortNames for items.

  • Items that cure on consumption
    • Cure chance on consumption
      • The percent change from 0-100 of this item will cure this disease on consumption.
    • Short prefab name
      • The shortName of the item.
      • See this link for a list of shortNames for items.

  • Items that reduce infection on consumption
    • Min infection time decreased
      • The min amount of time (in seconds) that recovery of the disease will be sped up by.
    • Max infection time decreased
      • The max amount of time (in seconds) that recovery of the disease will be sped up by.
      • The time of recovery will be a random value between the min and max value.
    • Delay between reusing treament
      • The time delay (in seconds) before a treament item can be used again to reduce infection time.
    • Short prefab name
      • The shortName of the item.
      • See this link for a list of shortNames for items.

  • Entities that cause infection on hit
  • Short prefab name* The shortName of the entity that can cause infection when attacking a player.* See this link for a list of shortNames for entities.
  • Infection chance on hit* The percent chance that an entity will cause infection when damaing a player.

  • Random outbreak settings
    • Settings for how random outbreaks are handled for this disease.
    • Outbreaks enabled
      • If set to true then a single random eligible player has a chance to be infected every time an outbreak occurs.
      • If set to false no outbreaks will occur randomly for this disease.
    • Outbreak chance
      • The percent value from 0-100 of an outbreak infecting a single randomy selected elligble player.
    • Time interval
      • The time in seconds that the game has a chance to infect a randomly selected elligible player.
      • It is recommended that this value be a long time (several minutes) to reduce lag and be balanced.
    • Only outbreak on players with the following stats
      • These conditions will limit the elligible players by the following constraints based on stats.
      • Stat name
        • The stat of the player to limit by
        • Valid values are: health, bleeding, calories, hydration, oxygen, radiation, temperature, or poison.
      • Min value
        • The minimum value of the player stat.
      • Max value
        • The maximum value of the player stat.
        • Only players with stats between the two values will be considered elligible.

  • Symptom effects
    • A list of effects that can be applied to players when a symptom occurs.
    • The following values can be used to customize the effect:
    • Asset path
      • The path string of the effect to be displayed.
      • See this link for a list of asset paths for effects.
    • Local only
      • If set to true then this effect will only be shown to the player it is applied to. Other players will not be able to see or hear the effect.
      • It is very important to set this to true for certain effects such as shaking, or else it will be applied to every player on the server!

  • Symptom screen effects
    • A list of images and overlays that can be applied to players when a symptom occurs.
    • The following values can be used to customize the overlay effect:
    • Sprite asset path
      • The path to the image file that will be displayed.
      • See this link for a list of image paths for screen effects.
    • Opacity
      • The opacity of the image shown, should be a decimal value from 0-1.0.
  • Duration
    • Duration in seconds that the image will be shown for, can be a decimal value greater than 0.
  • Fade out
    • Duration in seconds that a image will gradually fade out after expiring, can be a decimal value greater than 0.
  • Material asset path (optional)
    • Can specify a material texture that will be applied to the image
    • See this link for a list of image paths for the material.

Note: Make sure to ALWAYS update your disease data file when updating to a new version. If your disease file is invalid or out of date, you will receive errors.

Helpful Links

Donate

I make plugins for free, but donating keeps me motivated and is a great way to show appreciation if you use this plugin a lot. Totally optional, but if you're interested you can buy me a coffee with this link.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.