MR.POTATO 1.3 (26/02/2000)
MrPotato is distributed as FREEWARE for NON-COMMERCIAL use.
This means that you are free to use this applet as much as you want to for "non-commercial" sites and you will not be asked to pay anything for the use of it. Commercial sites can also use the applet free of charge after requesting and receiving written permission from me.
I do not ask for, or accept, any payment for this applet or it's use !
Sounds like a good deal, that because it is !

I do ask the following,
    1. You just send me a quick mail message saying that you are using it.
    2. You send me the http address of the page(s) using this applet. 
       I like to look at these, it's nice to see how people are using it.
    3. If you do not want me to include your pages in any links listing
       that I might make, please let me know. Otherwise I will assume that I can.
       (if you say no, then I will respect that).
    4. A link back to the games homepage http://svwhite.com/games,
       would be appreciated, but is not a condition of the applets use.
    5. I ask that you do not redistribute the applet either in part or as the
       the zip file without my permission.
and require that,
    1. (*)All class and jar files MUST NOT be tampered with or modified in any way.
    2. (*)All class and jar files MUST NOT be reverse engineered or decompiled.
    3. Commercial sites MUST ask for, and receive written permission from me 
       BEFORE using the applet.
in addition,
    I do not accept responsibility or liability for any damage or loss caused 
    either directly or indirectly by the use of the applet or any component part. 
    Neither do I accept any responsiblity or liability for any damage or loss 
    caused by the download or extraction of any or all of the supplied files.
    This applet is supplied on an "as is" basis, I do not guarantee it's ability to
    function or it's fitness for use in any way. 
    
Commercial user's MUST ask for permission before using this applet. I DO NOT charge for this applet, but I do reserve the right to decide if I want to allow it's use on individual commercial sites. My decision on commercial sites is based on how you intend using the applet and the type of site.

The MrPotato applet require's a Java 1.1 enabled browser !

The "MrPotato.jar" file is ALL that you need to use,
this contains all of the necessary class files.
To use the applet you need to transfer the "Jigsaw.jar" file to the server in binary mode.
You do not need to extract anything from the jar file
the jar file is just a "wrapper" for the class files.
Most browsers understand what to do with jar files.

For those users who wish to use class files instead of the
jar file, these have also been included in the zip file.


Changes in MrPotato 1.3
The image handler has been replaced.
This has corrected a problem where under some circumstances, images (jpeg images), were only partially drawn in the playing area.
All class files have been packed into a single jar file.


APPLET PARAMETERS

Parameter Value Description
ImgWidth nn The width for the main image(s).
ImgHeight nn The height for the main image(s).
BgColor "#rrggbb" The background color.
PickFrameColor "#rrggbb" The color used for the "over item" frame.
PickSpotColor "#rrggbb" The color used for the "item selected" spot.
ButtonTitle "title text" The text to be used for the "Reset" button. This allows easy conversion to another language.
PartsPath "pathname/" An optional path to be used to locate all "piece" images (This MUST end with a forward slash).
Imagen "Display Name,
path/image.fil"
Add a primary image. "n" can be between 1 and 10. Image1 MUST be defined, and this is the image which is used when the game is started. Additional images are added until the next number in the sequence is not found or you have added 10 images.

Display Name - The name to show in the list.
path/image.fil - The image file (and path) to add to the game.

* If more than one primary image is defined, a list-box is automatically added to the applet window so that the player can select the different main images.
Piecen "Qty,
Image.gif,
X Position,
Y Position,
Orientation,
Width,
Height"
Add a game piece. A maximum of 300 pieces can be used.
This is something of a "complex" definition, but looking at the example html files will also help you to understand how this works.

Qty - The number of copies of this piece.
Image.gif - The name of the image file
X Position - The starting X coordinate for this piece.
Y Position - The starting Y coordinate for this piece.
Orientation - (Optional) The starting orientation for this piece (0-3).
Width - (Optional) Set the width for this piece.
Height - (Optional) Set the height for this piece.
ShowPositions true When set to true, the position and orientation for pieces is shown in the top right hand panel.
This is mainly intended to help in setting the correct starting locations/orientation for pieces placed on the primary image.
The display shows,

X Position, Y Position, Orientation



USING Mr.Potato

Copying the jar files
You need to copy the jar file "MrPotato.jar" to the same directory as your web page. This file must be transfered in binary mode and must be named exactly as shown (take care with upper/lower case characters).

Using the class files instead of the jar file
This is intended for those people who wish to use the class files INSTEAD of the jar file.
If you are using the jar file (recommended) please skip this.

