-
Notifications
You must be signed in to change notification settings - Fork 100
Developer's Guide
This project can be built using the Eclipse IDE (versions Luna and Mars are tested). The development process follows the Fork & Pull principle.
The code of this project has grown over years. Furthermore, I never expected this project to get so far. However, I want to make clear that I know there is still a lot to do and that some parts of the code need to evolve. Therefore I'm glad you want to help. If you find ugly code, you know a better way to do something or you think the architecture needs to be changed, feel free to tell me. Feel free to open tickets for these proposals, so everybody can have a look on them and share their opinion.
Moreover, if you have any questions or additions to this guide, feel free to write me. As the documentation on this project is rather small, I'm also looking forward to improvements to it.
In order to assist development, follow these steps:
- Make sure you have installed the Java Development Kit (JDK). If you're on Windows, make sure the JAVA_HOME variable is added as a Windows variable. JAVA_HOME should point to the location of your JDK installation (example: C:\Program Files\Java\jdk1.8.0_60)
- Fork this repository.
- Clone the forked repository to your local machine.
- Import all projects in the cloned repository into your Eclipse Workspace (via "File" -> "Import" -> "Existing Projects into Workspace"). As this repository contains multiple Eclipse Projects, we recommend creating a new workspace for it.
- Build all the projects. This is easiest done with "CTRL + B". Alternatively, you can right click the jsettlers.main.swing -> build -> build.ant and click "Run as" and chose "Ant Build". If you have trouble building the projects, the following steps might help:
- Clean and build all the projects.
- Make sure the project jsettlers.common has a source folder called "gen". If not, refresh the project. If it still isn't there, try to explicitly build the project (right click on the project -> "Build Project").
- After that, rebuild all projects (without a clean!). You can do this with "CTRL + B".
- If there is still a project refusing to build, try to explicitly build that one via right click on the project -> "Build Project".
- If you know how to fix this trouble, I'm looking forward to your hints and code changes ;).
- When developing changes, create a new branch off of the project's master and give it a speaking name.
- Regularly commit your changes and push them to the new branch in your forked repository.
- If you have questions, need help, or want to see the test results of your code, create a Pull Request to this repository.
- After your changes have been reviewed and all is fine, we will merge them into the master.
In order to ease collaboration and reduce unnecessary overhead, developers should follow these guidelines.
This project uses a common auto formatter configuration. Please stick to this convention to prevent unnecessary merge overhead. The configuration file is provided as Eclipse Auto Formatter configuration.
To configure Eclipse correctly, open the workspace containing the project and select "Window" -> "Preferences" in the top bar. In the search field of the dialog, type "save actions" and select the Java save actions as shown in the picture below.
]
Adjust your settings to match the ones of the figure before clicking on "Formatter" and then "Import".
The formatter configuration can be found in the repository at "docs/eclipse-setup/formatterConfiguration.xml".
To prevent unnecessary merge conflicts, organize the imports as shown in the following figure.
Add the packages go
and jsettlers
and order all packages as shown.
Set the combining imports thresholds to 99.
Set encoding in "General" -> "Workspace" -> "Text file encoding" to "UTF-8" (Works with all special chars of all languages)
For IntelliJ IDEA, there is a plugin to use the Eclipse Auto Formatter configuration. For example this article covers the subject and gives a detailed manual.
- Android Development Tools for Eclipse: Required for building, running and developing the Android version of JSettlers in Eclipse. You furthermore require the Android SDK installed on your machine. Even if you don't want to develop the Android version, this is recommended, as without it, you will have compile errors in the Android projects, making it hard to find real compile errors introduced by your changes.
- FindBugs: Runs a static code analysis to detect potential bugs and bad code.
These plugins can be downloaded via the "Eclipse Marketplace".
The following tips can help you getting started with developing on this project.
In order to run JSettlers properly as developer, you must start the jsettlers.main.swing.SwingManagedJSettlers
main method in the correct working directory. This working directory is the jsettlers.main.swing
subproject folder in the GIT repository. Only when using this working directory, the required config.prp file can be found (when developing).
To ease development, JSettlers supports several command line parameters. Amongst others, we find the following combinations helpful.
-
jsettlers.main.swing.SwingManagedJSettlers --control-all --console-output --activate-all-players
-
--control-all
allows you to control and see the settlers of all players, instead of only your own ones. -
--console-output
prints the console / logging outputs to the console, instead of writing them to a file. -
--activate-all-players
ensures that all players on a map are positioned at start. This is especially useful when testing development with the single player mode, as otherwise you would only have one player on the map.
-
-
jsettlers.main.swing.SwingManagedJSettlers --control-all --console-output --targetTime=10 --replayFile="2015-02-27_13-23-03_new_map_replay.log
- This combination of parameters is very helpful for analysing bugs experienced during a game. With the
--replayFile
parameter, it is possible to specify a replay file that is then used to rerun the exact same game (by using the same map, random seed, and user inputs). -
--targetTime=<X>
specifies the game time of the savegame. This time is specified in minutes. -
--replayFile=<PATH TO FILE>
gives the path to the replay file used as source.
- This combination of parameters is very helpful for analysing bugs experienced during a game. With the
-
jsettlers.main.swing.SwingManagedJSettlers --control-all --console-output --activate-all-players --localhost
-
--localhost
ensures that localhost is used as multiplayer server, making it useful for local multiplayer development / debugging. NOTE: Of course you need to have a Dedicated JSettlers Server running on localhost (see below).
-
-
jsettlers.network.server.DedicatedServerApp
- Starts a local dedicated server.
-
jsettlers.main.replay.ReplayToolApp --targetTime=10 --replayFile="2015-02-27_13-23-03_new_map_replay.log"
- This tool lets you create a savegame from a replay file at a specified target time. Any remaining tasks of the replay that happen after the target time, will be saved to a new replay file
replayForSavegame.log
. This helps when searching a bug that happened after some hours of playing with a replay file. Instead of needing to replay the whole game every time you want to start the debugging over, you can create a savegame close to the time the bug happens and start replaying from there. -
--targetTime=<X>
specifies the game time of the savegame. This time is specified in minutes. -
--replayFile=<PATH TO FILE>
gives the path to the replay file used as source.
- This tool lets you create a savegame from a replay file at a specified target time. Any remaining tasks of the replay that happen after the target time, will be saved to a new replay file
- The project "jsettlers.main.android" displays a classpath error (red exclamation mark on the project symbol)
- Right click the project, select "Run As" -> "Android Application". This causes the missing dependency to be built. Please note, the first run may fail, with the message that there are errors in the project. After that, simply wait until Eclipse detects that the errors are no longer valid. Then you can run the project as Android Application and install it on your device.
The JSettlers code is divided into multiple projects. In the following, there main purposes will be described.
This is the main graphics project. It contains everything needed to draw the in game map.
This is the GUI overlay used on Android.
This is the GUI overlay used on PC. This does not really require swing any more, it also works with native gl.
This project contains the base graphics abstraction interface. Contains all code used on all plattforms
The Android graphics implementation.
Experimental: A native OpenGL implementation for Linux. No external libraries are needed here. Still needs some work (e.g. has no text support so far). Target is to bypass the overhead of JOGL and remove the need for external libraries.
The default Linux/Windows drawing library. It uses Swing to create a GL drawing window.
This project contains all the abstractions needed by most other modules. This includes the map interfaces, building specifications, further resources, image tables and some utility functions. One main purpose is to create a lose coupling of the game logic and the graphics layer.
The core game logic. Including the main grid, settlers, buildings, algorithms for path finding and management.
This project contains the network logic as well as the dedicated server implementation and is only used by the jsettlers.logic** project.
The Android launch code.
The Linux/Windows/Mac launch code using a Swing UI.
A standalone map creator app that lets you design your own maps.
In this project all test cases are collected. These are not included in a build of the game. Unit tests are run by Travis automatically. It also contains many helper classes that are no unit tests but contain main methods for manual debugging / testing.
A building editor. We use this to help implement new buildings. It presents a UI to specify blocked and protected tiles of a building as well as the stacks of required material. This code is not included in a build.