Fleks 2.0

[Quillraven]

I'd like to discuss the future of Fleks. In my opinion with version 1.6, which will be released soon, we will have a stable and nice ECS solution for JVM and KMP. I am personally very happy how everything turned out and I am actually using Fleks over Ashley in my latest projects.

However, there are a few things that I dislike or at least I am not 100% happy with it:

• I don't like the split between JVM and KMP. This should be combined in the future.
• I am not 100% happy with the way ComponentMapper are handled. It is redundant to inject them into every system. While it is nice to see if a system gets too many mappers injected and therefore will alert users to maybe rethink or refactor their system, it is a little bit annoying to always define the mapper in case you need a component of a specific type.
• I don't like that you have to add every component in the KMP version. The reason is that we don't have the reflection capabilities in KMP and that's why we need to define a factory function to create components dynamically but it is also a little bit annoying imo.
• I am not 100% happy with the dependency injection mechanism. While I personally like it, I think it might be overwhelming for newcomers or users who are not familiar with such a concept.

---

Initially I though that annotiation processing (KSP) can help with some of the problems but I read a couple of articles and now I am not sure anymore. I think it actually does not help at all :D
The reason is that you cannot modify existing source code like e.g. Lombok is doing it. You can only add additional code which means extensions, which is basically useless because Fleks does not know and cannot access companion object code of classes outside of Fleks (like all components or systems that are created by users).

My initial idea was to automatically create an ID for each component to somehow get rid of the ComponentMapper but imo this is not possible. Also, the way Kotlin works with static properties, this will never be possible the way I thought about it.

I had something in mind like:

abstract class Component {
  companion object {
    val id : Int
  }
}

// Fleks internally then access the id of any component e.g. like
data class Position : Component()

entity.add<Position>(...) // <-- here I was hoping that internally Fleks can access the ID of position

However, from what I read, this is impossible in Kotlin and will never work. It already fails when trying to access the id of a reified property. Additionally, overriding the static id or shadowing it is not possible in Kotlin. Something like that would work in C++ but we don't use that sorcery ;)

Additionally, KSP is also in an alpha (or beta?) stage, which I also do not like a lot and it also requires more gradle setup for users to also include autogenerated code. This is also a downside that I see.

---

So right now I am thinking how important we value performance over usage/simplicity. I fiddled around with Kotlin a little bit to find out a way to easily create entities/components and to access them. The way systems/families are working right now, is pretty intuitive and nice imo and I want to keep that.

Here is a quick&dirt implementation and a draft of how Fleks 2.0 could look like (including a very simple benchmark):

import kotlin.system.measureTimeMillis

interface ComponentType<C>

interface Component<C> {
    val type: ComponentType<C>

    fun onRemove(entity: Entity) = Unit
}

data class Position(var x: Float = 0f, var y: Float = 0f) : Component<Position> {
    companion object : ComponentType<Position>

    override val type: ComponentType<Position> = Position
}

data class Graphic(var texture: String = "") : Component<Graphic> {
    companion object : ComponentType<Graphic>

    override val type: ComponentType<Graphic> = Graphic
}

class Entity {
    val components = HashMap<ComponentType<*>, Component<*>>()

    operator fun plusAssign(component: Component<*>) {
        components[component.type] = component
    }

    inline operator fun <reified C> get(type: ComponentType<C>): C {
        return components[type] as C
    }
}

class World {
    val living = mutableSetOf<Entity>()
    private val recycled = ArrayDeque<Entity>()

    fun entity(cfg: (Entity) -> Unit = {}): Entity {
        val entity = if (recycled.isEmpty()) {
            Entity().apply(cfg)
        } else {
            recycled.removeLast().apply(cfg)
        }
        living += entity
        return entity
    }

    operator fun minusAssign(entity: Entity) {
        entity.components.values.forEach { it.onRemove(entity) }
        recycled += entity
        living -= entity
    }
}

fun main() {
    val world = World()
    val times = mutableListOf<Long>()

    repeat(5) {
        times += measureTimeMillis {
            repeat(10_000) {
                world.entity { entity ->
                    entity += Position()
                }
            }
        }

        val entities = world.living.toTypedArray()

        times[it] += measureTimeMillis {
            entities.forEach { entity ->
                world -= entity
            }
        }
    }
    println("MAX: ${times.max()} | MIN: ${times.min()} | AVG: ${times.average()}")

    val player = world.entity {
        it += Position()
        it += Graphic()
    }
    println(player[Position])
    println(player[Graphic])
    world -= player
}

