BattlEye Filters - AsYetUntitled/Framework GitHub Wiki

How to edit the BattlEye filters

This wiki page will serve as a brief guide on how to edit the BattlEye filters. This page is a work-in-progress until specified otherwise. It may contain errors or inaccuracies and only serves as an approximate guide on understanding and editing BattlEye filters.

What are they and what do they do?

BattlEye filters serve as a customisable and optional extension to BattlEye, the anti-cheat standard for the Arma video game series by Bohemia Interactive.

BattlEye filters scan for specific keywords on all scripts running on the client (scripts.txt) and server-side command parameters (other filters). When a match is detected the filters can be set to perform one of the following actions:

1 = Log to .log file only.
2 = Log to console window only.
3 = Log to .log file and console window.
4 = Kick without generating a .log entry.
5 = Kick and log to .log file only.
6 = Kick and log to console window only.
7 = Kick and log to .log and console window.

Console window refers to the window which opens when running the Arma server executable. .log refers to the respective .log file (to the .txt file) located in the \BattlEye\ folder within the server's directory.

Adding keywords

On a new line add a number from 1 to 7 followed by a single space and then a keyword. For example:
5 keyword

Keywords that contain one or more spaces must be enclosed within quotation marks ". For example:
5 "key word"

Keywords that contain quotation marks " themselves must have the quotations marks be preceded by a backslash \. For example:
5 "key \"word\""

Keywords that contain regular expression (regex) meta characters (\^$.|?*+()[]{}) must have the meta characters be preceded by a backslash \. For example:
5 "key $word$"

Note: The one exception to the above rule regarding regex meta characters is that it does not apply to the scripts.txt filter as that filter does not and will not support regular expressions^[1].

When possible, it is preferred to use keywords that can catch multiple strings. For example, in createVehicle.txt you want to kick for spawning Hunters. Rather than adding a keyword for each class name for the Hunter such as:

5 B_MRAP_01_F
5 B_MRAP_01_gmg_F
5 B_MRAP_01_hmg_F

It is more efficient to use a single keyword that covers all Hunter class names:
5 B_MRAP_01_

To catch everything use empty double quotes for the keyword "" or leave it blank. For example:
5 ""
or
5

Adding exceptions

On the same line add a single space after the keyword. Then add either ! or != and then the exception keyword. For example:
5 keyword !keywordException
or
5 keyword !=keywordException

Keyword exceptions follow the same rules as keywords. Keyword exceptions that contain one or more spaces must be enclosed within quotations marks ". For example:
5 keyword !"keyword exception"

Keyword exceptions that contain quotation marks " themselves must have the quotations marks be preceded by a backslash \. For example:
5 keyword !"keyword \"exception\""

Keyword exceptions that contain regular expression (regex) meta characters (\^$.|?*+()[]{}) must have the meta characters be preceded by a backslash \. For example:
5 keyword !"keyword $exception$"

Note: As before, the one exception to the above rule regarding regex meta characters is that it does not apply to the scripts.txt filter.

There are two options for exceptions:

!= - The parameter must exactly match the exception. In scripts.txt the entire statement the keyword is found in must exactly match the exception.
! - The parameter must contain the exception. In scripts.txt the statement the keyword is found in must contain the exception.

For example, if this is our createvehicle.txt filter:
5 "HMMWV_" !"HMMWV_Ambulance"

The code example below will not kick because the type parameter contains HMMWV_Ambulance which is an exception:
createVehicle ["HMMWV_Ambulance_DES_EP1",getPosATL player,[],10,"NONE"];

The code example below will kick because the parameter does not contain HMMWV_Ambulance:
createVehicle ["HMMWV_DES_EP1",getPosATL player,[],10,"NONE"];

If we change our filter to use != like so:
5 "HMMWV_" !="HMMWV_Ambulance"

