Progress:

• [x] Breakthrough
• [x] Code adjustments
• [x] Unit test adjustments
• [x] Update comments
• [x] Update wiki
• [x] Update ReadMe
• [x] Update version and combine JVM and KMP. Maybe make the current master a new JVM_history branch to keep the history
• [x] Verify new version in Dinoleon and Mystic Woods

This is currently a WIP for Fleks 2.0. I did most of the code adjustments but I am still missing the unit test adjustments and comments.

I did a test driven development approach (fleks2-tdd.kt) which I kinda liked for this exercise. It helped to get the API faster in the way I wanted it.

Also, I want to discuss the changes that I have applied, if they make sense to everyone or not. Be aware, here comes a wall of text ;) Questions are highlighted in bold and with a ❓ emoji.

To easily create the boilerplate code for the new Fleks component approach, I suggest to create a Live Template in the IDE. For example in IntelliJ we can do the following. You then just type flekscomponent or whatever abbreviation you want to use to get the necessary code.

class $FLEKS_COMPONENT$ : Component<$FLEKS_COMPONENT$> {
	override fun type() = $FLEKS_COMPONENT$

	companion object : ComponentType<$FLEKS_COMPONENT$>()
}

TLDR: imo the Fleks codebase gets a little smaller and easier to understand with those changes. Also, with the removal of reflection and factory methods it is easier to understand, use and debug. The performance is slightly faster than before. I guess because of the removal of factory method calls and the conversion from listeners to hooks.

Changes

Components

It is no longer necessary to add components to the WorldConfiguration. ComponentMapper are created automatically similar to the JVM version, and we also no longer need any reflection or factory methods.

In order for that to work, a new interface and abstract class was added and every component now must implement the new Component interface. More about the benefits below in the "Systems" section.

A position component now looks like this:

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

    companion object : ComponentType<Position>()
}

The ComponentType is important to give each type of component a unique ID which is necessary for Fleks internal stuff to optimize the way components are stored.

With Kotlin's unnamed companion object we can then achieve imo some nice syntax sugar (see below in "Systems" section).

With this change it is now also possible to add the same component multiple times to an entity. This is not possible in Fleks 1.x. This is something new! :) Here is an example of a Sprite component that can either be a background or foreground of an entity:

ata class Sprite(
    val background: Boolean,
    var path: String = "",
) : Component<Sprite> {
    override fun type(): ComponentType<Sprite> {
        return when (background) {
            true -> SpriteBackground
            else -> SpriteForeground
        }
    }

    companion object {
        val SpriteForeground = object : ComponentType<Sprite>() {}
        val SpriteBackground = object : ComponentType<Sprite>() {}
    }
}

Because type() is a function, we can basically do whatever we want and therefore reuse the same component class for different purposes.

Systems

Since we cannot get annotations in KMP, I adapted the existing approach of defining the family configuration in a system's constructor. For that, I added a new family function with a new FamilyDefinition configuration to define the family and removed the allOf, anyOf, noneOf arguments with a single family argument.

This has two advantages imo:

1. Users must provide a family and cannot forget it anymore. Before this was not immediately visible because allOf, anyOf and noneOf had a default to an empty collection.
2. The amount of constructor arguments for an IteratingSystem gets reduced

Here is an example of the new syntax:

private class PositionSystem : IteratingSystem(family { all(Position) }) {
    override fun onTickEntity(entity: Entity) {
        entity[Position].x++ // <-- new way of retrieving components
    }
}

Note, that ComponentMapper are no longer necessary from a user's point of view. Via entity[Position] we can now simply access the position component of an entity.

Also, family definitions no longer need the ::class syntax. The allI, none and any functions of a FamilyDefinition take a vararg of ComponentType.

❓ Shall we use the familyDefinition approach? Or is the previous approach nicer?

The configureEntity function got replaced with an extension function for an Entity. Instead of writing configureEntity(entity) { ... } it is now entity.configure { ... }. This is a minor change but I think it is easier to read. Also, the configuration API got changed from mappers to the new component approach. Here is an example of one of the benchmark systems that removes a FleksPosition component and adds a FleksLife component:

class FleksSystemComplex1 : IteratingSystem(family { all(FleksPosition).none(FleksLife).any(FleksSprite) }) {
    private var actionCalls = 0

    override fun onTickEntity(entity: Entity) {
        if (actionCalls % 2 == 0) {
            entity[FleksPosition].x++
            entity.configure { it += FleksLife() } // <-- new way of adding components
        } else {
            entity.configure { it -= FleksPosition } // <-- new way of removing  components
        }
        entity[FleksSprite].animationTime++
        ++actionCalls
    }
}

