PHost - PVCR User's Guide

Index

• Introduction
• Invoking PVCR
  • Command-Line Options
• Interactive Usage
  • Game Selector
  • Battle Selector
  • Battle Viewer
• Obtaining Results from PVCR

Introduction

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.

Back to top

Invoking PVCR

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:

• if there exists a vcrinit.tmp file, PVCR will read instructions from that file. This file is created by planets.exe. PVCR will, repeatedly, let the user choose a battle and watch it. Upon exit, it will reload planets.exe. If the battles were not generated by PHost, PVCR will hand them to the normal VCR (vcr.exe).
• (v4.0f:) otherwise, if there exists a gamestat.dat file, PVCR will offer a menu of the games defined there-in. This applies when you run PVCR from your Winplan directory.
• if none of these applies, PVCR will load planets.exe, just as Tim's VCR does.

Command-Line Options

Back to top

Interactive Usage

Game Selector

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.

• Use the arrow keys to navigate.
• When on the left panel, Enter selects that game and places the cursor in the right panel to choose a race (use the left-arrow to get back). When in the right panel, Enter chooses that race and enters the battle selector.
• ESC exits PVCR (it will not reload a program even if -r was specified).

Battle Selector

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.

• Arrow keys switch to next/previous battle.
• Enter displays the current battle.
• ESC exits PVCR, and reloads planets.exe or whatever program was set using -s/-r.
• F1 displays the closing credits.

Battle Viewer

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.

• Space starts/pauses the display.
• "+" and "-" increase or decrease playback speed.
• ESC exits back to the battle selector.

Back to top

Obtaining Results from PVCR

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:

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).

Back to top

Last updated 31 May 2015.