Welcome to Fleks Discussions!

[Quillraven]

👋 Welcome!

Discussions is the place to talk about Fleks like new ideas or feedback for the library. I hope that you:

• Ask questions you’re wondering about.
• Share ideas.
• Welcome others and are open-minded. Remember that this is an open source project and we
  build together 💪.

---

Some technical details that I found out during the development of Fleks

Entity as Class vs Entity as Int

• Storing and iterating over an Array<Entity> is slower than having an IntArray. Also, creating an instance of Entity is slower than creating an Int
• That's the reason why Fleks (and also Artemis) are using Int internally for storing entities
• Artemis also allows an optional usage of an Entity class but I think we don't need that for Fleks. With a clean API in Kotlin, having an Int as entity shouldn't be an issue

ComponentMapper

• A naive approach to store components would be via a map of type <KClass<out Component>,Component>. However, this is very slow because:
  • hashing and a map are slower than an array
  • getting the class of a component is slower than using a fixed index
• That's the reason why Ashley/Artemis introduce so called ComponentMapper. To keep it simple: it assigns a unique index to a component and this index is used for an array that stores all component instances of that type
• Unfortunately, Java/Kotlin do not allow static inheritance because if they would, we could simply define a static Int which is different for each component. Since that is not possible, we need those ComponentMapper instances
  • someone in my stream mentioned something about annotation pre-compiling or something like that which automatically generates some code for the user. The idea was to use an annotation like @Component which automatically assigns a static int to that class with a unique number. But I didn't understannd how that could be used because Fleks internally needs to access that index in the code and since it doesn't know about that static int it cannot use it. Maybe I missed something here but for now we have to live with the mappers

System

• To optimize the storage of systems they are mandatory for the world's creation which should not be a problem because you can enable/disable a system and therefore simply turn off systems that you don't need from the start
• Both Ashley and Artemis have a lot of different systems which can be broken down to different combinations of an IteratingSystem that iterates over a specific configuration of entities and a IntervalSystem that runs periodically without a context to entities
• I personally do not like that approach and tried to simplify it in Fleks by providing only two systems. Both have a tickRate which can be used to create the different combinations of systems that Ashley/Artemis have.
• There might be a minor performance impact because the systems check if the tickRate is 0 or not and then handles it slightly differently but in my opinion this can be ignored for a cleaner/more user-friendly API

Custom Collections

• There are currently two custom collections in Fleks
  • Bag: it is basically a flexible Array that resizes automatically and doesn't keep the order of added entries. Since arrays are the fastest way to store/iterate over things, this is a very useful collection
  • BitArray: Kotlin implementation of a BitSet. It is based on LibGDX's Bits implementation and not finalized yet. I think we also need that for multi platform because Java's BitSet is not available in all backends?
• There is a special IntBag implementation to avoid autoboxing

Family

• Family (=Aspect in Artemis) is a container for entities of a specific configuration of components and is in my opinion the most performance critical part in an ECS
• I tried a lot of different collection types for storing entities and entity changes but in the end I went for custom collections like Ashley/Artemis are doing it
• For whatever reason it is a lot faster to set an index of a BitSet than adding an Int to a Set<Int>. I also tried a custom implementation of IntSet to avoid autoboxing but it didn't even get close to the speed of a BitSet
  • The BitSet is used to remember updated entities which are part of the family
  • Ideally, when an entity configuration changes an interested family gets notified only once instead of once per component add/remove call
  • Currently, we have World.configureEntity for that to only make one notification call but I am not happy with this part of the API yet. Would be better if users can directly use the ComponentMapper to add/remove components but I don't know yet how to make then only one notification call to interested families
• Iterating over a BitSet is slower than iterating over an IntArray because there can be empty space between two set bits. That's the reason why we also have an IntBag per family to store the active entity ids for the fastest way to iterate over them

Pooling vs Non-pooling for Components

• For now I didn't go for pooling of components in Fleks because it makes it slightly more complex and we also will need to introduce a reset method for components which is very often just a redundant assignment of values that you already do in the constructor
• I am interested if I or other people will experience some issues without pooling. GC and hardware is improving all the time and I am not sure if the problems from years ago still apply to today
• That said, if pooling is needed then I don't want to make a split between Component/PooledComponent. In my opinion we will just go then with pooling as default and only option

[Quillraven]

@czyzby / @Jkly / @nanodeath: I saw that all of you were part of the initial ktx-ashley issue for libktx. I would appreciate if you could give some feedback for Fleks whenever you have time. Also, feel free to contribute/suggest changes. You can find the motiviation/reasons for writing a Kotlin ECS and how to use it in the ReadMe.
I also added some technical details/my thought process to the opening post of this discussion.

I am currently super busy at work and plan to have my holidays "soonish". That's why I might not be able to implement changes that fast.
However, I will always participate in any discussions.

Thank you for your help and feedback in advance! Maybe we can build a great ECS in Kotlin together and provide an alternative to Ashley/Artemis ;)

[nanodeath]

BTW, you may also be interested in https://github.com/nanodeath/korge-ecs which is a little prototype I worked on last year.