Finally, a new compareEntityBy function was added for easier sorting. You can now make any component implement the Comparable interface and then write the sorting code in that specific component. With that you can achieve something like this:

private data class SystemTestComponent(
    var x: Float = 0f
) : Component<SystemTestComponent>, Comparable<SystemTestComponent> {
    override fun type() = SystemTestComponent

    override fun compareTo(other: SystemTestComponent): Int {
        return other.x.compareTo(x)
    }

    companion object : ComponentType<SystemTestComponent>()
}

private class SystemTestIteratingSystemSortManual : IteratingSystem(
    family = family { all(SystemTestComponent) },
    comparator = compareEntityBy(SystemTestComponent), // <-- easy and concise way to create an EntityComparator
    sortingType = Manual
) {
    // ... rest of the code omitted
}

Entities

As seen above, entity configuration and also the creation got adjusted to the new components implementation. Here are some examples:

    @Test
    fun testComponentHooks() {
        val addComponent = Position(0f, 0f)
        val removeComponent = Position(0f, 0f)
        lateinit var testWorld: World
        testWorld = world {
            components {
                // example of an onAdd hook for a position component. 'component' is of type Position
                onAdd(Position) { world, entity, component ->
                    component.x = 1f
                    assertEquals(testWorld, world)
                    assertTrue { entity.id in 0..1 }
                    assertTrue { component in listOf(addComponent, removeComponent) }
                }

                // example of an onRemove hook for a position component. 'component' is of type Position
                onRemove(Position) { world, entity, component ->
                    component.x = 2f
                    assertEquals(testWorld, world)
                    assertEquals(Entity(1), entity)
                    assertEquals(removeComponent, component)
                }
            }
        }

        // entity that triggers onAdd hook
        testWorld.entity { it += addComponent }
        // entity that triggers onRemove hook
        val removeEntity = testWorld.entity { it += removeComponent }
        testWorld.configure(removeEntity) { it -= Position }

        assertEquals(1f, addComponent.x)
        assertEquals(2f, removeComponent.x)
    }

    @Test
    fun testFamilyHooks() {
        lateinit var testWorld: World
        lateinit var testFamily: Family
        var numAddCalls = 0
        var numRemoveCalls = 0
        testWorld = world {
            testFamily = family { all(Position) }
            families {
                // example of an onAdd hook for a family with allOf=Position
                onAdd(testFamily) { world, entity ->
                    ++numAddCalls
                    assertEquals(testWorld, world)
                    assertTrue { entity.id in 0..1 }
                }

                // example of an onRemove hook for a family with allOf=Position
                onRemove(testFamily) { world, entity ->
                    ++numRemoveCalls
                    assertEquals(testWorld, world)
                    assertEquals(Entity(1), entity)
                }
            }
        }

        // entity that triggers onAdd hook
        testWorld.entity { it += Position(0f, 0f) }
        // entity that triggers onRemove hook
        val removeEntity = testWorld.entity { it += Position(0f, 0f) }
        testWorld.configure(removeEntity) { it -= Position }
        // trigger family update to call the hooks
        testFamily.updateActiveEntities()

        assertEquals(2, numAddCalls)
        assertEquals(1, numRemoveCalls)
    }

ComponentListeners and FamilyListeners

I thought about this and in my opinion it is actually useless to have a list of listeners because why would someone register multiple listeners for the same component/family? At least I never used that and I could not come up with why I would ever do that.

That's why I changed the listener approach to a "hook" approach. It is basically the same but you specify only one add/remove hook per component/family. That way we don`t need to iterate over a list of listeners all the time which always has the size 1.

Important to note is that a hook always gets the world instance as an argument and the world now keeps the registered injectables and does not remove them anymore after creation. That way you can still get any relevant object into your hook code.

