[VM] Terrain Technical Specifications

[HexCode]

CONTENT LINKS
==============

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

MAPNAMES.STR
viewtopic.php?f=100&t=550#p9029

Underlying Terrain Representations
viewtopic.php?f=100&t=550#p9031

Underlying Roadworks Representations
viewtopic.php?f=100&t=550#p9035

*.STM
viewtopic.php?f=100&t=550#p9032

*.SET (Section 1)
viewtopic.php?f=100&t=550#p9033

*.SET (Section 2)
viewtopic.php?f=100&t=550#p9034

*.SET (Section 3)
viewtopic.php?f=100&t=550#p9036

*.SET (Section 4)
viewtopic.php?f=100&t=550#p9037

*.SET (Section 5)
viewtopic.php?f=100&t=550#p9038

*.SET (Section 6)
viewtopic.php?f=100&t=550#p9039


===================================================================

The topic's contents may be modified or progressively added upon as time goes by.

===================================================================

INTRODUCTION
==============

Kindly review:

Introduction
viewtopic.php?f=100&t=536#p8929

All scenario maps are rectangular. The superimposed grid is mathematically defined by

Code: Select all

Columns: 0 , 1 , 2  . . .  C
   Rows: 0 , 1 , 2  . . .  R

It contains [(C+1)*(R+1)] cells (i.e., hexes). Sometimes, this number is referred to as the map's "area" (A).

There are THREE (3) types of visible map-related information that PGF assigns to a typical map hex:

a) It assigns TWO (2) coordinates to each map hex in the format (c,r). The presentation format is "spreadsheet style" in the sense that it connotes (column, row).

Upon mouse pointer hovering over a hex, its map coordinates are always visible near the bottom of the Scenario Panel. They are enclosed in parentheses.

b) It also assigns a Geographical Location Name (GLN) descriptor to each map hex (e.g, Clear, Rome etc).

Upon mouse pointer hovering over a hex, its GLN descriptor is also always visible near the bottom of the Scenario Panel to the immediate left of the displayed hex map coordinates.

c) In addition, PGF also assigns a Terrain Iconic Representation (TIR) or "tile" to each map hex. Such TIRs are always visible as they constitute the... "map" in the ordinary sense of the word (i.e., visual perusal).

There are also a few types of invisible map-related information that PGF assigns to a typical map hex. Such information is intended to be read internally and "understood" by PGF's engine.

[HexCode]

LINEAR MAP COORDINATE SPECIFICATION
====================================

PGF's engine "reads & understands" a rectangular map's coordinates in strictly linear fashion. In essence, the engine establishes a one-to-one correspondence between each coordinate pair (human reference) and its companion linear value (engine reference).

PGF's engine "reads" a rectangular map in continuous, sequential, uninterrupted fashion. Namely, starting with row 0, it canvasses the values therein traversing them from left to right. Next comes row 1 and so forth ending with row R's values.

PGF engine's linear map coordinate algebraic specification assumes the form:

Code: Select all

0 1 2...C (C+1) (C+2) (C+3)...(2C+1)...........................................
...............[R*(C+1)] [R*(C+1)+1] [R*(C+1)+2]...[(R+1)*(C+1)-1]

It comprises [(C+1)*(R+1)] strictly sequential values.

For example, a tiny rectangular map sporting columns 0,1 and 2 and rows 0 and 1 gives rise to the following linear map coordinate description:

Code: Select all

0 1 2 3 4 5

The one-to-one correspondence relationships follow:

Code: Select all

Linear Value 0 <==> Hex (0,0)
Linear Value 1 <==> Hex (1,0)
Linear Value 2 <==> Hex (2,0)
Linear Value 3 <==> Hex (0,1)
Linear Value 4 <==> Hex (1,1)
Linear Value 5 <==> Hex (2,1)

The rectangular map's precise dimensions fully specify the requisite one-to-one correspondence. How does PGF's engine "know" them ? Well, please be patient...

[HexCode]

MAPNAMES.STR
==============

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

Engine Hexadecimal Character Strings
viewtopic.php?f=100&t=536#p8935

Character Set Evolution
viewtopic.php?f=100&t=535#p11090

Preliminaries

A typical MAPNAMES.STR file sports a binary format which has been "borrowed" from SSI.

The file should always be located in folder ...\SCENARIO corresponding to the particular "game" that it is intended to support. Exceptionally, PGF's engine does not recognize the file's function should one place it in folder ...\DEFAULT\SCENARIO.

Internal Structure

PGF's engine completely ignores the values of the FIRST TWO (2) bytes. For all practical purposes, one may as well assign 8-bit values of "00" to both bytes.