The benchmark is basically the "ADD_REMOVE" benchmark of Fleks. Of course performance-wise it is worse but I think it is not that bad. On my machine it has a minimum of 2 milliseconds, which is the same as Fleks has at the moment. The average is ~12ms which is about half the speed of Fleks right now.

HOWEVER, I do like the syntax a lot and I think for users it is also easier to understand and debug the Entity class which already contains all the components of that specific entity. The "magic" is following part:

interface ComponentType<C>

interface Component<C> {
    val type: ComponentType<C>

    fun onRemove(entity: Entity) = Unit
}

data class Position(var x: Float = 0f, var y: Float = 0f) : Component<Position> {
    companion object : ComponentType<Position>

    override val type: ComponentType<Position> = Position
}

The ComponentType is like the unique ID of each type of component (like the ID I described above). A component then needs to implement the new Component interface. You can simply copy&paste the two necesarry lines to each component or create a live template for it in IntelliJ. Again, this is a little bit annoying but I think it is acceptable. With that way we can achive an API like this:

    val player = world.entity {
        it += Position()
        it += Graphic()
    }

    // access the position of the player <-- note that we don't need to write Position.mapper or Position.type or whatever
    player[Position]

    world -= player

Another benefit of this approach is that it requires no Reflection and is therefore usable for KMP as well. Also, the component creation is not "magically" happening in the background of the framework. That way the user can already create and modify the component directly the way he needs it. In my opinion we might be able to remove ComponentListener that way. At least the adding makes no more sense to me. The removal might be nice still, that's why I added it to the quick&dirt draft above.

Also, with this approach it is no longer necessary for KMP to define a factory method for every component.

Finally, it would even be possible to attach the same component multiple times to an entity which is currently not possible in Fleks. Imagine like you have an entity with multiple sprites. At the moment you can solve that by giving your sprite component a list of sprites. With this approach you can simply define different ComponentType "keys" in the Sprite component like "BaseSprite", "WeaponSprite", "HeadSprite", ... and then just add them to the entity. The entity then has multiple Sprite components that can be accessed via the different types.

@jobe-m / @mariorez: What do you think about that? Shall we move in such a direction in the future for Fleks, knowing that the performance will most likely be a little bit worse (but of course still faster than Ashley at least ;) ).

Do you have any suggestions or pain points right now?

---

edit: some tryout on the playground from my phone. Just another draft that might help:

open class ComponentType(val id:Int = nextId++) {
    companion object {
        private var nextId = 0
    }
}


interface Component {
    val type : ComponentType
}

class Position : Component {
    companion object : ComponentType()
    override val type : ComponentType = Position 
}

class Graphic : Component {
    companion object : ComponentType()
    override val type : ComponentType = Graphic 
} 

fun printId(type : ComponentType){
    println(type.id)
}
    
fun main() {
   val pos = Position()
   println(pos.type.id)
   println(Position().type.id)
   printId(Position)
   printId(Graphic)
}

[Quillraven]

Just fiddled around some more. Very similar to above but now a ComponentType has a unique number and therefore, we could almost use the same structure as Fleks already has. Would be great if somehow it's possible to avoid defining the companion object and the override val type per component. Companion object would be possible via an annotation processor but override val type isn't from what I know.

UPDATE: actually type must be a function because I just checked the decompiled code and looks like with a val it is creating a final field for each component which of course we don't want. We just want a static type/id per component. So, I updated it now to a function and this seems to be having no impact on the speed (it actually is faster for some reason, maybe because the class creation is easier because of one less final property per instance).

import kotlin.system.measureTimeMillis

open class ComponentType<C>(val id: Int = nextId++) {
    companion object {
        private var nextId = 0
    }
}

interface Component<C> {
    fun type(): ComponentType<C>

    fun onRemove(entity: Entity) = Unit
}

data class Position(var x: Float = 0f, var y: Float = 0f) : Component<Position> {
    companion object : ComponentType<Position>()

    override fun type() = Position
}

data class Graphic(var texture: String = "tex") : Component<Graphic> {
    companion object : ComponentType<Graphic>()

    override fun type() = Graphic
}

class Entity {
    val components = bag<Component<*>>()

    operator fun plusAssign(component: Component<*>) {
        components[component.type().id] = component
    }

    inline operator fun <reified C> get(type: ComponentType<C>): C {
        return components[type.id] as C
    }
}

class World {
    val living = mutableSetOf<Entity>()
    private val recycled = ArrayDeque<Entity>()

