NextGenPVE 1.3.7

Selectively prevents damage to players and objects in a PVE environment

Uses ZoneManager, Friends, Clans, RustIO, GUIAnnouncements

Works with DynamicPVP, HumanNPC (from remod.org), ZombieHorde, SAM Targeting, BotSpawn, et al.

Don't let the documentation trouble you.  In most cases all you should need to do is install the plugin.  The rest is optional.

 

NOTE FOR GINGERBREADNPC: Due to a section of code being commented out, the admin may need to run /pveupdate to add the GingerbreadNPC as a viable target (December 15, 2022).  The other reason for this is that they appeared mid-wipe.

 

NEW FOR 1.2.8: New purge options available only in the config (no GUI yet).  See below.

NEW FOR 1.1.0: New Schedule GUI for selecting day(s) and start and end times.  Can select all days or none.  Defaults (with useSchedule set to true) are now *;0:00;23:59 meaning always active.

NEW FOR 1.0.52: Custom rule and entity collection editor - You must set AllowCustomEdit true in the configuration to enable this feature.  To go along with this, new entity types will be detected at wipe and should be available to set into existing or new collections for inclusion in rulesets.

EXAMPLE: Creating your own rules:

EXAMPLE: Manage new entities yourself, or reassign existing ones:

Overview

NextGenPVE is a new plugin and not a fork of TruePVE, et al.  It includes an integrated GUI for ruleset management.

NextGenPVE is organized into entity collections, rules that use those collections, and rulesets that include a set of rules.

Each ruleset has a default damage value of true or false.

Each ruleset may include a list of rules which override the default setting called exceptions.

Each ruleset may include a list of exclusions to the exceptions that override those exceptions.

Each ruleset can and probably should be associated with a zone (if not the default ruleset).

Each ruleset can be either enabled or disabled.

The default ruleset (out of the box) has the following settings:

