Contributing to libGDX can come in a few different forms: you can report issues, help out on the Discord, pledge to the Patreon page, and submit code and documentation back to the project on GitHub. Check out the CONTRIBUTING.md file on GitHub to find out more!

If you want to submit code back to the project, please take a moment to review our guidelines below.

Guidelines

API Changes & Additions

If you modify a public API, or add a new one, make sure to add these changes to the CHANGES file in the root of the repository.

If you want to pick the brains of other devs, either open an issue on our issue tracker, send a pull request and start a conversation on Github, or join our official Discord server.

Contributor License Agreement

libGDX is licensed under the Apache 2.0 license. Before we can accept (major) code contributions, we need you to sign our Contributor License Agreement. Just print it out, fill in the blanks and send a copy to contact@badlogicgames.com, with the subject [libGDX] CLA.

Signing the CLA will allow us to use and distribute your code. This is a non-exclusive license, so you retain all rights to your code. It’s a fail-safe for us should someone contribute essential code and later decide to take it back.

Formatting

If you are working on any of the libGDX code, we require you to use our formatter. To make our life easier, we have integrated the formatter into our build system with Spotless. This allows you to run ./gradlew spotlessApply to format your files locally and also ensures that pull requests are formatted automatically via GitHub Actions.

Alternatively, you can find the Eclipse formatter file here, which can also be imported into IntelliJ IDEA and Android Studio. See here for official documentation on how to do this.

Code Style

libGDX doesn’t have an official coding standard, but we stand by the usual Java style, as should you.

Please do not do any of the following:
  • Underscores in identifiers
  • Hungarian notation
  • Prefixes for fields or arguments
  • Curly braces on new lines

A few additional notes to keep in mind:

  • When creating a new file, make sure to add the Apache file header, as you can see here
  • Follow the style of the code in the file you are changing
  • If you create a new class, please add documentation that explains the usage and scope of the class. You don’t have to add javadocs for methods that are self explanatory.
  • If your class is thread safe, mention it in the documentation. Its assumed that libGDX classes are not thread safe by default, so please mention it.

Compatibility

Due to the cross platform nature of libGDX, there are some things you have to avoid when contributing code. For example. GWT does not support all java features, and Android does not support all desktop JVM features.

Considerations for GWT compatibility

If some java features are not supported on GWT they must either be emulated or avoided. Emulation is also required for native code (Matrix4). An example of emulation is shown here.

Common limitations on GWT include:
  • Formatting: String.format() is not supported.
  • Regular expressions. However, a basic emulation of Pattern Matcher is provided.
  • Reflection. Use libGDX reflection instead.
  • Multithreading: Timers are supported on GWT, but threads are strictly not.

For each new file added to LibGDX, you need to determine whether it is compatible with GWT, and either include or exclude it in the GWT module. To include a class file, add a new entry to the gdx/src/com/badlogic/gdx.gwt.xml file. See for example this PR. If the new file isn’t added to gdx/src/com/badlogic/gdx.gwt.xml, an error similar to

[ERROR] Errors in 'jar:file:<...>'
      [ERROR] Line <line num>: No source code is available for type com.badlogic.gdx.graphics.g3d.environment.PointShadowLight; did you forget to inherit a required module?
[ERROR] Aborting compile due to errors in some input files

may be seen.

Performance considerations

Due to some of the targets of the framework being mobile and the web, along with it being a game development focused framework, its important to keep performance as tight as possible. On mobile platforms especially, memory management is very important, so we don’t create any garbage in the core of libGDX.

A couple of guidelines regarding performance:
  • Avoid any temporary object allocation
  • Do not make defensive copies
  • Avoid locking, libGDX is not thread safe, unless explicitly specified.
  • Use the Collection classes libGDX provides in the com.badlogic.gdx.utils package, do not use java collections
  • Do not perform argument checks for methods that may be called thousands of times per frame
  • Use pooling if necessary, if possible avoid exposing the internal pooling to the user

Size of code changes

To reduce the chances of introducing errant behavior and to increase the chance that your pull request gets merged, we ask you to keep the requests small and focused.

  • Submit a pull request dedicated to solving one issue or feature. Pull requests confusing multiple things are much harder to review and will be denied.
  • Keep the code changes as small as possible.


Other development resources

There are a few wiki articles concerned with contributing to libGDX: