ProconRulz - 37c.1

Author: bambam_ofc

ProconRulz Procon plugin

You can 'right-click' and select 'Print...' to print this page.

Apply admin commands (e.g. Kill, Kick, Say) to players
according to certain 'conditions' (e.g. spawned with Kit Recon)
Allows programming of weapon or kit limits, with suitable messages.


Triggers, Conditions, Actions Summary

Rule Format

Writing Rulz in the Right Order

%xyz% Substitution Variables

Some Example Rulz

Using TargetActions

Weapon keys (for BF3)


Note that not all games provide the data to support all ProconRulz features. In particular BF3 (as of release 16) does not provide player loadout details at spawn time, so for BF3 the "On Spawn" rulz are of very limited use.

actions include kick, ban, or just a warning (yell, say).

conditions include kit type, weapon type, and can be applied at Spawn time or on a Kill.

Each rule has three parts:

  1. Trigger - i.e. when the rule should fire, On Spawn, On Kill, On Teamkill etc
  2. Conditions - list of tests to apply before actions are done, e.g. Headshot, Kit Recon etc
  3. Actions - list of admin actions to take if all conditions succeed, e.g. Kill, Kick, Say

example rule: "On Spawn;Team Attack;Teamsize 8;Kit Recon 2;Say >>%p%<< Max 2 Snipers!!;Kill"
which means:
If player "X" has


A '#' character at the start of any line makes that whole line a comment, e.g. "# the following rulz are sniper limits"

Triggers, Conditions, Actions summary

As in the example above, rules can have
    One trigger;Multiple conditions;Multiple actions

On Round
On Spawn
On Kill
On TeamKill
On Suicide
On PlayerBlock
On Join
On Leave
On Say
Team <part name>
Teamsize <N>
Map <string>
MapMode <string>
On Kill;...Headshot
On Kill;...Kit <kit>
On Kill;...Weapon <weapon>
On Kill;...Damage <damage>
On Kill;...Range <N>
On Spawn;...Kit <kit> [<N>]
On Spawn;...Weapon <weapon> [<N>]
On Spawn;...Damage <damage> [<N>]
TeamKit <kit> <N>
TeamWeapon <weapon> <N>
TeamDamage <damage> <N>
TeamSpec <specialization> <N>
PlayerCount <N>
TeamCount <N>
ServerCount <N>
Rate <N> <M>
On Say;...Text <key>
TargetPlayer [<playername>]/td>
Ping <N>
Set <%varname%> <value>
Incr <%varname%>
Decr <%varname%>
If <varname> <comparison> <value>
Say <message>
PlayerSay <message>
VictimSay <message>
AdminSay <message>
Yell <message>
PlayerYell <message>
Log <message>
Both <message>
All <message>
Kill [<delay>]
Kick <message>
Ban <message>
TempBan [<seconds>] <message>
PBBan <message>
PBKick [<minutes>] <message>
PlayerBlock <item_name>
TargetAction <action>

Rule Format:

[..] = optional part
* = repeatable part
 | = separates alternative parts

rule = [<trigger>;][<condition>;]*[<action>;]* | #<comment>

I.e. trigger is optional (defaults to On Spawn), you can have multiple conditions including zero, and you can have multiple actions (actually including zero actions, but this has no point unless you are debugging conditions in 'Trace Rules' mode). If the first character of a rule is '#' then the rule is a comment. Rule lists can also contain empty lines for clarity (use this to separate sections of your rules).

<trigger> = "On Round" | "On Spawn" | "On Kill" | "On TeamKill" | "On Suicide"| "On PlayerBlock"| "On Join"| "On Leave"| "On Say" (rule with no trigger is the same as using On Spawn)

