Raid Protection 3.2.0

The ultimate base protection plugin that allows players to pay a resource in exchange for configurable protection for their base. This plugin has been rewritten from the ground up for performance, quality, and integrating community suggested features.

 

Features

 

There are many different ways you can configure this plugin to fit the needs of your server. Many features can be modified or disabled entirely through the plugin configuration file. These include:

• Both online and/or offline base protection
• Trade currency for protection or provide it for free
• Players can turn on/off protection
• Permission based protection tiers
• Configure what gets protected and who it is protected from
• Set limits on how long protection lasts
• Indicator(s) for displaying base protection
• Option for allowing raiders to bypass protection if they can drain the protection balance with damage
• Options for making protection more expensive for larger bases/clans and cheaper for small groups.
• UI that blends in seamlessly with vanilla Rust.

 

How to Use

1. Configure the plugin and load it
2. Once loaded, assign yourself (or your group) one of the protection level permissions.
3. Place a new tool cupboard, or find one that YOU have previously placed.
4. Open the tool cupboard inventory, at the top you should see two tabs: "Upkeep" and "Protection". Select the protection tab to view the raid protection info.
5. On this screen, you will be able to spend the configured currency in order to purchase hours of protection. By default, this currency is scrap.
6. Use the buttons on the right to add some hours of protection, you should see that status change to show the time you are protected.
7. Your base will now be protected for the amount of time specified.

Notes

• You can use the Clear button to withdraw all balance, and stop protection
• The Pause/Resume button can be used to start/stop protection without changing the balance.
• The Info button will reveal a panel which displays additional information on protection.
• The +Max button will deposit the maximum amount of time that you can afford

 

Quick Start Presets

There is a lot of documentation for this plugin because there is a lot you can do with it! However, it doesn't have to be complicated. If you have a simple use case in mind, you can use one of these preset configurations to get what you need or use as a starting point without having to figure it out yourself!

Important: You will want to assign your default permission group the raidprotection.level.1 permission for any of these configurations.

• Always Free Config
  • Provides free raid protection for all players with the level 1 permission
  • Recommended for PvE or light PvP servers
• Offline Only Offline
  • Same as the default config, but only offers offline protection
  • Has a limit of 48 hours of protection for level 1
  • Includes a level 2 permission with unlimited hours of protection (VIP)
  • Recommended for PvP servers
• Hardcore Config
  • Offline only protection
  • Two protection levels, one with a 48 hour limit and one with no limit
  • Additional costs that scale with number of owners and building size
  • Raiders can damage a structure and cause it to "bleed" protection balance to attempt to disable the protection with enough damage
  • Significant delay for activating protection
  • Recommended for hardcore PvP servers

Upgrading Versions

When a new version is released, you may need delete your config and lang files and reload them to accommodate the new changes. You do NOT need to delete the data file, unless specifically instructed. As long as you do not delete the data file, then all of your protection balances will persist, even between versions. Not all updates will require this process, but if it does, you will be notified with a message like this:

To resolve this, simply delete the config and lang files and reload the plugin. You will need to manually update these files to align with what you want.

Protection Levels

Protection levels are how you assign a particular set of rules to a player. These protection levels are added in the configuration file, and are then assigned to an auto-generated permission.

Each protection level needs a unique Rank property, this rank determines the order of precedence when a player is assigned multiple protection levels. In this event, a player's protection level will always be the highest ranked protection level they are granted.

Protection levels are managed in the configuration file, here is some information on some of the properties:

• Cost per damage protected  - This amount will be deducted from the protection balance for each point of damage that was protected. So if this value is set to 1 and someone attempts to deal 100 damage to a protected structure, and that structure has 100% protection, then 100 balance will be deducted. If in that same example it was only 50% protection, then only 50 balance would be deducted. Entity resistances are taken into account as well (twig will take more damage than metal, ect).
• Hourly base cost - This is a fixed cost that is charged per hour of protection.
• Hourly cost per authorized player - This amount will be charged for each owner every hour. Can be used to charge players more if they have a larger clan.
• Hourly cost per floor - This amount will be charged for each floor every hour. Can be used to charge players more for protecting a larger base.
• Max protection time - The max number of hours protection can be applied for. If set to null, then there will be no limit.
• Offline protection percent - The percent of protection a structure will receive when all the owners are offline. A value of 0 will be unprotected, and a value of 100 will be fully protected.
• Online protection percent - The percent of protection a structure will receive when at least one owner is online. A value of 0 will be unprotected, and a value of 100 will be fully protected.
• Rank - A number value indicating the order of importance when a player is assigned multiple protection ranks. Higher values indicate a greater importance. For example, if a player is assigned both protection rank 1 and protection rank 2, then tool cupboards they place will be of protection rank 2 instead of 1.  These ranks must be unique DO NOT create protection levels with the same rank. This value needs to be 1 or higher, it cannot be 0.
• Delay after taking damage - The number of seconds before protection may begin after a structure has taken unprotected damage. It is recommended to set this to a higher amount on PvP servers.
• Delay for offline protection - The number of seconds before offline protection kicks in after the last owner has gone offline. It is recommended to set this to a higher amount on PvP servers.

 

