KTX Documentation

KTX is a Kotlin game framework designed to extend libGDX and make it more Kotlin-friendly. Instead of rewriting the libGDX API, KTX provides modular utilities and extensions for parts of libGDX that lack idiomatic Kotlin support. It leverages several Kotlin language features to improve usability, performance, and readability, including:

• Operator overloads for collections and mathematical operations.
• Extension methods to expand libGDX APIs without inheritance.
• Inline methods for reduced overhead in listeners, builders, and loggers.
• Nullable types for improved typing in interfaces and functions.
• Default parameters to reduce boilerplate.
• Type-safe builders for GUI, interface styling, ECS, and physics engine setup.
• Default interface methods to simplify implementations.
• Coroutines context for concurrency and non-blocking asset loading.
• Reified types to simplify methods that typically require Class parameters.

The ktx-vis module provides a Kotlin DSL for creating VisUI widgets, making GUI layouts as readable as markup languages while maintaining the power of Kotlin. It extends ktx-scene2d with factory methods for various widget categories:

• Root actors: visDialog, visWindow, toastTable.
• Parent actors (Layout/Control): visTable, visTree, gridGroup, floatingGroup, flowGroup, dragPane, visScrollPane, visSplitPane, multiSplitPane, collapsible, horizontalCollapsible.
• Parent actors (Can store actors): visTextButton, visImageButton, visImageTextButton, visCheckBox, visRadioButton, basicColorPicker, extendedColorPicker, spinner.
• Child actors: visLabel, linkLabel, visImage, visList, visListOf, visProgressBar, visSelectBox, visSelectBoxOf, visSlider, visTextArea, highlightTextArea, scrollableTextArea, visTextField, visValidatableTextField, busyBar, separator.
• Widget managers: buttonBar, listView, tabbedPane.

KTX AssetStorage is a coroutine-based alternative to the libGDX AssetManager. It is designed for developers using Kotlin coroutines who want to avoid the thread-blocking and polling-based API of the standard AssetManager.

Key Advantages over libGDX AssetManager:

• True Multi-threading: Unlike AssetManager which uses a single thread for async operations, AssetStorage can utilize any number of threads provided by your chosen CoroutineContext.
• Non-blocking API: Instead of calling update() every frame in your render loop, you simply launch a coroutine and await or load assets. The rendering thread remains unblocked.
• Better Error Handling: Uses standard Kotlin try-catch blocks for asynchronous errors, providing more granular control than global listeners.
• Flexible Identification: Supports loading multiple assets of different types from the same file path (e.g., a Texture and a Pixmap from the same PNG), whereas AssetManager uses the path as a unique identifier.
• Controlled Loading Order: Users have full control over whether assets load sequentially or in parallel by managing coroutines.

The AssetGroup class allows you to group related assets so they can be managed collectively (e.g., loadAll() or unloadAll()). You typically subclass AssetGroup and define assets as properties.

• Immediate Loading: Use asset<T>(path) within a subclass. These assets are queued for loading immediately when the AssetGroup is instantiated.
• Delayed/On-Demand Loading: Use delayedAsset<T>(path). These are not queued immediately; they are loaded on the first access or when loadAll() is called manually.
• Prefixing: You can provide a filePrefix to the constructor to allow all assets in the group to be loaded from a specific subdirectory.

/** Groups UI-related assets. */
class UIAssets(manager: AssetManager) : AssetGroup(manager, filePrefix = "ui/") {
  val skin by asset<Skin>("skin.json")
  val clickSound by asset<Sound>("mapScreen.wav")
}

val uiAssets = UIAssets(manager)
uiAssets.finishLoading()
// Accessing assets:
val mySkin = uiAssets.skin

// Disposing:
uiAssets.unloadAll()