The rest of the file accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to a Geographical Location Name (GLN) descriptor ultimately intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each GLN binary record is precisely TWENTY (20) bytes long. Within each GLN record, PGF's engine ignores all bytes located on the right of the first "00" byte encountered (if any) as one traverses the record's bytes going from left to right. In other words, encountering a "00" byte triggers an 8-bit null termination. GLN records need NOT be 8-bit null terminated.

A GLN record byte's value points to some particular alphanumeric character practically restricted to the ASCII Standard Character Set comprising 128 distinct characters. The encoding is "old fashioned" 8-bit as opposed to PGF's "more modern" 16-bit.

PGF's engine imposes strict, sequential order to GLN records within a typical MAPNAMES.STR file as per "standard" programming indexing practice: 0, 1, 2, etc.

A typical MAPNAMES.STR file is 2 + 20*R bytes long. R is the number of GLN records contained in the file.

Notes

1) PGF's engine cannot address GLN records sporting index values higher than 65,535 (the ultimate restriction due to 16-bit encoding).

2) UTF-16 character encoding is NOT backwards compatible with the ASCII Extended character set. It can only "straightforwardly understand" ASCII Standard character representations; hence, PGF engine's inability to display any ASCII Extended character hexadecimal representations which might be contained in file MAPNAMES.STR. For example, PGF's engine cannot display (near the bottom of the Scenario Panel) Latin-based characters featuring diacritics which may appear in GLN descriptor text.

[HexCode]

UNDERLYING TERRAIN REPRESENTATIONS
=====================================

Absolute Prerequisite

Introduction
viewtopic.php?f=100&t=550#p9027

Preliminaries

PGF's engine does not give a hoot about GLN generic descriptors; ditto for TIR ones. The engine "wants" to be "told" something exact that it can "fully understand" and "act upon" accordingly. Hence, enter the Underlying Terrain Representation (UTR) typology.

UTR Typology

The text descriptors appearing immediately below "mean" absolutely nothing to PGF's engine. They are provided solely for the benefit of the reader. What PGF's engine "single-mindedly" focuses on are the corresponding hexadecimal values (i.e., codes). It is only through such invisible input that PGF's engine usefully "perceives" of map terrain.

Code: Select all

Text Descriptor  Hexadecimal Value (Code)

Clear            00
Clear            01
Clear            02
Clear            03
Coast            04
Coast            05
Coast            06
Ocean            07
Port Facilities  08
River            09
River            0A
River            0B
Mountain         0C
Mountain         0D
Mountain         0E
Mountain         0F
Mountain         10
Mountain         11
Mountain         12
Airfield         13
Swamp            14
Non-Naval City   15
Rough            16
Forest           17
Clear            18
Fortification    19
Fortification    1A
Bocage           1B
Bocage           1C
Embarkation City 1D
Desert           1E
Mountain         1F
Mountain         20
Fortification    21
Rough Desert     22
Escarpment       23
Escarpment       24
Port City        25
Desert           26

The preceding table contains thirty nine (39) UTR codes. The UTR order in the code is "canonical". These codes are hard-coded in PGF's executable.

Note

The foregoing UTR Typology exhibits considerable "terrain duplication". The Typology originated with SSI. PGF's programmer simply adopted all, but one code, unchanged. Code "18" used to indicate "Desert" terrain properties.

[HexCode]

*.STM
======

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

Underlying Terrain Representations
viewtopic.php?f=100&t=550#p9031

Preliminaries

A typical *.STM file sports a binary format which has been "borrowed" from SSI.

The file should always be located in folder ...\SCENARIO corresponding to the particular "game" that it is intended to support. It is always scenario-specific.

It may be important to note that the file extension STM itself has been "borrowed" from SSI as well. Nevertheless, PGF's engine does not contain any hard-coded references regarding this "legacy" extension. Consequently, a modder has full freedom to employ any reasonable, valid filename (with or without an extension) if he so chooses.

Internal Structure

