************************************************************** ** ** ** PPPPP ll TTTTTTTT ** ** PP PP ll TT ** ** PPPPP ll aaaaa nn nnn TT oooo ww ww ** ** PP ll aa aa nn nn TT oo oo ww ww ww ** ** PP ll aa aa nn nn TT oo oo ww ww ww ** ** PP lll aaa aa nn nn TT oooo ww ww ** ** ** ************************************************************** PlanTow by Michael Herrmann ~~~~~~~ - is a tool for VGA Planets ((c) Tim Wisseman). If you don't know what that is, you don't need this program :-) . - features a new tow model that is supposed to be more satisfactory than existing tow models. - will cooperate with both TimHost and PHost. - was created after the release of PHost 3, the new tow model of which heavily handicaps cloaker races and destroys the equilibrium of the races. The new PHost tow model was considered unusable; the alternative, TimHost-compatible model was okay, but somewhat unsatisfactory because of its heavy reliance on IDs and waypoints. The old PHost 2 model was also okay, but no longer available. So I wrote this program in order to get a simple and fair tow model that sums up the advantages of the other existing (or no longer existing) models. What you should really know ~~~~~~~~~~~~~~~~~~~~~~~~~~~ You should really know that you should read or at least scan this manual at least once :-) . But for those who really have to start quickly, here is a short summary. Installation: PlanTow feels comfortable in your main planets directory. In that case call PlanTow with your match directory as a command line parameter. This is a way of making sure that PlanTow finds the necessary files (ship.hst and hullspec.dat). For alternatives, call 'PlanTow ?' or RTFM. Run PlanTow immediately before the movement phase or in AuxHost1.Ini. Features: In simple words, a simple tow will always succeed. A ship that is being towed successfully, cannot tow another ship. In a conflict situation, the stronger ship wins. Strength depends on tech level, number of engines, warp speed, GravAx and travel distance. If you want to know more, RTFM :-) . Moreover: PlanTow supports program exit codes and writes a PlanTow.Log file. Warranties: Ths usual stuff. Anyway, by using this program you confirm that you agree with the warranties section of this manual. Contents ~~~~~~~~ 1. How it works 2. Who's towing who? 3. Where to put it, command line parameters 4. How to use PlanTow 5. The file PlanTow.Log 6. Exit codes and run-time errors 7. No warranties 8. History 9. Known problems 10. Please hand on 11. Contact 1. How it works ~~~~~~~~~~~~~~~ PlanTow does not replace the tow or the movement phase of the host program. It is supposed to run before that phase. In order to force the host program to behave as PlanTow wants, PlanTow switches off the Tow mission of a tower if the ship is not supposed to tow. If a ship is supposed to be towed, PlanTow reduces its warp speed or cuts the waypoint (whatever is needed for your preferred host program). 2. Who's towing who? ~~~~~~~~~~~~~~~~~~~~ The basic understanding of a tow beam in PlanTow is that a tow beam disables its target's engines and tow beam (and maybe more). Consequently, any simple tow (by which I mean ship A towing ship B, and no other ships interfering) will always succeed. This closely matches Host and PHost 2 behavior because in those programs a simple tow can always be made work by setting the tower's warp speed to 9. (In TimHost, the tow target can actually escape by setting a large waypoint, but you don't really like to set long waypoints because you don't want to tell your opponent which planet you came from, right?) In PHost 3, the number of engines plays an important role, e.g. a (fully equipped and fast-moving) STF cannot be towed e.g. with a Resolute or Dark Wing, and a Merlin, Golem or Rush cannot even be towed with a MCBR. I wouldn't want to play any cloaker race (let alone Privateer) under these circumstances. Exceptions to the basic rule are ships without fuel, which cannot tow because the tow beam doesn't get energy, and cloaking tow targets, in which case the captain of the tower can't know where to direct the tow beam. This also matches Host and PHost behavior. A self-tow is not possible in PlanTow, because a Tow beam is straight and cannot be directed to one's own ship. You may want to know what happens in conflict situations as a mutual tow or a multipe tow. Before I come to that, let me explain three structures. Or, if you are not really interested in the details, you can skip the rest of this section. A tow chain is a structure as A tows B tows C tows D ... A tow node is a structure as B tows A, C tows A, D tows A ... One ship is tow targeted by several would-be towers. This is also called a 'multiple tow' (e.g. by PHost). Tow chains can end in a tow node, and one tow chain may come out of it. A tow ring is a structure as A tows B tows C tows ... tows A. Chains can end in a ring but never origin from a ring. A ring of length one is a 'self-tow', a ring of length two is a 'mutual tow'. PlanTow deals with these structures by breaking them down into simple tows (or 'tow pairs') starting with the chains from top to bottom. For a chain A tows B tows C tows D ..., A will tow B. Since B's tow beam is then disabled, C is free to move and can tow D, etc. A ship will never tow two ships at the same time (compatible with TimHost and PHost). After all chains are broken down as far as possible, only nodes and rings remain. For a node (or multiple tow), the strongest ship wins. This agrees with PHost, but not with TimHost (in which case the ship with the lower ID wins). To determine the tow strength, the new PHost 3 formula is used with one change: Strength = (Enging_TL^2 * (No_of_engines + GravAx) * Speed * 163) + Distance. GravAx equals the maximum number of engines for any ship found in the Hullspec.dat for a ship with gravitonic accelerators, or 0 for all other ships. This makes sure that a Transwarp GravAx ship will win a tow competition agains any other ship. The ships with the IDs 44, 45, 46 are considered GravAx ships. Distance is the distance that the ship can travel in one turn. In case two ships have equal tow strength, the lower ID ship wins (in agreement with PHost 3). In a tow ring, the strongest ship will win, too. The ring is thus broken up into a chain and treated correspondingly. The shortest ring is a ring of length one, i.e. a ship towing itself. Since the ship is the strongest of the ring :-) , the tow (from itself) is broken, and the ship can move. The next shortest ring is a ring of length two. This means that two ships are trying to tow each other. As in the more general case, the strongest ship will win this tow. This agrees with PHost 3, but does not agree with PHost 2 (in which case both ships won't move) or with TimHost (in which case the ship with the lower ID wins). As a last complex case consider the following situation: A tows B tows C tows B. B and C form a tow ring with which A interferes. The situation is handeled as follows. While the tow beams of B and C struggle with each other, A's tow beam operates. This shuts down B's tow beam, so that C's tow beam can also work. Thus B will be towed by the stronger ship of A and C. 3. Where to put it, command line parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PlanTow can be operated from any directory. However, it needs to find the match files, more specific the ship.hst and the hullspec.dat. The ship.hst is always found in the match directory, and the hullspec.dat usually resides in the main planets directory (in the following called 'game directory'). You can tell PlanTow about these two directories using command line parameters: Usage: PlanTow [/no1] [/tcs] [/bfX] [[game_directory] match_directory]'); A '?' in any of the command line parameters will call the info function and abort the program. If the game directory is not supplied, it is supposed to be the parent directory of the match directory. If the match directory is not supplied, it is supposed to be the current directory. All files (i.e. also the hullspec.dat) are first searched for in the match directory. If not found there, they will be searched for in the game directory and, finally, also in the current directory. Examples: 1. To make things easy, you would probably install PlanTow in your game directory and call 'PlanTow <match_directory>' which will work even if the match directory is not a subdirectory of the (current) game directory. 2. If your match directories are subdirectories of your game directory, you can go to your match directory and from there call PlanTow without command line parameters. The parameter '/no1' (or '-no1' or '/NO1' etc.) switches OneEngineTow off. (If your game or match directory happens to be called '-no1', write './-no1' if you mean your directory.) OneEngineTow must be switched on both in PlanTow and Host in order to work! If it is switched on in one of them and off in the other, the result will be strange. PlanTow does *not* read the PConfig.src! With '/tcs' (or '-TCS' or '/TcS' etc.) set, ships are allowed to tow cloaked ships even if they belong to a different race. When '/tcs' is not set, players can only tow their own cloaked ships. TimHost uses '/tcs' set, the default for PHost is '/tcs' not set. Please note that PlanTow does not read the PHost alliance status. Thus, if '/tcs' is not set, you can't tow your ally's cloaked ships even if the ship level of alliance is set. The parameter '/bfX' (or '-bfX' or '/BFX' etc.) with X = 0 .. 6 determines what PlanTow does with ships that are supposed to be towed. The default is X = 0. PlanTow then sets the warp speed of the ship to zero and also cancels the waypoint. This means that a towed ship can never break free from a tow if the tower runs out of fuel or is hit by a mine. If you want your ships to break free in such an incident, you have to set X = 1 .. 5 depending on your host program. If you don't want ships to break free, the default is the safest choice. X = 1 .. 3 are for use with TimHost or the TimHost compatible mode of PHost 3. X = 1 will cut the waypoint to a distance the towed ship can travel within one turn. X = 2 will reduce the warp speed to less that the towing ship's speed. Each of those should be sufficient to enable breaking free. If you want to make sure, use X = 3 which does both. X = 4 limits the towed ship's warp speed to the towing ship's warp speed. This is for PHost 2. Note that X = 4 differs a little from X = 2 also in respect to GravAx ships. X = 5 is for PHost 3. X = 6 does nothing whatsoever to the speed or waypoint of the towed ship and leaves the action to the host program. Be warned that the result of this may be inconsistent. For instance, if ship A is set to tow B and B is set to tow C with no other ships interfering, PlanTow will disable the tow from B to C. But with X = 6 the host program may decide that A is not allowed to tow B. Now B should tow C, but it can't because PlanTow already disabled it. I don't recommend using X = 6. But if you still think, it makes sense for your case, feel free to use it - eh, and please drop me a note :-) . 4. How to use PlanTow ~~~~~~~~~~~~~~~~~~~~~ The most suitable time to run PlanTow is immediately before the movement phase of your host program (i.e. PHost 3). If you can't do that, you can also run it from AuxHost1.Ini or before phase 2 of PHost 2.x. 5. The file PlanTow.Log ~~~~~~~~~~~~~~~~~~~~~~~ PlanTow writes all its actions to the screen and also to a file called 'PlanTow.Log' which is located in the match directory. If an old file with this name exists, it will be overwritten. 6. Exit codes and runtime errors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ On successful execution, PlanTow quits with exit code 0. Command line errors (esp. also any '?' in the command line) call the info function and cause exit code 255 (or -1). Exit codes from 10 through 19 indicate a file read or write error. Exit codes from 20 to 29 mean that the program encountered a situation which it could not handle (which actually should never happen). In case of an error, the program beeps and waits for any key to be pressed. When a key is pressed or if no key is pressed after 30 seconds (or maybe less), the program exits. 7. No warranties ~~~~~~~~~~~~~~~~ I wrote this program very carefully and tested it thoroughly. However, to err is human, and you know that no useful program is really free of bugs of every kind. By using this program you accept that the risk is completely on your side and that I cannot be made responsible for problems of any kind including (but not limited to) loss of data, hardware destruction etc. (By the way, you *do* make backups of your planets matches, don't you?) 8. History ~~~~~~~~~~ PlanTow 1.1: - Bug corrected: GravAx ships had been treated as in PHost 3. - Bug corrected: Multiple tows had not been resolved correctly. PlanTow 1.0: - first public release 9. Known problems ~~~~~~~~~~~~~~~~~ - PlanTow doesn't check the PHost alliance status. Thus a player can't tow an ally's cloaked ships unless the command line parameter '/tcs' is set which enables towing all cloaked ships. In addition, for determining if a ship is cloaked or not, its mission is checked. Although this seems to be a proper indicator of a valid cloak status, I am not completely sure. If you run into a problem (and esp. if you know a way out of it :-) ) please write me a mail. 10. Please hand on ~~~~~~~~~~~~~~~~~~ PlanTow is Freeware. Please feel free to give it to anyone else and/or upload it to mailboxes or servers if - you distribute it free of charge (and only free of charge) and - you distribute it together with this documentation. You are not allowed to make any changes to the program or the documentation. 11. Contact ~~~~~~~~~~~ For questions, comments, bug reports etc. please contact Michael_Herrmann@m2.maus.de or email@example.com. If both doesn't work, someone in the newsgroup maus.spiele.planets probably knows how to find me.
Last Modified: 4-Mar-2000