![]() |
PVCR User's Guide
|
PHost combat must be played by PVCR, PHost's battle viewer. The built-in battle viewers in planets.exe and Winplan can not display PHost combat; they will display complete garbage or crash.
Information on how to install PVCR for your client is described in the Combat section of First Time with PHost. This document describes how to use PVCR.
PVCR is a 16-bit DOS program. It can play combat generated by all public PHost versions that ever existed, so there's no need to keep older versions.
Similar to PHost, the general syntax for PVCR is
pvcr [-v|-h] [-pplayer] [-s|-rprogram] [-bN] [-f] [-F] [-ttime] [-Xseg:ofs] [GameDir [RootDir]] |
Note that, if you use DOS Planets, PVCR will be
installed under the name vcr.exe.
Defaults are such that if you have installed PVCR correctly for your
planets.exe or VPA, you can
simply use the normal VCR display function of your client program
to invoke PVCR; if you installed it for Winplan, you can simply run
it without caring for the rest.
Unless you specify an option that says something else, PVCR will do the following when run:
-h | Print help summary and exit successfully. |
-v | Print PVCR's version number and exit successfully. |
-pplayer | Play player's battles. When this option is specified, PVCR will not read vcrinit.tmp or gamestat.dat. If you have a host directory, -p0 (player zero) will play all battles encountered this turn (vcr.hst). |
-s | Standalone mode. Do not reload planets.exe afterwards. You'll most likely use this switch if you run PVCR yourself. |
-rprogram | Reload program instead of planets.exe. This option might be useful for client or battle simulator authors. |
-bN | Play only the N'th battle, then exit. This option is useful for client programs. Note that this switch was broken in PVCR before version 3.3e(2). |
-f | Force. This will play the fight with PVCR even if it was generated by HOST. You will not get the same result as HOST in this case, but you might get a vague idea about the difference between normal HOST combat and alternate combat, for example. |
-F | Font bug workaround. On some systems, the running battle stats ("10% shield remaining") might display incorrectly or not at all. This switch enables a workaround for that bug. Note that the bug is in the BGI library used by PVCR, not in PVCR itself, so we cannot easily fix it. |
time | Time scale. This option affects the speed of playback. By default, the time scale value is 15. Smaller values of time scale result in faster battle displays. This parameter should be kept in the range [1,20]. |
-Xseg:ofs | Compute battle results and return them in a transfer area. This option is for programmers of utility programs only. See below for details. |
The game selector is available in version 4.0e and later.
The game selector displays two panels. The left one displays the available games (the same 8 game slots as in Winplan), the right one displays all the races which have battles in this game slot.
You will see information about one battle. You can browse through all available battles and watch them. After each battle, you return to the battle selector.
The battle viewer displays the battlefield on top of the screen, with squares for the ships, triangles for fighters, etc. The bottom half contains running stats, such as current damage, charge status for beams, and so on.
This section is of interest to programmers only.
This interface is probably not too useful. But it is
there and therefore it is documented here. When you want to
simulate battles, you are probably better off using the PDK or the
combat.log interface.
When you specify a -Xseg:ofs option, PVCR will return results about the watched battles to the program invoking PVCR. The address is specified in standard hexadecimal format (e.g. 12CF:038E), as a real-mode address
The result area must begin with the following two data items:
long Signature word Number of Results |
The first field must be set to 1033FE51h; this provides a check mechanism for PVCR so that accidental overwrites of uninitialized memory locations do not occur.
This header is followed by a sequence of result structures, the number of which was given in the header. PVCR will not store more results in the area.
Each result structure has this format:
word Valid word[2] Shields word[2] Damage word[2] Fighters word[2] Torps word[2] Crew word[2] Outcome |
The first field 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 members should be self-explanatory. The Outcome field is the same as in util.dat:
0 | Victor: this unit won the battle |
1 | Captured: this unit was captured (never true for planets) |
2 | Destroyed: this unit was destroyed (in case of a planet, the planet got captured because all its defense was destroyed) |
3 | No Ammo: this unit no longer has offensive capability |
Once PVCR terminates, then the Valid 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).
Last updated 15 July 2007.