Class Recovery

java.lang.Object
privbot.hooks.Recovery

public final class Recovery extends Object
Recover after the local player dies: 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 and notifyDeath() 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 Details

    • isSupported

      @Deprecated public boolean isSupported()
      Deprecated.
      only for the legacy tick() route; afterDeath works on every server
      Only for the legacy tick() route; afterDeath(RecoveryPlan) works on every server.
      Returns:
      whether this server has the legacy shared death recovery (Impact only)
    • tick

      @Deprecated public boolean tick()
      Deprecated.
      Impact-only and unproved; use afterDeath(RecoveryPlan), which waits for the respawn, reclaims where the server can, restocks and returns, on every server
      One 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 public void notifyDeath()
      Deprecated.
      use afterDeath(RecoveryPlan), which re-arms the Impact reclaim itself
      Re-arms the recovery for a death the plugin observed (Impact: a same-items death is otherwise missed).
    • notifyOnDeath

      public Events.Subscription notifyOnDeath(Events events)
      Registers notifyDeath() 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

      public Observed<Boolean> isActive()
      Returns:
      whether a recovery is running; UNREADABLE where unsupported
    • reset

      public void reset()
      Interrupts a running recovery and clears its state (Stop, disconnect, shutDown).
    • watch

      public DeathWatch watch()
      A new death watch for one plugin; feed it ctx.player hitpoints, animation and tile once per tick. Pure polling (never the animation event). See DeathWatch.
      Returns:
      a fresh watch with the default death animation (836)
    • held

      public Observed<Boolean> 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

      public Observed<String> holdReason()
      Returns:
      why actions are held; ABSENT when they are not held; UNREADABLE when the guard cannot be read
    • afterDeath

      public Job afterDeath(RecoveryPlan plan)
      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:
      1. 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;
      2. 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";
      3. Restock: the plan's ctx.restock.to job, 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 a back that travels to a bank and restock there yourself;
      4. Back: the plan's ctx.travel.go job, 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