    fun entity(cfg: (Entity) -> Unit = {}): Entity {
        val entity = if (recycled.isEmpty()) {
            Entity().apply(cfg)
        } else {
            recycled.removeLast().apply(cfg)
        }
        living += entity
        return entity
    }

    operator fun minusAssign(entity: Entity) {
        entity.components.forEach { it.onRemove(entity) }
        recycled += entity
        living -= entity
    }
}

fun main() {
    val world = World()
    val times = mutableListOf<Long>()

    repeat(5) {
        times += measureTimeMillis {
            repeat(10_000) {
                world.entity { entity ->
                    entity += Position()
                }
            }
        }

        val entities = world.living.toTypedArray()

        times[it] += measureTimeMillis {
            entities.forEach { entity ->
                world -= entity
            }
        }
    }
    println("MAX: ${times.max()} | MIN: ${times.min()} | AVG: ${times.average()}")

    val player = world.entity {
        it += Position()
        it += Graphic()
    }
    println(player[Position])
    println(player[Graphic].texture)
    world -= player
}

[jobe-m]

First of all I need to write a big "thank you" that you are so actively developing and maintaining Fleks. Luckily I discovered Fleks while I thought to write my own (quick and dirty) ECS for my Korge-based game. It saved me from a lot of pain and actually by reading and adapting Fleks for Korge I learned a lot! :)
I initially thought that my adapted (KMP) Fleks version would be a fork on its own in the Korge repo and I would mainly need to maintain it. So again big thanks that you have taken over the KMP version into your repo and that you are actively maintaining it in parallel to the JVM version.

I have to admit that the KMP version of Fleks is fine for me as it is currently. It has some pain-points as you mentioned but it is fine IMHO because you added very good documentation in handling those.

But I understand and acknowledge that you want to solve the puzzle to merge both versions of Fleks together again.

So here are some of my thoughts about the new implementation:

I would like to still have a mechanism to run code when a specific component was added/created. This is needed to independently do some actions on component creation regardless where the component was added. Or could I just write an extension function which returns a component after it was created and initialized?

Also family listeners should be still available. Do you already have an idea how this will work? I heavily use the family listeners to do initialization for a specific set of components.

One general question: With defining an own independent ID for components isn't this going against the initial idea of an ECS? I mean that the Entity should be just an ID for accessing the components in a system and not a class containing data?
I also would compare the runtime carefully with the current implementation because you did a great job in writing a fast and light ECS implementation for Kotlin.

[Quillraven]

Hey, thanks! Happy to hear that but actually I have to return the kind words to you as well. Helping with the initial KMP setup was amazing and I learned a lot about this topic with that. Also it advertised Fleks to other people like the KorGE community which helps :)

I thought about the changes more and I think you are right. We should not change it too much especially since the current setup seems to work well and fast. This means that we can keep everything that we have including ComponentListener and FamilyListener of course.

---

Regarding the component ID - let me explain it a little bit to make it clearer:

In an ECS you want to add dynamic data to an entity, which are called components. Ideally, you want to write something easy like entity += Position(1f, 2f) and entity.get<Position>(). Especially with the component retrieval, you need to specify what type of component you want to retrieve.

A very simple but intuitive approach would be to store that in a HashMap<KClass<*>, Any> which works of course. However, looking up components in a HashMap is not the fastest way to achieve that. First, it needs to calculate the hashcode of the KClass and then it needs to lookup the component in the map which can be time consuming depending on the map implementation you choose.

I think a HashMap is the fastest way here and I think in the JVM the hashcode calculation even gets optimized over time and improves. I also think a HashMap basically uses an array in the background which is also good. So this sounds great, doesn't it? ;)

Well, this can be optimized further by simplifying everything to a simple array approach, which is the fastest possible way to add and get data, if you know the index already. I cannot tell you exactly how much faster because I forgot the results for my benchmarks a couple of years ago but believe me, it is worth it!

In this optimized approach you simply have an array of components for an entity. In order for us to know which component is located at which index, we need a unique ID per "component type" like e.g. Position is index 0, Graphic is index 1, ...

Unfortunately (and for me this is something bad in Kotlin), Kotlin does not allow the inheritance of companion objects. I think it is very similar in Java. That's why we cannot simply have a "static counter" in a Component abstract class and automatically assign an ID to every subclass. Remember, that we want to have an ID per component type and not per component instance. The later one would be easy to implement but then we waste memory because every instance has an additional ID field, which we also don't want.

