Released KTX 1.9.8-b2. #134

.github/CONTRIBUTORS.md

@@ -14,8 +14,10 @@ Project contributors listed chronologically.
 * [@Jkly](https://github.com/Jkly)
   * Author of the [`Ashley` module](../ashley).
   * Author of the [gdx-box2d-kotlin](https://github.com/Jkly/gdx-box2d-kotlin) library, which inspired the `Box2D` **KTX** module.
-  * Provided insightful review of the [`Box2D`](../box2d) module. Contributed ray casting utilities.
+  * Provided insightful review of the [`Box2D`](../box2d) module. Contributed ray casting and AABB query utilities.
 * [@keturn](https://github.com/keturn)
   * Suggested the [`FreeType` extension](../freetype).
 * [@TomGrill](https://github.com/TomGrill)
   * Contributed improvements to the [dependency injection module](../inject).
+* [@mrdlink](https://github.com/mrdlink)
+  * Contributed significant improvements to the [math module](../math).

CHANGELOG.md

@@ -1,3 +1,23 @@
+#### 1.9.8-b2
+
+- **[UPDATE]** Updated to Kotlin 1.2.30.
+- **[UPDATE]** Updated to Kotlin Coroutines 0.22.5.
+- **[UPDATE]** Updated to Dokka 0.9.16.
+- **[UPDATE]** Updated to Gradle 4.6.
+- **[FEATURE]** (`ktx-math`) `dot` and `x` infix functions added to `Vector2` and `Vector3` allow to calculate dot
+products and cross products of two vectors respectively.
+- **[FEATURE]** (`ktx-box2d`) Initiation blocks of `Body` in `World.body` extension method is now optional thanks to
+default lambda parameters in inlined functions.
+- **[FEATURE]** (`ktx-box2d`)  `World.query` extension method allowing to execute AABB query with idiomatic Kotlin.
+- **[CHANGE]** (`ktx-math`) Binary operators of `Vector2`, `Vector3`, `Matrix3` and `Matrix4` (`+`, `-`, `*`, `/`) no
+longer modify the first vector or matrix. Instead, they create new instances of vectors or matrices that store the
+operation result. Use the assign operators (`+=`, `-=`, `*=`, `/=`) instead to avoid creating new instances.
+- **[CHANGE]** (`ktx-math`) New mutating assign operators (`+=`, `-=`, `*=`, `/=`) were added to `Vector2`, `Vector3`,
+`Matrix3` and `Matrix4`.
+- **[CHANGE]** (`ktx-math`) Parameters of matrix vector multiplication operators are switched. `vector * matrix` does
+not exist anymore and now is available as `matrix * vector`.
+- **[CHANGE]** (`ktx-math`) Operators of `Matrix3` to left-multiply a `Vector3` were removed.
+
 #### 1.9.8-b1
 
 - **[UPDATE]** Updated to LibGDX 1.9.8.

README.md

@@ -1,6 +1,6 @@
 [![Travis CI](https://travis-ci.org/libktx/ktx.svg?branch=master)](https://travis-ci.org/libktx/ktx)
 [![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)
-[![Kotlin](https://img.shields.io/badge/kotlin-1.2.21-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.2.30-orange.svg)](http://kotlinlang.org/)
 [![LibGDX](https://img.shields.io/badge/libgdx-1.9.8-red.svg)](https://libgdx.badlogicgames.com/)
 
 [![KTX](.github/ktx-logo.png "KTX")](http://libktx.github.io)
@@ -10,7 +10,11 @@ _**K**o**t**lin utilities for LibGD**X** applications._
 ### About the project
 
 **KTX** aims to make [LibGDX](http://libgdx.badlogicgames.com/) as [Kotlin](http://kotlinlang.org/)-friendly as possible
-without turning the API upside down. This is **not** a new framework by any means - but Kotlin sure makes LibGDX feel like one.
+without turning the API upside down. It provides modular utilities for certain parts of LibGDX with poor Kotlin support.
+This is **not** a new framework by any means - but Kotlin certainly makes LibGDX feel like one.
+
+Do not confuse **KTX** with [`android-ktx`](https://github.com/android/android-ktx): an official Google project with
+Android utilities. "**KTX**" name was chosen long before the Android project was announced.
 
 ### Modules
 
@@ -35,20 +39,20 @@ Current **KTX** modules:
 - [log](log): minimal runtime overhead cross-platform logging using inlined blocks.
 - [math](math): operator overloads for LibGDX math API and general math utilities.
 - [scene2d](scene2d): type-safe Kotlin builders for `Scene2D` GUI.
-- [style](style): enhances `Skin` API with type-safe builders of official Scene2D widget styles. Replace your JSON skin file today!
+- [style](style): enhances `Skin` API with type-safe builders of official Scene2D widget styles. Replace your JSON skin file with type-safe DSL.
 - [vis](vis): type-safe Kotlin builders for `VisUI`. An _alternative_ to the [scene2d](scene2d) module.
 - [vis-style](vis-style): enhances `Skin` API with type-safe builders of `VisUI` widget styles. An _extension_ of [style](style) module.
 
 Note that most guides and examples assume that the reader is at least a bit familiar with the LibGDX API.
 
 Afraid to use some third-party code? Browse through the sources, run the test suites. While certainly not perfect, we try to keep to
-keep the public API clean and *every* features fully unit tested. *Reported code coverage may not be so impressive though, as the
-coverage tools are currently unable to calculate coverage of inlined methods. And there are plenty of these in some modules.*
+keep the public API clean and *every* feature fully unit tested. *Note: coverage tools still have problems with Kotlin
+inlined methods, so the reported code coverage might be much lower than the actual.*
 
 ### Dependencies
 
-**KTX** libraries are currently almost out of beta. While tested and stable enough, we want to give them a little bit more time
-and get some user feedback before a stable release. All versions are available through Maven Central and
+**KTX** libraries are currently in late beta. While tested and stable enough, we want to give them a little bit
+more time and get some user feedback before a stable release. All versions are available through Maven Central and
 [here](https://github.com/libktx/ktx/releases). You can also use the preview snapshot releases from
 `https://oss.sonatype.org/content/repositories/snapshots/` repository.
 

async/README.md

@@ -1,4 +1,4 @@
-[![Kotlin](https://img.shields.io/badge/kotlin--coroutines-0.22-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin--coroutines-0.22.5-orange.svg)](http://kotlinlang.org/)
 
 # KTX: coroutines support and threading utilities
 

box2d/README.md

@@ -37,6 +37,7 @@ with the following shapes:
   - `jointWith`: any `Joint` type supported by the custom `JointDef` passed as the method argument.
 - `earthGravity` is a constant that roughly matches Earth's gravity.
 - `World.rayCast` extension methods allow creating ray-cast callbacks with Kotlin lambda syntax.
+- `World.query` extension method allow creating AABB querying callbacks with Kotlin lambda syntax.
 
 ### Usage examples
 
@@ -285,6 +286,19 @@ fun createRayCast() {
 }
 ```
 
+Querying the world for fixtures overlapping an AABB:
+
+```Kotlin
+import ktx.box2d.*
+
+fun createQuery() {
+  world.query(lowerX = 0f, lowerY = 0f, upperX = 1f, upperY = 1f) { fixture ->
+    // Will be called when this query overlaps a fixture.
+    Query.CONTINUE
+  }
+}
+```
+
 #### Synergy
 
 Pair this library with [`ktx-math`](../math) for `Vector2` factory methods, operator overloads and other math-related

box2d/src/main/kotlin/ktx/box2d/worlds.kt

@@ -18,12 +18,12 @@ fun createWorld(gravity: Vector2 = Vector2.Zero, allowSleep: Boolean = true) = W
  * Type-safe [Body] building DSL.
  * @param type [BodyType] of the constructed [Body]. Matches LibGDX default of [BodyType.StaticBody].
  * @param init inlined. Invoked on a [BodyDefinition] instance, which provides access to [Body] properties, as well as
- *    fixture building DSL.
+ *    fixture building DSL. Defaults to no-op.
  * @return a fully constructed [Body] instance with all defined fixtures.
  * @see BodyDefinition
  * @see FixtureDefinition
  */
-inline fun World.body(type: BodyType = BodyType.StaticBody, init: BodyDefinition.() -> Unit): Body {
+inline fun World.body(type: BodyType = BodyType.StaticBody, init: BodyDefinition.() -> Unit = {}): Body {
   val bodyDefinition = BodyDefinition()
   bodyDefinition.type = type
   bodyDefinition.init()
@@ -152,3 +152,55 @@ fun World.rayCast(
     callback: KtxRayCastCallback) {
   rayCast(callback, startX, startY, endX, endY)
 }
+
+/**
+ * Query the world for all fixtures that potentially overlap the provided AABB (Axis-Aligned Bounding Box).
+ *
+ * @param lowerX the x coordinate of the lower left corner
+ * @param lowerY the y coordinate of the lower left corner
+ * @param upperX the x coordinate of the upper right corner
+ * @param upperY the y coordinate of the upper right corner
+ * @param callback a user implemented callback that is called for every fixture overlapping the AABB.
+ * @see Query
+ */
+fun World.query(
+    lowerX: Float,
+    lowerY: Float,
+    upperX: Float,
+    upperY: Float,
+    callback: KtxQueryCallback) {
+  QueryAABB(callback, lowerX, lowerY, upperX, upperY)
+}
+
+/**
+ * Stores constants that can be returned by [KtxQueryCallback] to control its behavior.
+ * @see query
+ */
+object Query {
+  /**
+   * Stop querying the world.
+   * @see KtxQueryCallback
+   */
+  const val STOP = false
+  /**
+   * Continue querying for the next match.
+   * @see KtxQueryCallback
+   */
+  const val CONTINUE = true
+}
+
+/**
+ * Callback lambda for querying with an AABB.
+ *
+ * This lambda is called for each fixture the AABB overlaps.
+ *
+ * There is no guarantee on the order of the callback is called.
+ *
+ * The lambda returns whether to terminate the query.
+ *
+ * Can be used in place of [com.badlogic.gdx.physics.box2d.QueryCallback] via Kotlin SAM conversion.
+ *
+ * @see Query
+ * @see query
+ */
+typealias KtxQueryCallback = (fixture: Fixture) -> Boolean

box2d/src/test/kotlin/ktx/box2d/jointsTest.kt

@@ -111,8 +111,8 @@ class JointsTest {
   @Test
   fun `should create GearJoint`() {
     val (bodyA, bodyB) = getBodies()
-    val jointA = bodyB.revoluteJointWith(bodyA) {}
-    val jointB = bodyA.revoluteJointWith(bodyB) {}
+    val jointA = bodyB.revoluteJointWith(bodyA)
+    val jointB = bodyA.revoluteJointWith(bodyB)
 
     val joint = bodyA.gearJointWith(bodyB) {
       joint1 = jointA
@@ -212,11 +212,11 @@ class JointsTest {
     val world = createWorld()
     val bodyA = world.body {
       position.set(-1f, 0f)
-      box(1f, 1f) {}
+      box(1f, 1f)
     }
     val bodyB = world.body {
       position.set(1f, 0f)
-      box(1f, 1f) {}
+      box(1f, 1f)
     }
     return bodyA to bodyB
   }

box2d/src/test/kotlin/ktx/box2d/worldsTest.kt

@@ -36,7 +36,7 @@ class WorldsTest : Box2DTest() {
   fun `should construct a Body`() {
     val world = createWorld()
 
-    val body = world.body { }
+    val body = world.body()
 
     assertNotNull(body)
     assertSame(world, body.world)
@@ -48,7 +48,7 @@ class WorldsTest : Box2DTest() {
   fun `should construct a Body of chosen BodyType`() {
     val world = createWorld()
 
-    val body = world.body(type = KinematicBody) { }
+    val body = world.body(type = KinematicBody)
 
     assertNotNull(body)
     assertSame(world, body.world)
@@ -175,7 +175,7 @@ class WorldsTest : Box2DTest() {
   @Test
   fun `should ray-cast between two vectors`() {
     val world = createWorld()
-    val expectedEdge = world.body {}.edge(from = Vector2.Zero, to = Vector2(0f, 2f)) {}
+    val expectedEdge = world.body().edge(from = Vector2.Zero, to = Vector2(0f, 2f))
     var called = false
 
     world.rayCast(Vector2(-1f, 1f), Vector2(1f, 1f)) { fixture, point, normal, fraction ->
@@ -194,7 +194,7 @@ class WorldsTest : Box2DTest() {
   @Test
   fun `should ray-cast between two coordinates`() {
     val world = createWorld()
-    val expectedEdge = world.body {}.edge(from = Vector2.Zero, to = Vector2(0f, 2f)) {}
+    val expectedEdge = world.body().edge(from = Vector2.Zero, to = Vector2(0f, 2f))
     var called = false
 
     world.rayCast(startX = -1f, startY = 1f, endX = 1f, endY = 1f) { fixture, point, normal, fraction ->
@@ -218,4 +218,53 @@ class WorldsTest : Box2DTest() {
     assertEquals(0f, RayCast.TERMINATE, tolerance)
     assertEquals(-1f, RayCast.IGNORE, tolerance)
   }
+
+  @Test
+  fun `should query for overlapping fixtures with AABB and stop`() {
+    val world = createWorld()
+    val matchingEdge1 = world.body().edge(from = Vector2.Zero, to = Vector2(0f, 2f))
+    val matchingEdge2 = world.body().edge(from = Vector2(1f, 0f), to = Vector2(1f, 2f))
+    val matchedFixtures = mutableSetOf<Fixture>()
+
+    world.query(lowerX = -1f, lowerY = 1f, upperX = 1f, upperY = 1f) { fixture ->
+      matchedFixtures += fixture
+      Query.STOP
+    }
+
+    assertEquals(1, matchedFixtures.size)
+    assertTrue(matchedFixtures.contains(matchingEdge1) || matchedFixtures.contains(matchingEdge2))
+    world.dispose()
+  }
+
+  @Test
+  fun `should query for overlapping fixtures with AABB and continue`() {
+    val world = createWorld()
+    val matchingEdge1 = world.body().edge(from = Vector2.Zero, to = Vector2(0f, 2f))
+    val matchingEdge2 = world.body().edge(from = Vector2(1f, 0f), to = Vector2(1f, 2f))
+    val matchedFixtures = mutableSetOf<Fixture>()
+
+    world.query(lowerX= -1f, lowerY = 1f, upperX = 1f, upperY = 1f) { fixture ->
+      matchedFixtures += fixture
+      Query.CONTINUE
+    }
+
+    assertEquals(setOf(matchingEdge1, matchingEdge2), matchedFixtures)
+    world.dispose()
+  }
+
+  @Test
+  fun `should query world and not callback if there are no fixtures overlapping the AABB`() {
+    val world = createWorld()
+    world.body().edge(from = Vector2.Zero, to = Vector2(0f, 2f))
+    world.body().edge(from = Vector2(1f, 0f), to = Vector2(1f, 2f))
+    val matchedFixtures = mutableSetOf<Fixture>()
+
+    world.query(lowerX= -2f, lowerY = 1f, upperX = -1f, upperY = 1f) { fixture ->
+      matchedFixtures += fixture
+      Query.CONTINUE
+    }
+
+    assertTrue(matchedFixtures.isEmpty())
+    world.dispose()
+  }
 }

gradle.properties

@@ -1,7 +1,7 @@
 libGroup=io.github.libktx
 gdxVersion=1.9.8
-kotlinVersion=1.2.21
-kotlinCoroutinesVersion=0.22
+kotlinVersion=1.2.30
+kotlinCoroutinesVersion=0.22.5
 
 ashleyVersion=1.7.3
 visUiVersion=1.4.0
@@ -15,7 +15,7 @@ junitPlatformVersion=1.0.2
 slf4jVersion=1.7.25
 wireMockVersion=2.7.1
 
-dokkaVersion=0.9.15
+dokkaVersion=0.9.16
 nexusPluginVersion=0.5.3
 configurationsPluginVersion=3.0.3
 

gradle/wrapper/gradle-wrapper.properties

@@ -1,5 +1,5 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.6-all.zip
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-4.4-all.zip