Raid Protection 3.4.16

The ultimate base protection plugin that allows players to pay a resource in exchange for configurable protection for their base or tugboat. 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.

Disclaimer

This plugin will be updated at the owners discretion. Before purchasing any plugin, I recommend checking the date of the last update and refer to support tickets to see if there might be any issues with the latest Rust game version. If a game update breaks this plugin, please open a support ticket (if it doesn't already exist) and direct message me on Discord (link found below).

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
  • Provides free raid protection for all players with the level 1 permission
  • Protection for tugboat bases
  • Recommended for PvE or light PvP servers
• Offline Only
  • 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)
  • Protection for tugboat bases
  • Recommended for PvP servers
• Hardcore
  • 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
  • No protection for tugboat bases
  • 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.

As of v3.4.0 you no longer need to delete your config files when upgrading from a previous version. However, you still should check the config after the update is installed to verify no unintended changes have occurred.

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.
• Damage resets timer when owner is offline  - If this is set to true, then if a raid has already started on a structure that has offline only protection, but the protection hasn't kicked in yet (due to a delay timer) then the attackers can continue to raid indefinitely as long as they continue to do damage while the owner(s) are offline. If this is set to false, then the attackers will only have a certain amount of time to continue their raid if the owner(s) are offline.
• Allow tugboat protection  - If this is set to true, then players with this protection level may receive protection for tugboat bases. For these tugboat bases the protection panel can be accessed in the fuel inventory of the boat. The founder of a tugboat base is whomever is the FIRST player to authorize on a tugboat.
• Founder Limit  - The number of tool cupboards that a player can be a Founder of and receive raid protection. If a player exceeds this limit, then future tool cupboards will not receive protection until enough previously placed ones have been destroyed in order to be within the limit. If a player places a tool cupboard, and they have exceeded the limit, once they are no longer exceeding the limit they can "activate" that tool cupboard in the info panel to have it gain raid protection. If this value is set to null then there is no limit.

 

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.

For tugboat bases, the founder is whomever is the first player to authorize themselves on the tugboat.

 

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)
• raidprotection.ignore - raid protection will not count any player with this permission towards being an owner. They will not show up in the owner list and will not count toward team member count for offline protection. They also will not receive protection on bases they build even if they have a protection level assigned. This is useful for admin groups so that you don't have to remember to deauth on tool cupboards. However, if this permission is ever revoked, that player will be retroactively counted as an owner on ALL tool cupboards they are currently authed on.

 

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.
• Protection Tabs Offset  - This value will adjust the vertical placement of the Protection Tabs in the tool cupboard menu. Positive values will move it up, negative values will move it down. Useful for making it so those tabs don't conflict with other UI plugins that use that area.
• 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. If you want it to be a custom item that has a skin, you can put # followed by the skin id after the item name. For example "scrap#12345" would only accept scrap items with the skin 12345.
  • 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.
  • Protect twig  - If set to true, then twig building blocks will receive raid protection. If set to false, then twig building blocks will not receive raid protection, even if placed by an owner of the base.

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.

As of v3.2.3 you can also mass restore all tool cupboards to a specific time or date.

For example, using the ledger file listed above, if we wanted to rollback the tool cupboard to the time 16:19:00. We could run the following command.
 

/tc ledger rollback 16:19

This will rollback ALL TOOL CUPBOARDS to the first ledger entry that comes BEFORE the given time.   In this case that entry would be GUID=5c83390e-bbd2-4049-8ec9-8f2951746159 at time 16:18:28 because that is the latest entry before 16:19:00. Thus the balance will be 0.

Rollbacks can also accept a date in addition to a time. For example, if you wanted to rollback to noon the following day you could run the following command.
 

/tc ledger rollback "5/25/2023 12:00"

Notice that there is no ledger entry for this tool cupboard that goes back that far. In this case, the balance of the cupboard will be set to ZERO. Please note that if you include a date and time the value MUST be enclosed in quotes (see the example above).

Tugboat Bases

As of v3.3.0, Raid Protection can optionally be allowed for tugboat bases. This is configurable per protection level. Tugboat bases can utilize all the features of a normal tool cupboard base. You can access the protection panel for tugboat bases in the fuel inventory in the drivers seat. For tugboat bases, the founder of the base is considered to be the FIRST player to authorize on the tugboat.

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.

Simple Status

Simple Status is a plugin that is still being developed, and will be an alternative, more performance friendly option to Custom Status Framework. This plugin is not yet available, but as of v3.4.0, configuration options have been added to support this plugin when it releases.

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.

Raidable Bases

Bases spawned by Raidable Bases will be ignored by Raid Protection. They should not show up in ledgers and players cannot add balance to them.

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

If you experience any issues with the default images provided by this plugin I recommend hosting them yourself. The urls can be changed in the config. Here is a zip file containing all the images.
icons.zip

Carbon

As of 8/19/2023 I can confirm that this plugin is compatible with Carbon. Please open a support ticket if you experience any Carbon related issues.

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.