Events

Events are the things that happen in the game on their own: someone died, an item dropped, a party invitation arrived, the server rejected an action. You don't have to poll the world in a loop for them — there is a stream.

Reading events

Imperatively — waitEvent

The most common approach: wait for a specific event after a command.

suspend inline fun <reified T : ScriptEvent> L2Bot.waitEvent(
    timeoutMs: Long,
    predicate: (T) -> Boolean = { true },
): T?

Waits for the first event of type T matching predicate, but no longer than timeoutMs milliseconds. Returns the event, or null if it never arrived.

bot.attack(mob)
val died = bot.waitEvent<ScriptEvent.Died>(15_000) { it.oid == mob.oid }
if (died != null) bot.log("mob killed") else bot.log("gave up waiting")

Reactively — bot.events

bot.events is a Flow<ScriptEvent>. Use it when you need to react to a stream of events continuously, alongside your main logic:

import kotlinx.coroutines.flow.filterIsInstance
import kotlinx.coroutines.flow.collect

override suspend fun run(bot: L2Bot) = coroutineScope {
    launch {
        bot.events.filterIsInstance<ScriptEvent.ChatMessageReceived>()
            .collect { if (it.message.contains("help")) bot.log("called by ${it.senderName}") }
    }

    while (true) { /* main logic */ delay(500) }
}

Handling events in parallel needs its own coroutine: bot.events never completes, so a collect in the main body would block the script forever.

What to know about the stream

• The stream is live. Events that happened before the script started listening are lost — there is no history.
• waitEvent subscribes at the moment of the call. If an event arrives very quickly there is a race between the command and waitEvent: the answer is already in while nobody is listening yet. For fast reactions subscribe up front — run a collect in a separate coroutine — or check the world state instead.
• The buffer is finite. If your collect handler is slow, the oldest events are dropped. Keep heavy work out of collect.

The ones you'll actually use

Died · SkillUsed · SkillLanded · TargetSelected · NpcAggroChanged · ItemDropped · InventoryUpdated · DialogReceived · ConfirmDialogReceived · PartyInviteReceived · ChatMessageReceived · SystemMessage · ActionFailed

The full list follows. All events are nested types of ScriptEvent, referenced as ScriptEvent.Died and so on. Events with no fields are singletons — only their type is checked.

Combat

Target

Own character

Movement

World

Inventory

Pet

Party

Dialogs and chat

System

Mail, auction, castles

Raw packets

The only events that are not about the game: they say what was on the wire, not what happened. They arrive only while capture is on — see Raw traffic in the command reference.

They do not travel through bot.events or waitEvent — they have their own stream, bot.packetsIn / bot.packetsOut, and that is where to read them. The split is not cosmetic: in combat there are dozens of packets a second, and on the shared stream they would crowd out the game events someone is waiting for. As a bonus that stream hands you a ready Packet with opcode, bytes and a direction instead of a bare hex string.

Supporting types

InventoryListType

The list type in the InventoryLoaded event: USER · PET · QUEST.

ConfirmDlgParam

A parameter in the CaptchaReceived event. A sealed type with three variants:

val texts = captcha.params.filterIsInstance<ConfirmDlgParam.Text>().map { it.value }

ApSkillEntry

An entry in the ApSkillListReceived event.

PrivateStoreEntry

One lot in the PrivateStoreListReceived event. In a buy store (storeType == StoreType.BUY) three of the fields read backwards — see the descriptions.