[VM] PG1-DOS Content Conversion Functionality

[HexCode]

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

Introduction
viewtopic.php?f=100&t=647#p11330

Content Conversion Workspace Construction
viewtopic.php?f=100&t=647#p11468

Command Line Operations
viewtopic.php?f=100&t=647#p11501

Converted Custom Content
viewtopic.php?f=100&t=647#p11507


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

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

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

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

Preliminaries

This topic should be of interest to Veteran Modders (VMs). It is assumed that the reader is already intimately familiar with the information featured here:

[NP] Introductory Documentation
viewtopic.php?f=100&t=531

Also, kindly review:

Introduction
viewtopic.php?f=100&t=535#p8923

VMs mightily depend on PGF's Veteran Modder Interface (VMI). PGF's VMI is essentially open-ended and constantly enables technical novelties applicable to "ambitious" custom content design, including the judicious hex-editing of PGF's binary files.

Most VMs can be described as computer "power users".

PG1-DOS Content Conversion

PGF's underlying play system is a reasonably faithful emulation of SSI PG1-DOS'. To boot, PGF and PG1-DOS share a couple of scenario map definition file formats. Because PG1-DOS has predated the release of PGF, a need has arisen to adapt content originally playable under PG1-DOS so that it can be played under PGF. PGF's Developer / Programmer has done exactly that by suitably adapting SSI's "flagship" PG1/AG content technically conforming to PG1-DOS file format specifications.

PGF's engine features a PG1-DOS Content Conversion Functionality (CCF). This CCF is a useful component of PGF's VMI. Its main purpose is to allow modders to convert campaign content en masse. Nevertheless, the CCF also allows one to indirectly convert less "extensive" content as well.

[HexCode]

CONTENT CONVERSION WORKSPACE CONSTRUCTION
==============================================

Software Requirements

PG1-DOS -- Floppy Disk Version 1.2
PGF Version 1.02

Workspace Construction

No seasoned Modder exposes his precious hobby setup to folder / file overwrite accidents... To this effect, the "construction" of an appropriate Content Conversion Workspace (CCWS) is a must ! In the present context, I highly recommend that modders proceed as follows:

1) Copy your core PG1-DOS folder structure to .\PGDtoPGF ; at this stage of the operation, your CCWS folder structure will look like this:

Code: Select all

.\PGDtoPGF
.. \DAT
.. \EXE
.. \EXE\LIBDRV
.. \SAVES
.. \SCNBRIEF
.. \SOUND

2) Create an additional .. \SCENARIO folder here. Following that, your CCWS folder structure will look like this:

Code: Select all

.\PGDtoPGF
.. \DAT
.. \EXE
.. \EXE\LIBDRV
.. \SAVES
.. \SCENARIO
.. \SCNBRIEF
.. \SOUND 

3) Go over to the root of your core PGF folder structure and copy files

Code: Select all

HTMLAYOUT.DLL
PGFOREVER.EXE

to .\PGDtoPGF ; the root of your CCWS folder structure.

4) Go over to .. \PG\SCENARIO of your core PGF structure and copy file

Code: Select all

PG.PGCAM

to .\PGDtoPGF\SCENARIO over at your CCWS folder structure.

Your CCWS folder structure is now complete.

[HexCode]

COMMAND LINE OPERATIONS
=========================

Absolute Prerequisites

All prior posts under this topic.

Copy & Overwrite

The next step is rather simple. One just copies the PG1-DOS files collectively comprising his "content" to the appropriate Content Conversion Workspace (CCWS) folders. Clearly, each such file will intentionally overwrite its namesake.

Enter a... Cryptic PGF

At this conversion stage, PGF enters the... fray. However, this is NOT the PGF that its fans love or, at least, rely on to play. Nay ! It is an inscrutable "black box" that generates either one of two possible outcomes:

a) Conversion success in toto; or
b) Conversion failure in toto.

In other words, there can NEVER BE "partial" successes or failures here. Most importantly, it is extremely difficult to troubleshoot such conversion failures. Why ? PGF's Developer / Programmer DID NOT leave behind any pertinent technical notes which could potentially assist an unlucky Modder...

Enter the... Dinosaurs

Let us remember... MS-DOS' ways !

1) MS-WIN XP includes CMD.EXE, a DOS-like, command line shell located in folder

Code: Select all

%SystemRoot%\system32\

Upon its invocation, the user is faced with a window sporting an austere, black background...

2) Let us assume that the root of "our" CCWS is

Code: Select all

C:\PGDtoPGF

It is imperative that one renders this root folder "current" (DOS parlance). To accomplish this, one has to type in the following commands into the... austere window, one command (implemented by hitting the Enter key) at a time:

Code: Select all

C:
CD \
CD PGDtoPGF

