ManualFileLanguage

As a GameCreate customer, your domain comes supplied with configuration files already setup and ready to use.

GameCreate also allows you to modify and store configuration files either for an entire game or a specific server (see Admin Server Files Page and Admin Game Files Page for details on adding or modifying files).

GameCreate uses a simplified interface for server configuration that allows the user to pick values for a series of properties (see Manual Game for information on configuring properties). The values chosen on the server configuration page are then inserted into the configuration file. The GameCreate File Language specifies the manner in which properties are inserted into and manipulated in configuration files.

1. Overview
2. Literal Text
3. Substitutions
   1. Built-In Properties
   2. Game Properties
4. Tags
   1. Syntax
   2. Arithmetic
      1. Format
      2. Examples
   3. Conditional Block
      1. Format
      2. Examples
   4. List Block
      1. Format
      2. Examples
   5. Remote Includes
      1. Format
      2. Example
   6. Substrings
      1. Format
      2. Examples
   7. Regular Expressions
      1. Format
      2. Example
   8. Date Formatting
      1. Example
   9. Random Numbers
      1. Format
      2. Example

Overview

Consider the following snippet of a configuration file which you would like written to disk:

name "My Server"
serverPort "14500"
queryPort "14510"
timelimit "20"

The appropriate properties are set up in GameCreate: Server Name and Host Port are built-in, and a game property for the Time Limit. The following file definition could use the properties from GameCreate:

// My Configuration file
name "%server:name%"
serverPort "%server:port%"
queryPort "<gc:eval>%server:port% + 10</gc:eval>"
timelimit "%timelimit%"

When GameCreate needs to write the configuration file to disk (such as when starting a game server), GameCreate will apply a series of rules to the definition to determine the final data to be written. These rules can either insert values in a server's configuration or manipulate values to fit the configuration file's requirements.

The configuration file above demonstrates the three types of text encounted in configuration files. Each type has separate rules that govern its usage:

• Literal text. Parts of the file like // My Configuration file and name are simply written to the configuration file and do not have any specific rules.

• (Property) Substitutions. Parts of the file like %server:name% and %timelimit% when encountered, are replaced by the value of the named property.

• Tags. Parts of the file like <gc:eval> and </gc:eval> are treated specially by GameCreate. There are a number of different tags to perform a variety of actions.

Literal Text

Literal text is written to the host's configuration file exactly as it is encountered; all text entered in a configuration file is literal unless it conforms to the style of substitutions or tags.

The percentage sign and angle brackets % < > do not need to be escaped; %somevalue% is treated as literal text unless somevalue identifies a property. <tag> is ignored unless it is of the form <gc:tag> (that is, the tag is ignored unless it is prefixed with gc:).

Substitutions

Substitutions allow you to directly interact with the server's configuration page, by using the values specified in the configuration file. GameCreate has several built-in properties (available to every server) along with a set of game-specific properties.

You instruct GameCreate to insert the value of a property by inserting the property's substitution keyword surrounded by percentage signs. Built-in properties have a name prefix like server:; game properties do not have a prefix and are named exactly as they appear on the Game Properties page.

Fortunately you do not need to know any of this; when editing a configuration file simply choose the property you wish to insert and click the Insert Property link. This will insert the appropriate %property% word at the current cursor position.

There is no limit to the number of times properties can be inserted into a configuration file; the same %property% word can appear as many times as is necessary to meet the requirements of the file. Note that the %property% word will not appear in the on-disk configuration file - the value of that property will appear in its place.

Built-In Properties

GameCreate supports the following built-in properties. Built-in properties apply to all servers and are not dependent on the particular game type of the server.

• %server:name% - The name of the server, after applying the domain's name format (see Manual Domain for information on using the name format).

• %server:rawname% - The name of the server, without the domain's name format. Normally you should use %server:name%.

• %server:players% - The maximum number of players permitted on the server.

• %server:ip% - The IP of the host the server is on.

• %server:port% - The host port for the server.

• %server:permanent% - The number '1' if the server is permanent; the number '0' if the server is temporary. Can be useful in combination with GameCreate tags - see the Tags section for details.

• %server:id% - The unique ID used by GameCreate to identify the server. Useful if you need an identifier that will never be re-used by a different server, such as for creating individual logging directories for each server.

These properties are also built-in, but are the same for all servers. These domain properties are configured from the Domain Settings page (see Manual Domain).

• %domain:name% - The name of this GameCreate domain

• %domain:email% - The primary email contact address listed for this domain.