Here is an example of a component and a family hook. Fleks distinguishes between an add and remove hook. It is not necessary to add the code directly to the WorldConfiguration. It can of course link to a function in a different file.

    @Test
    fun testComponentHooks() {
        val addComponent = Position(0f, 0f)
        val removeComponent = Position(0f, 0f)
        lateinit var testWorld: World
        testWorld = world {
            components {
                // example of an onAdd hook for a position component. 'component' is of type Position
                onAdd(Position) { world, entity, component ->
                    component.x = 1f
                    assertEquals(testWorld, world)
                    assertTrue { entity.id in 0..1 }
                    assertTrue { component in listOf(addComponent, removeComponent) }
                }

                // example of an onRemove hook for a position component. 'component' is of type Position
                onRemove(Position) { world, entity, component ->
                    component.x = 2f
                    assertEquals(testWorld, world)
                    assertEquals(Entity(1), entity)
                    assertEquals(removeComponent, component)
                }
            }
        }

        // entity that triggers onAdd hook
        testWorld.entity { it += addComponent }
        // entity that triggers onRemove hook
        val removeEntity = testWorld.entity { it += removeComponent }
        testWorld.configure(removeEntity) { it -= Position }

        assertEquals(1f, addComponent.x)
        assertEquals(2f, removeComponent.x)
    }

    @Test
    fun testFamilyHooks() {
        val testFamilyDef = familyDefinition { allOf(Position) }
        var numAddCalls = 0
        var numRemoveCalls = 0
        lateinit var testWorld: World
        testWorld = world {
            families {
                // example of an onAdd hook for a family with allOf=Position
                onAdd(testFamilyDef) { world, entity ->
                    ++numAddCalls
                    assertEquals(testWorld, world)
                    assertTrue { entity.id in 0..1 }
                }

                // example of an onRemove hook for a family with allOf=Position
                onRemove(testFamilyDef) { world, entity ->
                    ++numRemoveCalls
                    assertEquals(testWorld, world)
                    assertEquals(Entity(1), entity)
                }
            }
        }

        // entity that triggers onAdd hook
        testWorld.entity { it += Position(0f, 0f) }
        // entity that triggers onRemove hook
        val removeEntity = testWorld.entity { it += Position(0f, 0f) }
        testWorld.configure(removeEntity) { it -= Position }
        // trigger family update to call the hooks
        testWorld.family(testFamilyDef).updateActiveEntities()

        assertEquals(2, numAddCalls)
        assertEquals(1, numRemoveCalls)
    }

❓ Shall we keep the hook approach? Or shall we go back to the listeners approach?

Injectables

As mentioned before, injectables are no longer cleared after the world is created. The main reason is the new hook approach.

But there are also other changes like e.g. the removal of the Inject object. Since the world is now keeping references to the different injectables, we can directly use the world to inject stuff. Also, it is now possible to do constructor DI instead of just property DI. Imo constructor DI is always preferable because it creates cleaner code and makes it easier to test classes when you directly see their dependencies. In order for that to work, the world creation process was adjusted a little bit and a new inject function was added.

Here is an example of a system that showcases both DI mechanisms:

private class SpriteSystem(
    val cstrInjectable: String = inject() // <-- constructor DI via the global inject function
) : IteratingSystem(family { any(SpriteBackground, SpriteForeground) }) {
    val propInjectable: String = world.inject("qualifiedString") // property DI via world.inject. The global function will work here as well

    override fun onTickEntity(entity: Entity) = Unit
}

WorldConfiguration

As already seen in some examples above, the configuration of the world has also changed slightly because of the removal of the listeners but also, because of the removal of factory methods for systems. Systems are now directly created which makes it imo easier to understand the code and also to debug the creation process, if necessary.

It is important, that the systems block comes last in the configuration when family or component hooks are registered. Fleks takes care of that and throws a new FleksWrongConfigurationOrder exception if users fail to do so. The reason is that system constructors can create new entities and if user hooks are registered after system creation, then of course they are not called correctly for such entities.

Here is an example test case with component hooks and a system:

    @Test
    fun notifyComponentHooksDuringSystemCreation() {
        var numAddCalls = 0
        var numRemoveCalls = 0

        world {
            components {
                onAdd(WorldTestComponent) { _, _, _ -> ++numAddCalls }
                onRemove(WorldTestComponent) { _, _, _ -> ++numRemoveCalls }
            }

            systems {
                add(WorldTestInitSystem())
            }
        }

        assertEquals(1, numAddCalls)
        assertEquals(0, numRemoveCalls)
    }

Changelog:

• [x] BUGFIX: Entities created inside a system's constructor are now properly added to their family and also EntityListener get notified correctly in this case
• [x] BUGFIX: ComponentListener did not get notified when entities are created in a system's init block
• [x] UPDATE: change dokka from 1.6.10 to 1.6.21
• [x] UPDATE: the used parameter of an injectable is removed because injectables are now properly resolved and cleared once the world is created
• [x] NEW: make world a default dependency for the dependency injection mechanism. That way it is now possible to easily pass the world to a ComponentListener
• [x] NEW: add getter for world's systems
• [x] NEW: add configureEntity to world. This makes it now possible to modify an entity outside of a system as requested in the comments section of my YouTube channel
• [x] NEW: add support to create families out of a system via the world. This is the biggest change of this version and adds new flexibility on how to handle and iterate over entities with specific component configurations
• [x] NEW: users have now access to the family of an IteratingSystem
• [x] NEW: family now also contains a configureEntity function which allows users to modify an entity outside of a system in a convenient way
• [x] NEW: a new FamilyListener support is added which allows users to react on when an entity is added to, or removed from a family
• [x] NEW: new DSL to create a world. Use components , systems, injectables or families block to define your world. For more details, refer to the ReadMe
• [x] NEW: the KMP setup was updated to a proper multiplatform gradle setup. That way it is now possible to add Fleks to a KorGE dependency via following line in the korge block

  dependencyMulti("io.github.quillraven.fleks:Fleks:1.3-KMP", registerPlugin = false)
  

