Generic Components

[ernespn]

Hi Simon,
Nice frameworks you have built here.
I'm working in roguelike using fleks which I found quite easy to use.
I'm facing a problem which maybe is more related to kotlin but would like to run it by you as you may have encountered this in the past.

I'm working in a system to transfer component from an entity to another something like:

class TransferComponentSystem :  IteratingSystem(World.family { all(TransferFrom).none(Dead) }){
    override fun onTickEntity(entity: Entity) {
        val entitySource = entity[TransferFrom].entity
        val componentType = entity[TransferFrom].transferableComponent
        val componentToTransfer = entitySource[componentType]
        entity.configure {
            it += componentToTransfer
            it -= TransferFrom
        }
        entitySource.configure {
            it -= componentType
        }
    }
}

The component class is this one:

data class TransferFrom(val entity: Entity, val transferableComponent: Damage.Companion) : Component<TransferFrom> {
    override fun type(): ComponentType<TransferFrom> = TransferFrom
    companion object : ComponentType<TransferFrom>()
}

This works well when there is one type of component, but I would like to generalise so multiples component can be transferred (Eg. Health, Fire, etc..).
But I cannot find the way to use the type in the transferableComponent type.
I would appreciate any input/suggestion/recommendations of how to do this.

Here is the test cases so it may help to run the code:

class TransferComponentSystemTests {
    private val world = world {
        systems {
            add(TransferComponentSystem())
        }
    }


    @Test
    fun itShouldTransferTheEffectToTheUser(){
        val usable = world.entity {
            it += Damage(1)
        }

        val user = world.entity {
            it += TransferFrom(usable, Damage)
        }

        world.update(1f)

        with(world){
            Assertions.assertTrue(user.hasNo(TransferFrom))
            Assertions.assertTrue(user.has(Damage))
            Assertions.assertTrue(usable.hasNo(Damage))
        }
    }

    @Test
    fun itShouldTransferDifferentEffectToTheUser(){
        val usable = world.entity {
            it += Health(1)
        }

        val user = world.entity {
            it += TransferFrom(usable, Health)
        }

        world.update(1f)

        with(world){
            Assertions.assertTrue(user.hasNo(TransferFrom))
            Assertions.assertTrue(user.has(Health))
            Assertions.assertTrue(usable.hasNo(Health))
        }
    }
}

[Quillraven]

Hi,

That's an interesting use case. I will have a look on the weekend because right now I cannot check it, sorry.

My first idea is that your TransferableComponent takes a type of ComponentType<*>. That way you should be able to get any component.

Since we cannot use reified in this case the correct type information will be lost and most likely you need a cast to Component<*> in your system when you retrieve the component in a generic way. You should be then able to add it.

Said that, it might not be possible yet because the current functions for getting and adding components are reified and therefore typesafe.

I might need to add a non typesafe variant to support your use case.

Can you explain a little bit what is the purpose of your scenario here and why you do it like that? E.g. why don't you remove/add the specific components directly where you currently use your TransferComponent?

[Quillraven]

@ernespn: I experimented a little bit now, and I see two solutions but still I'd like to know why you do it like that instead of modifying the components directly where you currently add your Transfer component.

Option 1

This is similar to what you tried and as I expected, it does not work currently in Fleks. I had to add another plusAssign operator that accepts a "wildcard" ComponentType to work. The result would be this:

class Damage : Component<Damage> {
    override fun type(): ComponentType<Damage> = Damage

    companion object : ComponentType<Damage>()
}

class Life : Component<Life> {
    override fun type(): ComponentType<Life> = Life

    companion object : ComponentType<Life>()
}

class Transfer(
    val target: Entity,
    val cmpType: ComponentType<out Component<*>>
) : Component<Transfer> {
    override fun type(): ComponentType<Transfer> = Transfer

    operator fun component1(): Entity = target

    @Suppress("UNCHECKED_CAST")
    operator fun component2(): ComponentType<Component<*>> = cmpType as ComponentType<Component<*>>

    companion object : ComponentType<Transfer>()
}

class TransferSystem : IteratingSystem(family { all(Transfer) }) {
    override fun onTickEntity(entity: Entity) {
        val (target, type) = entity[Transfer]
        val cmp = entity[type]

        entity.configure {
            it -= type
            it -= Transfer
        }
        target.configure { it += cmp }
    }
}

class Test {
    @Test
    fun testDamage() {
        val world = world {
            systems {
                add(TransferSystem())
            }
        }

        val e1 = world.entity()
        val e2 = world.entity {
            it += Damage()
            it += Transfer(e1, Damage)
        }

        with(world) {
            assertTrue(e1 hasNo Damage)
            assertTrue(e2 has Damage)

            world.update(0f)

            assertTrue(e1 has Damage)
            assertTrue(e2 hasNo Damage)
        }
    }

    @Test
    fun testLife() {
        val world = world {
            systems {
                add(TransferSystem())
            }
        }

        val e1 = world.entity()
        val e2 = world.entity {
            it += Life()
            it += Transfer(e1, Life)
        }

        with(world) {
            assertTrue(e1 hasNo Life)
            assertTrue(e2 has Life)

            world.update(0f)

            assertTrue(e1 has Life)
            assertTrue(e2 hasNo Life)
        }
    }
}

