You are on page 1of 8

****************************

* PG FOREVER MODDING GUIDE *


****************************

==================
General principles
==================

There are 2 important things to understand about the PG Forever (PGF) data
organization.

1. Game folders and default folder


----------------------------------

PGF allows the user to have several different games installed side-by-side and
sharing the same PGF engine. Some of the games are already included in the main PGF
package (for example, PG and AG), other games can be downloaded and installed
separately. Each game has its very own folder next to the game's primary
PGForever.exe file. For example, the classical Panzer General game resides in pg
folder, and Allied General - in ag folder.

When PGF needs to load some game file (equipment table, campaign file etc.), it
looks in the game's folder first. But if the required file is not found, the game
tries to load it from 'default' folder instead. This scheme allows to share certain
files between games. For example, all games in PGF package share the same sound
effects, and so these are located in default\Sound folder. PG and AG share the same
standard set of unit icons and tiles, and these are also taken from the default
folder. On the other hand, games like Kauser General and K.u.k. General use their
own sets of unit icons, and so include them in their own folders (kaiser\Graphics
and kuk\Graphics respectively).

Scenarios are exceptions from the general rule: they are never looked for in the
default folder. Each game must have its own set of scenarios. The reason is that
the game enumerates all available scenarios to show them in the scenario list (in
the main menu). If it could take scenarios from the default folder as well, they
would show up in all games.

Internally, all game folders (and default folder as well) use the same subfolder
structure:

- Graphics. Contains all graphics files (in BMP format).


- Log. Contains the logs written by the game.
- Replay. Contains replay files saved by the player.
- Save. Contains saved games.
- Scenario. This is a very important folder which contains all the game's useful
content - equipment table, scenarios, maps, briefings and campaign file.
- UI. This folder contains the UI layout files. For now, most games reuse the
standard PGF UI layout (included in default\UI folder). However, in the future each
game may get its own, unique look-and-feel.

2. Tab-separated unicode text files


-----------------------------------

PGF uses a number of different data files: equipment table, campaign file, scenario
file etc. As I move more and more hard-coded stuff from the game's EXE to external
data files, this number will increase. Although all data files are different, most
of them use the same scheme of data organization: these are tab-separated unicode
text files.
- Each such file contains a number of tables separated by one or more empty lines.
- All columns in a table are separated by a single tab character. Multiple tabs,
spaces or any other separators are not supported.
- Lines starting with # are considered comments and are completely ignored. Often
the comments are used to provide labels for the columns in the tables.
- The files use UTF-16 encoding. This makes localizing data files very easy.

Since the files are plain text, they can be edited in any text editor, including
Notepad. But a better way to work with such files is in Microsoft Excel. Excel
understands tab characters, and presents the contents of the file in a convenient
tabular format. While working with the file in Excel, you can change the widths of
any columns at will - this will not effect the resulting file in any way.

Please keep in mind that empty lines are very important: they specify where a table
ends and the next one begins. So, do not remove empty lines or insert new empty
lines where they were not before. This may render the whole file unreadable.

=============
Campaign file
=============

Overview: Campaign file describes all campaigns of a given game. This file is
unique for PGF, because in the original game certain aspects of the campaigns were
hard-coded in the game EXE and were very hard (if not impossible) to modify.

Location: <game folder>\Scenario\pg.pgcam

Format: tab-separated unicode text file

Campaign file consists of 5 tables.

1. Format version
-----------------

This is by far the simplest table in the file: it consists of just one cell. This
cell speficies the version of the campaign file format. For now, the only valid
version is 1. In the future, if the campaign file format changes, this field will
be used to preserve backwards compatibility with the old campaigns crteated for
PGF.

2. Entry points
---------------

This table specifies all the starting points for the campaign. The list of starting
points is what the user sees in the main manu on the Campaigns tab. For example,
for the stock PG campaign entry points are: 1939, 1941 West, 1941 East, 1943 West
and 1943 East.

Entry points table has 6 columns.

- Name. User-friendly name of the entry point (as shown in the main menu).
- Campaign path label. Specifies the point in the campaign tree from where the
campaign starts. Campaign path labels will be explained later.
- Description. Description of the entry point (as shown in the main menu below the
name).
- Campaign side. Side of the player when playing the campaign. 0=Axis, 1=Allies. It
is possible to have campaigns for both Axis and Allies in the same file, and in
this case different entry points will use different sides.
- Campaign nation. This is the nation the player will play the campaign for. Only
units of this nation can be bought to player's core. Units of all other nations are
automatically bouhgt as auxiliaries.
- Free elite replacements. This flag specifies if the game should give the player
free elite replacements of his core units between missions.

