event handlers - GregHib/void GitHub Wiki

Event handlers are blocks of code which fire when events happening in the game world are emitted by the game engine, every handler is registered inside of a script.

This page focuses on using handlers, for the full API see the parents of Script.kt.

Basic Handler

A basic playerSpawn which runs when a player logs in:

class HelloWorld : Script {
    init {
        playerSpawn {
            message("Welcome to Void.")
        }
    }
}

For longer handlers, you can extract the logic:

class HelloWorld : Script {
    init {
        playerSpawn(::spawn)
    }

    fun spawn(player: Player) {
        player.message("Welcome to Void.")
    }
}

All examples you can assume are inside a scripts init {} block.

Handler parameters

Some handlers take arguments, usually IDs:

npcSpawn("sheep") {
    say("Baa!")
}

IDs can use wildcards:

npcSpawn("cow_*") {
    softTimers.start("eat_grass")
}

See Wildcards for details.

Handler Scope

Handlers run in the context of the entity that triggered them:

npcSpawn("sheep") {
    say("Baa!") // npc.say("Baa!")
}

playerSpawn {
    say("Baa!") // player.say("Baa!")
}

Interface and inventory handlers also use player scope:

interfaceOption("Yes", "quest_intro:startyes_layer") {
    // this == player
}

Interactions

Interactions fire when a Character performs an action on an Entity. They fall into two categories operate (adjacent) and approach (from a distance).

Player -> Target

npcOperate("Talk-to", "doric") { }

objectOperate("Steal-cowbell", "dairy_cow") { }

Item/Interface -> Target

itemOnNPCOperate("wool", "fred_the_farmer_lumbridge") { }

NPC -> Target

npcOperateFloorItem("Take") {
}

Interfaces

Interface IDs follow: interface:component.

interfaceOpened("bank") { }

interfaceClosed("price_checker") { }

interfaceOption("Show rewards", "quest_intro:hidden_button_txt") { }

Inventories

itemAdded("logs", "inventory") { }

itemRemoved("cowhide", "inventory") { }

Timers

Timers have a start, stop and tick event.

timerStart("poison") {
   30 // Game Ticks until next call
}

timerTick("poison") {
    Timer.CONTINUE
}

timerStop("poison") { }

The best way to learn is by exploring existing scripts to see how handlers are used in practise.