Lifecycle hooks
Lifecycle hooks let your code step in when something happens to a player or the realm, like a player logging out, a modal opening, or the realm shutting down. Inside the hook, this is what happened, and its type is the hook’s name without on_. subject is the body it happened to.
import players.InCombat
on_logout_requested { subject -> if (subject.hasComponent<InCombat>()) hold()}InCombat stands for your game’s own component, public in a library file such as scripts/players/components.rift. So do Duel, InCutscene, Busy and Parked below. For what players click and type, see Gameplay hooks.
Holding a logout
Section titled “Holding a logout”While a player is trying to leave, on_logout_requested runs every tick until they’re gone. reason tells you why they’re leaving. Call hold() to keep them in for one more tick. Holding only works for the first 16 ticks, then they leave anyway. To say no outright, call refuse(message). The player stays and sees your message.
import players.InCombat
on_logout_requested { subject -> if (!subject.hasComponent<InCombat>()) return@on_logout_requested when (reason) { DisconnectReason.REQUESTED, DisconnectReason.HOP -> refuse("You can't log out during combat.") else -> hold() }}You can only refuse two kinds of logout. REQUESTED is when the player clicks Logout or your game asks for it. HOP is when they move to another realm. If your hook throws, the error is reported, and the player isn’t held or refused.
Cleaning up as a player logs out
Section titled “Cleaning up as a player logs out”Once nothing is holding the player any more, on_logging_out runs one time. They haven’t been saved yet, so anything you change here ends up in their save.
import players.Duel
on_logging_out { subject -> subject.findComponent<Duel>()?.forfeit()}A logout runs in this order: on_logout_requested each tick, then the hold or refusal, then on_logging_out, then the save.
Keeping an idle player in
Section titled “Keeping an idle player in”When a player has been idle long enough to be logged out, on_idle_logout_due runs every tick. Call hold() to keep them in. Unlike a normal logout, there’s no limit on how long you can hold. The engine never holds an idle player on its own.
import players.InCutscene
on_idle_logout_due { subject -> if (subject.hasComponent<InCutscene>()) hold()}Reacting to modals
Section titled “Reacting to modals”on_modal_opened fires when a modal opens on the player’s interface, with the lock level it raises: None, ModalPause or Locked. on_all_modals_closed fires when they have all closed, however they closed.
import players.Busy
on_modal_opened { subject -> if (lock == LockLevel.Locked) subject.addComponent(Busy())}
on_all_modals_closed { subject -> subject.removeComponent<Busy>()}Handling the end of a sequence
Section titled “Handling the end of a sequence”When a sequence ends, or its director leaves the realm, the director lets go of everyone taking part. on_participant_released runs for each of them. subject is the participant, and director is the director that let go.
import players.InCutscene
on_participant_released { subject -> subject.removeComponent<InCutscene>() subject.message("You can move again.")}Saving when the realm stops
Section titled “Saving when the realm stops”A realm stops in one order, whether from a countdown on the panel, the panel’s “Stop now”, the command line or the host’s stop signal:
- New logins close.
- The tick stops.
- Each player sees the realm’s parting line and is disconnected.
on_realm_stopruns once.- Every character is saved.
- The save store closes.
on_realm_stop has no subject. The players are already disconnected, but every character is still in the realm until it is saved, so a component you change or a world record you write here is saved.
import players.Duel
on_realm_stop { World.players.forEach { player -> player.findComponent<Duel>()?.forfeit() } if (!restarting) Logger.info { "Stopped: ${message ?: "no message"}" }}restarting says whether the realm comes back on its own, and message is what the person who stopped it wrote, or null. A countdown set to “Restart” brings the realm back into its staged build if one is ready, and otherwise it stays down.
You can’t queue events from on_realm_stop, because no tick runs after it. If the hook throws, the error is reported and the realm still stops and saves.
A stop gets 10 minutes. If saving takes longer than that, the realm gives up and exits with a failure. You can change the limit with STOP_CEILING.
When you test with rift dev or Play in Forge, a countdown works differently. It sends everyone out and blocks logins until the realm restarts, and “Stop now” does nothing.
Sending your own events
Section titled “Sending your own events”An event is a class that extends DomainEvent. Queue one with subject.queueEvent(event), and on_event<T> hears it at the top of the next tick, for every event of class T or a class below it.
class ClanFounded(val clan: String) : DomainEvent() { override fun keys(subject: Entity) = listOf("[clan_founded]") override fun describe() = "ClanFounded($clan)"}
fun foundClan(founder: Entity, name: String) { founder.queueEvent(ClanFounded(name))}
on_event<ClanFounded> { subject -> subject.message("You founded $clan.")}Inside on_event<T>, this is the event, so its fields are in scope. An event that another file queues or hears is public, in a library file: see Sharing code between files.
public class ClanFounded(val clan: String) : DomainEvent() { override fun keys(subject: Entity) = listOf("[clan_founded]") override fun describe() = "ClanFounded($clan)"}
public fun foundClan(founder: Entity, name: String) { founder.queueEvent(ClanFounded(name))}import clans.ClanFounded
on_event<ClanFounded> { subject -> subject.message("You founded $clan.")}Binding hooks when writing a server plugin
Section titled “Binding hooks when writing a server plugin”A server plugin binds the same hooks by the same names in its load(), each imported from rift.packages.
import rift.ecs.Systemimport rift.packages.RiftPackageimport rift.packages.on_logging_outimport rift.packages.on_realm_stop
public object DuelsPackage : RiftPackage { override val systems: List<System<*, *>> = emptyList()
override fun load() { on_logging_out { subject -> subject.findComponent<Duel>()?.forfeit() } on_realm_stop { World.players.forEach { player -> player.findComponent<Duel>()?.forfeit() } } }}Duel is the plugin’s own public class, in package duels. Every hook on this page works in a server plugin.
Tracking which body a client drives
Section titled “Tracking which body a client drives”Three hooks follow which body a player’s client is controlling. on_client_body_created runs when a new login gets its body, before on_create and before its save loads. on_body_possessed runs when a client takes over a body that already exists. on_body_released runs when a client lets go of a body that stays in the realm.
import players.Parked
on_body_possessed { subject -> subject.message("You take control.")}
on_body_released { subject -> subject.addComponent(Parked())}Releasing a body doesn’t save it. A realm stop saves it with everyone else. Most games need only on_login and the logout hooks above.