JSettlers

This project intends to create a remake of the famous strategy game "The Settlers 3" published by Blue Byte in 1998. The project is developed in Java and runs on PC (Windows/Linux), macOS and Android.

The game is currently in an alpha status! Therefore bugs, frequent changes making saved games invalid and server abortions need to be expected. Nevertheless we will try to minimize trouble.

If you experience troubles / find a bug, help us fix it. Please either report your bug as an issue or post it on the JSettlers Discord in the #support channel.

The JSettlers game creates log files of your games that are essential for debugging. Therefore, always include the following information in a bug report:

1. What OS and JRE are you using? If it is Android, please state your Android version.
2. Revision of your build:
3. In the PC version this can be found in the head of the window as "JSettlers - commit: XXXXXXX".
4. In the Android version, the info is displayed on the start screen in the lower right corner as "build: XXXXXXX".
5. In the game's folder, there is a subfolder resources/logs/ containing a folder of log files for every game you played. Please package the folder belonging to your game where you experienced the bug (identifiable by date and map name). This folder contains the following files:
6. *_out.log: This is the console / debugging output of the game.
7. *_replay.log: This file contains all game relevant actions you and other players did in the game (e.g. place a building, send soldiers somewhere). With this game, we can recalculate your game and debug it to find the exact source of your trouble.
8. Specify the game time when you first experienced the bug (the game time can be found in the upper right corner while playing).
9. If you were playing a custom map, please attach the map. Without it, replaying the game won't be possible.
10. Describe what problem you experienced so that we can easily understand it.

Many thanks in advance for helping to improve this game!

In order to play the game, you need to have the folders "GFX", "SND" and "MAP" (optional) of the original version of "The Settlers 3" as obtained by installing the original "The Settlers 3" game (DEMO version also works).

The desktop releases come in two flavours:

• Portable builds (JSettlers-<version>-windows.zip, JSettlers-<version>-linux.zip, JSettlers-<version>-macos.zip): each bundles its own Java runtime, so no Java installation is needed. Just unzip and start.
• JSettlers.zip: the classic jar-based distribution (also includes the Map Editor). It needs an up-to-date installation of Java 11 or newer.

Java is preinstalled on Android.

After that, follow the detailed installation instructions for your platform.

1. Install "The Settlers III" or a demo version (Settlers III Amazons Demo) of it. Don't worry, if it is not running on your OS, we only need the graphics and sound files. In order to get them, you can also unzip the Amazons Demo exe file (yes: unzip the .exe) and copy the folders Gfx, Snd and Map (optional) into an empty folder on your computer.
2. Download the newest stable release and unpack JSettlers-<version>-windows.zip to wherever you want JSettlers to live.
3. Double-click JSettlers.exe.
4. On the first start, the game will ask you for the folder where you've installed / unzipped (see step 1) the original Settlers III. Please select the respective folder and continue.
5. Have fun and enjoy the game!

1. Install "The Settlers III" or a demo version (Settlers III Amazons Demo) of it. Don't worry, if it is not running on your OS, we only need the graphics and sound files. In order to get them, you can also unzip the Amazons Demo exe file (yes: unzip the .exe) and copy the folders Gfx, Snd and Map (optional) into an empty folder on your computer.
2. Download the newest stable release and unpack JSettlers-<version>-linux.zip to wherever you want JSettlers to live. This works on any distribution, including immutable ones like Fedora Silverblue/Bazzite.
3. Run JSettlers/bin/JSettlers.
4. On the first start, the game will ask you for the folder where you've installed / unzipped (see step 1) the original Settlers III. Please select the respective folder and continue.
5. Have fun and enjoy the game!

1. Install "The Settlers III" or a demo version (Settlers III Amazons Demo) of it. Don't worry, if it is not running on your OS, we only need the graphics and sound files. In order to get them, you can also unzip the Amazons Demo exe file (yes: unzip the .exe) and copy the folders Gfx, Snd and Map (optional) into an empty folder on your computer.
2. Download the newest stable release and unpack JSettlers-<version>-macos.zip to wherever you want JSettlers to live.
3. Open JSettlers.app. If macOS warns that the developer cannot be verified, right-click the app and choose Open.
4. On the first start, the game will ask you for the folder where you've installed / unzipped (see step 1) the original Settlers III. Please select the respective folder and continue.
5. Have fun and enjoy the game!