Here is a fragment from the stock PG campaign file.

# Entry points
# Name Label in campaign path Description Side Nation Free elite
replacements
1939 Poland Germany launches a series of blitzkrieg attacks in Europe,
beginning with Poland. 0 8 1

This row specifies the 1939 campaign. Campaign tree lable is Poland, because this
is where this campaign starts. Campaign side is 0 (Axis), and campaign nation is 8
(Germany). Free elite replacements are provided because this is the way the
original game worked.

3. Outcomes
-----------

This table specifies all possible scenario outcomes used in this particular
campaign. It has just one column for the outcome name. This is the name that will
be displayed to the player in the game, so it should be user-friendly.

Here is the outcome list from the stock PG campaign:

# Outcomes
MAJOR VICTORY
MINOR VICTORY
ALLIED VICTORY

In PGF you can have any number of outcomes you want. For example, you can model the
PG2 scheme (brilliant victory/victory/tactical victory), or introduce a completely
new one (e. g. major victory, minor victory, draw, minor defeat and minor defeat).

The last outcome is special because it is used by default, if no other outcomes


match. This means that usually this will be the most unfavorable outcome for the
player. For example:

if the player captured all VHs 10 turns before deadline -> major victory
else, if the player captured all VHs on the last turn -> minor victory
else (no more conditions are checked) -> loss

4. Scenarios
------------

This table lists all scenarios used by the campaign. It has 2 columns, plus 3
column for each outcome (except the last one). The meaning of the columns is as
follows.

- Name. This name will be used to reference the scenario from the campaign tree. It
will NOT be displayed anywhere in the game UI, and so may not be user-friendly.
- Scenario file. Name of the pgscn file containing the scenario.

The following 3 columns specify the victory conditions, and are repeated for each
possible outcome, except the last one. As explained above, the last outcome is used
by default, no conditions are checked for it, so there is no point in specifying
them. Victory conditions are always specified from player's side point of view. In
campaign mode, victory conditions specified in the campaign file for a given
scenario completely override victory conditions specified in the scenario file
itself.

- Remaining turns. The scenario must be won (by capturing all VHs or eliminating
all enemy units) at least this number of turns earlier than the scenario would
normally end. Current turn is included in the remaining turns count. So, if we
capture all VHs on the last turn, remaining turns count is 1. If the scenario has
10 turns and we finish it in the 8th turn, remaining turns count is 3. And so on.
- Number of objectives to hold. This column is used more often with defensive
scenarios, but it can be used in offensive scenarios as well (as in Ardennes
scenario from PG campaign).
- Mandatory objectives. This column complements the previous one and specifies the
coordinates of the exact VHs which the player must hold. Each coordinate is
enclosed in brackets, and the coordinates are separated by the colon character.
There should no spaces between the coordinates.

If the number of objectives to hold (N) is less than the number of mandatory
objectives listed in the third column, the playr must hold ANY N OBJECTIVES FROM
THE MANDATORY OBJECTIVES LIST.

To make all this clear, let's consider several examples from the stock PG campaign.
There are 8 columns here (2, plus 3 for each of the two victory types - major and
minor).

POLAND 001.pgscn 3 0 1 0

In Poland we get a major victory if we win with at least 3 turns remaining. Since
the total turn count in this scenario is 10, we can get the major on the 8th turn
latest. To get a minor, we must capture all objectives on the last turn latest.
Failure to do this results in a loss.

TORCH 012.pgscn 0 6 (27:5) 0 3 (27:5)

Torch is a defensive scenario, and our goal as an Axis player is to hold Tunis
(27:5) and at least 2 other objectives. Holding Tunis and at least 5 other
objectives gives us major. Failure to meet these criteria yields loss.

D-DAY 015.pgscn 0 3 (11:7)(22:28)(43:27) 0 2 (11:7)(22:28)


(43:27)

D-Day is another example of a defensive scenario. Here we must hold all 3 of our
initial objectives to get a major. Minor victory is granted if we hold ANY TWO OF
THE THREE MANDATORY OBJECTIVES (number of objectives to hold is less than the
number of mandatory objectives in the list). Taking one of the two Port Facilities
across the Channel will not count - mandatory objectives list is still, well,
mandatory. We just don't need to hold ALL of them to get a minor.

ARDENNES 017.pgscn 0 8 0 7 (16:16)(26:4)(27:21)(39:21)


