Xedge-ktx-PROSAGA-码农传奇

Kotlin extensions for libGDX.

Introduction
Modules
Installation
Documentation
Contribution

Introduction

KTX is a Kotlin game framework extending 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 expanding and improving the 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 and providing sensible defaults for various operations.
Type-safe builders for GUI, interface styling, ECS, and physics engine setup.
Default interface methods simplifying their implementation.
Coroutines context providing concurrency utilities and non-blocking asset loading.
Reified types simplifying usage of methods normally consuming Class parameters.

See the Choosing KTX article for pros and cons of this framework.

Modules

KTX was designed to be modular from day one. In fact, some of its libraries consist of just a single Kotlin file.
You can include the 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-ai`	Type-safe Kotlin builders and utilities for `gdxAI`.
`ktx-app`	`ApplicationListener` implementations and general application utilities.
`ktx-artemis`	`Artemis-odb` entity-component-system 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-script`	Kotlin scripting engine for desktop applications.
`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

New projects

New projects with support for KTX can be generated with the gdx-liftoff tool.
In contrary to the official gdx-setup tool, gdx-liftoff provides greater support for libGDX extensions and
a wider set of platforms, as well as custom project templates. You can download the latest release of the tool
here.

Click on the sections below for instructions on how to set up a new KTX project with gdx-liftoff.

General

—-

Fill the basic information about your project such as its name, root package or main class name.
Provide an empty folder to generate the project into. If you want to target the Android platform,
define the path to the Android SDK.

The following sections describe each tab of the setup tool available below the basic project info.

—-

Platforms

—-

KTX supports the following platforms:

Core: mandatory shared module. Desktop: the default desktop platform based on LWJGL3.
Android: native Android mobile platform. iOS: mobile platform using RoboVM to support iOS.
HTML (TeaVM): unofficial experimental web platform using TeaVM. Headless: a desktop platform without a graphical interface.
Server: a separate server application without libGDX APIs. Shared: a module for sharing code between the Server and Core.

The following platforms are unsupported or untested:
HTML: the default web platform. Supports only Java projects. Desktop (Legacy): legacy desktop platform built upon LWJGL2. Might not work with modern JVMs.
* iOS Multi-OS Engine: an alternative iOS platform. Untested.

—-

Languages

—-

You can select the Kotlin language support to ensure it is correctly set up in the generated project.
If a Kotlin project template is selected, it will automatically add the necessary Kotlin libraries and plugins.

—-

Extensions

—-

This section includes the official libGDX extensions. Each of these should be compatible with Kotlin
projects. However, some extensions might be unavailable on specific platforms. In particular, the TeaVM
backend might be unable to compile libraries relying on native code or reflection.

—-

Third-party extensions

—-

This section contains all verified third-party extensions for libGDX. All KTX modules are listed
in this tab.

To include a KTX module, scroll down to the KTX libraries list and click on the corresponding
checkbox. This will ensure that the module is properly installed and includes all of its dependencies
in the latest available versions.

The gdx-liftoff tool will also set up a Gradle property named ktxVersion that will be shared across
all KTX libraries. To upgrade your project after a KTX release, update to the latest version
in the gradle.properties file.

—-

Templates

—-

Choosing a template for the project determines the initial implementation of the libGDX ApplicationListener,
as well as the application launchers on each platform. Some templates also showcase specific parts of the framework,
such as the Scene2D GUI or event handling. You can generate several projects and check out various templates,
but for working with Kotlin and KTX these are the best starting points:

Kotlin: a basic project template that generates Kotlin application launchers. Kotlin Logo: a simple project that generates Kotlin application launchers and draws the libGDX logo on the screen.
Kotlin + KTX (recommended): a project template that generates the ApplicationListener using KTX
utilities. When launched, the application draws the *KTX logo on the screen. Some modules that require additional
setup, such as ktx-async, are properly initiated by the template if selected.

—-

Advanced

—-

This section can be used to specify versions of core dependencies. If you are just starting with libGDX,
these settings can be mostly left untouched. However, if you wish to have a basic Scene2D GUI Skin that you
can use to test the available widgets, mark the Add GUI assets checkbox.

—-

Example KTX projects:

ktx-sample-project: includes all KTX modules and the official
libGDX extensions. Targets the desktop and mobile platforms.
ktx-sample-web-project: includes most KTX modules that are
at least partially supported by the web platform, as well as the official libGDX extensions. Targets the desktop,
mobile and web platforms.

When using the official gdx-setup tool instead of the recommended gdx-liftoff, generate a project with Kotlin
support and refer to the next section.

Existing projects

KTX libraries can be added to existing Kotlin libGDX projects. Please refer to the
libGDX wiki for more information on how to add Kotlin
support to a libGDX application.

All KTX modules are uploaded to Maven Central and are fully compatible with the Gradle build tool, which is used
in libGDX projects by default.

The libraries are published under the io.github.libktx group and are named with the ktx- prefix. You can find
a complete list of KTX modules in the previous section. As an example, including the app module
with the ktx-app identifier would require the following changes in your build.gradle or build.gradle.kts file:

build.gradle _{Gradle Groovy DSL}

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

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

build.gradle.kts _{Gradle Kotlin DSL}

kotlin
// Update this version to match the latest KTX release:
val ktxVersion = "1.13.1-rc1"

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

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

You can find the latest KTX version on Maven Central:

Platforms

KTX currently supports the following platforms:

Platform	Status	Description
Desktop	Complete	All major desktop platforms are supported by the official libGDX LWJGL3 backend.
Android	Complete	Supported natively by the official libGDX Android backend.
iOS	Complete	Supported by the official libGDX iOS backend using RoboVM.
Web	Experimental	Partially supported by the unofficial web backend using TeaVM.

Note that platforms other than desktop might provide limited support for features such as reflection, coroutines
or Java standard library emulation. In particular, mobile platforms might not support the entire Java standard
library including the newer additions, while the web platform currently does not support Kotlin coroutines or more
advanced reflection features. Please refer to the documentation of the respective libGDX backends, as well as
the tools that they are based on.

Versioning

Each KTX version is based on the matching libGDX release. KTX uses suffixes to differentiate multiple releases
made against a single libGDX version. The -rc suffix is reserved for stable releases.

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. When choosing the appropriate KTX version, always pick
the latest release matching your current libGDX version.

You can browse through our official releases on Maven
and on GitHub.

Although KTX technically uses beta release tags, the official releases are considered suitable for production use.
All modules are thoroughly tested with comprehensive test suites.

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
released version.

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

The preview snapshot releases with the latest changes are uploaded automatically to the
https://oss.sonatype.org/content/repositories/snapshots/ repository. To use them in your application, add
the following Maven repository, and change the suffix of the KTX version to -SNAPSHOT:

build.gradle _{Gradle Groovy DSL}

groovy
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.13.1-SNAPSHOT'
}

build.gradle.kts _{Gradle Kotlin DSL}

kotlin
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.13.1-SNAPSHOT"

The full version of the latest snapshot release can be found on the
develop branch, and usually matches the latest
stable libGDX release. Snapshot releases for the nightly libGDX builds are not available.

Note that 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 libraries 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 the 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
or the contributors list.

Licensing

This project is dedicated to public domain.

Working from sources

See this section of the contribution guideline to get started.

Table of contents