<condition> = (prefix with "Not " to reverse meaning)
    "Admin": player is a server Admin - typically use Not Admin
    "Admins": at least one server admin is on the server
    "Protected": player is on reservedslots list and protected from ProconRulz kicks and kills
    "Team Attack": player is an Attacker in Rush mode
    "Team Defend": player is a Defender in Rush mode
    "Teamsize <N>": smallest team has N or fewer players
    "Map <string>": map name or filename contains string, e.g. Map Nelson
    "MapMode <string>": current map mode contains string e.g. MapMode rush
    "On Kill;Headshot": kill was with a headshot
    "On Kill;Weapon <weapon>": player has killed with this weapon
    "On Kill;Damage <damage>": player has done this damage
    "On Kill;Range <N>": the distance of the kill was > N meters. Note BFBC2 +/- 20 meter random error
    "Kit <kit> [<N>]": player originally spawned with this kit, >N players on team with this kit incl. player
    "On Spawn;Weapon <weapon> [<N>]": player has this weapon, weapon limit is >N as for Kit
    "On Spawn;Damage <damage> [<N>]": player has spawned with weapon that can do this damage, limit N as Kit
    "On Spawn;Spec <specialization> [<N>]": player has this Spec, spec limit is N
    "TeamKit <kit> <N>": team has >N players spawned with this kit not necessarily including current player
    "TeamWeapon <weapon> <N>": team has >N players spawned with this weapon not necessarily including current player
    "TeamDamage <damage> <N>": team has >N players spawned with weapons that do this damage not necessarily including current player
    "TeamSpec <specialization> <N>": team has >N players spawned with this specialization not necessarily including current player
    "PlayerCount <N>": player has already triggered rule N times during this round: i.e. succeeds at N+1) - subst text %c%
    "TeamCount <N>": rule hit count for Team this round, see PlayerCount - subst text %tc%
    "ServerCount <N>": rule hit count for Server this round, see PlayerCount - subst text %sc%
    "Rate <N> <M>": player has triggered this rule N times in M seconds
    "PlayerFirst": player has triggered this rule for their first time this round
    "TeamFirst": player has triggered this rule for the first time for their team this round
    "ServerFirst": this is the first time any player has triggered this rule this round
    "PlayerOnce": player has triggered this rule for the first time since joining server
    "On Say;Text <key>": player has just entered say text including this key string
    "On Say;Text <key>;TargetPlayer": A playername can be found in the say text after <key>
    "Ping <N>": Player ping (from last listPlayers update) is higher than N
    "Set <%varname%> <value>": Set rule variable to a value
    "Incr <%varname%>": Increment (i.e. add 1) rule variable
    "Decr <%varname%>": Decrement (i.e. subtract 1) rule variable
    "If <value1> <comparison> <value2>": Test comparison of variables and values

Note: "OnSpawn;Kit Recon 2..." is equivalent to "On Spawn;Kit Recon;TeamKit Recon 2..."

<action> =
    "Say " <message>
    "PlayerSay " <message>: only the player involved will see message
    "VictimSay " <message>: On Kill only, the player killed will see message
    "AdminSay " <message>: only in-game admins will see message
    "Yell " <message>
    "PlayerYell " <message>: only the player involved will see Yell message
    "Log " <message>: log to procon chat log but don't use Say
    "Both " <message>: Say and Yell same message
    "All " <message>: Say and Yell and Log same message
    "Kill [<N>]": Kill after N milliseconds, for default see plugin setting
    "Kick " <message>
    "Ban " <message>: perm ban using EA ID
    "TempBan " <N> <message>: temp ban for N seconds using EA ID
    "PBBan " <message>: PunkBuster ban using PB GUID
    "PBKick " <N> <message>: PunkBuster kick for N minutes using PB GUID
    "PlayerBlock " <item_name>: e.g. PlayerBlock SniperRifle, PlayerBlock HG-2
    "TargetAction "<action> : <action> is applied to target after confirmation
    "TargetConfirm": confirms target for delayed actions
    "TargetCancel": cancels delayed actions from this player
    "Exec "<rcon command> ": Send rcon command to game server
    "End": End processing of this event
    "Continue": Continue processing the following rulz for this event, even if Kill/Kick/Ban applied

<N> = number (defaults to 0)

Rule order is important to avoid unreachable rules

The rules are tested in the order written. When a rule is reached that has all the conditions succeed, the rule actions will be applied to the player that triggered the rule, and processing for the current event will end if a kill/kick/ban action is applied to the player at that point.

This is important to understand if you want your rulz to work as intended.

Let's say you want to make teamkills suicidal, but also KICK a teamkiller if he already has 3 teamkills:

On TeamKill;PlayerCount 3;Kick
On TeamKill;Kill

On the FIRST teamkill, ProconRulz will check the first rule and get a PlayerCount of 1. 1 is NOT > 3 so ProconRulz stops processing this rule and moves on to the next rule (On TeamKill;Kill). For that rule, there are no more conditions so the rule succeeds and ProconRulz applies the KILL action and the teamkiller is slayed. As a Kill/Kick/Ban action has now been applied, ProconRulz stops processing rulz for this particular event.

On the SECOND and THIRD teamkills the same thing happens, except PlayerCount on the first rule has gone 1..2..3.

On the FOURTH teamkill,ProconRulz will check the first rule and get a PlayerCount of 4. 4 IS > 3 so the rule succeeds and ProconRulz applies the KICK action and the teamkiller is kicked from the server. As a Kill/Kick/Ban action has now been applied, ProconRulz stops processing rulz for this particular event.

