serandel/ktx

LibKTX: Kotlin extensions for LibGDX games and applications

Kotlin extensions for LibGDX.

Introduction

KTX 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 APIs 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 simplifying the implementation.
• Type-safe builders for GUI, styling and physics engine.
• Coroutines context providing concurrency utilities.
• 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.

Module	Dependency name	Description
actors	ktx-actors	General Scene2D GUI utilities for stages, actors, actions and event listeners.
app	ktx-app	ApplicationListener implementations and other general application utilities.
ashley	ktx-ashley	Ashley entity-component-system utilities.
assets	ktx-assets	Resources management utilities.
async	ktx-async	Coroutines context based on LibGDX threading model.
box2d	ktx-box2d	Box2D physics engine utilities.
collections	ktx-collections	Extensions for LibGDX custom collections.
freetype	ktx-freetype	FreeType font loading utilities.
graphics	ktx-graphics	Utilities related to rendering tools and graphics.
i18n	ktx-i18n	Internationalization API utilities.
inject	ktx-inject	A simple dependency injection system with low overhead and no reflection usage.
json	ktx-json	Utilities for LibGDX JSON serialization API.
log	ktx-log	Minimal runtime overhead cross-platform logging using inlined functions.
math	ktx-math	Operator functions for LibGDX math API and general math utilities.
scene2d	ktx-scene2d	Type-safe Kotlin builders for Scene2D GUI.
style	ktx-style	Type-safe Kotlin builders for Scene2D widget styles extending Skin API.
tiled	ktx-tiled	Utilities for Tiled maps.
vis	ktx-vis	Type-safe Kotlin builders for VisUI. An alternative to the scene2d module.
vis-style	ktx-vis-style	Type-safe Kotlin builders for VisUI widget styles. An extension of style module.

Installation

KTX modules are uploaded to Maven Central and are fully compatible with the Gradle build tool used by LibGDX 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.

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.6-b2'
}

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

Note that defining ktxVersion as a property 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 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.6-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. GitHub releases contain archives with generated Dokka documentation for each module, although you can go through the documentation by viewing the sources directly.

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

Before creating any pull requests, be aware that the code is dedicated to public domain.

Working from sources

See this section of the contribution guideline to get started.