So in the end I went for a similar approach as Ashley/Artemis are doing it, I think. Which means I assign and remember an ID for each component type internally in Fleks. This also means, when you'd access a component via its type like entity.get<Position> then I first need to lookup the ID of the Position class which is stored in a HashMap and afterwards I can get the component via its unique ID.

This is of course not great and worse then the initial HashMap KClass approach and that's why I enforce the usage of ComponentMapper in Fleks. This is basically the fast array access of components. They are the result of the ID lookup of a component type.

This was now a long explanation but I hope I could clarify the thought process behind this topic.

---

Coming now to ideas for Fleks 2.0 I think changing the ComponentMapper approach is something worth looking into it. My idea is:

• Add a new ComponentType class that creates the unique array indices starting from 0

  open class ComponentType<C>(val id: Int = nextId++) {
      companion object {
          private var nextId = 0
      }
  }

• add a new Component interface that needs to be implemented by any user component

  interface Component<C> {
      fun type(): ComponentType<C>
  }

  • That way we enforce that a Component has a type and therefore a unique ID
• A user component for a Position can then look something like this

  data class Position(var x: Float = 0f, var y: Float = 0f) : Component<Position> {
      companion object : ComponentType<Position>()
  
      override fun type() = Position
  }

  • Thanks to the way Kotlin's syntax with companion objects is working, we can then access the ComponentType of the Position by simply writing Position. To access e.g. the position in a system could then look like this

    @AllOf([Position::class])
    class PositionSystem : IteratingSystem() {
        override fun onTickEntity(entity: Entity) {
            println(entity[Position])
        }
    }

• Also, adding component instances can then be done directly by the user

  world.entity {
      it += Position(2f, 3f)
  }

I made a quick breakthrough implementation here: #68

The advantages I see:

• we remove the Reflection part in JVM which is always good as we should try to avoid Reflection when possible ;)
• we don't need to register every component in KMP. The factory methods are no longer necessary since the user is now creating the component instance
• we no longer need to inject ComponentMapper. I think we can basically remove the ComponentMapper class completely or at least refactor it because the component creation part is no longer necessary and the ID part as well.
• I think creating components should be faster as well because it is no longer done via reflection.
• I think it is then also possible to assing the same component multiple times to a single entity by just enhancing the ComponentType for this component. We are not limited to the companion object way that I used above. It can be something more complex. E.g. we can have a "background graphic" type and a "foreground graphic" type both using a single Graphic component.

If we go for something like that then I also vote for removing other Reflection parts of Fleks like creating systems, ComponentListener and FamilyListener. Especially the annotation class parsing, which did not work in KMP, can maybe be changed to a DSL style approach.

Also, we could remove the imo ugly ::class usages and use the new ComponentType instead. E.g. instead of writing allOf = arrayOf(Position::class), we can write allOf = arrayOf(Position).

Of course, I also see a downside to this approach which is the tidious creation of the companion object ComponentType and the type() override function for each component.
First, I'd argue that doing that over injecting a ComponentMapper everywhere or registering every newly created component to the world for KMP is nothing different. Both approaches are not ideal but there is only so much we can do at some point :D
Second, in theory it would be possible to write a Kotlin compiler plugin that automatically creates that piece of code for users. I just learned about that yesterday and watched a video: https://www.youtube.com/watch?v=w-GMlaziIyo&t=900s

Seems to support multiplatform as well but the documentation for such a thing is non-existant :( Or at least I couldn't find a good documentation/tutorial. The things in the video (from 2018) seem to be no longer valid. I was missing some of the classes that he mentions, so I assume that got changed over the years. But anyway, theoretically there would be something available to autogenerate that for users which is in my opinion of course the DREAMworld. But even if we don't have that, implementing the type and overriding the type() function is acceptable imo and not worse than what we have now.

[jobe-m]

Remember, that we want to have an ID per component type and not per component instance.

Aah, this is exactly what I was missing. Now, it makes much more sense :)
Thanks for the very good explanation.
IMO we wouldn't necessarily need component listeners for the onAdded call if that can be done while creating the component. Maybe that way the component creation might be even faster, because no callback is needed. OnRemoved could be added to the component class as you did before.

I like the idea that we do not change too much in Fleks. Removing the need for the factory methods when creating components and (family) listeners could be the first step. If you remove other reflection code, keep in mind that some reflect features are available in KMP. Also I would therefore only remove it if the alternative implementation would bring some more benefit e.g. faster execution.

Also, we could remove the imo ugly ::class usages and use the new ComponentType instead. E.g. instead of writing allOf = arrayOf(Position::class), we can write allOf = arrayOf(Position).