The idea is that the rulz must be that way around... if the "On TeamKill;Kill" rule was the TOP rule, then it would ALWAYS succeed for every teamkill, and the "On TeamKill;PlayerCount 3;Kick" rule would NEVER be reached.

This is the basic point that ProconRulz users are most likely to struggle with. Anyone with a programming background should be able to get this easily, probably because they can step through the rulz in their head and understand the simple control flow that ProconRulz is using. If you don't get it, read these notes above again, and ask on the forum.

As a small detail, those of you that understand the point above might note that a refinement for ProconRulz v37 onwards is that processing doesn't stop for an event (as before) when any action is applied. I.e. for 'Say' and 'Log' actions, processing will continue to the following rulz. This allows multiple 'logging' rulz to fire for the same event. But any Kill/Kick/Ban event will cause the event processing to end at that rule. This behaviour can be modified with the End and Continue actions, which force processing to end or continue respectively. Effectively versions of ProconRulz prior to v37 have an 'End' action at the end of every rule.

Message substitutions

Anywhere a message appears in a rule, e.g. "Say %p% just spawned", the following substitutions can be embedded in the message:

Subsitute stringMeaning
%p%Player name (On Spawn, or killer on a kill)
%pt%Player team name, e.g. Attackers, US Army
%v%Victim name (On Kill|TeamKill|Suicide rules only)
%vt%Victim team name
%k%Player kit on spawn, e.g. Recon (or kit associated with kill weapon)
%w%Weapon (On Kill), e.g. SVU Snaiperskaya Short. Or list of weapons On Spawn.
%d%Damage (On Kill) e.g. SniperRifle or VehicleHeavy. Or list of damage types On Spawn
%spec%Specializations (On Spawn only) e.g. 12-Gauge Sabot Rounds
%r%Range (On Kill) - note each player position is randomised by 10 meters
%n%Teamsize of current smallest team
%c%Count of the number of times this player has triggered this rule
%tc%Count of the number of times this player's TEAM have triggered this rule
%sc%Count of the number of times ALL PLAYERS ON SERVER have triggered this rule
%h%Headshot (On Kill) - substituted with "Headshot" or blank
%m%Map name e.g. Nelson Bay
%mm%Map mode e.g. Rush
%t%Target found from previous TargetPlayer condition
%ping%Ping milliseconds for current player
%text%Text from player On Say event in this rule
%ea_guid%Player EA GUID
%pb_guid%Player PunkBuster GUID
%ip%Player IP address

E.g. "On Kill;Say Player >>>%p%<< killed [%v%] with [%w%] (damage %d%) range %r%."

Some example rules

Kit Recon 2;Say >>%p%<< Max 2 Snipers!!;Kill Max 2 Recon players on either team
Team Attack;Kit Recon;Say >>%p%<< No snipers on attacking side!!;Kill No Recon players on 'attackers' team in Rush
On Kill;Teamsize 4;Damage VehicleHeavy;Say No tanks until >4 players a side;Kill Killing with tank when your team is 4 players or less will be suicidal
On TeamKill;Kill Teamkilling is suicidal
On Suicide;Yell NOOOOOB %p% Suicided Message yelled when player suicides
On Kill;Say >>%p%<< killed [%v%] with [%w%], range %r% Chats a kill message on every kill

Using 'Target' actions

The Target condition and actions are designed to allow actions to be applied to players other than the %p% player that triggered the rule, e.g. to support in-game admin.

The plugin has to use a condition to extract the target for the action from somewhere, typically say text by the triggering player using the TargetPlayer condition, which sets up a %t% substitution variable for use in messages and also as the 'target' for TargetAction actions.

The following rules would implement an in-game-admin 'xkill' command:

On Say;Admin;Text xkill;TargetPlayer;PlayerSay Confirm %t%?;TargetAction Kill;
On Say;Text xyes;TargetConfirm;
On Say;Text xno;TargetCancel;

If TargetPlayer find exactly ONE player that matches the string given in the say text, then a TargetConfirm will automatically be applied. E.g. in the above example, "xkill bam" will slay player "bambam_ofc" if that is the only player found with the "bam" substring anywhere in the name.

Note that we avoided a rule such as "On Say;Text no;..." because this would fire EVERY time a player say ANYTHING with 'no' as a substring, e.g. "I am from Norway". We used "xno" instead.

List of all weapons, kits and specializations


DescriptionKit key
No kitNone
Special OpsSpecialist


