Client Source Code

The source code for the Haven game client is available publically, subject to certain terms. The purpose of this document is to describe the philosophy behind this and what it means to any user of the code (that might be you!) in practice. For the nitty-gritty details of the copyright terms, please see the COPYING file in the client source tree, a copy of which is available online.

Philosophy

I (Fredrik Tolf) am quite a long and ardent supporter of free software. I have previously published quite a number of programs under various open source licenses for public perusal and I use almost exclusively free software on my own computers; so I know well the advantages for both users and developers of using free software.

Free Software and Games

However, games offer a very interesting clash of various property interests. Obviously, it is always good for software to be as free as possible. On the other hand, the game content itself (being not only images or other multimedia data that constitute the game, but also the code defining the game rules) is something I regard very much like, say, a book of fiction or a movie: Releasing the content of a game freely would not only prevent the makers of a game (us) to profit from the game, but the full disclosure of game mechanics and all game content would also detract from the exploration and discovery aspects of the game in question, leading, in all likelyhood, to a worse experience for the players. Yes, an individual can always avoid looking at the code (maybe), but even then it may be hard to avoid the greater community of players, and especially so in a MMO game such as Haven.

As far as general opinions and rules of thumb go, it is therefore my (current) opinion that the best situation for a game to be in is one where the game engine is free software, and the game content is clearly separate from the engine and proprietary.

Its Relation to Haven

Unfortunately, Haven is not quite at that point. The game engine, located almost entirely in the game server, cannot currently be cleanly separated from the game content, and it is not obvious if it ever can be. Fortunately, however, the client is very much in a situation where that is possible—fortunately especially since the client is the program which players actually run and which is therefore what matters the most to them. I designed the client from the outset to be as little as possible, and I think I have succeeded rather well in that goal: It is little more than a dumb terminal with some interpolation logic. Furthermore, the client's source code is very cleanly separated from the actual content of the game; they even reside in completely different files (the haven.jar and haven-res.jar files)! The client implements only the barest possible minimum of the game mechanics, so it ought be very difficult to cheat by modifying the client. We actually (more or less) decided on releasing the client code quite some time ago, and much of the delay has simply been issues of deciding the exact legalistic details of everything.

Free and Non-free Parts

The actual source code of the client is released under the GNU LGPL, which means that you're basically free to do whatever you want with it, as long as you yourself continue releasing it under the GNU LGPL. That would include building a new game server of your own devise and hosting a new game using the same client. We don't mind—that would basically be a new game anyway, and we might even enjoy playing it! More importantly, having access to the client code allows you to modify the game UI to fit you better, or to fix bugs that may be peculiar to your system or any other issue that may be important to you.

That applies only the source code of the client proper, though. When you play Haven & Hearth, the client proper is combined with our game resources, and it is that combination (along with the server to which it connects) which creates the actual game. As long as you play that combination, we consider that being our game that you play. As such, there are a few restrictions which we consider proper. Most importantly, there are a few ways in which the client can be modified so as to constitute what we would consider cheating (rather minor cheating, but cheating nonetheless). As a matter of policy, we do not allow such clients to connect to our server, or use our resources. In practice, we are, of course, not likely able to police all such use, but if we do discover it being used blatantly, we'll certainly take action. Likewise, we would, naturally, consider it an offense to try and crack or otherwise break the server. (Those points will probably not apply to the vast majority of you reading this text, so please do excuse my brusqueness. You probably agree that they are worth mentioning.)

Again, please see the COPYING file for the details.

Detailed Usage of the Source Code

To begin with, you can get a copy of the source code by using the Git Version Control System. Our public (pull-only) repository is accessed via the Git URL <git://sh.seatribe.se/client>. Just clone a repository and hack away!

The Basics

To compile and run the client, you'll need the following things:

• A Java 1.5-compatible JDK,
• Apache Ant, and
• Locally installed versions of JOGL's shared object files (that is, its native code).

Compiling

Compiling the client shouldn't be harder than running ant on the default target in the client source tree. Note that the default target will also download the (proprietary) JAR file with the game resources and place it in the build tree, so that it can be accessed by the client when running.

