diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 9be9cfdc..ae2af0f6 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -146,6 +146,8 @@ to update the [version.txt](../version.txt) and [milestones](https://github.com/ [vis/README.md](../vis/README.md) file. - **Ashley**: update `ashleyVersion` in the versions file and Ashely version in the tag on the top of the [ashley/README.md](../ashley/README.md) file. +- **Artemis-odb**: update `artemisOdbVersion` in the versions file and Artemis-odb version in the tag on the top of the +[artemis/README.md](../artemis/README.md) file. All the major dependencies updates should be added to the [changelog](../CHANGELOG.md). diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 922bd99e..a9248695 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -11,17 +11,20 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - java-version: [1.8, 1.11] + java-version: [8, 11] steps: - name: Repository checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: JDK setup - uses: actions/setup-java@v1 + uses: actions/setup-java@v3 with: java-version: ${{ matrix.java-version }} - - name: Execution permission for Gradle wrapper - run: chmod +x gradlew + distribution: temurin + - name: Gradle setup + uses: gradle/gradle-build-action@v2 + - name: Gradle wrapper validation + uses: gradle/wrapper-validation-action@v1 - name: Build run: ./gradlew assemble install -x dokkaHtml -x dokkaZip - name: Tests diff --git a/.github/workflows/publish-documentation.yml b/.github/workflows/publish-documentation.yml index d4032934..36f1361f 100644 --- a/.github/workflows/publish-documentation.yml +++ b/.github/workflows/publish-documentation.yml @@ -3,28 +3,33 @@ name: publish-documentation on: push: branches: [ master ] + workflow_dispatch: jobs: - build: + publish: runs-on: ubuntu-latest steps: - name: Repository checkout - uses: actions/checkout@v2 - with: - persist-credentials: false + uses: actions/checkout@v3 - name: JDK setup - uses: actions/setup-java@v1 + uses: actions/setup-java@v3 with: - java-version: 1.11 - - name: Execution permission for Gradle wrapper - run: chmod +x gradlew + java-version: 11 + distribution: temurin + - name: Save version + shell: bash + run: | + echo "KTX_VERSION=$(cat version.txt)" >> $GITHUB_ENV + - name: Gradle setup + uses: gradle/gradle-build-action@v2 - name: Dokka run: ./gradlew dokkaHtmlMultiModule - name: Publish GitHub pages - uses: JamesIves/github-pages-deploy-action@releases/v3 + uses: JamesIves/github-pages-deploy-action@releases/v4 with: - ACCESS_TOKEN: ${{ secrets.accessToken }} - BRANCH: gh-pages - FOLDER: build/dokka/htmlMultiModule - REPOSITORY_NAME: libktx/docs + token: ${{ secrets.accessToken }} + branch: gh-pages + folder: build/dokka/htmlMultiModule + repository-name: libktx/docs + commit-message: 'Documentation of KTX ${{ env.KTX_VERSION }}.' diff --git a/.github/workflows/publish-project-samples.yml b/.github/workflows/publish-project-samples.yml new file mode 100644 index 00000000..bd6f29cd --- /dev/null +++ b/.github/workflows/publish-project-samples.yml @@ -0,0 +1,55 @@ +name: publish-project-samples +on: + push: + tags: [ '*' ] + workflow_dispatch: + +jobs: + publish: + runs-on: ubuntu-latest + + steps: + - name: Repository checkout + uses: actions/checkout@v3 + with: + repository: tommyettinger/gdx-liftoff + - name: JDK setup + uses: actions/setup-java@v3 + with: + java-version: 11 + distribution: temurin + - name: Save versions + shell: bash + run: | + echo "LIFTOFF_VERSION=$(cat version.txt)" >> $GITHUB_ENV + echo "KTX_VERSION=$(curl https://raw.githubusercontent.com/libktx/ktx/master/version.txt)" >> $GITHUB_ENV + - name: Gradle setup + uses: gradle/gradle-build-action@v2 + - name: Generate sample + run: ./gradlew sample --args="ktx" + - name: Prepare sample for release + run: | + find build/dist/sample/ -type f \( -iname \*.kt -o -iname \*.gradle -o -iname \*.json -o -iname \*.xml \) | xargs sed -i -e 's/\t/ /g' + - name: Publish KTX sample + uses: JamesIves/github-pages-deploy-action@v4 + with: + token: ${{ secrets.accessToken }} + branch: main + folder: build/dist/sample + repository-name: libktx/ktx-sample-project + commit-message: 'Automatic deployment: KTX ${{ env.KTX_VERSION }}, gdx-liftoff ${{ env.LIFTOFF_VERSION }}.' + - name: Clean basic sample + run: rm -rf build/dist/sample + - name: Generate web sample + run: ./gradlew sample --args="ktx_web" + - name: Prepare sample for release + run: | + find build/dist/sample/ -type f \( -iname \*.kt -o -iname \*.gradle -o -iname \*.json -o -iname \*.xml \) | xargs sed -i -e 's/\t/ /g' + - name: Publish KTX web sample + uses: JamesIves/github-pages-deploy-action@v4 + with: + token: ${{ secrets.accessToken }} + branch: main + folder: build/dist/sample + repository-name: libktx/ktx-sample-web-project + commit-message: 'Automatic deployment: KTX ${{ env.KTX_VERSION }}, gdx-liftoff ${{ env.LIFTOFF_VERSION }}.' diff --git a/.github/workflows/upload-snapshot.yml b/.github/workflows/upload-snapshot.yml index 0f3c85f6..871d4c4c 100644 --- a/.github/workflows/upload-snapshot.yml +++ b/.github/workflows/upload-snapshot.yml @@ -5,18 +5,19 @@ on: branches: [ develop ] jobs: - build: + upload: runs-on: ubuntu-latest steps: - name: Repository checkout - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: JDK setup - uses: actions/setup-java@v1 + uses: actions/setup-java@v3 with: - java-version: 1.8 - - name: Execution permission for Gradle wrapper - run: chmod +x gradlew + java-version: 8 + distribution: temurin + - name: Gradle setup + uses: gradle/gradle-build-action@v2 - name: Tests run: ./gradlew check env: diff --git a/CHANGELOG.md b/CHANGELOG.md index b48ed8f4..7b41cded 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ _See also: [the official libGDX changelog](https://github.com/libgdx/libgdx/blob/master/CHANGES)._ +#### 1.11.0-rc4 + +- **[UPDATE]** Updated to Kotlin 1.8.0. +- **[UPDATE]** Updated to VisUI 1.5.1. +- **[MISC]** Project README now includes installation instructions for new projects using `gdx-liftoff`. +- **[MISC]** Sample KTX projects are now generated by `gdx-liftoff` on every release. + - [Basic project demo](https://github.com/libktx/ktx-sample-project). + - [Experimental project demo with web support via TeaVM](https://github.com/libktx/ktx-sample-web-project). +- **[MISC]** Removed migration guides from `ktx-scene2d` and `ktx-vis` README files. If you are migrating from an old KTX version, please refer to the *1.11.0-rc3* tag. +- **[FEATURE]** (`ktx-assets-async`) `AssetStorage.silenceAssetManagerWarnings` property was added, allowing to silence logging on non-fatal `AssetLoader` issues. +- **[FEATURE]** (`ktx-assets-async`) `AssetManagerWrapper` warnings caused by `AssetLoader` issues were extended and improved. + #### 1.11.0-rc3 - **[UPDATE]** Updated to Kotlin 1.7.22. diff --git a/README.md b/README.md index fede100e..41d9a1cd 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ [![GitHub Build](https://github.com/libktx/ktx/workflows/build/badge.svg)](https://github.com/libktx/ktx/actions?query=workflow%3Abuild) -[![Kotlin](https://img.shields.io/badge/kotlin-1.7.22-orange.svg)](http://kotlinlang.org/) +[![Kotlin](https://img.shields.io/badge/kotlin-1.8.0-orange.svg)](http://kotlinlang.org/) [![libGDX](https://img.shields.io/badge/libgdx-1.11.0-red.svg)](https://libgdx.com/) [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-async.svg)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22) @@ -7,30 +7,38 @@ _**K**o**t**lin extensions for libGD**X**._ +# Table of contents + +* [Introduction](#introduction) +* [Modules](#modules) +* [Installation](#installation) +* [Documentation](#documentation) +* [Contribution](#contribution) + ## Introduction -**KTX** is a Kotlin game framework built on [libGDX](http://libgdx.badlogicgames.com/). It aims to make libGDX as +**KTX** is a Kotlin game framework extending [libGDX](http://libgdx.badlogicgames.com/). It aims to make libGDX as [Kotlin](http://kotlinlang.org/)-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. +- *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. -- *Type-safe builders* for GUI, styling, and physics engine. -- *Default interface methods* for common interfaces, simplifying their implementations. +- *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* that simplify usage of methods normally consuming `Class` parameters. +- *Reified types* simplifying usage of methods normally consuming `Class` parameters. See the [_Choosing **KTX**_](https://github.com/libktx/ktx/wiki/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. +**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 | |:--------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------| @@ -62,25 +70,157 @@ You can include selected **KTX** modules based on the needs of your application. ### 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. +#### New projects -All libraries follow the same naming schema: +New projects with support for KTX can be generated with the [`gdx-liftoff` tool](https://github.com/tommyettinger/gdx-liftoff). +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](https://github.com/tommyettinger/gdx-liftoff/releases). -```groovy -api "io.github.libktx:$module:$ktxVersion" -``` +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
-Replace `$module` with the name of the selected **KTX** library (see the table above). +--- -For example, including the [app](app) module with the `ktx-app` identifier would require the following changes -in your `build.gradle` file: +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`](https://github.com/libktx/ktx-sample-project): includes all **KTX** modules and the official + libGDX extensions. Targets the desktop and mobile platforms. +* [`ktx-sample-web-project`](https://github.com/libktx/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](https://libgdx.com/wiki/jvm-langs/using-libgdx-with-kotlin) 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](#modules). As an example, including the [app](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.11.0-rc3' + ktxVersion = '1.11.0-rc4' } dependencies { @@ -88,57 +228,75 @@ dependencies { } ``` -```kotlin -// Kotlin DSL: +
+ +
build.gradle.kts Gradle Kotlin DSL +```kotlin // Update this version to match the latest KTX release: -val ktxVersion = "1.11.0-rc3" +val ktxVersion = "1.11.0-rc4" 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: [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-app.svg)](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22) -**KTX** modules should generally be added to the dependencies of the shared `core` module of your libGDX application. +#### Platforms -> 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. +**KTX** currently supports the following platforms: -#### Versioning +| 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](http://robovm.mobidevelop.com/). | +| Web | Experimental | Partially supported by the unofficial [web backend](https://github.com/xpenatan/gdx-teavm/) using [TeaVM](https://teavm.org/). | -**KTX** versions match the libGDX versions that they were compiled against. `$ktxVersion` will usually match your libGDX -version, but it might end with `-rc` suffix if it is a stable release, or `-SNAPSHOT` if you are using the development -branch. Older **KTX** releases use the `-b` suffix to mark milestone releases. +> 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. -You can browse through our official releases [on Maven](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22) -and [on GitHub](https://github.com/libktx/ktx/releases). +#### 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](https://semver.org/) guidelines. Both minor and patch versions can introduce breaking changes. Please read the [libGDX](https://github.com/libgdx/libgdx/blob/master/CHANGES) -and [**KTX** change logs](CHANGELOG.md) before updating. +and [**KTX** change logs](CHANGELOG.md) 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](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22) +and [on GitHub](https://github.com/libktx/ktx/releases). -Although **KTX** still uses beta release tags, the official releases are stable enough for production use. -All modules are thoroughly tested with unit tests. +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`](https://github.com/libktx/ktx/tree/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. +released version. The newest changes can be found on the [`develop`](https://github.com/libktx/ktx/tree/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`: +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 -// Groovy DSL: repositories { // Include your other repositories here. maven { url 'https://oss.sonatype.org/content/repositories/snapshots/' } @@ -150,8 +308,11 @@ ext { } ``` +
+ +
build.gradle.kts Gradle Kotlin DSL + ```kotlin -// Kotlin DSL: repositories { // Include your other repositories here. maven("https://oss.sonatype.org/content/repositories/snapshots/") @@ -161,11 +322,14 @@ repositories { val ktxVersion = "1.11.0-SNAPSHOT" ``` -The latest snapshot version name can be found on the [`develop`](https://github.com/libktx/ktx/blob/develop/version.txt) -branch. +
+ +The full version of the latest snapshot release can be found on the +[`develop`](https://github.com/libktx/ktx/blob/develop/version.txt) branch, and usually matches the latest +stable libGDX release. Snapshot releases for the nightly libGDX builds are not available. -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. +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 @@ -202,7 +366,7 @@ If you would like to contribute, please read [the contribution guideline](.githu 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](https://github.com/libktx/ktx/graphs/contributors) -and on [the contributors list](.github/CONTRIBUTORS.md). +or [the contributors list](.github/CONTRIBUTORS.md). ### Licensing diff --git a/assets-async/src/main/kotlin/ktx/assets/async/AssetManagerWrapper.kt b/assets-async/src/main/kotlin/ktx/assets/async/AssetManagerWrapper.kt index ed9608a6..b84c4961 100644 --- a/assets-async/src/main/kotlin/ktx/assets/async/AssetManagerWrapper.kt +++ b/assets-async/src/main/kotlin/ktx/assets/async/AssetManagerWrapper.kt @@ -45,10 +45,10 @@ internal class AssetManagerWrapper( ) override fun dispose() { if (initiated) { - logger.error("Not fully supported AssetManagerWrapper.dispose called by AssetLoader.") + logIncompleteSupportWarning("dispose") KtxAsync.launch { assetStorage.dispose { path, error -> - logger.error("Unable to dispose of the asset: $path", error) + logWarning("Unable to dispose of the asset: $path", error) } } } @@ -73,7 +73,7 @@ internal class AssetManagerWrapper( replaceWith = ReplaceWith("AssetStorage.add") ) override fun addAsset(fileName: String, type: Class, asset: T) { - logger.error("Not fully supported AssetManagerWrapper.addAsset called by AssetLoader.") + logIncompleteSupportWarning("addAsset") KtxAsync.launch { assetStorage.add(AssetDescriptor(fileName, type), asset) } @@ -85,7 +85,7 @@ internal class AssetManagerWrapper( @Deprecated("Not supported by AssetStorage.", replaceWith = ReplaceWith("Nothing")) override fun setErrorListener(listener: AssetErrorListener?) { - logger.error("Not supported AssetManagerWrapper.setErrorListener called by AssetLoader.") + logNoSupportWarning("setErrorListener") } @Deprecated("Not supported by AssetStorage.", replaceWith = ReplaceWith("Nothing")) @@ -103,7 +103,7 @@ internal class AssetManagerWrapper( assetStorage[identifier] } catch (exception: Throwable) { if (required) throw MissingDependencyException(identifier, exception) else { - logger.error("Missing asset requested: $fileName", exception) + logWarning("Missing asset requested: $fileName", exception) null } } @@ -111,13 +111,13 @@ internal class AssetManagerWrapper( @Deprecated("AssetStorage requires type to find a stored asset.", replaceWith = ReplaceWith("get(fileName, type, required)")) override fun get(fileName: String, required: Boolean): Asset? { - logCollisionWarning("get(String, Boolean)") + logCollisionWarning("get(String, Boolean)", fileName) @Suppress("UNCHECKED_CAST") val identifier = getIdentifier(fileName) as Identifier? val asset = identifier?.let { try { assetStorage[it] } catch (exception: Throwable) { null } } if (asset == null) { - if (required) throw MissingDependencyException("Required asset not found: $required") - else logger.error("Missing asset requested: $fileName") + if (required) throw MissingDependencyException("Required asset not found: $fileName") + else logWarning("Missing asset requested: $fileName") } return asset } @@ -133,7 +133,7 @@ internal class AssetManagerWrapper( replaceWith = ReplaceWith("Nothing") ) override fun getAssetType(fileName: String): Class<*>? { - logCollisionWarning("getAssetType") + logCollisionWarning("getAssetType", fileName) val identifier = getIdentifier(fileName) return identifier?.type } @@ -144,7 +144,7 @@ internal class AssetManagerWrapper( @Deprecated("Not supported by AssetStorage.", replaceWith = ReplaceWith("Nothing")) override fun getAssetFileName(asset: T): String? { - logger.error("Not supported AssetManagerWrapper.getAssetFileName called by AssetLoader.") + logNoSupportWarning("getAssetFileName") return null } @@ -167,7 +167,7 @@ internal class AssetManagerWrapper( replaceWith = ReplaceWith("isLoaded(fileName, type)") ) override fun isLoaded(fileName: String): Boolean { - logCollisionWarning("isLoaded(String)") + logCollisionWarning("isLoaded(String)", fileName) val identifier = getIdentifier(fileName) return identifier != null && assetStorage.isLoaded(identifier) } @@ -177,7 +177,7 @@ internal class AssetManagerWrapper( replaceWith = ReplaceWith("AssetStorage.unload") ) override fun unload(fileName: String) { - logCollisionWarning("unload") + logCollisionWarning("unload", fileName) val identifier = getIdentifier(fileName) ?: return KtxAsync.launch(assetStorage.asyncContext) { assetStorage.unload(identifier) @@ -212,7 +212,7 @@ internal class AssetManagerWrapper( suffix: String?, loader: AssetLoader ) { - logger.error("Not fully supported AssetManagerWrapper.setLoader called by AssetLoader.") + logIncompleteSupportWarning("setLoader") assetStorage.setLoader(type, suffix) { @Suppress("UNCHECKED_CAST") loader as Loader @@ -224,26 +224,18 @@ internal class AssetManagerWrapper( replaceWith = ReplaceWith("AssetStorage.getDependencies") ) override fun getDependencies(fileName: String): GdxArray { - logCollisionWarning("getDependencies") + logCollisionWarning("getDependencies", fileName) val identifier = getIdentifier(fileName) return if (identifier != null) GdxArray(assetStorage.getDependencies(identifier).map { it.path }.toTypedArray()) else GdxArray.with() } - - private fun logCollisionWarning(method: String) { - logger.error( - "Warning: AssetManagerWrapper.$method might throw an exception " + - "if multiple assets with the same path are loaded with different types." - ) - } - @Deprecated( "AssetStorage requires type to find reference count.", replaceWith = ReplaceWith("AssetStorage.getReferenceCount") ) override fun getReferenceCount(fileName: String): Int { - logCollisionWarning("getReferenceCount") + logCollisionWarning("getReferenceCount", fileName) val identifier = getIdentifier(fileName) ?: return 0 return assetStorage.getReferenceCount(identifier) } @@ -260,12 +252,12 @@ internal class AssetManagerWrapper( @Deprecated("AssetStorage does not maintain an assets queue.", ReplaceWith("Nothing")) override fun getQueuedAssets(): Int = 0.also { - logger.error("Not supported AssetManagerWrapper.getQueuedAssets called by AssetLoader.") + logNoSupportWarning("getQueuedAssets") } @Deprecated("Unsupported operation.", ReplaceWith("Nothing")) override fun finishLoading() { - logger.error("Not supported AssetManagerWrapper.finishLoading called by AssetLoader.") + logNoSupportWarning("finishLoading") } @Suppress("UNCHECKED_CAST") @@ -274,7 +266,7 @@ internal class AssetManagerWrapper( @Deprecated("Unsupported without asset type.", ReplaceWith("finishLoadingAsset(assetDescriptor)")) override fun finishLoadingAsset(fileName: String): T { - logCollisionWarning("finishLoadingAsset(String)") + logCollisionWarning("finishLoadingAsset(String)", fileName) val identifier = getIdentifier(fileName)!! @Suppress("UNCHECKED_CAST") return get(identifier.path, identifier.type as Class) @@ -289,6 +281,29 @@ internal class AssetManagerWrapper( } } + private fun logWarning(warning: String, cause: Throwable? = null) { + if (!assetStorage.silenceAssetManagerWarnings) { + if (cause != null) logger.error(warning, cause) + else logger.error(warning) + } + } + + private fun logIncompleteSupportWarning(method: String) { + logWarning("AssetManagerWrapper.$method method with incomplete support was called by an asset loader.") + } + + private fun logNoSupportWarning(method: String) { + logWarning("Unsupported AssetManagerWrapper.$method method was called by an asset loader.") + } + + private fun logCollisionWarning(method: String, path: String) { + logWarning( + "AssetManagerWrapper.$method method called by an asset loader might throw an exception " + + "if multiple assets from the same path are loaded with different types. " + + "Warning issued for asset loaded from path: $path" + ) + } + override fun toString(): String = "AssetManagerWrapper(storage=$assetStorage)" override fun hashCode(): Int = assetStorage.hashCode() override fun equals(other: Any?): Boolean = diff --git a/assets-async/src/main/kotlin/ktx/assets/async/storage.kt b/assets-async/src/main/kotlin/ktx/assets/async/storage.kt index a8ea1b4d..f4705905 100644 --- a/assets-async/src/main/kotlin/ktx/assets/async/storage.kt +++ b/assets-async/src/main/kotlin/ktx/assets/async/storage.kt @@ -52,21 +52,23 @@ import com.badlogic.gdx.graphics.g3d.particles.ParticleEffectLoader as ParticleE * * [asyncContext] is used to perform asynchronous file loading. Defaults to a single-threaded context using an * [AsyncExecutor]. See [newSingleThreadAsyncContext] or [ktx.async.newAsyncContext] functions to create a custom - * loading context. Multi-threaded contexts are fully supported and might boost loading performance if the assets + * loading context. Multithreaded contexts are fully supported and might boost loading performance if the assets * are loaded asynchronously in parallel. * * [fileResolver] determines how file paths are interpreted. Defaults to [InternalFileHandleResolver], which loads * internal files. * * If `useDefaultLoaders` is true (which is the default), all default libGDX [AssetLoader] implementations - * will be registered. + * will be registered. If [silenceAssetManagerWarnings] is false (which is the default), all non-fatal asset loading + * issues caused by asset loaders will be logged as errors. It is encouraged not to change this setting to true during + * the development to avoid potential errors. */ class AssetStorage( val asyncContext: CoroutineContext = newSingleThreadAsyncContext(threadName = "AssetStorage-Thread"), val fileResolver: FileHandleResolver = InternalFileHandleResolver(), - useDefaultLoaders: Boolean = true + useDefaultLoaders: Boolean = true, + var silenceAssetManagerWarnings: Boolean = false, ) : Disposable { - @Suppress("LeakingThis") private val asAssetManager: AssetManager = AssetManagerWrapper(this) private val loaderStorage = AssetLoaderStorage() @@ -834,7 +836,7 @@ class AssetStorage( } } else { // The asset was unloaded asynchronously. The deferred was likely completed with an exception. - // Now we have to take care of the loaded value or it will remain loaded and unreferenced. + // Now we have to take care of the loaded value, or it will remain loaded and unreferenced. value.dispose(asset.identifier) } } @@ -1157,7 +1159,7 @@ class AssetStorage( /** * Returns the amount of references to the asset under the given [path] of [T] type. * - * References include manual registration of the asset with [add], + * References consist of manual registration of the asset with [add], * scheduling the asset for loading with [load], [loadAsync] or [loadSync], * and the amount of times the asset was referenced as a dependency of other assets. */ @@ -1166,7 +1168,7 @@ class AssetStorage( /** * Returns the amount of references to the asset described by [descriptor]. * - * References include manual registration of the asset with [add], + * References consist of manual registration of the asset with [add], * scheduling the asset for loading with [load], [loadAsync] or [loadSync], * and the amount of times the asset was referenced as a dependency of other assets. */ @@ -1175,7 +1177,7 @@ class AssetStorage( /** * Returns the amount of references to the asset identified by [identifier]. * - * References include manual registration of the asset with [add], + * References consist of manual registration of the asset with [add], * scheduling the asset for loading with [load], [loadAsync] or [loadSync], * and the amount of times the asset was referenced as a dependency of other assets. */ @@ -1226,7 +1228,7 @@ class AssetStorage( fun getAssetIdentifiers(path: String): List> = pathToIdentifiers.getOrDefault(path, emptyList()) /** - * Creates a deep copy of the internal assets storage. Returns an [AssetStorageSnapshot] + * Creates a deep copy of the internal asset storage. Returns an [AssetStorageSnapshot] * with the current storage state. For debugging purposes. * * Note that the [CompletableDeferred] that store references to assets are preserved only @@ -1265,7 +1267,7 @@ class AssetStorage( } /** - * Creates a deep copy of the internal assets storage. Returns an [AssetStorageSnapshot] + * Creates a deep copy of the internal asset storage. Returns an [AssetStorageSnapshot] * with the current storage state. Blocks the current thread until the snapshot is complete. * If assets are currently being loaded, avoid calling this method from within the rendering * thread. For debugging purposes. diff --git a/async/README.md b/async/README.md index 70b9dae3..242d54d1 100644 --- a/async/README.md +++ b/async/README.md @@ -55,6 +55,8 @@ in the core Gradle module instead of `api`. `ktx-async` was tested on desktop, Android and iOS, and should work on every major platform. If you encounter any issues with launching the coroutines, do not hesitate to create an [issue](https://github.com/libktx/ktx/issues). +> Note that Kotlin coroutines are not supported by the unofficial TeaVM web platform. + #### Coroutines _Please refer to Kotlin coroutines documentation or tutorials if you are having trouble with this section._ diff --git a/buildSrc/src/main/kotlin/ktx/Versions.kt b/buildSrc/src/main/kotlin/ktx/Versions.kt index 687a2846..f3f772bd 100644 --- a/buildSrc/src/main/kotlin/ktx/Versions.kt +++ b/buildSrc/src/main/kotlin/ktx/Versions.kt @@ -5,7 +5,7 @@ const val kotlinCoroutinesVersion = "1.6.4" const val artemisOdbVersion = "2.3.0" const val ashleyVersion = "1.7.4" -const val visUiVersion = "1.5.0" +const val visUiVersion = "1.5.1" const val spekVersion = "1.1.5" const val kotlinTestVersion = "2.0.7" diff --git a/gradle.properties b/gradle.properties index ca187d40..fa76c9e5 100644 --- a/gradle.properties +++ b/gradle.properties @@ -1,6 +1,6 @@ libGroup=io.github.libktx -kotlinVersion=1.7.22 +kotlinVersion=1.8.0 dokkaVersion=1.7.20 junitPlatformVersion=1.2.0 diff --git a/scene2d/README.md b/scene2d/README.md index 493b9b78..8a6078e9 100644 --- a/scene2d/README.md +++ b/scene2d/README.md @@ -772,37 +772,6 @@ Pair this library with [`ktx-style`](../style) for type-safe actor styles buildi for useful extension methods for `Scene2D` API. [`ktx-assets`](../assets) or [`ktx-assets-async`](../assets-async) might help with `Skin` loading and management. -### Migration guide - -`ktx-scene2d` up to `1.9.10-b5` had no `scene2d` object and instead provided root level factory functions -only for parental actors such as `Table` or `Window`. This turned out a bit more problematic than the current -approach, as you could not easily construct child actors (such as labels) without a parent, and the name clashes -between root level factory function and nested factory methods could lead to subtle bugs. - -```kotlin -// Up to 1.9.10-b5: -val myTable = table { - label("Old approach.") -} - -// Currently: -val myTable = scene2d.table { - label("Current approach.") -} -``` - -The migration is pretty straightforward: add `scene2d.` prefix to all root actor definitions. You can also leverage -the new `Stage.actors` extension method to add actors directly to a `Stage`. Note that nested actor definitions do not -require any changes. - -Only 2 factory methods were changed significantly: `listWidget` and `selectBox`. Now they have only a single -generic parameter - type of the items - and no longer consume `Cell` or `Node` instances in their building blocks. -Instead, you have to call `cell`, `inCell`, `node` or `inNode` outside of their building blocks to configure the layout. - -`ktx-scene2d` version `1.9.10-b6` has the deprecated root actor factory functions available with annotations -for automatic replacement. To ease migration to the newer KTX versions, use `1.9.10-b6` to refactor your application. -Further KTX releases do not contain the deprecated functions. - ### Alternatives - Creating layouts with [Scene2D](https://libgdx.com/wiki/graphics/2d/scene2d/scene2d) directly in Kotlin or Java. @@ -811,7 +780,7 @@ Further KTX releases do not contain the deprecated functions. - [LML](https://github.com/czyzby/gdx-lml/tree/master/lml) allows building `Scene2D` views using HTML-like syntax. It also features a [VisUI extension](https://github.com/czyzby/gdx-lml/tree/master/lml-vis). However, it lacks first-class Kotlin support and the flexibility of a programming language. -- [`ktx-vis`](../vis) extends `ktx-scene2d` with type-safe builders of +- [`ktx-vis`](../vis) extends `ktx-scene2d` with type-safe builders of the [VisUI](https://github.com/kotcrab/vis-editor/wiki/VisUI) widgets. #### Additional documentation diff --git a/version.txt b/version.txt index 1e1095e3..7f878f09 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -1.11.0-rc3 +1.11.0-rc4 diff --git a/vis/README.md b/vis/README.md index 276b431f..49b176f0 100644 --- a/vis/README.md +++ b/vis/README.md @@ -1,4 +1,4 @@ -[![VisUI](https://img.shields.io/badge/vis--ui-1.5.0-blue.svg)](https://github.com/kotcrab/vis-ui) +[![VisUI](https://img.shields.io/badge/vis--ui-1.5.1-blue.svg)](https://github.com/kotcrab/vis-ui) [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-vis.svg)](https://search.maven.org/artifact/io.github.libktx/ktx-vis) # KTX: VisUI type-safe builders @@ -348,31 +348,6 @@ Consider using [`ktx-actors`](../actors) module to improve event handling with l [`ktx-vis-style`](../vis-style) adds DSL for defining custom VisUI widget styles. -### Migration guide - -Since `1.9.10-b6`, `ktx-vis` extends the [`ktx-scene2d`](../scene2d) module. If you are migrating from a previous -`ktx-vis` version, see the `ktx-scene2d` migration guide first. - -Additionally to changes that apply to `ktx-scene2d`, `ktx-vis` was rewritten to match the `ktx-scene2d` API. -Notable changes include: - -* All factory methods for VisUI widgets are now inlined. -* `vis` prefix was added to the names of some VisUI widget factory methods to avoid clashes with Scene2D -and better reflect the widget class names. A complete list is available in the change log. -* 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. -* `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`. - -Since `ktx-vis` required a complete rewrite and had to match `ktx-scene2d` API, there is no intermediate version with -deprecated methods. All legacy APIs were removed in `1.9.10-b6`. Please refer to the [change log](../CHANGELOG.md) -for a complete list of changes. - -On top of that, `HorizontalFlowGroup` and `VerticalFlowGroup` are now deprecated in VisUI. While `ktx-vis` still -provides factory methods for these, they are deprecated - `flowGroup` with appropriate settings should be used instead. - ### Alternatives - Creating layouts with [VisUI](https://github.com/kotcrab/vis-editor/wiki/VisUI) directly in Kotlin or Java.