Class Events

java.lang.Object
privbot.hooks.Events

public final class Events extends Object
Typed game events for plugins, backed by POLLING: 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).

  • Field Details

    • OSRS_DEATH_ANIMATION

      public static final int OSRS_DEATH_ANIMATION
      OSRS player death animation.
      See Also:
  • Constructor Details

    • Events

      public Events(Events.Source source)
      The facade over any Events.Source: tests, the API test kit, or a recorded session.
      Parameters:
      source - reads one frame per tick
  • Method Details

    • onProjectile

      public Events.Subscription onProjectile(Consumer<Events.ProjectileEvent> listener)
      Parameters:
      listener - called once per new projectile
      Returns:
      the subscription
    • onHitsplat

      public Events.Subscription onHitsplat(Consumer<Events.HitsplatEvent> listener)
      Parameters:
      listener - called once per new hitsplat on any actor (the local player, NPCs, players)
      Returns:
      the subscription
    • onAnimation

      public Events.Subscription onAnimation(Consumer<Events.AnimationEvent> listener)
      Parameters:
      listener - called when the local player's or an NPC's animation changes between two readable ticks
      Returns:
      the subscription
    • onLocalDeath

      public Events.Subscription onLocalDeath(Consumer<Events.DeathEvent> listener)
      The local player died, detected by polling (never by @Subscribe). See the class notes.
      Parameters:
      listener - called once per death
      Returns:
      the subscription
    • onGraphic

      public Events.Subscription onGraphic(Consumer<Events.GraphicEvent> listener)
      Parameters:
      listener - called once per new graphics object
      Returns:
      the subscription
    • onChat

      public Events.Subscription onChat(Consumer<Events.ChatEvent> listener)
      Parameters:
      listener - called once per new chat line (polled, or forwarded where the client list is empty)
      Returns:
      the subscription
    • onVarbit

      public Events.Subscription onVarbit(int varbitId, Consumer<Events.VarChange> listener)
      Watches one varbit (the client's own id: see Vars.observedVarbit(int)).
      Parameters:
      varbitId - the varbit id
      listener - called when its value changes between two readable ticks
      Returns:
      the subscription
    • onVarp

      public Events.Subscription onVarp(int varpId, Consumer<Events.VarChange> listener)
      Watches one varp.
      Parameters:
      varpId - the varp id
      listener - 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

      public void accept(Events.Frame frame)
      Dispatches one already-read frame (tests, and sources driven by something other than onGameTick()).
      Parameters:
      frame - the frame
    • forward

      public void forward(Object event)
      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) and ChatMessage (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

      public Map<String,Integer> listenerCounts()
      For diagnostics: the listener counts by kind.