[PHost Logo]©

The PVCR Program
The Portable Host



The PHOST VCR Program (PVCR) is a DOS-only program that is used to graphically display the outcome of battles generated by PHOST, just like the original VCR program does for HOST-generated battles. PVCR can also be used by battle simulator programs for statistics gathering, and also directly by the player for quick viewing of battles and experimentation with combat parameters.

For information on installing PVCR, please refer to the Viewing Battles section of the "Playing with PHOST" page.

Note that battles executed by PVCR will not end in the same conclusion as if executed by the original VCR program. The combat algorithms, although similar, are different and lead to different results. The battle mechanics, however, are highly configurable and a good approximation to original VCR-style combat can be achieved. For players who want to experiment with different combat configurations, the external battle simulator BSIM v2.2[Remote] by Thomas Voigt provides a simple interface to PVCR (in fact, this program has PVCR built in to it).

Developers of battle simulation programs may want to note that PVCR makes use of battle-related configuration parameters stored in a PCONFIG.SRC file. PVCR will not run correctly unless a PCONFIG.SRC file is found that corresponds to the same file used by PHOST in generating the battle. Developers familiar with the mechanism used in PHOST 2.x for sending configuration information within the VCR files themselves should note that this mechanism is no longer in practice in PHOST 3.

PVCR can return the results of battles in a predefined memory area. Battle simulator programs can use these results to compile statistics on battles. See the section on battle specifications below.

Back to the index

Interface Files

PVCR uses the same files that the original VCR uses (VCR*.DAT, VCRINIT.TMP) unless overridden by command-line parameters (see below). PVCR will also generate a log file named PVCR.LOG in the game subdirectory. If an error occurs during execution, inspecting the PVCR.LOG file will reveal the nature of the error.

Back to the index

Command-Line Invocation

Normally, PVCR is invoked automatically by the DOS Planets program or VPA to display the battles from the current turn. PVCR can also be invoked manually from the command line. You may wish to do this if:

  1. You're using WinPlan (in this case, command-line invocation is mandatory)
  2. You'd like to view your battles without having to run the client program
  3. You want to view other people's battles which they have sent to you
  4. The running battle stats come out garbled. To work around this problem, you want to pass the -F option to PVCR.
  5. You want to experiment with the combat-related configuration parameters (see the Combat Parameters section of the "Configuration Parameters" page).

The command line syntax for PVCR is:

vcr [-f] [-F] [-p Player] [-s | -r Program] [-t time] [-v|-h] [-b N] [GameDir [RootDir]]

Simply typing PVCR with no options causes the following to happen:

  1. PVCR will look for a file named VCRINIT.TMP in the directory specified by GameDir. If GameDir is not specified, then the file must be located in the current directory.

  2. The VCRINIT.TMP file is normally generated by the DOS Planets program or by a simulator. It contains information regarding the player number of the VCR data file. PVCR will then attempt to open the VCR data file (VCR*.DAT, for example VCR4.DAT) first in the GameDir directory or, if GameDir is unspecified, in the current directory.

  3. The VCR*.DAT file is inspected and determined to be a HOST-generated or PHOST-generated battle. If it is a HOST-generated battle then PVCR terminates itself and loads the program VCROLD.EXE, assumed to reside in the same directory as VCR, to run the battle. VCROLD automatically loads the PLANETS.EXE program when it ends.

  4. If the battle is PHOST-generated, then PVCR will search the game directory for a PCONFIG.SRC file and then display the battles. If no PCONFIG.SRC file is found, default battle parameters will be used but there will then be the possibility that an incorrect battle outcome will be observed.

  5. Once the player exits the PVCR program (if it was a PHOST-generated battle), the PLANETS.EXE program is automatically executed. Note that this will also happen for HOST-generated battles since the VCR program does the exact same thing.

The above sequence of events is designed to be compatible with what the DOS Planets program expects, not with what a player generally wants to have happen when invoking PVCR from the command line. The command-line options are meant to make this form of invocation more useful.

The -f option (Force) overrides step 3 above. Using this option forces PVCR to display the battle even if it is determined that the battle is HOST-generated. You can use this switch to compare the behavior of PVCR and VCROLD on the same battle (generated by HOST or by a simulator).

The -p option (Player Select) overrides step 2 above. This option causes PVCR to ignore the presence (or absence) of the VCRINIT.TMP file and to try to open the file VCRn.DAT where n is the argument to the -p option. For example:

vcr -p 10

will cause PVCR to look for the file VCR10.DAT regardless of the contents of VCRINIT.TMP.

A special case of the above option exists for a player number of 0. If player 0 is specified then PVCR looks for a file named VCR.HST. This file is generated by PHOST (or HOST) but is not transmitted to players. Using this option, a host can review all of the battles in a turn with only one invocation of PVCR.