• %domain:website% - The website URL listed for this domain.

• %domain:location% - Descriptive name of the location of hosts for this domain.

Game Properties

Each game has its own set of properties. These properties contain values for settings specific for that game, such as map to start the server on, time limit, and friendly fire. You can see a game's property list by visiting the game's Overview page and clicking _Properties (again, Manual Game covers adding and modifying game properties in more detail).

Each game property has a Substitution Keyword, which is used to specify when that game property should be inserted into the file. For example, a Time Limit property might have a Substition Keyword of timelimit, which would be inserted into a configuration file as %timelimit%.

Tags

Tags are the most powerful part of GameCreate's File Language: they allow a variety of actions to be taken that would typically otherwise require programming. Tags augment property substitions by allowing the creation of configuration files that would otherwise be impossible. The following actions are available:

• Arithmetic: Typically just adding numbers together, but arbtirary arithmetic is permitted.

• Conditional Blocks: Include or remove parts of a configuration file based on a value comparison.

• List Blocks: One type of game-specific property is the List. List blocks can provide extra formatting when outputting the contents of a list property.

• Remote Includes: Include the contents of a HTTP-accessible resource into the configuration file.

• Substrings: Shorten a property value to a specific length of select only part of the value.

• Regular Expression Replacements: Modify a property value using the regular expression syntax.

• Current Time/Date: Commonly used to give every log file a unique name.

• Random Number: Provides random number generation to make random logic decisions

Syntax

Tags can be used anywhere within a game or server configuration file. Tags in GameCreate look much like HTML or XML tags - that is, of the form <gc:tag>. All GameCreate tags carry the gc: prefix.

Unlike XML, tags in GameCreate do not necessarily occur in open/close pairs: a <gc:tag> may not need a </gc:tag> after it. See the individual tag sections below for specific requirements.

GameCreate Language tags may be nested. The following expression is perfectly valid and would return Expression is true:

<gc:if><gc:eval>5 + 2</gc:eval> = 7<gc:then>Expression is true<gc:else>Not True</gc:if>

The behaviour of a malformed tag is undefined - a good way to check if a configuration file is doing what you expect is to use the Preview link found on the game's or server's Files page.

The tags themselves will never appear in the file written to disk.

Arithmetic

The arithmetic tags allows you to perform simple numeric calculations: addition, subtraction, multiplaction and division. The most common use for this is when specifying a server's query port as being (for example) 10 greater than the base port.

Format

<gc:eval>operation</gc:eval>

operation is a combination of literal numbers, %variable% property substitutions, and the mathematical symbols: + - * / ( ) and modulus (%). The usual rules of mathematic notation apply; whitespace is not significant. This tag can not be nested. An optional attribute of format may be specified, which is either round, ceil or floor in order to modify the returned value. Leaving out this attribute will cause no rounding to occur.

Examples

queryPort "<gc:eval>%server:port% + 10</gc:eval>"
extraPlayers "<gc:eval format="floor">4 / 3</gc:eval>"
availableSlots "<gc:eval>%server:players% - 2</gc:eval>"

Conditional Block

The conditional tags allows you to pick one block of text from a series of blocks based on the result of a comparison. This allows you to change the contents of the configuration file based on property values.

Format

1. <gc:if>expr1 op expr2<gc:then>arbitrary text</gc:if>
2. <gc:if>expr1<gc:then>arbitrary text</gc:if>
3. <gc:if>expr1 op expr2<gc:then>arbitrary text<gc:else>arbitrary text</gc:if>
4. <gc:if>expr1 op expr2<gc:then>arbitrary text<gc:elseif>expr1 op expr2<gc:then>arbitrary text</gc:if>
5. <gc:if>expr1 op expr2<gc:then>arbitrary text<gc:elseif>expr1 op expr2<gc:then>arbitrary text<gc:else>arbitrary text</gc:if>

