![[PHost Logo]](logo.gif){kind=logo} ©
|
The PVCR Program
|
| ©
|
The PVCR Program
|
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]](remote.gif){kind=small}
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.
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.
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:
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:
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.
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.
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.
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:
STRUCTURE BattleHeader
WORD NumBattles
STRUCT BattleSpec[NumBattles]
END
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:
STRUCTURE BattleSpec
WORD RandomSeed
WORD Key
WORD PlanetBitmap
WORD RightIsPlanet
WORD MassLeft
WORD MassRight
STRUCT ShipLeftSpec
STRUCT ShipRightSpec
WORD ShieldLeft
WORD ShieldRight
END
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
END
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:
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:
STRUCTURE TransferArea
LONG Key
WORD NumResults
STRUCT ResultArea[NumResults]
END
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
END
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).
(support@phost.de).