Jump to content
Infinity Gaming

About This File

Description
This plugin is a customizable limits/rules enforcer. It allows you to setup and enforce limits based on player statistics, and server state.

It tracks extensive Battlelog stats and round stats. Several limits are available in the Procon Plugin Enhancements forum.

Version 0.9.4.0 and later is optionally integrated with a MySQL server (using the Battlelog Cache plugin). This enables caching of Battlelog stats fetching, which over time should reduce the delay caused by restarting Procon/enabling Insane Limits when your server is full. This should also reduce load on Battlelog, which in turn will reduce the number of Web errors and exceptions. This version is compatible with TrueBalancer and other plugins that use stats fetching.

In addition to keeping track of player statistics, the plugin also keeps tracks of the number of times a player has activated a certain limit/rule. I got this idea from the ProCon Rulz plugin. With this meta-information about limits, you are able to create much more powerful rules such as Spree messages. If it's not clear now, it's ok, look at end of the documentation for examples that make use if this information.

By default, the plugin ships with virtual_mode set to True. This allows you to test your limits/rules without any risk of accidentally kicking or banning anyone. Once you feel your limits/rules are ready, you can disable virtual_mode.

Minimum Requirements
This plugin requires you to have sufficient privileges for running the following commands:

serverInfo
mapList.list
mapList.getMapIndices
admin.listPlayers all
punkBuster.pb_sv_command pb_sv_plist
punkBuster.pb_sv_command pb_sv_ban
punkBuster.pb_sv_command pb_sv_kick

Additionaly, you need to have Read+Write file system permission in the following directories:

<ProCon>/
<ProCon>/Plugins/BF3
<ProCon>/Plugins/BF4


Supported Limit Evaluations
 

  • OnJoin - Limit evaluated when player joins
  • OnLeave - Limit evaluated when player leaves
  • OnSpawn - Limit evaluated when player spawns
  • OnKill - Limit evaluated when makes a kill (team-kills not counted)
  • OnTeamKill - Limit evaluated when player makes a team-kill
  • OnDeath - Limit evaluated when player dies (suices not counted)
  • OnTeamDeath - Limit evaluated when player is team-killed
  • OnSuicide - Limit evaluated when player commits suicide
  • OnAnyChat - Limit evaluated when players sends a chat message
  • OnInterval - (deprecated) Same behavior as OnIntervalPlayers
  • OnIntervalPlayers - Limit evaluated (for all players) every evaluation_interval number of seconds (minimum 10)
  • OnIntervalServer - Limit evaluated once every evaluation_interval number of seconds (minimum 10)
  • OnRoundOver - Limit evaluated when round over event is sent
  • OnRoundStart - Limit evaluated after round over event, when first player spawns
  • OnTeamChange - Limit evaluated after after player switches teams

Note that limit evaluation is only performed after the plugin has fetched the player stats from Battlelog. If a player joins the server, and starts team-killing, there will be a couple of seconds before the plugin catches on. Having said that, this is rare behavior. Most of the time, by the time the player spawns for the first time, the plugin would have already fetched the stats.

When you enable the plugin for the first time in a full server, it will take a couple of minutes to fetch all player stats


Architecture
When the plugin is enabled, it starts two threads:

  1. The fetch thread is in charge of monitoring the players that join the server. It fetches player statistics from battlelog.battlefield.com
     
  2. The enforcer thread is in charge of evaluating Interval limits. When the enforcer thread finds that a player violates a limit, it performs an action (Kick, Ban, etc) against that player.


The two threads have different responsibilities, but they synchronize their work.

Fetch-thread Flow
 

When players join the server, they are added the stats queue. The fetch thread is constantly monitoring this queue. If there is a player in the queue, it removes him from the queue, and fetches the battlelog stats for the player.

The stats queue can grow or shrink depending on how fast players join, and how long the web-requests take. If you enable the plugin on a full server, you will see that almost immediately all players are queued for stats fetching. Once the stats are fetched for all players in the queue, they are added to the internal player's list.

Enforcer-thread Flow

The enforcer thread runs on a timer (every second). It checks if there are any interval limits ready to be executed. If there are, it will evaluate those limits.
Each time around that the enforcer checks for the available limits is called an iteration. If there are no players in the server, or there are no limits available, the enforcer skips the current iteration and sleeps until the next iteration.

The enforcer is only responsible for Limits that evaluate OnIterval, events. Enforcing for other types of events like OnKill, and OnSpawn, is done in the main thread when procon sends the event information.


Limit Management

Creation - In order to create a new limit, you have to set new_limit variable to True.
This creates a new limit section with default values that you can change.
Deletion - In order to delete a limit, you have to set the variable delete_limit to the numerical id of the limit you want to delete.
Each limit has an id number, you can see the id number in the limit name, e.g. Limit #5.

