Skip to content

Project Setup

Jump to bottom
Tommy Ettinger edited this page Feb 21, 2016 · 1 revision

Setting up SquidLib and its dependencies

The Easy Way

So, there's a tool now for setting up dependencies and projects that use SquidLib automatically, called SquidSetup, and it's available in a beta release version and a snapshot non-release version. SquidSetup is a GUI tool that lets you choose various configuration details, like a game/project name, base package/main class for code, a path to save the project, options to change the platform targets, and more options to change the dependencies (but the defaults are all you need for a text-based game, and the demo will run just fine as long as SquidLib is checked). If you use either SquidLib for full-color text display or LibGDX for what's probably a fully-graphical game, you depend on the same setup steps that LibGDX needs on its own; see the LibGDX prerequisites and the setup details using their tool, which SquidSetup is based on and any instructions for the GDX Setup tool apply here. If you use NetBeans, you need to install a plugin to support Gradle, but both Eclipse and IntelliJ IDEA (and its derivatives like Android Studio) support Gradle out-of-the-box. For platform targets, Desktop should almost always be checked for testing across Windows, Linux, and Mac OS X. Android and iOS only need to be checked if you intend to target those platforms. Android projects need a substantial download of build tools using the Android SDK Manager before you can build them, so if you don't intend to target Android that box shouldn't be checked. iOS projects can only be built on a Mac with RoboVM installed (we use libGDX, which should qualify you for a free license), but that target hasn't been tested at all. HTML should not be checked on the beta 3 release; it should be fine on the snapshot release, and you should absolutely follow the instructions on the LibGDX wiki for how to get started, since it isn't as straightforward as desktop. For dependencies, SquidSetup automatically produces projects that depend on squidlib-util (if you don't use that project, there's no reason to use SquidSetup instead of the libGDX setup). The main other choice boils down to whether you want only libGDX for graphical, self-managed display or SquidLib for more automatic, primarily text-based display; both use libGDX internally but only one dependency checkbox or the other needs to be checked. Any other dependencies are not likely to be needed for text-based games, though a few may want Ashley (entity-component architecture) or GDX-AI (which overlaps somewhat with parts of squidlib-util). The advanced button at the bottom allows you to choose to generate Eclipse or IntelliJ projects that are separated from Gradle, which may be desirable in some cases, but for the snapshot it isn't recommended since Gradle is used to get the most recent version.

After you're all set up, click Generate, respond to any dialogs relating to Android tool versions (clicking "yes" seems to work...), wait for it to download dependencies and make a project, then open up the gradle project (the file build.gradle) in your IDE. There's a sample demo generated in the core project, and platform-specific launchers for desktop and any other platforms you selected. You can run the desktop project's launcher to see a basic "@ moving around a random dungeon" demo, that shows a few other nice things in SquidLib (good Unicode support can be seen in the gibberish strings at the bottom, you can click to move or use different keys, you aren't limited to basic colors, and the font should stretch smoothly (in at least the snapshot) if you resize the window). There is heavy documentation in the demo code. As for where to go next... more documentation is forthcoming.

The beta release downloads beta 3 currently, which should typically be no older than 3 months behind the current latest code. In that time there may have been fixes to things that are relevant to your interests, such as HTML targeting (works now, did not in beta 3 unless you tinkered with some difficult stuff) and an unpredictable crash with certain map generators that at least included SerpentDeepMapGenerator and crashed only for some RNG states (fixed). If either of those bugs, or any other bugs you encounter, seem like a problem you would like to avoid, you can use the snapshot version, which defaults to downloading a build of the most recent commit from https://jitpack.io. The latest build is likely to have more features and tries not to break existing beta or stable APIs very often. You can "Look Up" https://github.com/SquidPony/SquidLib on jitpack, click commits, and choose from a few recent commits if the latest one isn't working (in which case please submit an issue here on Github!); the instructions further down on the page change to match the commit you pick. After you create a project with the snapshot version of SquidSetup, you can update any dependencies by running gradlew --refresh-dependencies at the command line from the root of the project directory. I'm not sure of gradle's default behavior, but it might update to the latest commit at a fixed interval (once per day?) if you use a "-SNAPSHOT" dependency, or it might wait for you to specify when to update using that gradlew command.

Using SquidSetup is by far the recommended approach for new users, but you may have some reason to set up your application more manually.

More manual management methods

