libktx / Ktx

Kotlin extensions for LibGDX.

Introduction

KTX is a Kotlin game framework built on LibGDX. It aims to make LibGDX as Kotlin-friendly as possible without completely rewriting the API. It provides modular utilities and extensions for selected parts of LibGDX with poor native Kotlin support.

Examples of Kotlin language features used to improve usability, performance and readability of LibGDX include:

• Operator overloads for collections and mathematical operations.
• Extension methods with sensible default parameters.
• Inline methods with reduced runtime overhead for various listeners, builders and loggers.
• Nullable types which improve typing information of selected interfaces and functions.
• Default interface methods for common interfaces, simplifying their implementations.
• Type-safe builders for GUI, styling and physics engine.
• Coroutines context providing concurrency utilities and non-blocking asset loading.
• Reified types that simplify usage of methods normally consuming Class parameters.

See the Choosing KTX article for pros and cons of this framework.

Modules

KTX was designed to be modular from day one - in fact, some of these libraries are just a single Kotlin file. You can include selected KTX modules based on the needs of your application.

Installation

KTX modules are uploaded to Maven Central and are fully compatible with the Gradle build tool, which is used in LibGDX projects by default.

All libraries follow the same naming schema:

compile "io.github.libktx:$module:$ktxVersion"

Replace $module with the name of the selected KTX library (see table above).

For example, including the app module with the ktx-app identifier would require the following changes in your build.gradle file:

ext {
  // Update this version to match the latest KTX release:
  ktxVersion = '1.9.14-b1'
}

dependencies {
  compile "io.github.libktx:ktx-app:$ktxVersion"
}

You can find the latest KTX version on Maven Central:

As a side note, defining ktxVersion as a property in ext is not necessary, as versions can be set directly in the dependencies section. However, extracting the dependencies versions is a good practice, especially if they can be reused throughout the build files. This will speed up updating of your project if you include multiple KTX modules.

KTX modules should generally be added to the dependencies of the shared core module of your LibGDX application.

Versioning

KTX versions match the LibGDX versions that they were compiled against. $ktxVersion will usually match your LibGDX version, but it might end with -b postfix if it is a beta release or -SNAPSHOT if you are using the development branch.

For example, the first official beta release with the current group ID io.github.libktx was compiled against LibGDX 1.9.6 and since it was the second beta release, its version was 1.9.6-b2. The corresponding snapshot release of this version was 1.9.6-SNAPSHOT.

You can browse through our official releases on Maven and on GitHub.

Unfortunately, LibGDX does not follow the semantic versioning guidelines. Both minor and patch versions can introduce breaking changes. Please read the LibGDX and KTX change logs before updating.

Although KTX is still in late beta, the official beta releases are stable enough for production use. All modules are thoroughly tested with unit tests.

Latest changes

The master branch is the default branch of the repository. However, it represents the last stable release of KTX. The latest changes can be found on the develop branch.

You do not have to compile the sources manually to use the latest features. The preview snapshot releases are uploaded to the https://oss.sonatype.org/content/repositories/snapshots/ repository. To use them in your application, add the following Maven repository and modify the prefix of ktxVersion to -SNAPSHOT:

repositories {
  // Include your default repositories here.
  maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' }
}

ext {
  // Update this version to match the latest LibGDX release:
  ktxVersion = '1.9.14-SNAPSHOT'
}

The latest snapshot version name can be found on the develop branch.

Even the snapshots should be more or less stable, as the libraries are not pushed to Maven Central unless they pass their extensive test suites.

Documentation

Official guides

Each module contains a README.md file with a list of all features or a guide with some code snippets. Browse through the directories in the root folder to find out more about each library.

Source documentation

All public classes and functions are also documented with standard Kotlin KDocs. You can access the documentation by:

• Viewing the generated Dokka files hosted on the the project website.
• Reading the sources directly.
• Using the doc archive in GitHub releases with generated Dokka files.

Links

KTX wiki lists some useful resources that can help you get started.

Note that most official guides and examples in this repository assume that the reader is at least a bit familiar with the LibGDX API. If you are just getting to know the framework, it might be helpful to go through the official LibGDX wiki.

android-ktx

Note that android-ktx is a separate project with official Android utilities. The "KTX" name was chosen long before the Android project was announced.

Contribution

Suggestions, questions, typo fixes, documentation improvements and code contributions are always welcome. If you would like to contribute, please read the contribution guideline and browse through the active issues. Don't hesitate to create issues just to ask a question or make a request for any kind of improvement.

The develop is the active development branch. When creating pull requests, make sure to choose develop as the target branch.

You can check the list of the contributors via GitHub insights and on the contributors list.

Licensing

This project is dedicated to public domain.

Working from sources

See this section of the contribution guideline to get started.