Founders and Owners

When a tool cupboard is placed, the player who places it is permanently labeled as the "Founder" of that tool cupboard and building privilege. The protection level of that building privilege is derived soley from the founder's protection level, and therefore won't change unless the founder's protection level changes.

Whenever a player is authorized on a tool cupboard, they will be permanently branded as an "Owner" of that tool cupboard. Owners are all the players, including the founder, who have EVER been authorized on the tool cupboard. This means that players will still be listed as an owner even if they deauthorize themselves. Owners are important because they affect how Online/Offline protection will be triggered. A base will only be granted offline protection if ALL the owners are offline, otherwise online protection (if available) will be granted if at least one owner is online.

 

Permissions

• raidprotection.admin
• raidprotection.level.x - these permissions are autogenerated based on your protection level settings in the config, they will show up in the server console when the plugin is loaded (unless you have Enable Console Messages set to false)

 

Commands

Player Commands

These commands require no permissions and can be used by any player.

• /pro - displays the raid protection information panel, requires authorization on the tool cupboard in the current area.
• /lev - displays a screen that tells the player their personal assigned protection level and explains the benefits that comes with it.

Admin Commands

These commands require the raidprotection.admin permission to use.

• /tc - displays a screen with all the available admin commands
• /tc help - same as /tc
• Use the above commands to see a full command list in game.

 

Configuration

The default config file: 
Here is an explanation for some of the fields:

• Enable Logging - Set to true to keep logs of tool cupboards protection activity. Logs will be saved to the oxide/logs/RaidProtection folder.  It is recommended only to enable this only for debugging purposes, as it will take a significant amount of storage space if you have a larger server.
• Enable Ledger - Set to true to keep track of protection balance changes for tool cupboard. These ledger files are stored in oxide/data/RaidProtection/Ledgers. It is recommended to keep this enabled, as it will help you roll back balances if a player has an issue. This does not take up as much storage space as logging does as it only keeps track of balances.
• Enable Console Messages - Set to false to disable the info messages upon plugin reload.
• Commands - You can change the prefix for the commands this plugin uses here.
• Chat Message Icon ID - A steam id for the portrait of chat messages.
• Image Settings - Links for the images the plugin uses.
• Indicator Settings - Settings for the indicator that (by default) appears in the top right when you attack a protected structure. You can change its size and position or disable it.
• Plugin Integration - Set any of these to true if you want this plugin to take advantage of the features of another supported plugin.
• Custom Status Framework Settings (Ignore if you do not have Custom Status Framework integration enabled)
  • Popup Attack Indicator - If set to true, a status will briefly appear when a player attacks a protected structure.
  • Persistent Status For Owners - If set to true, a status will appear while a player is in a protected area that they are an owner for. Slight performance cost when enabled.
  • Persistent Status For Non Owners - If set to true, a status will appear while a player is in a protected area that they are NOT an owner for. Slight performance cost when enabled.
  • Popup Status When Hammer Equipped - If set to true, a status indicating the protection level of the area they are in will appear while they are holding a hammer. This will appear regardless of if you are an owner of that area or not.
• Protection Settings
  • Admin owners removed when deauthorized - Normally, you cannot remove an owner even if they deauthorize. But if this setting is enabled, it allows admins to remove themselves as owners when they deauthorize from a tool cupboard. They can also achieve this with commands.
  • Allow balance withdraw - If set to true, then players will see a "Clear" button in the tool cupboard panel that allows them to withdraw any protection balance.
  • Allow max deposit - If set to true, there will be a "+Max" button that will purchase the maximum number of protection hours a player can afford.
  • Award remaining balance when cupboard is destroyed - If set to true, whomever destroys a tool cupboard will be awarded whatever amount was in the protection balance.
  • Currency item - The item that will be used as currency for protection, this will only be overridden if you are using Server Rewards or Economics for your currency.
  • Protected entities - If any of these are set to true, then that type of entity will be covered under Raid Protection. If you are using other protection plugins like TruePvE, then you will want to configure these to not overlap with what other plugins are protecting.
  • Protected from - If these are set to true, then damage from that type of source will be protected. By default Authed Players is set to false, which means that players will be able to damage their own structures, but enemy players cannot.
  • Protection levels - See the section about protection levels for information.

Ledgers

As of Raid Protection v3.2.0, you can optionally configure ledgers to be enabled. When enabled, the plugin will keep logs protection balance changes for all tool cupboards. These logs will be saved to oxide/data/RaidProtection/Ledgers. There is a ledger file for each tool cupboard, and it's filename will make the entity ID of that tool cupboard. You can use the /tc id command to see what the ID of a tool cupboard is (see commands section). The benefit of ledgers is that each balance change has a specific GUID identifier attached to it that can be used to restore a tool cupboard's balance to that exact state in the event that a player has an issue. An example of a ledger file might look like this:

Ledger file for tool cupboard with ID 2250729

[
  "05/26/2023 16:17:56,ad87f16e-52eb-4689-887f-ecc53cd3ff13,0,Withdraw",
  "05/26/2023 16:18:20,108e54c0-98c4-46df-9eb3-e17192c37bb3,0,CollectionStopped",
  "05/26/2023 16:18:23,a2f03162-200c-47ce-948e-b0c703435e51,0,CollectionStarted",
  "05/26/2023 16:18:28,5c83390e-bbd2-4049-8ec9-8f2951746159,0,Withdraw",
  "05/26/2023 16:19:29,cd892a3f-249b-4cad-8949-abf904656288,20,Added",
  "05/26/2023 16:19:31,6e710dfc-23c2-4375-8c4f-07017d4d44c6,40,Added",
  "05/26/2023 16:19:31,bc51f8c7-3f3a-4abc-8fd2-8bb4c47fe454,60,Added",
  "05/26/2023 16:20:25,f08cfa34-a623-4de3-9027-7c3acb3e3ec3,60,CollectionStarted",
  "05/26/2023 16:20:52,a849be59-899c-4779-bba6-2f5f1b0ffb8d,59.93055,CollectionStopped"
]

The format of each row goes as follows, from left to right separated by commands.

• Date and Time of balance activity
• GUID identifier, used by the /tc restore command to roll back a balance
• The protection balance of the tool cupboard at that given time
• A brief descriptive reason as to what changed about that balance

For example, using the ledger file listed above, if we wanted to rollback the tool cupboard to before the collection started (the last "Added" one), we could run the following command.

/tc restore 2250729 bc51f8c7-3f3a-4abc-8fd2-8bb4c47fe454

Running this command will set the balance of the tool cupboard with ID 2250729 back to its balance of 60.

Plugin Integration

Clans

This plugin provides built-in support for Clans. If a player is in a Clan, it will automatically treat all clan members as owners. This of course means that the owners will not be removed even when a member is kicked from a clan.

True PVE

This plugin is compatible with True PVE as long as both plugins are configured in a non-conflicting way. For example, if you use True PVE to provide protection to players, then in your Raid Protection config file under the Protected entities section you should set Authed Players and Unauthed Players both to false to avoid hook conflict errors. If you do see hook conflicts, see the section of this documentation about how to resolve hook conflict errors.

Zone Manager

This plugin is compatible with ZoneManager without any extra configuration. ZoneManager will take priority if the zone has the "undestr" flag.

Custom Status Framework

If you have CustomStatusFramework installed and want to take advantage of the status indicators (that appear in the bottom right) in your Raid Protection config file under the Plugin Integration section set Custom Status Framework to true.

Preview of indicators:

 

Economics and Server Rewards

If you wish to use economics balance or server rewards points as a currency instead of an item, you can set ONE of these to true in the plugin integration section of the config. It is important to set ONLY ONE of these to true, or else both will be disabled and you will get a warning in the console.

Protection panel with Economics:

NoDecay

This plugin is compatible with NoDecay without any extra configuration.

Notify

If you want to use Notify as your source of indicators you can enable the flag for it in the Raid Protection config.

Abandoned Bases

If you enable Abandoned Bases in the integration config, then bases that are labeled as Abandoned will not receive raid protection.

Skill Tree

If Skill Tree is enabled in the integration config then it will prevent players with the lockpicking skill from picking locks in raid protected areas.

Other Plugins

