Fleks ECS

Fleks is a fast, lightweight Entity Component System (ECS) library written in Kotlin. It is designed to be more concise and idiomatic than older ECS libraries like Ashley.

Key improvements in version 2.x include:

• Unified API: Combines KMP and JVM flavors into one.
• No Reflection: Completely removed reflection usage for better performance and easier debugging.
• Simplified API: ComponentMapper is no longer necessary, making the API more concise and readable.
• Null-Safety: Improved null-safety compared to older libraries.

An EntityProvider defines how entities are created, removed, and tracked within a World. It is a core component used by an EntityService to manage the lifecycle of Entity objects.

Users can specify a custom provider via WorldConfiguration. If no provider is specified, Fleks defaults to using DefaultEntityProvider.

Key responsibilities of an EntityProvider include:

• Creating new entities (create())
• Removing entities (entity -= entity)
• Tracking active entities (contains(entity))
• Iterating over active entities (forEach { ... })
• Resetting the provider (reset())

If you are implementing a custom provider, you must provide a reference to the World it operates on.

An EntityRef is a stable reference to an Entity that can be safely stored within components. Unlike raw Entity values, an EntityRef tracks its own validity. When the referenced Entity is removed from the World, the EntityRef becomes invalid, allowing you to detect stale references.

Key properties:

• entity: The underlying Entity being referenced.
• id: The integer ID of the referenced entity.
• valid: A boolean indicating if the reference is still active in the world.

Use the companion object extension functions to check validity safely, even on nullable references.

// Checking validity of a potentially null EntityRef
if (myEntityRef.isValid()) {
    // The entity is still alive in the world
    val id = myEntityRef.id
}

// Using the NONE constant for an invalid reference
val emptyRef = EntityRef.NONE
println(emptyRef.isValid()) // false

A ComponentsHolder<T> is responsible for storing all instances of a specific component type for all entities in a World. It uses an internal array where the index corresponds to the Entity.id.

Key Operations

• Set (operator fun set): Assigns a component to an entity. If a component of that type already existed, its onRemove lifecycle method is called first. Then, the new component is assigned and its onAdd method is called.
• Remove (operator fun minusAssign): Removes the component from the entity and triggers its onRemove lifecycle method.
• Get (operator fun get): Retrieves the component. Throws FleksNoSuchEntityComponentException if the entity does not have the component.
• Get Or Null (fun getOrNull): Returns the component or null if not present.
• Contains (operator fun contains): Returns true if the entity has the component.

An EntityTag is a specialized, data-less ComponentType used to tag entities. They are more memory-efficient than standard components.

You can use entityTagOf() to create a tag, or use the EntityTags type alias to make an enum class behave as a collection of tags. This is done by delegating to entityTagOf().

enum class MyTags : EntityTags by entityTagOf() {
    TAG_A, TAG_B
}

To use a class as a component in Fleks, implement the Component<T> interface. You must provide a ComponentType<T> via the type() function.

A common and convenient pattern is to use the class's unnamed companion object as its ComponentType by having the companion object inherit from ComponentType<T>.

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

    companion object : ComponentType<Position>()
}

To set up a Fleks World, use the configureWorld function. This function provides a DSL context via WorldConfiguration to define systems, injectables, entity hooks, and family hooks.

Note that configure() is called internally by configureWorld, which executes the configuration in a specific order:

1. Injectables
2. Families
3. Systems

This order ensures that hooks are correctly triggered during the world's lifecycle.

val world = configureWorld(entityCapacity = 1024) {
    // Configuration goes here
}

Use forEach to perform an action on every active entity currently managed by the EntityService. The action is executed within the context of the World.

entityService.forEach { entity ->
    // 'this' refers to the World
    println("Processing entity: ${entity.id}")
}

Clears all entities from the service.

• If clearRecycled is false (default): Only the active entities are removed.
• If clearRecycled is true: All entities are removed, and the internal state (recycled IDs, component masks, and references) is reset so that new entities start with ID 0.

// Remove active entities only
entityService.removeAll()

// Completely reset the service
entityService.removeAll(clearRecycled = true)

Systems in Fleks are instances of IntervalSystem. They are updated during the world.update() call if they are enabled.

Operations:

• Add a system: world += system or world.add(system)
• Remove a system: world -= system or world.remove(system)
• Retrieve a system: Use world.system<T>() to get a specific type, or world.systemOrNull<T>() if the system might not be present.
• Check for system: world.contains<T>()

Note: Adding the same system class twice will throw a FleksSystemAlreadyAddedException.

// Adding a system
world += MovementSystem()

// Retrieving a system later
val movementSystem = world.system<MovementSystem>()

// Checking if a system exists
if (world.contains<MovementSystem>()) {
    // ...
}