Due to the fact that PlayN supports four different target platforms, a PlayN game project has a lot of moving parts. Fortunately, the Maven build system used by PlayN allows those parts to be cleanly separated and to stay out of your way until and unless you need them.
A PlayN game project consists of a top-level meta module and a number of different sub-modules. Here’s an outline of the structure of the Hello example project:
hello/pom.xml - main project Maven build file
/core - cross-platform game code
/assets - cross-platform game assets
/android - Android backend code and configuration
/html - HTML backend code and configuration
/java - desktop Java backend code and configuration
/robovm - iOS (RoboVM) backend code and configuration
The main cross-platform game code is in the core module. The cross-platform game assets are in
the assets module. Due to requirements of the Android and RoboVM builds, it is most convenient to
have the assets in a separate module rather than bundled with the core module. The remaining
modules deal with the various supported target platforms.
The assets module simply contains images, sounds and other non-code game assets. These are placed
into the assets/src/main/resources/assets/ directory and organized however you like. The Hello
project contains:
assets/pom.xml
assets/src/main/resources/assets/images/bg.png
assets/src/main/resources/assets/images/pea.png
The core module contains the game code. This is placed into the core/src/main/java/ directory
and organized like a normal Java project:
core/pom.xml
core/src/main/java/playn/sample/hello/core/HelloGame.java
Each module also contains a pom.xml Maven build file which contains build instructions and
configuration.
The PlayN sample games follow the Maven standard project layout, which places resources into
src/main/resources and code into src/main/java, but a game author is free to change that layout
if desired. This Stack Overflow question describes the process of customizing the directories in
which Maven looks for code and resources.
Note that even if you plan to build with an IDE, changing directories via the Maven configuration is a good idea because the IDE will usually read the Maven build configuration files to determine where to find code and resources in a Maven project. This also ensures that building from the command line continues to work properly.
The Java module contains just a single source file which bootstraps the game when running in the JVM:
java/pom.xml
java/src/main/java/playn/sample/hello/java/HelloGameJava.java
The Android module contains a number of Android-specific configuration files, a source file which
defines an Android Activity and which bootstraps the game on Android, and any Android-specific
media resources like the app icons.
android/AndroidManifest.xml
android/pom.xml
android/proguard.cfg
android/project.properties
android/res/drawable-hdpi/icon.png
android/res/drawable-ldpi/icon.png
android/res/drawable-mdpi/icon.png
android/res/values/strings.xml
android/src/main/java/playn/sample/hello/android/HelloGameActivity.java
The AndroidManifest.xml file is the main configuration for an Android app. You’ll want to
familiarize yourself with the Android manifest docs if you’ll be deploying to Android.
The RoboVM module contains a number of iOS-specific configuration files, a source file which
defines a UIApplication and bootstraps the game on iOS, and any iOS-specific media resources like
app icons and splash screens.
robovm/Info.plist.xml
robovm/pom.xml
robovm/resources/Default*.png
robovm/resources/Icon*.png
robovm/resources/iTunesArtwork
robovm/robovm.properties
robovm/robovm.xml
robovm/src/main/java/playn/sample/hello/robovm/HelloGameRoboVM.java
The Info.plist.xml file is the main configuration file for an iOS app. You’ll want to
familiarize yourself with iOS application docs if you’ll be deploying to iOS.
The HTML module contains the GWT configuration file, a source file which defines a GWT module that
bootstraps your game, an HTML page that hosts your game, and metadata for a Java webapp, which you
can use if you deploy your game via a war file (to Google App Engine, for example).
html/pom.xml
html/src/main/java/playn/sample/hello/HelloGame.gwt.xml
html/src/main/java/playn/sample/hello/html/HelloGameHtml.java
html/src/main/webapp/HelloGame.html
html/src/main/webapp/WEB-INF/web.xml
The HelloGame.gwt.xml file is the main GWT configuration file. The GWT project organization
documentation provides details on these configuration files.
Maven contains facilities for generating new projects from a so-called archetype. PlayN uses this mechanism to make it easy to generate a new PlayN game project with all the different parts properly configured according to a small amount of information provided by you up front.
To generate a new PlayN game project using Maven, run the following command:
mvn archetype:generate -DarchetypeGroupId=io.playn -DarchetypeArtifactId=playn-archetype -DarchetypeVersion=2.0
This will ask you to provide various metadata for your project. These are explained in turn:
Define value for property 'groupId': :
This should be a reverse domain that identifies your project. Examples include:
com.googlecode.myproject, com.github.myid.myproject, com.mydomain.myproject.
Define value for property 'artifactId': :
This should be an all lowercase identifier that identifies your game. Examples include:
monkeybattle, upsetavians, gameamazing.
Define value for property 'version': 1.0-SNAPSHOT: :
This defines the version used when naming your jar files. You can press enter to use the default:
1.0-SNAPSHOT, or if you don’t plan on using Maven to deploy snapshot versions of your game to a
Maven repository, you can specify whatever version you prefer (e.g. 1.0, 0.1, r55-alpha).
Define value for property 'package': com.mydomain.myproject: :
This defines the Java package in which your game files will be placed. The default will be the
value you provided for groupId, which is often also a good package name. However, you can use
whatever package you like. The PlayN project, for example, eschews the Java tradition of using
verbose reverse domain package names and simply uses playn.
Define value for property 'JavaGameClassName': :
This defines the name used for your game when naming various Java classes. As such it should follow
Java class naming conventions and start with an upper-case letter. Examples include:
MonkeyBattle, UpsetAvians, GameAmazing.
Once you have provided these properties, you will be asked to confirm that they are correct.
Confirm properties configuration:
groupId: ....
artifactId: ...
version: ...
package: ...
JavaGameClassName: ...
Y: :
If they are, enter y and press return. Your game skeleton will be generated in a directory with the
name that you provided for artifactId.
You should now be able to run your skeleton game:
cd <your-new-game-directory>
mvn test -Pjava
If you are doing this in preparation for a tutorial, head back there and get going. Otherwise good luck with your exciting new game!