PET2PLY
-------
The purpose of this document is to explain a few things about how to use
the pet2ply utility and offer solutions to common problems you may run
into.


What does pet2ply do?
---------------------
Pet2ply is a utility for generating ply files for use with the Petz Player
Plug-in from PF.Magic, which allows people to play with your petz online.
Pet2ply also generates html files that contain the necessary code to make
your petz come alive on your web page.


1. Instructions
---------------
 If you create an icon on your desktop for pet2ply, you can simply drag and
 drop a pet file onto the pet2ply icon.
 
 1.0 If this is your first time using pet2ply, please start with step 1.1.
     However, if you have already configured the wallpaper image, you
     can skip to step 1.4.

 1.1 To use pet2ply you will first need to find the file pet2ply.exe.  If
     you unzipped the zip file in C:\, then pet2ply.exe should be in the
     folder C:\pet2ply\.  If it isn't you may need to use the Find feature
     of Windows Explorer to find it.

 1.2 Once you've located pet2ply you may wish to make a shortcut for it
     on your desktop.  To do this simply drag pet2ply.exe to the desktop
     using the right mouse button.  When you drop it on the desktop be
     sure to choose "Create Shortcut(s) Here".  If you didn't get the
     menu then you probably didn't use the right mouse button.

 1.3 Once you've created your pet2ply icon, you can set the wallpaper by
     simply dragging and dropping the bitmap file onto the icon.  Pet2ply
     will then ask if you want to set the default wallpaper (say yes).
     If you don't set a default wallpaper image, pet2ply will ask you
     for the filename (including its full path) each time you run it.
       
 1.4 Once the wallpaper is set you can simply drag and drop your pet files
     onto the pet2ply icon.
     
 1.5 When you drop a pet file onto the pet2ply icon, a window will open to
     display the progress of the conversion.  Occasionally a problem will
     arise and pet2ply will ask a simple yes or no question.  It is generally
     safe to answer yes to these questions, but you might not get the
     results you expect. 
     
 1.6 When the conversion is complete simply hit enter to get rid of the
     pet2ply window and the ply and html files will be in the folder the
     pet files came from.

 1.7 Verify that each of the ply files was generated correctly, by
     opening the html files with your web browser.

 For more instructions on other ways to run pet2ply see Appendix A.


2. Changing the Background
--------------------------
 There are several ways in which you can specify the image to use for the
 wallpaper.
 
 2.1 To configure the wallpaper image for use in your ply file simply drag and
     drop a single bitmap file onto the pet2ply icon.
 
 2.2 A window will open and you will be asked if you want to set this file as
     the new default wallpaper.  Answer "yes" to this question and the
     config.ini file will be modified for the new wallpaper image.
 
 If you don't have a wallpaper image configured, pet2ply will ask you for the
 wallpaper file at run time.  You will generally have to give the full path to
 the file in this case, making it by far the most difficult method to use.

 For more instructions on configuring the wallpaper, see Appendix B.


3. Tips & Tricks
----------------
o To make entering filenames easier it is suggested that you copy all of the
  pet files and image files you will need to the folder that pet2ply.exe is
  in.

o Once you are done generating your ply files, be sure to test them by opening
  the accompanying html file with your web browser.


4. Trouble shooting
-------------------
Problem:
 When I try to open the ply file with the Petz Player Plug-in the pet isn't
 wearing clothes, but it should be.

 This is because pet2ply doesn't encode the clothes files into the ply file
 like PF.Magic's Petz Publisher does.

Solution:
 If you really want everybody who plays with the pet on-line to be able to
 see the clothes, then you will have to use the Petz Publisher. 

 If it's not terribly important then go ahead and use the ply file pet2ply
 generated.  But only people who have the necessary clothing files in their
 \PetzPlayer\Resouces\Downloads folder will be able to see the clothes.
 Files are added to that folder whenever a ply file made with the Petz
 Publisher is loaded that has clothing files encoded in it.


Problem:
 When I try to open the ply file with the Petz Player Plug-in the
 wallpaper isn't the one I specified.  Instead it is the PF. Magic
 logo.

 This can happen when the image file you specified was not in the proper
 format for the Petz Player.