(48:8)(54:14)(59:18)

This is an offensive scenario, but, unlike many other Axis offensives, it is ruled
by VHs we can get, not by the turn count. We get a major if we capture all 8 VHs on
the map. To get a minor, we must capture ALL OBJECTIVES EXCEPT BRUSSELS. That's why
it is necessary to enumerate all objectives except Brussels in the mandatory
objectives list. If we only specified 7 objectives to hold, the player would be
able to get Brussels and any other 6 objectives to get a minor, and that's not what
we want.
5. Campaign path
----------------

This is probably the most important table in the file, as it drives the campaign
logic. The table is quite extensive: it contains 3 columns, plus 3 for each
possible outcome. This time, all outcomes are included, as we need to specify
campaign path for the loss case as well.

Each row in the campaign path table describes a single scenario played in the
course of the campaign. The meaning of the columns is as follows.

- Campaign path label. This is a label used to reference this row from other rows
in the table, or from the Entry points table (see above). In most cases you can
think of the label as one more alias for a scenario, but there are a few nuances
here which I'll explain in a moment.
- Scenario. Name of the scenario to play (as specified in the Scenarios table
described above).
- Pre-scenario briefing. Briefings are not included in the campaign file directly,
because they are quite large and would bloat up the file considerably. Instead,
each briefing is stored in its own file with pgbrf extension. This column specifies
the name of the pgbrf file to use.

The following 3 columns are repeated for each possible outcome.


- Next label. Specifies the campaign path label of the next scenario we'll play, or
"END" if the campaign ends. In some cases this cell can be left empty. In this case
the user will have to choose the next scenario himself. In this case all possible
options must be included in the post-scenario briefing, or the campaign will end.
- Prestige. How much prestige we get for this outcome.
- Post-scenario briefing. Name of the pgbrf file used for this outcome.

As we can see, in most cases the user will see 2 briefings: a post-scenario
briefing for the scenario he's just finished, and a pre-scenario briefing for the
next scenario he will play in the campaign. Any of these briefings can be omitted.
For example, in AG the post-scenario briefings include information about the next
scenario as well. In this case the pre-scenario briefings are used only for the
four scenarios starting the four Allied campaigns (because there is no previous
scenario when you start a campaign).

The structure of the campaign path table should be pretty clear, but one aspect
requires some more explanation, and that is the campaign path labels. Why do we
need them, in addition to the actual scenario names?

Let's consider the following example. In AG we can play the Western Europe campaign
for British or American side. British campaign starts at Mareth Line. American
campaign starts at Torch and joins the path of the British campaign after
Kasserine. So, the path is:

<GB start> -> Mareth Line -> ...


<US start> -> Torch -> Kasserine -> Mareth Line -> ...

Do you see a problem here? After Mareth Line we have lost the campaign context. We
no longer know if it is a british or american campaign. Later, when the GB campaign
branches to Meuse and US campaign - to Moselle, we have no idea what path to take.
So, we introduce different labels for the same scenarios when played as GB or US.
Here is a fragment from the AG campaign file:

Mareth Line(GB) 0003.pgbrf Mareth Line ...


Torch(US) 0002.pgbrf Torch ...
Kasserine(US) Kasserine ...
Mareth Line(US) Mareth Line ...

As we can see, both Mareth Line(GB) and Mareth Line(US) use the same scenario
(Mareth Line), but they remain different labels used to specify different campaign
subtrees. And now, let's look at the Entry point table from the same campaign:

North Africa Sidi Barrani ...


Western Europe/American Torch(US) ...
Western Europe/British Mareth Line(GB) ...
Russia Finland ...

The British and American campaigns use their specialized labels (GB and US) in
order to direct the campaign down the right path from the very begining.

So, the purpose of the campaign path labels is to create different campaign
subtrees using the same scenarios. The same idea is used to specify "No east/no
west" conditions in the stock PG campaign. But the labels can be useful in some
other cases as well. For example, in AG British and American campaigns use slightly
different briefings. So, even if these campaigns shared exactly the same campaign
path, it might make sense to separate them and specify different briefing for each.

==============
Briefing files
==============

Briefing files have pgbrf extension and reside in the game's Scenario folder. Each
file contains just one briefing. pgbrf files are plain text files and as such can
be edited in any text editor (like Notepad). Unlike the original PG, it is possible
to use HTML tags to layout the text in briefing files. For example, enclosing text
between <b> and </b> makes it bold. <p> and </p> tags specify the borders of a
paragraph. And so on.