Option 2

This way works already in Fleks right now and imo it has the benefit that you are still getting the typesafety when transfering your components that way. The TransferComponent in this case contains a lambda that does the transfer stuff that you want to do. Here is how it looks:

class Damage : Component<Damage> {
    override fun type(): ComponentType<Damage> = Damage

    companion object : ComponentType<Damage>()
}

class Life : Component<Life> {
    override fun type(): ComponentType<Life> = Life

    companion object : ComponentType<Life>()
}

class Transfer(
    val action: EntityUpdateContext.() -> Unit
) : Component<Transfer> {
    override fun type(): ComponentType<Transfer> = Transfer

    companion object : ComponentType<Transfer>()
}

class TransferSystem : IteratingSystem(family { all(Transfer) }) {
    override fun onTickEntity(entity: Entity) {
        entity.configure {
            it[Transfer].action.invoke(this)
            it -= Transfer
        }
    }
}

class Test {
    @Test
    fun testDamage() {
        val world = world {
            systems {
                add(TransferSystem())
            }
        }

        val e1 = world.entity()
        val e2 = world.entity {
            it += Damage()
            it += Transfer {
                e1 += it[Damage]
                it -= Damage
            }
        }

        with(world) {
            assertTrue(e1 hasNo Damage)
            assertTrue(e2 has Damage)

            world.update(0f)

            assertTrue(e1 has Damage)
            assertTrue(e2 hasNo Damage)
        }
    }

    @Test
    fun testLife() {
        val world = world {
            systems {
                add(TransferSystem())
            }
        }

        val e1 = world.entity()
        val e2 = world.entity {
            it += Life()
            it += Transfer {
                e1 += it[Life]
                it -= Life
            }
        }

        with(world) {
            assertTrue(e1 hasNo Life)
            assertTrue(e2 has Life)

            world.update(0f)

            assertTrue(e1 has Life)
            assertTrue(e2 hasNo Life)
        }
    }
}

---

Which option do you prefer?

[Quillraven]

Glad you could resolve it and I think your solution should fix my bug because you have separate configure blocks per entity.

However, to be 100% sure I'd also check in your test if the entities are part of the correct families after the world update.
Unfortunately, this is not very intuitive and normally you won't face this special case but the way entity.configure is working, is that at the end of the configuration it will notify all families about the component change of the entity. When it comes to nesting you might run into the problem that you modify the components of the entity after the family notification was triggered and therefore it won't be correct. Or you modify an entity for which you did not call entity.configure and therefore the notification for that entity is not send at all.

I tried to come up with a solution to throw an error if such a scenario is happening but I couldn't come up with a good solution that doesn't impact performance that much. That's why we agreed in some other discussion to just update the documentation of this method and warn users about it.

In short: I suggest you also verify family correctness in your test to be safe. And as a general rule of thumb only modify the entity that you pass into entity.configure.

[ernespn]

I've just did a quick test and seems that it is working

@Test
    fun itShouldUpdateTheFamilyCorrectly(){
        val usable = world.entity {
            it += Damage(1)
            it += Transferable { e ->
                e.configure { entity -> entity += it[Damage]  }
                it -= Damage
            }
        }

        val user = world.entity {
            it += TransferFrom(usable)
        }

        val family = world.family { all(Damage) }
        assertTrue(family.contains(usable))
        assertFalse(family.contains(user))

        world.update(1f)

        assertTrue(family.contains(user))
        assertFalse(!family.contains(usable))
    }

Is this what you refer to?

[ernespn]

Actually forget what I just said... I did a mistake in the code for the test, and it is failing:

assertFalse(family.contains(usable))

[ernespn]

I think I found how to update the families, calling configure to the source entity. These seems to pass the test now

class TransferComponentSystem :  IteratingSystem(World.family { all(TransferFrom).none(Dead) }){
    override fun onTickEntity(entity: Entity) {
        val entitySource = entity[TransferFrom].entity
        if (entitySource has Transferable){
            entity.configure {
                entitySource[Transferable].action.invoke(this, entity)
            }
            entitySource.configure {  }
        }
        entity.configure {
            it -= TransferFrom
        }
    }
}

[Quillraven]

This is exactly what I meant and good that you tested it. This is a hard to identify bug imo.

The problem is that you can do things like:

e1.configure { e2+= Damage() }

Meaning that you can use any entity in the configure block which will correctly update the components but it will not update the families correctly.

This is not ideal, but as mentioned above, so far I couldn't come up with a nice solution for this specific problem.

What you could do is give your Transferable component two lambdas. One e.g. for the add component code and one for the remove component code. From what I understood this is applied to two different entities and therefore you could call those lambdas in the correct configure block like:

source.configure { transferableCmp.onRemove.invoke(this) }
target.configure{ transferableCmp.onAdd.invoke(this) }

I guess it is personal preference which way to go but the important
thing is that you got a working solution 🙂