/ktx

LibKTX: Kotlin extensions for LibGDX games and applications

Primary LanguageKotlinCreative Commons Zero v1.0 UniversalCC0-1.0

Travis CI Maven Central Kotlin LibGDX

KTX

Kotlin utilities for LibGDX applications.

About the project

KTX aims to make LibGDX as Kotlin-friendly as possible without turning the API upside down. It provides modular utilities for certain parts of LibGDX with poor Kotlin support. This is not a new framework by any means - but Kotlin certainly makes LibGDX feel like one.

Do not confuse KTX with android-ktx: an official Google project with Android utilities. "KTX" name was chosen long before the Android project was announced.

Modules

KTX was designed to be modular from day one: in fact, some of these libraries are just a single Kotlin file. After all, you might not want or need all modules in your application. When possible, the extensions do not depend on the standard Kotlin library - and even if they do, it is marked as a provided dependency. You can choose the Kotlin version that suits you best and it will not be overridden by your build system.

Current KTX modules:

  • actors: general Scene2D utilities for stages, actors, actions and event listeners.
  • app: ApplicationListener abstract implementations and other general LibGDX application utilities.
  • ashley: Ashley entity-component-system utilities.
  • assets: resources management utilities.
  • async: coroutines context based on LibGDX threading model.
  • box2d: Box2D physics engine utilities.
  • collections: extensions for LibGDX custom collections. Based on Kotlin standard library utilities.
  • freetype: FreeType font loading utilities.
  • graphics: utilities related to rendering tools and graphics.
  • i18n: some simple extensions that make LibGDX internationalization API less verbose, safer and easier to use.
  • inject: unsettlingly simple dependency injection with nearly zero runtime overhead and no reflection trickery.
  • json: utilities for LibGDX JSON serialization class.
  • log: minimal runtime overhead cross-platform logging using inlined blocks.
  • math: operator overloads for LibGDX math API and general math utilities.
  • scene2d: type-safe Kotlin builders for Scene2D GUI.
  • style: enhances Skin API with type-safe builders of official Scene2D widget styles. Replace your JSON skin file with type-safe DSL.
  • vis: type-safe Kotlin builders for VisUI. An alternative to the scene2d module.
  • vis-style: enhances Skin API with type-safe builders of VisUI widget styles. An extension of style module.

Note that most guides and examples assume that the reader is at least a bit familiar with the LibGDX API.

Afraid to use some third-party code? Browse through the sources, run the test suites. While certainly not perfect, we try to keep the public API clean and every feature fully unit tested. Note: coverage tools still have problems with Kotlin inlined methods, so the reported code coverage might be much lower than the actual.

Dependencies

KTX libraries are currently in late beta. While tested and stable enough, we want to give them a little bit more time and get some user feedback before a stable release. All versions are available through Maven Central and here. You can also use the preview snapshot releases from https://oss.sonatype.org/content/repositories/snapshots/ repository.

All libraries follow the same naming schema - this is an example Gradle dependency:

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

Replace $module with the name of required KTX library. $ktxVersion usually matches LibGDX version it was compiled against - although it might end with -b1 (if it is a beta release) or -SNAPSHOT (if you are using the snapshots). For example, the first official beta release with the current group ID was compiled against LibGDX 1.9.6 and its version was 1.9.6-b2. You can browse through our releases here.

Note that even snapshots should be more or less stable, as libraries are not pushed to Maven Central unless they pass the extensive tests.

Documentation

Each module contains a README.md file with a list of all features or a guide with a few code snippets. Browse through the directories in root folder to find out more about each library. GitHub releases also contain archives with generated Dokka documentation for each module. KTX wiki lists some useful resources as well.

Contribution and working from sources

If you want to help, read the contribution guideline and browse through the issues to see what's currently to do. Don't be afraid to create issues just to ask a question or make a request for any kind of improvements. Before creating any pull requests, be aware that the code is dedicated to public domain.