Kotlin extensions for the libGDX game framework

KTX

Last update: Dec 31, 2022

Related tags

Kotlin android kotlin gamedev game-engine async graphics libgdx coroutines game-development kotlin-extensions kotlin-library scene2d box2d kotlin-dsl ktx hacktoberfest kotlin-coroutines kotlin-utilities libgdx-api libktx

Overview

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 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 improving original libGDX APIs without the use of inheritance.
Inline methods with reduced runtime overhead for various listeners, builders, and loggers.
Nullable types which improve typing information of selected interfaces and functions.
Default parameters reducing boilerplate code.
Type-safe builders for GUI, styling, and physics engine.
Default interface methods for common interfaces, simplifying their implementations.
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, many of its libraries are just a single Kotlin file. You can include selected KTX modules based on the needs of your application.

Module	Description
`ktx-actors`	`Scene2D` GUI extensions for stages, actors, actions, and event listeners.
`ktx-app`	`ApplicationListener` implementations and general application utilities.
`ktx-ashley`	`Ashley` entity-component-system utilities.
`ktx-assets`	Resources management utilities.
`ktx-assets-async`	Non-blocking asset loading using coroutines.
`ktx-async`	Coroutines context based on libGDX threading model.
`ktx-box2d`	`Box2D` physics engine utilities.
`ktx-collections`	Extensions for libGDX custom collections.
`ktx-freetype`	`FreeType` fonts loading utilities.
`ktx-freetype-async`	Non-blocking `FreeType` fonts loading using coroutines.
`ktx-graphics`	Utilities related to rendering tools and graphics.
`ktx-i18n`	Internationalization API utilities.
`ktx-inject`	A dependency injection system with low overhead and no reflection usage.
`ktx-json`	Utilities for libGDX JSON serialization API.
`ktx-log`	Minimal runtime overhead cross-platform logging using inlined functions.
`ktx-math`	Operator functions for libGDX math API and general math utilities.
`ktx-preferences`	Improved API for accessing and saving preferences.
`ktx-reflect`	Utilities for libGDX reflection API.
`ktx-scene2d`	Type-safe Kotlin builders for `Scene2D` GUI.
`ktx-style`	Type-safe Kotlin builders for `Scene2D` widget styles extending `Skin` API.
`ktx-tiled`	Utilities for Tiled maps.
`ktx-vis`	Type-safe Kotlin builders for `VisUI`.
`ktx-vis-style`	Type-safe Kotlin builders for `VisUI` widget styles.

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:

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

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

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

// Groovy DSL:
ext {
  // Update this version to match the latest KTX release:
  ktxVersion = '1.10.0-b4'
}

dependencies {
  api group: 'io.github.libktx', name: 'ktx-app', version: ktxVersion
}

// Kotlin DSL:

// Update this version to match the latest KTX release:
val ktxVersion = "1.10.0-b4"

dependencies {
  api(group = "io.github.libktx", name = "ktx-app", version = ktxVersion)
}

You can find the latest KTX version on Maven Central:

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

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.

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.

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 still uses beta release tags, 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. It represents the latest stable release of KTX. It ensures that the documentation in the repository is in sync with the latest version.

The newest changes can be found on the develop branch instead.

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:

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

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

// Kotlin DSL:
repositories {
  // Include your other repositories here.
  maven("https://oss.sonatype.org/content/repositories/snapshots/")
}

// Update this version to match the latest libGDX release:
val ktxVersion = "1.10.0-SNAPSHOT"

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

Even the snapshots are rather stable, as the libraries are not pushed to Maven Central unless they pass their extensive test suites. However, the public APIs in snapshot releases might be changed prior to a stable release.

Documentation

Official guides

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

Source documentation

All functionalities are documented with Kotlin KDocs. You can access the source documentation by:

Viewing the generated Dokka files hosted on the project website.
Extracting the doc folders with Dokka files from release archives.
Reading the sources directly.

Links

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

Most official guides and code 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, and convert some Java examples to Kotlin.

Contribution

Suggestions, questions, typo fixes, documentation improvements and code contributions are always welcome.

Do not hesitate to start a discussion with questions about the framework. Feel free to advertise your KTX project, propose new features, discuss game jams, or even create a personal devlog.

If you would like to contribute, please read the contribution guideline, and browse through the active issues. 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.

Comments

Coroutines fail to run on iOS with RoboVM
I'm hoping to get some help with the use of async on iOS. I'm not sure if it's a bug, or if it's my setup, or if async is even meant to work on iOS.

When using versions 1.9.13 of libGDX, 1.9.13-b1 of KTX, 1.4.2 of kotlinx-coroutines-core, the app compiles fine, but I see the following runtime error when I try to call the KtxAsync.initiate() function in Game#create().

java.lang.NoClassDefFoundError: ktx/async/KtxAsync

When using versions 1.9.14 of libGDX and 1.9.14-b1 of KTX, I get 58 duplicate symbols error due to underscore and dot versions in the packages and fails to compile the app.

libgdx.a(com.badlogic.gdx.graphics.g2d.Gdx2DPixmap.o) libgdx.a(com_badlogic_gdx_graphics_g2d_Gdx2dPixmap.o)

The issue in 1.9.14 is probably due to this: https://github.com/libgdx/libgdx/issues/6437 and not a KTX issue.

More versions:

Kotlin: 1.4.+

Robovm: 2.3.11

Kotlinx-coroutines-core: 1.4.2

Please let me know if you have any ideas of about getting async working on iOS.
bug async
opened by auraxangelic 36
Tools module and BundleLineCreator for #14

This adds a class for generating BundleLines mostly automatically. It can be used from an app or the module can be imported as a buildscript dependency and used as a gradle plugin that adds a task for generating the BundleLines. See the README for a complete description.

How rigorous should the testing be? I'm not sure how to appropriately test some of the behaviors like finding the assets directory. Unlike other Ktx utilities, this tool is more like a development script, not a component relied on by game code.

Feel free to edit this branch. I don't know if I've appropriately set up the new module.
tools

opened by cypherdare 28
Immutable Vector 2D
Contributes to #152

I open this pull request, because I consider ImmutableVector2 to be feature-complete.

Before merge I want to:

[x] Rename for ImmutableVectorN

[x] Inline alias-functions

[x] Add tiny vectors (like (0.001, -0.001)) in the list of vector to test

[x] Add the missing comments

[x] Replicate syntax sugar KTX was providing for Vector2

[x] Update the changelog

[x] Update math module's readme

[x] Explicitly test equals and hashCode methods. (It is very important, since most of the tests rely on it)

[x] Re-read everything / Fix typos

[x] Add examples to the README section

[x] Add some test against expected values in order to make sure to detect bugs present in both KTX and LibGDX

[x] Fix documentation and address requested changes

Open questions and points to notice :

~~What name should we choose? I know I proposed it, but I don't like KVector, because the K means nothing, and certainly not "immutable". I think I'd prefer ImVector or ImmutableVector~~

Solution: We'll name them ImmutableVectorN and write in the doc that one can create typealiases for shorter names

~~Should the 3D vectors be part of this PR?~~

Solution: Vector 3D will be part of a separate PR

~~I intentionnaly chose to make angle() return values between -180 and 180 instead of between 0 and 360 like LibDGX does. I chose that to be consistent with angle(Vector2), angleRad() and angleRad(Vector2).~~

Update: We provide angleDeg functions and deprecate angle to make the difference in behavior clearer and less error-prone

Two tests are disabled while waiting the resolution of https://github.com/libgdx/libgdx/issues/5385

Most of the function got exact same name as their equivalent in Vector2. Exceptions to this rule are setter and functions which became Kotlin operators:

setLength and setLength2 became withLength and withLegnth2

setToRandomRotation became withRandomRotation

scl became the operator times: v * 3 or v1 * v2

unaryMinus is the equivalent of scl(-1f): -v == v * -1

add became the operator plus: v1 + v2

sub became the operator minus: v1 - v2

math
opened by jcornaz 25
Box2D utilities module
[x] Review gdx-box2d-kotlin code.

~~Migrate gdx-box2d-kotlin to ktx-box2d module.~~

[x] FixtureDef factory methods supporting different shapes.

[x] earthGravity property.

[x] World factory methods.

[x] Documentation listing all extensions. Usage examples.

[x] Provide an easy way to access built Fixture instances.

[x] Improve FixtureDef.filter API.

[x] Address FixtureDef.shape issue.

[x] Add userData properties to extended body and fixture definitions.

@Jkly
box2d
opened by czyzby 21
Preferences API extensions

Hi,

was working on preferences in my game and saw there is no nice kotlin extensions. I tried to come up with something but I was not sure how to solve get calls to avoid getInt, getString, etc..

Any ideas?

I will work on the documentation next week, if someone thinks this might be a useful addition. If not, feel free to delete this PR ;)
preferences

opened by Quillraven 19
DisposableRegistry
This is a tool I've been using lately to make it easy to keep track of all the Disposable instances stored in fields of a class so I won't miss disposing of them.

The way I use it is by instantiating a concrete implementation as a delegate. This exposes an .alsoRegister() extension function for Disposables so they can be registered right where you instantiate them. Then they are easy to dispose all together. Example:

