Class Pvp

java.lang.Object
privbot.hooks.Pvp

public final class Pvp extends Object
ctx.pvp: a detached, per-tick copy of a PvP fight (the local player and the players around it: overhead, skull, HP bar, animation, graphic, worn item ids, tile and who they interact with), the same on every server.

The snapshot is plain immutable data. Feed it to the pure rules in privbot.mechanics (OverheadWatch, StylePolicy, OpponentLock, and effects()' tracker) instead of reading the client more than once a tick.

What a result proves. A present PvpSnapshot was read in one client-thread batch: the local player, its tile and the player list were read, so an empty PvpSnapshot.opponents() means "nobody the query keeps is in range on the local player's plane".

Fields. Overheads and skulls use their supported enum names. Unknown overheads are null, never "NONE"; skull IDs without a named enum use "ID_<n>". Worn item IDs exclude appearance kits such as bare arms and hair. Tiles use the player's current server position when readable, and otherwise the reported world location. An unknown tile makes the filtered snapshot unreadable. Combat level is the displayed level when the client supports reading it.

Unreadable. Not logged in, no local player or tile, an unreadable player list, a client-thread timeout, or an exception from one of those reads each give Observed.unreadable(String) ("ctx.pvp.snapshot: ..."). Smaller gaps never discard the snapshot: an overhead, skull, HP bar, animation, graphic, worn list, combat level or interaction that cannot be read is null in its PlayerView, and an unreadable spec energy is a null PvpSnapshot.localSpecPercent().

Thread. Call from the runner worker or a node; it marshals its own read through GameThread.ensure(Supplier). Do not wrap it in another client-thread read.

  • Method Details

    • snapshot

      public Observed<PvpSnapshot> snapshot(PvpQuery query)
      Reads the fight once.
      Parameters:
      query - what to include (radius, names, whether to list the local player); null is PvpQuery.all()
      Returns:
      the snapshot, or UNREADABLE with the reason (see the class comment); never null
    • fight

      public Observed<FightFrame> fight(PvpQuery players, ThreatQuery threats)
      Collects the local player, opponents, threats, containers and spec orb within one client-thread callback. A missing player snapshot or mismatched tick makes the result unreadable; an unavailable auxiliary read is null in the frame, never an empty container or an unarmed orb. Call from the runner worker.
    • fightObserver

      public Pvp.FightObserver fightObserver(PvpQuery players, ThreatQuery threats)
      A single-owner observer for one fight. The first readable hit and graphic samples establish baselines; their event lists are null. A session must be reset at Stop, death, disconnect or a new client session. Call observe and reset from the same runner worker. No client object escapes in the returned observation.
    • wildernessLevel

      public Observed<Integer> wildernessLevel(WildernessModel verifiedRules)
      Read the local server tile and apply caller-verified wilderness rules. A null model, unavailable player/tile, uncovered tile or conflicting zones returns UNREADABLE, never a guessed safe level. The model is not evidence that the server permits a teleport. Call from the runner worker; this method batches its own client read.
    • riskValue

      public Observed<Long> riskValue(FightFrame frame, Map<Integer,RiskValuation.ItemRule> itemRules, Boolean skulled, Boolean protectItem, int ordinarySlots, int skulledSlots, boolean prayerAddsSlot)
      Estimate loss from both containers in a detached fight frame using caller-verified item values, death rules, skull and prayer observations. Missing inputs return UNREADABLE; the result is an estimate, not a server guarantee. This pure calculation makes no client reads and must not be treated as a market-price quote.
    • escape

      public Job escape(Destination safe, Destination lower, WildernessModel verifiedRules, int teleportLimit)
      Create a cancellable escape job to a caller-verified safe destination. When the destination names a teleport, the exact lower waypoint must be in supplied coverage at or below the caller-verified teleport level; the job walks there first while above that limit. Unknown level pauses and cancels the active route, failing after five unreadable steps. DONE requires both arrival and a fresh level-zero read. This does not prove server teleport authorization or a hazard-free route. Step it from one runner worker; cancel may be called from Stop.
    • measuredDamage

      public Observed<DamageRow> measuredDamage(String weapon, boolean special)
      Historical Elorin PvP capture distribution for a weapon and attack kind. The bundled model was built from September 2026 captures; it is an estimate, not a promise about current server damage. Other or unknown servers, missing resources and unreadable server identity return UNREADABLE. A readable model without that weapon returns ABSENT. Call on the runner worker: the first call loads a bundled resource.
    • effects

      public SpellEffects effects()
      A new Freeze / Vengeance / Tele Block tracker using the historical Elorin cue set. An OSRS animation id goes through ctx.ids.animation(..); Elorin's captured raw cast is also recognised. Graphics are compared unchanged. Feed it from each tick's snapshot (PlayerView.graphic(), PlayerView.animation()).
      Returns:
      a new tracker, owned by the caller
      Throws:
      UnsupportedOperationException - when the server is unknown or lacks verified effect cues