Class Recovery
ctx.recovery.
The cross-server way: poll watch() each tick; when it says DEAD hand the plugin's plan to
afterDeath(RecoveryPlan) and step the job it returns. It waits for the respawn, reclaims items where the
server has an item reclaim (Impact), restocks and travels back, proving each stage.
The older route, deprecated in its favour:
- Impact: the shared "Unclaimed items at Death" reclaim (one service, run for you): it watches for the reminder, walks to Death, reclaims and confirms the items arrived, on its own worker;
- every other server: no legacy recovery;
isSupported()(deprecated) is false,tick()always answers false andnotifyDeath()does nothing.
Use of the older route: call tick() FIRST in the plugin's per-tick decision and yield while it answers
true. Tell it about deaths from the POLLED death event, never from @Subscribe onAnimationChanged (a client
does not see its own death through that on Impact):
ctx.recovery.notifyOnDeath(ctx.events); // once, at Start
if (ctx.recovery.tick()) return; // every tick, first
-
Method Summary
Modifier and TypeMethodDescriptionafterDeath(RecoveryPlan plan) Starts the job that gets the player back to work after dying.held()Whether bot actions are held because the client saw a forced move (a jail pull, a burst of teleports).isActive()booleanDeprecated.voidDeprecated.useafterDeath(RecoveryPlan), which re-arms the Impact reclaim itselfnotifyOnDeath(Events events) RegistersnotifyDeath()on the polled death event.voidreset()Interrupts a running recovery and clears its state (Stop, disconnect, shutDown).booleantick()Deprecated.Impact-only and unproved; useafterDeath(RecoveryPlan), which waits for the respawn, reclaims where the server can, restocks and returns, on every serverwatch()A new death watch for one plugin; feed itctx.playerhitpoints, animation and tile once per tick.
-
Method Details
-
isSupported
Deprecated.only for the legacytick()route;afterDeathworks on every serverOnly for the legacytick()route;afterDeath(RecoveryPlan)works on every server.- Returns:
- whether this server has the legacy shared death recovery (Impact only)
-
tick
Deprecated.Impact-only and unproved; useafterDeath(RecoveryPlan), which waits for the respawn, reclaims where the server can, restocks and returns, on every serverOne recovery check. Non-blocking.- Returns:
- true while a recovery is running (the plugin should do nothing else this tick); false when idle or unsupported (logged once)
-
notifyDeath
Deprecated.useafterDeath(RecoveryPlan), which re-arms the Impact reclaim itselfRe-arms the recovery for a death the plugin observed (Impact: a same-items death is otherwise missed). -
notifyOnDeath
RegistersnotifyDeath()on the polled death event.- Parameters:
events-ctx.events; the plugin must forward its GameTick to it- Returns:
- the subscription (cancel it at Stop, or let
events.clear()do it)
-
isActive
-
reset
public void reset()Interrupts a running recovery and clears its state (Stop, disconnect, shutDown). -
watch
A new death watch for one plugin; feed itctx.playerhitpoints, animation and tile once per tick. Pure polling (never the animation event). SeeDeathWatch.- Returns:
- a fresh watch with the default death animation (836)
-
held
Whether bot actions are held because the client saw a forced move (a jail pull, a burst of teleports). Actions are refused until the user resumes from the tray icon;afterDeath(privbot.mechanics.RecoveryPlan)stays RUNNING meanwhile.- Returns:
- the hold state; UNREADABLE when the guard cannot be read
-
holdReason
-
afterDeath
Starts the job that gets the player back to work after dying. Step it once per tick; each step is at most one bounded action and waits at most 2400 ms. Stages, in order:- Respawn: wait (bounded, 150 steps) until hitpoints are above 0 and the tile is readable. While
held()is true (in any stage) it stays RUNNING with reason "held: ..." and no stage budget runs out; - Reclaim: where the server has an item reclaim (Impact's "Unclaimed items at Death"), step it (200 steps); everywhere else the stage is skipped with the note "no item reclaim on this server";
- Restock: the plan's
ctx.restock.tojob, if planned (500 steps). Restock does not travel: it needs a bank within reach of the respawn point, otherwise it fails "restock: bank did not open". Respawning away from a bank, restock at home or plan abackthat travels to a bank and restock there yourself; - Back: the plan's
ctx.travel.gojob, if planned (300 steps).
What it proves: DONE ("respawned; ran: ...; skipped: ...") means every planned stage's own job ended DONE, so each carries that job's proof (items arrived, the tile is inside the destination). The reclaim stage is DONE when the server's reclaim ran and went idle; a reclaim that gave up ends the job FAILED "reclaim: item reclaim failed", and one whose "Unclaimed items" reminder never appeared (10 idle steps) is listed under skipped, not ran. A second death during the reclaim, restock or back stage stops that stage (the reclaim worker or the sub-job) and waits for the respawn again (reclaim re-armed); the next death ends it FAILED "died again during recovery". A failing sub-job ends this job FAILED with its reason prefixed by the stage ("restock: bank has none: Shark"); a sub-job past its budget is cancelled and ends it FAILED "<stage>: took too long".
Unreadable looks like: unreadable hitpoints or tile never count as respawned; the wait stays RUNNING ("hitpoints unreadable") and runs out its budget. A throwing read or sub-job step is caught; five in a row end the job FAILED "<stage>: unreadable". A finished job is inert. Every way the job ends (DONE, FAILED,
Job.cancel()) cancels a sub-job that is still running and, in the reclaim stage, stops the server's reclaim worker; cancel ends it FAILED "cancelled" and may come from another thread (Stop).Thread rule: step from one node on the script worker; reads marshal themselves and waits use
PrivTaskContext.sleepUntil(java.util.function.BooleanSupplier, int). The job is not thread-safe.- Parameters:
plan- what to do after respawning- Returns:
- a new job, RUNNING
- Respawn: wait (bounded, 150 steps) until hitpoints are above 0 and the tile is readable. While
-
tick()route;afterDeathworks on every server