class MyLoadScreen: Screen, DisposableRegistry by DisposableContainer() { private val batch = SpriteBatch().alsoRegister() private val logoTexture = Texture("myLogo.png", true).apply { setFilter(TextureFilter.Linear, TextureFilter.MipMapLinearLinear) alsoRegister() } //... override fun dispose() { disposeRegisteredSafely() } }

The reason for the interface is to allow you to use it as a delegate so you don't have to subclass it to get the extension functions for Disposable. But subclassing is still an option.

If this sounds like a good fit for Ktx, I can flesh this out with tests and documentation.
assets
opened by cypherdare 15
Adapters for Json.Serializer and Json.ReadOnlySerializer
I've noticed couple of things which could be a bit more kotlin-friendly when writing custom serializer. IDEA auto-implements all serializer paramters nullabe. And the knownType and type are of type Class<*>?. So, the auto-implemented serializer looks like this:

class MySerializer: Json.Serializer<MyClass> { override fun write(json: Json?, `object`: MyClass?, knownType: Class<*>?) { } override fun read(json: Json?, jsonData: JsonValue?, type: Class<*>?): MyClass { } }

I analyzed the sources of com.badlogic.gdx.utils.Json and noticed that only the last parameter of both methods may be null. In all the other cases the serializer is simply not called, so that we can omit ?. Additionally the object parameter could be renamed to something that does not reqire quotes. And Class<*>? could be converted to KClass<*>? (this one requires new method). Basically the adapter may look like this:

abstract class KtxSerializer<T> : Json.Serializer<T> { final override fun write(json: Json, obj: T, knownType: Class<*>?) { // the same for the read method write(json, obj, knownType?.kotlin) } abstract fun write(json: Json, obj: T, knownType: KClass<*>?) }

And the same can be done for com.badlogic.gdx.utils.Json.ReadOnlySerializer. But generally I think it does not make much sense if not the Class<*>, as we could simply omit the question marks and rename the parameter. But if changing the type of the type and knownType parameters then why not do the others. So, if that all makes sense, I can submit a PR. Though I'm not sure what to test here except the parameters that are passed to new methods (including conversion of Class to KClass).
json
opened by lowercase1024 14
Coroutines support
[x] Add ktx-async module.

[x] Implement coroutine context for LibGDX applications that executes tasks on the main rendering thread, using Gdx.app.postRunnable to resume coroutines executed on other threads.

[x] Implement utility functions for asynchronous tasks based on coroutines executed on a configurable AsyncExecutor instance.

[x] Add HttpRequest utilities based on coroutines.

[x] Simplify LibGDX Timer API. Currently it does not support lambdas.

[x] Add suspending delay method, which does not block the main rendering thread using LibGDX Timer.

[x] skipFrame suspending method that resumes on the next frame using Gdx.app.postRunnable API.

[x] Implement tasks cancellation.

[x] Documentation with usage examples.

Implement ktx-async module with asynchronous operations utilities and Kotlin 1.1 coroutines support.
async
opened by czyzby 14
Merging LibGDX utilities from Ore Infinium
[x] Common LibGDX interfaces adapters.

[x] Math extensions.

[x] ~~ktx-graphics?~~ Utilities for Batch and ShaderProgram in ktx-app.

i'm gonna find some time to push some of my helper functions from my game upwards into here so other people can benefit from my headaches.

some of them are rather useful, some of them are useless even for me ( experiments :wink: )

see here https://github.com/sreich/ore-infinium/blob/master/core/src/com/ore/infinium/util/LibgdxExtensions.kt

i also have artemis ones that would be useful(delegate system initters and some other things), but i'll push that to the backburner because i want to see where i go with those

mostly the interface ones of libgdx, but there's a few others that might be useful to someone other than my crazy self, we'll have to see

the interfaces exist because if you have to inherit from it or create an object of it, it's waaay easier. since libgdx doesn't use default interface java keyword, meaning you have to implement everything. it also gives guarantees on nullability which i found annoying for some of them (like Actor? but turns out it's never not null, so my kotlin wrappers give you that info back) and so on.

i'm sure i'll find ones in the future as i'm working and move them upwards where it makes sense.

there's also a couple in here https://github.com/sreich/ore-infinium/blob/master/core/src/com/ore/infinium/util/KotlinExtensions.kt (obvs ignore the ones that are clearly useless. mutableListOfNulls actually made it into stdlib in a form recently, i believe)

ones of interest are probably

interfaces

random.nextint(range) *shaderprogram.use {} *Texture.flipx, flipy ...

any thoughts? care to take a glance and call out ones you think others might find useful, or use my best judgement and give a PR awaiting feedback on it?
math app
opened by sreich 14

Adding ktx-vis to gradle dependencies breaks project

added to core/build.gradle api "io.github.libktx:ktx-vis:$ktxVersion"

stacktrace:

	at com.badlogic.gdx.backends.lwjgl3.Lwjgl3Application.<init>(Lwjgl3Application.java:120)
	at com.abysl.gdxcrawler.desktop.Lwjgl3Launcher.createApplication(Lwjgl3Launcher.kt:15)
	at com.abysl.gdxcrawler.desktop.Lwjgl3Launcher.main(Lwjgl3Launcher.kt:11)
Caused by: java.lang.AbstractMethodError: Receiver class com.badlogic.gdx.backends.lwjgl3.Lwjgl3GL20 does not define or inherit an implementation of the resolved method 'abstract java.lang.String glGetActiveAttrib(int, int, java.nio.IntBuffer, java.nio.IntBuffer)' of interface com.badlogic.gdx.graphics.GL20.
	at com.badlogic.gdx.graphics.glutils.ShaderProgram.fetchAttributes(ShaderProgram.java:841)
	at com.badlogic.gdx.graphics.glutils.ShaderProgram.<init>(ShaderProgram.java:169)
	at com.badlogic.gdx.graphics.g2d.SpriteBatch.createDefaultShader(SpriteBatch.java:162)
	at com.badlogic.gdx.graphics.g2d.SpriteBatch.<init>(SpriteBatch.java:126)
	at com.badlogic.gdx.graphics.g2d.SpriteBatch.<init>(SpriteBatch.java:80)
	at com.abysl.gdxcrawler.utils.GameRenderer.<init>(GameRenderer.kt:17)
	at com.abysl.gdxcrawler.screens.game.GameScreen.<init>(GameScreen.kt:28)
	at com.abysl.gdxcrawler.Game.create(Game.kt:18)
	at com.badlogic.gdx.backends.lwjgl3.Lwjgl3Window.initializeListener(Lwjgl3Window.java:433)
	at com.badlogic.gdx.backends.lwjgl3.Lwjgl3Window.update(Lwjgl3Window.java:381)
	at com.badlogic.gdx.backends.lwjgl3.Lwjgl3Application.loop(Lwjgl3Application.java:138)
	at com.badlogic.gdx.backends.lwjgl3.Lwjgl3Application.<init>(Lwjgl3Application.java:114)
	... 2 more
7:22:47 PM: Task execution finished 'run'.

bug vis

opened by abueide 13

#233 tile map extensions for libktx

First draft of the extensions that I am using in my projects. I had to generalize them a little bit and also tried to follow the kotlin "standard" with naming of some functions like e.g. "propertyOrNull".

Let me know what you think :)

Looking forward to your feedback!
tiled

opened by Quillraven 13

Additional library for FlexBox

I have recently implemented the FlexBox widget locally, maybe this could be added as future library?

gdx-flexbox

// my initial implementation
flexBox {
    label("Item 1") {
        setAlignment(Align.center)
    }.flex {
        setSize(100f)
    }
    label("Item 2") {
        setAlignment(Align.center)
    }.flex {
        setWidth(100f).setHeight(100f)
        positionType = YogaPositionType.ABSOLUTE
        setPosition(YogaEdge.LEFT, 10f)
    }
}
or 
flexBox {
    label("Item 1") {
        setAlignment(Align.center)
    }.flex(size = 100f)
    label("Item 2") {
        setAlignment(Align.center)
    }.flex(width = 100f, height = 100f, positionType  = YogaPositionType.ABSOLUTE, positionLeft = 10f)
}

extensions .flex could be implemented like .cell

scene2d

opened by ronjunevaldoz 5

[Feature Request] Asset Manager loader for Distance Field fonts
A loader for asset manager in the vein of what was done with ktx-freetype but for distance field fonts: https://github.com/libgdx/libgdx/wiki/Distance-field-fonts

A loader for this type of fonts might be desirable, I couldn't figure out how to integrate the loading method specified in the wiki with my asset manager setup.

Alternatively to that, I have used https://github.com/maltaisn/msdf-gdx to load msdf fonts seamlessly like this, because the library includes a loader and I just needed to load it onto the Asset Manager:

val assetManager = AssetManager() assetManager.setLoader(MsdfFontLoader(InternalFileHandleResolver())) enum class DistanceFieldFontAssets(val path: String) { DankMono32("skin/dank-mono-48-msdf.fnt"), } fun AssetManager.load(asset: DistanceFieldFontAssets) = load<MsdfFont>(asset.path) operator fun AssetManager.get(asset: DistanceFieldFontAssets) = getAsset<MsdfFont>(asset.path) DistanceFieldFontAssets.values().forEach { assetManager.load(it).finishLoading() }

I'm not sure about all the differences between the distance field fonts described on the libgdx wiki and the ones used by the msdf library, so I can't really say if using that library is sufficient to cover the use cases set forth by the libgdx wiki.
assets help wanted
opened by rubybrowncoat 1
Add README files to Dokka documentation

Dokka supposedly allows to add markdown files to the generated documentation pages. This would improve the quality of the documentation website. README files contain many relative links though, so this might require some additional investigation.
dev

opened by czyzby 0
Add TypingLabel extension module
[ ] Create a new KTX module that extends ktx-scene2d.

[ ] Include and document another major dependency: com.rafaskoberg.gdx:typing-label.

[ ] Add and test factory method for TypingLabel.

[ ] Add utility extension methods that register event listeners.

[ ] Add support for multiple TypingListener instances.

[ ] Consider adding custom DSL for TypingLabel tokens.

TypingLabel is an interesting third-party extension that defines additional Scene2D actor: a label that appears to be typed in real time. It supports a wide range of special effects. It would be a nice addition to our Scene2D extensions.

scene2d help wanted
opened by czyzby 0
Provide equal set of utilities for LibGDX collections
LibGDX defines a number of specialized collections that limit garbage collection and store primitives more efficiently. Unfortunately, none of them implement a common interface, including official Java collection interfaces. This makes it difficult to add utilities, as most extension methods have to be rewritten for each collection separately.

We currently support most commonly used LibGDX collections - such as Array, ObjectSet and ObjectMap - but the utilities for the rest of the collections are minimal. See #176 as an example.

The goal of this task is to prepare an automated or semi-automated way of adding utilities for LibGDX collections. This includes:

Type alias, if the name of the collection clashes with default Kotlin types (e.g. Array -> GdxArray).

Factory methods (e.g. gdxArrayOf).

get & set ([]), +, -, += and -= operators.

lastIndex property (if applicable).

Missing commonly used methods (e.g. addAll, removeAll).

Conversion methods from common collection types (e.g. Array.toGdxArray, Iterable.toGdxArray).

This can be implemented in form of a Gradle task that generates a basic utilities file and associated test file depending on the settings. It would be ideal if the generated code required no changes, but some manual corrections and additions are acceptable.
collections
opened by czyzby 0
AssetStorage API extensions
[x] Progress tracking.

Either as a built-in feature of the AssetStorage (internal counters of scheduled, loaded and failed assets) or an external class that allows to list all assets up front and updates itself via callbacks.

[x] PolygonRegion loading support.

PolygonRegion is a niche asset type loaded by PolygonRegionLoader. The loader does work with AssetStorage out of the box, as it calls AssetManager operations that are unsupported by the storage. Extending the loader and slightly modifying its behavior allows to support this asset type.

[ ] Aliases.

It could be quite useful to make it possible to add aliases for asset identifiers. E.g. a texture could be loaded with its original "images/sprites/plane.png" path, but it could be referred to as "plane" throughout the application. Dynamically changing what aliases point to could also make it easy to create applications with multiple themes. For example, "skin" could point to completely different UI assets depending on the application config - changing the alias and reloading a view would be all it takes to change the theme.

[ ] JSON assets loading.

Initial version of the AssetStorage supported asynchronous loading and deserialization of JSON files. This feature was stripped during the latest release, as even the basic asset loading functionalities of AssetStorage turned out to be quite a bit of work (#258). The existing code can be adapted to the latest version of the storage along with its tests, as it's quite useful for loading game configuration, game data, etc.

[ ] Built-in TMX map loaders.

LibGDX provides AtlasTmxMapLoader and TmxMapLoader for TMX map loading. Neither of these is registered by default in AssetManager (nor AssetStorage). We could investigate why the loaders are not included by default, and if there is a way to set sensible defaults for TMX map loading in terms of loaders setup in AssetStorage.

[ ] Better support for cancelling.

This is a long shot, as I'm not sure if it can be done without public API changes, but we could introduce better support for cancelling of loading coroutines. Note that this already possible - cancelling of coroutines would have a similar effect to unloading an asset concurrently, as the current loading code already handles such case and will interrupt loading process if it detects that the Deferred was already completed exceptionally.

Use this issue if you'd like to make a feature request regarding AssetStorage or review the current API of ktx-assets-async.

See #182 and #258.
assets async
opened by czyzby 0

Releases(1.11.0-rc3)

1.11.0-rc3(Dec 2, 2022)
The first stable release to support a new KTX module: ktx-artemis.

[UPDATE] Updated to Kotlin 1.7.22.

[UPDATE] Updated to Dokka 1.7.20.

[FEATURE] (ktx-ashley) Added tagFor<Component> utility functions that automatically create a mapper for a flag component. These properties can be used to check for Component presence within the Entity, as well as automatically add and remove Component instances upon property modification.

[FEATURE] (ktx-artemis) new KTX module with Artemis-odb entity component system utilities: ktx-artemis.

ArchetypeBuilder.add and ArchetypeBuilder.remove extension methods for adding and removing components from an ArchetypeBuilder.

oneOf, allOf, exclude DSL and extension methods for Aspect.Builder.

EntityEdit.plusAssign operator function for adding components.

EntityEdit.with builder function for adding components to an entity.

EntityEdit.remove extension function for removing components from an entity.

EntityTransmuterFactory.add and EntityTransmuterFactory.remove extension functions for adding and removing components from an EntityTransmuterFactory.

ComponentMapper.contains operator function to check if an entity has a component.

World.edit extension builder function to edit an entity.

World.entity extension builder function to create and edit an entity.

World.get operator function for retrieving a system which returns null if it doesn't exist.

World.getSystem extension function for retrieving a system which throws an exception if it doesn't exist.

World.mapperFor extension function for retrieving a ComponentMapper instance.

[FEATURE] (ktx-assets-async) AssetStorage now stores a basic path-to-type map, which allows it to support more AssetManager methods called by some AssetLoader implementations. These include:

AssetManager.contains(String)

AssetManager.get(String)

AssetManager.get(String, Boolean)

AssetManager.get(String, Class, Boolean)

AssetManager.getAssetType(String)

AssetManager.isLoaded(String)

AssetManager.unload(String)

AssetManager.getDependencies(String)

AssetManager.getReferenceCount(String)

Source code(tar.gz)
Source code(zip)
1.11.0-rc3.zip(8.90 MB)
1.11.0-rc2(Jul 28, 2022)
Maintenance release with support for Kotlin 1.7 and Dokka 1.7, as well as several new utilities.

[UPDATE] Updated to Kotlin 1.7.10.

[UPDATE] Updated to Kotlin Coroutines 1.6.4.

[UPDATE] Updated to Dokka 1.7.10.

[MISC] New Dokka theme is available on the documentation website.

[FEATURE] (ktx-actors) Added Actor.onEnter, Actor.onExit, Actor.onEnterEvent and Actor.onExitEvent extension methods that attach ClickListener instances listening for enter and exit events.

[FEATURE] (ktx-ashley) Added ComponentDelegate and OptionalComponentDelegate that allow accessing component via Entity extension properties.

[FEATURE] (ktx-ashley) Added propertyFor<Component> and optionalPropertyFor<Component> utility functions that automatically create a mapper for the component delegates.

Source code(tar.gz)
Source code(zip)
1.11.0-rc2.zip(8.07 MB)
1.11.0-rc1(May 22, 2022)
The first stable release to support libGDX 1.11.0.

[UPDATE] Updated to libGDX 1.11.0.

[MISC] Gradle dependencies changed from compile-only to API scope.

[FEATURE] (ktx-app) Added gdxError utility that throws a GdxRuntimeException.

[FIX] (ktx-assets-async) Fixed a niche bug with AsyncAssetManager which could lead to missed custom user callbacks after attempting to load the same asset concurrently with loadAsync.

Source code(tar.gz)
Source code(zip)
1.11.0-rc1.zip(7.37 MB)
1.10.0-rc2(Apr 24, 2022)
A maintenance release with notable changes to the ktx-ashley and ktx-script modules.

[UPDATE] Updated to Kotlin 1.6.21.

[UPDATE] Updated to Kotlin Coroutines 1.6.1.

[FEATURE] (ktx-ashley) Added utilities for working with Ashley's EntityListener interface:

EntityAdditionListener: an interface extending EntityListener that only requires implementation of the entityAdded method.

EntityRemovalListener: an interface extending EntityListener that only requires implementation of the entityRemoved method.

Engine.onEntityAdded and Engine.onEntityRemoved extension methods that create entity listeners from lambdas.

Wrappers for Engine.onEntityAdded and Engine.onEntityRemoved for IteratingSystem, IntervalIteratingSystem and SortedIteratingSystem that use system's Family and Engine automatically.

[FEATURE] (ktx-script) Added KotlinScriptEngine.evaluateOn methods that can execute scripts with a custom receiver.

[CHANGE] (ktx-script) Generic libGDX and Java exceptions replaced with a custom ScriptEngineException.

Source code(tar.gz)
Source code(zip)
1.10.0-rc2.zip(7.36 MB)
1.10.0-rc1(Jan 19, 2022)
The first release to support a new KTX module: ktx-script with a Kotlin scripting engine.

Note that the KTX stable versions will have a -rc suffix instead of -b from now on.

[UPDATE] Updated to Kotlin 1.6.10.

[UPDATE] Updated to Kotlin Coroutines 1.6.0.

[MISC] Links to the libGDX wiki were updated.

[MISC] Stable KTX releases are now marked with the -rc suffix.

[FEATURE] (ktx-actors) Added Tree.onSelectionChange extension method that attaches a ChangeListener to a Tree.

[CHANGE] (ktx-scene2d) The generic Node type of KTreeWidget was changed to KNode<*>.

[FEATURE] (ktx-script) Added a new module with KotlinScriptEngine evaluating Kotlin scripts in runtime.

evaluate(String): compiles and executes a script passed as a string.

evaluate(FileHandle): compiles and executes a script from the selected file.

evaluateAs<T>(String): compiles and executes a script passed as a string. Casts the result to T.

evaluateAs<T>(FileHandle): compiles and executes a script from the selected file. Casts the result to T.

set(String, Any): adds a variable to the script execution context.

get(String): returns the current value assigned to the selected variable.

remove(String): removes the variable registered under the given name.

import(String, String?): adds an import to the script context. Accepts optional alias.

importAll(vararg String), importAll(Iterable<String>): adds the selected imports to the script context.

setPackage(String): sets the package for the scripts.

[CHANGE] (ktx-vis) The generic Node type of KVisTree was changed to KNode<*>.

Source code(tar.gz)
Source code(zip)
1.10.0-rc1.zip(7.34 MB)
1.10.0-b4(Oct 12, 2021)
A maintenance release with minor API changes in ktx-scene2d and ktx-collections, as well as new features in ktx-app, ktx-ashley, ktxc-collections, and ktx-freetype-async. Includes new utilities for platform-specific code in ktx-app.

[UPDATE] Updated to Gradle 7.2.

[UPDATE] Updated to Dokka 1.5.30.

[FEATURE] (ktx-app) Added Platform object that exposes various utilities for platform-specific code.

Platform.currentPlatform returns current ApplicationType or throws GdxRuntimeException if unable to determine.

Platform.version returns the current version of the platform (e.g., Android API version, iOS major OS version).

Boolean properties that allow to determine current platform:

Platform.isAndroid checks if the current platform is Android.

Platform.isDesktop checks if the current platform is desktop with graphical application.

Platform.isHeadless checks if the current platform is desktop without graphical application.

Platform.isiOS checks if the current platform is iOS.

Platform.isMobile checks if the current platform is Android or iOS.

Platform.isWeb checks if the current platform is HTML/WebGL.

Inlined methods that allow to execute code on specific platforms:

Platform.runOnAndroid executes an action if the current platform is Android. Returns action result or null.

Platform.runOnDesktop executes an action if the current platform is desktop. Returns action result or null.

Platform.runOnHeadless executes an action if the current platform is headless desktop. Returns action result or null.

Platform.runOniOS executes an action if the current platform is iOS. Returns action result or null.

Platform.runOnMobile executes an action if the current platform is Android or iOS. Returns action result or null.

Platform.runOnWeb executes an action if the current platform is HTML/WebGL. Returns action result or null.

Inlined runOnVersion executes an action if the current platform version is within minimum and maximum values.

[FEATURE] (ktx-ashley) Mapper abstract class designed for companion objects of Components. Allows to easily obtain instances of a ComponentMapper corresponding to the enclosing Component class.

[FEATURE] (ktx-assets-async) AssetStorage.loadSync(String) now supports optional loading parameters.

[FEATURE] (ktx-collections) isEmpty and isNotEmpty extension methods of libGDX collections now support Kotlin contracts. If they return true, the collection is implied not to be null.

[CHANGE] (ktx-collections) As IdentityMap now extends ObjectMap, some redundant utilities specific to IdentityMap were removed. From the user point of view, all additional functionalities are covered by the ObjectMap utilities.

[FEATURE] (ktx-freetype-async) AssetStorage.loadFreeTypeFontAsync was added, mimicking loadAsync behavior.

[FEATURE] (ktx-freetype-async) AssetStorage.loadFreeTypeFontSync was added, mimicking loadSync behavior.

[FEATURE] (ktx-freetype-async) AsyncAssetManager.loadFreeTypeFontAsync was added, returning a Deferred<BitmapFont> instance.

[CHANGE] (ktx-scene2d) Scene2DSkin.defaultSkin now throws IllegalStateException when accessed before overriding.

Source code(tar.gz)
Source code(zip)
1.10.0-b4.zip(7.13 MB)
1.10.0-b3(Sep 30, 2021)
The first release to include the ktx-reflect module with new reflection utilities. Includes notable new features in ktx-collections, ktx-inject, and ktx-assets-async.

[UPDATE] Updated to Kotlin 1.5.31.

[UPDATE] Updated to Kotlin Coroutines 1.5.2.

[FEATURE] (ktx-assets-async) AssetStorage now supports loading PolygonRegion assets out of the box if the default loaders are registered.

[FEATURE] (ktx-assets-async) AsyncAssetManager is a new AssetManager extension with basic support for Kotlin coroutines.

AsyncAssetManager.loadAsync allows to schedule an asset for loading, returning a Deferred asset reference.

AsyncAssetManager.getDefaultParameters allows to create a default instance of AssetLoaderParameters for a selected asset.

AsyncAssetManager.setLoaderParameterSupplier has to be called for each custom asset loader in order to enable asynchronous loading without explicitly passing loader parameters.

[FEATURE] (ktx-collections) Factory methods for LibGDX arrays of primitives:

gdxBooleanArrayOf

gdxByteArrayOf

gdxCharArrayOf

gdxShortArrayOf

gdxIntArrayOf

gdxLongArrayOf

gdxFloatArrayOf

[FEATURE] (ktx-inject) New reflection-based Context methods with automatic dependency injection:

newInstanceOf: constructs an instance of the selected class. Injects constructor dependencies from the Context.

bind<Type>: registers a provider that creates a new instance of selected class via reflection each time it is requested.

bindSingleton<Type>: creates, registers, and returns a singleton of selected class using reflection.

[FEATURE] (ktx-reflect) Added a new module with reflection utilities.

Reflection annotation, which requires opt-in, allows marking functionalities that rely on reflection.

ReflectedClass is an inlined wrapper for Class that allows to easily use LibGDX reflection API.

ClassReflection methods exposed as ReflectedClass read-only properties:

simpleName

isMemberClass

isStatic

isArray

isPrimitive

isEnum

isAnnotation

isInterface

isAbstract

componentType

constructors

methods

declaredMethods

fields

declaredFields

annotations

declaredAnnotations

interfaces

enumConstants

ClassReflection methods exposed as ReflectedClass methods with improved Kotlin class handling:

isInstance

isAssignableFrom

newInstance

getConstructor

getDeclaredConstructor

getMethod

getDeclaredMethod

getField

getDeclaredField

isAnnotationPresent

getAnnotation

getDeclaredAnnotation

Additional ReflectedClass utilities:

constructor property allows to extract the only class constructor if it is available.

newArrayInstance method allows to create a type array of the given size using ArrayReflection.

KClass constructor allows creating ReflectedClass from a KClass.

reflect<Type>() function allows to wrap a selected class with ReflectedClass.

reflect(KClass<Type>) function allows to wrap a selected KClass with ReflectedClass.

reflect(Class<Type>) function allows to wrap a selected Class with ReflectedClass.

reflect(String) function allows to find a selected class by qualified name and wrap it with ReflectedClass.

Annotation.get extension method with a reified type allowing to get an instance of the annotation.

Source code(tar.gz)
Source code(zip)
1.10.0-b3.zip(7.04 MB)
1.10.0-b2(Aug 4, 2021)
A maintenance release with improved support for the new LibGDX 1.10.0 features. Includes a minor refactoring of the ktx-log module.

[UPDATE] Updated to Gradle 7.0.2.

[UPDATE] Updated to Kotlin 1.5.21.

[UPDATE] Updated to Kotlin Coroutines 1.5.1.

[UPDATE] Updated to VisUI 1.5.0.

[CHANGE] The JVM target compatibility of all modules was set to 1.8, since Java 1.6 target was deprecated and is incompatible with the latest coroutines library. Note that source compatibility level is still set to 1.7.

[FEATURE] (ktx-assets) Added discard lambda parameter to the pool factory method that is invoked after an object is rejected from the created Pool.

[FEATURE] (ktx-scene2d) Added support for ParticleEffectActor in Scene2D DSL via particleEffect factory method.

[FEATURE] (ktx-log) Added DEBUG, INFO and ERROR constants with default logger tags.

[CHANGE] (ktx-log) Default tags are no longer wrapped in square brackets. This caused a change of the logs structure.

[CHANGE] (ktx-log) Logger.tag variable was renamed to Logger.name.

[CHANGE] (ktx-log) Log prefix variables from Logger were removed. Message tags are now configurable directly through the constructor.

[CHANGE] (ktx-log) Logger name is no longer a part of the message tag. Instead, it is now prepended to the message. This causes a change of the logs structure.

[FEATURE] (ktx-log) Added Logger.buildMessage method that allows to modify logged message structure. This method can be overridden when extending the Logger class, simplifying the usage of custom message formats.

Source code(tar.gz)
Source code(zip)
1.10.0-b2.zip(6.72 MB)
1.10.0-b1(Apr 19, 2021)
Maintenance release with support for LibGDX 1.10.0.

[UPDATE] Updated to LibGDX 1.10.0.

[CHANGE] The Java source compatibility and JVM target version of the KTX modules was changed from 1.6 to 1.7.

Source code(tar.gz)
Source code(zip)
1.10.0-b1.zip(6.70 MB)
1.9.14-b2(Apr 12, 2021)
A maintenance release with notable dependency updates and a minor VisUI module bug fix.

[UPDATE] Updated to Ashley 1.7.4.

[UPDATE] Updated to Kotlin 1.4.32.

[UPDATE] Updated to Kotlin Coroutines 1.4.3.

[UPDATE] Updated to Gradle 6.8.3.

[UPDATE] Updated to Dokka 1.4.30.

[MISC] Due to the newly added support for multimodule projects in Dokka, published documentation URLs will change.

[FEATURE] (ktx-tiled) Added isEmpty and isNotEmpty extension function for MapLayers and MapObjects collections.

[FEATURE] (ktx-tiled) Added forEachLayer extension function for TiledMap to iterate over an exact type of MapLayer instances of a specific map.

[FIX] (ktx-vis) visScrollPane and visSplitPane now define the correct types for this in the init lambdas, adding support for Scene2D and VisUI DSL.

Source code(tar.gz)
Source code(zip)
1.9.14-b2.zip(6.70 MB)
1.9.14-b1(Feb 23, 2021)
The first release to support LibGDX 1.9.14. Includes notable debugging extension for ktx-assets-async.

[UPDATE] Updated to LibGDX 1.9.14.

[UPDATE] Updated to Kotlin 1.4.30.

[UPDATE] Updated to VisUI 1.4.11.

[FEATURE] (ktx-app) clearScreen now accepts additional clearDepth boolean parameter that controls whether the GL_DEPTH_BUFFER_BIT is added to the mask.

[FEATURE] (ktx-assets-async) Added AssetStorageSnapshot class that stores a copy of AssetStorage state for debugging purposes. Supports formatted string output with prettyFormat.

[FEATURE] (ktx-assets-async) AssetStorage now includes takeSnapshot and takeSnapshotAsync methods that allow to copy and inspect the internal state of the storage for debugging purposes.

[FEATURE] (ktx-collections) Added getOrPut extension function for LibGDX map collections including ObjectMap, IdentityMap, ArrayMap and IntMap.

Source code(tar.gz)
Source code(zip)
1.9.14-b1.zip(8.65 MB)
1.9.13-b1(Jan 5, 2021)
The first release to support LibGDX 1.9.13. Maintenance release with some notable dependencies updates.

[UPDATE] Updated to LibGDX 1.9.13.

[UPDATE] Updated to Kotlin 1.4.21-2.

[UPDATE] Updated to VisUI 1.4.8.

[FEATURE] (ktx-style) Added Skin.register extension method that allows to register widget styles with the DSL.

[FEATURE] (ktx-vis) Added flowGroup factory method that allows to construct FlowGroup actors.

[CHANGE] (ktx-vis) horizontalFlowGroup and verticalFlowGroup are now deprecated. Use flowGroup instead.

Source code(tar.gz)
Source code(zip)
1.9.13-b1.zip(8.59 MB)
1.9.12-b1(Dec 1, 2020)
The first KTX release with support for LibGDX 1.9.2.

[UPDATE] Updated to LibGDX 1.9.12.

[UPDATE] Updated to Kotlin 1.4.20.

[UPDATE] Updated to Kotlin Coroutines 1.4.2.

Source code(tar.gz)
Source code(zip)
1.9.12-b1.zip(8.56 MB)
1.9.11-b2(Nov 1, 2020)
A release that features relatively minor additions, but major changes in terms of internal project architecture and documentation generation. The project was updated to the latest Gradle version with Kotlin DSL, and the latest Dokka version with an overhauled auto generated UI.

[UPDATE] Updated to Kotlin 1.4.10.

[UPDATE] Updated to Kotlin Coroutines 1.4.0.

[UPDATE] Updated to Gradle 6.7.

[UPDATE] Updated to Dokka 1.4.10-2.

[MISC] Groovy Gradle scripts and configuration files migrated to Kotlin.

[MISC] The generated sources documentation is vastly improved and moved to a new URL.

[FEATURE] (ktx-collections) Added GdxIdentityMap and GdxArrayMap aliases for LibGDX IdentityMap and ArrayMap collections.

[FEATURE] (ktx-collections) Added set operator extension method to ArrayMap to support square brackets assignment.

[FEATURE] (ktx-graphics) Added optional Camera and projection matrix parameters to ShapeRenderer.use.

[FEATURE] (ktx-scene2d) Added image builders for NinePatch, TextureRegion, Texture and Drawable.

Source code(tar.gz)
Source code(zip)
1.9.11-b2.zip(8.59 MB)
1.9.11-b1(Jul 30, 2020)
The first release to officially support LibGDX 1.9.11. No major changes otherwise.

[UPDATE] Updated to LibGDX 1.9.11.

[UPDATE] Updated to Kotlin Coroutines 1.3.6.

[UPDATE] Updated VisUI to 1.4.6.

[FEATURE] (ktx-scene2d) Added a generic container factory method that supports adding a custom actor.

Source code(tar.gz)
Source code(zip)
1.9.11-b1.zip(1.74 MB)
1.9.10-b7(Jul 28, 2020)
The last release to officially support LibGDX 1.9.10. A few deprecated functionalities were removed.

[MISC] Added ktlint formatting. Contributors are asked to run format Gradle task before committing files.

[CHANGE] (ktx-actors) Deprecated Action.parallelTo and ParallelAction.parallelTo extension methods were removed. Use along instead.

[CHANGE] (ktx-actors) Touch event listeners attached with extension methods now extend InputListener rather than ClickListener.

[CHANGE] (ktx-actors) onTouchEvent parameters renamed from downListener and upListener to onDown and onUp.

[CHANGE] (ktx-actors) Event listeners attached with extension methods now consume the Actor as this. Listeners that used to consume actors as regular parameters now should rely on this instead.

[FEATURE] (ktx-actors) KtxApplicationAdapter, KtxGame and KtxScreen now explicitly implement the Disposable interface, matching the dispose method from ApplicationListener and Screen respectively. This allows to leverage existing Disposable utilities.

[FEATURE] (ktx-ashley) Added Engine.configureEntity extension method that allows to add components to an existing entity.

[FEATURE] (ktx-assets) Added DisposableRegistry and DisposableContainer for management of multiple Disposable instances.

[FEATURE] (ktx-graphics) Added support for Color destructuring syntax.

[CHANGE] (ktx-scene2d) Deprecated top-level widget factory methods and tooltip utilities were removed.

Source code(tar.gz)
Source code(zip)
1.9.10-b7.zip(1.74 MB)
1.9.10-b6(Apr 25, 2020)
A major release with breaking changes in ktx-scene2d, a rewrite of ktx-vis, removal of Javadocs generation, Kotlin contracts support and refactoring of operator extensions to conform to Kotlin guidelines.

[UPDATE] Updated to Kotlin 1.3.72.

[UPDATE] Updated to Dokka 0.10.1.

[CHANGE] Javadocs are no longer generated with Dokka. Since KTX focuses solely on Kotlin support for LibGDX, usability from Java is not a priority. The generated Javadocs are not very helpful, especially for Kotlin development. Instead, the Javadoc jar published to Maven Central now contains exported Kotlin-compatible Dokka documentation. Starting from this release, GitHub releases will no longer contain the Javadoc archives.

[FEATURE] (ktx-actors) Added Action.repeat extension method that allows to repeat an action for the given amount of times.

[FEATURE] (ktx-ashley) Added Engine.get operator to access a chosen EntitySystem.

[FEATURE] (ktx-ashley) Added Engine.getSystem extension method to access a chosen EntitySystem. Throws MissingEntitySystemException in case the system is not added.

[FEATURE] (ktx-ashley) Added Entity.addComponent extension method to create a Component for an existing Entity.

[FEATURE] (ktx-ashley) Added Entity.plusAssign (+=) operator that allows to add an Component to an Entity.

[FEATURE] (ktx-ashley) Added contracts support to EngineEntity.with, Engine.create, Engine.add, Engine.entity add Entity.addComponent. Now their lambda parameters are ensured to be executed exactly once:

// Before: lateinit var value: Int engine.add { value = 42 } // Now: val value: Int engine.add { value = 42 }

[FEATURE] (ktx-assets) Iterable.dispose and Array.dispose extension methods consuming an error handler are now inlined.

[FEATURE] (ktx-box2d) Added contracts support to body, fixture and joint factory methods, as well as FixtureDef.filter. This ensures that the configuration lambdas are executed exactly once.

[CHANGE] (ktx-collections) PooledList was removed due to concurrent iteration safety issues. Use standard library lists instead.

[CHANGE] (ktx-collections) - and + operators no longer mutate the collections. Instead, they create a new collection instance and add or removed the selected elements. To modify an existing collection, use new mutating += and -= operators.

[FEATURE] (ktx-freetype) Added contracts support to AssetManager.loadFreeTypeFont, freeTypeFontParameters and FreeTypeFontGenerator.generateFont. This ensures that the font configuration lambdas are executed exactly once.

[FEATURE] (ktx-freetype-async) Added contracts support to AssetStorage.loadFreeTypeFont.

[FEATURE] (ktx-graphics) Added contracts support to Camera.update, Batch.use, ShaderProgram.use, GLFrameBuffer.use and ShapeRenderer.use.

[FEATURE] (ktx-inject) Added contracts support to Context.register.

[CHANGE] (ktx-log) Added contracts to logging methods. Logging methods now might need to be imported explicitly.

[FEATURE] (ktx-preferences) Added contracts support to Preferences.flush.

[FEATURE] (ktx-math) Added +=, +, -= and - operators supporting floats and ints to Vector2 and Vector3.

[CHANGE] (ktx-math) -, !, ++ and -- operators no longer mutate vectors and matrices, returning new instances instead.

[FIX] (ktx-math) Operators documentation regarding mutating of vectors and matrices was updated.

[FEATURE] (ktx-scene2d) scene2d object was added. It supports the entire Scene2D DSL and allows to create root-level widgets.

[FEATURE] (ktx-scene2d) Stage.actors extension method was added. It allows to define actors with Scene2D DSL and adds all top-level actors to the Stage.

[CHANGE] (ktx-scene2d) Root-level actor function was deprecated.

[CHANGE] (ktx-scene2d) Root-level widget factory functions were deprecated. Use scene2d. prefix or Stage.actors to create these widgets. Note that the actors can still be created via standard DSL. See the migration guide in README. This includes:

stack

horizontalGroup

verticalGroup

container

splitPane

scrollPane

table

window

dialog

buttonGroup

tree

[CHANGE] (ktx-scene2d) listWidget and selectBox now have a single generic type to improve usability. Their building blocks no longer consume Cell and Node instances.

[CHANGE] (ktx-scene2d) Internal KWidget.appendActor and KGroup.add methods were removed.

[FEATURE] (ktx-scene2d) Added contracts support to widget factory methods and Stage.actors. This ensures that widget configuration lambdas are executed exactly once.

[FEATURE] (ktx-style) Added contracts support to style factory methods and top-level skin functions.

[CHANGE] (ktx-vis) Overhaul of the module.

ktx-vis now includes and extends the ktx-scene2d module. The majority of APIs are now shared.

All factory methods for VisUI widgets are now inlined, which can improve the performance of GUI building.

Factory methods of some VisUI widgets were renamed to avoid clashes with Scene2D methods and better reflect the wrapped widget class names:

label: visLabel

image: visImage

list: visList, visListOf

selectBox: visSelectBox, visSelectBoxOf

slider: visSlider

textArea: visTextArea

textField: visTextField

validatableTextField: visValidatableTextField

textButton: visTextButton

imageButton: visImageButton

imageTextButton: visImageTextButton

radioButton: visRadioButton

tree: visTree

table: visTable

scrollPane: visScrollPane

splitPane: visSplitPane

addTooltip: visTooltip

addTextTooltip: visTextTooltip

Parental actors including collapsible, dragPane, horizontalCollapsible, visScrollPane, visSplitPane and multiSplitPane now do not require passing widgets to their factory methods. Instead, widgets are either automatically created or can be defined as nested children with the same DSL.

Inlined functions with lambda parameters, such as widget factories with their building block lambdas, now use Kotlin contracts to ensure that they are executed exactly once.

DEFAULT_STYLE constant is removed in favor of defaultStyle from ktx-scene2d.

styleName parameters in factory methods were renamed to style for consistency with ktx-scene2d.

@VisDsl DSL marker is replaced with @Scene2dDsl marker from ktx-scene2d.

The sources documentation was greatly expanded.

[FEATURE] (ktx-vis-style) Added contracts support to widget style factory methods.

Known issues:

[BUG] (ktx-box2d) Due to a Kotlin compiler bug, methods with vararg parameters do not support contracts. This includes some polygon, chain and loop factory methods. See this issue. They can still be used and work as expected, but the compiler does not ensure that their lambda parameters are executed exactly once.

Source code(tar.gz)
Source code(zip)
1.9.10-b6.zip(1.89 MB)
1.9.10-b5(Apr 10, 2020)
This major release contains 2 new KTX modules: ktx-preferences with utilities for application preferences and ktx-assets-async with an asset manager based on Kotlin coroutines. ktx-freetype-async is also no longer disabled and now it can be used along with the ktx-assets-async to load FreeType fonts asynchronously.

ktx-assets-async comes with a complete rewrite of AssetStorage that used to be available in a limited form in a few older versions of ktx-async. Updated to the new coroutines API, AssetStorage can now be used as a more performant and Kotlin-idiomatic alternative to AssetManager from LibGDX.

[UPDATE] Updated to Kotlin 1.3.71.

[UPDATE] Updated to Kotlin Coroutines 1.3.5.

[UPDATE] Updated to Gradle 5.6.4.

[FEATURE] (ktx-app) Added profiling utilities.

profile inlined function allows to profile an operation with the LibGDX PerformanceCounter.

PerformanceCounter.profile inlined extension method eases usage of PerformanceCounter API.

PerformanceCounter.prettyPrint allows to print basic performance data after profiling.

[CHANGE] (ktx-app) LetterboxingViewport moved from ktx-app to ktx-graphics.

[FEATURE] (ktx-ashley) Added Entity.contains (in operator) that checks if an Entity has a Component.

[FEATURE] (ktx-assets-async) Added a new KTX module: coroutines-based asset loading.

AssetStorage is a non-blocking coroutines-based alternative to LibGDX AssetManager.

get operator obtains an asset from the storage or throws a MissingAssetException.

getOrNull obtains an asset from the storage or return null if the asset is unavailable.

getAsync obtains a reference to the asset from the storage as Deferred.

load suspends a coroutine until an asset is loaded and returns its instance.

loadAsync schedules asynchronous loading of an asset.

loadSync blocks the thread until selected asset is loaded.

unload schedules asynchronous unloading of an asset.

add allows to manually add a loaded asset to AssetManager.

dispose unloads all assets from the storage.

getLoader and setLoader manage AssetLoader instances used to load assets.

isLoaded checks if loading of an asset was finished.

contains operator checks if the asset was scheduled for loading or added to the storage.

progress allows to check asset loading progress.

getReferenceCount returns how many times the asset was loaded or referenced by other assets as a dependency.

getDependencies returns a list of dependencies of the selected asset.

getAssetDescriptor creates an AssetDescriptor with loading data for the selected asset.

getIdentifier creates an Identifier uniquely pointing to an asset of selected type and file path.

Identifier data class added as an utility to uniquely identify assets by their type and path.

Identifier.toAssetDescriptor allows to convert an Identifier to an AssetDescriptor.

AssetDescriptor.toIdentifier allows to convert an AssetDescriptor to Identifier used to uniquely identify AssetStorage assets.

LoadingProgress is an internal class used by the AssetStorage to track loading progress.

[FEATURE] (ktx-async) Added RenderingScope factory function for custom scopes using rendering thread dispatcher.

[FEATURE] (ktx-async) newAsyncContext and newSingleThreadAsyncContext now support threadName parameter that allows to set thread name pattern of AsyncExecutor threads.

[FIX] (ktx-async) isOnRenderingThread now behaves consistently regardless of launching coroutine context.

[FEATURE] (ktx-freetype-async) This KTX module is now restored and updated to the new AssetStorage API. There are no public API changes since the last released version.

[FEATURE] (ktx-graphics) Added LetterboxingViewport from ktx-app.

[FEATURE] (ktx-graphics) Added takeScreenshot utility function that allows to save a screenshot of the application.

[FEATURE] (ktx-graphics) Added BitmapFont.center extension method that allows to center text on an object.

[FEATURE] (ktx-graphics) Added Camera utilities.

center extension method allows to center the camera's position to screen center or the center of the chosen rectangle.

moveTo extension method allows to move the camera immediately at the chosen target position with optional offset.

lerpTo extension method allows to move the camera smoothly to the chosen target position with optional offset.

update inlined extension method allows to change camera state with automatic Camera.update call.

[FEATURE] (ktx-math) Added lerp and interpolate extension functions for Float ranges.

[FEATURE] (ktx-preferences) Added a new KTX module: Preferences API extensions.

Added set operators for String, Int, Float, Double, Long, Boolean, Pair<String, Any> and Any

Added get operator which automatically determines preference type and retrieves them with the correct method.

get and set will automatically attempt to (de)serialize non-basic preferences to and from JSON.

set(String, Double) is deprecated, since the LibGDX Preferences do not support doubles.

Added flush inlined extension method that executes a lambda and automatically calls Preferences.flush.

[CHANGE] (ktx-scene2d) Improved typing support for Tree.Node widgets. Since LibGDX 1.9.10, Tree.Node is a generic class, but KTX KNode remained non-generic until now. Type of stored actors must now be specified for KNode variables, but thanks to that actors from KNode instances are now correctly typed and easier to handle. This required minor internal changes - KWidget.storeActor is now generic.

[FEATURE] (ktx-vis) Added image (VisImage) factory methods consuming Texture, TextureRegion and NinePatch.

Source code(tar.gz)
Source code(zip)
1.9.10-b5.zip(2.96 MB)
1.9.10-b4(Jan 24, 2020)
The first release to include a new KTX module with Tiled map editor utilities: ktx-tiled.

[FEATURE] (ktx-actors) Added onTouchDown, onTouchUp and onTouchEvent extension methods that allow to attach ClickListener instances to actors.

[CHANGE] (ktx-collections) Array.removeAll and retainAll now return a boolean if any elements were removed.

[CHANGE] (ktx-collections) Array.transfer is now less strict about typing.

[FEATURE] (ktx-math) Added Kotlin ranges extensions that simplify creating ranges and rolling random numbers:

Int.amid, Float.amid;

+, -, * and / for ranges;

ClosedRange<Float>.random, IntRange.random;

ClosedRange<Float>.randomGaussian;

ClosedRange<Float>.randomTriangular.

[FEATURE] (ktx-tiled) Added a new KTX module: Tiled API extensions.

Added contains (in) and set ([]) operators support to MapProperties.

Added extension methods that simplify properties extraction from MapLayer, MapObject, TiledMap, TiledMapTile and TiledMapTileSet:

property

propertyOrNull

containsProperty

Added shape extension field to MapObject.

Added extension fields that ease extraction of basic properties from TiledMap and MapObject.

Source code(tar.gz)
Source code(zip)
1.9.10-b4.zip(2.63 MB)
1.9.10-b3(Dec 22, 2019)
Includes multiple new utilities, major documentation improvements and some notable dependencies updates.

[UPDATE] Updated to Kotlin 1.3.61.

[UPDATE] Updated to Kotlin Coroutines 1.3.3.

[FEATURE] (ktx-assets) Added AssetGroup abstract class that allows to manage groups of assets.

[FEATURE] (ktx-collections) Added removeAll, retainAll and transfer extensions to LibGDX Array using lambda predicates to modify the array in-place.

[CHANGE] (ktx-collections) PooledList now implements MutableIterable.

[FEATURE] (ktx-graphics) Added Batch.begin extension methods that automatically set projection matrix from a Camera or Matrix4.

[FEATURE] (ktx-style) Added Skin extension methods with reified resource types: optional, add, remove, has and getAll.

[FEATURE] (ktx-style) The overloaded += operator can now be used to add "default" resources to Skin.

[FEATURE] (ktx-json) Added JsonSerializer and ReadOnlyJsonSerializer adapters to facilitate writing custom serializers.

[FEATURE] (ktx-json) Added readOnlySerializer() factory functions to simplify creation of ReadOnlyJsonSerializer.

Source code(tar.gz)
Source code(zip)
1.9.10-b3.zip(2.49 MB)
1.9.10-b2(Aug 30, 2019)
A maintenance release with notable dependencies updates and two bug fixes in ktx-actors and ktx-box2d.

[UPDATE] Updated to Kotlin 1.3.50.

[UPDATE] Updated to Kotlin Coroutines 1.3.0.

[UPDATE] Updated to Gradle 5.6.1.

[CHANGE] (ktx-actors) Action.parallelTo changed to Action.along.

[CHANGE] (ktx-actors) Action.along (formerly Action.parallelTo) and Action.then no longer unwrap the second action.

[CHANGE] (ktx-actors)ParallelAction.along (formerly ParallelAction.parallelTo) and SequenceAction.then simply add the second action to the group without unwrapping.

[FEATURE] (ktx-actors) Added / operator to Action, which performs the non-mutating version of along, wrapping the caller and argument in a new ParallelAction.

[CHANGE] (ktx-actors) ParallelAction.plus() and SequenceAction.plus() no longer unwrap their components.

[FIX] (ktx-actors) along, then, + and / Action extension methods now properly differentiate between SequenceAction and ParallelAction, taking their inheritance into account.

[CHANGE] (ktx-box2d) Added disposeOfShape parameters to fixture extension methods of Body and BodyDefinition. Setting these values to true will cause the fixture shapes to be immediately disposed of after Fixture construction.

[FIX] (ktx-box2d) Removed memory leak caused by undisposed shapes.

[FEATURE] (ktx-graphics) Batch.use extension methods now accept Matrix4 and Camera to update the batch's projection matrix before rendering.

Source code(tar.gz)
Source code(zip)
1.9.10-b2.zip(2.44 MB)
1.9.10-b1(Aug 17, 2019)
The first stable release to support LibGDX 1.9.10 and feature ktx-json - a new KTX module with utilities for LibGDX JSON serialization API.

[UPDATE] Updated LibGDX to 1.9.10.

[UPDATE] Updated to Kotlin 1.3.41.

[UPDATE] Updated to Kotlin Coroutines 1.3.0-RC2.

[UPDATE] Updated VisUI to 1.4.4.

[UPDATE] Updated to Gradle 5.5.1.

[CHANGE] (ktx-app) clearScreen now also clears depth buffer to support 3D applications.

[FEATURE] (ktx-json) Added a new KTX module with the goal of improving LibGDX Json API: ktx-json. The following extension methods were added to avoid passing Java class instances:

fromJson

addClassTag

getTag

setElementType

setSerializer

readValue

[FEATURE] (ktx-graphics) Added GLFrameBuffer.use to allow safe omission of the begin() and end() calls.

Known issues:

[BUG] (ktx-actor) Since SequenceAction extends ParallelAction in LibGDX 1.9.10, using parallelTo with a SequenceAction as the first argument leads to unexpected behaviour.

[BUG] (ktx-box2d) Since fixture shapes are not disposed of after fixture creation, all fixture factory methods can lead to minor memory leaks.

Source code(tar.gz)
Source code(zip)
1.9.10-b1.zip(2.43 MB)
1.9.9-b2(Jun 2, 2019)
Maintenance release with dependencies update and some additional utilities in ktx-style.

[UPDATE] Updated to Kotlin 1.3.31.

[UPDATE] Updated to Kotlin Coroutines 1.2.1.

[FEATURE] (ktx-assets) Added TextAssetLoader that can be registered in an AssetManager to load text files asynchronously.

[FEATURE] (ktx-style) Added Skin.get extension method that allows to pass enum instances as style names.

[CHANGE] (ktx-style) Skin.get extension method are no longer infix.

[CHANGE] (ktx-style) Skin.get now has accepts default parameter equal to the default style name.

Source code(tar.gz)
Source code(zip)
1.9.9-b2.zip(2.40 MB)
1.9.9-b1(Feb 5, 2019)
A major KTX release with some significant changes. Most notably:

ktx-async module was overhauled and now properly provides coroutines scope consistent the stable coroutines API.

AssetStorage and ktx-freetype-async were temporarily removed until they are refactored to the new ktx-async API.

ImmutableVector2 was added as an immutable alternative to the official Vector2.

[UPDATE] Updated LibGDX to 1.9.9.

[UPDATE] Updated to Kotlin 1.3.20.

[UPDATE] Updated to Kotlin Coroutines 1.1.1.

[UPDATE] Updated VisUI to 1.4.2.

[UPDATE] Updated to Gradle 5.0.

[CHANGE] (ktx-actors) Replaced Stage and Group extension operator methods plus and minus with plusAssign and minusAssign to avoid mutating the objects with addition and subtraction operators.

// Adding an actor to a Stage/Group - before: stage + actor group + actor // Now: stage += actor group += actor

[CHANGE] (ktx-actors) Replaced Stage and Actor extension operator methods plus and minus with plusAssign and minusAssign to avoid mutating the objects with addition and subtraction operators.

// Adding an action to a Stage/Actor - before: stage + action actor + action // Now: stage += action actor += action

[CHANGE] (ktx-actors) SequenceAction.then was removed. Using the method on a sequence no longer mutates it for consistency with Action.then. then now unwraps actors from passed SequenceActions.

[CHANGE] (ktx-actors) ParallelAction.parallelTo was removed. Using the method on a ParallelAction no longer mutates it for consistency with Action.parallelTo. parallelTo now unwraps actors from passed ParallelActions.

[CHANGE] (ktx-async) Overhaul of the ktx-async module.

KtxAsync is now the main coroutines scope that should be used instead of the GlobalScope.

Dispatchers.KTX can be used to access a coroutines dispatchers that executes tasks on the main rendering thread.

AsyncExecutorDispatcher can be used to wrap LibGDX AsyncExecutor to execute tasks asynchronously.

newSingleThreadAsyncContext allows to create an AsyncExecutorDispatcher with a single thread.

newAsyncContext allows to create an AsyncExecutorDispatcher with the given max amount of threads.

onRenderingThread suspends the coroutine to execute a task on the main rendering thread and return its result.

isOnRenderingThread allows to check whether the corouting is executed on the main rendering thread.

skipFrame attempts to suspend the coroutine for at least one rendering frame.

httpRequest allows to perform an asynchronous HTTP request.

schedule and interval functions simplify LibGDX Timer API usage.

AssetStorage and associated asset loading utilities were temporarily removed. They will be added to a separate module.

Asynchronous tests were significantly simplified.

Assume that other utilities were either removed or integrated with the listed utilities.

[CHANGE] (ktx-freetype-async) The module is temporarily disabled due to the removal of AssetStorage.

[FEATURE] (ktx-actors) Added + operator to create sequence of actions (an alternative syntax to then).

[FEATURE] (ktx-actors) Added += operators to SequenceAction and ParallelAction to ease adding new actions to these action groups.

[FEATURE] (ktx-actors) Added stage factory method that uses named and default parameters to ease Stage creation.

[FEATURE] (ktx-graphics) Added ShapeRenderer.use to allow safe omission of the begin() and end() calls.

[FEATURE] (ktx-math) Added ImmutableVector2, an immutable equivalent to Vector2.

Known issues:

[REMOVAL] (ktx-async) AssetStorage was removed until refactoring to the new ktx-async API.

[REMOVAL] (ktx-freetype-async) Since ktx-freetype-async depends on the AssetStorage, this module was disabled before this release.

Source code(tar.gz)
Source code(zip)
1.9.9-b1.zip(2.38 MB)
1.9.8-b5(Sep 20, 2018)
Maintenance release with major dependencies update and an improvement of the ktx-ashley component creation API.

[UPDATE] Updated to Kotlin 1.2.70.

[UPDATE] Updated to Kotlin Coroutines 0.26.1.

[UPDATE] Updated to Gradle 4.10.2.

[FIX] (ktx-ashley) Component classes without a default no-arg constructors could not have been initiated by the Ashley engine. This is still the case, but now an exception with a meaningful message is thrown.

Source code(tar.gz)
Source code(zip)
1.9.8-b5.zip(2.35 MB)
1.9.8-b4(Jul 27, 2018)
Maintenance release with notable dependencies updates and ktx-collections unit tests refactoring.

[UPDATE] Updated to Kotlin 1.2.51.

[UPDATE] Updated to Kotlin Coroutines 0.24.0.

[UPDATE] Updated to Dokka 0.9.17.

[UPDATE] Updated to Gradle 4.9.

[CHANGE] (ktx-async) KtxAsync.asynchronous is now inlined. The action lambda is cross-inlined to avoid excessive object creation.

Source code(tar.gz)
Source code(zip)
1.9.8-b4.zip(2.35 MB)
1.9.8-b3(Jun 1, 2018)
The first release to feature the new ktx-graphics module with ShapeRenderer extensions and various graphics-related utilities moved from the ktx-app module.

[UPDATE] Updated to Kotlin 1.2.41.

[UPDATE] Updated to Gradle 4.7.

[FEATURE] (ktx-graphics) Added new graphics module with the following ShapeRenderer extension methods:

arc

box

circle

cone

ellipse

rect

rectLine

rotate

scale

translate

triangle

[CHANGE] (ktx-app, ktx-graphics) Utility functions moved from ktx-app to the new ktx-graphics:

color

Color.copy

Batch.use

ShaderProgram.use

[MISC] Removed migration guides from very old versions. If you are in a process of migrating an existing application to the latest KTX and facing any errors, see README files in 1.9.8-b2 tag.

Source code(tar.gz)
Source code(zip)
1.9.8-b3.zip(2.34 MB)
1.9.8-b2(Mar 7, 2018)
Contains notable breaking changes to ktx-math operators in order to prevent calculation errors arising from vectors and matrices mutability.

[UPDATE] Updated to Kotlin 1.2.30.

[UPDATE] Updated to Kotlin Coroutines 0.22.5.

[UPDATE] Updated to Dokka 0.9.16.

[UPDATE] Updated to Gradle 4.6.

[FEATURE] (ktx-math) dot and x infix functions added to Vector2 and Vector3 allow to calculate dot products and cross products of two vectors respectively.

[FEATURE] (ktx-box2d) Initiation blocks of Body in World.body extension method is now optional thanks to default lambda parameters in inlined functions.

[FEATURE] (ktx-box2d) World.query extension method allowing to execute AABB query with idiomatic Kotlin.

[CHANGE] (ktx-math) Binary operators of Vector2, Vector3, Matrix3 and Matrix4 (+, -, *, /) no longer modify the first vector or matrix. Instead, they create new instances of vectors or matrices that store the operation result. Use the assign operators (+=, -=, *=, /=) instead to avoid creating new instances.

[CHANGE] (ktx-math) New mutating assign operators (+=, -=, *=, /=) were added to Vector2, Vector3, Matrix3 and Matrix4.

[CHANGE] (ktx-math) Parameters of matrix vector multiplication operators are switched. vector * matrix does not exist anymore and now is available as matrix * vector.

[CHANGE] (ktx-math) Operators of Matrix3 to left-multiply a Vector3 were removed.

Source code(tar.gz)
Source code(zip)
1.9.8-b2.zip(2.30 MB)
1.9.8-b1(Jan 27, 2018)
The first release that contains ktx-freetype and ktx-freetype-async modules: FreeType font loading utilities. The transition from Kotlin 1.1 to 1.2 also allowed us to use default functional parameters in inlined methods, which simplified some APIs. It also contains notable changes and simplifications of the ktx-inject API.

[UPDATE] Updated to LibGDX 1.9.8.

[UPDATE] Updated to Kotlin 1.2.21.

[UPDATE] Updated to Kotlin Coroutines 0.22.

[UPDATE] Updated to Gradle 4.4.

[UPDATE] Updated to VisUI 1.4.0.

[CHANGE] (ktx-scene2d) Duplicate functions in Scene2D building DSL were removed thanks to optional default lambda parameters in inlined functions (added in Kotlin 1.2). Due to the limitation in inlined methods, there used to be two inlined methods for each actor to support syntax both with braces (init block) and without. Now there is just one factory method supporting both syntax variants per widget. This should not affect most application, but might require Kotlin 1.2 usage.

[CHANGE] (ktx-ashley) Default functional parameters were added to create, entity and with, simplifying the implementation and making configuration blocks optional.

[CHANGE] (ktx-inject) Parameters of bindSingleton consuming multiple classes have been swapped to be more compatible with the bind functions.

[CHANGE] (ktx-inject) bind and bindSingleton methods consuming multiple classes now take KClass as parameters instead of Class, so now you can use YourType::class instead of more verbose YourType::class.java.

[FEATURE] (ktx-style) Initiation blocks of Skin and Scene2D actor styles are now optional.

[FEATURE] (ktx-vis-style) Initiation blocks of VisUI actor styles are now optional.

[FEATURE] (ktx-box2d) Initiation blocks of fixtures and joints are now optional thanks to default lambda parameters in inlined functions.

[FEATURE] (ktx-inject) Add higher-order function parameters for bindSingleton to allow the use of lambda expressions.

fun createCircle(body: Body) { // Before - would not compile without additional braces: body.circle(radius = 2f) {} // Now - braces are optional (lambda parameter defaults to no-op): body.circle(radius = 2f) }

[FEATURE] (ktx-freetype) Implemented ktx-freetype module.

AssetManager.registerFreeTypeFontLoaders allows to register all loaders necessary to handle FreeType font assets.

AssetManager.loadFreeTypeFont provides Kotlin DSL for loading of FreeType fonts.

freeTypeFontParameters function provides Kotlin DSL for building FreeType font loading parameters.

FreeTypeFontGenerator.generateFont extension function allows to generate BitmapFont with Kotlin DSL.

[FEATURE] (ktx-freetype-async) Implemented ktx-freetype-async module.

AssetStorage.registerFreeTypeFontLoaders allows to register all loaders necessary to handle FreeType font assets.

AssetStorage.loadFreeTypeFont provides Kotlin DSL for asynchronous loading of FreeType fonts.

[FIX] (ktx-box2d) As LibGDX 1.9.8 fixes its ChainShape implementation, ChainShape utilities are supported once again.

Source code(tar.gz)
Source code(zip)
1.9.8-b1.zip(2.22 MB)
1.9.7-b1(Nov 2, 2017)
The first release supporting LibGDX 1.9.7.

[UPDATE] Updated LibGDX to 1.9.7.

[UPDATE] Updated to Kotlin 1.1.51.

[UPDATE] Updated to Kotlin Coroutines 0.19.3.

[UPDATE] Updated to Gradle 4.3.

Known issues:

[BUG] (ktx-box2d) ChainShape does not work correctly in LibGDX 1.9.7, and hence is not supported in KTX. This might break existing applications. If your application relies on Box2D, it is advised to use previous or next LibGDX release. Note that 1.9.7-b1 should work with LibGDX 1.9.8 without any issues.

Source code(tar.gz)
Source code(zip)
1.9.7-b1.zip(2.06 MB)