Savegame File Naming Conventions

Author: Fyron
Date: Sep 14, 2013 7:54 PM
Category: PBW2 Knowledge Base
Posts: 1

This article outlines the file naming conventions associated with hosted games. The rules for each game type are defined in the game type definitions.

The base name for many of a game's files starts with the "game_code" property. For example, a game named "Adamant Rumble" might have a game_code of "adrum". The core savegame file for this game might be named "adrum.gam". All file patterns that begin with a "." or a "_" will be automatically prefixed with the game code. It is assumed that such patterns refer to files beginning with the base savegame name.

All file patterns are case-sensitive. A file "adrum.GAM" is not considered an acceptable file.

Below, we will discuss how PBW2 interprets the rules during various savegame file operations.

Host Uploads Game Setup Files

Some games can use setup files before the first turn is created. Games like SE5 can save game setup options to a file. Server-based games like THANCS require the game host to upload a host turn 0 file to the server for the game to be created.

Files that should used by the players to create their empire files can be specified in the "player setup files" pattern. For example, this pattern might be used for SE5's game options file:


Files that should only be used by the host/autohost to generate the first turn can be specified in the "host setup files" pattern. For example, this pattern might be used for THANCS' host turn 0 player file:


Host Uploads Next Turn

A game host can either upload a .gam file, or an archive file that contains the .gam file and any extra files. The only rule that applies during this action is that the base save file must be present. The "process files" pattern must include a pattern for the savegame file, usually ".gam".

PBW2 also supports games that use the turn number in the base savegame file name. For these types of games, the turn number set on PBW2 must match exactly with the in-game turn number. If an Event Horizon game "eh" is on turn 5, its file name should be "eh_5.gam", and the game entry on PBW2 should be on turn 5. In this case, the .gam file pattern in the "process files" pattern should contain the {{turn}} token. It should look something like "_{{turn}}.gam".

Host Downloads Current Turn for Processing

When the host downloads the current turn, PBW2 creates a rar archive containing the base savegame file, any files ending in ".plr", and any files that match the set of strings in the "host process" pattern. This pattern contains a pipe-delimited set of bash shell file expansion patterns.

For example, this pattern might be used for SE4:


SE4 creates events and stats text files for each player. Each time a turn is processed, it adds some new lines of data to these files. Thus, they need to be downloaded with the savegame file. For a game with a game code of "adrum," a sample turn archive for the 13th turn might need to include these files:

  • adrum.gam
  • adrum_0001.plr
  • adrum_0002.plr
  • adrum_plr_1_events.txt
  • adrum_plr_2_events.txt
  • adrum_plr_1_stats.txt
  • adrum_plr_2_stats.txt

When PBW2 builds the rar archive for SE4, it might use a command that looks like this to capture those files:

rar a adrum_13.rar adrum.gam adrum*.plr adrum_plr_*_events.txt adrum_plr_*_stats.txt

If a game uses turn numbers in the savegame file names, the pattern for the savegame file in the process files pattern can include a {{turn}} token. This token will be replaced with the current turn number in the rar command. For example, Event Horizon has this process pattern:


When PBW2 builds the rar archive for EH, it might use a command that looks like this to capture those files:

rar a eh_13.rar eh_13.gam eh*.plr

Player Uploads Order File

After a player plays a turn, the game will automatically generate an order file. Since these files have predictable patterns, PBW2 requires that each player upload a correctly named file. This can help to prevent uploading the wrong plr file for players that are also hosts, for example.

The expected player order file name is generated from the "player order file" pattern. This pattern can contain a few tokens that will be replaced by current game data. For example, the order pattern for Event Horizon might be:


PBW2 will add this to the game_code property for the game. It will the replace the {{turn}} token with the current turn number, and the {{player}} token with the player's number. Some games require certain portions of the file names to be zero-padded. This is specified in the pattern by including the padded string length in parenthesis at the end of the token. An actual player order file for player 4 of a game "eh" might look like this:


Some games might allow the host to upload plr files from time to time. This file should typically be treated as a player 0. To enable support for a host player, simply tick the "Has Host Player" box.

Player Downloads Current Turn

When a player downloads the current turn, PBW2 generates a RAR archive that contains all of the files specified by the "common files" and the "player turn files" patterns.

The "common files" pattern is a pipe-delimited list of bash shell file expansion patterns, similar to the "host process file" pattern.

The "player turn files" pattern is a pipe-delimited list of tokenized file patterns, similar to the "player order file" pattern.