                     UFO/XCOM saved game editors
                      SOLDIER.EXE documentation
Program requirements:
        * 286 computer  running DOS 3.0 or later (talk about crazy ...
          UFO needs a 386, so this should be redundant... :) )
        * Memory - about 640K.

  Note that,  within this  document, all  statements about  "UFO" also
apply to  XCOM. This  program has been tested with the UFO saved game;
it should work with XCOM games too.

  This  program  is  FREEWARE.  NO  warranties  are  made  as  to  its
suitability to any particular task, or to any limitations thereof. You
may freely copy, distribute, etc. this program. You may NOT decompile,
reverse engineer,  etc. the  code of this program. Should you have any
suggestions, send them to me and I'll try to incorporate them into the
next version.  The source  code is  not likely  to be  released, but I
might be persuaded... :)

  Having got that out of the way...

  This program  is intended to be used as an editor of the SOLDIER.DAT
portion of  the UFO saved game. It should be fairly straightforward to
use. If  you need  any help,  F1 will  bring up  a (rather terse) help
screen. Upon  loading the  program, you  will be prompted to enter the
saved game  you wish  to edit.  If there  is no  saved  game  in  that
directory, you  will be  told as  much. You  should run  this  program
whilst in the UFO directory, but the SOLDIER.EXE file does not have to
be in  that directory  - anywhere in the DOS path is fine. When typing
in your  choice, remember  that typing  "1" to "9" corresponds to that
same saved game; typing "0" corresponds to saved game "10".

  To exit the program, press ESC at the point where you are choosing a
field to  edit. You will be asked if you wish to save the changes. For
those of  you who  just want to maximise statistics and get out of the
*** program,  load the  editor as usual, and hit F10. The program will
give you the same "Save changes" prompt.

  Comments? Criticisms? My Internet addresses are (as of 28/9/94):
    sjlam1@mfs01.cc.monash.edu.au
    lamble@yoyo.cc.monash.edu.au

  I would  prefer mail  to be sent to the Unix system (lamble@yoyo...)
as it  has no  mail quotas (as of this writing). It will automatically
forward the mail to my Novell account (sjlam1@mfs01...), and retain it
within the  Unix system  too. If  the Unix system's drive is full, the
mail will  be refused  - in  this case, try the mfs account. There is,
however, a  mail quota  there, so  there is a chance (depending on how
much mail  I haven't  read) that  your message  will not  get through.
Should this  happen, you  *will* receive a message from the postmaster
informing you of this fact.

  Version 2.1  of the base editor incorporates mouse support. I do not
believe, however,  that the  number of  fields  in  the  soldier  data
structure warrants  the addition  of mouse  support. I also received a
request to  make the  program a  TSR. If  you think *you* can modify a
Turbo Pascal program so that it won't crash the computer whenever it's
called as  a TSR, go right ahead. Speaking for myself, though, I'm not
even going  to try. :) :) :) Maybe, someday, I'll port the source code
to C - then again, maybe not.

  A word of warning: As of January 1 1995, AARNet (Australian Academic
Research Network)  will be  changing (read:  increasing) its  charges.
Instead of  charging a  FLAT CONNECTION  RATE, there  will  be  a  PER
MEGABYTE CHARGE.  "So what?"  you might ask. Well, AARNet is the route
Monash University uses to link to the InterNet. It is still unclear as
to how  this will affect the students' access to the InterNet, but FTP
access is almost certainly "out"; news is a little less definite; mail
is even less so; etc. As a result, you can *try* my InterNet addresses
during '95, but you might not get through. My course will *definitely*
finish by  the end  of 1999,  and, possibly  (if I  choose not  to  do
honours) in  1998. Therefore,  even if the mail addresses hold through
1995, they will *not* work during 2000 or the 21st century. (Yes, I do
hold to the idea that 2001 is the first year of the 21st century...:).
To summarise this paragraph:

  The mail  addresses might  not work  after this (1994) year. If they
do, they  might not  during 1999.  They definitely will not during and
after 2000.  It's possible that I will pass the source code to someone
else for  updating, etc.,  after this  year because  of  the  loss  of
InterNet access. Watch this space (or comp.sys.ibm.pc.games.strategic)
for  more   details.  Requirements:   The  ability  to  look  at,  and
understand, just  under 1,000  lines of  uncommented Pascal code. <wry
grin>.

                           Revision History
                           ~~~~~~~~~~~~~~~~
Version 1.0
~~~~~~~~~~~
  Initial release - so many bugs, it was released as public domain :).