An *.STM file is 2*A bytes long (A is the corresponding map's "area" which is equal to the total number of its constituent hexes).

An *.STM file accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to an Underlying Terrain Representation (UTR) descriptor directly intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each binary record is precisely TWO (2) bytes long. It expresses the relevant, map hex-specific UTR code in 16-bit format ("XX YY"). The value is always understood as hexadecimal "YYXX" (i.e., YYXXh).

Important

UTR descriptors provide PGF's engine with an adequate "understanding" of a map's "true" terrain, visual aids for the benefit of humans be damned. The engine puts its "understanding" to good use by appropriately "policing" PGF's play system.

Note

Given that PGF's engine "comprehends" 39 UTR codes only, the 16-bit format is kind of... overkill. Barring careless hex-editing, byte "YY" should be "00" across the board. No matter though. Any binary code value greater than hexadecimal "26" encountered is automatically "interpreted" by PGF's engine to "mean" UTR code "00".

[HexCode]

*.SET (Section 1)
=====

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

*.STM
viewtopic.php?f=100&t=550#p9032

Preliminaries

A typical *.SET file sports a binary format which has been "borrowed" from SSI.

The file should always be located in folder ...\SCENARIO corresponding to the particular "game" that it is intended to support. It is always scenario-specific.

It may be important to note that the file extension SET itself has been "borrowed" from SSI as well. Nevertheless, PGF's engine does not contain any hard-coded references regarding this "legacy" extension. Consequently, a modder has full freedom to employ any reasonable, valid filename (with or without an extension) if he so chooses. In any case, the corresponding scenario-specific *.PGSCN file always contains the aforementioned filename's specification.

Constituent Sections

A is the corresponding map's "area" which is equal to the total number of its constituent hexes.

A typical *.SET file contains SIX (6) sections serially arranged one after another, without any intervening gaps.

Section 1 -- Companion *.STM File & Map Dimensions Specs (123 bytes long)
Section 2 -- Map Hex GLN References (2*A bytes long)
Section 3 -- Map Hex URR References (A bytes long)
Section 4 -- Map Hex COR References (A bytes long)
Section 5 -- Map Hex CUR References (A bytes long)
Section 6 -- Map Hex TIR References (2*A bytes long)

Therefore, a typical *.SET file is:

123 + 2*A + A + A + A + 2*A = 123 + 7*A bytes long.

Internal Structure

All *.SET files contain a "Section 1" which is 123 bytes long. It comprises FOUR (4) sequentially encountered segments, without any gaps.

Segment #1 -- Defunct:
This segment is 41 bytes long (i.e., decimal offsets 0-40). PGF's engine completely ignores this segment's values. For all practical purposes, one may as well assign the value "00" (i.e., 0h) to all bytes therein.

Segment #2 -- Companion Map UTR File Specification:
This segment is 60 bytes long (i.e., decimal offsets 41-100). The first byte always has the value "5C" (i.e., 5Ch) and represents a backward slash. The last byte always has the value "00" (i.e., 0h) and constitutes 8-bit null termination. The entire segment serves one and only one purpose: to define the filename of the Companion Map UTR File (usually sporting a "traditional" STM extension) in 8-bit format. This segment's alphanumeric contents are invariably subject to "early" 8-bit null termination.

Segment #3 -- Map Dimensions Specification:
This segment is 4 bytes long (i.e., decimal offsets 101-104). Much earlier, under this topic:

The rectangular map's precise dimensions fully specify the requisite one-to-one correspondence. How does PGF's engine "know" them ? Well, please be patient...

Well, as usual, patience is a virtue. The 4-byte long segment "CC cc RR rr" strictly pertains to decimal offsets 101, 102, 103 and 104, respectively. The two hexadecimal values here (16-bit format) are ccCCh and rrRRh. The first one specifies the ID number of the last map column (decimal C). The second one specifies the ID number of the last map row (decimal R).

In theory, one can contemplate maps sporting up to 65,536 columns and up to 65,536 rows. In practice, there may be practical limitations due to insufficiently large program memory buffers...

Segment #4 -- Defunct:
This segment is 18 bytes long (i.e., decimal offsets 105-122). PGF's engine completely ignores this segment's values. For all practical purposes, one may as well assign the value "00" (i.e., 0h) to all bytes therein.

[HexCode]

*.SET (Section 2)
=====

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

MAPNAMES.STR
viewtopic.php?f=100&t=550#p9029

*.SET (Section 1)
viewtopic.php?f=100&t=550#p9033

Visual Display Purpose

Section 2 enables PGF's engine to unambiguously assign a Geographical Location Name (GLN) descriptor to each map hex (e.g, "Clear", "Rome" etc). Upon hovering over a particular map hex with the mouse pointer, the assigned descriptor is always visible in the lowermost, right part of the screen, just to the immediate left of the displayed hex coordinate pair.

Internal Structure

Section 2 is 2*A bytes long (A is the corresponding map's "area" which is equal to the total number of its constituent hexes).

Section 2 accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to a GLN descriptor index value directly intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each Section 2 binary record is precisely TWO (2) bytes long. It points to the relevant, map hex-specific GLN descriptor index value in 16-bit format ("XX YY"). The value is always understood as hexadecimal "YYXX" (i.e., YYXXh).

Important

PGF's engine is "interested" in GLN descriptors for visual display purposes only. Such descriptors play no role whatsoever in the way PGF's underlying play system is being "policed" by the engine.

Note

Upon encountering a Section 2 record the corresponding GLN index value of which is higher than the index value of the last GLN record contained in file MAPNAMES.STR, PGF's engine "interprets" it as "nothing" and just displays the hex coordinate pair.

[HexCode]

UNDERLYING ROADWORKS REPRESENTATIONS
========================================

Absolute Prerequisite

Introduction
viewtopic.php?f=100&t=550#p9027

Preliminaries

PGF's engine does not give a hoot about visually displayed Terrain Iconic Representation (TIR) (i.e., tile) descriptors. The engine "wants" to be "told" something exact that it can "fully understand" and "act upon" accordingly. Hence, enter the Underlying Roadworks Representation (URR) basic typology.

URR Basic Typology

The text descriptors appearing immediately below "mean" absolutely nothing to PGF's engine. They are provided solely for the benefit of the reader. What PGF's engine "single-mindedly" focuses on are the corresponding hexadecimal values (i.e., codes). It is only through such invisible input that PGF's engine usefully "perceives" of a map hex's roadworks. Clockwise:

Code: Select all

Text Descriptor                           Hexadecimal Value (Code)

No Roadworks Whatsoever                   00
Road Points to the North (12 o'clock)     01
Road Points to the Northeast (2 o'clock)  02
Unused                                    04
Road Points to the Southeast (4 o'clock)  08
Road Points to the South (6 o'clock)      10
Road Points to the Southwest (8 o'clock)  20
Unused                                    40
Road Points to the Northwest (10 o'clock) 80

The preceding table contains NINE (9) URR basic codes.

Technical Explanation

The preceding URR basic codes are based on a rather well known coding scheme which unambiguously aggregates the standard EIGHT (8) bit values collectively specifying a byte's value into a unique hexadecimal value. Here is how it is done:

Code: Select all

Constituent Bit Values    Hexadecimal Value (Code)

0 0 0 0 0 0 0 0           00
1 0 0 0 0 0 0 0           01
1 1 0 0 0 0 0 0           02
1 1 1 0 0 0 0 0           04
1 1 1 1 0 0 0 0           08
1 1 1 1 1 0 0 0           10
1 1 1 1 1 1 0 0           20
1 1 1 1 1 1 1 0           40
1 1 1 1 1 1 1 1           80

URR Composite Codes

URR basic codes can be additively employed to put together URR composite codes representing more complex hex roadworks.

For example, a hex hub sporting roadworks pointing to the South as well as to the Northwest will be assigned hexadecimal code "90". How ?

"10" + "80" = "90" (hexadecimal addition)

Important

All URR basic and additively derived composite codes are unambiguously unique, at least as far as PGF's engine is concerned.

[HexCode]

*.SET (Section 3)
=====

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

Underlying Roadworks Representations
viewtopic.php?f=100&t=550#p9035

*.SET (Section 1)
viewtopic.php?f=100&t=550#p9033

Internal Structure

Section 3 is A bytes long (A is the corresponding map's "area" which is equal to the total number of its constituent hexes).

Section 3 accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to an Underlying Roadworks Represenation (URR) descriptor code directly intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each Section 3 binary record is precisely ONE (1) byte long. It points to the relevant, map hex-specific URR descriptor value in 8-bit format ("XX"). The value is always understood as hexadecimal "XX" (i.e., XXh).

Important

URR descriptors provide PGF's engine with an adequate "understanding" of a map's "true" roadworks, visual aids for the benefit of humans be damned. The engine puts its "understanding" to good use by appropriately "policing" PGF's play system.

Note

Any "unknown" binary code value encountered is automatically "interpreted" by PGF's engine to "mean" URR code "0" (i.e., no underlying roadworks whatsoever).

[HexCode]

*.SET (Section 4)
=====

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

Combatant Ownership Representations
viewtopic.php?f=100&t=547#p8993

*.SET (Section 1)
viewtopic.php?f=100&t=550#p9033

Internal Structure

Section 4 is A bytes long (A is the corresponding map's "area" which is equal to the total number of its constituent hexes).

Section 4 accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to a Combatant Ownership Representation (COR) descriptor code directly intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each Section 4 binary record is precisely ONE (1) byte long. It points to the relevant, map hex-specific COR descriptor value in 8-bit format ("XX"). The value is always understood as hexadecimal "XX" (i.e., XXh).

PGF's engine cannot accommodate COR codes the index value of which is higher than 255 (the ultimate restriction due to 8-bit encoding).

Important

COR descriptors provide PGF's engine with an adequate "understanding" of a map's "true" "combatant ownership", visual aids for the benefit of humans be damned. The engine puts its "understanding" to good use by appropriately "policing" PGF's play system.

Relevant UTRs

"Combatant ownership" of a map hex is meaningful only with respect to the following Underlying Terrain Representation (UTRs) codes:

Code: Select all

Text Descriptor Hexadecimal Value (Code)

Port Facility   08
Airfield        13
City            15
Embark. City    1D
Port City       25

All map hexes sporting UTRs other than the preceding FIVE (5) ones are assigned a COR index (code) hexadecimal value of "00" (i.e., 0h).

Note

PGF's engine visually depicts a map hex's "combatant ownership" by displaying the corresponding Combatant Flag Iconic Representation (CFIR) image (if any) residing in file FLAGS.BMP. The image appears on the map hex's bottom-center.

Upon encountering a Section 4 record the corresponding COR index value of which is higher than the index value of the last image slot contained in file FLAGS.BMP, PGF's engine just displays, well, nothing !

[HexCode]

*.SET (Section 5)
=====

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

*.SET (Section 1)
viewtopic.php?f=100&t=550#p9033

Visual Display Purpose

Section 5 enables PGF's engine to unambiguously inform a human player as to whether any particular map hex is completely unenterable by units or not. Completely unenterable map hexes feature green hexsides.

Internal Structure

Section 5 is A bytes long (A is the corresponding map's "area" which is equal to the total number of its constituent hexes).

Section 5 accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to a Complete Unenterability Representation (CUR) descriptor code directly intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each Section 5 binary record is precisely ONE (1) byte long. It points to the relevant, map hex-specific CUR descriptor value in 8-bit format ("XX"). The value is always understood as hexadecimal "XX" (i.e., XXh).

Pseudo-Boolean Encoding

PGF's engine recognizes one and only one byte value indicating that a particular map hex is, indeed, completely unenterable by units: "03" (i.e., 3h). Any other values are completely ignored by the engine. For all practical purposes, all map hexes which are enterable by some units in one fashion or another could readily be assigned byte values of "00" (i.e., 0h).

Important

CUR descriptors provide PGF's engine with an adequate "understanding" of a map hex's "true" unenterability status, visual aids for the benefit of humans be damned. The engine puts its "understanding" to good use by appropriately "policing" PGF's play system.

Note

Complete unenterability by units may be viewed as a logical expansion of two partial hex unenterability regimes also present in PGF's play system. Most Ground units cannot "normally" enter hexes featuring Rough Desert, Escarpment or Ocean / Sea underlying terrain (UTRs). Most Naval units cannot "normaly" enter hexes featuring any other underlying terrain but Ocean / Sea, Port Facility or Port. Complete unenterability includes Air units as well and allows for no exceptions whatsoever, irrespective of unit class or type.

SSI's "classic" content describes a hex's Complete Unenterability as "Neutral Territory".

[HexCode]

*.SET (Section 6)
=====

Absolute Prerequisites

Introduction
viewtopic.php?f=100&t=550#p9027

Linear Map Coordinate Specification
viewtopic.php?f=100&t=550#p9028

TACMAP_??????.BMP
viewtopic.php?f=100&t=545#p9030

Underlying Terrain Representations
viewtopic.php?f=100&t=550#p9031

*.STM
viewtopic.php?f=100&t=550#p9032

*.SET (Section 1)
viewtopic.php?f=100&t=550#p9033

Visual Display Purpose

Section 6 enables PGF's engine to unambiguously assign a Terrain Iconic Representation (TIR) descriptor to each map hex for the visual benefit of a human player.

Internal Structure

Section 6 is 2*A bytes long (A is the corresponding map's "area" which is equal to the total number of its constituent hexes).

Section 6 accommodates binary records which appear in strict sequential order, one after another, without any intervening gaps. Each such record corresponds to a TIR descriptor index value directly intended to be linked to some particular, unambiguously identified (from PGF engine's standpoint) map hex.

Each Section 6 binary record is precisely TWO (2) bytes long. It points to the relevant, map hex-specific TIR descriptor index value in 16-bit format ("XX YY"). The value is always understood as hexadecimal "YYXX" (i.e., YYXXh).

Important

PGF's engine is "interested" in TIR descriptors for visual display purposes only. Such descriptors play no role whatsoever in the way PGF's underlying play system is being "policed" by the engine.

Note

Upon encountering a Section 6 record the corresponding TIR index value of which is higher than the index value of the last TIR record contained in files TACMAP_??????.BMP, PGF's engine "interprets" it as "nothing" and just displays a pitch black background.