LWJGL Project Template Development

Sarah Silva

Completed work

Software Engineer

Java

Computer Software

LWJGL Template

🌟 This is a template for kick-starting a LWJGL project

☕ This template is using Java 1.11

🐘 This is a Gradle project, it comes with the following dependencies:

Everything needed to spin up a simple LWJGL application with GLFW.

Java OpenGL Math Library

guacamole: A small collection of some common and very basic utilities for libGDX games

For more details about dependencies, take a look at the build.gradle file

Getting started

Get this template by clicking on the Use this template button at the top of this page

This will generate a repository of your own with this template inside. After creating your brand new repository, go ahead and clone your repo:

Eg:

git@github.com:your-username/your-brand-new-repo.git

Choose a name for your project by changing the default name set inside settings.gradle:

rootProject.name = 'your-brand-new-project-name'

Change your group and version attributes as needed inside build.gradle:

group "org.example"
version "1.0-SNAPSHOT"

Review and change any other configuration inside build.gradle if needed.

Build and run your appplication:

./gradlew run

and voilà! 💨

Breakdown

This repository is divided into the following:

Application.java

Class with the main method:

import glfw.Window;

import static de.damios.guacamole.gdx.StartOnFirstThreadHelper.startNewJvmIfRequired;

public class Application {

    private static final Window WINDOW = Window.getInstance();

    public static void main(String[] args) {
        // Starts a new JVM if the application was started on macOS without the
        // -XstartOnFirstThread argument.
        if (startNewJvmIfRequired()) {
            System.exit(0);
        }
        WINDOW.run();
    }
}

GLFW windows may only be created on the main application thread. However, on MacOS systems, there's a strange behavior where this does not happen naturally and the following exception is thrown when trying to run the application.

Caused by: java.lang.IllegalStateException: GLFW windows may only be created on the main thread and that thread must be the first thread in the process. Please run the JVM with -XstartOnFirstThread. For offscreen rendering, make sure another window toolkit (e.g. AWT or JavaFX) is initialized before GLFW.

More on that here. As cited on the message above, a fix for that would be setting up the JVM flag -XstartOnFirstThread. Even so, this is a manual process that needs to be done every time before the application is run on a MacOs system. In order to avoid having to do anything outside of the application itself, a helper function startNewJvmIfRequired() is being used for this template, that will automatically start a new JVM with the necessary flag if the application was started on macOS without -XstartOnFirstThread. This solution can be seen being used inside the main method inside Application.java (as shown on the snippet above) and was provided by the guacamole collection, thanks for that! 🙏

Util package:

Color.java: Utilitary enum class for RGB colors. You can instantiate a Color with RGB values by its name. For example, let's say you wanted to get the RGB values for the color purple:

   // Call Color.from(nameOfYourColorAsString);
   Color purpleColor = Color.from("purple");
   
   System.out.println(purpleColor.getRed());
   System.out.println(purpleColor.getGreen());
   System.out.println(purpleColor.getBlue());

The output would be:

   0.502
   0.0
   0.502

Besides the already existing colors inside Color.java, it's possible to modify it and add any additional colors as you desire.

FileUtils.java: Utilitary class that can retrieve the contents of a resource file as an InputStream. For example, let's say you wanted to get the contents of a file whose path is {project_root}/src/main/resources/example/HelloWorld.txt. The following code would print out the file contents of the file:

  String fileContents = FileUtils.getFileFromResourceAsStream("example/HelloWorld.txt").toString();
  System.out.println(fileContents);

NOTE: Files should be stored inside: {project_root}/src/main/resources/ as this is the starting root directory for resources. Storing files inside this directory will ensure the files can also be located when you build your application into a jar.

Geometry Configuration package:

World.java: Configuration class that holds the values representing the projection of the world. The static funcion setCoordinatePlane() will apply the configured values to the org.lwjgl.opengl.GL11.glOrtho() function. For more details, take at look at the class itself.

GLFW package:

Window.java: Singleton class that holds the GLFW window configuration setup and the main game loop.

Usage:

  // Get the Window instance
  Window windowInstance = Window.getInstance();
  // Calling the run() method will initialize GLFW and OpenGL bindings. Soon after that, the main game loop will start.
  windowInstance.run();
  // Calls after this point will only be executed after GLFW has received a signal to terminate..
  // ...

Listeners: A Key Listener and a Window Resize Listener are configured for use with GLFW. Both are singletons.

Key Listener Example for quering if a key is pressed during the game loop:

  // Get KeyListener instance
  KeyListener keyListener = KeyListener.getInstance();
  if (keyListener.isKeyPressed(GLFW_KEY_SPACE)) {
         System.out.println("Space key is being pressed!");
     }

Window Resize Listener: This listener will execute whatever is inside the method reshape(long window, int width, int height); whenever GLFW detects that the window has been resized.

Authors

Sarah Lacerda

License

This project is licensed under the MIT License - see the LICENSE file for details.

Like this project

Completed work

Posted Jul 30, 2025

A well-organized LWJGL3 starter template using Java 11, Gradle, GLFW helper classes, and utility code

Likes

Views