It did work, but not completely :(.

Version 1.1
~~~~~~~~~~~
  Released as  freeware. (ie,  you *could* decompile the first version
legally, but  not this  version or  any later  version.) Note that the
record structure of SOLDIER.DAT *is* available on request.

  The first  release would  leave SOLDIER.DAT  as-is, and save the new
file  as   SOLDIER.NEW.  This   version  now  renames  SOLDIER.DAT  to
SOLDIER.BAK, and  SOLDIER.NEW to  SOLDIER.DAT (in  that order... :) ).
Note that,  due to  these changes,  DOS 3.0 or higher is now required.
(Then again,  if you're  playing UFO,  you're  probably  using  a  DOS
version later than 3.0 anyway...)

  One semi-unidentified field has been clarified, as has Bravery.
  The first  release would  allow you to edit only those records found
in the  initial grouping. Any unused records, *plus those after them*,
would be ignored. This problem has been fixed.

Version 1.11
~~~~~~~~~~~~
  Minor modifications  - the  stats are now limited to a (total) value
of 200, rather than 255. This should fix the problem of "wrap around".
In addition,  you can  now increase  Psi Skill to 200, rather than the
value of Psi Strength. These changes *do* carry over to the F10 key.

  This modification  also fixed  the problem  of low  energy - ie, you
would have  a maximum  energy of  255, but usually only about 17 or so
available for use. Don't ask me why this worked - it just did.

Version 1.12
~~~~~~~~~~~~
  Minor cosmetic changes.

  Interface changed  - in  this version,  you press ESC to finish, not
ENTER. This  was done  for two  reasons: to make the interface of this
editor similar  to the base editor; and to ensure that the program did
not finish  after entering a value if ENTER was pressed twice (or held
down for too long).

  Can now specify the saved game to edit on the command line.

Version 1.20
~~~~~~~~~~~~
  Added ability to resurrect dead soldiers.

Version 1.30
~~~~~~~~~~~~
  Several fillers have been identified. My thanks and acknowledgements
go to  those who  helped me  out with  them...if I could just remember
their names... <wry grin>

  The maximum throwing accuracy is now 100, not 200. When throwing was
set to  200, there  would be error messages along the lines of "Out of
Range" when  trying to throw an object. This doesn't seem to happen at
100. One  of these  days I'll  have to sit down and figure out maximum
values....then again, UFO's too much fun. :)

  In earlier  versions, if  you were  on the  last (250th)  record and
pressed the  right arrow  key, the  program would  give you  a  "Range
check" error. This has been fixed.

Version 1.30a
~~~~~~~~~~~~~
  Functionally equivalent  to 1.30,  except that the Strength field is
now limited  to a  maximum of  150 instead  of 200.  My thanks  to the
correspondent who  informed me  that *this*  was the  problem, not the
throwing accuracy <wry grin>.
Version 1.30b
~~~~~~~~~~~~~
  I managed  to do  it again...releasing  a program  without  complete
testing! <groan>  This time,  the program would not save properly - to
be exact,  it would  save, but  the contents  of the  saved file would
match the  original file. The reason was tracked down to a very subtle
bug, relating  to the  way Pascal handles variable passing: if I don't
put a  "var" before  a variable  name in the procedure, any changes to
that variable  are *not*  passed back  to the  calling function.  As a
result, you  could edit to your heart's content, but when you returned
from the  editing procedure,  there would  have been,  in  effect,  no
changes. This  effectively made  the program  a SOLDIER.DAT *viewer* -
useful, but not what was intended...

  I have also changed the maximum values of most skills to reflect the
limits in  UFO 1.2 (and XCom). They are now, with the exception of Psi
Strength and Psi Skill, limited to a maximum value of 80.

Known 1.30 problems:
~~~~~~~~~~~~~~~~~~~~
  Still some  four or  five unidentified  fields. Filler  3 + 4 *look*
like they are some sort of "Gained + Initial" combination, but this is
still unconfirmed.  I have  left the filler numbers as they originally
were, to  make it  easier for  me to  understand which  field is being
discussed -  if I  renumbered them, it would cause some ambiguity when
somebody tries  to inform me of the purpose behind the field. Besides,
I'm too lazy to change the code... ;)

  If you  receive a run-time error message, such as "Runtime error 201
at address  xxxx:xxxx", please  let me know *what* you were doing, and
what keys  you pressed,  when you  got the  message. If you have Turbo
Pascal, the  error numbers  are listed  in the  online help should you
want to  know what  they mean.  (read: should  you want  to know how I
stuffed up. :) )
