THE PORTABLE HOST PVCR -- Portable Host VCR Program Version 3.2.2.12 This file provides information regarding the usage of the PVCR program. This program is a DOS-only program used by players for viewing combat results. PVCR will display both HOST-generated and PHOST-generated battles. This document also describes the mechanism by which battles can be specified to PVCR and results returned. This information may be useful for designers of battle simulators and other utilities. Note that PVCR versions 2.6 and higher will correctly display battles displayed by both major versions of PHOST, versions 3.15.1.x and 3.2.2.x. Players may use the same PVCR program in all of their games, regardless of version. However, PVCR versions v1.x will not display battles generated by PHOST 3.2.2.x. It is therefore suggested that all players upgrade to the latest v2.x version of PVCR. PVCR can be used to view PHOST-generated battles for players using WinPlan. In this case, PVCR must be invoked in stand-alone mode (using the -s option) from the DOS command line in a full-screen window. If the player does not have a copy of the RESOURCE.PLN file that comes with DOS Planets (both shareware and registered versions) then the player must obtain this file and place it in the main WinPlan directory for PVCR to work. See Common Question #17 in the FAQ.DOC file for more info. This file is divided into the following sections: * Introduction * Quick Installation * Files * Invocation * Viewing Battles * Battle Specifications * Configuration Information Introduction ============ The Portable Host 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. 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 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 contained within VCR files. This configuration information is stored as an extra battle at the end of the VCR file when the VCR file is generated by PHOST. The format of this configuration information section is documented near the end of this file in the "Configuration Information" section. Also, 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. Quick Installation ================== The PVCR program can be invoked in one of three ways: manually from the command line, through a simulator program such as BSIM, or from the DOS Planets or VPA programs. Players using DOS Planets (Planets 3.0) --------------------------------------- When using DOS Planets, you must fool this program into thinking that PVCR is actually VCR. To do this, you must: 1) Rename your original VCR program (VCR.EXE) to VCROLD.EXE 2) Rename the new PVCR program (PVCR.EXE in the distribution) to VCR.EXE (see the file INSTALL.DOC for more details) It is recommended that you mark the VCROLD.EXE file as read-only (by typing 'attrib +r vcrold.exe') to reduce the possibility of deleting this original VGA Planets distribution file. The above two steps must be performed only once. When new versions of PVCR are released, then only step 2 above needs to be repeated. The VCROLD.EXE program must always be the VCR program that came with the original distribution of DOS Planets. PVCR is intelligent in that it will detect whether a battle was generated by HOST or PHOST and will automatically call VCROLD.EXE if it is a HOST-generated battle. Thus, you need not continuously swap files around if you are participating in both HOST and PHOST games. Simply perform the above two steps once and both kinds of games will work correctly. WARNING: Attempting to invoke the original VCR program (which should have been renamed to VCROLD.EXE) on a PHOST-generated battle file will cause the program to crash. Players using VPA ----------------- VPA players need only install PVCR as PVCR.EXE, VPA will automatically call it when PHOST-generated battles are encountered. Players using WinPlan --------------------- WinPlan players should simply install PVCR as PVCR.EXE. Creating PIF files (for Windows 3.1) or shortcuts (for Windows 95) can simplify the interface to PVCR for WinPlan players. WARNING: Do not use the built-in VCR viewer of WinPlan to view PHOST-generated battles. The program will crash. Please see Common Question #17 in the FAQ.DOC file for more details. 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. 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) You want to experiment with the combat-related configuration parameters (see the PCONFIG.DOC file). The command line syntax for PVCR is (assuming you've renamed it to VCR.EXE): vcr [-f] [-p Player] [-s | -r Program] [-t time] [-v|-h] [GameDir [RootDir]] Simply typing 'VCR' 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 program when it ends. 4) If the battle is PHOST-generated, then PVCR will search the VCR?.DAT file for battle configuration options (see CONFIG.DOC). These options are placed in the VCR?.DAT file as an extra battle by PHOST. If the battle configuration is not in the VCR?.DAT file (as may happen when using an external simulator, or when viewing a HOST-generated battle), then PVCR will attempt to load a PCONFIG.HST file (which must be located in the 'GameDir' directory, or the current directory if 'GameDir' is not specified) to get the battle parameters. 5) Finally, the battles are displayed by PVCR. When the user quits the program, PVCR will automatically reload the PLANETS program. 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. Since there is no battle configuration information inserted into the VCR.HST file, there must be a PCONFIG.HST file in the game directory for PVCR to use (which must be the case anyways for PHOST to run). WARNING: do not attempt to view the battles in a VCR.HST file when this file was generated by a non-DOS version of PHOST. That is, if you host a game on a Unix system (or other non-DOS system) then you cannot download the VCR.HST file to a DOS system and use PVCR to view the battles. This restriction does NOT apply to VCR?.DAT files. All VCR?.DAT files are readable by PVCR regardless of the system on which they were generated. The '-s' option (Standalone) overrides step 5 above. When this option is specified, then PVCR will not reload the PLANETS 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 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 '-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 'GameDir' parameter specifies the game directory i.e., the directory in which the battle data files (VCRINIT.TMP, VCR?.DAT, PCONFIG.HST, 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. Examples: 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. 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. 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: 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. Note that in this case, the last battle in the file is not a battle at all but in fact contains configuration information. See the "Configuration Information" section below. 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 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 WORD Race WORD BitmapNumber 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', 'Race', 'BeamTech', 'BeamNumber', 'FighterBays', and 'TubeTech' all describe their respective ship or planet attributes. The 'BitmapNumber' member indicates the number of the bitmap in RESOURCE.PLN to use to display the ship. 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: * The 'Ammunition' member describes the number of fighters * The lower 8 bits of the 'Tubes' member describes the number of torpedo tubes assigned to the planet * The upper 8 bits of the 'Tubes' member describes the number of torpedoes available 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 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 is 0 : Combatant survived and won the battle Outcome is 1 : Combatant was captured Outcome is 2 : Combatant was destroyed Outcome is 3 : 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). Configuration Information ========================= In PHOST, combat behavior is greatly influenced by a set of combat configuration parameters. These parameters are documented in the CONFIG.DOC file. PHOST reads these parameters from the PCONFIG.HST file in its game directory, but PVCR does not have access to this file, yet it too needs to be able to access the same parameters. There are two ways by which PVCR can obtain these parameters: 1) PVCR examines the last battle in a VCR?.DAT file (never a VCR.HST file, though). If it finds a special marker in this battle, then it interprets the battle data as being configuration information rather than an actual battle. For this reason, PLANETS will show a player that he has one more battle than truly exists in a PHOST-generated VCR file. The extra battle is, in fact, configuration information. 2) If PVCR does not find the configuration information in the VCR?.DAT file itself, then it attempts to read this data from a PCONFIG.HST file which is assumed to reside in the game directory. This section documents the format of the configuration information as found in the extra battle of a PHOST-generated VCR?.DAT file. Hopefully, by making this information available, authors of battle simulator programs can include configuration information in VCR?.DAT files thus allowing players to easily tinker with combat-related parameters. The following description assumes that the reader is already familiar with the structure of a VCR?.DAT file (see the "Battle Specifications" section above). Only the format of the extra battle is described. Configuration parameters which are boolean-values (Yes/No or True/False) indicate False/No with 0 and True/Yes with 1. Name Size Byte Offset of Parameter in bytes Description --------------+---------------------+--------+--------------------------------- 0 CheckWord1 2 If CheckWord1+CheckWord2 add 2 CheckWord2 2 up to 48879 modulo 65536 then PVCR identifies this battle record as containing config information rather than an actual battle. 4 PHOSTVerMajor 1 PHOST major version 5 PHOSTVerMinor 1 PHOST minor version 6 CfgInfoSize 2 This parameter contains the size in bytes of the config data that follows (currently 64) 8 BayRechargeRate 2 Configuration parameter 10 BayRechargeBonus 2 Configuration parameter 12 BeamRechargeRate 2 Configuration parameter 14 BeamRechargeBonus 2 Configuration parameter 16 TubeRechargeRate 2 Configuration parameter 18 BeamHitFighterCharge 2 Configuration parameter 20 BeamHitShipCharge 2 Configuration parameter 22 TorpFiringRange 4 Configuration parameter 26 BeamFiringRange 4 Configuration parameter 30 TorpHitOdds 2 Configuration parameter 32 BeamHitOdds 2 Configuration parameter 34 BeamHitBonus 2 Configuration parameter 36 StrikesPerFighter 2 Configuration parameter 38 FighterKillOdds 2 Configuration parameter 40 FighterBeamExplosive 2 Configuration parameter 42 FighterBeamKill 2 Configuration parameter 44 ShipMovementSpeed 2 Configuration parameter 46 FighterMovementSpeed 2 Configuration parameter 48 BayLaunchInterval 2 Configuration parameter 50 MaxFightersLaunched 2 Configuration parameter 52 AlternativeCombat 2 Configuration parameter 54 StandoffDistance 4 Configuration parameter 58 PlanetsHaveTubes 2 Configuration parameter 60 FireOnAttackFighters 2 Configuration parameter 62 TorpHitBonus 2 Configuration parameter 64 TubeRechargeBonus 2 Configuration parameter 66 ShieldDamageScaling 2 Configuration parameter 68 HullDamageScaling 2 Configuration parameter 70 CrewKillScaling 2 Configuration parameter