The Rift ECS
Rift games are built from entities, components and systems. This page follows one goblin from the moment it appears to the moment it is gone. For the idea behind it all, start with ECS Fundamentals.
A goblin appears
Section titled “A goblin appears”The goblin starts as an entity: a thing in the realm, with no state of its own. This one appears when a player opens a door.
import goblins.Damageableimport goblins.Poisoned
val GOBLIN = Assets.Npc.goblin.id
on_object_option(Assets.WorldObject.poordoor, "Open") { subject -> val goblin = Npc.create(GOBLIN, Tile3(3244, 3245, 0)) World.registerNpc(goblin)}Players, NPCs, trees and items on the ground are all entities. What makes each one different is the components it carries.
It gets its parts
Section titled “It gets its parts”Components are the goblin’s state. Every NPC in this game is given hitpoints and the ability to be hit:
on_create<Npc> { npc -> npc.addComponent(Hitpoints(max = 10), Damageable())}Hitpoints comes with the engine. Damageable, IncomingDamage, Dead and Expires are components this game made itself, kept in a library file next to its systems.
import rift.ecs.Component
public class Damage(val amount: Int)
public class IncomingDamage(val damage: MutableList<Damage> = mutableListOf()) : Component()
public class Damageable : Component() { fun hit(amount: Int) { val incoming = entity.findComponent<IncomingDamage>() ?: entity.addComponent(IncomingDamage()) incoming.damage.add(Damage(amount)) }}
public class Dead : Component() { var handled: Boolean = false}
public class Expires(after: Int) : Component() { val dueOn: Int = World.cycle + after}A player poisons it
Section titled “A player poisons it”Poison is just another component. Put it in a library file and mark it public, and any script can use it.
import rift.ecs.Component
public class Poisoned(var damage: Int, val every: Int = 30) : Component() { var nextHitOn: Int = World.cycle + every}A player attacks the goblin with a poisoned dagger. This doesn’t need a system, which runs every tick. It needs a hook, which runs when something happens, like this click:
on_npc_option(GOBLIN, "Attack") { subject -> if (!target.hasComponent<Poisoned>()) target.addComponent(Poisoned(damage = 4))}subject is the player who clicked and target is the goblin. Now the goblin is poisoned.
The poison does its work
Section titled “The poison does its work”Systems hold the rules. This one runs every tick, for every entity that is both Poisoned and Damageable. The goblin never signed up for it. It’s included because of the components it has. Systems also go in a library file, marked public, because the game loop needs to name them.
import rift.ecs.*import goblins.Damageableimport goblins.Deadimport goblins.Expiresimport goblins.IncomingDamageimport goblins.Poisoned
public val PoisonSystem = system<ComponentsTwo<Poisoned, Damageable>> { name = "PoisonSystem" run { (poisoned, damageable) -> if (World.cycle < poisoned.nextHitOn) return@run damageable.hit(poisoned.damage) poisoned.nextHitOn = World.cycle + poisoned.every if (--poisoned.damage <= 0) poisoned.entity.removeComponent<Poisoned>() }}When the poison wears off, the system removes the component, and the goblin stops matching.
It asks for damage instead of dealing it
Section titled “It asks for damage instead of dealing it”PoisonSystem never touches the goblin’s hitpoints. Calling hit() just puts the hit in a queue. DamageSystem then applies every queued hit, whatever caused it, so poison, swords and falling rocks all follow the same rules.
The goblin takes damage
Section titled “The goblin takes damage”DamageSystem runs over everything with hitpoints and hits waiting. It takes each hit off the goblin’s hitpoints, and when they reach zero, it marks the goblin Dead.
public val DamageSystem = system<ComponentsThree<Damageable, Hitpoints, IncomingDamage>> { name = "DamageSystem" run { (_, hitpoints, incoming) -> for (damage in incoming.damage) hitpoints.current -= damage.amount incoming.damage.clear() val entity = hitpoints.entity if (hitpoints.isDepleted && !entity.hasComponent<Dead>()) entity.addComponent(Dead()) }}The goblin dies
Section titled “The goblin dies”DeathSystem picks up anything marked Dead. The goblin’s body is set to expire a few ticks later.
public const val NPC_CORPSE_TICKS = 5
public val DeathSystem = system<ComponentsOne<Dead>> { name = "DeathSystem" run { (dead) -> if (dead.handled) return@run dead.handled = true dead.entity.addComponent(Expires(after = NPC_CORPSE_TICKS)) }}Its body disappears
Section titled “Its body disappears”When the time is up, ExpirySystem swaps Expires for Despawn, and the engine removes the goblin from the realm.
public val ExpirySystem = system<ComponentsOne<Expires>> { name = "ExpirySystem" run { (expires) -> if (World.cycle < expires.dueOn) return@run val entity = expires.entity entity.removeComponent<Expires>() if (!entity.hasComponent<Despawn>()) entity.addComponent(Despawn()) }}No system calls another. Each one leaves a component behind, and the next system picks it up.
Every tick, in the order you choose
Section titled “Every tick, in the order you choose”Rift runs a tick every 600 ms. You list your systems in the game loop, and they run in that order:
import goblins.*
game_loop { main( PoisonSystem, // queues the hit DamageSystem, // applies it this tick DeathSystem, ExpirySystem, )}The order is part of your game’s design. Here poison runs before damage, so the poison’s hit lands in the same tick. Swap them, and it lands a tick later. Each system runs over every matching entity before the next one starts: all the poison, then all the damage, then all the deaths.
Most of your game’s rules go in main. The engine handles input, movement and sending updates to players itself, and gives you a few more places to run systems in between.