The minimal form for a conditional tag is given in (1) above: an opening <gc:if> tag, a condition to test, a <gc:then> tag, some arbitrary text, and finally a closing </gc:if>}} tag. All three tags are required; note there is no closing {{{</gc:then> tag.

The condition to test consists of two expressions separated by a comparison operator. expr1 and expr2 are the two expressions that will be compared. Either or both may use the arithmetic format discussed in the previous section, but should not include the <gc:eval> </gc:eval> tags themselves - expressions are implicitly evaluted using mathematic notation.

op must be one of == != > < >= <= = <>. == and = means 'is equal to', != and <> mean 'is not equal to'. The remaining comparison operators are 'greater than', 'greater than or equal to', 'less than', 'less than or equal to' respectively.

If the condition is true, arbitrary text will appear in the file output. If the condition is false, arbitrary text will not appear. The arbitrary text can contain literal text, property substitutions, or tags. In particular, conditional tags may be nested.

The form in (2) shows a single expression; the expression is considered to be true if the expression evaluates to a value other than nothing (ie, no characters at all) or the number 0.

The forms in (3), (4), and (5) show the use of <gc:elseif> and <gc:else>. <gc:else> is used to supply a separate block of arbitrary text to display if the preceding comparison was false. <gc:elseif> provides a further comparison to evaluate if the previous comparison was false. <gc:elseif> can be repeated indefinately withing a conditional block. At most one literal block in a chain of <gc:if> <gc:elseif> <gc:elseif> ... <gc:else> </gc:if> will be displayed - as soon as a condition is found to be true, the associated literal block is written to the host's disk and all other parts of the conditional tag up until the closing </gc:if> will be skipped.

Examples

<gc:if>%mod% == ctf<gc:then>
map ctf01
capturelimit %capturelimit%
</gc:if>

<gc:if>%password%<gc:then>usePassword=True<gc:else>usePassword=False</gc:if>

List Block

GameCreate properties come in a variety of types: Text, Checkbox, Drop down list. One type of property is the List, which is used to handle properties that are naturally a collection of text items such as a server map cycle. The list tags allow the contents of the list property to be processed.

Format

<gc:list text="text-value" separator="separator-value" random="random-value">Arbitrary text <gc:count start="start-value"> <gc:value separator="inner-separator" index="index-value">  arbitrary text </gc:list>

The <gc:list> and </gc:list> tags are required. The text attribute text-value specifies the list to process - typically using a %property% substitution, although that is not required. text must be supplied - without it, the list has no items.

text-value is split up into pieces using the separator specified by separator-value. Each time separator-value is encountered the text is split. For example, splitting text "the-dog" on the hyphen character would give two pieces - "the" and "dog".

The separator separator-value is not required: if ommitted, it defaults to the line separator (that is, each line in the text-value will form a separate piece). If specified, separator-value is treated as a sequence of characters to split text-value. separator-value can also be tab to separate the text on tab characters.

random-value is not required; if ommitted it defaults to "no", meaning the split pieces are processed in the order they occur in text-value. If random-value is "yes", the split pieces are shuffled before processing. One use for this feature is to re-order a map list each time a server starts.

Once text-value is split into pieces, the text within the <gc:list> ... </gc:list> is written to disk, once per item in the list. Literal text, property substitutions and tags are all valid. Two extra tags, <gc:value> and <gc:count> are also valid within the list block. Both are optional (although generally required). <gc:value> and <gc:count> can be used multiple times within the list block if required.

<gc:value> is used to insert the list item currently being processed. It has two optional attributes: separator and index. If an inner-separator is supplied, the list item is further split using the same mechanism described earlier (note that inner-separator and the separator-value for the <gc:list> must be different for this to work). After the list item has been split, index-value specifies which part of the split item to display: index="1" would select the first piece, index="2" the second piece, and so on. If index="0" or is not specified, the inner-separator is ignored and the list item is written in its entirety.

<gc:count> is used to determine how many list items have been processed so far. start-value specifies what number the first item in the list is - so start="1" would write the number 1 for the first list item, 2 for the second, and so on. start-value can be omitted, in which a default value of 1 is used.

Note that GameCreate will process the literal text exactly as is. In particular, if you need each list item to be written out on a separate line, be sure to include the new line in your literal text by placing the closing </gc:list> on a line of its own.

Examples

// Assume the maplist property is one map name per line

<gc:list text="%maplist%" random="yes">addMap <gc:value>
</gc:list>

// This game needs a named sequence to tie the map list together

<gc:list text="%maplist%">part<gc:count start=1> = "changemap <gc:value>; nextmap part<gc:value start=2>"
</gc:list>

// This game can change maximum players on a per map basis.
// Here we also demonstrate using literal text for the 'text' attribute

<gc:list text="downtown-8,cinema-16,hotel-12,lastmap-10" separator=",">addMap <gc:value separator="-" index="1">?playerLimit=<gc:value separator="-" index="2">
</gc:list>

Remote Includes

The include tag allows a HTTP URL to be read, and if found, written to the host each time the configuration file is written. If the URL's contents are dynamic (eg, its a PHP or ASP.NET page) the contents of the server's configuration file can be determined externally. One popular use for this feature is managing ban lists.

Format

<gc:include> http-url </gc:include>

The specified URL must use the HTTP protocol and be accessible by GameCreate. If any error occurs nothing is written to the host.

Example

<gc:include>http://www.example.com/bansystem/hl2bans.php</gc:include>

Substrings

Substrings allow you to limit the length of a property value, or output a portion of the property value.

Format

<gc:substr start="start-value" length="length-value"> arbitrary text </gc:substr>

The <gc:substr> and </gc:substr> tags are both required. At least one of start and length must be specified. The arbitrary text may include literal text, property substitions, and tags.

start specifies which character of arbitrary text to start writing from. If omitted, start-value defaults to 1 - the first character.

length specifies the maximum number of characters to write from arbitrary text. If omitted, all text beginning from the start-valueth character is written.

Note that start and length apply to the 'transformed' arbitrary text - that is the text resulting from performing any property substitutions and tag evaluations.

Examples

// Ensure our server's name does not exceed 30 characters
hostname "<gc:substr length="30">%server:name%</gc:substr>"

// This would write '234'
<gc:substr start="2" length="3">123456</gc:substr>

Regular Expressions

Regular expressions are a powerful feature that can be used to transform a property value in any number of ways. One Typical is to remove illegal characters from a property value.

Format

<gc:regex find="find-pattern" replace="replace-pattern">arbitrary text</gc:regex>

The <gc:regex> and </gc:regex> tags are both required. The find and replace attributes are also required. arbitrary text may include literal text, property substitutions, and tags.

find-pattern and replace-pattern are valid regular expression patterns. Regular expressions are a topic unto their own that we will not cover here; http://www.regular-expressions.info/tutorial.html is one tutorial that describes their use. Your favourite search engine will turn up many other resources.

find-pattern must be wrapped in forward slashes. The usual regular expression suffix modifiers like i for "ignore case" are supported.

Example

// Replace any character that's not a letter or number with an underscore
<gc:regex find="/[^A-Za-z0-9]/" replace="_">$Bad Ch@racters</gc:regex>
// RESULT: _Bad_Ch_racters

Date Formatting

GameCreate can include the date and/or time (formatted to your specification) at the time the file is written.

An example of where this may be useful is in creating log files which include the date the server was started.

<gc:date format="format-value" type="type-value">

The format-value and type-value attributes are optional.

Omiting the format-value attribute will mean a default formatting string is used: d m Y g:ia

format-value contains the formatting string on how to format the current date and time.

type-value is a shortcut to specifying a particular format-value, allowing you to use a pre-defined format string without having to remember it.

The format characters available for use are based on PHP's format implementation.

Note: Any characters used which are not listed here are treated as literal text. So providing a format string of d/m/Y is perfectly valid.

The available type-value shortcuts is currently:

• log - Will provide a timestamp format appropriate for a log file: Y.m.d-g.i.sa

Example

Here's an example which would be appropriate for telling an America's Army server to start logging to an easily recognized filename:

server.exe global %startmap% -log=port%server:port%.log -ini=port%server:port%.ini -nohomedir -log port%server:port%-<gc:date type="log">.log

Would produce:

server.exe global Insurgent_Camp.aao -log=port2016.log -ini=port2016.ini -nohomedir -log port2016-2006.03.31-12.00.56pm.log

The format given to the log parameter of the command line includes the word 'port' as a prefix (to identify a given server), followed by the server's port number, then followed by a <gc:date> tag with the pre-defined format type of 'log'.

The result is an output string that includes the day, month, year, hour minute and second the server was started.

Of course, if you wanted to replace this format with another, you can do so through the format-value parameter.

server.exe global %startmap% -log=port%server:port%.log -ini=port%server:port%.ini -nohomedir -log port%server:port%-<gc:date format="Y.m.d">.log

Would produce:

server.exe global Insurgent_Camp.aao -log=port2016.log -ini=port2016.ini -nohomedir -log port2016-2006.03.31.log

Which may be more suitable.

Random Numbers

The random tag allows you to generate a random whole number between a defined range.

Random numbers are useful to use in logic decisions when you wish to randomize specific settings or randomly assign values to server options.

Format

<gc:random min="min-value" max="max-value">

Defines an inclusive range of random value's to generate between min-value and max-value.

The min-value attribute is optional and defaults to zero.

Example

<gc:random min="2" max="5">

The output of this expression may be the whole number 2, 3, 4 or 5.