KTX 1.9.11-b1

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.

KTX 1.9.10-b7

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.

KTX 1.9.10-b6

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.

KTX 1.9.10-b5

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.

KTX 1.9.10-b4

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.

KTX 1.9.10-b3

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.

KTX 1.9.10-b2

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.

KTX 1.9.10-b1

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.

KTX 1.9.9-b2

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.

KTX 1.9.9-b1

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.