=============================================================================
Pairs - Desktop Memory Game                                      Version 0.37

(c) Stephen Fryatt, 1997-2017                               23 September 2020
=============================================================================

  This file is also contained within the Pairs application and can be
  accessed from 'Help' on the Pairs iconbar menu and from the 'Help' entry
  in the Filer menu.



Licence
-------

  Pairs is licensed under the EUPL, Version 1.2 only (the "Licence"); you may
  not use this work except in compliance with the Licence.

  You may obtain a copy of the Licence at
  http://joinup.ec.europa.eu/software/page/eupl

  Unless required by applicable law or agreed to in writing, software
  distributed under the Licence is distributed on an "AS IS" basis, WITHOUT
  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  See the Licence for the specific language governing permissions and
  limitations under the Licence.

  The source for Pairs can be found alongside this binary download, at
  http://www.stevefryatt.org.uk/software



Credits
-------

  Pairs uses PlayIt, originally by Rick Hudson and now maintained by Chris
  Martin, to play sound samples.  This is Freeware and can be obtained from
  Chris Martin's website at http://www.users.on.net/~belles/software/playit/.



Introduction
------------

  Pairs is a Desktop memory game.  The playing area is covered in pairs of
  picture cards, placed face down.  Each player takes it in turns to flip
  over two cards and look at the pictures.  If they match, the cards are
  removed and the player gets another turn; the winner is the player to have
  removed the most pairs of cards at the end of the game.

  Interactive help is fully supported.



Installing Pairs
----------------

  Pairs requires RISC OS 3.1 or later and has been tested on RISC OS Select
  (RISC OS 4.33).  It is 32-bit compliant and compatible with RISC OS 5 on
  the Iyonix and its successors.

  Pairs can be run off a hard disc or floppy disc.  To install it on a hard
  disc, copy the !Pairs application to a suitable place on your disc.  If
  sound samples are used, use from a floppy disc may be impractical due to
  space limitations.

  Pairs uses Rick Hudson's PlayIt -- now maintained by Chris Martin -- to
  handle sound samples.  The latest version of this is can be obtained from
  Chris's website at http://www.users.on.net/~belles/software/playit/.
  Versions from 1.68 onwards are 32-bit clean.  Pairs requires version 1.59
  or later.

  The !PlayIt application should be copied into !Boot.Resources, so that it
  can be found by any applications that need it.  Full documentation is
  supplied in the PlayIt archive.  If you do not wish to use sound,
  installing PlayIt is not necessary.


  Upgrading from version 0.20 or earlier
  --------------------------------------

  If you are upgrading Pairs from version 0.20 or earlier, you will need to
  update the structure of the !Pairs.Cards directory.  Card sets are now
  stored in their own sub-directories, to allow for the storage of sound
  samples.

  Open the Cards directory (Shift-double-click on !Pairs to open the
  application directory).  It will contain sprite files that correspond to
  the various installed card sets: these will have the names of the card
  sets, with optional "22" and "23" suffixes.

  For each set of card sprites in turn, rename the file with NO suffix (for
  example, Pictures) as Sprites.  Then create a directory with the original
  name inside !Pairs.Cards and move the renamed sprite file into it.  If
  there are files with the same name and either "22" or "23" suffixes, rename
  them as Sprites22 and Sprites23 respectively and move them into the
  directory too (it is very unlikely that there will be any "23" files
  present).  Repeat this process until there are no sprite files in the root
  !Pairs.Cards directory.



Using Pairs
-----------

  Put Pairs on to the iconbar by double-clicking on the !Pairs application in
  a Filer window.  To start a new game using the default options, click
  Select on its iconbar icon to open the playing window.

  The human player moves first against the computer, so click Select on any
  two of the cards to turn them over.  Look at the pictures and try to
  remember what they are.  After a short pause the cards are flipped back
  again and the computer will turn over two cards of its own; again, watch
  what the cards are and try to remember them.

  If either player turns over a pair of cards, the cards are removed from
  play and that player gets another turn.  At the end of the game, the winner
  is the one to find the most pairs.

  The current scores are shown at the top of the playing window, alongside
  the players' names.  To change the name of the human player, click over the
  name and enter a new one in the field that appears.  Press Return to change
  the name or Escape to cancel.  Editing the name of the computer player can
  be enabled from the Choices Window, or editing the human player's name can
  be disabled.

  To start a new game, click Menu over the game board and select 'New game'.


  Game Statistics
  ---------------

  A few more statistics are available, to indicate how the current game is
  progressing.  Select 'Statistics...' from the icon bar menu to open the
  Game Statistics window.

  This window contains the game scores for each player, as shown in the
  playing window.  It also contains the largest number of attempts taken to
  turn over a pair of cards, as well as the average number of attempts.
  Finally, the total number of turns taken is shown.



Game Options
------------

  The various game options can be set from the Choices Window, by choosing
  'Choices...' from the icon bar menu.  The options set here will take effect
  in the next new game to be started and do not affect any game that is
  currently in progress.

  The 'Players' section allows details of the two players to be set.  The
  names of the human and computer players can be entered here; if the
  'Editable' option is on, they can then be changed from the game window as
  described above.

  The 'Forgetfulness' option for the computer player sets its playing level.
  In each round it will forget a certain percentage of what it knows: the
  higher the percentage, the weaker it plays.  At 100% its game play is
  totally random, at 0% it will never forget any cards it sees.  It can be
  surprising how high this must be set for the human player to have any
  chance of winning...

  'Board' allows the playing board to be set up.  The 'Card set' menu selects
  the card sprites to be used.  The rows and columns (and hence the total
  number of cards) is set by the 'Size' fields.  Use the bump icons to change
  the values, but note that if one dimension is an odd number, the other can
  only be set to even numbers to ensure an even number of cards (and hence a
  full set of pairs).  Finally, 'Different cards' sets the number of
  different images used.

  The 'Play' section allows the length of time the cards are turned over for
  to be adjusted.  The value shown is in half-seconds.  If a suitable version
  of PlayIt is installed and has been seen, selecting the 'Use sounds' option
  will cause the card sounds to be played if available.

  Click Select on 'Apply' to use the changes or on 'Cancel' to forget them.
  'Save' will use the changes and save them so that they will be used in
  future too.  Clicking with Adjust will leave the window open; with 'Cancel'
  this resets the values in the window to the state they were in when it was
  opened.



