Instructions for building WorldPainter from source:

Prerequisites

WorldPainter is coded in Java (​https://www.oracle.com/java/index.html) and uses Maven (​http://maven.apache.org/) as the build system, so you must have a JDK installed (at least version 8), and Maven (at least version 3). These instructions assume that both are correctly installed and added to the PATH so that you can execute java and mvn commands from the command line, but if you are going to be using an IDE exclusively that is not necessary. The WorldPainter sources do not include any IDE metadata and are not dependent on any particular IDE for being built.

The source code is contained in a Git repository hosted on GitHub, so for checking out the source code you will need to have Git installed, although it is also possible to download the source code from GitHub as a zip file so this is not essential.

Knowledge and experience

WorldPainter is a large and complex program. You'll need a good understanding of Java (up to version 8) to be able to understand the code and work on it. If you want to work on the GUI you'll need at least a good working knowledge of Swing as well. Since the build system is Maven, you'll need some experience with that as well, including how to install artifacts in your local Maven repository, which you will need to do below.

Check out the source code

The WorldPainter source code is hosted on GitHub: ​https://github.com/Captain-Chaos/WorldPainter

Check it out from there, or fork it and then check out your own fork. The command for checking out the code anonymously from the command line is:

git clone https://github.com/Captain-Chaos/WorldPainter.git

Install missing dependencies

WorldPainter uses some dependencies which are not present in Maven Central, either because they are commercial products, or they are too old, or the creators aren't aware of Maven. Some of these dependencies (JPen; the NetBeans Dark Look and Feel) are hosted in a private Maven repo on www.worldpainter.net (see the pom.xml for the WorldPainter module), but one you will have to download and install manually:

TODO: JPen has native libraries, which are currently missing (meaning the tablet support won't actually work. This has yet to be incorporated in the build somehow.

JIDE Docking Framework

For the docks, WorldPainter uses the JIDE Docking Framework (​http://www.jidesoft.com/products/dock.htm), which is a commercial product. For development, you can download an evaluation version of the product ​here, with user ID and password documented ​here. The evaluation version will expire after two months, but you can keep downloading it again whenever it expires for two more months of development time.

Once you have your copy, either the evaluation version or the release version, install the jide-common.jar, jide-dock.jar and jide-plaf-jdk7.jar files in your local Maven repository by executing the following commands from inside the directory where you extracted them:

mvn install:install-file -DgroupId=com.jidesoft -DartifactId=jide-plaf-jdk7 -Dversion=3.7.3 -Dpackaging=jar -Dfile=jide-plaf-jdk7-3.7.3.jar
mvn install:install-file -DgroupId=com.jidesoft -DartifactId=jide-dock -Dversion=3.7.3 -Dpackaging=jar -Dfile=jide-dock-3.7.3.jar
mvn install:install-file -DgroupId=com.jidesoft -DartifactId=jide-common -Dversion=3.7.3 -Dpackaging=jar -Dfile=jide-common-3.7.3.jar

Note: if you downloaded a different version than 3.7.3 you must use the correct version numbers in these commands, and update the version numbers in the pom.xml of the WPGUI module!

If you ever want to distribute your own version of WorldPainter (although I respectfully request that you don't), you'll have to download the release version of the framework and get your own licence. JIDE Software give out open source licences, which are free. When using the release version of the framework, you have to create a file called src/main/resources/jide_licence.properties in the WPGUI module to fill in your actual licence details. It should have the following contents, filling in the actual values in place of the texts after the equals signs:

companyName=<company name>
projectName=<project name>
licenceKey=<licence key>

Note: make sure not to commit that file to any publicly visible source code repository, as your licence is associated with you and may not be used by other people!

Alternatively you could remove the JIDE Docking Framework from the code and replace it with some alternative docking framework. It's a lot of work, but doable.

Build WorldPainter

Once all dependencies are installed you can build WorldPainter from the command line or using your favourite IDE:

Build WPValueObjects

The other modules depend on WPValueObjects, so build that first by executing the following command from inside the WPValueObjects directory, or use your favourite IDE to build the WPValueObjects module or invoke the install Maven goal on it:

mvn install

You only need to do this once, as long as you don't change any code in the WPValueObjects module.

Build WorldPainter

Now you can build WorldPainter itself. Execute the following command from inside the WorldPainter directory, or use your favourite IDE to build the WorldPainter module or invoke the install Maven goal on it. There are some rudimentary unit tests, but they take a while to run and don't contribute much, so I recommend skipping them:

mvn install -DskipTests=true

Repeat this whenever you change code in any of the modules below the WorldPainter directory. Or of course use your favourite IDE, preferably one with good Maven support, to build the project.

Run WorldPainter

Once it is built, you can run WorldPainter from the command line with the following command, executed from inside the WPGUI directory:

mvn exec:exec

You can also define a run configuration in your favourite IDE. The main class is org.pepsoft.worldpainter.Main.

Develop WorldPainter

For a few pointers, pitfalls and gotchas about developing WorldPainter, see this page.