ktx - LibKTX - Kotlin extensions for LibGDX games and applications - Kotlin Resources

Travis CI Maven Central Kotlin LibGDX

KTX

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.

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.

compile "io.github.libktx:ktx-actors:1.9.10-b4"

Related Libraries

uno-sdk

UNofficial Opengl SDK

Last updated 3 mins ago

ovr

4

Last updated 3 mins ago

openvr

OpenVR SDK

Last updated 3 mins ago

glm

jvm glm

Last updated 3 mins ago

gli

jvm gli

Last updated 3 mins ago