Class Pvp
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.
-
Nested Class Summary
Nested Classes -
Method Summary
Modifier and TypeMethodDescriptioneffects()A new Freeze / Vengeance / Tele Block tracker using the historical Elorin cue set.escape(Destination safe, Destination lower, WildernessModel verifiedRules, int teleportLimit) Create a cancellable escape job to a caller-verified safe destination.fight(PvpQuery players, ThreatQuery threats) Collects the local player, opponents, threats, containers and spec orb within one client-thread callback.fightObserver(PvpQuery players, ThreatQuery threats) A single-owner observer for one fight.measuredDamage(String weapon, boolean special) Historical Elorin PvP capture distribution for a weapon and attack kind.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.Reads the fight once.wildernessLevel(WildernessModel verifiedRules) Read the local server tile and apply caller-verified wilderness rules.
-
Method Details
-
snapshot
Reads the fight once.- Parameters:
query- what to include (radius, names, whether to list the local player); null isPvpQuery.all()- Returns:
- the snapshot, or UNREADABLE with the reason (see the class comment); never null
-
fight
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
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
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
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
A new Freeze / Vengeance / Tele Block tracker using the historical Elorin cue set. An OSRS animation id goes throughctx.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
-