[Quillraven]

Thanks! I had a quick look and I am wondering, why is it necessary to register component types? I remember in one of my approaches I had that as well but in the end it wasn't needed because that can be created internally and the user doesn't need to bother.

[czyzby]

That's the reason why Fleks (and also Artemis) are using Int internally for storing entities

Use a @JvmInline value class Entity(val id: Int). AFAIK that should be an equivalent of using Int performance-wise, but gives the ability to add extension methods. They can even be scoped to specific systems. Quick and dirty example:

@JvmInline value class Entity(val id: Int)
interface Component
data class Position(val x: Float, val y: Float): Component

class System {
  inline fun <reified T: Component> Entity.getComponent(): T =
    TODO("Use $id to extract ${T::class} component.")
}

fun example() {
  val system = System()
  val entity = Entity(1)
  system.run { 
    val position = entity.getComponent<Position>()
  }
}

Unfortunately, Java/Kotlin do not allow static inheritance because if they would, we could simply define a static Int which is different for each component. Since that is not possible, we need those ComponentMapper instances

It kinda does with companion object, if you're open to requiring your users to define one. Here's a proof of concept that obtains unique ID for each component:

// With generics:
interface Component {
  companion object {
    val COMPONENT_ID = AtomicInteger()
  }
}

abstract class Mapper<T: Component>(val id: Int = Component.COMPONENT_ID.getAndIncrement())

data class Position(val x: Float = 0f, val y: Float = 0f): Component {
  companion object ID: Mapper<Position>()
}

class System {
  fun <T: Component> getComponent(mapper: Mapper<T>): T = TODO("Fully typed, based on mapper!")
}

fun example() {
  val system = System()
  // No casting or generic required, will infer Position type.
  val position = system.getComponent(Position.ID)
}

companion object approach does require more boilerplate than a @Component annotation, but there's no code generation or annotation processing involved. I think it's a safer approach that will be much less error-prone and easier to implement. However, it does depend on a static mutable variable. If the user has multiple Worlds, they would likely need separate mappers with manually assigned IDs, especially if the worlds do not share all components.

Proof of concept that would be more flexible in terms of custom IDs/multiple systems, but requires more user setup:

interface Component
typealias MapperIdProvider = () -> Int
class ThreadSafeMapperIdProvider: MapperIdProvider {
  private val id = AtomicInteger()
  override fun invoke(): Int = id.getAndIncrement()
}
abstract class Mapper<T: Component>(idProvider: MapperIdProvider) {
  val id: Int = idProvider()
}

// Usage (library user POV):

val idProvider = ThreadSafeMapperIdProvider() // Might want a shorter name for that, just sayin'.

data class Position(val x: Float, val y: Float) : Component {
  companion object ID : Mapper<Position>(idProvider)
  // Can work for multiple worlds - in fact, object does not have to be a companion in the first place:
  object MY_SPECIAL_SYSTEM_ID : Mapper<Position>(TODO("Some other provider"))
}

fun example() {
  // Both work:
  Position.ID
  Position.MY_SPECIAL_SYSTEM_ID
}

That said, if pooling is needed then I don't want to make a split between Component/PooledComponent. In my opinion we will just go then with pooling as default and only option

I'd go for separate classes, actually. Maybe not necessarily for PooledComponent, but for PooledWorld with some extra methods that allow you to obtain and return components instances. It's a functionality that adds something on top of plain ECS, which might be unnecessary for many use cases (e.g. desktop games, smaller systems). Pooling done wrong can be a larger issue that just going for a plain approach and optimizing when necessary. The good news is that you probably don't have to resort to reflection or Unsafe, as you can ask the users to define () -> Component providers, or even handle that automatically in the mapper (abstract method in Mapper requiring the users to implement it, or platform-specific ReflectionMapper/UnsafeMapper using Java magic to create instances).

[Quillraven]

@czyzby : I now had some time to do minor modifications and think it through once more and for now I will stick to the current approach because mainly it is the least effort from a user point of view and I personally like that you have to define the necessary mappers per system. It makes it easy to see which components are needed by a system by just looking at the constructor.

I followed your proposal from above and configureEntity is now part of the IteratingSystem and inside the lambda of this function you have special ComponentMapper extension functions.

Thank you again for your feedback! I have one question where you might be able to help. Currently, I am missing the functionality to sort entities by a custom comparator. Normally, Kotlin has a sortWith function but this seems to be not available for IntArray which is internally used by the IntBag class that I introduced to avoid autoboxing of Int.

It is available though for Array<Entity> which is Array<Int> in the end. I guess this introduces boxing/unboxing again? What is the best way to sort an IntArray by a comparator in Kotlin?`

The use case is that sometimes you need to sort entities before iterating over them like e.g. in a RenderSystem where you want to sort your entities by the y-coordinate to get the correct render order. How would you approach that?

[czyzby]

It is available though for Array<Entity> which is Array<Int> in the end. I guess this introduces boxing/unboxing again? What is the best way to sort an IntArray by a comparator in Kotlin?`

