Getting_started

Getting started

This text intends to be the main reference for everyone feeling interested in taking part in the development of OpenPatrician. In this quick review we will guide you through the most basic features of the project development.

General concepts

OpenPatrician is based on the game The Patrician and its successor Patrician II plus its Add-on. The Add-on was sold on the international market as Patrician III. To avoid confusion we will use international terminology and call the Add-on Patrician III. Patrician IV, the game that Kalypso Media started selling in 2010, is currently not the focus of this development.

The development of the game is planned to follow these three stages of continuously improved games. We are currently working on the first stage, which will consists in the implementation of a basic game engine that will be used as a base for the next stages. This engine will contain the features included in The Patrician.

If you haven't played the game, you should read the following reviews:

• The Patrician. This game can be downloaded for free.
• Patrician II
• Patrician III

Valuable hints on how the internals on Patrician III work can be found in this German tip collection. For a more general and interactive description of the game, there is also a Patrician III wiki in English.

An important address may be the German Patrician Forum.

Project structure

OpenPatrician is stored in the SVN repository's trunk. Branches are used for experimental purposes and tags are created with each new release. In the trunk we can find the following four projects:

• OpenPatrician: contains the source code, as well as some documentation.
• OpenPatricianWeb: a web project containing the game's website files.
• OpenPatricianGameArt: contains the art production resources of the game.
• OpenPatrician-assembly: used for assembling OpenPatrician's modules in one executable.

Game art can be found on OpenGameArt and sounds and music on OpenGameArt.

The source code of the project is structured by using Maven. Therefore, there is a master project (OpenPatrician) which contains several Maven children modules. These modules have dependencies between them, which are resolved by using Spring framework's dependency injection. The current game modules are the following:

Events modules:

• GameEvent: provides data models for events that aren't specific to OpenPatrician and that can be passed around using Guavas EventBus.
• OpenPatricianGameEvent: contains game-specific event classes.

JavaFX modules:

• OpenPatricianJavaFX provides UI components used by OpenPatricianDisplay.
• OpenPatricianDisplay: manages the UI of the game by using the control elements provided by OpenPatricianJavaFX. This module also includes the main class OpenPatrician.
• MarvinFXEssentials: module with largely imported code. It is a utility that allows testing the JavaFX user interface.

Server/client architecture modules:

• OpenPatricianClientServerInterface: interfaces used by the client and the server. Provides the basis to divide the whole application into a server and a client part, which will be used for multiplayer.
• OpenPatricianServer: the server part of the game.

Game data and resources modules:

• OpenPatricianData: contains data (text, icons...) that is shared by several modules.
• OpenPatricianModel: one of the most central modules which basically holds all the logical data structures (game, player, city, ...) and some utility logic to instantiate these models.
• OpenPatricianEngine: drives the models and the game and it is where the AI is implemented.
• OpenPatricianMetadata: Containing meta data required for building and running an executable jar.
• OpenPatricianImage and OpenPatricianSound: takes care of loading image and sound resources.
• OpenPatricianUtilities: provides several tools such as the management of game properties, text, locales, etc...

Development enviroments

It is recommended to use the command line or an IDE to edit the game code. There are many options, but we suggest you to use one of the following because we tested the project on them.

Command Line

Producing a runnable jar is fairly easy. If maven 3 and svn are installed and in the executable search path, all you have to do is to issue the following on the command line.

Checkout:

We will just checkout the needed projects (anonyoumous and with username):

    svn co svn+ssh://svn.code.sf.net/p/openpatrician/code/trunk/OpenPatrician OpenPatrician
     svn co --username=<username> https://svn.code.sf.net/p/openpatrician/code/trunk/OpenPatrician OpenPatrician

or update an existing project:

svn up OpenPatrician

Build all the components (inclusive running all tests):

cd OpenPatrician
mvn install

Build an executable jar file:

mvn install -P build-installer

Run the game:

java -jar target/OpenPatrician-jfx-0.0.1-SNAPSHOT.jar

The version number (in the above example 0.0.1-SNAPSHOT) may be adjusted, based on the version built (see output of the mvn package command).

IntelliJ IDEA

IntelliJ IDEA community edition is the IDE that we are currently using. To import the project, just check the code project (OpenPatrician folder) from the SVN repository by using File->New->Project from Version Control. To avoid problems with lombok annotations, you need to install the Lombok Plugin, which can be found in Settings->Plugins.

Eclipse

Check out the code project (OpenPatrician folder) into your Eclipse workspace by using the import from SVN option or by importing it as a Maven project after checking it out from the command line. You will need to install the M2Eclipse plug-in if Maven support isn't already included in your IDE.

NetBeans

To check out the code project (OpenPatrician folder) under NetBeans go to Team->Subversion->. Since it has been used under other IDEs you may not find the needed properties to set the projects up.

To get the projects from the checked out code you need to have the Maven plugin installed. Then you can File->Open Project and select the folder where your code lies. This will create a root folder with the parent project. All children are in the 'folder' modules. Double clicking on a module will extract it as a project that can be used.

Compiling

The compilation usualy is done in the IDE. However to build the whole project use the Maven command:
mvn clean install

Classpath

The dependencies are gennerally defined and managed by Maven. However there is one dependency that you need to add to the classpath of your JDK. It is the tools.jar which is located in the JDK's lib directory. This jar file holds utilities that are needed for documenting purposes, so it does not go into any productive release but is required to build the classes locally.

Joining the team

There are several tasks that you may want to help us with: programming, game art, sounds and music, documentation, etc... For coding it is recommended (not actually needed) to have some experience with the following tools:

• Java language
• SVN (Subversion)
• Spring framework
• JavaFX
• Maven

If you have never used Maven I suggest Sonatypes Getting started guide and the more complete version.

Commiting

Basically we commit everything, here are some guidelines:

• documentation goes into the doc folder
• tests, demo and other main application that do not belong to the game go into the test subfolder of the respective module
• IDE specific configuration is commited as well, the first time. This allows others to leverage these settings. However as each local environment is different from another, we do not commit subsequent changes.

Contact me so you can be added as a developer to the project and gain write access to the repository.

Where to start

On this page various issues aree listed that need to be addressed in some way. The list is generated at the end of each release, therefore it might not be that up to date, but it is a good starting point. It allows you to take a look at some of the smaller issues and in doing so browsing through the code.
Another approach is to take a look at the issue tracker for issues labeled starting task. Those are issues that were created and thinking that they are not that complex and do not need that much knowledge of the inner working or other parts of the code. Of course this initial asumptioon might be wrong.