I also like this idea very much :)

[Quillraven]

I tried something very quickly now by only adjusting the necessary code to run the Fleks Benchmarks with the new idea and indeed it gets faster. What is interesting as well, ony my PC I only rarely get an OutOfMemory exception for the Artemis "addRemove" benchmark. On my notebook it is 100% failing. Seems like something is messed up in Artemis a little bit???

Anyway, here is the result for Fleks:

• addRemove went down from ~14ms to ~12ms
• simple went down from ~15ms to ~13ms
• complex went down from ~750ms to ~680ms

So looks like this will improve performance by ~10-20% which is not bad in my opinion.

Two things came to my attention when adjusting the code:

1. How do we want to adjust the addOrUpdate method of the ComponentMapper. This method either creates a new component or adjusts an existing one. Since the creation is now happening on user side, it will in worst case create an unnecessary component. I am not 100% sure yet what is the best idea to adjust this method.
2. Is it even necessary to have multiple ComponentListener for the same component? At least I only need a single listener per type. This could therefore be solved maybe via a simple onAdd and onRemove function on the component interface. The parameters could be the world, entity and component. We could keep the world dependencies after creation and grant access to them. That way you can access any necessary object in those two methods.

edit: oh and by the way to lower the expectations. I have no plans to release a 2.0 version in the upcoming weeks. I am not even sure if I can do it within this year. This is more likely something for next year because of time constraints due to things that are happening in my personal life (mainly positive things :) ).

[Quillraven]

I forgot to add the code. This would be the same API for JVM and KMP. No more reflection necessary so far. I replaced the family annotations of a system with a new familyCfg API. Name is up for discussion of course :D

package com.github.quillraven.fleks.benchmark

import com.github.quillraven.fleks.*
import org.openjdk.jmh.annotations.*
import java.util.concurrent.TimeUnit

data class FleksPosition(var x: Float = 0f, var y: Float = 0f) : Component<FleksPosition> {
    companion object : ComponentType<FleksPosition>()

    override fun type() = FleksPosition
}

data class FleksLife(var life: Float = 0f) : Component<FleksLife> {
    companion object : ComponentType<FleksLife>()

    override fun type() = FleksLife
}

data class FleksSprite(var path: String = "", var animationTime: Float = 0f) : Component<FleksSprite> {
    companion object : ComponentType<FleksSprite>()

    override fun type() = FleksSprite
}

class FleksSystemSimple : IteratingSystem() {

    override fun familyCfg(): FamilyCfg = FamilyCfg {
        allOf(FleksPosition)
    }

    override fun onTickEntity(entity: Entity) {
        entity[FleksPosition].x++
    }
}

class FleksSystemComplex1 : IteratingSystem() {
    private var actionCalls = 0

    override fun familyCfg(): FamilyCfg = FamilyCfg {
        allOf(FleksPosition)
        noneOf(FleksLife)
        anyOf(FleksSprite)
    }

    override fun onTickEntity(entity: Entity) {
        if (actionCalls % 2 == 0) {
            entity[FleksPosition].x++
            configureEntity(entity) {
                it += FleksLife()
            }
        } else {
            configureEntity(entity) {
                it -= FleksPosition
            }
        }
        entity[FleksSprite].animationTime++
        ++actionCalls
    }
}

class FleksSystemComplex2 : IteratingSystem() {

    override fun familyCfg(): FamilyCfg = FamilyCfg {
        anyOf(FleksPosition, FleksLife, FleksSprite)
    }

    override fun onTickEntity(entity: Entity) {
        configureEntity(entity) {
            it -= FleksLife
            it += FleksPosition()
        }
    }
}

@State(Scope.Benchmark)
open class FleksStateAddRemove {
    lateinit var world: World

    @Setup(value = Level.Iteration)
    fun setup() {
        world = world {
            entityCapacity = NUM_ENTITIES
        }
    }
}

@State(Scope.Benchmark)
open class FleksStateSimple {
    lateinit var world: World

    @Setup(value = Level.Iteration)
    fun setup() {
        world = world {
            entityCapacity = NUM_ENTITIES
            systems {
                add<FleksSystemSimple>()
            }
        }

        repeat(NUM_ENTITIES) {
            world.entity {
                it += FleksPosition()
            }
        }
    }
}

@State(Scope.Benchmark)
open class FleksStateComplex {
    lateinit var world: World