I don't think there's a way to do this, since Comparator interface would box the variables either way. You'd need an IntComparator working on primitives to achieve that. A custom extension method for IntArray seems like the correct approach in this case, especially since you can choose the right sorting algorithm for your use case.

After a quick Google search, I've found this library that does what you need. However, it would only work in Java, and it seems like an unnecessary dependency at this point. Consider checking their sources and implementing your own sorting method based on that.

[Quillraven]

Sorting is now available as part of commit c8bbd2d

I used the quick sort algorithm to have in place sorting without the need of an additional array. I also read somewhere that this is the preferred sorting algorithm for arrays.

Also, added a compareEntity function that returns an EntityComparator and can be passed as a parameter to an IteratingSystem.

@AllOf([Position::class])
class TestSystem(
    private val eventSystem: EventSystem,
    private val number: Int = eventSystem.number,
    private val positions: ComponentMapper<Position>
) : IteratingSystem(compareEntity { entA, entB -> positions[entA].y.compareTo(positions[entB].y) }) {
    override fun onTickEntity(entity: Entity) {
        println("$number $entity ${positions[entity]} ${world.deltaTime}")
    }
}

For now I am happy and this covers at least my use cases. However, I am not 100% sure if sorting per update call is ideal for every user. Right now sorting is happening automatically when you pass in a comparator to an IteratingSystem. For me, this is what I need but maybe it should be a user decision? Maybe a sort method as part of IteratingSystem is a better solution and users just call that whenever they need it?
For me, it will make it a little less convenient but for the users out there it might be better... not sure ;)

[czyzby]

You might consider adding extension support, which would allow the users to add functionality like sorting on specific events (e.g., before or after iteration over systems). That would be a bit more flexible.

[Quillraven]

I changed it now a little bit by adding a SortingType parameter. If it is set to Automatic - which is the default - then it behaves like it does right now and which is my use case ;)

If you set it to Manual then it is up to the user when he wants to sort. For that he simply sets a doSort flag to true and the system will sort the next time it gets updated.

I went the flag approach instead of overriding a function because sorting must be done after the family is up to date and to keep that order I thought it is the simplest way to just set this flag. It then gets cleared automatically after a sort is done and needs to be set again whenever needed.

That should allow to support all needs when it comes to sorting, I hope.

[Quillraven]

I will post here some things that I noticed during the development of the RPG tutorial game. Until now I could solve things differently but I think they might make sense to add it to Fleks:

• Provide a way to get all systems of a world: currently you can only get a specific system but I had a case where I wanted to iterate over all of them and get the ones which have a specific interface implemented. A simple getter might do the trick
• Provide a way to get entities of a specific component configuration: I had a use case where I wanted to have all player entities within a system but the system itself was iterating over a completely different family. It might be cool to create families on demand after world creation. It will have some initial performance impact to update the family with existing entities. Also, we most likely need to store families in a different way because asking for the same family multiple times should always return just one family. Maybe a map makes sense and the key is the allOf/anyOf/noneOf configuration of the family
• someone on YouTube mentioned that you cannot modify an entity's components outside of a system. You can get a mapper of the world but you cannot call e.g. configureEntity in that case. Should not be a problem to add that to the world as well since it cann also notify all EntityListener like families to guarantee a correct behavior
• make World an injectable during creation: my use case was that I needed it for a ComponentListener for some LibGDX AI initialization to easily create and update my StateEntity like :

  data class StateEntity(
      val entity: Entity,
      val world: World,
      private val stateCmps: ComponentMapper<StateComponent> = world.mapper(),
      private val animationCmps: ComponentMapper<AnimationComponent> = world.mapper(),
      private val moveCmps: ComponentMapper<MoveComponent> = world.mapper(),
      private val attackCmps: ComponentMapper<AttackComponent> = world.mapper(),
      private val lifeCmps: ComponentMapper<LifeComponent> = world.mapper(),
  ) {
      val wantsToMove: Boolean
          get() {
              val moveCmp = moveCmps[entity]
              return moveCmp.cos != 0f || moveCmp.sin != 0f
          }
  
      val wantsToAttack: Boolean
          get() = attackCmps.getOrNull(entity)?.doAttack ?: false
  
      val moveCmp: MoveComponent
          get() = moveCmps[entity]
  
      val attackCmp: AttackComponent
          get() = attackCmps[entity]
  
      fun animation(type: AnimationType, mode: PlayMode = PlayMode.LOOP) {
          with(animationCmps[entity]) {
              nextAnimation(type)
              this.mode = mode
          }
      }
  
      fun resetAnimation() {
          animationCmps[entity].stateTime = 0f
      }
  
      fun state(newState: EntityState) {
          stateCmps[entity].nextState = newState
      }
  
      fun changeToPreviousState() {
          with(stateCmps[entity]) {
              nextState = stateMachine.previousState
          }
      }
  
      fun startAttack() {
          attackCmps[entity].startAttack()
      }
  
      fun isDead(): Boolean = lifeCmps[entity].isDead()
  }