Slick is a 2D library for Java written on top of LWJGL (itself written on top of OpenGL).  Eclipse is the IDE I use for developing in Java.  I love Slick for being able to get up and running quickly, but I’m fairly new to Eclipse, so setting things up has proven to be a bit of a repeated pain for me.  This tutorial will describe how I set up Eclipse for my Java projects, to serve mostly as a reference for myself when I next start a new project.

The source for this tutorial is available at Bitbucket (https://bitbucket.org/apocriva/tutorials).  Full tutorial after the break!

Directory Structure and Source Control

For source control, I use a Mercurial (Hg) repository, typically hosted on Bitbucket, using tortoisehg.  I try to ensure that it’s possible to sync to the latest, load the project in Eclipse, and build/run right out of the box.  I still don’t know if I have things 100% correct, but I’ll make a note below of the Eclipse files which I currently store in Hg, and how the .hgignore file filter is set.  I won’t, however, belabour Hg, since this is a Slick/Eclipse tutorial, and not a Mercurial tutorial.

With that in mind, I’ll be referring to the Hg repository root as {Root}.  If that maps to something like “C:\dev\tutorials” for you, then you should read “{Root}\Eclipse” as “C:\dev\tutorials\Eclipse”.

Here’s the directory structure we’ll be setting up:

  • {Root}.  Contains the .hgignore file and the .hg folder.
    • Common.  Certainly not the most space-saving way of doing things, but a way I’m used to doing it from my nine-to-five game dev job, I keep a full copy of the version of each common library I’m using on a project within that project’s directory structure.  This means that what I have in my repository won’t suffer from breakages due to new library versions if I have to build the project later.  I’m almost positive this would also be a legal problem if I had the Common folder in the repositories publicly available, but I don’t.
    • Eclipse.  Eclipse-specific metadata stuff.  I have this in its own folder so that it’s clear that the .metadata folder is an Eclipse construct, and not part of source control, or directly part of the project.
    • Project Folders.  Each project created within Eclipse goes in its own folder, with quite a few source folders.  In the base project folder, you’ll find the very-important .classpath file.  You may have to hand-edit this later to properly have relative paths.  This folder also contains any Ant build files that are used for things like building data.  The paths within the base project are split into two categories: those which contain source files, or files otherwise needed by the build, and therefore must be in the Hg repository; and those which are generated as part of the build and therefore do not reside in the repository.
      • Source Folders.
        • lib.  Contains the jars and native dlls that will later be built into a distribution.  These don’t technically have to be here, since they exist under Common, but the build scripts were a lot more straightforward to set up assuming we just had to blindly copy this folder over.
        • src.  Contains Java source code.
        • srcData.  Contains source data, including all working files (things like PSDs, XCFs, etc) and generally most exported files (PNGs, WAVs) which will be copied over directly.  Some files in srcData get processed by the build pipeline, with the resulting generated files ending up elsewhere.
      • Build Folders.
        • bin.  Contains .class files built from src.
        • data.  Contains the built and copied data from srcData.  This is the data accessed by the game when running/debugging from within Eclipse.
        • dist.  Contains a full distribution of the project.  The projects I work on in development use getdown for distribution, so this folder contains a bunch of things related to building that distribution.  Most importantly, it contains a zip file with the getdown updater and the built data to post to FTP.
      • I lied, there’s a third category: Miscellaneous Folders.  Each project generally has a few folders which are unique to that project, or some temporary build folders.  I could clean this up a lot, and I may end up doing so.

Setting up the Eclipse Workspace

I apologize in advance if there’s anything missing here for getting set up from a fresh installation of Eclipse.  I haven’t been familiar enough with the IDE to know what settings are project-specific, and which are global.  Just drop me a line if anything doesn’t jive correctly, and I’ll get the tutorial fixed up!

When booting Eclipse, it will ask you which workspace you’d like to open.  The workspace for this tutorial is going to be “tutorials”, and as mentioned above, the Eclipse workspace files go in the Eclipse subfolder of {Root}, so we tell Eclipse something like: “{Root}\tutorials\Eclipse”.


The first thing we do from an empty workspace is create a project.  Select “Java Project” from the New Project wizard, and for the project name enter something classy (for me, “Tut00”).  We also change the location of the project to be a sibling of the Eclipse folder.

You can just hit Finish from here to create the project, and if Eclipse prompts you to go to the “Java perspective”, you want to let it!  Note that it is possible, from the next step of the wizard, to set up the project dependencies for things like LWJGL and Slick, but in the event that you’ve skipped that panel, it’s just as easy to explain how to do so from the Java perspective directly.  Less straightforward is re-creating the project just to access that step of the wizard.

Once the project is created, right-click on it and add a new folder.  In the new folder wizard, click Advanced, select Linked Folder, click Variables, and add a new variable called COMMON_LOC, which points to ${WORKSPACE_LOC}\..\Common.  Then use this as the location for the folder.

Now go to the project Properties window (by right-clicking on the project).  Go into the Java Build Path tab.  Select “Add JARs…” and find slick.jar in the Common folder we just added.  Once this is added, expand the tree view beside the jar, and set its source, javadoc, and native library locations.  Repeat for lwjgl.jar (and note that the Slick distribution at the time of this writing doesn’t have the proper 64-bit native libraries for lwjgl, so you’ll have to get those separately).  Things should end up looking something like this:

At this point, you’re able to build and run a simple Slick application!  Feel free to try adding TutGame.java to test it out.

Data Build Pipeline

It was important for me to get a functional data build pipeline in place, since that’s what I’m used to from the day job!  I use Ant for this.  The first thing to do is create an Ant project file, which is simply an XML file, in this case called “build.xml”.

I’m not going to cover anything about Ant here, but here’s a very simple build.xml.  This will simply copy all png files from scrData to data.  From the dropdown beside the run arrows, go to “External Tools Configurations”.

From within that configuration dialog, double-click Ant Build.  It should automatically reference build.xml.  You can rename the run configuration whatever you like, as long as it still points at build.xml.  Under the Refresh tab, I always have “Refresh resources upon completion.” -> “The entire workspace” checked, so that all the built files show up properly in the workspace view.  In the Common tab, you can check “External Tools” under “Display in favorites menu” to have the build available all the time easily from the run dropdown as shown in the figure above.

The build script will fail if you don’t have a srcData folder, but that’s okay!

Ant is easily extensible if you need to add custom tasks.  The easiest thing to do in my experience has been to add a new project to the workspace, have the build task source code there, and have that project export its .jar back into the main project when it builds via an Ant build step.  There’s probably a more concise way of doing this, though.

What to Source Control?

I’ll be honest, I’m not 100% sure about this section.  There are a lot of Eclipse files that definitely need to stay out of source control.

First and foremost, let’s set up the ignore filter.  Again, as noted above, I’m expecting you to be using tortoisehg.  Right-click anywhere in Explorer under {Root}, and in the TortoiseHg submenu, select “Edit Ignore Filter”.  Here’s an example of what my ignore filter looks like:

The only Eclipse-related files that show up here are the project ones (for Tut00).  In order for the launch settings to be saved in Hg, we have to manually add the files in Eclipse/.metadata/.plugins/org.eclipse.debug.core/.launches.  From what I can tell, Eclipse has some hardcoded paths in there, though, so I don’t know if it’s possible to have a workspace checked into Hg that will work right out of the box.  One thing that we can do is modify our projects’ .classpath files manually to change the absolute paths to relative paths.

Further Pipeline Setup

Beyond the basic data build, I typically have a “distribution” pipeline, which includes packaging data and code together, and posting the result in an accessible place.  That’s a topic for a future tutorial, however!

Advertisements