Package privbot.mechanics
@PublicApi
package privbot.mechanics
Pure game-mechanic rules shared by plugins on every server: the same name and meaning on Impact, Elorin, Orion,
SpawnPK and Roat Pkz.
Rules for everything in this package:
- Pure. No client, adapter or thread calls, no clock, no I/O. A method answers from its arguments alone.
- Unreadable is not "no". Where an input may be unknown, a type here takes null (or an
Observed) and answers "unknown", never false, empty or 0. - Safe in a plugin's own unit tests. Nothing here needs a running client, so a plugin can test its use of these types with plain JUnit.
- Narrow dependencies. Only the JDK,
net.runelite.api.coords,net.runelite.api.Skill,privbot.api,privbot.taskandprivbot.hooks.container; enforced byMechanicsIsolationTest.
-
ClassDescriptionMaps the cues an NPC shows when it attacks (its animation id, its projectile id) to the
CombatStylethe attack demands, plus the animation ids that are known to be harmless and how many cycles pass between an animation and its projectile launching.Collects cues.Single-owner count of consecutive accepted attacks whose pending windows expired without an observed fire.Detects attack fires from caller-supplied, server-ID-space cues and separately confirmed spec-energy fires.Single-owner record of accepted attack sends and independently confirmed fires, eats and clearing exits.Pure attack timing calculations, adapted from ElorinPvP's AttackClock.A step-out interval, inclusive at both ends.Decides when to drink another dose of a stat boost (overload, super combat, and so on) from the boost the account actually shows.Detached boosted and real combat levels; null means an individual read was unavailable.The three combat styles and the overhead prayer that blocks each.What the engine is committed to: a STYLE, and on top of it at most one fixed-plan EPISODE (plan fix 6, D44).A fixed-plan episode, or none.Pure per-tick consume planning over detached inputs.Detached current inputs from one decision tick.Pure consume cooldown rules.Holds the combat style the most recently LAUNCHED attack demands.Detached historical damage distribution.Detects the local player's death and respawn by POLLING, oneDeathWatch.observe(java.lang.Integer, java.lang.Integer, net.runelite.api.coords.WorldPoint, int)call per game tick.What one observation says.A place to travel to: a name, a tile, how close counts as "there", and optionally a teleport to try first.Observes a potion-family dose total before and after an accepted drink.Bounded non-critical food timing.Historical Elorin PvP capture cues copied from the flagship's September 2026 tables.Pure emergency consume selection.Detached observations for one PvP decision.One fight frame plus newly observed local hits and graphics from the same client-thread batch.A bounded observation of one accepted food action, using a pre-send count and later detached inventory snapshots.Square-footprint maths for big NPCs, on server tiles.The clock of a freeze on an opponent: when it should end, whether a move of theirs ended it by running out or by breaking, and the immunity after it.How a move of theirs relates to a running freeze.Which item names are the same piece of gear.An immutable description of the gear a fight needs, the same on every server: what is worn, or what is carried.One wanted item.Whether a setup describes worn equipment or carried supplies.What a carried item is for.Pure decisions for the Elorin-observed instant granite maul behavior.A detached copy of one graphics object (a ground effect such as a falling rock or a pool) taken at the tick of aThreatSnapshot.The tiles that hurt right now: timed ones (a graphic or a telegraphed attack that lasts a few ticks) and persistent ones (ground the fight never lets you stand on).Detached recent health observations for the eat decision.Chooses an incoming combat style from detached, independently classified threat evidence.A null style means the inputs do not establish a style; keep the current protection.A detached instant-maul proposal over the selected opponent and one fight frame.A multi-tick piece of work a task node drives by callingJob.step(privbot.task.PrivTaskContext)once per pass until it is finished.Where aJobstands.Pure probability calculations adapted from ElorinPvP's KO-risk model; inputs are estimates, not guarantees.Combines caller-supplied risk estimates with a hit-time estimate.One independently justified possible attack.Pure KO-weapon switch timing adapted from the Dharok-mode policy.KEEP also covers an accepted equip that has not yet appeared in the worn read; it is not a new dispatch.Frame-bound gear proposals for the KO-weapon decision.Which ground items are worth picking up: by exact name, by id, or by stack value.Builds aLootSpec.Counts kills and loot per NPC name, so a plugin can report what a trip earned.Detached result of a bounded NPC attacker scan.One NPC reduced to what targeting and hazard maths need.Which offensive prayer to keep on, and when to give one up.Conservative observed-swing timing for one locked opponent.Conservative upper bound for an opponent's special energy, based only on independently confirmed spends and caller-supplied regeneration rules.The locked opponent.Detached opponent-lock selection.Facts about one observed player.Single-owner opponent lock history.Pure timing rules adapted from ElorinPvP's opponent clock; no client reads or claimed hit observations.An opponent's overhead prayer, debounced: "has their prayer blocked this style long enough to act on it".Combines a cue detector and confirmed-action history for our attack cycle.One player reduced to what a PvP fight needs.Protection-prayer planner for several simultaneous attackers.Planner settings.Stops a prayer toggle the state read never confirmed from being sent again and again.One unconfirmed toggle: the direction asked for and when it was sent.Notices a bot that has stopped making progress.Composes detached consumption decisions with the PvP action-family arbiter.The original consume decision is explanatory; dispatch only non-held entries fromPvpActionPlanner.Plan.actions().Pure action-family conflict resolution for a detached PvP plan.Current decision facts.Single-owner coordinator for detached PvP observations.Detached inputs derived from the same observation.Immutable results for one sampled tick.Chooses between same-frame instant-maul and KO-weapon episodes before combining with ordinary actions.Combines a KO-weapon gear episode with an ordinary same-frame PvP plan.Combines an ordinary PvP proposal and an instant-maul proposal from the exact same frame and arbiter facts.Detached proposal for the flagship PvP closing and step-out rules.What actx.pvp.snapshot(..)call should include.A detached copy of one tick of a PvP fight: the local player and the other players around it.Whatctx.recovery.afterDeathdoes once the player is back: an optional restock, then an optional trip back.Builds aRecoveryPlan.What a restock should end with, the same on every server: an optional worn setup, an optional carried setup, whether to empty the backpack of unwanted items first, and an optional server preset to try before withdrawing.Builds aRestockTarget.Pure valuation over caller-supplied prices and death rules.One physical entry.Value and death treatment for one item ID, from a caller-verified server-specific source.Finds the nearest tile to step to that is out of every hazard and clear of every big NPC's footprint.What aGearSetupstill lacks, compared with the player's real containers, the same on every server.Tells a new projectile launch from one already seen.One projectile in flight, reduced to what attack tracking needs.Whether a special attack fired between two readings of special-attack energy: a fire is an energy drop.Pure special-attack phase ordering.All flags are nullable: null is unreadable.Single-owner special-energy observation history; it never treats an unreadable sample as an energy value.Freeze, Vengeance and Tele Block on us and on opponents, tracked from the graphics and animations a PvP snapshot reads each tick.Deterministic style-set planning with the flagship's least-switching, range and commitment rules.One carried item matched to a missing equipment slot.Which combat style to fight in against an opponent's protection prayer.WhatSustainPolicysays to do about hitpoints, prayer or a boost this tick.The kinds of answer.What one call ofctx.sustain.maintaindid.The kinds of outcome.What to eat and drink, and when.Builds aSustainPlan.Chooses the one sustain action to take this tick (eat, brew, prayer restore, boost dose) from values the caller has already read.Proves a same-tick gear switch on later ticks, and backs off a switch that keeps failing.A verdict on the outstanding switch.What onectx.loadouts.switchTo(..)call sent.Spreads a first hit across every NPC in a group before finishing any, the tag-all-then-kill pattern.Chooses which NPC to fight and sticks to it, so a bot does not flip between two targets every tick.Which NPCs count as a target: by name, by id, minus an ignore list, optionally inside an area.Single-owner rolling threat memory.A verified magic tell and its lead in client cycles; callers perform server-ID matching before construction.What actx.threats.snapshot(..)call should include.A detached copy of one tick of a fight: the local player, the NPCs, projectiles and graphics around them, and the prayers that were checked.How many ticks a weapon takes between attacks.Weapon name to combat style, for Elorin's RS2-era item names.Explicit, caller-verified wilderness coordinate rules.Notices a world that has stopped changing while the tick counter keeps running: the signature of a death or a disconnect the client never reported (a real fight always moves something).