Tiled extensions

[Quillraven]

Hi,

just wanted to know if there is an interest in TiledMap extensions as well.
I am using a few in my own game and I could make a pull request if someone is interested.

Just needed to know if this is something useful or not and if it is useful, what do I need to do for a valid pull request? :)

I have following extensions in place for accessing properties

// extension method to access properties the Kotlin way ;)
inline fun <reified T> MapObject.property(key: String, defaultValue: T): T =
    this.properties[key, defaultValue, T::class.java]

inline fun <reified T> MapLayer.property(key: String, defaultValue: T): T =
    this.properties[key, defaultValue, T::class.java]

This extension is used to retrieve the shape of a MapObject

// extension property to access shape of a MapObject
val MapObject.shape: Shape2D
    get() = when (this) {
        is RectangleMapObject -> this.rectangle
        is PolylineMapObject -> this.polyline
        is PolygonMapObject -> this.polygon
        else -> {
            LOG.error { "Unsupported MapObject of type ${this::class.java}. Cannot retrieve shape!" }
            Rectangle.tmp.set(0f, 0f, 1f, 1f)
        }
    }

Extensions to quickly access properties that are used very often like id, x, y, width, height

// extension property to easily access MapObject IDs, x and y position
val MapObject.id: Int
    get() = this.property(PROPERTY_ID, -1)
val MapObject.x: Float
    get() = this.property(PROPERTY_X, 0f)
val MapObject.y: Float
    get() = this.property(PROPERTY_Y, 0f)

// inside my own Map class, which stores a reference to  a TiledMap I also have
val width: Float
        get() = property(PROPERTY_WIDTH, 0f) * property(PROPERTY_TILE_WIDTH, 0f) * UNIT_SCALE
    val height: Float
        get() = property(PROPERTY_HEIGHT, 0f) * property(PROPERTY_TILE_HEIGHT, 0f) * UNIT_SCALE

 // extension method to access properties the Kotlin way for TiledMap
    inline fun <reified T> property(key: String, defaultValue: T): T =
        tiledMap.properties[key, defaultValue, T::class.java]

    fun containsProperty(key: String) = tiledMap.properties.containsKey(key)

    private fun layer(layerName: String): MapLayer {
        val layer = tiledMap.layers.get(layerName)
        if (layer == null) {
            // layer not defined in tiled map
            LOG.debug { "There is no $layerName layer for map $type" }
            return defaultLayer
        }
        return layer
    }

    fun mapObjects(layerName: String): MapObjects = layer(layerName).objects

With the last extensions, which could be of course created for TiledMap instead of my own Map class you can then do things like this:

private fun createCharacterEntities(map: Map, layer: String) {
        map.mapObjects(layer).forEach { mapObj ->
            try {
                val charKey = Character.valueOf(mapObj.property(PROPERTY_CHARACTER, ""))
                ecsEngine.character(
                    characterConfigurations[charKey],
                    world,
                    mapObj.x * UNIT_SCALE,
                    mapObj.y * UNIT_SCALE
                )
            } catch (e: IllegalArgumentException) {
                if (!mapObj.properties.containsKey(PROPERTY_CHARACTER)) {
                    LOG.error { "Missing character property for object with ID ${mapObj.id} for map ${map.type} in layer $layer" }
                } else {
                    LOG.error(e) { "Invalid character property specified for object with ID ${mapObj.id} for map ${map.type} in layer $layer" }
                }
            }
        }
    }

[czyzby]

Definitely, this could be a very useful KTX module. I'd have to review each utility during code review, but it looks good so far.

The contribution guide has a section on adding new KTX modules. Would you like to set it up and submit a PR?

[Quillraven]

cool, will prepare something over the weekend and let you know

[Quillraven]

@czyzby : Sorry but I will need your help as I don't know how that works on github.

I cloned the repository and checked out the "develop" branch. I followed your guide and created now the new extensions including the tests.
Tomorrow I will update the README.md but how can I push/PR my changes?

I committed them locally but I do not want to click push because that would either fail(?) or I would directly commit to the develop branch which might also not be ideal.

edit: or should I create a new branch for my changes? Am I allowed to push a new branch? :D

edit2: just tried to create a new branch and push it but it says "Permission to libktx/ktx.git" denied to Quillraven :(

[czyzby]

1. Fork the repository. You should have a https://github.com/Quillraven/ktx/ repo after this. You can fork the repository with a Fork button next to Star.
2. Clone the forked repository. E.g. git clone https://github.com/Quillraven/ktx/
3. Apply and commit your changes locally.
4. Push the changes into a branch in your repository. You will have the push rights to your own fork.
5. Setup a pull request from your repository to develop branch here.

[Quillraven]

Thanks for the info! I had no idea about that "fork" functionality.

I hope I did everything correctly and you should hopefully see my PR without messing up your repo ;)

[czyzby]

Don't worry, you won't. :) I'll review the PR shortly.

[czyzby]

Thanks, I did some minor refactoring and documentation improvements. I also added operator extensions to MapProperties (contains, set). I'm closing this issue for now, but if you'd like to suggest or contribute any additional utilities, you're welcome to reopen the issue.

Thanks again for your contributions!

[czyzby]

You can expect a snapshot release of ktx-tiled 1.9.10-SNAPSHOT soon.