Cardset Customization Tutorial
==============================
:Author: Eric Rausch
:Email: <neelix570@gmail.com>

Setting up a Cardset
--------------------
The easiest way to create a cardset would be to copy an existing cardset folder of the same type in your cardsets directory.  All cardsets need a number of files to work.

* An image for each card - these images should be the same format and the same size, as defined in the config.txt file (described below).  These files should be named something like 01s.png for the ace of spades.  The first two (or more) digits represent the rank, and the letter after represents the suit.  The suits are labeled hcds in French decks or decks that use French suits (i.e. Hex A or Tarock decks), and the suits are alphabetical for other decks.  The suit letter z is used for jokers or trumps.
* A shade file - shade.png, for example.
* At least one back image, as defined in the config.txt file below.
* A config.txt file, the format described below.
* A copyright file, containing copyright info.

The following optional files may also be added, but are only used under certain circumstances.

* Bottom images.  A number of images for the bottoms of stacks.  These are not used unless your PySol install does not support generating stack bottoms, or you enable them manually (currently only possible through editing the options.cfg file).  Which bottoms are used depend on the cardset type.  Each bottom has a version with a suffix of -n, indicating the negative bottom that gets used if the appropriate option is enabled.
* Shadow images.  These will only be used if your PySol install does not support auto-generated shadows.

config.txt template
-------------------

....
PySolFC solitaire cardset;$A;$FMT;$B;$C;$D,$E;$F;$G;$H
<internal_name>;<cardset_name>
X Y D
XOFF YOFF SXOFF SYOFF
back01.ext
back01.ext;back02.ext;back03.ext
....

Line 1
------

*$A:* The cardset version number that belongs to the number of fields divided through ";" on the first line (e.g. `.gif;1;78;8,1016` -> `$A=4`)

( *WARNING:* For Mahjongg, $A must always be 6 or 7 and the $F field must be included in the line; however, you can put `0` in `$F` if you wish, in that case. )

( *NOTE:* $D and $E are comma separated and count for one field )

*$FMT:* The format of the images used - .gif, .png, .jpg, .ppm, and .bmp are supported

*$B:* The type of the cardset (see types below)

Cardsets Types:
~~~~~~~~~~~~~~~

* French = 1
* Hanafuda = 2
* Tarock = 3
* Mahjongg = 4
* Hex A Deck = 5
* Mughal Ganjifa = 6
* Navagraha Ganjiga = 7
* Dashavatara Ganjifa = 8
* Trumps Only = 9
* Matching = 10
* Puzzle = 11
* Ishido = 12

*$C:* The number of cards in the cardset, generally 42, 48, 52, 68, 78, 96 or 120

*$D:* The Style of the cardset (this field can hold one or more comma separated values)

Cardsets Styles:
~~~~~~~~~~~~~~~~

* Abstract = 35
* Adult = 1
* Animals = 2
* Anime = 3
* Art = 4
* Cartoons = 5
* Children = 6
* Classic Look = 7
* Collectors = 8
* Computers = 9
* Divination = 36
* Engines = 10
* Fantasy = 11
* Four Color = 37
* Ganjifa= 30
* Hanafuda = 12
* Hex A Deck = 29
* Holiday = 13
* Ishido = 34
* Mahjongg = 28
* Matching = 32
* Monochrome = 38
* Movies = 14
* Matrix = 31
* Music = 15
* Nature = 16
* Operating Systems = 17
* People = 19
* Places = 20
* Plain = 21
* Products = 22
* Puzzle = 33
* Round Cardsets = 18
* Science Fiction = 23
* Sports = 24
* Tarock = 27
* Vehicles = 25
* Video Games = 26

*$E:* The origin (country) of the cardset

Cardsets Origins:
~~~~~~~~~~~~~~~~~

* Australia = 1021
* Austria = 1001
* Belgium = 1019
* Canada = 1010
* China = 1011
* Czech Republic = 1012
* Denmark = 1013
* England = 1003
* France = 1004
* Germany = 1006
* Great Britain = 1014
* Hungary = 1015
* India = 1020
* Italy = 1005
* Japan = 1016
* Netherlands = 1002
* Portugal = 1022
* Russia = 1007
* Spain = 1008
* Sweden = 1017
* Switzerland = 1009
* USA = 1018

*$F:* The Year the cardset was created (in the range 1000 to 2299)

*$G:*  The subtype of the cardset.  Usually 0 - for French type cardsets, a value of 1 is used if there are jokers.  For Puzzle type cardsets, it is the number of pieces per row/column.

*$H:* Whether the cardset is a 3D Mahjongg cardset - 1 if it is, 0 if it isn't.  For cardsets with a version less than 7, version 6 cardsets treat this value as 1, and older version cardsets treat it as 0.

Line 2
------

`<internal_name>`: A name for PySolFC to identify your cardset (without spaces)

( *TIP:* You could add a number prefix (e.g. 123-cardset-name) )

`<cardset_name>`: Your cardset name as it should appear in the cardset manager.  Note that a cardset name of more than 30 characters will be truncated.

Line 3
------

* *X:* The cards' width (the card image width)
* *Y:* The cards' height (the card image height)
* *D:* The color depth (mostly 8)

Line 4
------

* *XOFF:* The horizontal offset of the cards
* *YOFF:* The vertical offset of the cards
* *SXOFF:* The offset of the horizontal shadow (mostly 7)
* *SYOFF:* The offset of the vertical shadow (mostly 7)

Line 5
------

`back01.ext`: The name of the default back image (where `ext` means the file extension
e.g: `png` or `gif`.)

Line 6
------

`back01.ext;back02.ext;back03.ext;…``: The name of the other back images, including the default one.

About this document:
--------------------

*NOTE:*
This tutorial may be incomplete. It is given as is, without any warranty,
to help players customize their own cardsets.
You are welcome to send any suggestions to: mailto:neelix570@gmail.com[the Author's E-mail],
https://github.com/shlomif/PySolFC/issues[PySol FC's GitHub issue tracker] or
https://sourceforge.net/p/pysolfc/_list/tickets[PySol FC's Sourceforge issue tracker].

*NOTE 2:*
You should also place a file called `COPYRIGHT` in the same directory as `config.txt`,
containing the text that can be accessed via `Info/Settings`.

License:
~~~~~~~~

This tutorial was created under the terms of the GNU General Public License
version 3 or later. You can redistribute it as is and/or modify it.

Shlomi Fish, hereby puts his modifications to this document under
https://github.com/shlomif/shlomif-computer-settings/blob/master/shlomif-settings/git/commit-messages/cc0-copyright-disclaimer.txt[CC0 / Public Domain / MIT License / GPL terms]

Credits:
~~~~~~~~

Credits go to:

mailto:andsa@web.de[Andreas Sauer] for clarifying certain points +

https://www.shlomifish.org/[Shlomi Fish] for making some improvements to this tutorial