The -s option (Standalone) overrides step 5 above. When this option is specified, then PVCR will not reload the PLANETS.EXE program, it will simply exit back to the DOS command line. ==>  You will normally always want to specify this option when invoking PVCR from the command line.

The -r option (Reload Program) specifies the program to reload when PVCR is finished (normally, PVCR reloads PLANETS.EXE unless the -s option is specified). This option is not meant for player use but is instead meant for simulator programs. A simulator program can set up a battle, invoke PVCR to display it, and then direct PVCR to automatically reload the simulator program when it is done. Alternatively, the simulator program can keep itself in memory and simply spawn PVCR with the -s switch.

The -t option specifies the initial time scale of playback. By default, this value is 15. The time scale of playback is an arbitrary positive number that determines the speed with which the battle is displayed. Smaller values of time scale result in faster battle displays. This parameter should be kept in the range [1,20].

The -b option allows you to specify a single battle to view. The number following this option is the battle to view, in the range 1 through N where N is the number of battles that were fought this turn. PVCR will jump directly to the battle display and will exit once the battle display is complete.

The -v option displays the version number of PVCR and exits the program.

The -h option displays a brief summary of PVCR's command line usage before exiting.

The -F option will cause PVCR not to use the ROM BIOS font for displaying the running battle stats. The BGI library, on which PVCR is based, has a bug which makes the text come out garbled under various environments, Windows ME and DOSEMU being some of the most prominent ones (this is the same problem that worries VPA, too). This option is new in PVCR 3.3e.

The GameDir parameter specifies the game directory i.e., the directory in which the battle data files (VCRINIT.TMP, VCR*.DAT, PCONFIG.SRC, RACE.NM) are expected to reside. If this parameter is not specified, then the game directory is assumed to be the current directory.

The RootDir parameter specifies the master directory i.e., the directory in which the VGA Planets data files (e.g., BEAMSPEC.DAT, HULLSPEC.DAT, RESOURCE.PLN, etc.) are expected to be found. If this parameter is not specified, then the current directory is assumed to be the master directory.


vcr -s -p 1 game1

Review the battles for the Federation (player 1) for the game in directory game1. This directory contains a PHOST game.

vcr -s -p 11 -f game2

Review the battles for the Colonies (player 11) for the game in directory game2. This game is a HOST game hence the -f flag must be specified for PVCR to perform the combat.

vcr -s -f -p 5 . \planets

Review the battles for the Privateers for the game in the current directory. The master files are located in the \PLANETS directory.

Back to the index

Viewing Battles

Once PVCR is invoked, a screen appears showing the first battle available for viewing. If more than one battle is available, the up-arrow and down-arrow keys can be used to select the battle to view. The ENTER key begins the display of the currently selected battle. The ESCAPE key exits from PVCR.

Once a battle is selected for viewing, the combatants are drawn on the screen along with their related statistics. Pressing the ENTER key begins the battle display. While the battle is in progress, pressing the SPACEBAR puts PVCR in single-step mode. Each subsequent press of the SPACEBAR advances the battle by one time step. Pressing ENTER returns the battle to a continuous display. Pressing ESCAPE terminates the battle and redisplays the battle selection screen.

The plus + and minus - keys can be used to speed up or slow down the display of a battle after it has begun.

Back to the index

Battle Specifications

This section describes the mechanism by which external programs specify battles for PVCR to display, and the mechanism by which PVCR can return the results of those battles to the calling program.

Input Specification

PVCR reads VCR*.DAT or VCR.HST files to obtain the specifications of battles that it is to perform and display. This section describes the format of those files.

The battle specification file has the following format:

where NumBattles is a 16-bit quantity indicating the number of battles specified in the file. This quantity is followed by an array of structures of type BattleSpec (described below). The number of elements in this array is NumBattles.

Each BattleSpec structure has the following format:

The RandomSeed specifies the random seed for the battle. A battle with the same specifications and the same random seed will always come to the same conclusion. A battle with a different random seed may come to a different conclusion. The value of Key is normally 0 for HOST-generated battles but can take on a different value for PHOST-generated battles. In fact, Key is used to distinguish between HOST-generated and PHOST-generated battles. If the numeric sum of RandomSeed plus Key equals 48879 (modulo 65536) in the first battle of the specification file, then all battles in the file are considered to have been generated by PHOST.

The PlanetBitmap element indicates the bitmap number in RESOURCE.PLN to use to display the planet, if the planet is a combatant. If RightIsPlanet is non-zero, then the combatant on the right side is a planet instead of a ship.

