forked from dolda2000/hafen-client
-
Notifications
You must be signed in to change notification settings - Fork 44
/
README
145 lines (116 loc) · 6.74 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
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 the `build.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' and `ant' 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 the `lib/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 running `ant 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.