Running

In turn, running the client shouldn't be any harder than running java -jar build/haven.jar. However, to actually connect to the real server (instead of your local machine), you need to specify the name of the server, being moltke.seatribe.se, as a command-line argument. You will probably also be aided by turning on some of the real-time debugging output with the -d option. The common way of running the client, thus, would be java -jar build/haven.jar -d moltke.seatribe.se. There are some other useful command-line switches as well. Run java -jar build/haven.jar -h to see a summary, and see the code (particularly src/haven/Config.java) for the details.

Finally, if you insist on using an IDE of some kind, you'll have to figure out on your own how to make it do the procedure outlined above. I don't particularly believe in such things.

The Source Tree

The layout of the source tree should be rather simple to comprehend. The src directory contains all the actual source code; the lib directory contains a couple of third-party libraries (they are described more in-depth in the COPYING file); the etc directory contains various odd ends, such as a couple of auxiliary scripts that you'll probably never use, or some server certificates that are built into the Jar file for runtime checking; the build script creates a build directory in which all intermediate files and the final results of the build are placed (it is the only location actually modified by the build script); the build.xml file (Yuck) is the Ant build script; and COPYING is the file describing the copying rights in detail.

As for the source code itself, I cannot reasonably describe all of it, but the following classes ought to be useful as pointers:

• haven.MainFrame: The class containing the main function when running the Jar file normally
• haven.HavenPanel: This class takes care of the vast majority of ground-work; it runs the main game loop, cycles the draw engine and collects input events.
• haven.Session: The class mainly responsible for the protocol decoding and encoding and for establishing and maintaining the connection to the server
• haven.error.ErrorHandler: When running in the JNLP environment, this class (which extends java.lang.ThreadGroup) takes care of all the Haven threads, and catches uncaught exceptions, serializes them, and sends them to the server so that I may look at them.
• haven.Resource: This class manages the (proprietary) game resources and loads them as necessary.
• haven.Widget: This is the base class of all the UI widgets in the game. All specialized widgets need to be registered with it, so that their static code initialization is run (and thus, their names registered) when the game starts.

Coding Style

The first thing you'll probably notice is that my coding style is a bit idiosyncratic—probably more so than usually. It is probably not made any better by the fact that I didn't really intend the code to be public from the beginning, but I'll admit right now that the main reason is because I hate Java with a passion. Describing all the details and reasons for it is certainly beyond the scope of this document, though, so I'll leave it aside. The main things that should be noted are these:

• Indentation is done in blocks of 4 columns.
• The code uses trailing-brace style ("if(...) {", that is) exclusively.
• The Tab character (ASCII 9, that is) 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 (Eclipse and Visual Studio users are warned especially!), 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 abhor camelCase. If you wish me to accept back any modifications you make, you would do good not to use it. Thank you!

Contributing Back

If you want me to accept back some changes that you might have made into the public client available from the website, there is one main rule that we wish to enforce: We want you to sign over ownership of the code that wish to contribute to us (the same way as the FSF works, in other words). It may seem draconian to some, but it is quite important to us, for two main reasons:

• First of all, we wish to ensure that we do not lose control over the client. It would be a great pity if game development was being hindered by some legalistic details along the way or because we would become prevented from doing certain changes because of ownership issues.
• I'll admit it: As long as we own the code, we are free to change licenses in the future. We don't expect to have to do so, but it may become important in case of some weird kind of abuse or other unforeseen issues. In relation to this, it is worth mentioning that it is our hope that we may, at some point, be able to derive profit from Haven in one way or another (it is still unclear just how, though). In such an event, your code would be used for our profit.

Generally, we would consider the code 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. Since we use Git, the preferred method for us to accept code is, simply, by way of pulling it. If you can put up a public pull server for publishing your changes to us, that would be preferable. Just mail me the Git URL to your repo and I'll check whatever you've done.

Of course, that may be hard for you, for some reason or another. If it's just some small change, you can just mail me a patch in the Unified format (just run git diff with any appropriate arguments). It might be even easier for you to use git send-email; please see its documentation for details.