Running the game engine and libGDX-based tools on macOS

There is a quirk that you will run into with the game engine if you are working on a Mac. Hopefully this wiki will help resolve some of the most likely issues you could run into while working during the sprints.

Common Issues

Why do I need XstartOnFirstThread?

The Getting Started guide mentions that to run the game on macOS, you need to set the XstartOnFirstThread argument. The reason is that the game engine is built on libGDX, which in turn uses libraries that require specific thread management. You do not need to worry about these thread management issues in developing a game built on this game engine but, for macOS, you must tell the JVM to run the application's main thread on thread zero. If you do not do this the game will not run or will be unstable.

I want to use the TexturePacker GUI for my sprite sheets. Nothing opens up!

Guess what? This may be the same issue as with the game engine. Add the XstartOnFirstThread JVM argument. Once you have installed it, run the following: java -jar -XstartOnFirstThread /Applications/GDX Texture Packer.app/Contents/java/desktop.jar. This will launch the application with the additional JVM argument, and the interface should appear now.

If you are still struggling to use it, I would encourage you to try using the runnable-texturepacker.jar application from libGDX via the Terminal. This is the official libGDX tool. You can run it using the following command: java -cp [location of runnable-texturepacker.jar] com.badlogic.gdx.tools.texturepacker.TexturePacker [source directory of sprites] [desired output directory of atlas] [atlas name], replacing the arguments as required. For more details, see its documentation.