Developer's Guide

Developer's Guide

This project can be built using the IntelliJ IDEA and Android Studio. The development process follows the Fork & Pull principle.

A Word in Advance

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.

Development Process

Prerequsites:

• 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.

Setting up your Development Environment

In order to assist development, follow these steps:

1. 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)
2. Fork this repository.
3. Clone the forked repository to your local machine.
4. Open the main folder of the project in your IntelliJ IDEA or Android Studio.
5. The IDE should automatically sync the gradle files and you should be able to build the project.
6. When developing changes, create a new branch off of the project's master and give it a speaking name.
7. Regularly commit your changes and push them to the new branch in your forked repository.
8. If you have questions, need help, or want to see the test results of your code, create a Pull Request to this repository.
9. After your changes have been reviewed and all is fine, we will merge them into the master.

Development Guidelines

In order to ease collaboration and reduce unnecessary overhead, developers should follow these guidelines.

Auto Formatter

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.

IntelliJ IDEA

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.

Further Plugins

• 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".

Tips & Tricks for Developers

The following tips can help you getting started with developing on this project.

Java8 Support with Retrolambda and Streamsupport Frameworks

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.

Correct Working Directory

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).

Recommended Run Configurations

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.
• 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.

Known Issues

• 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.

Project Structure Overview

The JSettlers code is divided into multiple projects. In the following, there main purposes will be described.

jsettlers.graphics

This is the main graphics project. It contains everything needed to draw the in game map.

jsettlers.graphics.androidui

This is the GUI overlay used on Android.

jsettlers.graphics.swing

This is the GUI overlay used on PC. This does not really require swing any more, it also works with native gl.

go.graphics

This project contains the base graphics abstraction interface. Contains all code used on all plattforms

go.graphics.android

The Android graphics implementation.

go.graphics.nativegl

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.

go.graphics.swing

The default Linux/Windows drawing library. It uses Swing to create a GL drawing window.

jsettlers.common

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.

jsettlers.logic

The core game logic. Including the main grid, settlers, buildings, algorithms for path finding and management.

jsettlers.network

This project contains the network logic as well as the dedicated server implementation and is only used by the jsettlers.logic** project.

jsettlers.main.android

The Android launch code.

jsettlers.main.swing

The Linux/Windows/Mac launch code using a Swing UI.

jsettlers.mapcreator

A standalone map creator app that lets you design your own maps.

jsettlers.tests

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.

jsettlers.buildingcreator

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.