This guide gives a brief overview of the Hearts package and related resources on this website.
This documentation (when complete) should give a good overview of the steps required to build, install and modify the Hearts game. Right now it's still in the process of being written though. If you need any help (or if you simply want to talk about the game) feel free to sign up to the Hearts mailing list.
You can download a nightly snapshot of the Hearts trunk at: http://www.jejik.com/files/gnome-hearts/gnome-hearts.snapshot.tar.gz You can also browse our Subversion repositories online at http://svn.jejik.com. You can also download a release tarball from the download page, but because the game is constantly under development, the release sources may be outdated.
If you have Subversion installed on your system, you can grab the latest sources directly from the repository. Our repository is readable by guests (commits require an account though). Use the following command:
Before you can compile and install Hearts, you need several other packages and libraries:
Aside from the packages and libraries listed in the above list, you also need a decent C build enviroment (the build-essential package on Debian and deratives), the GNU autotools, the GNU gettext package and GNOME's intltool package.
Untar the sources somewhere convenient and run the ./bootstrap script. If you downloaded a release tarball then you can skip this step. Release packages are already bootstrapped. This script checks some things in your build enviroment, processes some macro's and runs various autotools in the right order. If all goes well then the only thing it will output is that you can run the ./configure script (it will not run it for you, so you can play with the standard ./configure options yourself).
Note that you need a working internet connection for this step to fully execute. If you do not, then ./bootstrap will complain that it cannot get some config files from the internet. Download them yourself (or get them via other means), add them in the package root directory and rerun the ./bootstrap. You need the following two files:
Compiling and installing is done the usual way (for GNU packages that is) through the invocation of the magical commands:
If the ./bootstrap ran without errors and you have all required libraries then there should be no errors. If you find that other libraries than the one's listed above are required, please post to the mailing list so we can update this document. The compilation will throw a few warnings at the end. These are caused by Python and can be ignored.
If you configure Hearts with the same prefix as you have installed gnome-games and gnome-games-extra-data then Hearts will be able to use the card styles provided by those packages. Make sure you uninstall and version of hearts you already have before doing so. Also, you should probabely delete the .gnome-hearts.cfg file from your home directory because hearts won't be able to find the old paths. For most Linux systems you should configuring the package with:
The Hearts source code consists of two main parts: the core game written in C and the computer opponents in various Python scripts. If you want to work on the computer opponents then you don't need to know C. Simply edit the Python scripts (or create a new player script) and put it in the /scripts/players directory.
The core game is written in C and can be found in the /src directory. The overview below lists what can be found where.
A note about cards: The only object that actually holds any cards is the CardsDeck. All other objects such as hands of cards and the trick only pass around pointers to individual cards in the CardsDeck.
The computer opponents are implemented as separate Python scripts in the /scripts/players directory. Each Python script is a distinct player. If you want to create your own players, simply write a script and put it in the players directory. If you want an example player script, take a look at the standard AI in /scripts/stock_ai.py. Just copy that to /scripts/players/your_player.py and start editing it. The player should become selectable from the preferences dialog.
Each player runs as a separate Python module inside the core hearts game. That means that you are free to use global variables to keep track of things during the game over different tricks and rounds.
The core game sets several class attributes in your player. These attributes are reïnitialized before each function call, so feel free to munge them. Most of these attributes contain cards or lists of cards. A card is a tuple with two values. The first value is the suit of the card and the second is the rank. In Python you would define a card with:
You can use numbers, but for your convenience a range of global variables have been defined by the core game:
A list of cards in Python would look like:
The core game sets the following class attributes for you before calling one of your functions:
Your player must derive from the Player class, and your classname must be prefixed with PlayerAI. At a bare minimum, your player must implement the select_cards() and play_cards() method. Hearts will quit with a failed assertion if you do not provide these. The select_cards() method should return a list of three cards that you want to pass on to the next player. The play_card() function should return a single valid card that you want to play on this trick. You must also set the self.name attribute to string containing the name of your AI as it should be used in the Hearts game.
Optionally, you can also provide a trick_end() or round_end() method. The trick_end() method will be called at the end of a trick, when all four players have played their cards and the trick is full. The round_end() function is called at the end of each round, after all cards have been played (and after the trick_end() function).
The Trick object represents the trick that is currently being played by the players. It has the following attributes and methods.
The core game also defines several usefull functions, filters and sorting methods you can use in your player scripts. Filters can be used to filter lists of cards. An example:
Sorting methods can be used as such:
All bugs, feature requests and the like should go in Bugzilla, but before you file a new one, please do a quick search of bugzilla and the mailing list archive to see if your issue has already been reported. We don't expect you to search for hours, but do read the first page or so of results to see if your bug is listed.
Hearts is translated through Launchpad.net's Rosetta system. Translations should be added and updated through there, not as diffs for the subversion repository. This makes our life easier because we won'thave to resolve conflicts between translations in Subversion and translations in Rosetta. You can find Hearts in Rosetta as https://launchpad.net/products/hearts/trunk/+pots/hearts.
If you have a patch that you want to contribute then you can send an e-mail to the Hearts mailing list at firstname.lastname@example.org. You must be subscribed to the mailing list to do so (to prevent spammers abusing our lists). If you have a Subversion account on our server, you can commit it directly. You might want to post it to the list before committing anyway so other people can proofread your code. This goes especially for non-trivial patches.