ktx.ashley.entities.kt Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ktx-ashley Show documentation
Ashley entity component system utilities for Kotlin LibGDX applications.
There is a newer version: 1.12.1-rc2
package ktx.ashley

import com.badlogic.ashley.core.Component
import com.badlogic.ashley.core.ComponentMapper
import com.badlogic.ashley.core.Engine
import com.badlogic.ashley.core.Entity
import kotlin.contracts.ExperimentalContracts
import kotlin.contracts.InvocationKind
import kotlin.contracts.contract

/**
 * Gets the specified [Component] from the [Entity] with a [ComponentMapper].
 *
 * @param T the [Component] type to get
 * @param mapper the [ComponentMapper] to retrieve the [Component] with
 * @return the specified [Component]. Otherwise `null` if the [Entity] does not have it.
 * @see ComponentMapper.get
 * @see mapperFor
 */
operator fun  Entity.get(mapper: ComponentMapper): T? = mapper.get(this)

/**
 * Gets the specified [Component] from the [Entity].
 *
 * Note that this function provides `O(log n)` performance for [Component] retrieval. It is recommended that retrieving
 * a [Component] is done using [get] consuming a [ComponentMapper].
 *
 * @param T the [Component] type to search for.
 * @return the specified [Component]. Otherwise `null` if the [Entity] does not have it.
 * @see ComponentMapper
 */
inline fun  Entity.get(): T? = getComponent(T::class.java)

/**
 * Checks whether the [Entity] has the specified [Component].
 *
 * @param T the [Component] type to inspect.
 * @param mapper the [ComponentMapper] to check the [Component] with.
 * @return `true` if the [Entity] has the specified component, and `false` otherwise.
 * @see ComponentMapper.has
 */
fun  Entity.has(mapper: ComponentMapper): Boolean = mapper.has(this)

/**
 * Checks whether the [Entity] does not have the specified [Component].
 *
 * @param T the [Component] type to inspect.
 * @param mapper the [ComponentMapper] to check the [Component] with.
 * @return `true` if the [Entity] does not have the specified component, and `false` otherwise.
 * @see ComponentMapper.has
 */
fun  Entity.hasNot(mapper: ComponentMapper): Boolean = !has(mapper)

/**
 * Checks whether the [Entity] has the specified [Component].
 *
 * @param T the [Component] type to inspect.
 * @param mapper the [ComponentMapper] to check the [Component] with.
 * @return `true` if the [Entity] has the specified component, and `false` otherwise.
 * @see ComponentMapper.has
 */
operator fun  Entity.contains(mapper: ComponentMapper): Boolean = mapper.has(this)

/**
 * Removes the specified [Component] from the [Entity].
 *
 * @param T the [Component] type to remove.
 * @return the removed [Component] instance (if was present and matched the specified type) or null.
 * @see Entity.remove
 */
inline fun  Entity.remove(): Component? = remove(T::class.java)

/**
 * Adds a constructed [Component] to this [Entity]. If a [Component] of the same type exists, it will be replaced.
 * @param component will be added to this [Entity].
 */
operator fun Entity.plusAssign(component: Component) {
  add(component)
}

/**
 * Adds a [Component] to this [Entity]. If a [Component] of the same type already exists, it will be replaced.
 *
 * @param T type of component to add. Must have a no-argument constructor.
 * @return a [Component] instance of the chosen type.
 * @throws [CreateComponentException] if the engine was unable to create the component.
 * @see Entity.add
 */
@OptIn(ExperimentalContracts::class)
inline fun  Entity.addComponent(
  engine: Engine,
  configure: (@AshleyDsl T).() -> Unit = {},
): T {
  contract { callsInPlace(configure, InvocationKind.EXACTLY_ONCE) }
  val component = engine.create()
  component.configure()
  add(component)
  return component
}