If successful, one should be looking at the following last line

Code: Select all

C:\PGDtoPGF>_

where the underscore character is blinking. This is where the next, critical command should be typed in immediately followed by hitting the Enter key.

Code: Select all

PGFOREVER /CONVERT

In DOS parlance, "PGFOREVER" refers to executable PGFOREVER.EXE; /CONVERT (separated from PGFOREVER by a space) is a "switch" "instructing" the executable to do something very specific. In this case, it is the desired... conversion, of course !!

Back to Pretty...Windows

A Folder Display window will open up entitled "Browse for Folder". The user will be prompted to:

"Enter PG folder"

Never mind "PG"... What one should do is navigate over to CCWS folder "PGDtoPGF", highlight it and press the OK key.

One's conversion is successful IF AND ONLY IF a little information message appears entitled "PG FOREVER", stating:

"Conversion was successful"

If so, one just presses the OK key.

Any other outcome or message indicates failure to convert in toto !

A New Folder Makes An Appearance

Assuming conversion "success", one goes back to the CCWS folder structure and "refreshes" it by hitting the F5 key. All of a sudden, a "Log" folder appears out of the blue. It contains file "log.txt". This file is NOT part of the converted input per se. Rather, it provides one with useful information should he wish to do some targeted post-conversion remedial editing. Most importantly, the file's contents provide him with incontrovertible, empirical evidence that NOT ALL input "irregularities" abort the conversion process. Sometimes, a Modder is just lucky...

[HexCode]

CONVERTED CUSTOM CONTENT
=========================

Absolute Prerequisites

All prior posts under this topic.

Content In, Content Out

The content conversion under discussion accepts a bunch of PG1-DOS files as input. If successful, the conversion outputs a bunch of PGF files. Obviously, the conversion's output is at most as "good" as its input.

The PG1-DOS files collectively comprising the custom content input "live" side by side with a whole bunch of files that come with a fresh stock SSI PG1-DOS' installation. In other words, the conversion's overall input is a hybrid ! It stands to reason, then, that a successful conversion will also result in a hybrid assortment of PGF files.

Clearly, a Modder needs to accurately make note of the specific files constituting HIS custom input so that he may be able to unambiguously identify the corresponding output files containing HIS converted custom content.

Yet Another New Folder Makes An Appearance

The "refreshed" CCWS folder structure now contains yet another new folder entitled "Graphics". It contains the following graphics files (I almost always capitalize the names of files and folders to enhance readability):

Code: Select all

File Name          Description

TACICONS.BMP       Unit Type Icons -- Normal
STACKICN.BMP       Unit Class Icons -- Stacked

FLAGS.BMP          Combatant Identification Icons

TACMAP_DRY.BMP     Terrain Type Icons -- Dry Ground Conditions
TACMAP_FROZEN.BMP  Terrain Type Icons -- Frozen Ground Conditions
TACMAP_MUDDY.BMP   Terrain Type Icons -- Muddy Ground Conditions

EXPLODE.BMP        Explosion Graphics
HEXSIDES.BMP       Hexside Type Graphics

Depending on the type and extent of the custom graphics content that was input into the conversion:

Code: Select all

*.SHP ==> *.BMP

unambiguously points to the converted custom material (if any).

Careful though:

Code: Select all

TACMAP.SHP ==> TACMAP_DRY.BMP, TACMAP_FROZEN.BMP, TACMAP_MUDDY.BMP

Folder "SCENARIO" Gets... Populated

Prior to the conversion, this folder contained just one file:

Code: Select all

PG.PGCAM

The file remains... unmolested. However, the folder now contains THIRTY EIGHT (38) file triplets:

Code: Select all

0??.PGSCN
MAP??.SET
MAP??.STM

Technically speaking, the conversion ties together the following files:

Code: Select all

GAME0??.SCN and SCENSTAT.BIN     ==>     0??.PGSCN
MAP??.SET                        ==>     MAP??.SET
MAP??.STM                        ==>     MAP??.STM

It is important to internalize the fact that the conversion leaves files

Code: Select all

MAP??.SET
MAP??.STM

... unmolested ! However, newly generated files

Code: Select all

0??.PGSCN

ARE native to PGF !

The folder also contains file

Code: Select all

MAPNAMES.STR

which also remains... unmolested !

On the other hand, newly generated file

Code: Select all

EQUIPMENT.PGEQP

IS native to PGF. Technically speaking, the conversion ties together the following files:

Code: Select all

PANZEQUP.EQP and PANZER.EXE     ==>     EQUIPMENT.PGEQP

TO SUMMARIZE: ONLY OUTPUT FILES

Code: Select all

0??.PGSCN
EQUIPMENT.PGEQP

ARE TRULY GENERATED BY THE CONTENT CONVERSION.