Tutorial

PlayN UI Tutorial

How to create your first user interface using the PlayN and Triple Play libraries for Android and HTML.

Other Tools

Before you start writing your own project, make sure you have all the tools set up by running the sample projects. Follow the getting started guide to run them as Java, HTML, and Android. The Android SDK documentation is also helpful.

Create the Project

Once you've gotten that running, create your own project using the Maven archetype. Here is the command I used, along with all the settings:

mvn archetype:generate -DarchetypeGroupId=com.googlecode.playn -DarchetypeArtifactId=playn-archetype -DarchetypeVersion=1.8
groupId: com.github.donkirkby
artifactId: playnuitutorial
version: 1.0-SNAPSHOT
package: com.github.donkirkby.playnuitutorial
JavaGameClassName: TutorialApp

In Eclipse, import that as an existing Maven project. It will complain about the lifecycle configuration of the Android and Flash projects.

Plugin execution not covered by lifecycle configuration: com.jayway.maven.plugins.android.generation2:android-maven-plugin

According to the Eclipse wiki, this is the Maven integration of Eclipse getting confused. You can use a quick fix to tell Eclipse to ignore the Android and Ant run stuff. Just open the Android project's pom, click on the line with the error, and type Ctrl-1. Choose the option to permanently mark goal proguard in pom.xml as ignored in Eclipse build. That will add a section to your Android project's pom.xml that gives special instructions to Eclipse. Do the same quick fix in the Flash project, then tell Maven to update both projects from the right click menu. You should now have no errors in your project.

The point of this tutorial is to get started with the Triple Play library and its user interface tools, so let's add it to the Maven dependencies. Open the core project's pom.xml, and add a new dependency.

<dependency>
  <groupId>com.threerings</groupId>
  <artifactId>tripleplay</artifactId>
  <version>${playn.version}</version>
</dependency>

If you want to deploy your project on the HTML or Flash platforms, follow the extra steps described in the Triple Play README file.

Add a Screen

In the core project, add a new class called ButtonDemoScreen. You can copy the source code from the tutorial GitHub project, but the most important piece of code is this:

final Button button = new Button("Click Me");
root.add(button.onClick(new UnitSlot() { 
    public void onEmit () {
        button.text.update("Clicked");
    }
}));

It creates a button and tells it to change its name when you click it. The rest of the class is creating a framework to hold that button.

The last thing to do is to tell your TutorialApp class to launch the screen. You can copy the source code from the tutorial GitHub project, but the main thing is to add two member variables to hold the screen and control timing:

private final Clock.Source clock = new Clock.Source(UPDATE_RATE);
private final ScreenStack screens = new ScreenStack();

Even if your app only has one screen class, the ScreenStack takes care of calling the screen's life cycle methods at the right time. The rest of the code just updates those two objects.

@Override
public void init() {
    screens.push(new ButtonDemoScreen());
}

@Override
public void update(int delta) {
    clock.update(delta);
    screens.update(delta);
}

@Override
public void paint(float alpha) {
    clock.paint(alpha);
    screens.paint(clock);
}

Now run the Java project, and you should see a screen with your button in the middle. Click it, and its name should change to "Clicked".

Congratulations, you just wrote your first user interface code with PlayN and Triple Play. Now you can look at the Triple Play demo for examples of how to use all the classes.