Here is an example of a simple briefing taken from AG (0001.pgbrf):

=== Cut ===


<p>Sir:</p>
<p>As you well know, since September, the Italians have pushed as far east as Sidi
Barrani. Whilst they may have suspended their advance, their presence remains a
threat to the stability of the region and to our reserves of petrol.</p>
<p>High Command has instructed us to proceed at top gear with the resources we have
to hand, and dislodge the Italians from their Libyan colonies.</p>
=== Cut ===

As we can see, there are a few <p> tags to designate the three paragraphs in the
text. Other than that, it is just a plain text file. But using HTML allows to
create much more advanced briefings than that. For example, if you want to include
a little fancy image in your briefing called berlin.png, all you needto do is add
the following tag:

<img src="berlin.png" />

You can also use lists with bullets, tables, various fonts and text colors etc.
Describing all possible HTML tags is outside the scope of this document, but this
information is very easy to find on the Web.

Besides the informative function, the briefings can be used to prompt the user for
the next scenario he wants to play. There are a few special tages for that, which
are easier to explain by example.
=== Cut ===
<p>Congratulations on your outstanding victory in France. My humiliation in 1918 is
avenged.</p>
<p>We are preparing for operations next year against the British in North Africa as
well as against Yugoslavia and Greece. Your performance to date has been
outstanding and we will be happy to allow you to choose your next operation for
yourself and your army.</p>
<p>Would you prefer to fight next in North Africa or in the Balkans?</p>
<p>
<a href="North_Africa">North Africa</a><br/>
<a href="Balkans">Balkans</a>
</p>
=== Cut ===

This briefing is displayed after mafor victory in France (PG stock campaign). The
player can proceed to North Africa or Balkans at will. href value specifies the
campaign tree label for each option, while the text between <a> and </a> is a user
friendly text that the player will see in the briefing.

Another example:

=== Cut ===


<p>Sir:</p>
<p>You have given a good account of yourself. High Command judges that you were
bang on target in your appraisal of Jerry's predicament. The PM has even alluded to
the prospect of Birthday Honours.</p>
<p>In light of this exceptional accomplishment, High Command will no doubt offer
you the opportunity to lead the combined Allied forces in the campaign to liberate
Europe. If so, I should look forward to our serving together again.</p>
<p>In either case, it has been a privilege. The best of luck to you, sir.</p>
<p>
<a href="Mareth Line(GB)">Proceed to Western Europe</a><br/>
<a href="END">End campaign</a>
</p>
=== Cut ===

This briefing is displayed in AG at the end of North Africa campaign. The player
can stop here, or proceed to the Western Europe campaign instead. Note href="END"
for the second option. As was explained in the Campaign File section, END is a
special campaign tree label meaning end of the campaign. As we can see, this
special option can be used in briefings as well.

Finally, let's consider a more advanced example.

=== Cut ===


<p>Your smashing success in overrunning the Russian frontier armies and taking
Smolensk proves that yet again that you are the premier Panzer General in the
world.</p>
<p>We have reached a critical juncture in our war in Russia. Many generals believe
that we should divert your forces to assist Army Group South in its drive to
capture Kiev. There does appear to be an opportunity to trap and destroy a large
part of the Soviet Army in this area. Other generals believe we should ignore the
south and instead send your forces driving directly toward Moscow as soon as
supplies can be brought forward, in order to reach there before winter. They
believe a move toward Kiev will delay the drive on Moscow and may cause us to fail
at the city gates. It appears that high command is leaning toward a drive on Kiev.
Your opinion on this matter could sway their decision toward Moscow, but it would
surely cost you some of your prestige to voice your opinion regarding such a key
decision.</p>
<p>Would you like to spend 1500 of your prestige points to convince high command to
allow you to avoid an attack on Kiev and instead continue your drive to Moscow?</p>
<p>
<a -prestige="1500" href="Early_Moscow">Yes</a><br/>
<a href="Kiev">No</a>
</p>
=== Cut ===

This briefing is used in PG after a major victory in Barbarossa. The player can
proceed to Kiev or Early Moscow, but the latter option will cost the player some
prestige. This is specified by an additional -prestige attribute of the <a> tag. Of
course, prestige amount can be arbitrary.

Note that the value of -prestige tag is an internal implementation detail of this
briefing. It is not shown to the user automatically. So, to avoid confusion, the
briefing text should describe the options and how much it will cost to use them (as
is done in the briefing text above).