This PR contains all the changes that were missing in the KMP branch that got added in the 1.1-JVM, 1.2-JVM and 1.3-JVM version.

In addition it changes the gradle setup to be a real KMP project. Most of the code is in commonMain but there are some testcases in other source sets because when it comes to exceptions then the different backends are behaving differently.

Not sure if this is the best solution to do it but for now let's roll with it ;) As an example, in JS there is no IndexOutOfBoundsException when accessing an invalid array position. It won't show any error but the result is most likely undefined.

It also contains some changes that were done in this PR: https://github.com/Quillraven/Fleks/pull/37

With the new setup it should be now possible to add Fleks as a normal dependency to KorGE like this:

dependencyMulti("io.github.quillraven.fleks:Fleks:1.3-KMP", registerPlugin = false)

I am not an expert when it comes to Kotlin MPP but I guess it should not be super difficult to convert the current code to MPP? Would be great if we can achieve this to support any backend.

Please share good articles/tutorials about MPP or create a PR yourself! Would be much appreciated.

In general we should improve the way to debug and analyze Fleks. Imo it is currently impossible to understand which bit of a BitArray is set which makes it hard to e.g. debug entities of a family before the bag gets updated or the component mask of an entity.

In addition, it is not comfortable to immediately see which entities have which components because of the performant and efficient way things are stored internally.

I am thinking of a toMap function for the world where the key is the entity and the value is a list of components of that entity.

Such a map can e.g. easily be converted to a JSON string for serializing but it also allows an easy overview of the current state of the world, it's entities and its components.

That should not be hard to implement with the information that the EntityService already has. It knows the active entities and the component mask of each entity which is the ComponentMapper ID of each component of the entity. The mapper can already be retrieved via the ID with the ComponentService.

The content on the next branch should not be the same as for release 1.2-JVM. After some testing we could publish release 1.2-KMP.

I will also try to use directly this version in my stand alone Korge game. If that works I could drop Korge-fleks again.

I want a way to be able to easily get a family of entities with certain components that's decoupled from the systems.

Example:

        val familyContainer = world.familyContainer(
            allOf = ...,
            anyOf = ...,
            noneOf = ...,
        )
        val entities: List<Entity> = family.getEntities()

The family container should be automatically updated on addition/removal of entities and addition/removal of their components.

Fleks has two separate versions at the moment:

• JVM backend - master branch
• Kotlin Multiplatform - kmp branch

The future, in my opinion, is the kmp branch which currently has a slightly different API than the master branch.

The things that we should have a look at is:

• How to avoid that users need to register components to the world as this is a little bit redundant and tidious setup
• In general, is it possible to get rid off the WorldConfiguration? If we can remove the component setup from above then it might be possible to also remove ComponentListener and System setup. The only thing left would be the entity capacity which can be directly passed to the world and the dependency injection (see next point).
  • As an idea: introduce new @Component and @System(priority : int) annotations. Users can add them to their component/system classes and via annotation processing we can maybe automatically register them to the world.
• If we go for the annotation processing route then it is maybe also possible to replace Inject.dependency and Inject.componentMapper with an annotation to be consistent.
  • Idea: here we can maybe go the other route and mark injectables with an @Injectable annotation. They will then be collected during the processing step and can be directly passed to the system constructors?
• Optional: bring back the family annotations instead of using properties in the system

As an alternative, if we do not want to go for the annotations route, we could think about a declarative api but then we should maybe remove the dependency injection part to create something like:

val world = World {
  lateinit var boundaryMapper : ComponentMapper<BoundaryComponent>
  lateinit var moveMapper: ComponentMapper<MoveComponent>
  lateinit var renderMapper: ComponentMapper<RenderComponent>

  components {
    boundaryMapper  = add<BoundaryComponent>()
    moveMapper = add<MoveComponent>()
    renderMapper = add<RenderComponent>()
  }

  systems {
    MoveSystem(textureAtlas, eventManager, moveMapper, boundaryMapper ) {
      allOf<MoveComponent, BoundaryComponent>
    }
    RenderSystem(spriteBatch, camera, boundaryMapper, renderMapper) {
      allOf<BoundaryComponent, RenderComponent>
    }
  }
}