    @Setup(value = Level.Iteration)
    fun setup() {
        world = world {
            entityCapacity = NUM_ENTITIES
            systems {
                add<FleksSystemComplex1>()
                add<FleksSystemComplex2>()
            }
        }

        repeat(NUM_ENTITIES) {
            world.entity {
                it += FleksPosition()
                it += FleksSprite()
            }
        }
    }
}

@Fork(1)
@Warmup(iterations = WARMUPS)
@Measurement(iterations = ITERATIONS, time = TIME, timeUnit = TimeUnit.SECONDS)
open class FleksBenchmark {
    @Benchmark
    fun addRemove(state: FleksStateAddRemove) {
        repeat(NUM_ENTITIES) {
            state.world.entity {
                it += FleksPosition()
            }
        }
        repeat(NUM_ENTITIES) {
            state.world.remove(Entity(it))
        }
    }

    @Benchmark
    fun simple(state: FleksStateSimple) {
        repeat(WORLD_UPDATES) {
            state.world.update(1f)
        }
    }

    @Benchmark
    fun complex(state: FleksStateComplex) {
        repeat(WORLD_UPDATES) {
            state.world.update(1f)
        }
    }
}

[Quillraven]

How do we want the addOrUpdate function look like which either adds a component to an entity if it didn't had one, or updates the existing component?

I made a prototype with a LifeComponent and I think it is somehow acceptable but maybe it can be improved. It is important to note that we either need the ComponentType or a Component to get the ID.

data class Life(var points: Float) : Component<Life> {
    companion object : ComponentType<Life>()

    override fun type() = Life
}

// system code omitted
    override fun onTickEntity(entity: Entity) {
        entity.configure {
            it.addOrUpdate(Life, { Life(30f) }) {
                points += 30f
            }
        }
        println(entity[Life])
    }

// test main
fun main() {
    val w = world {
        components {
            add<PositionComponentListener>()
        }

        systems {
            add<PositionSystem>()
        }
    }

    w.entity {
        it += Position(2f, 3f)
        it += Life(50f)
    }

    w.entity {
        it += Position(1f, 1f)
    }

    w.update(1f)
}

It correctly prints 80 life for the first entity and 30 for the second but it requires two callbacks in addOrUpdate which is not super nice imo. However, I don't see a way around that because if we replace e.g. the factory parameter with the component itself then we might create useless objects if the component is already existing.

inline fun <reified T, C : Component<T>> Entity.addOrUpdate(
        type: ComponentType<T>,
        factory: () -> C,
        block: T.() -> Unit
    ) {
        val mapper = cmpService.mapper(type)
        cmpMask.set(mapper.id)
        val cmp = mapper.getOrNull(this)
        if (cmp == null) {
            mapper.addInternal(this, factory())
        } else {
            (cmp as T).apply(block)
        }
    }

Is that okay? Or is there a better way to support that?

[jobe-m]

I will look into it next time in more detail when I am at my laptop :)

How about creating separate update and add functions? At least when it is known if an component exists then there would be less code running when just using the update method.

[Quillraven]

Add and update separately is anyway available. This was more a convenient method if you don't know that an entity has a component or not. Granted, this is most likely rare but I sometimes needed it 😅

E.g. imagine a DamageTaken component which collects all the damage that an entity takes in a frame and then deals that damage to it.

Such a damage can occur in different areas of the codebase like spell damage or melee combat damage. Instead of checking everywhere if the component is available or not and update it or create it, it can be done in one step with this function.

This can be solved of course in many ways. One way is to simply always add such a component to an entity and inside the damage take system just validate if the damage is greater 0 and otherwise do nothing. But imo it is not bad to also offer the possibility of other ways like addOrUpdate is doing to reduce the amount of entity iterations in a frame.

[jobe-m]

Aah, sorry, you are right. I didn't remember exactly the code;)
I think the factory parameter in the addOrUpdate function is the trade-off when removing the add component in the world :D

[Quillraven]

I think so too 😂 I read an article today where they are proposing this solution exactly with named arguments. It should be possible to make a DSL out of it but I need to try that out. Otherwise I think the current solution is as best as it can get 😅

[mariorez]

Hey guys,

Sorry for my absence from discussions for the new version of Fleks, but professional and family situations kept me away from open-source projects for a while.

I see that v2 is already well advanced and I'm really enjoying the direction the project is taking.

If you still have room for collaboration, I can help by reviewing the documentation.

I want to clone my game to the new version, so I can collaborate more effectively on documentation, code examples, game examples, etc.

But first I need help:
How to configure gradle to install Fleks v2 ?

