Class Events
ctx.events.
Why polling: on Impact, Elorin and SpawnPK several RuneLite events are posted late, re-posted, or never posted
(a client never sees its own death through @Subscribe onAnimationChanged: poll for death, never
subscribe). This facade reads the client once per game tick and turns the difference from the previous tick into
events, so the same plugin code works on every server.
The plugin drives it. This facade registers no subscriptions and starts no thread. Forward the plugin's own GameTick, while the plugin is running:
@Subscribe
public void onGameTick(GameTick tick) {
if (!runState.enabled) return; // a stopped plugin reads nothing
ctx.events.onGameTick(); // reads one frame, dispatches the listeners below
taskTree.onGameTick();
}
// in startUp / Start:
deathSub = ctx.events.onLocalDeath(d -> runState.markDied(d.tick));
ctx.events.onProjectile(p -> threat.record(p.id, p.endCycle));
// in Stop / shutDown:
ctx.events.clear();
Servers whose client can only report hitsplats or chat through RuneLite events (Orion's RuneLite fork) need
those events forwarded too: @Subscribe onHitsplatApplied(e) { ctx.events.forward(e); } and the same for
ChatMessage. Forwarding is harmless everywhere: a hitsplat is taken from a forwarded event only on a
server where this facade cannot poll hitsplats, and chat lines are de-duplicated against the polled ones.
Threading. onGameTick() reads the frame through GameThread.ensure(java.util.function.Supplier<T>, T) (inline on the client
thread, marshalled otherwise) and then calls the listeners on the CALLING thread, outside the client-thread read.
Listeners must be short: record the fact for the task tree and return. Never sleep, wait or dispatch a blocking
action from a listener. Event objects carry values; an Actor reference on an event is valid only during
the dispatch (on Impact, Elorin and SpawnPK an actor is a new object on every read).
Baselines. The first tick after start or reset() records what is already there and reports
nothing: projectiles in flight, graphics already drawn, current animations and var values are not "new". Call
reset() on disconnect, world hop and Stop. An unreadable read never produces an event and never moves
a baseline: a var that cannot be read is not "changed to 0".
Death. onLocalDeath(java.util.function.Consumer<privbot.hooks.Events.DeathEvent>) fires once per death, when the local player's current hitpoints read 0 or
its animation is one of the death animations (setDeathAnimations(int...), default OSRS 836; server numbering
differs, e.g. Elorin player animations are OSRS + 19000, so add the server's id when it is known). It re-arms
when hitpoints read above 0 again (or, where hitpoints are unreadable, when the animation is readable and not a
death animation).
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic final classAn animation change on the local player or an NPC.static final classA chat line that arrived since the previous tick.static final classThe local player died.static final classEverything one poll observed.static final classA graphics object (spot animation in the scene) that appeared since the previous tick.static final classOne graphics object as read on a tick.static final classA hitsplat that landed since the previous tick.static final classWhat one poll should read; anything not needed is skipped so an idle facade costs nothing.static final classOne NPC's animation as read on a tick.static final classA projectile that appeared since the previous tick.static final classOne projectile as read on a tick.static interfaceReads oneEvents.Frame.static interfaceA registered listener;Events.Subscription.cancel()(or close) removes it.static final classA watched varp or varbit changed between two readable ticks. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final intOSRS player death animation. -
Constructor Summary
ConstructorsConstructorDescriptionEvents(Events.Source source) The facade over anyEvents.Source: tests, the API test kit, or a recorded session. -
Method Summary
Modifier and TypeMethodDescriptionvoidaccept(Events.Frame frame) Dispatches one already-read frame (tests, and sources driven by something other thanonGameTick()).voidclear()Removes every listener (call from Stop / shutDown) and forgets the baselines.voidFeeds a RuneLite event the plugin received through@Subscribe, for servers where polling cannot see it:HitsplatApplied(used only when this server's hitsplats are not polled) andChatMessage(de-duplicated against polled lines).For diagnostics: the listener counts by kind.onAnimation(Consumer<Events.AnimationEvent> listener) onChat(Consumer<Events.ChatEvent> listener) voidReads one frame and dispatches the listeners.onGraphic(Consumer<Events.GraphicEvent> listener) onHitsplat(Consumer<Events.HitsplatEvent> listener) onLocalDeath(Consumer<Events.DeathEvent> listener) The local player died, detected by polling (never by@Subscribe).onProjectile(Consumer<Events.ProjectileEvent> listener) onVarbit(int varbitId, Consumer<Events.VarChange> listener) Watches one varbit (the client's own id: seeVars.observedVarbit(int)).onVarp(int varpId, Consumer<Events.VarChange> listener) Watches one varp.voidreset()Forgets every baseline, so the next tick only records the current state (call on disconnect, world hop, and Stop).voidsetDeathAnimations(int... animationIds) Sets the animations that mean "the local player is dying", in this server's numbering.
-
Field Details
-
OSRS_DEATH_ANIMATION
public static final int OSRS_DEATH_ANIMATIONOSRS player death animation.- See Also:
-
-
Constructor Details
-
Events
The facade over anyEvents.Source: tests, the API test kit, or a recorded session.- Parameters:
source- reads one frame per tick
-
-
Method Details
-
onProjectile
- Parameters:
listener- called once per new projectile- Returns:
- the subscription
-
onHitsplat
- Parameters:
listener- called once per new hitsplat on any actor (the local player, NPCs, players)- Returns:
- the subscription
-
onAnimation
- Parameters:
listener- called when the local player's or an NPC's animation changes between two readable ticks- Returns:
- the subscription
-
onLocalDeath
The local player died, detected by polling (never by@Subscribe). See the class notes.- Parameters:
listener- called once per death- Returns:
- the subscription
-
onGraphic
- Parameters:
listener- called once per new graphics object- Returns:
- the subscription
-
onChat
- Parameters:
listener- called once per new chat line (polled, or forwarded where the client list is empty)- Returns:
- the subscription
-
onVarbit
Watches one varbit (the client's own id: seeVars.observedVarbit(int)).- Parameters:
varbitId- the varbit idlistener- called when its value changes between two readable ticks- Returns:
- the subscription
-
onVarp
Watches one varp.- Parameters:
varpId- the varp idlistener- called when its value changes between two readable ticks- Returns:
- the subscription
-
setDeathAnimations
public void setDeathAnimations(int... animationIds) Sets the animations that mean "the local player is dying", in this server's numbering. Replaces the default (OSRS_DEATH_ANIMATION). Hitpoints reading 0 counts as death regardless.- Parameters:
animationIds- the death animation ids
-
clear
public void clear()Removes every listener (call from Stop / shutDown) and forgets the baselines. -
reset
public void reset()Forgets every baseline, so the next tick only records the current state (call on disconnect, world hop, and Stop). Listeners stay registered. -
onGameTick
public void onGameTick()Reads one frame and dispatches the listeners. Call from the plugin's GameTick handler while it is running. Does nothing (reads nothing) when no listener is registered. -
accept
Dispatches one already-read frame (tests, and sources driven by something other thanonGameTick()).- Parameters:
frame- the frame
-
forward
Feeds a RuneLite event the plugin received through@Subscribe, for servers where polling cannot see it:HitsplatApplied(used only when this server's hitsplats are not polled) andChatMessage(de-duplicated against polled lines). Other event types are ignored. Never forward an animation event to detect death: death is polled.- Parameters:
event- the RuneLite event
-
listenerCounts
-