Developer's Guide
This project can be built using the IntelliJ IDEA and Android Studio. 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.
- The project maintainers develop with Android Studio and IntelliJ IDEA. At the moment we cannot support Eclipse. If you find any outdated references to Eclipse in this manual, please inform us.
- Furthermore you need to install the Android SDK (can be installed with Android Studio) to be able to work with the Android projects.
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.
- Open the main folder of the project in your IntelliJ IDEA or Android Studio.
- The IDE should automatically sync the gradle files and you should be able to build the project.
- 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.
As the project maintainers don't use Eclipse, we cannot ensure the project is compatible with it. However, the following tipps have been proposed by an Eclipse user:
- Import the project as gradle project
- JSettler has circular dependencies, which produces problems in Eclipse, follow the second post to solve the issue: https://github.com/eclipse/buildship/issues/460
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. The configuration will be switched to an IntelliJ configuration in the future.
Install the Eclipse Code Formatter Plugin as shown in the following figure.
After you have installed the plugin (maybe a restart of IntelliJ is required) configure the Eclipse Code Formatter Plugin. Use the docs/eclipse-setup/formatterConfiguration.xmlwhich is contained in the repository.
Add the packages go and jsettlers to Import order [x] Manual configuration and order all packages as shown.
To prevent unnecessary merge conflicts, organize the imports as shown in the following figure. Set the combining imports thresholds to 99.
The following tips can help you getting started with developing on this project.
To be able to use most Java8 features, we are using the Retrolambda and Streamsupport frameworks. Please have a look at the wiki page discussing this in more detail.
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-allallows you to control and see the settlers of all players, instead of only your own ones. -
--console-outputprints the console / logging outputs to the console, instead of writing them to a file. -
--activate-all-playersensures 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
--replayFileparameter, 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-
--localhostensures 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 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.