[jobe-m]

Currently you need to build fleks V2 from the feature branch in the PR of quillraven. And release it locally as a "2.0-SNAPSHOT" version in maven lokal.

How to setup gradle is explained in the wiki pages.

[Quillraven]

@mariorez: no worries and thank you for also looking into it and giving feedback :) As @jobe-m mentioned, you have to checkout the "fleks2" branch locally and then adjust the version in the build.gradle.kts file and execute the publishToMavenLocal task:

By adding "-SNAPSHOT" to the version, it is not necessary to sign it which is nice and easy for local testing.

[mariorez]

It worked, thanks :)

[Quillraven]

@mariorez / @jobe-m: Let me know if some of your examples are converted to 2.0 or if you maybe have a new repository for 2.0 games. Then I will update the 2.0 section accordingly in the wiki :)

[jobe-m]

I will update my examples and let you know.

[mariorez]

I'm creating a new game for version 2 (still under construction):
https://github.com/mariorez/libktx-treasure-quest

[jobe-m]

My template / hello world example for using Fleks 2.0 in a KorGE game is ready: https://github.com/jobe-m/korge-fleks-hello-world

[jobe-m]

I will update the Fleks example inside the KorGE repo later

[rubybrowncoat]

I see there's a forEach on families. What about other collection methods?
Just curious, because I was in the debugger and wanted to filter a family. Didn't really need to, it would have just been convenient

[Quillraven]

I had a look now and I think making a family a Collection does not really make sense because there are many functions where I would not know what they should do OR they are useless for game development imo like:

• iterator: we don't need that because we have forEach and you are not allowed to add/remove entities directly to the underlying data structure. Also, it is normally an extra object that gets created every time you iterate which is also not ideal because of the garbage collector performance.
• asIterable / asSequence: why would we need that?
• ...

Therefore, I suggest to take over the important functions that make sense. For me that is:

• size: already existing as numEntities
• EXISTING: contains, forEach, sort, first, firstOrNull, isEmpty, isNotEmpty
• NEW: filter, filterNot, filterTo, filterNotTo, random, randomOrNull, take

Especially the ...To functions can be useful in case you do filtering frequently because you can pass in any mutable collection and avoid creating new collection instances all the time which is again good for GC.

I also thought that takeWhile, takeLast and takeLastWhile make sense but I decided against it because entities are per default in a "random" order inside a family until you explicitly sort them. Therefore, those take functions return "random" results which I think is not really useful. But this is up for discussion!

---

TL;DR: I will add following functions to family and also to the world: filter, filterNot, filterTo, filterNotTo, random, randomOrNull, take

Would that be okay?

[rubybrowncoat]

• iterator: we don't need that because we have forEach and you are not allowed to add/remove entities directly to the underlying data structure. Also, it is normally an extra object that gets created every time you iterate which is also not ideal because of the garbage collector performance.
• asIterable / asSequence: why would we need that?

I think add/remove methods only apply to mutable collections, don't they? As for the rest, it's true that there are potentially redundant functions but I don't have a clear idea of why they exist in Collection in the first place so I can't say if they are useless or not.

• size: already existing as numEntities

It's true. I personally would add it for consistency with other Kotlin nomenclatures. Since you are adding a lot of collection-like methods it may make sense to also expose a collection-like size attribute.

I also thought that takeWhile, takeLast and takeLastWhile make sense but I decided against it because entities are per default in a "random" order inside a family until you explicitly sort them. Therefore, those take functions return "random" results which I think is not really useful. But this is up for discussion!

This makes sense. The same goes for drop and dropWhile, and similar methods.

TL;DR: I will add following functions to family and also to the world: filter, filterNot, filterTo, filterNotTo, random, randomOrNull, take
Would that be okay?

I think it's fine.

I don't know the overhead involved with implementation, but as long as we are discussing this possibility I would advocate for considering also the associate, map, fold and reduce groups of methods, which would round off the standard for interacting with collections.

For example's sake I could see myself using these methods to associate/map a family to a list/map of specific components from that family (e.g. to a list of full Storage components in my family of entities with Market and Storage components, with mapNotNull), or fold/reduce a family to a single value (e.g. the total remaining HP of all active Enemies without the Death component).

Just floating potential ideas, there may be other approaches to do similar things making them redundant.

[Quillraven]

Might make sense for some UI stuff e.g.. I will consider them as well 🙂

Overhead should not be huge. The biggest concern for me is the creation of the additional collection instance with most methods but as long as you don't call them per frame I don't see an issue. And for specific events like e.g. UI stuff it is convenient to write code with known kotlin functions 🙂