DescriptionWeapon keyDamageKit
870 Combat870MCSShotgunNone
AEK-971 Assault RifleAEK-971AssaultRifleAssault
AKS-74u Assault RifleAKS-74uSMGDemolition
AN-94 Abakan Assault RifleAN-94&AbakanAssaultRifleAssault
AS Val Supressed Assault RifleAS&ValAssaultRifleNone
DAO-12 Striker ShotgunDAO-12ShotgunNone
F2000 AssaultF2000AssaultRifleAssault
FAMAS Assault RifleFAMASAssaultRifleAssault
FGM-148 JavelinFGM-148ProjectileExplosiveDemolition
FIM-92 StingerFIM92ProjectileExplosiveDemolition
Glock 18 PistolGlock18HandgunNone
HK53/MP5 Assault RifleHK53AssaultRifleNone
L96A1 Sniper RifleL96SniperRifleRecon
M1014 Semi-automatic ShotgunM1014ShotgunNone
M15 Anti Tank MineM15&AT&MineExplosiveDemolition
M16A4 Assault RifleM16A4AssaultRifleAssault
WWII M1911 .45M1911HandgunNone
M240 Maschine GunM240LMGSupport
M249 SAWM249LMGSupport
M26 MASS ShotgunM26MassShotgunAssault
M27 IAR M27IARLMGSupport
M320 Grenade luncherM320ProjectileExplosiveAssault
M39 Sniper RifleM39SniperRifleRecon
M40A5 Sniper RifleM40A5SniperRifleRecon
M4A1 CarbineM4A1SMGDemolition
M60 LMGM60LMGSupport
M67 GrenadeM67ExplosiveNone
M9 PistolM9HandgunNone
Baretta M93RM93RHandgunNone
MK11 Sniper RifleMk11SniperRifleRecon
Barrett M98B Sniper RifleModel98BSniperRifleRecon
MP7 Maschine GunMP7SMGNone
Pecheneg Maschine GunPechenegLMGSupport
PP-19 Bison SubMaschine GunPP-19LMGNone
PP-2000 SubMaschine GunPP-2000SMGNone
QBB-95 Light Machine GunQBB-95LMGSupport
QBU-88 Sniper RifleQBU-88SniperRifleRecon
QBZ-95 Assault RifleQBZ-95AssaultRifleDemolition
Repair ToolRepair&ToolMeleeDemolition
RPG-7 Anti Tank rocket-propelled grenade launcherRPG-7ProjectileExplosiveDemolition
RPK-74M Light Maschine GunRPK-74MLMGSupport
SIG SG 550 Assault RifleSG&553&LBSMGDemolition
Saiga 20K SemiSiaga20kShotgunNone
Simonow SKS-45 RifleSKSSniperRifleRecon
SMAW Anti Tank weaponSMAWProjectileExplosiveDemolition
SV98 SnayperskayaSV98SniperRifleRecon
SVD Sniper RifleSVDSniperRifleRecon
Taurus .44 Mag revolverTaurus&.44HandgunNone
Type88 Maschine GunType88LMGSupport
USAS-12 automatic ShotgunUSAS-12ShotgunNone
A-91 Assault RifleWeapons/A91/A91SMGDemolition
AK-74 Assault RifleWeapons/AK74M/AK74AssaultRifleAssault
G36C Assault RifleWeapons/G36C/G36CSMGDemolition
G3A3 Battle RifleWeapons/G3A3/G3A3AssaultRifleAssault
C4 ExplosiveWeapons/Gadgets/C4/C4ExplosiveSupport
Claymore mineWeapons/Gadgets/Claymore/ClaymoreExplosiveSupport
KH2002 Assault RifleWeapons/KH2002/KH2002AssaultRifleAssault
M416 Assault RifleWeapons/M416/M416AssaultRifleAssault
Magpul Personal Defense RifleWeapons/MagpulPDR/MagpulPDRSMGNone
MP412 REX RevolverWeapons/MP412Rex/MP412REXHandgunNone
MP-443 Grach PistolWeapons/MP443/MP443HandgunNone
SA-18 IGLA Air DefenseWeapons/Sa18IGLA/Sa18IGLAProjectileExplosiveDemolition
SCAR-H Assault RifleWeapons/SCAR-H/SCAR-HSMGDemolition
UMP-45 SubMaschine GunWeapons/UMP45/UMP45SMGNone
L85A2/SA80 Assault RifleWeapons/XP1_L85A2/L85A2AssaultRifleAssault


None, Nonlethal, Impact, Melee, Handgun, AssaultRifle, LMG, SMG, SniperRifle, Shotgun, Explosive, ProjectileExplosive, VehicleWater, VehicleAir, VehicleStationary, VehicleLight, VehicleHeavy


DescriptionSpecialization key