Should be compatible with most other plugins given they don't use the onEntityTakeDamage hook. If they do use this hook, it just means you have to change your configuration settings, see the hook conflicts section for more info.

Images

By default, all my images I use in this plugin are hosted on imgur. The problem with imgur is that it can only handle so many requests at once, so sometimes you might see an error in your console like:

Error: HTTP/1.1 429 Too Many Requests

To avoid this, I recommend hosting the images yourself, all the links are available in the config file.

 

Hook Conflicts

If you're getting messages in the server console that looks similar to this:

OnEntityTakeDamage resulted in a conflict between the following plugins: NoDecay - True (Boolean), RaidProtection (False (Boolean))

That means that another plugin is conflicting with Raid Protection. In most cases this is an easy fix, and it just means that you need to update your Raid Protection config file to not protect the same entities that another plugin is already protecting. So for example, if you have a plugin already that makes it so player's cannot attack each other, then there is no need for Raid Protection to do that job, and therefore in the Protected entities section of the config you should set Authed players and Unauthed players to false to avoid conflicts.

Previous Versions

You may have seen the free version of this plugin available on uMod. That version (2.X.X) will stay available for free on umod, but is no longer supported.

If you are upgrading from the free version, you must first delete the config/lang/data files before installing v3.0.0 and above. If you do not delete these files, you will likely run into issues, as despite having the same name, the plugin has been completely rewritten, and therefore is completely incompatible with the free version.

 

Developer API

        /*
         * Returns 0 if entity unprotected and 100 if entity fully protected
         */
        private float GetProtectionPercent(BaseEntity entity)

        /*
         * Returns a list of the owners of the structure associated with the given entity
         */
        private List<BasePlayer> GetOwners(BaseEntity entity)

        /*
         * Returns the player who is the founder of the structure associated with the given entity. Can be null.
         */
        private BasePlayer GetFounder(BaseEntity entity)
          
        /*
         * Returns the protection balance of the structure associated with the given entity
         */
        private float GetProtectionBalance(BaseEntity entity)
          
        /*
         * Returns the hours of protection remaining of the structure associated with the given entity
         */
        private float GetProtectionHours(BaseEntity entity)

Discord

If you want to report a bug, require support, have a suggestion or want to be notified when I release an update you can join my plugin development discord with this link:

Plugin Development Discord Link

Donate

Writing and maintaining these plugins takes a tremendous amount of work. Donating is one way to give some positive feedback which helps me continue making them!
Buy me a coffee here!

 

FAQ

Please check out this section before opening a support ticket, it may save us both some time!

Q: I don't see the status indicators in the bottom right.

A: The status indicators come from another plugin called CustomStatusFramework, you must install it and enable it in the config file to get the indicators.

Q: I have protection time, but I am able to damage my own structure.

By default "Authed players" are able to damage their own structures. You can change this in the config file.

Q: The add hours buttons aren't showing for me in the tool cupboard panel.

A: The hours buttons will not show if the protection has 0 cost.

Q: I have a max protection time set, but it says "protected for forever"

A: If the protection cost is 0, then there cannot be a max protection time.

Q: I deauthorized myself from the tool cupboard, but I am still listed as an owner.

A: Owners are not removed after deauthorization. Only admins can remove owners.

Q: How are overlapping tool cupboards handled?

A: If a player has a base with overlapping tool cupboards, then each cupboard will need its own protection. Which entities are protected depend upon which tool cupboard governs that entity.

Q: Can player's exploit offline only protection by deauthorizing?

A:Deauthorizing will not help players looking to exploit offline only protection because they will still be considered an Owner even if they deauthorize.

Q: Can a player exploit offline only protection by never authorizing?

A: If a player is never authorized on a cupboard, then they will not count toward being online, and therefore offline protection can occur. However, players cannot add or manage protection balance unless they are authorized, and therefore the protection balance will run out, especially if a max protection time is set.

Q: I have protection for horses on, but now the horses never poop

A: If horses don't lose health, they will never eat and therefore never poop, this is a side effect of protection for horses.

Q: Why does protection say "pending" in the bottom right?

A: Pending either means that you have offline only protection or your structure has recently taken damage and therefore protection is delayed. See the tool cupboard protection panel for more info.

Q: I'm seeing conflict warnings in my console between Raid Protection and True PvE

A: Please refer to the sections of documentation for TruePvE and Hook Conflicts

Q: I'm seeing Image failed to download! Error: HTTP/1.1 429 Too Many Requests

A: Refer to the Images section of the documentation.