Designing New Card Sets
-----------------------

  To add to the selection of cards available, Shift-double-click on !Pairs
  and open the Cards directory.  This holds the sprite files and sounds used
  for the card sets.  Each set of cards is stored in a separate directory;
  the name of the directory is used to identify the cards within the
  application.

  The directory for each set contains a sprite file holding the images of the
  cards, with one sprite per card.  To create different versions of a card
  set for low and high resolution modes (mode 12 and mode 27), use the
  standard Wimp sprite name suffixes to differentiate the files.  The low res
  file should be called Sprites and the high res set Sprites22 (if you create
  a high-res mono set, call it Sprites23).  If you don't create a set of
  low-res sprites, don't bother with the number suffix.

  The sprite files should each contain a set of sprites, one for each card,
  named from "0" to "31" (if fewer images are created, the file will still
  work, but fewer different cards can be used in the game).  An additional
  sprite named "null" must also be included, which is used for the backs of
  the cards.

  The sprites can be any size and colour depth, although bear in mind the
  practicality of using the cards (particularly on low-res monitors).  The
  dimensions of the card set, used for laying out the playing grid, are taken
  from the "null" sprite.  For this reason, all the cards should have the
  same dimensions as the "null" sprite.

  To use images derived from other formats (such as JPEGs), use ChangeFSI to
  convert the images into sprites and then use Paint to merge them into a
  single sprite file and adjust the image names accordingly.


  Adding sounds
  -------------

  To add sounds to the card set, create a directory within the card set
  directory called Sounds.  This directory should contain a set of sound
  samples.  Each card gets a file; the names of the files should match the
  sprite names in the sprites file.

  The formats that can be used for the sound samples are anything that PlayIt
  can support.  See the PlayIt documentation for more details.

  If you design any new sets of cards that you think others could make use
  of, I would be happy to include them in the Pairs distribution.



Version History
---------------

  Here is a list of the versions of Pairs, along with all the changes made.


  0.01 (19 April 1997)
  --------------------

  Initial release version.


  0.10 (24 November 2002)
  -----------------------

  Limited distribution Beta release.

  * Merged scores window into main game window.
  * Support for varied sprite sizes and different size files added.
  * Options system re-written so changes to configuration are only used when
    creating new games.  Save options facility added.
  * Resources internationalised and MessageTrans used for all text.
  * Players' names are now configurable and editable.
  * Variable sized boards are now possible.
  * Any number of different images (up to half the total cards in play) are
    now allowed, with the number of cards of each type being varied as
    required.
  * Help text now accessible from the icon bar menu.
  * Game statistics window added.
  * Interactive help support added.


  0.20 (30 November 2002)
  -----------------------

  Public Beta release.

  * Fixed bug causing card menu to be widthed wrongly under RISC OS 3.1.
  * Card set list handling improved, so that available sets are read each
    time the Options Window is opened.
  * When setting the options, the number of different cards in play is
    limited to the number of different cards in the currently chosen pack.
    The selected pack is ticked in the card menu.
  * Error trapping of sprite file handling improved.
  * Adjusts relative width of name icons in main window to try and keep both
    names visible, if possible.
  * Sprite masks are now plotted for the playing cards.
  * Bug fixed which caused lockup when computer player picked random cards
    from certain remaining sets.
  * Card forget routine moved to before the computer's turn, so that 100%
    really means 100% and the human's two cards are not remembered.


  0.30 (12 March 2003)
  --------------------

  Limited distribution release.

  * Changed card set directory structure so that each set has its own
    directory within !Pairs.Cards.
  * Sound samples can be attached to cards, so that they are played when
    cards are turned over.


  0.31 (17 March 2003)
  --------------------

  * Method of loading PlayIt improved to prevent screen refresh.
  * Waits for human's second card sound to finish before turning the cards
    back over.


  0.32 (2 April 2003)
  -------------------

  * Problems with sound events across games and after game window was closed
    have been fixed.


  0.35 (6 September 2014)
  -----------------------

  * Build system revised and license updated to EUPL.
  * Added 'Help' entry in iconbar menu.
  * Added 'Website' button to program information window.
  * Test for presence of Sprite files in card folders before loading, to
    avoid crashing if the folders are not card sets. (Ticket #483)
  * Correctly set the sounds option when starting games, to prevent an
    apparent hang if sounds are not available. (Ticket #188)


  0.36 (5 March 2017)
  -------------------

  * Fix !Help so that 'Help' menu items work correctly.


  0.37 (23 September 2020)
  ------------------------

  * Licence updated to EUPL v1.2.
  * Use ResConf-style system variables to identify resources.



Updates and Contacting Me
-------------------------

  If you have any comments about Pairs, or would like to report any bugs that
  you find, you can email me at the address below.

  Updates to Pairs and more programs for RISC OS computers can be found on my
  website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: info@stevefryatt.org.uk