Solution:
 To fix this problem the image must be converted to an 8-bit windows
 bitmap file.

 To convert the image to the proper format you can open the image with
 Paint Shop Pro 5.  Then go to the 'Save as' window found under the File
 menu.  Next change the 'Save as type' to 'Windows or OS/2 Bitmap (*.bmp)'.
 Once that is selected go to the options and make sure 'Windows' and 'RGB'
 are selected.  Then hit ok and save the image.  Now if you use the new
 file as a wallpaper image it should work.


Problem:
 When I try to open the ply file with the Petz Player Plug-in I get the
 right wallpaper image, but the colors are all messed up.

 This is because the Petz Player Plug-in uses its own 8-bit palette that
 doesn't have all of the colors in your wallpaper image.

Solution:
 No easy solution really.  One thing you might try to get a better
 wallpaper image is to edit one of the wallpaper images that came with
 the petz program.  All of those images use a palette that is compatible with
 the Petz Player.


Problem:
 When I go to a DOS prompt and type 'pet2ply', I get 'Bad command or file
 name'?

 This means that pet2ply is not in your path.  You can get a listing of what
 directories are currently in your path by typing the 'path' command
 (without the quotes).

Solutions:
 1. Change to the directory that contains the pet2ply.exe file by using
    the 'cd' command and executing it from there.
 2. Add the directory that contains pet2ply.exe to your path.  This can be
    done by editing C:\AUTOEXEC.BAT and adding the directory to the path
    line.
 3. Give the full pathname to pet2ply.exe when you run it.  For example, if
    pet2ply is in the directory C:\pet2ply\, then type C:\pet2ply\pet2ply.exe.


Problem:
 Whenever I run pet2ply it complains about the extensions not being
 correct, what does this mean?

 This means that the filename as entered didn't end with the characters
 that files of that type usually end with.  Windows likes to hide
 extensions(everything after '.' in a filename) from users so there may be
 more to a filename than Windows Explorer shows you.

Solution:
 Try adding the extension to the file names.  The extensions that it's
 looking for are as follows:
    .pet for pet files
    .bmp for bitmap files

 
Problem:
 When I specify the filenames on the command line it complains about not
 being able to open a file, but only shows the first part of the filename.

 This is probably due to spaces in the filename.  The DOS shell uses spaces
 to delimit command line arguments, so it thinks that one filename is
 really two arguments.

Solution:
 To fix this problem try putting double quotes around the filename.  For
 example, if the file is named 'My Dog.pet' (without quotes).  The try using
 "My Dog.pet" (with quotes) instead.


Problem:
 I've read all of the documentation and still am unable to get pet2ply to
 work right for me.

 This may be caused by many things from unclear instructions to a bug in
 the program.

Solution:
 If you truly have read ALL of the instructions and trouble shooting and you
 are still unable to get pet2ply to work for you, please send some e-mail
 to the author, bmfrankl@silver.trica.com.  Be sure to include a detailed
 description of what you tried and what error messages you get (if any).


Appendix A Alternate Instructions
---------------------------------
 A.1 Running from an Icon
 ------------------------
  If you wish to place an icon pet2ply on your desktop and click on that to
  start pet2ply, that will work as well.  If you wish to use pet2ply in this
  manner however, you will probably need to specify the full pathnames of
  your pet file and image file.  If you don't it's hard to say where pet2ply
  will look for those files.

 A.2 Running from a DOS prompt
 -----------------------------
  To run pet2ply from a DOS prompt you will either have to add the directory
  containing pet2ply.exe to your path, or you will have to change to the
  directory containing pet2ply.exe.

  There are then two ways in which to use pet2ply from a DOS prompt.  The first
  is by simply running pet2ply.exe.  It will then ask you for the pet filename
  and the name of the wallpaper image file needed to generate the ply file.
  If pet2ply detects that any of the input you give it might be invalid, it
  will ask if you are sure you want to continue.

  The other way in which pet2ply can be invoked from a DOS prompt is by
  supplying the filenames on the command line.  To do this the format is as
  follows:
      pet2ply.exe [bitmap.bmp] [petfile.pet]


Appendix B Changing the Background (revisited)
----------------------------------------------
 B.1 Including the bitmap with the pet files.
     Another way to change the wallpaper is to include the bitmap file with
     the pet files when you drop them.  This can be tricky because windows
     won't allow you to select multiple files in different folders for
     dragging and dropping.

 B.2 Yet another way in which the wallpaper can be selected is by editing
     the config.ini file and pointing it at the file you want.