Limit Definition
At its basic, there are four fields that determine the structure of a limit. These fields are state, action, and first_check, and second_check.
  1. state
    Enabled - the limit will be used, and actions will be performed live
    Virtual - the limit will be used, but actions will be done in virtual_mode
    Disabled - the limit will be ignored
    This field is useful if you want to temporarily disable a limit from being used, but still want to preserve its definition.
  2. action
    (string, psv) - list of actions for this limit (Pipe separated "|")

    e.g. Say | PBBan | Mail

    These are all the allowed actions:
    None - no action is performed against the player
    • Kick - player is kicked, if the limit evaluates to True
    • EABan - player is banned (using the BF3 ban-list), if the limit evaluates True
    • PBBan - player is banned (using PunkBuster ban-list), if the limit evaluates True
    • Kill - kills the player (delay optional), if the limit evaluates True
    • Say - sends a message the server (All, Team, Squad, or Player), if the limit evaluates True
    • Log - logs a message to a File, Plugin log, or both, if the limit evaluates True
    • Mail - sends an e-mail to specified address, if the limit evaluates True
    • SMS - sends an SMS message to the specified phone number, if the limit evaluates True
    • Tweet - posts a Twitter status update (default account is @InsaneLimits), if the limit evaluates True
    • PBCommand - executes the specified PunkBuster command, if the limit evaluates True
    • ServerCommand - executes the specified Server command, if the limit evaluates True
    • PRoConChat - sends the specified text to PRoCon's Chat-Tab, if the limit evaluates True
    • PRoConEvent - adds the specified event to PRoCon's Events-Tab, if the limit evaluates True
    • TaskbarNotify - sends a Windows Taskbar notification, if the limit evaluates True
    • SoundNotify - plays a sound notification with the specified sound file, if the limit evaluates True
    • Yell - yells a message to the server (All, Team, or Player), if the limit evaluates True

    Depending on the selected action, other fields are shown to specify more information about the action.
    Supported PB ban-duration: Permanent, Temporary
    Supported PB ban-type: PB_GUID (default)

    Supported EA ban-duration: Permanent, Temporary, Round
    Supported EA ban-type: EA_GUID, IPAddress, Name

    Also note that each of these actions have a target player. You have to be careful on what target is for each action.

    For example, during a Kill event, the target of the action is the Killer.
    But, during a Death event, the target of the action is the player that was killed
    You don't want to accidentaly Kick/Ban the wrong player!
  3. first_check
    Disabled - the limit does not evaluate anything in the first step of evaluation
    Expression - the limit uses a C# conditional expression during the first step of evaluation
    Code - the limit uses a C# code snippet (must return true/false) during the first step of evaluation
    second_check
    Disabled - the limit does not evaluate anything in the second step of evaluation
    Expression - the limit uses a C# conditional expression during the second step of evaluation
    Code - the limit uses a C# code snippet (must return true/false) during the second step of evaluation
    Depending on the selected check type, an extra field will be shown for specifying the Expression, or Code text.

    Both Expressions, and Code snippets must be syntactically correct in accordance to the C# language. The plugin compiles your Expression/Code in-memory with the Microsoft C# Compiler. If there are compilation errors, those are shown in the plugin log.

    If you do not know what C# is, or what an expression is, or what a code snippet is ... do not worry. Study the examples in the Examples Index forum thread. Then, if you are still unclear, how to write an expression or a code snippet, ask for help in forums at phogue.net


Limit Evaluation
After compilation, limit evaluation is by far the most important of all steps this plugin goes through.
Limit evaluation is comprised of three steps:

  1. first_check Evaluation
    During this step, the plugin executes the Expression/Code in first_check to get a True or False result.
    If the result is False, the plugin does not perform any action, and quits. But, if it's True, it keeps going to the next step
     
  2. second_check Evaluation (optional)
    Next, the plugin runs the Expression/Code for the second_check, if it's enabled. If it's not enabled, it keeps going to next step.
     
  3. action Execution
    If the final result of the limit evaluation is True, the plugin then executes the action associated with the limit.
    If the final result of the limit evaluation is False, no action is executed.

