Gameplay hooks
Gameplay hooks run your code when a player does something, like clicking a button, picking an option on an NPC, or typing a number or a ::command. The engine doesn’t decide what any of it means. Clicking the ground won’t move anyone, and a chat message won’t show up, until one of your hooks makes it happen.
on_public_chat { subject -> subject.speak(text = text, colour = colour, effect = effect)}Writing a hook
Section titled “Writing a hook”Inside the hook, this is what the player did, and its type is the hook’s name without on_. So on_public_chat gives you a PublicChat. subject is whatever the player is controlling. Usually that’s their character, but it can be an NPC they’re driving or any other entity.
import rift.ts2.UI
on_ui_component_click(UI.Logout.button) { subject -> val actor = subject as? Actor ?: return@on_ui_component_click if (!actor.hasComponent<Disconnecting>()) actor.addComponent(Disconnecting())}Hooks don’t check what subject is for you. If only a player’s character should react, check with subject as? Actor, as above. To hold or refuse the logout that follows, see Lifecycle hooks.
Handling options on NPCs, players and world objects
Section titled “Handling options on NPCs, players and world objects”Options are matched by their text, and case doesn’t matter. target is the thing the player clicked.
on_npc_option(Assets.Npc.hans, "Talk-to") { subject -> target.speak("Welcome to the realm.")}
on_object_option(Assets.WorldObject.poordoor, "Open") { subject -> subject.message("The door is locked.")}
on_player_option("Trade with") { subject -> target.message("Someone wants to trade with you.")}
on_world_item_option(Assets.Item.shark, "Take") { subject -> subject.message("It smells too much to pick up.")}The hook runs the moment the player clicks. If they should walk over first, that’s up to your game, for example with an action queue. These four hooks only work in scripts.
Handling interface clicks
Section titled “Handling interface clicks”on_ui_component_click can listen to one component, a whole interface, or every click on every interface if you give it nothing. Components get their names from your ts2 interfaces, as UI.<Interface>.<component>.
import rift.ts2.UI
on_ui_component_click(UI.Inventory.root) { subject -> if (option == 10 && item == Assets.Item.shark) subject.message("A tasty fish.")}
on_ui_component_click(UI.Friends) { subject -> if (UI.Friends.ignore.wasClicked(this)) subject.message("Showing your ignore list.")}The click tells you the ui, component, option, subOption, childIndex, slot and item. If the player clicks part of a component that your interface doesn’t name, like one slot of an inventory, you get the component with that slot. Clicks on components your realm doesn’t serve never reach you.
Handling drags
Section titled “Handling drags”on_ui_component_drag runs when a drag starts on the component. It tells you where the drag started and where it was dropped: from, fromSlot, fromItem, to, toSlot, toItem.
import rift.ts2.UIimport players.Backpack
on_ui_component_drag(UI.Inventory.root) { subject -> if (to != UI.Inventory.root) return@on_ui_component_drag val from = fromSlot ?: return@on_ui_component_drag val into = toSlot ?: return@on_ui_component_drag subject.findComponent<Backpack>()?.move(from, into)}Backpack here stands for your game’s own inventory component, public in a library file such as scripts/players/components.rift. So does Conversation below.
Continuing dialogue
Section titled “Continuing dialogue”on_ui_continue fires when a player clicks “Click here to continue” or picks one of a dialogue’s options, which arrives as slot. Like clicks, it takes a component, an interface, or nothing.
import players.Conversation
on_ui_continue { subject -> subject.findComponent<Conversation>()?.answer(slot)}Reading what a player types
Section titled “Reading what a player types”Each kind of input box has its own hook. The hook doesn’t know what you asked, so your game has to remember, for example with a component you add when you open the box.
class Pet(var name: String = "") : Component()
on_ui_text_submit { subject -> subject.findComponent<Pet>()?.name = text }
on_ui_name_submit { subject -> subject.message("You looked up $name.") }
on_ui_number_submit { subject -> subject.message("You chose $number.") }
on_ui_item_submit { subject -> if (item == Assets.Item.shark) subject.message("You searched for a shark.")}number is always a Long, whichever number box the player used. on_ui_item_submit only runs for items that are in your game’s data.
Handling clicks on the world and the minimap
Section titled “Handling clicks on the world and the minimap”on_world_click fires on the ground’s “Walk here”, and on_minimap_click on a click on the minimap. Both carry the tile and controlHeld.
on_world_click { subject -> if (controlHeld) subject.teleport(tile)}
on_minimap_click { subject -> subject.message("You clicked ${tile.x}, ${tile.z}.")}The tile is on the same level as subject. Nothing moves unless your game moves it, or you can add a movement plugin that handles these clicks for you.
Listening to public chat
Section titled “Listening to public chat”on_public_chat carries text, colour, effect, colourPattern and isAutotyped. Moderation runs first, so you never hear from a muted player.
on_public_chat { subject -> if (text.startsWith("!roll")) subject.message("You rolled ${(1..100).random()}.") else subject.speak(text = text, colour = colour, effect = effect)}A chat message only appears over a player’s head if one of your hooks says it with speak.
Adding ::commands
Section titled “Adding ::commands”Each command is a class. Its arguments and options are fields, and run() does the work. Register it with on_command, giving the name players type after ::. The class and its on_command go in the same script:
on_command("teleport", ::Teleport, groups = listOf("admin"))
class Teleport(subject: Entity) : DeveloperCommandDefinition(subject) { override val commandHelp = "Teleport to a tile" override val examples = listOf("teleport 3222 3218", "teleport 3222 3218 --level 1") private val x by argument(help = "x").int() private val z by argument(help = "z").int() private val level by option("--level", help = "height level").int().default(0) private val quiet by option("--quiet").flag()
override fun run() { subject.teleport(Tile3(x, z, level)) if (!quiet) subject.message("Teleported to $x, $z.") }}examples show up when a player types ::teleport --help. Arguments and options can also be .long(), .double() or .multiple(). An argument can be .optional(), and an option can be .required(). To stop and tell the player something, throw UsageError("…") to show your message with the usage line, or PrintMessage("…") to show just the message. Both come from rift.cmd.cli:
import rift.cmd.cli.UsageError
on_command("roll", ::Roll, groups = Everyone)
class Roll(subject: Entity) : DeveloperCommandDefinition(subject) { override val commandHelp = "Roll a die" private val sides by argument(help = "sides").int()
override fun run() { if (sides < 2) throw UsageError("A die needs at least 2 sides.") subject.message("You rolled ${(1..sides).random()}.") }}Commands are private unless you say otherwise. Without groups, only the realm’s owner can use them. Use Everyone to let every player use one. Anyone who isn’t allowed gets no reply at all, so they can’t tell the command exists.
Binding hooks when writing a server plugin
Section titled “Binding hooks when writing a server plugin”A server plugin uses the same hooks, set up in its load() and imported from rift.packages. Its package object is public, like anything shared between files. When the plugin unloads, its hooks go with it.
import rift.ecs.Systemimport rift.packages.RiftPackageimport rift.packages.on_public_chat
public object DicePackage : RiftPackage { override val systems: List<System<*, *>> = emptyList()
override fun load() { on_public_chat { subject -> if (text == "!roll") subject.message("You rolled ${(1..100).random()}.") } }}Every hook on this page works in a plugin except the four option hooks. So does on_login.
Going lower with on_input
Section titled “Going lower with on_input”on_input<T> gives you the raw message the client sent, already decoded, with the same subject. Use a named hook when there is one. on_input is for anything else, like a plugin’s own messages.
on_input<DeveloperCommandInput> { subject -> // your own parser, for ::names no on_command registered}Which hook fires first
Section titled “Which hook fires first”Input hooks run once per tick, before your systems. So anything a click changes is already there when your systems run that tick. See the game loop.
- For one interface click: the component’s hook, then the interface’s, then the hook for every interface, then
on_input, thenon_inventory_option. - Hooks of the same kind run in the order you set them up. If one throws, it’s reported and the others still run.
- A registered
::commandis handled beforeon_inputever sees it.