Awesome
SquidSetup
A fork of czyzby/gdx-setup, preconfigured for SquidLib
SquidLib is a nice way to make roguelikes or other grid-based games in Java, but in the
current version, it has the problem that all libGDX-based libraries have: it needs some
challenging setup to be done to get Gradle, a JVM build tool, to build the project.
Thankfully, both the official libGDX team and the unofficial group working with czyzby
have provided a setup tool that does the grunt work of configuring a sample Gradle
project to know about LibGDX's dependencies, automatically downloading them, and optionally
setting up platforms other than desktop, like HTML, iOS and Android. Since SquidLib had the
same issue that was solved for libGDX with this setup tool, a quick edit of czyzby's setup
to depend on the latest commit of SquidLib means we have this tool, SquidSetup, that lets
you go through a few simple steps in a GUI and get a pre-configured project set up to run
on Linux, Windows, MacOS, GWT/HTML, Android, and/or iOS. The project will include modules
for whichever of Desktop, GWT, Android, and/or iOS you selected plus an always-present Core
module, and a sample set of code (mostly in one file in the core module) that uses squidlib
and squidlib-util
and shows how to use the libraries to handle dungeon generation, input
handling, pathfinding, text-based display, field of vision, fictional language generation,
and the kitchen sink. It will also guarantee SquidLib's core in squidlib-util
is available,
and optionally will depend on squidlib
to provide text-based full-color display using
LibGDX (this dependency is needed to run the sample game, but if you don't intend to use the
text-based example code, the tool also lets you use LibGDX a la carte if you want to
handle the graphics yourself).
Usage
- Get the latest
SquidSetup.jar
from the Releases tab of this project.- You may want the stable 3.0.0 release, which came out July 22, 2020 and won't change until another stable release (which still won't make the stable SquidSetup act any differently).
- You may want the small but meaningful improvements in the 3.0.4 release, which applies fixes to Android and some fixes to JDK version issues on desktop/LWJGL3, plus some new features.
- Future changes to SquidSetup for an existing SquidLib version will be applied to -u1, -u2, -u3, etc.; there's already a 3.0.0-u1, but it's almost entirely superseded by 3.0.4.
- You may instead want the latest possible code using the 3.0.5-JITPACK Release,
which is still receiving updates, just at a slower pace. The latest version will get a commit compiled by JitPack.io, while the beta and stable versions
will be obtained from Maven Central. The latest commit is determined by the library
jcabi-github
, and involves an API call to GitHub when using the snapshot release (not any beta or stable releases); the API call may be a little slow or might not complete if GitHub is having issues. However, because the code at that commit is the same at any point in the future, the snapshot commits won't "suddenly stop working" like a dependency on a nightly build might; you update when you want to, and if something breaks, you can always go back to an older commit that you know works.
- Regardless of what platforms you intend to target, make sure the steps described by the LibGDX wiki here are taken care of.
- Run the JAR. Plug in whatever options you see fit:
- For the Platforms tab, you can technically use the "Toggle Client Platforms" button to enable LWJGL3 (which works
on all desktop/laptop platforms), Android, iOS (which will only build on a MacOS machine), and HTML. This
isn't always a good idea because downloading iOS and HTML dependencies can take some time, so just check the
platforms you want to target. You can re-run the setup, make a new project with the same settings (in a different
folder), and copy in the existing code if you want to quickly add a platform or platforms.
- Desktop and/or LWJGL3 should usually be checked, so you can test on the same computer
you develop on.
- LWJGL3 is almost the same as Desktop, but because it has better support for new hardware (such as high-DPI displays), it should probably be preferred. It also allows multiple windows and drag+drop.
- iOS should probably not be checked if you aren't running MacOS and don't intend to later build an iOS app on a Mac. It needs some large dependencies to be downloaded when you first import the project.
- Android should only be checked if you've set up your computer for Android development, and may cause some hassles even in other projects if you use Android Studio or IntelliJ IDEA. Personally, I avoid creating Android modules as part of a larger project unless they only target Android, since if there's only a core and an android module, nothing will interfere. You should absolutely make sure that IDEA has "configure on demand" disabled; under settings you can search for "demand" to find it. Android Studio and IDEA should always have it disabled now by default.
- HTML is a more-involved target, with some perfectly-normal code on all other platforms acting completely
different on HTML due to the tool used, Google Web Toolkit (GWT). It's almost always possible to work around
these differences and make things like random seeds act the same on all platforms, but it takes work. Mostly,
you need to be careful with the
long
andint
number types, and relates toint
not overflowing as it would on desktop, andlong
not being visible to reflection. See this small guide to GWT for more.- SquidSetup for release 3.0.4 uses GWT 2.9.0 via a custom backend,
which enables using Java 11 features, such as
var
, but not JDK 11 library code. The backend is closely related to the libGDX version used, and requires using libGDX 1.10.0 (the current version). The 3.0.0-JITPACK release does not use GWT 2.9.0 or the custom backend, and uses libGDX 1.10.0's default of GWT 2.8.2, but the newer 3.0.5-JITPACK release does use GWT 2.9.0 via the custom backend.
- SquidSetup for release 3.0.4 uses GWT 2.9.0 via a custom backend,
which enables using Java 11 features, such as
- Desktop and/or LWJGL3 should usually be checked, so you can test on the same computer
you develop on.
- If the "Templates" tab has "SquidLib Basic" checked, then dependencies will be added
for
squidlib-util
andsquidlib
. If that template isn't checked, no dependencies will be added beyond libGDX. It is recommended that you use the SquidLib Basic template just so everything is set up correctly, even if you remove thesquidlib
display to only usesquidlib-util
for logic handling. - You don't need LibGDX checked (the tool is set up to download LibGDX and set it as a dependency in all cases).
- For the Platforms tab, you can technically use the "Toggle Client Platforms" button to enable LWJGL3 (which works
on all desktop/laptop platforms), Android, iOS (which will only build on a MacOS machine), and HTML. This
isn't always a good idea because downloading iOS and HTML dependencies can take some time, so just check the
platforms you want to target. You can re-run the setup, make a new project with the same settings (in a different
folder), and copy in the existing code if you want to quickly add a platform or platforms.
- Click generate, and very soon a window should pop up with instructions for what to do.
Now you'll have a project all set up with a sample.
- The project will have a lot of font resources in the
assets/
folder. You should probably delete or move any you don't need.Iosevka-Slab-msdf.fnt
andIosevka-Slab-msdf.png
are needed to run the generated basic demo, and if you intend to keep using them you should also includeIosevka-License.md
to abide by Iosevka's license. You don't need any other files unless you intend to use a different font, such asIosevka-Family-msdf
to get bold and italic support,NotoSerif-Family-msdf
to have a nice variable-width font that also has bold and italic support,SourceHanCodeJP-Regular-distance
to get excellent support for Japanese text, orMonty-4x10
if you want your users to go blind staring at one of the smallest fonts possible. The classDefaultResources
has documentation on what exact files are needed to use which fonts and other assets, such as icons. - If you use Android Studio or IntelliJ IDEA and have an Android project, you'll need to use
Gradle tasks to do any part of the build/run process, thanks to a long-standing issue in
IDEA's Android plugin. The simplest way to do this is in the IDE itself, via
View -> Tool Windows -> Gradle
, and selecting tasks to perform, such asDesktop -> Tasks -> application -> run.
If you try to run a specific class'main()
method, you may encounter strange issues, but this shouldn't happen with Gradle tasks. This also shouldn't happen if you avoid creating an Android module in the first place (if you didn't check Android in the setup, this problem shouldn't apply). - If you had the LWJGL3 (or Desktop) and SquidLib options checked in the setup, you can try to run the LWJGL3 or Desktop module right away, with a simple pathfinding/FOV/text-gen demo that responds to mouse and keyboard input in a random dungeon (the random number generator is seeded the same every time by default, but you can change the RNG constructor as a way to experiment).
- If you had the Android option checked in the setup and are using the SquidLib Basic template, you can try to run the Android module on an emulator or a connected Android device.
- If you had the GWT option checked in the setup and are using the SquidLib Basic template,
you can go through the lengthy, but simple, build for GWT, probably using the
superDev
task for thegwt
module, or also possibly thedist
task in that module. - If you had the iOS and SquidLib options checked in the setup, you're running Mac OS X, you have jumped through Apple's now-infamous process described at the LibGDX wiki at the earlier link, you've made the blood sacrifice to your iAltar, and the Black Turtleneck of Cosmic Power and Ultimate Build Quality has manifested before you and informed you of your truename, you can attempt to run the iOS module. If it works, you'll have the record of being the first person to run SquidLib on an iOS device... In case you can't tell, I am not terribly confident in the ability of this tool to generate iOS projects that work on the first try, though it may be easy enough to modify things in the likely case they don't immediately work.
- All builds currently use Gradle 7.1 with the "api/implementation/compile fiasco" resolved.
Recent Java works with SquidSetup because Gradle 7.1 supports Java from 8 to 16.
Adding dependencies will use the
api
keyword instead of thecompile
keyword it used in earlier versions. All modules use thejava-library
plugin, which enables theapi
keyword for dependencies. - You may need to refresh the Gradle project after the initial import if some dependencies timed-out;
JitPack takes a minute or two to build SquidLib, and it usually doesn't take long before the SquidLib
dependencies can be downloaded in full. In IntelliJ IDEA, the
Reimport all Gradle projects
button is a pair of circling arrows in the Gradle tool window, which can be opened withView -> Tool Windows -> Gradle
. - JCenter is being rapidly closed by its parent company, so it's a good idea to get away from that sinking ship as quickly as possible. SquidSetup won't look on JCenter for dependencies by default.
Recommended Settings
These apply to the options on the Advanced tab, which may need some extra explanation.
- LibGDX version: 1.10.0.
- 1.10.0 is a dependency of SquidLib 3.0.4.
- 1.10.0 is the current dependency for later commits available on JitPack.
- If you target HTML, the custom backend used here by default requires libGDX 1.10.0.
- Application version: Your choice
- Maybe
0.0.1-SNAPSHOT
if it's going to change a lot.-SNAPSHOT
has special meaning as a non-release.- On iOS, you can't use anything but digits and
.
in a release version.
- On iOS, you can't use anything but digits and
- Maybe
- Java version: 8.0, 11.0, or 16.0
- 8.0 is the max for Android and iOS, but 16.0 can be used for desktop/LWJGL3 only
(if you have Java 16 installed, which you should also bundle for users). 11.0 is the current LTS
release, which really only has meaning if you're paying for support from Oracle. Contrary to popular
opinion, LTS releases have no special guarantees of stability, just that Oracle is maintaining that
version for a longer period of time. Red Hat marks Java 8 as an LTS release if you pay for support
from them (Azul Systems also treats 8 as LTS, and probably several others), and Java 8 is still what
most Java developers are using.
- You must use a JDK with version 15 or lower to build Android projects, currently, due to limitations of the Android tooling. JDK 8 and 11 are recommended.
- 8.0 is the max for Android and iOS, but 16.0 can be used for desktop/LWJGL3 only
(if you have Java 16 installed, which you should also bundle for users). 11.0 is the current LTS
release, which really only has meaning if you're paying for support from Oracle. Contrary to popular
opinion, LTS releases have no special guarantees of stability, just that Oracle is maintaining that
version for a longer period of time. Red Hat marks Java 8 as an LTS release if you pay for support
from them (Azul Systems also treats 8 as LTS, and probably several others), and Java 8 is still what
most Java developers are using.
- Server Java version: Must be at least equal to
Java version
, maybe should be equal.- Only matters if you have selected a Server project on the Platforms tab.
- Android plugin: 4.1.2
- 4.1.2 seems to work well as long as Android has been set up fully. It enables more of Java 8's
features, and you can set the Java version to 8.0 with this Android Gradle Plugin version.
- You can try to update
androidPluginVersion
ingradle.properties
if you want to try some newer features, and if the newer version doesn't work, you can downgrade there too.
- You can try to update
- 4.1.2 seems to work well as long as Android has been set up fully. It enables more of Java 8's
features, and you can set the Java version to 8.0 with this Android Gradle Plugin version.
- Target Android API: 29
- This is required by the Play Store. 30 may be required now.
- RoboVM Version: 2.3.12
- This can be updated if there's a newer release, but only matters if you target iOS.
- GWT plugin version: 1.1.12
- This is the most recent version, and it works fine.
Good luck, and I hope you make something great!