Now both of the above code examples will kick because the parameters are not exact matches to HMMWV_Ambulance. The below code example will not kick because it is an exact match:
createVehicle ["HMMWV_Ambulance",getPosATL player,[],10,"NONE"];

Exceptions work differently in scripts.txt as noted above. For example, if this is our filter in scripts.txt:
5 keyword !=keywordException

The code example below will kick because the exception is not an exact match to the statement:
systemChat "keywordException";

To fix we need to change the filter to include the entire statement as an exception: 5 keyword !="systemChat \"keywordException\";"

Now the above code example will not kick.

In general exceptions should be written with != whenever possible. Using ! allows much more through the filter. There are some exceptions to this, such as the createVehicle.txt HMMWV_Ambulance example above. In that case it is more efficient to use a single ! exception to allow multiple class names, rather than multiple != exceptions. Many more fancy things can be done in filters that support regular expressions. To learn more about regex click this link.

Note: BattlEye filters are not case sensitive, but they are sensitive to spaces and line breaks.

Here is how to add exceptions that span across multiple lines.

In this example our scripts.txt file will be...

//new2
1 "teleport"
5 addAction
5 createDialog

... and in scipts.log and our entry will be:

21.12.2012 06:66:00: playerName (10.0.0.7:2316) 12345678901234567890123456789012 - #2 ""_side","_struct"];
disableSerialization;

closeDialog 0;
createDialog 'playerMenu';

_inv = ((findDisplay 20057) displayCtrl 15"

Copy the code between the outer most quotation marks like so:

"_side","_struct"];
disableSerialization;

closeDialog 0;
createDialog 'playerMenu';

_inv = ((findDisplay 20057) displayCtrl 15

Follow the aforementioned rules by preceding each occurrence of a quotation mark " with a backslash \. As this is for scripts.txt, we can ignore regex meta characters. Text editors such as Notepad++ can be used to quickly replace all occurrences of " with \".

\"_side\",\"_struct\"];
disableSerialization;

closeDialog 0;
createDialog 'playerMenu';

_inv = ((findDisplay 20057) displayCtrl 15

Now add backslash n \n on each new line like so:

\"_side\",\"_struct\"];
\ndisableSerialization;
\n
\ncloseDialog 0;
\ncreateDialog 'playerMenu';
\n
\n_inv = ((findDisplay 20057) displayCtrl 15

Format it onto one line like so:

\"_side\",\"_struct\"];\ndisableSerialization;\n\ncloseDialog 0;\ncreateDialog 'playerMenu';\n\n_inv = ((findDisplay 20057) displayCtrl 15

As it contains spaces it will need to be enclosed within quotation marks like so:

"\"_side\",\"_struct\"];\ndisableSerialization;\n\ncloseDialog 0;\ncreateDialog 'playerMenu';\n\n_inv = ((findDisplay 20057) displayCtrl 15"

Now we need to preceded the whole exception with either ! or != so BattlEye can recognised it as an exception. We will use != as it is more secure.

!="\"_side\",\"_struct\"];\ndisableSerialization;\n\ncloseDialog 0;\ncreateDialog 'playerMenu';\n\n_inv = ((findDisplay 20057) displayCtrl 15"

Finally the whole line of code must be added at the end of the line corresponding to the kick restriction number like so:

5 createDialog !="\"_side\",\"_struct\"];\ndisableSerialization;\n\ncloseDialog 0;\ncreateDialog 'playerMenu';\n\n_inv = ((findDisplay 20057) displayCtrl 15"

Now the aforementioned scripts.txt will look like:

//new2
1 "teleport"
5 addAction
5 createDialog !="\"_side\",\"_struct\"];\ndisableSerialization;\n\ncloseDialog 0;\ncreateDialog 'playerMenu';\n\n_inv = ((findDisplay 20057) displayCtrl 15"

Acknowledgements

This page uses content in part from A Guide to BattlEye Filters on Open DayZ Community.

References

[1] - Confirmed via e-mail with Bastian Suter, developer of BattlEye.