VPA.MSG
File Format Description
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
PBP PBP
------------ ------------------------------------------
See VPA.MSG
for examples on all fields.
|