• Default damage false
• Exceptions:
  • animal can damage animal
  • animal can damage player
  • fire can damage building
  • fire can damage player
  • fire can damage resource
  • helicopter can damage building
  • helicopter can damage helicopter (for debris, etc.)
  • helicopter can damage player
  • npc can damage player
  • npc turret can damage animal
  • npc turret can damage npc
  • npc turret can damage player
  • player can damage animal
  • player can damage building (their own or a friend's)
  • player can damage helicopter
  • player can damage minicopter
  • player can damage npc
  • player can damage plant (Growable Entity)
  • player can damage resource
  • player can damage scrapcopter
  • player can damage vehicle
  • resource can damage player
  • scrapcopter can damage player
  • trap can damage trap
  • elevator can damage (crush) player
• Exclusions: NONE (Could be chicken, bear, HumanNPC, etc.)

There is an integrated GUI for the admin to use to:

• Enable/disable NextGenPVE
• Create or delete rulesets
• Enable or disable rulesets
• Set the default damage for a ruleset
• Add rules for exceptions to the default damage setting of a ruleset
• Add exclusions for the rules
• Set the zone enabling activation of a ruleset
• Set a schedule for ruleset enable/disable (NEEDS IMPROVEMENT)
  • Schedules consist of the following simple format.  A schedule (currently one per ruleset) determines when the ruleset is active.  If not set, it is always active.
    • FORMAT: DAYOFWEEK_OR_*;START:TIME;END:TIME
    • 1;1:00:21:00 == Monday between 1AM local time and 9PM local time
    • *;4:00;15:00 == Every day between 4AM and 3PM
  • The schedule can be inverted such that the period entered would disable the ruleset rather than enable it.
• Set global flags.

 

Commands

The following commands have been implemented:

• `/pverule` - Starts the GUI for editing, creating, and deleting rulesets
• `/pveenable` - Toggles the enabled status of the plugin
• `/pvedebug` - Toggles HEAVY debugging of attacker/target and some other data to oxide log and rcon.  There is also an associated option 'debug' which is toggled by this command.  This is mostly useless debug info but allows for tracking of what part of the plugin activity may have failed or cause an NRE, etc.  pvelog is going to be more useful in almost every case.
• `/pvelog` - Toggles the creation of a log file to monitor ruleset evaluation.  This will severely impact performance and so should be used sparingly.
• `/pvebackup` - Creates a database backup copy in the plugin oxide data folder.
  • This could be used, for example, in timed plugins or scripts to create periodic backups.
  • It might also be used prior to making major changes that go wrong (for recovery purposes).
  • If an end user is having trouble with the plugin, we might request that you make and send a backup file for troubleshooting.
• `/pvedrop` - Drop and create a new database with default values.  This will not affect the config file, only the db.  Yes, this will delete your rulesets.
• `/pveupdate` - Update new entity types (normally run automatically at wipe, but can be run any time).  Any newly-detected entities will be added to the collection 'unknown'.

Sub-commands for /pverule

• `/pverule list` - List current rulesets
• `/pverule dump RULESETNAME` - List some information about a specific ruleset
• `/pverule backup` - Same as /pvebackup.
• `/pverule restore` - List available backup files from the plugin oxide data folder.
• `/pverule restore FILENAME` - Restores the named database backup file to the live database.  The file must end in .db and MUST be from a previous backup created by NextGenPVE.  It must also be located in the plugin oxide data folder.

Additional sub-commands of /pverule called by GUI

• `/pverule editconfig {CONFIG} true/false` - Set any of the global flags below to true/false
• `/pverule editconfig RESET true` - Reset all of the global flags to default
• `/pverule editruleset default defload YES` - Reset the default ruleset to defaults.
• `/pverule editruleset {RULESETNAME} delete` - Delete the named ruleset.
• `/pverule editruleset {RULESETNAME} name {NEWNAME}` - Change the name of a ruleset.
• `/pverule editruleset {RULESETNAME} schedule {SCHEDULE}` - Set schedule for a ruleset.  Format is day;starthour:startminute;endhour:endminute, e.g. 1;1:00;9:00, 2;15:00;21:00.  Use '*' for every day
• `/pverule editruleset {RULESETNAME} clone ` - Clone a ruleset.  The new name wil be {RULESETNAME}1 or {RULESETNAME}2, etc. if 1 exists.
• `/pverule editruleset {RULESETNAME} damage 0/1` - Set default damage for the named ruleset.
• `/pverule editruleset {RULESETNAME} invschedule 0/1` - Set schedule inversion for the named ruleset.
• `/pverule editruleset {RULESETNAME} enable 0/1` - Enable or disable the named ruleset.
• `/pverule editruleset {RULESETNAME} except {RULENAME} add` - Add a named exception RULENAME to the named ruleset.
• `/pverule editruleset {RULESETNAME} except {RULENAME} delete` - Delete a named exception RULENAME from the named ruleset.
• `/pverule editruleset {RULESETNAME} src_exclude {TYPE} add` - Add a source exclusion, e.g. NPCMurderer.
• `/pverule editruleset {RULESETNAME} src_exclude {TYPE} delete` - Delete a source exclusion, e.g. HumanNPC.
• `/pverule editruleset {RULESETNAME} tgt_exclude {TYPE} add` - Add a target exclusion, e.g. NPCMurderer.
• `/pverule editruleset {RULESETNAME} tgt_exclude {TYPE} delete` - Delete a target exclusion, e.g. HumanNPC.
• `/pverule editruleset {RULESETNAME} zone default` - Set a ruleset zone to default.
• `/pverule editruleset {RULESETNAME} zone delete` - Delete zone from a ruleset.
• `/pverule editruleset {RULESETNAME} zone {zoneID}` - Set zone for ruleset.

The above commands can also be run from console or RCON (without /).

 

Permissions

• nextgenpve.use -- Currently used only in for the requirePermissionForPlayerProtection configuration, which should be considered experimental and for niche cases only.
• nextgenpve.admin -- Required for access to GUI and other functions
• nextgenpve.god -- Override PVE, killall

 

Configuration

{
  "Options": {
    "debug": false,
    "useZoneManager": false,
    "protectedDays": 0,
    "purgeEnabled": false,
    "autoCalcPurge": false,
    "autoCalcPurgeDays": 2,
    "purgeStart": "12/31/1969 12:01",
    "purgeEnd": "1/1/1970 14:20",
    "purgeStartMessage": null,
    "purgeEndMessage": null,
    "useSchedule": false,
    "useGUIAnnouncements": false,
    "useMessageBroadcast": false,
    "useRealtime": true,
    "useFriends": false,
    "useClans": false,
    "useTeams": false,
    "AllowCustomEdit": false,
    "AllowDropDatabase": false,
    "NPCAutoTurretTargetsPlayers": true,
    "NPCAutoTurretTargetsNPCs": true,
    "AutoTurretTargetsPlayers": false,
    "HeliTurretTargetsPlayers": true,
    "AutoTurretTargetsNPCs": false,
    "NPCSamSitesIgnorePlayers": false,
    "SamSitesIgnorePlayers": false,
    "AllowSuicide": false,
    "TrapsIgnorePlayers": false,
    "HonorBuildingPrivilege": true,
    "UnprotectedBuildingDamage": false,
    "TwigDamage": false,
    "HonorRelationships": false,
    "AllowFriendlyFire": false,
    "BlockScrapHeliFallDamage": false,
    "AutoPopulateUnknownEntitities": true,
    "requirePermissionForPlayerProtection": false
  },
    "Version": {
      "Major": 1,
      "Minor": 3,
      "Patch": 7
    }
}

The non-use flags above can be set from the GUI without reloading, etc.  useXXX flags are for the admin to determine third-party plugin use and require a reload.  In the GUI, you may also RESET the non-use flags to default.

ZoneManager can be used to associate a ruleset with a zone.

A few global flags are currently available to limit NPC AutoTurret and trap damage.

If protectedDays is set to a value greater than 0, player-owned items will become unprotected if the player has been offline for this number of actual days (experimental).

If a player is trying to damage a building, "HonorBuildingPrivilege" determines whether or not they are limited to damaging their own structures or any structures.  This is overridden for zoned rulesets where damage is allowed (PVP).

"UnprotectedDamage" determines whether or not an unprotected building (no TC) can be damaged by players other than the builder.

"TwigDamage" determines whether or not twig building components can be destroyed by any player.

"HonorRelationships" determines whether or not a player can damage their friend's structures or deployables.  This requires at least one of useFriends/useClans/useTeams and any associated plugins.

"AllowFriendlyFire" allows damage between players who are friends/clanmates/teammates.  This requires that HonorRelationships also be set to true.

"BlockScrapHeliFallDamage" handles the special case where players flying the scrapheli into other players causes fall damage, killing the target player.

Note that friends support can include Friends, Clans, or Teams.

AllowCustomEdit - Enables the editing of custom rulesets and setting collections for entities.  Be careful here as you can easily categorize animals as NPCs, resources as players, etc.

AllowDropDatabase - Enables pvedrop command and GUI button to reset the database to defaults.  This wipes everything!!!

AutoPopulateUnknownEntitities - Enables automatic discovery of new entity types when attacked or attacking. For example, a new plugin creates a custom npc type, e.g. CustomScientistNpc (NpcSpawn).  The code will now see that this type does not exist and will add it.  If, as in this case, the name contains 'npc', the new type will be added as npc.  Otherwise, it will be added as unknown.  This can then be adjusted as desired within the admin tool (pverule).  Note that if you had already added this type yourself, it should not get added again - let me know...

requirePermissionForPlayerProtection - require that players have the nextgenpve.use permission in order to be protected from damage.  DO NOT SET THIS unless you are willing to test it and understand what you are doing.  In general, NextGenPVE is for protecting against PVP damage on PVE servers.  ymmv...

NOTE: Flags can be external, although currently they must be written into the code to be called.  The current example is SAM Targeting.  If loaded, we call out to it for it's 6 settings, and we can set those values, which will then be reflected in the NextGenPVE GUI.

PURGE (1.2.8 and above)

This is a way to automate disabling rulesets based on calendar dates instead of solely by days of the week, etc.

1. For the purge options to work, you must set useSchedule to true.
2. Next, set purgeEnabled to true.
3. Set your purge start and end dates and times (currently in US format which is Month/day/year hour:minute:second)
4. For the start and end dates, time is optional.  The following examples would be valid:
   1. "12/31/1969 12:01" - December 31st 1969 at 12:01 pm
   2. "12/31/1969" - December 31st 1969 at midnight or 0:00
5. Optionally, set "purgeStartMessage" and "purgeEndMessage" to whatever you would like to see in chat and possibly in GUIAnnouncements if so enabled.
   1. Defaults are PURGE ACTIVE and PURGE OVER
6. Set autoCalcPurge to true to have the plugin create automatic end of month purge start and end times.  Set autoCalcPurgeDays to the number of days in advance of a wipe to start the purge.
   1. This is of course optional.
   2. Currently, the default would set a purge to Tuesday at 12 am through Thursday at 12am.
   3. The thought here is that many servers would want to at least have an end of month purge.  You can of course adjust the times after the plugin does its thing each month.

Obviously, there are currently some limitations to this.  But, if it works I can try to enhance it a bit to add for multiple purge windows per month, automatic update based on anticipated force wipe day, etc.

For now, you would need to update this configuration some time during each month, week, etc. depending on how often you purge.

Additionally, the following hooks are called at purge enable/disable:

// At purge enable
Interface.CallHook("DisableMe");
// At purge disable
Interface.CallHook("EnableMe");

Plugins can accept these hooks by setting something like:

        private void DisableMe()
        {
            if (!configData.respondToActivationHooks) return;
            enabled = false;
            Puts($"{Name} disabled");
        }
        private void EnableMe()
        {
            if (!configData.respondToActivationHooks) return;
            enabled = true;
            Puts($"{Name} enabled");
        }

They would need to adjust the checks and actions taken, of course.

Developers

The following hooks are available:

// Toggle PVE on or off
private bool TogglePVE(bool on = true)
// Toggle a single ruleset on or off
private bool TogglePVERuleset(string rulesetname, bool on = true)
// Check if a BaseCombatEntity is located in a zone associated with a ruleset with
//   damage == true OR (damage == false && enabled == false)
private bool IsInPVEZone(BaseCombatEntity target)
// Add a zone mapping (key) to a ruleset (In use by DynamicPVP, possibly others.)
private bool AddOrUpdateMapping(string key, string rulesetname)
// Remove a zone mapping (key) from a ruleset (In use by DynamicPVP, possibly others.)
private bool RemoveMapping(string key)

Details

NextGenPVE uses SQLite for most of its data storage. The database file is named nextgenpve.db.

The only other data file is ngpve_zonemaps.json. This is currently used by third party plugins that create their own PVP ruleset and zones.  Many of those would need to be modified to use NextGenPVE, but the function calls should behave the same.

Each rule includes a source and target listing all of the types that will be matched for the rule. The player is simply BasePlayer, whereas NPCs include several different types.

Any individual type of NPC, for example, can be added to one of the "exclude" fields of a ruleset. This can be source or target. The list is based on the exception rules added to the ruleset, and the entity types they contain.

The default ruleset allows quite a bit of damage other than player to player. For example, it has an exception for player_animal, allowing players to kill animals. You can add, for example, "Chicken" to the target exclusion list to block killing chickens for the poultry-friendly.

The basic rule evaluation order is:

Ruleset -> Default Damage -> Exception Rule -> Exclusion.

Example 1:

Player attacking Bear

1. Default ruleset damage False.
2. Exception for player_animal.
3. No source exclusion for BasePlayer.
4. No target exclusion for Bear.
5. DAMAGE ALLOWED.

Example 2:

1. Bear attacking Player
2. Default ruleset damage False.
3. Exception for animal_player
4. No source exclusion for BasePlayer.
5. No target exclusion for Bear.
6. DAMAGE ALLOWED.

Example 3:

1. Player attacking Chicken
2. Default damage False.
3. Exception for player_animal.
4. No source exclusion for BasePlayer.
5. Target exclusion for Chicken.
6. DAMAGE BLOCKED.

 

DynamicPVP

For use with DynamicPVP, you may need to create a new ruleset.  Change the name to match the one that DynamicPVP uses - default name is "exclude".  Set that ruleset's default damage to true.  After that, reload DynamicPVP.  Your ruleset should look like this:

Note that the Zone is set to lookup.  You can click on "lookup" to see that the zone lookup for this is set to one or more DynamicPVP-created zones.  You should be able to adjust the rules for the zone to block things that would otherwise be allowed.

 

Competing Ruleset Examples

• You create a clone of the default ruleset and enable it.
  • You now have two rulesets with identical functionality including default damage, allow rules, and exclusions.
  • Both rulesets would apply to the entire map by default.
  • If you edit the allow rules or exclusions, the rulesets will compete.  The clone will likely override the default.
  • Without a schedule or zone to determine which one is active at any given time or place, either may match for all PVE activity.
  • FIX 1: Apply schedules to both rulesets
  • FIX 2: Set a zone to the cloned ruleset (requires ZoneManager) to isolate it.
• You create a new ruleset with default damage TRUE and enable it
  • You now have a ruleset which competes with the default ruleset.
  • This new ruleset has default damage TRUE, which overrides the default ruleset.
  • The entire map is now PVP.
  • FIX 1: Add a zone to the new ruleset (requires ZoneManager) to isolate it to a specific area of the map.
  • FIX 2: Add a schedule to the new ruleset.  A better option for scheduled PVP might be to add a schedule to the default ruleset and delete your secondary ruleset.

In short, any rulesets you copy or create should be isolated by time and/or area using schedules or zones.  If your intention is to simply modify what types of damage is to be allowed globally, delete the extra rulesets and edit the default ruleset instead.

 

TODO

• Performance tweaks as needed.