Skip to content

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.

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.

scripts/goblins/goblins.rift
import goblins.Damageable
import 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.

Components are the goblin’s state. Every NPC in this game is given hitpoints and the ability to be hit:

scripts/goblins/goblins.rift
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.

scripts/goblins/combat.rift
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
}

Poison is just another component. Put it in a library file and mark it public, and any script can use it.

scripts/goblins/poison.rift
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:

scripts/goblins/goblins.rift
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.

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.

scripts/goblins/systems.rift
import rift.ecs.*
import goblins.Damageable
import goblins.Dead
import goblins.Expires
import goblins.IncomingDamage
import 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.

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.

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.

scripts/goblins/systems.rift
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())
}
}

DeathSystem picks up anything marked Dead. The goblin’s body is set to expire a few ticks later.

scripts/goblins/systems.rift
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))
}
}

When the time is up, ExpirySystem swaps Expires for Despawn, and the engine removes the goblin from the realm.

scripts/goblins/systems.rift
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.

Rift runs a tick every 600 ms. You list your systems in the game loop, and they run in that order:

scripts/game-loop.rift
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.