AlmasB/FXGL: a JavaFX game framework for Java and Kotlin teams

What AlmasB/FXGL solves for Java and Kotlin teams

Most 2D engines assume you will learn their scene graph, their asset pipeline and their scripting language. FXGL takes the opposite position. It is a superset of JavaFX, so the UI toolkit you already know is the same one the engine renders through. The README states the API is "higher level than other engines" and that no installation or setup is required.

The audience is narrow and specific. The README lists any 2D game (side-scroller, platformer, arcade, RPG), business applications with complex UI controls and animations, hobby, academic and commercial projects, and fast prototyping. That second item is the one people miss: if you are building an internal tool with moving parts and you already ship JavaFX, FXGL gives you an entity system and a game loop without a second runtime.

The language surface matters too. The repository is primarily Kotlin, the artifact is consumed from Java or Kotlin, and the README points to a combined Maven/Gradle template project for both. So a mixed JVM codebase is the expected case, not an edge case.

How the FXGL entity and game loop mechanism works

The entry point is a subclass of GameApplication. You override initSettings, hand it a GameSettings object, and the framework owns the rest of the lifecycle. Width, height and title are set there. A static main method calls launch, which is the JavaFX application launch path. There is no separate bootstrapper and no generated project skeleton required.

On top of that lifecycle FXGL adds the techniques the README calls "real-world game development": Entity-Component, interpolated animations and particles. Entity-Component means behaviour lives in components attached to entities rather than in a deep inheritance tree, which is the standard way to keep game logic composable. Interpolated animations and particles are supplied by the framework rather than assembled by hand.

The repository layout reflects a modular build. Top-level modules include fxgl-core, fxgl-scene, fxgl-io, fxgl-controllerinput, fxgl-intelligence, fxgl-tools, fxgl-test and fxgl-samples, with the fxgl module aggregating them. That modularity has a practical consequence the README calls out directly: contributors do not need to understand the whole codebase, only the module they touch. The same structure tells you where a missing capability would live if you had to patch it.

Installing FXGL and running a first game

There is nothing to install as a separate tool. FXGL is a library, so the setup is a build file entry. The README gives the Maven coordinates with version 25, which matches the most recent release listed for the project.

<dependency>
    <groupId>com.github.almasb</groupId>
    <artifactId>fxgl</artifactId>
    <version>25</version>
</dependency>

The README also shows a Gradle form. Note that the snippet it publishes uses jcenter(), a repository that has been read-only for years, so most teams will point at Maven Central instead and keep the coordinate unchanged. The README itself says to refer to the template project if there are errors, which is the honest signal that build configuration is the part most likely to go wrong.

repositories {
    jcenter()
}

dependencies {
    compile 'com.github.almasb:fxgl:25'
}

If you are building a modular application, the README gives a complete module-info.java. One requires line is enough because the aggregator module re-exports the rest.

open module app.name {
    requires com.github.almasb.fxgl.all;
}

A minimal game is a single class. The README's example sets an 800 by 600 window titled "Basic Game App" and launches from main. Running it should open a JavaFX window with that title and nothing else, which confirms the dependency graph and the JavaFX runtime are both wired correctly before you add entities.

public class BasicGameApp extends GameApplication {

    @Override
    protected void initSettings(GameSettings settings) {
        settings.setWidth(800);
        settings.setHeight(600);
        settings.setTitle("Basic Game App");
    }

    public static void main(String[] args) {
        launch(args);
    }
}

If you would rather not manage a build at all, the README points to an uber jar on the Releases page. If you want working code before writing your own, the fxgl-samples module and the standalone basic examples directory are the fastest route.

Where FXGL is the wrong choice

The README is unusually candid about 3D: it appears in the topics and in the feature list, but the "Good for" section qualifies it as experimental 3D. If your project needs a production 3D renderer, that word is the answer, and no amount of entity-system convenience compensates for it.

Platform breadth is broader than it first appears but not free. The README claims Java 8 through 25 and Windows, Mac, Linux, Android 8+, iOS 11.0+ and Web. Those targets are reached through JavaFX and its packaging toolchain, not through FXGL itself, so the packaging step is where a mobile or web build will consume your time. The README does not document a rollback or downgrade path, and it does not describe what happens when a target platform's JavaFX support lags the JDK you are compiling against.

There is a second, quieter cost. Because FXGL is a superset of JavaFX, you are also bound by JavaFX's threading model and its module system. Teams that have fought JavaFX deployment before will recognise the shape of that work. Teams that have not should treat the packaging step, not the game code, as the risky part of the schedule.

Finally, the ecosystem is small. The README lists one maintainer and one coordinator, plus two named testers, and the community section is mostly universities and schools rather than studios. That is not a defect, but it does mean the answer to an unusual question may be in the wiki or in GitHub Discussions rather than in a search result.

FXGL against LibGDX and the plain JavaFX route

The closest comparison is LibGDX. LibGDX is a rendering and platform abstraction layer: it owns its own graphics backend and gives you a lower-level API that maps onto desktop, Android, iOS and web. FXGL does not replace the graphics stack; it sits on JavaFX and gives you a higher-level API over it. The practical difference is what you already know. A JavaFX team gets a game loop, entities, particles and animations without a second mental model. A team that wants direct control over rendering, shaders and asset pipelines will find LibGDX's lower level more appropriate, and will pay for it in setup time.

The other comparison is doing it yourself in JavaFX. You can write an AnimationTimer, keep a list of sprites and hand-roll collision. That works until you need particle effects, interpolated animation and an entity lifecycle, at which point you are rebuilding the parts FXGL already ships. The README frames the framework as a superset for exactly this reason: the migration path from plain JavaFX to FXGL is additive rather than a rewrite.

A third option worth naming is a general-purpose engine such as Godot or Unity. Those give you a visual editor and a much larger asset ecosystem, at the cost of leaving the JVM and adopting a new language or toolchain. FXGL's pitch is that you do not have to make that trade.

Licence, maintenance and the cost of upgrading

FXGL is MIT licensed, which is permissive and imposes few obligations beyond retaining the notice. The repository also carries a LICENSE_3RD_PARTY directory and a LICENSE_HEADER file, so a dependency audit should read those rather than assume the top-level MIT text covers everything bundled. This is a description of what the repository contains, not legal advice.

Maintenance is current. The last push to the dev branch was on 2026-09-19, four days before this writing, and the repository is not archived. Releases are infrequent and large rather than continuous: version 25 landed on 2026-02-05, version 21.1 on 2024-03-26, and version 21 on 2023-12-28. That cadence matters for planning. You can expect long gaps between tagged versions, so pin the version in your build file rather than tracking a range, and treat an upgrade as a scheduled task with a test pass rather than a background update.

The release notes for 25 would be the place to check for breaking changes; the README does not summarise them. Contributions are reviewed against a Code of Conduct, and the README states that the framework is fully modular, so a patch to one module does not require understanding the rest. That is the realistic path if you hit a bug in a module nobody else is using.

Editorial conclusion

Adopt FXGL if your team already writes Java or Kotlin and your target is a 2D game, a prototype, or a JavaFX application that needs sprites, particles and an input loop. Do not adopt it if you need a mature 3D pipeline or a non-JVM runtime, since the README itself labels 3D experimental. Before committing, verify the JavaFX packaging path for your target platform and pin the exact artifact version in your build file.

Frequently asked questions

Official sources

1. AlmasB/FXGL on GitHub
2. License: MIT
3. Project website
4. README
5. Releases