[Quillraven]

@rubybrowncoat: how does reduce work in this context? If I understand it correctly then the accumulator starts with the first value of the collection and then runs the operation argument with all remaining values.
In our case the value is an entity and accumulating entities does not make sense to me. Or am I missing something?

The fold functionality seems similar but you can specify an arbitrary initial value for the accumulator. They can be useful, as you mentioned, to sum up the life of all entities in a family. Or similar things.

---

The way I want to solve it to reduce copy&pasting the same functionality to family and world is, that I do the following:

• change the IntBag collection to an EntityBag. This is mainly renaming the class to make its purpose clearer.
• make it implement a new EntityCollection interface (see below)
• family will then expose its internal entitiesBag property. ❓ Or maybe I make it an EntityBag itself. Need to check what is more convenient.
• world will provide a new asEntityBag function that returns an EntityBag of all entities. ❓ Here I am not sure if it should always create a new bag instance or return the same instance. If this is used without nesting then I prefer returning the same instance.

interface EntityCollection {
    val size: Int

    operator fun contains(entity: Entity): Boolean

    fun containsAll(entities: Collection<Entity>): Boolean

    fun isEmpty(): Boolean

    fun isNotEmpty(): Boolean

    fun all(predicate: (Entity) -> Boolean): Boolean

    fun any(predicate: (Entity) -> Boolean): Boolean

    fun none(predicate: (Entity) -> Boolean): Boolean

    fun <K, V> associate(transform: (Entity) -> Pair<K, V>): Map<K, V>

    fun <K> associateBy(
        keySelector: (Entity) -> K
    ): Map<K, Entity>

    fun <K, V> associateBy(
        keySelector: (Entity) -> K,
        valueTransform: (Entity) -> V
    ): Map<K, V>

    fun <K, V, M : MutableMap<in K, in V>> associateTo(
        destination: M,
        transform: (Entity) -> Pair<K, V>
    ): M

    fun <K, M : MutableMap<in K, Entity>> associateByTo(
        destination: M,
        keySelector: (Entity) -> K
    ): M

    fun <K, V, M : MutableMap<in K, in V>> associateByTo(
        destination: M,
        keySelector: (Entity) -> K,
        valueTransform: (Entity) -> V
    ): M

    fun count(): Int

    fun count(predicate: (Entity) -> Boolean): Int

    fun filter(predicate: (Entity) -> Boolean): List<Entity>

    fun filterNot(predicate: (Entity) -> Boolean): List<Entity>

    fun filterIndexed(predicate: (index: Int, Entity) -> Boolean): List<Entity>

    fun <C : MutableCollection<Entity>> filterTo(
        destination: C,
        predicate: (Entity) -> Boolean
    ): C

    fun <C : MutableCollection<Entity>> filterNotTo(
        destination: C, predicate: (Entity) -> Boolean
    ): C

    fun <C : MutableCollection<Entity>> filterIndexedTo(
        destination: C, predicate: (index: Int, Entity) -> Boolean
    ): C

    fun find(predicate: (Entity) -> Boolean): Entity?

    fun first(): Entity

    fun first(predicate: (Entity) -> Boolean): Entity

    fun firstOrNull(): Entity?

    fun firstOrNull(predicate: (Entity) -> Boolean): Entity?

    fun <R> fold(
        initial: R,
        operation: (acc: R, Entity) -> R
    ): R

    fun <R> foldIndexed(
        initial: R,
        operation: (index: Int, acc: R, Entity) -> R
    ): R

    fun forEach(action: (Entity) -> Unit)

    fun forEachIndexed(action: (index: Int, Entity) -> Unit)

    fun <R> map(transform: (Entity) -> R): List<R>

    fun <R> mapIndexed(transform: (index: Int, Entity) -> R): List<R>

    fun <R, C : MutableCollection<in R>> mapTo(
        destination: C,
        transform: (Entity) -> R
    ): C

    fun <R, C : MutableCollection<in R>> mapIndexedTo(
        destination: C,
        transform: (index: Int, Entity) -> R
    ): C

    fun random(): Entity

    fun randomOrNull(): Entity?

    fun take(n: Int): List<Entity>
}

[rubybrowncoat]

The fold functionality seems similar but you can specify an arbitrary initial value for the accumulator. They can be useful, as you mentioned, to sum up the life of all entities in a family. Or similar things.

You are right, I was thinking of fold and not remembering which one was which exactly.