The MassLeft and MassRight parameters indicate the combat mass of the ships (or planet) on the left and right side of the battle, respectively. Similarly, ShieldLeft and ShieldRight specify the shield status of the combatants. ShipLeftSpec and ShipRightSpec specify the remaining parameters of the combatants. These structures are of type ShipSpec and are detailed below:

           STRUCTURE ShipSpec
               CHAR   Name[20]
               WORD   Damage
               WORD   Crew
               WORD   ShipID
               BYTE   Player
               BYTE   Race            -- Note!
               BYTE   BitmapNumber
               BYTE   HullNumber      -- Note!
               WORD   BeamTech
               WORD   BeamNumber
               WORD   FighterBays
               WORD   TubeTech
               WORD   Ammunition
               WORD   Tubes

The Name element is a 20-byte array containing the ship or planet name. Damage describes the amount of existing damage to the ship or planet, Crew contains the number of crew members (meaningful for ships only). Similarly, ShipID, BeamTech, BeamNumber, FighterBays, and TubeTech all describe their respective ship or planet attributes.

The Player field contains the owner of the object while the Race field contains the race he's playing (see the PlayerRace option). When the race equals the player number, the Race field is zero. In HOST-generated battles, the Race field is always zero, too, even when an "SRACE"-type host is used (actually, in HOST, the Player member occupies 16 bits).

The BitmapNumber member indicates the number of the bitmap in RESOURCE.PLN to use to display the ship. The HullNumber member indicates the hull number of the involved ship. This member is 0 for planets. Note that the inclusion of a ship's hull number in a battle specification is specific to PHOST. In HOST-generated battles, the BitmapNumber member occupies 16 bits (instead of PHOST's 8 bits) and no hull number information is conveyed.

The Ammunition member describes the number of fighters available if the ship/planet has fighter bays, or the number of torpedoes available if the ship has torpedo tubes.

For ships, the Tubes member describes the number of torpedo tubes mounted on the ship. Planets, however, may have both fighter bays and torpedo tubes when PHOST sets up a battle with the PlanetsHaveTubes option enabled. In this case, the elements of the above structure have slightly different meanings:

Output Specification

Normally, PVCR is used simply to display a battle graphically. PVCR can also be used to return the results of a battle in binary format (for use by external programs that wish to gather combat statistics). A special command-line option is used to set up a data transfer area in which PVCR will place its results.

If PVCR is invoked with the -X option, then the parameter following the -X must specify a segment:offset pointer to a data transfer area. For example:

vcr -s -p 0 -X 3F00:0D55

Note that the segment and offset are specified in hexadecimal notation. This data transfer area must have been allocated in low memory prior to invoking PVCR and must also conform to certain requirements. Specifically, this area must be formatted as follows:

Key is a 32-bit quantity that must be set to 1033FE51h. This key provides a check mechanism for PVCR so that accidental overwrites of uninitialized memory locations do not occur. The NumResults member indicates the number of result areas that have been allocated in the ResultArea array. Fewer results than battles may be allocated; PVCR will only store results for battles 0 through NumResults-1 or NumBattles-1, whichever is less.

Each element of the ResultArea array indicates one battle result. This result area must have the following structure:

           STRUCTURE ResultArea
               WORD   IsValid
               WORD   ShieldsLeft
               WORD   ShieldsRight
               WORD   DamageLeft
               WORD   DamageRight
               WORD   FightersLeft
               WORD   FightersRight
               WORD   TorpsLeft
               WORD   TorpsRight
               WORD   CrewLeft
               WORD   CrewRight
               WORD   OutcomeLeft
               WORD   OutcomeRight

NOTE: All of the result areas must be pre-initialized to 0 before invoking PVCR.

The IsValid member is set to 1 by PVCR if the remaining elements of the result are valid (i.e., represent the outcome of the battle). PVCR will only store results if the battle was actually viewed. Also, PVCR will store the results as of the time when the battle was stopped. If the battle came to its natural conclusion, then the results reflect the true battle outcome. If the user terminated the battle prematurely, the results reflect the state of the combatants at the time of this termination.

The remaining elements are self-explanatory. DamageLeft and DamageRight for example describe the amount of damage suffered by the combatant on the left and right side of the battle, respectively. The OutcomeLeft and OutcomeRight elements are to be interpreted as follows:

Outcome Interpretation
Combatant survived and won the battle
Combatant was captured
Combatant was destroyed
Combatant finished the battle with no offensive capability

Once PVCR terminates, then the Key member of the transfer area is set to the value 51FE3310h. This prevents the transfer area from being inadvertently used in the future without prior preparation, and also indicates to the calling program that the results can be correctly interpreted (i.e., PVCR exited without errors).

Back to the index

This document is maintained by The Portable Host Project[Remote] (support@phost.de).

Last updated 16 February, 2002