You need to copy the three class files to the same directory as your web page. These files must be transfered in binary mode and must be named exactly as shown (take care with upper/lower case characters). You should then REMOVE the archive="MrPotato.jar" setting from the applet definition (there is now NO archive [jar] file).

Creating themes
You can create your own themes, by choosing or making your own picture(s) for Image1...n and creating your own pieces. This can be absolutely anything you like. For example, you could create a "dress the doll" type game by using boy/girl pictures for Image1 and Image2 and then creating various clothes for Piece1 - Piecen.
You could use a landscape picture with a river and add boats and fish, planes, houses, people, sun, moon. You could and so on...
You can use your own picture and allow people to "modify your face" (this is much cheaper than plastic surgery). You are only limited by your own imagination.

A plea for help from you
As you have probably noticed by now, I am not an artist. If there is anyone out there who is interested in creating "theme sets", free of charge for free download, I would be grateful if you would contact me. I would give you full credit if they are made available from my site, or just point people at your site, or maybe both. Anyway, let me know. The important thing is that you have the rights to freely distribute all of the images that you use in your "theme set" and that you agree to them being made available free of charge.

Making pieces
To achieve good control over different shaped pieces, you should create pieces as transparent GIF images. You should also think about the size of the image files that you create. Large images increase the time needed to load the game. Often you can get away with making smaller pieces and "stretching" them to a larger size in the game using the last two parameters in the "Piecen" definition.
The more pieces that you use, the slower the game will be when moving pieces around because of the amount of image updating that is occuring in the background.
As mentioned before, all of the images were made by me (some with the aid of a camera), but you are free to use any of these if you want to.


Writing the HTML code
The multi-parameter definitions (Imagen and Piecen) do not like spaces between the parameters ie;
    value="1,fred.gif,  90, 90"
    value="1,steve.gif,100, 90"
will not work. I might do something about this later.
Most parameters and parameter names are case sensitive, take care to write these correctly.
Although you do not have to specify images or pieces in the correct order, processing will stop when a gap in the numbering is found ie;
    <param name=Piece1      value="1,a.gif,10,10">
    <param name=Piece3      value="1,b.gif,20,10">
    <param name=Piece4      value="1,c.gif,30,10">
    <param name=Piece2      value="1,d.gif,40,10">
    <param name=Piece6      value="1,e.gif,50,10">
    <param name=Piece7      value="1,f.gif,60,10">
will add pieces 1,2,3 & 4 even though they are not defined in sequence. Pieces 6 & 7 will not be added because "Piece5" is missing (ie; processing of the pieces stops when "Piece5" is not found).
Pieces are processed in numerical order, this means that pieces with higher numbers will be painted after pieces with lower numbers and will therefore appear on top. You should remember this when designing themes. For example, if you were to use the following,
    <param name=Piece1      value="1,hat.gif,40,10">
    <param name=Piece2      value="1,hair.gif,50,10">
Then the "hair.gif" image would always be always be displayed over the top of the "hat.gif" image.
Pathnames should use forward slashes as a path seperator (dir1/dir2/file.name) for compatibility.
The "PartsPath" parameter is intended to save you writing the full path for each "Piece" that you add, if you use this, you MUST terminate it with '/'.
To make it easier to create starting positions for all or some of the pieces, you can switch on the "ShowPositions" options when designing the game. It is better if you turn this off for the final version of the game.
You can also check out the examples provided with this zip file for more ideas and help.

If you do use the "Mr.Potato" applet, I would appreciate it if you let me know. I like to see how people have used my work and I might make a links page at some point.



SPECIFYING COLORS
Colors are defined as an RGB hex string (in the same way as other HTML commands).
The sequence is "#RRGGBB"

For more information please refer to the example html files provided.

ERRORS
If you experience errors please check,
ALL spelling and remember that java is "Case SEnsitiVe",
for example: TextColor is not the same as textcolor
The examples with this applet
You have the jar file in the correct directory with the correct name. It MUST be "MrPotato.jar" and NOT "mrpotato.jar".
You have not copied both the jar file and the class files to the server (this should be one or the other)

MAILING LIST
This mailing list is used to keep people informed about updates/errors/new applets.

To join the Games mailing list,
send an email to: game-applets-request@svwhite.com and subscribe as the subject.
Please leave the message body empty.

To remove yourself from the Games mailing list,
send an email to: game-applets-request@svwhite.com and unsubscribe as the subject.
Please leave the message body empty.

Update: 26/02/2000
Author: Steve White.
Puzzle homepage: http://svwhite.com/games.