Haven & Hearth Client

This client is used to connect to the server for the Haven & Hearth online game and play said game. For details regarding the game itself, please refer to its main website at http://www.havenandhearth.com/. This file exists mainly to describe various technical aspects of the source tree.

            Getting a copy

In case you are reading this README outside of a local copy of the source tree and wish to obtain one, the main way of doing so is by using the Git Version Control System. The public (read-only) repository is accessed via the following Git URL:

git://sh.seatribe.se/hafen-client

            Build process

In order to compile the source tree into a useful executable, the Apache Ant build system is needed. Running ant' reads thebuild.xml' file in the root directory of the source tree and performs the actions described by it to produce the executable output. There are two main outputs from the build process:

• The `build/hafen.jar' file is the main executable, but executed in that environment, it is not configured to connect to the official server, and by default it does not have the data files necessary to execute properly; rather, it is intended for local development against a local server, with locally supplied data files, and so if you are coming to this project with the intent to connect to the official server, this will not be what you are looking for, rather:

• The bin' directory contains a copy of the above described hafen.jar', but along with all the data files and configuration needed to connect to the official server. It can be executed with no further configuration (as with `java -jar bin/hafen.jar') and should work just like downloading the client from the main site.

In order to remove intermediary compilation artifacts and other dynamic state and return the source tree to a supposedly pristine state, the `ant clean' target can be run. There may exist cases of incompatible changes where doing so may be necessary in order for the source tree to properly recompile. They should be rare, but if you are stuck on some hard-to-explain compilation or run-time issue, please try it before giving up.

        External dependencies

The main external dependencies of the source tree are having a local Java Development Kit (JDK) installed, and (as mentioned above) the Apache Ant build system. On a Debian-based Linux system, these can usually be installed via the default-jdk' andant' packages. For other distributions or operating systems, please use local documentation or your own faculties.

Other than that, the client also requires the Java OpenGL implementation (JOGL), and also some data files from the main website. By default, the initial build process will download these dependencies from the main website into the lib/ext directory of the source tree. Once downloaded, they will not usually be updated, or even checked for updates, so subsequent runs should not depend on network access. If you want to supply your own local version of JOGL, you can do so by putting its files directly into lib/ext/jogl' and ensure that thelib/ext/jogl/has-jogl' file exists. As long as it does, the build system will not try to overwrite any JOGL files. Contrarily, in order to have the build system update JOGL to the latest version from the main website, the lib/ext/jogl/has-jogl' file can be manually removed. Please note that runningant clean' will remove the entire `lib/ext' directory, and so will both update JOGL from the main website and remove any local copy of JOGL that you may have supplied.

         Cursory source tree overview

The vast majority of files constituting the source code of the client reside in the `src/haven' directory. Given that standard Java directory structures tend to devolve into a bit of a dumping-ground of files of small and large relevance alike, some points of particular interest may be useful, as follows.

• MainFrame.java contains the main() function executed when running the client normally. It constitutes the main window of the client and starts everything running in it.

• Config.java loads all runtime configuration and handles any system properties, command-line arguments and the like to modify said configuration.

• JOGLPanel.java constitutes the main AWT component for running and rendering the game, and also contains the main-loop and all the event-dispatching machinery.

• Session.java handles the fundamentals of the main game protocol and maintaining the connection to the server.

• Resource.java is used to load any data not part of the source code itself, such as images, textures, audio clips, 3D models, &c&c.

• Widget.java contains the base class of all the UI widgets in the client.

         Formatting style

• Indentation is done in blocks of 4 columns.

• The Tab character (ASCII 9) is used in the classical and only correct way: It advances the cursor to the next column ordinal divisible by 8. It does not advance the cursor by 8 columns, and it most certainly does not advance the cursor by 4 or 2 columns. If you use an IDE, you may want to check your settings on that one, because they are often wrong.

• Line endings are neither Mac style (CR) nor Windows style (CRLF), but Unix style (LF).

• Last but not least, I'm not extremely particular about naming, but if it's one thing that I really dislike, it is camelCase. If you wish me to accept back any modifications you may make, you will certainly increase your chances of acceptance by avoiding it. Thank you!

        Contributing back

If you want me to accept back any changes that you might have made into the public client available from the website, the one main rule that we wish to enforce is that we want you to sign over ownership of the code you wish to contribute to us. That may seem draconian to some, but please keep in mind that it is fairly common, being practiced not least by the FSF, and it is too important for us to not lose ownership of future development to forgo.

Generally, we would consider the code as owned by us as long as the copyright notices at the top of each source file mentions our and only our names, and as long as the same copyright notice is copied to any new source files you would create, and as long as you haven't made any changes to the contrary in the COPYING file.

Other than that, it's mostly just a matter of technical details and getting in contact. It should be noted that, while there is a repository on GitHub for the client, it is mostly just for backup, and the GitHub account is not commonly used, so if you decide to send a GitHib Pull Request, do not be surprised if it goes unnoticed for an extended period of time. More certain ways of receiving a response include e-mail or private messages on the Haven & Hearth forums.