ProconRulz - 37c.1

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

[..] = 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)

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.

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

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

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.

Kits

Weapons

Damage

Specializations