KTX 1.12.1-rc2 release. #489

.github/CONTRIBUTORS.md

@@ -5,7 +5,7 @@ Project contributors listed chronologically.
 * [@czyzby](https://github.com/czyzby)
   * Author of most of the libraries, main maintainer.
 * [@kotcrab](https://github.com/kotcrab)
-  * Author of the [`VisUI` extension](../vis).
+  * Author of the initial iteration of the [`VisUI` extension](../vis).
 * [@MrPlow442](https://github.com/MrPlow442)
   * Contributed libGDX [collections](../collections) utilities.
 * [@sreich](https://github.com/sreich)
@@ -42,11 +42,11 @@ Project contributors listed chronologically.
   * Prepared several KTX template projects and showcases.
   * Improved [app](../app) utilities.
 * [@Quillraven](https://github.com/Quillraven)
-  * Author of the [Tiled](../tiled) module.
-  * Contributed [actors](../actors), [ashley](../ashley) and [collections](../collections) utilities.
-  * Wrote a complete [KTX tutorial](https://github.com/Quillraven/SimpleKtxGame/wiki) based on the original libGDX introduction.
-  * Author of the [preferences](../preferences) module.
+  * Author of the [Tiled](../tiled) and [preferences](../preferences) modules.
+  * Contributed [actors](../actors), [ashley](../ashley), [collections](../collections), [math](../math), and [scene2d](../scene2d) utilities.
+  * Wrote a complete [KTX tutorial](https://github.com/Quillraven/SimpleKtxGame/wiki) based on the original libGDX introduction app.
   * Tested and reviewed the [assets async](../assets-async) module.
+  * Creator of a [Youtube channel](https://www.youtube.com/c/Quillraven/videos) on Kotlin game development including several tutorials with KTX.
 * [@FocusPo1nt](https://github.com/FocusPo1nt)
   * Added utilities to [style module](../style).
 * [@maltaisn](https://github.com/maltaisn)
@@ -108,3 +108,5 @@ Project contributors listed chronologically.
 ### Metrics
 
 See [the GitHub insights](https://github.com/libktx/ktx/graphs/contributors).
+
+![Star history](https://api.star-history.com/svg?repos=libktx/ktx&type=Date)

.github/workflows/build.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        java-version: [8, 11, 17]
+        java-version: [11, 17]
 
     steps:
     - name: Repository checkout

.github/workflows/upload-snapshot.yml

@@ -14,7 +14,7 @@ jobs:
       - name: JDK setup
         uses: actions/setup-java@v3
         with:
-          java-version: 8
+          java-version: 11
           distribution: temurin
       - name: Gradle setup
         uses: gradle/gradle-build-action@v2

CHANGELOG.md

@@ -1,13 +1,33 @@
 _See also: [the official libGDX changelog](https://github.com/libgdx/libgdx/blob/master/CHANGES)._
 
+#### 1.12.1-rc2
+
+- **[UPDATE]** Updated to Kotlin 1.9.25.
+- **[UPDATE]** Updated to Kotlin Coroutines 1.8.1.
+- **[UPDATE]** Updated to Gradle 7.6.4.
+- **[UPDATE]** Updated to Dokka 1.9.20.
+- **[MISC]** JDK 11 or newer is now required to build the KTX project.
+- **[CHANGE]** (`ktx-assets`) The `pool` factory method now attempts to reset `Poolable` objects with the default `discard` lambda
+  to match the default libGDX pool behavior. Pass a custom function to override it.
+- **[FEATURE]** (`ktx-math`) Added component deconstructing operators for 2D shapes:
+  - `Rectangle`: _x, y, width, height_
+  - `Ellipse`: _x, y, width, height_
+  - `Circle`: _x, y, radius_
+  - `Polygon`: _x, y_
+  - `Polyline`: _x, y_
+- **[CHANGE]** (`ktx-scene2d`) `image` factory method can now be called without parameters or with `null` to create
+  an `Image` without a `Drawable`.
+- **[FEATURE]** (`ktx-tiled`) Added `use` extension method to `BatchTiledMapRenderer` that
+  automatically calls `beginRender()` and `endRender()`.
+
 #### 1.12.1-rc1
 
 - **[UPDATE]** Updated to libGDX 1.12.1.
 - **[UPDATE]** Updated to Kotlin 1.9.20.
 - **[UPDATE]** Updated to Kotlin Coroutines 1.7.3.
 - **[UPDATE]** Updated to VisUI 1.5.3.
 - **[UPDATE]** Updated to Dokka 1.9.10.
-- **[FEATURE]** (`ktx-math`) New extension and factory function were introduced to `Vector4`, offering similar utilities to other vectors.
+- **[FEATURE]** (`ktx-math`) New extension and factory functions were introduced to `Vector4`, offering similar utilities to the other vectors.
   - `vec4` factory methods allow creating new `Vector4` instances with default and named parameters.
   - `+=`, `-=`, `*=`, `/=` mutating operators are now supported.
   - `+`, `-` (including unary `-`), `++`, `--`, `*`, `/` operators are now supported, returning new instances of vectors as a result.

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.9.20-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.9.25-orange.svg)](http://kotlinlang.org/)
 [![libGDX](https://img.shields.io/badge/libgdx-1.12.1-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)
 
@@ -221,7 +221,7 @@ with the `ktx-app` identifier would require the following changes in your `build
 // Groovy DSL:
 ext {
   // Update this version to match the latest KTX release:
-  ktxVersion = '1.12.1-rc1'
+  ktxVersion = '1.12.1-rc2'
 }
 
 dependencies {
@@ -235,7 +235,7 @@ dependencies {
 
 ```kotlin
 // Update this version to match the latest KTX release:
-val ktxVersion = "1.12.1-rc1"
+val ktxVersion = "1.12.1-rc2"
 
 dependencies {
   api(group = "io.github.libktx", name = "ktx-app", version = ktxVersion)

assets/src/main/kotlin/ktx/assets/pools.kt

@@ -2,6 +2,7 @@ package ktx.assets
 
 import com.badlogic.gdx.utils.Disposable
 import com.badlogic.gdx.utils.Pool
+import com.badlogic.gdx.utils.Pool.Poolable
 
 /**
  * Allows to use a [Pool] instance as a functional object. When invoked with no parameters, [Pool] will provide an
@@ -14,7 +15,7 @@ operator fun <Type> Pool<Type>.invoke(): Type = this.obtain()
 /**
  * Allows to use a [Pool] instance as a functional object. When invoked with a parameter, [Pool] will treat the passed
  * parameter as an object freed to the pool.
- * @param free will be returned to the pool. Might be reset if it implements the Poolable interface.
+ * @param free will be returned to the pool. Might be reset if it implements the [Poolable] interface.
  * @see Pool.free
  */
 operator fun <Type> Pool<Type>.invoke(free: Type) = this.free(free)
@@ -24,14 +25,19 @@ operator fun <Type> Pool<Type>.invoke(free: Type) = this.free(free)
  * @param max max amount stored in the pool. When exceeded, freed objects are no longer accepted.
  * @param discard invoked each time an object is rejected or removed from the pool. This might happen if an object is
  * freed with [Pool.free] or [Pool.freeAll] if the pool is full, or when [Pool.clear] is called. Optional, defaults
- * to no operation. If the objects are [Disposable], this lambda might be used to dispose of them.
+ * to resetting the objects implementing the [Poolable] interface to replicate the default behavior. If the objects are
+ * [Disposable], this lambda should be used to dispose of them.
  * @param provider creates instances of the requested objects.
  * @return a new [Pool] instance, creating the object with the passed provider.
  */
 inline fun <Type> pool(
   initialCapacity: Int = 16,
   max: Int = Int.MAX_VALUE,
-  crossinline discard: (Type) -> Unit = {},
+  crossinline discard: (Type) -> Unit = {
+    if (it is Poolable) {
+      it.reset()
+    }
+  },
   crossinline provider: () -> Type,
 ): Pool<Type> =
   object : Pool<Type>(initialCapacity, max) {

assets/src/test/kotlin/ktx/assets/PoolsTest.kt

@@ -1,9 +1,11 @@
 package ktx.assets
 
 import com.badlogic.gdx.utils.Pool
+import com.badlogic.gdx.utils.Pool.Poolable
 import org.junit.Assert.assertEquals
 import org.junit.Assert.assertNotNull
 import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
 import org.junit.Test
 
 /**
@@ -76,6 +78,30 @@ class PoolsTest {
     assertEquals(listOf("Value6", "Value7", "Value8", "Value9", "Value10"), discarded)
   }
 
+  @Test
+  fun `should create new pools that reset discarded objects by default`() {
+    // Given:
+    val pool = pool(max = 1) { SamplePoolable() }
+    val freed = pool()
+    val discarded = pool()
+    pool.free(freed)
+
+    // When:
+    pool.free(discarded)
+
+    // Then:
+    assertTrue(discarded.isReset)
+  }
+
+  /**
+   * A simple data object implementing the [Poolable] interface.
+   */
+  private class SamplePoolable(var isReset: Boolean = false) : Poolable {
+    override fun reset() {
+      this.isReset = true
+    }
+  }
+
   /**
    * Provides new [Any] instances.
    */

async/README.md

@@ -1,4 +1,4 @@
-[![Kotlin Coroutines](https://img.shields.io/badge/kotlin--coroutines-1.7.3-orange.svg)](http://kotlinlang.org/)
+[![Kotlin Coroutines](https://img.shields.io/badge/kotlin--coroutines-1.8.1-orange.svg)](http://kotlinlang.org/)
 [![Maven Central](https://img.shields.io/maven-central/v/io.github.libktx/ktx-async.svg)](https://search.maven.org/artifact/io.github.libktx/ktx-async)
 
 # KTX: Coroutines support and parallelization utilities

build.gradle.kts

@@ -81,6 +81,8 @@ subprojects {
       freeCompilerArgs += "-opt-in=kotlin.RequiresOptIn"
     }
   }
+  val compileTestKotlin: KotlinCompile by tasks
+  compileTestKotlin.kotlinOptions.jvmTarget = JavaVersion.VERSION_11.toString()
 
   dependencies {
     val kotlinVersion: String by project

buildSrc/src/main/kotlin/ktx/Versions.kt

@@ -1,7 +1,7 @@
 package ktx
 
 const val gdxVersion = "1.12.1"
-const val kotlinCoroutinesVersion = "1.7.3"
+const val kotlinCoroutinesVersion = "1.8.1"
 
 const val artemisOdbVersion = "2.3.0"
 const val ashleyVersion = "1.7.4"
@@ -10,9 +10,9 @@ const val visUiVersion = "1.5.3"
 
 const val spekVersion = "1.1.5"
 const val kotlinTestVersion = "2.0.7"
-const val kotlinMockitoVersion = "4.1.0"
-const val assertjVersion = "3.11.1"
-const val junitVersion = "4.12"
-const val slf4jVersion = "1.7.26"
-const val wireMockVersion = "2.24.0"
+const val kotlinMockitoVersion = "5.4.0"
+const val assertjVersion = "3.26.3"
+const val junitVersion = "4.13.2"
+const val slf4jVersion = "1.7.36"
+const val wireMockVersion = "2.27.2"
 const val ktlintVersion = "0.50.0"

gradle.properties

@@ -1,8 +1,8 @@
 libGroup=io.github.libktx
 
-kotlinVersion=1.9.20
+kotlinVersion=1.9.25
 
-dokkaVersion=1.9.10
+dokkaVersion=1.9.20
 junitPlatformVersion=1.2.0
 configurationsPluginVersion=3.0.3
 

gradle/wrapper/gradle-wrapper.properties

@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.1-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.6.4-all.zip
 networkTimeout=10000
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists

math/README.md

@@ -240,6 +240,15 @@ val spawners = listOf(
 )
 ```
 
+#### `Shape2D` extensions
+
+- `Rectangle` and `Ellipse` instances can be destructed to four float variables in one step with
+  `val (x, y, w, h) = rectangle/ellipse` syntax thanks to `component1()`, `component2()`, `component3()` and `component4()` operator methods.
+- `Circle` instances can be destructed to three float variables in one step with
+  `val (x, y, radius) = circle` syntax thanks to `component1()`, `component2()` and `component3()` operator methods.
+- `Polygon` and `Polyline` instances can be destructed to two float variables in one step with
+  `val (x, y) = polygon/polyline` syntax thanks to `component1()` and `component2()` operator methods.
+
 ### Alternatives
 
 You can use libGDX APIs directly or rely on third-party math libraries:

math/src/main/kotlin/ktx/math/circle.kt

@@ -0,0 +1,21 @@
+package ktx.math
+
+import com.badlogic.gdx.math.Circle
+
+/**
+ * Operator function that allows to deconstruct this circle.
+ * @return X component.
+ */
+operator fun Circle.component1() = this.x
+
+/**
+ * Operator function that allows to deconstruct this circle.
+ * @return Y component.
+ */
+operator fun Circle.component2() = this.y
+
+/**
+ * Operator function that allows to deconstruct this circle.
+ * @return Radius component.
+ */
+operator fun Circle.component3() = this.radius

math/src/main/kotlin/ktx/math/ellipse.kt

@@ -0,0 +1,27 @@
+package ktx.math
+
+import com.badlogic.gdx.math.Ellipse
+
+/**
+ * Operator function that allows to deconstruct this ellipse.
+ * @return X component.
+ */
+operator fun Ellipse.component1() = this.x
+
+/**
+ * Operator function that allows to deconstruct this ellipse.
+ * @return Y component.
+ */
+operator fun Ellipse.component2() = this.y
+
+/**
+ * Operator function that allows to deconstruct this ellipse.
+ * @return Width component.
+ */
+operator fun Ellipse.component3() = this.width
+
+/**
+ * Operator function that allows to deconstruct this ellipse.
+ * @return Height component.
+ */
+operator fun Ellipse.component4() = this.height

math/src/main/kotlin/ktx/math/polygon.kt

@@ -0,0 +1,15 @@
+package ktx.math
+
+import com.badlogic.gdx.math.Polygon
+
+/**
+ * Operator function that allows to deconstruct this polygon.
+ * @return X component.
+ */
+operator fun Polygon.component1() = this.x
+
+/**
+ * Operator function that allows to deconstruct this polygon.
+ * @return Y component.
+ */
+operator fun Polygon.component2() = this.y

math/src/main/kotlin/ktx/math/polyline.kt

@@ -0,0 +1,15 @@
+package ktx.math
+
+import com.badlogic.gdx.math.Polyline
+
+/**
+ * Operator function that allows to deconstruct this polyline.
+ * @return X component.
+ */
+operator fun Polyline.component1() = this.x
+
+/**
+ * Operator function that allows to deconstruct this polyline.
+ * @return Y component.
+ */
+operator fun Polyline.component2() = this.y

math/src/main/kotlin/ktx/math/rectangle.kt

@@ -0,0 +1,27 @@
+package ktx.math
+
+import com.badlogic.gdx.math.Rectangle
+
+/**
+ * Operator function that allows to deconstruct this rectangle.
+ * @return X component.
+ */
+operator fun Rectangle.component1() = this.x
+
+/**
+ * Operator function that allows to deconstruct this rectangle.
+ * @return Y component.
+ */
+operator fun Rectangle.component2() = this.y
+
+/**
+ * Operator function that allows to deconstruct this rectangle.
+ * @return Width component.
+ */
+operator fun Rectangle.component3() = this.width
+
+/**
+ * Operator function that allows to deconstruct this rectangle.
+ * @return Height component.
+ */
+operator fun Rectangle.component4() = this.height

math/src/test/kotlin/ktx/math/CircleTest.kt

@@ -0,0 +1,20 @@
+package ktx.math
+
+import com.badlogic.gdx.math.Circle
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+class CircleTest {
+
+  @Test
+  fun `should destructure Circle`() {
+    val circle = Circle(1f, 2f, 3f)
+
+    val (x, y, radius) = circle
+
+    assertEquals(1f, x)
+    assertEquals(2f, y)
+    assertEquals(3f, radius)
+  }
+
+}