The advantage of this version is that no magic is happening and it describes everything you need to know in an understandable way. The disadvantage is that a few things are redundant like e.g. I personally do not like that I have to add components or create ComponentMapper. It would be great if defining a Component class would be sufficient somehow.

As per the #66 discussion, this PR is updating the existing IntBag functionality with certain Kotlin collection stdlib functions.

Following things are adjusted:

• rename IntBag to EntityBag: this change also includes converting the underlying IntArray to Array<Entity> and changing Entity back to a value class. For some reason it is a data class (I guess this is some leftover of the previous KMP branch changes)
• rename entityBag inside family to entities and expose it (internal -> public)
• add a new asEntityBag function to the world
• add collection stdlib functions to EntityBag

Additionally, this PR updates Kotlin and Dokka from 1.7.10 to 1.7.20.

Code adjustments are done but I am missing the tests currently and the documentation of the new functions. Following functions are now available for EntityBag:

• size: this is actually a property
• contains
• containsAll
• isEmpty, isNotEmpty
• all, any, none
• associate, associateBy, associateTo, associateByTo
• count
• filter, filterNot, filterIndexed, filterTo, filterNotTo, filterIndexedTo
• find
• first, firstOrNull
• fold, foldIndexed
• forEach, forEachIndexed
• map, mapIndexed, mapTo, mapIndexedTo
• random, randomOrNull
• take

New feature was added which makes it possible to mark an injectable as "used". Thus Fleks will not throw exception if the injectable is not used directly at creation of system and listener objects. Ie. that makes it possible to use the injected objects during init functions. Default for use is still "false" as before.

• Adapt registering of systems in World

Instantiation of generic classes is not possible in Kotlin multiplatform. Thus, instead of instantiating a generic class in the SystemService the system function gets a factory method for calling the constructor of the system.

• Introduce adding of component and its listener in world configuration

The component listener will be added together with registering the component in the world configuration. That was done because when registering the component listener the base type of the component is needed. But without java reflections it is not possible to detect the type of component listeners. Thus, adding component and listener objects together is the most elegant workaround for now - I hope.

• Adapted readme to reflect changed API

• Adapted Fleks benchmark

~~Currently registering of systems is not working in the benchmark fleks.kt. In my Korge example it is working that way. It could be that this is due to some multiplatform configuration in Korge. But currently this is beyond my understanding. :(~~

Stupid mistake. Now the benchmark is working. Only the complex one is failing due to an exeption.

• Renaming some variables

I changed cmp to comp because especially at the beginning I read e.g. cmpMapper as "compareMapper" and not "componentMapper" which was a bit confusing.

Hi Simon, I think I found a bug in the 2.1 version. So I have a extension that check if a certain family is in a position:

fun Position.findEntitiesInPosition(family: Family): List<Entity> {
    val entities = mutableListOf<Entity>()
    family.forEach {
        if (it.has(Position)
            && it[Position].x == x
            && it[Position].y == y
        ) {
            entities.add(it)
        }
    }
    return entities
}

I use this to see if I can move to a target position

class MoveSystem(
    private val maxWidth:Int = inject("maxWidth"),
    private val maxHeight:Int = inject("maxHeight")
) : IteratingSystem(family { all(Position, Moving).none(Dead)}) {
    override fun onTickEntity(entity: Entity) {
        val originalPosition = entity[Position]
        val targetPosition = entity[Moving].target
        // position is within the limit and position is not occupied
        if (targetPosition.positionWithin(maxWidth, maxHeight)
            && targetPosition.findEntitiesInPosition(world.family { all(Position, Solid) }).isEmpty()){
            originalPosition.x = targetPosition.x
            originalPosition.y = targetPosition.y
        }

        entity.configure { it -= Moving }
    }

So for the version 2.0 this was working fine but I recently upgraded to 2.1 and now it is failing the test below:

    @Test
    fun shouldMoveIntoADeadObject(){
        val x = 5
        val y = 5
        val original = Position(x, y)
        val target = Position(8,8)
        val entity = world.entity {
            it += original
            it += Moving(target)
        }

        val toDie = world.entity{
            it += target
            it += Solid()
        }

        world.update(1f)
        // Check I cannot move
        Assertions.assertEquals(original, Position(x,y))
        Assertions.assertNotEquals(original, target)

        with(world){
            toDie.configure {
                it -= Solid
                it += Dead()
            }
            entity.configure { it += Moving(target) }
        }

        world.update(1f)
        // Check it should have moved
        Assertions.assertEquals(original, target)
    }