Merged 1.9.6-b3 release.

.github/CONTRIBUTING.md

@@ -1,34 +1,35 @@
 ## Issues
 
 - Before submitting a bug-related issue, make sure that **its source is not the LibGDX itself**.
-- It is fine to create issues with simple questions and documentation improvement requests. In fact, issues are among
-the fastest way to contact the developers.
+- Issues are among the fastest way to contact the developers. It is fine to create issues with feature requests and
+questions about the library.
 
 ## Pull requests
 
-- The latest changes are always in the `develop` branch. `master` branch is frozen between releases. Make sure to
-checkout `develop` branch before starting your work and set `develop` as the target branch before creating a pull
-request.
+- The latest changes are always in the `develop` branch. `master` branch always matches the latest stable release. Make
+sure to checkout `develop` branch before starting your work and set `develop` as the target branch before creating
+a pull request.
 - Use IntelliJ Kotlin [code formatter](../intellij-formatter.xml) included in the root directory.
-- Make sure to include unit tests of your code. Older tests are not idiomatic Kotlin code and were written with vanilla
-JUnit and Mockito - all new tests should use [KotlinTest](https://github.com/kotlintest/kotlintest) framework along with
+- Make sure to include unit tests of your code. Test names should use the `` `backtick method name` `` syntax.
+JUnit and [KotlinTest](https://github.com/kotlintest/kotlintest) can be used to write tests. Use
 [Mockito-Kotlin](https://github.com/nhaarman/mockito-kotlin) for mocking.
-- If your pull request is not a simple bug fix or small utility, make sure to link it to an existing issue (or create
-an issue with your proposal first). API changes or new modules have to be discussed with the maintainers first.
+- If your pull request is not a simple bug fix or small utility, make sure to link it to an existing issue or create
+an issue with your proposal first. API changes or new modules have to be discussed with the maintainers first.
 - All notable changes should be added to the [changelog](../CHANGELOG.md) with an appropriate label:
   - **[FEATURE]** - a new functionality.
   - **[CHANGE]** - breaking API change.
   - **[UPDATE]** - update of one of project dependencies.
   - **[FIX]** - bug fix.
-- Some libraries (like `ktx-collections` or `ktx-math`) list all of the features in their `README.md` files to ease
-their usage. When adding new feature to these projects, please add description of your change to the file. Also, add
-all necessary imports in KTX examples in `README.md` files to make it easier to try them out.
+- Some libraries (like `ktx-collections` or `ktx-math`) list _all_ features in the `README.md` files to ease their
+usage. When adding new feature to these projects, please add description of your change to the file. Also, add all
+necessary imports in KTX examples in `README.md` files to make it easier to try them out.
 
 ## Working from sources
 
 ```bash
-git clone https://github.com/czyzby/ktx.git
+git clone https://github.com/libktx/ktx.git
 cd ktx
+git checkout develop
 ```
 
 ### Build tool
@@ -50,12 +51,12 @@ case of a non-snapshot upload to Maven Central.
 
 Releasing a new KTX version:
 
-- Change `libVersion` settings in `gradle.properties`. KTX uses the same versioning schema as LibGDX (mimicking the
+- Change `libVersion` settings in `version.txt`. KTX uses the same versioning schema as LibGDX (mimicking the
 LibGDX version that it was compiled against) with optional `-b#` or `-SNAPSHOT` suffixes depending on version status.
-- Run `gradle build install uploadArchives closeAndPromoteRepository` to push artifacts to both Maven Local and
-Maven Central.
+- Run `gradle build install uploadArchives closeAndPromoteRepository` to push artifacts to both _Maven Local_ and
+_Maven Central_.
 - Run `gradle distZip` to prepare archive with KTX sources, compiled binary and documentation.
-- Upload the archive to [releases](https://github.com/czyzby/ktx/releases) section. Tag should match released version.
+- Upload the archive to [releases](https://github.com/libktx/ktx/releases) section. Tag should match released version.
 Name of the release should match `KTX $libVersion`. Copy latest [changelog](../CHANGELOG.md) entries to release
 description. Note that a release is not necessary for snapshot versions.
 

.github/CONTRIBUTORS.md

@@ -1,4 +1,15 @@
+Project contributors listed chronologically.
+
 * [@czyzby](https://github.com/czyzby)
   * Author of most libraries, main maintainer.
 * [@kotcrab](https://github.com/kotcrab)
-  * Author of `VisUI` extension.
+  * Author of [`VisUI`](../vis) extension.
+* [@MrPlow442](https://github.com/MrPlow442)
+  * Contributed LibGDX [collections](../collections) utilities.
+* [@sreich](https://github.com/sreich)
+  * Contributed various utilities from [Ore Infinium](https://github.com/sreich/ore-infinium) project.
+* [@raincole](https://github.com/raincole)
+  * Provided insightful review of the [`Async`](../async) module.
+* [@Jkly](https://github.com/Jkly)
+  * Author of [gdx-box2d-kotlin](https://github.com/Jkly/gdx-box2d-kotlin), which inspired the `Box2D` **KTX** library.
+    Provided insightful review of the [`Box2D`](../box2d) module.

CHANGELOG.md

@@ -1,3 +1,34 @@
+#### 1.9.6-SNAPSHOT
+
+- **[UPDATE]** Updated to Kotlin 1.1.2.
+- **[UPDATE]** Updated to Kotlin Coroutines to 0.15.
+- **[CHANGE]** (`ktx-assets`) Static `AssetManager` instance container - `Assets` - was removed. All top level functions
+depending on the global `AssetManager` were removed.
+- **[FEATURE]** (`ktx-assets`) Added `FileType.getResolver` extension method creating `FileHandleResolver` instances.
+- **[FEATURE]** (`ktx-assets`) Added `FileHandleResolver.withPrefix` extension method decorating resolvers with `PrefixFileHandleResolver`.
+- **[FEATURE]** (`ktx-assets`) Added `FileHandleResolver.forResolutions` extension method decorating resolvers with `ResolutionFileResolver`.
+- **[FEATURE]** (`ktx-assets`) Added `resolution` function constructing `ResolutionFileResolver.Resolution` instances.
+- **[FEATURE]** (`ktx-async`) Added `AssetStorage`: a lightweight coroutines-based alternative to `AssetManager`.
+- **[FEATURE]** (`ktx-box2d`) Implemented a new **KTX** module with Box2D physics engine utilities: `ktx-box2d`.
+  - `world` factory method constructing `World` instances.
+  - `World.body` extension method providing type-safe builder DSL for `Body` instances.
+  - `FixtureDef` builder methods supporting all shapes (`CircleShape`, `PolygonShape`, `ChainShape`, `EdgeShape`).
+  - `FixtureDef.filder` extension methods simplifying `Filter` properties setup.
+  - `BodyDefinition` is a `BodyDef` extension providing `Body` building DSL. Used internally by `World.body`.
+  - `FixtureDefinition` is a `FixtureDef` extension providing `Fixture` building DSL. Used internally by `BodyDefinition`.
+  - `fixture`, `circle`, `box`, `polygon`, `chain`, `loop` and `edge` extension `Fixture` building methods added to `Body`.
+  - `earthGravity` property allowing to set `World` gravity roughly matching Earth's gravity.
+  - `onCreate` callbacks in `BodyDefinition` and `FixtureDefinition` giving access to built `Body` and `Fixture` instances in building blocks.
+  - `Body` extension methods that ease creation of `Joint` instances between 2 bodies: `jointWith`, `gearJointWith`,
+    `ropeJointWith`, `weldJointWith`, `motorJointWith`, `mouseJointWith`, `wheelJointWith`, `pulleyJointWith`,
+    `distanceJointWith`, `frictionJointWith`, `revoluteJointWith`, `prismaticJointWith`.
+- **[CHANGE]** (`ktx-i18n`) Static `I18NBundle` instance container - `I18n` - was removed.
+- **[CHANGE]** (`ktx-i18n`) Top level `nls` functions were removed.
+- **[FEATURE]** (`ktx-i18n`) `nls` property and method added to `BundleLine` for extra readability.
+- **[CHANGE]** (`ktx-inject`) Static `Context` instance container was removed. All top level functions depending on the
+global `Context` were removed.
+- **[FEATURE]** (`ktx-inject`) `Context.register` builder method added to ease context initiation process.
+
 #### 1.9.6-b2
 
 - **[UPDATE]** Updated to Kotlin 1.1.1.

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.1.1-orange.svg)](http://kotlinlang.org/)
+[![Kotlin](https://img.shields.io/badge/kotlin-1.1.2--3-orange.svg)](http://kotlinlang.org/)
 [![LibGDX](https://img.shields.io/badge/libgdx-1.9.6-red.svg)](https://libgdx.badlogicgames.com/)
 
 [![KTX](.github/ktx-logo.png "KTX")](http://libktx.github.io)
@@ -25,6 +25,7 @@ Current **KTX** modules:
 - [app](app): `ApplicationListener` abstract implementations and other general LibGDX application utilities.
 - [assets](assets): resources management utilities.
 - [async](async): [coroutines](https://kotlinlang.org/docs/reference/coroutines.html) context based on LibGDX threading model.
+- [box2d](box2d): `Box2D` physics engine utilities.
 - [collections](collections): extensions for LibGDX custom collections. Based on Kotlin standard library utilities.
 - [i18n](i18n): some simple extensions that make LibGDX internationalization API less verbose, safer and easier to use.
 - [inject](inject): unsettlingly simple dependency injection with nearly zero runtime overhead and no reflection trickery.
@@ -57,11 +58,11 @@ compile "io.github.libktx:ktx-$module:$ktxVersion"
 Replace `$module` with the name of required **KTX** library. `$ktxVersion` usually matches LibGDX version it was
 compiled against - although it might end with `-b1` (if it is a beta release) or `-SNAPSHOT` (if you are using
 the snapshots). For example, the first official beta release with the recent group ID was compiled against LibGDX
-`1.9.6`, so it was named `1.9.6-b2`. You can browse through our releases
-[here](https://search.maven.org/#search%7Cga%7C1%7Cktx).
+`1.9.6` and its version was `1.9.6-b2`. You can browse through our releases
+[here](https://search.maven.org/#search%7Cga%7C1%7Cg%3A%22io.github.libktx%22).
 
-Note that even snapshots should be more or less stable, as libraries are not pushed to Maven Central if they do not pass
-the unit tests.
+Note that even snapshots should be more or less stable, as libraries are not pushed to _Maven Central_ unless they pass
+the extensive tests.
 
 ### Documentation
 
@@ -72,5 +73,4 @@ directories in root folder to find out more about each library.
 
 If you want to help, read the [contribution](.github/CONTRIBUTING.md) guideline and browse through the issues to see
 what's currently to do. Don't be afraid to create issues just to ask a question or make a request for any kind of
-improvements. Before creating any pull requests, be aware that the code is dedicated to
-[public domain](LICENSE.txt).
+improvements. Before creating any pull requests, be aware that the code is dedicated to [public domain](LICENSE.txt).

actors/src/test/kotlin/kts/actors/eventsTest.kt

@@ -17,7 +17,7 @@ import org.junit.Test
 /**
  * Tests events and listeners utilities.
  */
-@Suppress("UNUSED_PARAMETER") // Unused lambda parameters showcase the listeners API.
+@Suppress("UNUSED_PARAMETER", "UNUSED_ANONYMOUS_PARAMETER") // Unused lambda parameters showcase the listeners API.
 class EventsTest {
   @Test
   fun `should attach ChangeListener`() {

app/src/test/kotlin/ktx/app/graphicsTest.kt

@@ -5,11 +5,11 @@ import com.badlogic.gdx.graphics.Color
 import com.badlogic.gdx.graphics.GL20
 import com.badlogic.gdx.graphics.g2d.Batch
 import com.badlogic.gdx.graphics.glutils.ShaderProgram
+import com.nhaarman.mockito_kotlin.never
+import com.nhaarman.mockito_kotlin.verify
 import io.kotlintest.mock.mock
 import org.junit.Assert.*
 import org.junit.Test
-import org.mockito.Mockito.never
-import org.mockito.Mockito.verify
 
 /**
  * Tests general utilities related to LibGDX graphics API.

assets/README.md

@@ -15,7 +15,7 @@ for the existing API to make assets usage more natural in Kotlin applications.
 - `AssetManager.load` extension method can be used to schedule asynchronous loading of an asset. It returns an asset
 wrapper, which can be used as delegate property, as well as used directly to manage the asset. Usually the asset will
 not be available until `AssetManager.finishLoading` or looped `AssetManager.update` are called. You can use string file
-paths or `AssetDescriptor` instances to load the asset. Typical usage:
+paths or `AssetDescriptor` instances to load the asset. Usage example:
 ```Kotlin
 // Eagerly loading an asset:
 val wrapper = load<Texture>("test.png")
@@ -30,21 +30,25 @@ class Test(assetManager: AssetManager) {
 ```
 - `AssetManager.getAsset` utility extension method can be used to access an already loaded asset, without having to pass
 class to the manager to specify asset type. This is the preferred way of accessing assets from the `AssetManager`,
-provided that they were already scheduled for asynchronous loading and fully loaded. Typical usage:
-`val texture: Texture = assetManager.getAsset("test.png")`. Note that this method will fail if asset is not loaded yet.
+provided that they were already scheduled for asynchronous loading and fully loaded. Note that this method will fail if
+asset is not loaded yet. Usage example:
+```Kotlin
+val texture: Texture = assetManager.getAsset("test.png")
+```
+
 - `AssetManager.loadOnDemand` is similar to the `load` utility method, but it provides an asset wrapper that loads the
 asset eagerly on first get call. It will not schedule the asset for asynchronous loading - instead, it will block current
 thread until the asset is loaded on the first access. Use for lightweight assets that should be (rarely) loaded only when
-requested. Typical usage:
+requested. Usage example:
 ```Kotlin
 // Eagerly loading an asset:
 val texture = by assetManager.loadOnDemand<Texture>("test.png")
 // Asset will be loaded upon first `texture` usage.
 
 // Delegate field:
 class Test(assetManager: AssetManager) {
-  val texture by assetManager.loadOnDemand<Texture>("test.png")
-  // Type of texture property is Texture. It will be loaded on first `texture` access.
+  val texture: Texture by assetManager.loadOnDemand("test.png")
+  // Asset will be loaded on first `texture` access.
 }
 ```
 - `AssetManager.unloadSafely` is a utility method that attempts to unload an asset from the `AssetManager`. Contrary to
@@ -54,13 +58,9 @@ loaded in the first place. Typical usage: `assetManager.unloadSafely("test.png")
 exception thrown during reloading. Note that `AssetManager` can throw `GdxRuntimeException` if the asset was not loaded yet.
 - `AssetManager.getLoader` and `setLoader` extension methods with reified types added to ease handling of `AssetLoader`
 instances registered in the `AssetManager`.
-- Global `AssetManager` instance is accessible (and modifiable) through `Assets.manager` utility field. Since it is
-advised to share and reuse a single `AssetManager` instance in the application and LibGDX already goes crazy with the
-statics thanks to `Gdx.files` and whatnot, this `AssetManager` instance was added to reduce asset-related boilerplate.
-If a utility asset loading (or accessing) method accepts an `AssetManager` instance, this global manager will be used by
-default to save you the trouble of getting your `AssetManager` manually. Its usage is completely optional and
-you can omit it entirely, while still benefiting from asset loading utility methods. **Note: global `AssetManager`
-instance has been deprecated in `1.9.6-b2` and will be removed after the next release.**
+
+Note: if you can use coroutines in your project, [`ktx-async`](../async) module provides a lightweight coroutines-based
+alternative to `AssetManager` that can greatly simplify your asset loading code.
 
 ##### Implementation tip: type-safe assets
 
@@ -131,6 +131,17 @@ method with a pleasant Kotlin syntax.
 - `file` utility function allows to quickly obtain a `FileHandle` instance. It features an optional `type` parameter
 which allows to choose the `FileType`, while defaulting to the most common `Internal`.
 
+#### `FileHandleResolver`
+
+- `FileType.getResolver` extension method was added to quickly construct `FileHandleResolver` instances for the chosen
+file types.
+- `FileHandleResolver.withPrefix` extension method was added to ease decoration of `FileHandleResolver` instances with
+`PrefixFileHandleResolver`.
+- `FileHandleResolver.forResolutions` extension method was added to ease decoration of `FileHandleResolver` instances
+with `ResolutionFileResolver`.
+- `resolution` factory function was added to construct `ResolutionFileResolver.Resolution` instances with idiomatic
+Kotlin syntax.
+
 ### Usage examples
 
 Obtaining `FileHandle` instances:
@@ -187,7 +198,7 @@ import ktx.assets.*
 import com.badlogic.gdx.assets.AssetManager
 
 class MyClass(assetManager: AssetManager) {
-  val image by load<Texture>("image.png")
+  val image by assetManager.load<Texture>("image.png")
   // image is Texture == true
 }
 ```
@@ -236,6 +247,35 @@ assetManager.setLoader(myCustomLoader) // No need to pass class.
 val loader = assetManager.getLoader<MyAsset>()
 ```
 
+Creating an `InternalFileHandleResolver`:
+
+```Kotlin
+import ktx.assets.getResolver
+import com.badlogic.gdx.Files.FileType
+
+val resolver = FileType.Internal.getResolver()
+```
+
+Decorating `FileHandleResolver` with `PrefixFileHandleResolver`:
+
+```Kotlin
+import ktx.assets.*
+import com.badlogic.gdx.Files.FileType
+
+val resolver = FileType.Internal.getResolver().withPrefix("folder/")
+
+```
+
+Decorating `FileHandleResolver` with `ResolutionFileResolver`:
+```Kotlin
+import ktx.assets.*
+import com.badlogic.gdx.Files.FileType
+
+val resolver = FileType.Internal.getResolver().forResolutions(
+    resolution(width = 800, height = 600),
+    resolution(width = 1024, height = 768)
+)
+```
 
 ### Alternatives
 
@@ -247,6 +287,8 @@ injects assets into annotated fields thanks to reflection.
 - [Kiwi](https://github.com/czyzby/gdx-lml/tree/master/kiwi) library has some utilities for assets handling, like
 graceful `Disposable` destruction methods and LibGDX collections implementing `Disposable` interface. It is aimed at
 Java applications though - **KTX** syntax should feel more natural when using Kotlin.
+- [`ktx-async`](../async) module provides `AssetStorage`: a lightweight coroutines-based alternative to `AssetManager`.
+It was extracted to `ktx-async` module due to the coroutines usage.
 
 #### Additional documentation
 

assets/build.gradle

@@ -1,4 +1,3 @@
 dependencies {
   provided "org.jetbrains.kotlin:kotlin-stdlib:$kotlinVersion"
 }
-