A JavaFX Game Application in a Single Java File with JBang and FXGL

FXGL is a framework to easily create JavaFX-based game applications. In this blog post, I want to show you how this can be done within a single Java-file which doesn't need a full Maven or Gradle project but can be executed directly with JBang without compilation. This approach can be used as an easy way to get new Java(FX) developers started or create your first experiments with FXGL.

More info and code walk-through together with Almas Baim in this live stream, recorded on December 27th, 2023:

Used Technologies

JBang

By using JBang, no full Maven or Gradle project is needed, and the code can be executed with a single command. JBang even allows you to open a file with VSCodium with all required plugins, see JBang Editing for all info.

The installation instructions for all platforms are documented on jbang.dev/download.

FXGL

FXGL is a JavaFX Game Development Framework, which is open-source and can be found on github.com/AlmasB/FXGL.

Advantages:

• No installation or setup required
• "Out of the box": Java 8-17, Win/Mac/Linux/Android 8+/iOS 11.0+/Web
• Simple and clean API, higher level than other engines
• Superset of JavaFX: no need to learn new UI API
• Real-world game development techniques: Entity-Component, interpolated animations, particles, and many more
• Games are easily packaged into a single executable .jar or native images

It's good for:

• Any 2D game (side-scroller / platformer / arcade / RPG)
• Any business application with complex UI controls / animations
• Experimental 3D
• Hobby / academic / commercial projects
• Teaching / learning / improving game development skills
• Fast prototyping of app ideas

Earlier articles about FXGL on this site:

• 20221019: Book review - Learn JavaFX Game and App Development with FXGL 17
• 20220126: 3D printed Raspberry Pi Arcade box
• 20210111: Device monitoring tool with JavaFX, FXGL and Mosquitto
• 20200507: Getting started with FXGL game development

Java Runtime With Included Java

OpenJFX (= the sources of JavaFX) is a separate project next to the OpenJDK project (= the sources of Java). Most Java runtimes are based on OpenJDK only, so an extra step is needed to download the JavaFX runtimes. Luckily some distributors provide builds of OpenJDK with OpenJFX integrated, so you only need one installation.

On Linux and macOS with SDKMAN!

If you are running this example on Linux or macOS, use SDKMAN! to easily install such a runtime:

$ curl -s "https://get.sdkman.io" | bash
$ sdk install java 21.0.1.fx-zulu  

On Windows

Download an installer, for example, from the Azul website.

Example Application

The sources of this demo can be downloaded from GitHub. Actually, there is only one important file JBangFXGLDemo.java as this is the single file with Java code, needed to run the application. Within the resources directory, you will find the images used in the game.

This example is based on the demo project created for the article Look out, Duke! Part 1: Build a Java game with JavaFX and FXGL where a Maven project is used. All the code spread across multiple classes, has been combined into one file for this example.

JBang Configuration

As with every JBang file, we need to use a specific first line. Additionally, we also define the dependencies (only one in this case, as FXGL includes the JavaFX dependency) and the directory with the resources.

///usr/bin/env jbang "$0" "$@" ; exit $?

//DEPS com.github.almasb:fxgl:17.3
//FILES resources/

Structure of the Code

The full class consists of several elements:

• The main class that extends GameApplication:
  • The main class that starts the application.
  • All the overrides that are provided by GameApplication to initialize, configure, and start the game.
• Inner class GameFactory that implements EntityFactory:
  • This defines all the elements (BACKGROUND, CENTER, DUKE, CLOUD, BULLET) that can be spawned within the game.
• Inner classes that extend Component:
  • These are used in the GameFactory in some of the elements during their creation.
  • PlayerComponent: defines everything for the Duke player entity.
  • CloudComponent: defines everything for the flying cloud entities (enemies).

Take a look at each section of this example application, and experiment with the various settings and Components.

Running the application

$ jbang JBangFXGLDemo.java 
[JavaFX Application Thread] INFO  Engine               - FXGL-17.3 (30.03.2023 11.49) on MAC (J:21.0.1 FX:21.0.1)
[JavaFX Application Thread] INFO  Engine               - Source code and latest versions at: https://github.com/AlmasB/FXGL
[JavaFX Application Thread] INFO  Engine               -       Ask questions and discuss at: https://github.com/AlmasB/FXGL/discussions
[JavaFX Application Thread] INFO  Engine               -              Join the FXGL chat at: https://gitter.im/AlmasB/FXGL
[FXGL Background Thread 1 ] INFO  FXGLApplication      - FXGL initialization took: 0,315 sec
[FXGL Background Thread 4 ] INFO  FXGLApplication      - Game initialization took: 0,104 sec

Conclusion

FXGL is a perfect library to get started with game development with Java and JavaFX. And by using JBang, it becomes even more easy, as you only need one file to create a complete game.