Console Script Grammar

Con files are the core of how Battlefield 2 (and 1942 before it) configures its weapons, maps, objects, players and other game assets. These files can be run by the engine or from within the in-game console. The in-game console uses the exact same syntax with the notable difference that multi-line commands like beginRem do not work. With Battlefield 2, the console grammar has extended into a rudimentry scripting language, with loops and full conditionals. Battlefield 1942 had only very rudimentry conditionals.

Comments

There exist two classes of comments, block:

 beginRem
 this text is ignored
 endRem

and line:

 rem this text is ignored

Statements

Statements are a command followed by a number of optionally "quoted", whitespace-seperated arguments.

 commandClass.commandMethod argument1 "argument2"

The number and type of the arguments depends on the command being used. The available commands is beyond the scope of this page, but a good portion of them are included with the editor.

A full list is available by running GNU strings against your bf2.exe

CRD Argument Type

Many arguments are a CRD type of argument, which stands for Continuous Random Distribution, and is used to calculate a random number based on the specify properties. A CRD always has four sub-arguments, e.g.:

 CRD_NONE/3/0/0

The first argument says what type of distribution should be used, the second and third depend on the type and the latter is called symmetry, and can affect any of the distributions; it will be explained later.

The meaning of the second and third arguments, which are always integers, varies depending on the type of distribution property specified. The four types for this first argument are:

   CRD_NONE - do not vary the argument at all, just return the first number.
   CRD_UNIFORM - uniform random distribution, between the two numbers specified.
   CRD_EXPONENTIAL - exponential drop off, first number specifies the mean (average).
   CRD_NORMAL - normal distribution, the first number is the mean, the second the variance. 

We just need the first three arguments to compute a random number, the final, fourth argument is a boolean and can affect the sign of this computed number: If this argument is 1 (true), then there is a 50/50 chance that the computed number will be negated. If 0 (false), no negation "coin-flip" takes place.

Some examples:

 ObjectTemplate.TimeToLive CRD_NONE/240/0/0

TimeToLive will be set to 240: no computation was performed we just returned the first argument. This sort of CRD can be directly replaced by the number itself.

 ObjectTemplate.TimeToLive CRD_UNIFORM/2/7/0

TimeToLive can be one of [2, 3, 4, 5, 6, 7] and they have all the same chance.

 ObjectTemplate.rotationalSpeedInDof CRD_EXPONENTIAL/-20/0/1

The exponential distribution basically gives a distribution curve that drops off sharply and then levels out. It is computed by -mean*ln( random(0,1) ). In other words, a random number between 0 and 1 (not including 0 or 1) is generated, the natural logarithm of this number is computed, and the result is multiplied by the negative of the mean (the average), the second argument (and first number) passed in. For example, if the random number generated was 0.1, the natural log is -2.3, so since the mean was -20, the final number returned would be -(-20)*-2.3 = -46. Since the symmetric flag, the last argument, is set to 1 (true), there is a 50/50 chance that this result will be negated, i.e. be returned as 46 instead of -46.

NOTE: this distribution is often misused in the Battlefield code, e.g.

 ObjectTemplate.initRotation CRD_EXPONENTIAL/0/180/1

is a common use. However, this setting actually always returns a value of 0, since that is the mean specified. The "180" argument is ignored.

 ObjectTemplate.timeToLive CRD_NORMAL/2/3.5/0

A normal distribution is a classic bell curve shape. The second argument is the mean, the average value, and the third argument is the variance, how fast the distribution curve drops off into its bell shape. The fourth argument again acts to force symmetry if set, though the bell curve has its own symmetry when the mean is 0.

Variance specifies the range in which about 4/5ths of the numbers generated will fall. In our example, the 2 is the average time to live desired, and a variance of 3.5 means that this value can vary fairly widely; about 4/5ths of the numbers generated will be in the range +3.5 to -3.5 from the mean of 2, i.e. -1.5 to 5.5, with 1/5th of the numbers appearing above and below this range.

(Source)

Variables

Variables must be predefined, and have a strict naming system. All mutable variables must begin with v_ whereas all immutable variables or constants must begin with c_. It's a simple form of wikipedia:Hungarian Notation.

Mutable Variables

The code:

 var v_dongs = test

Defines a new variable called dongs or v_dongs depending on your point of view with the value "test". When defining a variable you can omit the default value however:

 var v_dongs

is a value construct for example.

Immutable Variables

 const c_butts = test

Defines a constant called, again, butts or c_butts with the value "test". Obviously, this variable cannot be changed.

const vs. var and assignments

Assigning to a variable is as simple as appending -> v_varname to any command. However, many commands do not return a value. The ones that do generally return either a boolean value (0 or 1) or a simple string.

Clearly, trying to assign to a const variable is an error and will not work.

Conditionals

Conditionals include the standard if ... endIf, if ... elseIf ... endIf and while ... endWhile constructs. These evaluate an expression.

Expressions

The grammar of an expression is roughly:

 <variable> <comparator> <value>

Where

• variable is any variable name beginning with v_ or c_.
• comparator is one of ==, !=, >, >=, < or <= or their textual equivalents: lessOrEqualThan, lessThan, greaterOrEqualThan, greaterThan, notEquals, equals.
• value is any literal string, quoted if neccessary.

Return

You may cease interpretation of the current .con file by using the command return. This resumes interpretation from the calling file. It is an error to use this unless the file was called with...

include and run

Both include and run trigger the interpretation of another .con file. They also have the ability to set arguments, which are a special type of mutable variable. For example:

 run test.con 1 2 3

Runs test.con. In test.con, the variables v_arg1, v_arg2 and v_arg3 are set to 1, 2 and 3 respectively. Typically this is used along with a conditional to do something for the editor mode, or to do something different for single player mode (a common use in BF1942, where this method also existed).

As for differences, run seems to create a new scope while include does not.

An Example

 var v_tst
 fileManager.fileExists movies/menu.bik -> v_tst
 if v_tst == 0
 fileManager.copyFile ../../mods/bf2/movies/menu.bik movies/menu.bik
 fileManager.copyFile ../../mods/bf2/movies/menu_loggedin.bik movies/menu_loggedin.bik
 endIf

This example checks if movies/menu.bik exists, and if it doesn't copies two files from the bf2 mod to the current mod.