Java Settlers

A desktop client-server version of Settlers of Catan

Introduction

JSettlers is a Java version of the board game Settlers of Catan written in Java. This client-server system supports multiple simultaneous games between people and computer-controlled opponents. Initially created as an AI research project.

The client can host a server, connect to dedicated JSettlers servers over the net, or play practice games offline against bots.

The server can optionally use a database to store player account information and game stats (details below). A client java app to create user accounts is also provided.

If you're upgrading from an earlier version of JSettlers: Check doc/Versions.md for new features, bug fixes, and config changes, then see Upgrading from an earlier version section of this Readme.

JSettlers is an open-source project licensed under the GPL. The project is hosted at https://github.com/jdmonin/JSettlers2/ and https://nand.net/jsettlers/devel/ . Questions, bugs, patches, and pull requests can be posted at the github page.

- The JSettlers Development Team

Contents

• Screenshots
• Documentation
• Requirements
• Client Command Line
• Server Setup and Testing
• Shutting down the server
• Installing a JSettlers Server
• Upgrading from an earlier version
• Security and Admin Users
• Development and Building JSettlers

Screenshots

New Game options:

Classic 4-player board:

Classic 6-player board:

Sea board: Cloth Villages scenario:

Documentation

User documentation for game play is available as .html pages located in the src/site/users directory. These can be put on a web server for its users to access with a browser.

Currently, this Readme and the doc directory are the only technical documentation for running the client or server, setup and other issues. Over time, more docs will be written. If you are interested in helping write documentation please contact the development team from our github page. For developer docs, see Readme.developer.md.

If you downloaded a JSettlers JAR file without attached documentation, the official location of this Readme and the docs is online at https://github.com/jdmonin/JSettlers2/blob/main/Readme.md .

Requirements

To play JSettlers you will need either Java Runtime (JRE) version 8 from https://java.com/download/ , or the Java Development Kit (JDK) version 8 or higher from https://jdk.java.net/ .

Then download JSettlers-full.jar from either https://github.com/jdmonin/JSettlers2/releases or https://nand.net/jsettlers/ and run it.

To host a JSettlers server, use any server OS and hosting provider you like. To also provide a download for the full Jar, you will need any web server such as nginx or Apache httpd.

The JSettlers-full.jar file can also run locally as a server, without needing a web server. If you're running a LAN game for friends, that Jar is all you need.

To build JSettlers from source, you will need Java JDK 8 or higher, and either gradle 6.9.x or 7.x, or an IDE such as Eclipse which understands gradle's format. See doc/Readme.developer.md for details.

Client Command Line

Running the client with no parameters is the same as double-clicking it:
java -jar JSettlers-full.jar will bring up a window with options to connect to a server, practice against bots (no network needed), or start a server for others to connect to.

To connect directly to a server, give its host and port number:
java -jar JSettlers-full.jar myserver.example.com 8880

If your screen is High-DPI, JSettlers should automatically detect that instead of running in a very small window. If detection fails for some reason, ask for High-DPI support this way:
java -Djsettlers.uiScale=2 -jar JSettlers-full.jar

Also available: --help, --version, and various debugging flags listed in doc/Readme.developer.md.

Server Setup and Testing

From the command line, make sure you are in the JSettlers distribution directory which contains both JSettlers.jar, JsettlersServer.jar and the lib directory. (If you have downloaded jsettlers-2.x.xx-full.tar.gz, look in the /target directory for these files.)

If you have downloaded jsettlers-2.x.xx-full.jar or jsettlers-2.x.xx-server.jar instead of the full tar.gz, use that filename on the command lines shown below.

Server Startup

Start the server with the following command (server requires Java JDK 8 or higher, or JRE version 8):

java -jar JSettlersServer.jar

This will start the server on the default port of 8880 with 7 robots. It will try to connect to an optional mysql database named socdata; startup will continue even if there is no DB or the DB connect doesn't work.

You can change those values and specify game option defaults; see details below.

To automatically start the JSettlers server on a linux server, see src/main/bin/jsettlers.service.

If MySQL or another database is not installed and running (See "Database Setup" in doc/Database.md), you will see a warning with the appropriate explanation:

Warning: No user database available: ....
Users will not be authenticated.

The database is not required: Without it, the server will function normally except that user accounts cannot be maintained.

If you do use the database, you can give users a nickname and password to use when they log in and play. People without accounts can still connect, by leaving the password field blank, as long as they aren't using a nickname which has a password in the database. Optionally game results and stats can also be saved in the database, see next section; those aren't saved by default.

Parameters and game option defaults:

JSettlers options, parameters, and game option defaults can be specified on the command line, or in a jsserver.properties file in the current directory when you start the server.

Command line example:

java -jar JSettlersServer.jar -Djsettlers.startrobots=9 8880 50

In this example the parameters are: Start 9 bots; TCP port number 8880; max clients 50.

The started robots count against your max simultaneous connections (50 in this example). If the robots leave less than 6 player connections available, or if they take more than half the max connections, a warning message is printed at startup. To start a server with no robots (human players only), use

-Djsettlers.startrobots=0

Any command-line switches and options go before the port number if specified on the command line. If the command includes -jar, switches and options go after the jar filename.

To change a Game Option from its default, for example to activate the house rule "Robber can't return to the desert" and set default Victory Points to Win to 13, use -o switches with the game options' names and values, or equivalently "-Djsettlers.gameopt." + the names and values:

-o RD=t -o VP=t13
-Djsettlers.gameopt.RD=t -Djsettlers.gameopt.VP=t13

If a default VP is set, that will also be the minimum winning VP for any scenario. Some scenarios like Cloth Trade may have a higher VP amount, but none will be lower. To use the default VP in all scenarios, even those specifying a higher VP amount, also set game option _VP_ALL=t when starting the server.

You could also set a default game scenario this way; for example if your server was running a tournament of Fog Islands games:

-o SC=SC_FOG

If the scenario's game options conflict with any other game options given, a warning will be printed during startup. In general, servers shouldn't set a default scenario; users can choose a scenario on their own if they want.

To have all completed games' results saved in the database, use this option:

-Djsettlers.db.save.games=Y

To see a list of all jsettlers options (use them with -D), run:

java -jar JSettlersServer.jar --help

This will print all server options, and all Game Option default values. Note the format of those default values: Some options need both a true/false flag and a numeric value. To change the default winning Victory Points to 12 for example:

-o VP=t12

Savegame optional feature:

The server can save/load most games to files kept on the server, using admin commands. For details see doc/Readme.developer.md: Search for "Saving and loading games"

jsserver.properties:

Instead of a long command line, any option can be added to jsserver.properties which is read at startup if it exists in the current directory. Any option given on the command line overrides the same option in the properties file. Comment lines start with # . See src/main/bin/jsserver.properties.sample for full descriptions of all available properties. (Also available online at https://raw.githubusercontent.com/jdmonin/JSettlers2/main/src/main/bin/jsserver.properties.sample).

This example command line

java -jar JSettlersServer.jar -Djsettlers.startrobots=9 -o RD=t 8880 50 socuser socpass

is the same as jsserver.properties with these contents:

jsettlers.startrobots=9
jsettlers.gameopt.RD=t
jsettlers.port=8880
jsettlers.connections=50
# db user and pass are optional
jsettlers.db.user=socuser
jsettlers.db.pass=socpass

To determine if the server is reading the properties file, look for this text near the start of the console output:

Reading startup properties from jsserver.properties

To check the syntax and values of a jsserver.properties file,