• Home
  • Strategy
  • Race Guides
  • Games
  • Files
  • Forum
  • Info
  • Contact

VPA.MSG File Format Description

Author: Various

VPA does its best to simplify game situation analysis as much as possible. The best way of doing this is to display all known information on the map. But many important objects and events in the game are known to player only via host messages (mine fields, ion storms, ship explosions, etc.) In order to extract information about these objects and events, VPA reads and analyses host messages each time you unpack new RST. It uses file named VPA.MSG during the message reading process. This file contains so-called "templates" that are used by VPA to distinguish between different types of messages and extract valuable information from message bodies. Also VPA.MSG contains blank lines and comments that are ignored. Lines starting with a semicolon (";") are considered as comments.

> Here is an example of a message template:
> ; *** Laying deep space mines
> Message OwnMines
> Check 1,[Sub Space Message]
> Check 3,1,From
> Check [torpedoes into deep space mines]
> ID [ID#],[ID#]
> X [at (],[at (]
> Y [at (],[,,]
> Mines [mine units],1
> Keep Rhombe 13
> End

Each message template starts with a MESSAGE type identifier. There is a limited number of pre-defined message types that are processed by VPA.

> In the above example the message type is "OwnMines".

Lines starting with "CHECK" are used to determine whether or not the message, that is currently being read, belongs to the specified message type. VPA reads all messages one by one. Each message is checked against each message template until VPA finds that the message is matching the template.

CHECK statement can have 1, 2 or 3 parameters. The 1st parameter is a line number in the message body, the 2nd parameter is a position in the line, and the 3rd parameter is a text that must be present at the specified position in the specified line.

The 1st and 2nd parameters can be specified either by digital value of the line number and position respectively or by text string in brackets. If a text string in brackets is specified as the 2nd parameter, VPA checks if this string is present within the line specified by the 1st parameter. If a text string in brackets is specified as the 1st parameter, VPA searches within the whole message for a line containing this string.

The case of the string characters does not matter. The comma character (",") has a special meaning in VPA.MSG. To specify a string containing a comma, type comma twice: ",,"

The 2nd parameter or the 2nd and 3rd parameters together can be omitted. In this case VPA just doesn't check the rest. If the 3rd parameter is omitted, the text at the position specified by the 1st and 2nd parameters is not checked. If the 2nd and 3rd parameters are omitted, VPA just checks the presence of the line specified by the 1st parameter.

> In the above example:
> Check 1,[Sub Space Message]
> This statement checks if the 1st line of the message contains substring
> "Sub Space Message".
> Check 3,1,From
> This statement checks if the 3rd line of the message starts with "From".
> Check [torpedoes into deep space mines]
> This statement checks if there is a line containing substring "torpedoes
> into deep space mines" anywhere within the message.

When VPA finds that all CHECK statements in the currently applied message template are true, it skips checking the message against the remaining templates and starts extracting data from the message. At this point VPA knows what type the message is and what kind of information it contains.

Following CHECK statements are data extraction statements. Each message type has a pre-defined set of informative data fields (that can be an empty set). The corresponding message template must contain the same number of data extraction statements.

> In the above example the set of fields for message type "OwnMines" is:
> "ID", "X", "Y" and "Mines".

Each data extraction statement consists of data field identifier followed by 2 parameters. The parameters are used to specify line number and position of the informative field within the message body. Their format is the same as in CHECK statements, but both parameters are mandatory. VPA extracts the data from the text at the specified position. If the 2nd parameter is specified by a text string in brackets, VPA extracts the data from the text immediately following this string in the specified message line.

> In the above example:
> ID [ID#],[ID#]
> This statement extracts mine field ID number from the line containing "ID#",
> right after the first occurrence of "ID#" in this line.
> X [at (],[at (]
> This statement extracts X coordinate of the mine field center from the line
> containing "at (", right after the first occurrence of "at (".
> Y [at (],[,,]
> This statement extracts Y coordinate of the mine field center from the line
> containing "at (", right after the first comma.
> Mines [mine units],1
> This statement extracts the number of mine units from beginning of the line
> containing "mine units".

Message template can contain an optional KEEP statement. If a KEEP statement is present within a message template, all messages matching this template will be stored in the VPA database and can be read on the future turns. All other messages will be not stored and, hence, will be not available in the future.

KEEP statement can have 2 optional parameters. These parameters must be either both omitted or both specified. If the KEEP parameters are specified, VPA sets a marker on the map at the location mentioned in the message. The 1st KEEP parameter is marker type. There are 5 marker types available: FLAG, CIRCLE, CROSS, SQUARE and RHOMBE. The 2nd parameter is marker color (1..15). See the list of available colors in the beginning of VPA.INI file.

(VPA 3.61a+) When the marker type is CIRCLE, and the message template contains a RADIUS statement, this will create a circle with the specified radius. Otherwise, it will create the standard circle marker.

> In the above example:
> Keep Rhombe 3
> This means that all mine fields laid on the current turn will have their
> centers marked with cyan rhombes on the map, and their respective messages
> will be stored in the VPA database.

Each message template ends with an END statement.

Be extremely careful when changing anything in VPA.MSG! The most common origin of errors made by players tinkering with VPA.MSG is that the same message can match more than 1 template (for example, mine scoop message matches also the mine sweep template), that's why the order of templates in VPA.MSG in very important.

It is recommended that all changes made to the original VPA.MSG file be documented, because the author can change the distributive VPA.MSG on his own in future versions of VPA, and you will have to insert your custom changes into it again.

If you like your custom changes and think that many players would like to use the same templates, please send your VPA.MSG file to the author of VPA, and maybe your changes will be included within the next version.

Appendix: List of all fields for all message types supported by VPA 3.61a

Message Type Fields
------------ ------------------------------------------
Data Object, Data
E-Mail (none)
Common (none)
Marker X, Y
[VPA 3.61a+]: Radius
OwnMines Id, X, Y, Mines, Web
GatherMines Id, X, Y, Mines, Web, Gather
EnemyMines Id, Owner, X, Y, Mines, Web
SensorSweep Id, Owner, Activity
Surrender Planet, Owner
Exploration Planet, Owner, Climate, Clans
DarkSense Id, Owner, N, T, D, M, Funds
SuperSpy Planet, Mines, Factories, Defenses, FCode,
N, T, D, M, Funds
BioScanner Id, NRace, Natives, Climate
IonStorm X, Y, Radius, Voltage, Heading, Warp, Grow
Wormhole Id, X, Y, Mass, Stable
Battle X, Y, Id1, Id2
PlanetBattle Name1, Name2
Explosion X, Y, Name
HConfig1 Mines, Alchemy, ColFB, RoFB
HConfig2 Hiss, RGA, SuperRefit, Webs
HConfig3 CloakFB
HConfig5 MinRate, DetectMine
HConfig6 TaxRate, ESBonus, ESRate
HConfig7 FedCrew, HissEffect, Terraform, CPDamage
HConfig8 Gravity, OneEngTow, HyperDrive
HConfig9 MaxIncome, Cloning, Gambling, Chunnel,
GloryDevice, AntiCloak, Assault
HConfig10 AdvRefinery, BioScanners, Ramscoop
------------ ------------------------------------------

See VPA.MSG for examples on all fields.


Latest Messages


VGA Planets Homepage Donavan's VGA Planets Assistant

Copyright © Circus-Maximus.com unless otherwise specified. All Rights Reserved.
The Contents of this page may not be used, published or reproduced without the owners written permission.
All other material © of their respectful owners.
VGA Planets is Copyright © Tim Wisseman

Contact | History | Privacy Policy | Terms of Service