1. Install "The Settlers III" or a demo version (Settlers III Amazons Demo) of it. Don't worry, if it is not running on your OS, we only need the graphics and sound files. In order to get them, you can also unzip the Amazons Demo exe file (yes: unzip the .exe) and copy the folders Gfx, Snd and Map (optional) into an empty folder on your computer.
2. Download the newest stable release and unpack JSettlers.zip to wherever you want JSettlers' installation to be.
3. Run the "JSettlers.jar" file.
4. On the first start, the game will ask you for the folder where you've installed / unzipped (see step 1) the original Settlers III. Please select the respective folder and continue.
5. Have fun and enjoy the game!
6. Please have a look at the manual. The current state of the game lacks some controls known from the original, but also contains new ways to do things, which you shouldn't miss.

1. Install jsettlers-git from the AUR.
2. Optionally: Install settlers3-demo-data if you don't own an original The Settlers III and select the following folder when the game asks you: /usr/share/jsettlers/s3
3. You can start the game from the system-menu or with the commands "jsettlers" and "jsettlers-mapcreator".
4. See instructions above

As described before, the game's UI is still lacking a lot of features. That's why we have to offer some configurations via an options file. You can find a default options.prp file aside the JSettlers.jar file after you unpacked the archive.

When opening the file, you will see several options that can be enabled by uncommenting them (remove the # at the beginning of the respective line). This is also described in the file.

Possible configurations include:

• all-ai: Let all players be played by the AI. You will be able to watch all AI players and to "assist" them during the game.
• fixed-ai-type=YYYYY: Option to specify an AI type that shall be used for all AI players. The default behavior is to use a the weakest AI type for the first player and increase the difficulty for every player. Possible values: ROMAN_VERY_EASY, ROMAN_EASY, ROMAN_HARD, ROMAN_VERY_HARD
• disable-ai: If this flag is enabled, no AI players will be present in single player games.
• ai-attack-grace-seconds=N: Number of seconds at the start of a match during which computer players do not launch offensive attacks (they still defend). Default is 90. This prevents an unfair rush in the opening seconds on maps/scenarios where a computer player starts with more troops, while still letting the AI attack normally soon after. Set it to 0 if you want computer players to be able to attack from the very beginning (e.g. for a scenario that is meant to open with an assault), or higher for a longer peace at the start.
• locale: If you want to test a different localization than your systems default, it can be specify with this option. The value should look like: en_en.

Command line flags All the options above can also be specified as command line options. For this, you need to prepend every one of them with a double dash. Therefore the option fixed-ai-type=YYYYY should be specified as --fixed-ai-type=YYYYY.

1. Enable installation of Apps from "Unknown Sources".
2. Copy the folders "GFX", "SND" and "MAP" (optional) of your original "The Settlers 3" installation into a folder called "JSettlers" on your device. The "JSettlers" folder must be located in the root directory of your internal storage (alongside folders like "Download" or "DCIM") or your external storage (e.g. memory card).
3. Download the newest stable JSettlers-Android_v*.apk onto your Android device.
4. Install JSettlers by running the downloaded file.

This fork focuses on making the computer players smarter and more fun to play against. If you played the original game, you may remember that the enemies often just sat still, rarely attacked even with a big army, and never crossed water. That has been improved:

• They actually attack. An enemy with a strong enough army will now go on the offensive instead of sitting in its base forever. It also stops waiting when it clearly has the upper hand.
• They pick smarter targets. Enemies go after weak spots first – especially undefended (empty) towers, which are easy to capture – instead of always charging the nearest building. They also vary their target from game to game, so they are harder to predict.
• They judge a fight before committing. Before attacking, an enemy compares its army's real strength against yours (taking troop upgrades into account), so it no longer throws a large army at a smaller but much stronger one.
• They learn from how the war is going. An enemy adjusts how hard it presses over the course of a game, like a human would: if its attacks keep failing and bleeding troops without capturing anything, it becomes more careful and builds up (and upgrades) a bigger army before trying again instead of feeding soldiers into the same losing fight; when it is clearly winning and taking your buildings, it presses the advantage and attacks more readily. This adjustment is kept gentle and bounded, so a harder difficulty always stays stronger than an easier one.
• They defend properly. When you attack an enemy in several places at once, it now sends defenders to each break-in point instead of piling its whole army onto a single spot. It only commits as many troops as the threat needs, so a small raid will not pull its entire army away from the front.
• They can fight across water. On maps with seas or islands, an enemy will build a dockyard, produce ferries, load soldiers, sail them across the water and land them to attack – something the AI could not do before. If your land border is heavily defended, it may even sail around it and land troops behind your defenses.
• They harass and probe, not just charge. When an enemy has plenty of spare soldiers it will occasionally peel off a small raiding party and strike a lightly defended or empty building somewhere along your border, instead of only ever committing its whole army to one big frontal attack. These raids are kept small so they never weaken the enemy's main army or defence, they happen only now and then (aggressive personalities raid more often), and they respect the opening grace period. This makes an enemy feel more like a human that pressures several points and keeps you guessing.
• Every enemy has a personality. At the start of each game every computer player is randomly given a play style – for example a cautious turtle, a balanced player, an aggressive attacker, or a raider that loves shipping troops overseas. This makes each game feel a little different.
• No unfair opening rush. Computer players wait a short time (about 90 seconds by default) before launching their first attack (they still defend immediately), so an enemy that starts a scenario with more troops will not storm your base in the opening seconds. This delay is configurable – see ai-attack-grace-seconds under Configuration Flags – and each personality waits a bit more or less (an aggressor strikes sooner, a turtle later).
• Peacetime. When creating a single-player game you can pick a Peacetime of 5–30 minutes (or without, the default). While it runs, nobody – neither you nor the computer – can do any combat harm: units take no combat damage and towers cannot be attacked or captured, so everyone can build up in peace. Economy, scouting and troop movement are unaffected, and the moment the peacetime is over war works exactly as usual. Computer players know about it: they will not launch attacks before the peacetime ends (the AI attack-grace above still applies on top, so the effective wait is whichever of the two is longer).

There are four difficulty levels, from very easy to very hard. The difficulty mainly controls how fast and strong the enemy's economy is – a very hard enemy builds up a much stronger economy and army than an easy one. The personality above is added on top of the difficulty, so a very hard enemy is always the strongest, it just fights in its own style.

Difficulty also changes how cleverly the enemy fights, not only how fast it grows: the harder levels use the advanced tactics (such as the probing harassment raids described above), while the easier levels deliberately leave them out and play a plainer, more forgiving game. Harder enemies always keep every tactic an easier one has, so a higher difficulty is never weaker. As a first step towards making easier enemies feel less all-knowing, the easy levels now also send the occasional scout out towards you to "explore" instead of silently knowing where everything is.

By default, when a single-player game has several computer players, the first one is the weakest and each following one is a bit harder. You can change this with the fixed-ai-type option described under Configuration Flags above (for example --fixed-ai-type=ROMAN_VERY_HARD to make every computer player very hard).

• Recall fighting soldiers. A plain right-click is a fighting move order: soldiers walk there but engage enemies they meet on the way — and soldiers already chasing an enemy will keep chasing instead of obeying. Hold Ctrl while right-clicking for a forced move order: the soldiers break off combat immediately and go exactly where you pointed.
• Patrol. Hold Alt while right-clicking to make the selected soldiers patrol between their current position and the clicked point.
• Soldiers heading to a tower ignore orders. A soldier that is on its way to occupy a tower or castle finishes that job first and does not react to move orders until it has arrived. If you need it elsewhere, release it through the tower's selection panel.
• Savegames are stored in the save folder inside the game's resource directory (when running from source that is jsettlers.main.swing/save). Load them via Load Game in the main menu.
• Demo data limitations. JSettlers needs the graphics of an original Settlers 3 installation. With the old 1999 demo version's files the game runs, but many images are missing or shifted: ships and ferries are invisible (you only see the passengers), buildings of the non-Roman peoples do not show up, and the tower panel can show the wrong person (e.g. a healer instead of a soldier). Use the data files of a full Settlers 3 installation (for example the GOG edition) for correct graphics.

The build instructions and the developer's guide can be found in our wiki.

Building JSettlers requires a JDK 17 or newer (JDK 21 is recommended), because the build uses Gradle 8 and the Android Gradle Plugin 8. The built game still runs with Java 11 or newer.

You need a JDK (17 is used to build) and, as above, the GFX/SND folders of an original Settlers 3 installation (the GOG edition gives correct graphics; the demo works with the limitations noted above). From the repository root:

• Build and launch in one step:

  ./gradlew run
  

  (Windows: gradlew.bat run.) This compiles everything and starts the desktop client (jsettlers.main.swing.SwingManagedJSettlers). On the first launch a dialog asks you to select your Settlers 3 installation folder (the one containing GFX/SND); the choice is remembered for later runs. Savegames land in jsettlers.main.swing/save.

• Build a runnable jar instead:

  ./gradlew :jsettlers.main.swing:shadowJar
  

  produces the self-contained jsettlers.main.swing/build/libs/JSettlers.jar, which you can start with java -jar JSettlers.jar (same first-launch folder prompt).

To skip the folder dialog (e.g. for scripted runs), pass a config file that records the Settlers folder and options: ./gradlew run --args="configFile=/path/to/options.prp" — a default options.prp is shipped alongside the packaged jar and documents the available settings.

JSettlers is meant to be used with the original textures from Settlers 3. However we are working on replacing these with new textures that have a more permissive license. There is a list of textures that we didn't create ourselves but instead took from image sites on the internet

Besides the possibility to report bugs on Github you can also join our JSettlers Discord. Here you can discuss on development questions and find other players to meet with.