If you are upgrading older code that did not use a dependency manager like Maven or Gradle, you will have a hard time updating without SquidSetup, so the recommended approach in that case is to make a new project in a folder of your choice, copy all of your old code over into the new project, and if you're satisfied, then copy it back to replace your old project with the reorganized and updated code. If you're updating an existing project that does use a dependency manager, you may not want to create a whole new starting point and copy over your old code, though that can still be a good option. You can instead update your dependencies. All SquidLib projects need squidlib-util, which contains the core logic that anything that uses SquidLib needs, but if you depend on the text-based display module then squidlib-util will be downloaded automatically as part of depending on the display module. If you use the logic module on its own and handle graphics yourself, you should update your existing Maven, Gradle, etc. project with the Dependency Information here. If your project used text-based display in SquidLib 3.0.0-b1, then you need to change a few things.

  • If you used Swing before, you will need to change to use LibGDX. The API is relatively similar, but the typical folder layout is not. You should probably either stick with b1 or earlier, or use SquidSetup.
  • If you used libGDX before, the name of the dependency changed from squidlib-gdx in 3.0.0-b1, to just squidlib in 3.0.0-b2 and 3.0.0-b3. It depends on squidlib-util and the core LibGDX library (gdx), but needs to be told in beta 3 what platform it targets (this avoids distributing the large LWJGL library, which is used only on desktop, to Android or other platforms that it just weighs down).

This last step is slightly more involved than before, and is part of the rationale for making SquidSetup. Using Maven for a desktop project, you would use this dependency in the desktop pom.xml:

<dependency>
  <groupId>com.squidpony</groupId>
  <artifactId>squidlib</artifactId>
  <version>3.0.0-b3</version>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-backend-lwjgl</artifactId>
    <version>1.9.1</version>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-platform</artifactId>
    <version>1.9.1</version>
    <classifier>natives-desktop</classifier>
</dependency>

Using Maven for an Android project, you would use these dependencies in the Android pom.xml:

<dependency>
  <groupId>com.squidpony</groupId>
  <artifactId>squidlib</artifactId>
  <version>3.0.0-b3</version>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-backend-android</artifactId>
    <version>1.9.1</version>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-platform</artifactId>
    <version>1.9.1</version>
    <classifier>natives-armeabi</classifier>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-platform</artifactId>
    <version>1.9.1</version>
    <classifier>natives-armeabi-v7a</classifier>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-platform</artifactId>
    <version>1.9.1</version>
    <classifier>natives-x86</classifier>
</dependency>

HTML support is broken in 3.0.0-b3 and not even present before that, so if you want to try it you should just use the snapshot version of SquidSetup. A lot of resources are needed in specific places, and I don't know of a good way to get them laid out without using a setup tool.

If you really, truly want to use Swing, despite its sluggish response time and missing features, you need to use 2.9.1 or 3.0.0-b1. This is the dependency for SquidLib using the Swing renderer and version 3.0.0-b1, which has known bugs that are fixed in newer versions, but otherwise should "work" on Windows, Mac OS X, and Linux:

<dependency>
  <groupId>com.squidpony</groupId>
  <artifactId>squidlib</artifactId>
  <version>3.0.0-b1</version>
</dependency>

There's also the last stable release in the 2.x series, which optionally depends on libGDX but will not work on mobile devices:

<dependency>
  <groupId>com.squidpony</groupId>
  <artifactId>squidlib</artifactId>
  <version>2.9.1</version>
</dependency>

If you want to use the LibGDX code in 2.9.1 (anything in a package with "gdx" in it, in that release), you need to depend on (an earlier version of) libGDX.

<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx</artifactId>
    <version>1.6.4</version>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-backend-lwjgl</artifactId>
    <version>1.6.4</version>
</dependency>
<dependency>
    <groupId>com.badlogicgames.gdx</groupId>
    <artifactId>gdx-platform</artifactId>
    <version>1.6.4</version>
    <classifier>natives-desktop</classifier>
</dependency>

(This is not a recent version of LibGDX, and it may work with more recent versions, but no guarantees can be made. The snapshot of squidlib depends on libGDX 1.9.2, squidlib 3.0.0-b3 depends on libGDX 1.9.1, squidlib 3.0.0-b2 depends on libGDX 1.7.1, and they have similar behavior about dependency handling. squidlib-gdx 3.0.0-b1 handles its dependencies on its own, so you don't need this step, except because of that behavior it will always download the desktop dependencies, even when they do nothing on the current platform.)

Fully manual management

For experts only!

You can download a release JAR of squidlib, squidlib-util, the appropriate version of libGDX, and the many dependencies libGDX has from Maven Central; look up the name of the library on Maven Central like so, and from there you can click "jar" on the right to download the jar (if jar isn't available, that isn't meant to be a dependency). You can add these jars as dependencies from your IDE. There is no way to get a recent release version of libGDX as a jar from the LibGDX site, forcing the Maven Central route. You can get a nightly build of libGDX from their site, which may work with recent SquidLib. The nightly build probably has the needed dependencies, so at least try that first. Other than that, you're on your own, good luck!

Clone this wiki locally