Settings

  1. use_direct_fetch
    True - if the cache is not available, fetch stats directly from Battlelog
    False - disable direct fetches from Battlelog

    If the Battlelog Cache plugin is installed, up to date and enabled, it will be used for player stats regardless of the setting of this option. If the Battlelog Cache plugin is not installed, not up to date or disabled, setting use_direct_fetch to True will act as a fallback system, fetching stats directly from Battlelog. Otherwise, stats fetching will fail since the cache is not available and this setting is False.
  2. use_slow_weapon_stats
    False - skip fetching weapon stats for new players
    True - fetch weapon stats for new players

    Visible only if use_direct_fetch is set to True. Fetching weapon stats from Battlelog takes a long time, 15 seconds or more per player. By default, this slow fetch is disabled (False), so that your Procon restart or initial plugin enable time on a full server won't be delayed or bogged down while fetching weapon stats. However, if you have limits that use the GetBattlelog() function, you must set this value to True, or else stats will not be available. Also, see rcon_to_battlelog_codes.
  3. use_stats_log
    False - do not log Battlelog stats to the battle.log file
    True - log player stats to the battle.log file

    If stats fetching is enabled and stats are fetched successfully, all the stats that were fetched will be logged in a file that follows the standard logging file name pattern: procon/Logs/_/YYYYMMDD_battle.log (text file).
  4. limits_file
    (string, path) - path to the file where limits, and lists are saved
  5. auto_load_interval
    (integer >= 60) - interval in seconds, for auto loading settings from the limits_file
  6. player_white_list
    (string, csv) - list of players that should never be kicked or banned
  7. clan_white_list
    (string, csv) - list of clan (tags) for players that should never be kicked or banned
  8. virtual_mode
    True - limit actions (kick, ban) are simulated, the actual commands are not sent to server
    False - limit actions (kick, ban) are not simulated
  9. console
    (string) - you can use this field to run plugin commands

    For example: "!stats micovery" will print the player statistic for the current round in the plugin console.

    Note that plugin commands, are currently supported only inside ProCon, and not In-Game.
  10. rcon_to_battlelog_codes
    String[] Array - Syntax: RCON=Battlelog, e.g., U_XBOW=WARSAW_ID_P_WNAME_CROSSBOW

    Visible only if use_slow_weapon_stats is True. Lets you define mappings from RCON weapon codes to Battelog weapon stats codes. Useful when new unlocks or DLC are released and in-use before the next update of this plugin is available. You can also override incorrect mappings built-in to the plugin, if any.
  11. smtp_port
    (string) - Address of the SMTP Mail server used for Mail action
  12. smtp_port
    (integer > 0) - port number of the SMTP Mail server used for Mail action
  13. smtp_account
    (string) - mail address for authenticating with the SMTP Mail used for Mail action
  14. smtp_mail
    (string) - mail address (Sender/From) that is used for sending used for Mail action

    This is usually the same as smtp_account ... depends on your SMTP Mail provider.
  15. say_interval
    (float) - interval in seconds between say messages. Default value is 0.05, which is 50 milli-seconds

    The point of this setting is to avoid spam, but you should not set this value too large. Ideally it should be between 0 and 1 second.
  16. wait_timeout
    (int) - interval in seconds to wait for a response from the game server

    If you get several Timeout(xx seconds) expired, while waiting for ... exceptions in plugin.log, try increasing the wait_timeout value by 10 seconds. Repeat until the exceptions stop, but you should not exceed 90 seconds.


Plugin Commands
These are the commands supported by this plugin. You can run them from within the console field. Replies to the commands are printed in the plugin log.

!round stats
Aggregate stats for all players, current round

!total stats
Aggregate stats for all players, all rounds

!weapon round stats
Weapon-Level round stats for all players, current round

!weapon total stats
Weapon-Level stats for all players, all rounds

!web stats {player}
Battlelog stats for the current player

!round stats {player}
Aggregate stats for the current player, current round

!total stats {player}
Aggregate stats for the current player, all rounds

!weapon round stats {player}
Weapon-Level stats for the current player, current round

!weapon total stats {player}
Weapon-Level stats for the current player, all round

These are the most awesome of all the commands this plugin provides. Even if you are not using this plugin to enforce any limit, you could have it enabled for just monitoring player stats.

When calling player specific statistic commands, if you misspell, or only type part of the player name, the plugin will try to find the best match for the player name.
!dump limit {id}

This command creates a file in ProCon's directory containing the source-code for the limit with the specified id
For example, the following command
!dump limit 5
Creates the file "LimitEvaluator5.cs" inside ProCon's directory.
 
This command is very useful for debugging compilation errors, as you can see the code inside the file exactly as the plugin sees it (with the same line and column offsets).
  • !set {variable} {to|=} {value}
    !set {variable} {value}
    !set {variable}

    This command is used for setting the value of this plugin's variables.
    For the last invocation syntax the value is assumed to be "True".
  • !get {variable}
    This command prints the value of the specified variable.

In-Game Commands
These are the In-Game commands supported by this plugin. You can run them only from within the game. Replies to the commands are printed in the game chat.
  • !stats
    List the available stats, Battlelog
  • !stats [web|battlelog]
    List the available stats, Battlelog
  • !stats round
    List the available stats, current round
  • !stats total
    List the available stats, all rounds
    These commands are used as a shortcut for players to view what type of stats they can query. The plugin will try to fit all stat types into a single chat message.
  • !my {type}
    Print Battlelog stat of the specified type for the player that executed the command
  • !my round {type}
    Print current round stat of the specified type for the player that executed the command
  • !my total {type}
    Print all rounds stat of the specified type for the player that executed the command
  • ?{player} {type}
    Print Battlelog stat of the specified type for the specified player
  • ?{player} round {type}
    Print current round stat of the specified type for the specified player
  • ?{player} total {type}
    Print all rounds stat of the specified type for the specified player

Annex 1 - Boolean Operators:

For combining Expressions you use Boolean Logic operators. These are:

  • AND (Conjunction): &&
  • OR (Disjunction): ||
  • NOT (Negation): !

Annex 2 - Relational Operators:

All the previous examples use the Greater-Than ( > ) operator a lot, but that is not the only relational operator supported. These are the arithmetic relational operators you can use:

  • Greater-Than: >
  • Greater-than-or-Equal: >=
  • Less-than: <
  • Less-than-or-Equal: <=
  • Equality: ==
  • Not-Equal: !=

User Feedback

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
×
×
  • Create New...