Skip to main content

Guardians of the Rift

GuardiansRiftPlugin is a n3-native Guardians of the Rift automation plugin registered in runelite-plugin.properties (config group n3guardiansrift, disabled by default).

Architecture​

  • GuardiansRiftPlugin - RuneLite lifecycle, hotkey, overlay, input lock, and Break Handler active-only tracking.
  • GuardiansRiftController - pure per-tick decision controller.
  • GuardiansRiftRuntime - package-local runtime boundary used by tests.
  • RuneLiteGuardiansRiftRuntime - live adapter backed by InteractionApi.actions.* and sdk.query/sdk.widgets helpers.
  • GuardiansRiftAltar* and GuardiansRiftPouch* - package-local rules for altar selection, pouch capacity, degradation prevention, and repair routing.

Scope​

V1 ports the AutoRifts loop into n3 surfaces for:

  • barrier entry and game-busy waiting
  • pregame cells and guardian fragment mining
  • regular, large, and huge guardian remains mining
  • portal entry and altar exit
  • guardian essence crafting and rune crafting
  • altar selection with level, quest, talisman, ignore-toggle, point-balance, and blood/death priority rules
  • power guardian and cell placement
  • rune deposit or configured rune dropping
  • essence pouch capacity, degraded pouch detection, and direct repair routing by Cordelia, NPC Contact, or visible Dark Mage

Not included in v1: banking, full travel automation, guardian/chisel crafting, or Abyss travel to the Dark Mage.

Runtime Rules​

PacketUtilsPlugin.isAccountBootstrapReady() gates gameplay actions. The plugin registers with Break Handler on startup, starts active tracking only while the controller is running, releases input lock while break-paused, and stops tracking on idle, stop, disable, or shutdown.

The controller issues one result-aware action per tick. It does not own walker or suite pacing ticks; PacketUtilsPlugin.onGameTick remains the owner of ActionPacer.onTick(...) and Walker.tick().

State Priority​

  1. stopped, login, bootstrap, or break pause
  2. prerequisite failure such as missing pickaxe or pouch repair resources
  3. game-busy and barrier entry
  4. degraded pouch repair
  5. pregame cells, runes, and large-mine positioning
  6. first-portal fragment/large-mine handling
  7. endgame cleanup
  8. large/huge mine exit or mining
  9. altar craft or leave
  10. portal entry
  11. full-inventory power guardian, place cell, or enter altar
  12. cells, rune deposit/drop, fragment mining, and essence crafting

Testing​

.\gradlew.bat test --tests com.n3plugins.guardiansrift.* --console plain
.\gradlew.bat test --tests com.n3plugins.NativeManifestTest --tests com.n3plugins.breakhandler.AutomationBreakHandlerRegistrationTest --console plain

Covered by unit tests: controller priority, config defaults, pouch capacity and repair routing, altar gates, point balancing, ignore toggles, and blood/death priority.

Live validation pending​

Barrier entry, game-busy peek/check, first-portal timing, altar widget/varbit reads, Cordelia repair, NPC Contact repair, visible Dark Mage repair, cell placement target choice, reward threshold/endgame behavior, rune pouch deposit behavior, and full loop behavior in-client.

Logic Flow and Visualization​

1. Architectural Components​

The plugin is structured with clean separation between the RuneLite/game-tick lifecycle, state representation, decision controller, and game interaction adapter:

Component References​

2. Core Logic Flow​

On every game tick, GuardiansRiftPlugin fetches a snapshot from the runtime and runs determineState. The evaluated state corresponds to a precise action executed immediately.

3. Sub-Decision Flows​

A. Pregame Flow​

When the minigame is not active, the controller ensures inventory is clear and cells are stockpiled:

  • In Huge Mine: Goes to portal -> ENTER_PORTAL.
  • In Large Mine: Stands by -> WAITING_FOR_GAME.
  • In Altar: Crafts runes if essence present -> CRAFT_RUNES, else exits -> LEAVE_ALTAR.
  • Rune Present: Drop/Deposit -> DROP_RUNES / DEPOSIT_RUNES.
  • Cells < 10: Takes cells -> GET_CELLS.
  • Ready: Heads to starting position -> MOVE_TO_EAST_MINE.

B. First Portal Flow​

When starting a match, the controller mines a user-configured amount of starting fragments (startingFragments) before transitioning to the normal gameplay cycle:

  • In Altar: Exits -> LEAVE_ALTAR.
  • In Huge Mine: If full -> ENTER_PORTAL, else mines -> MINE_HUGE_GUARDIANS / MINING.
  • In Large Mine: Mines -> MINE_LARGE_GUARDIANS / MINING.
  • Cells < 10: Takes cells -> GET_CELLS.
  • Ready: Goes to start mining -> MOVE_TO_EAST_MINE.

C. Altar Room Flow​

When inside a runecrafting altar:

  • Essence Present: If player has guardian essence, pouch essence, or full pouches -> CRAFT_RUNES.
  • Empty: Leaves -> LEAVE_ALTAR.

E. Essence Crafting Flow​

When player's inventory is full:

  1. Power essence present: Delivers to Great Guardian -> POWER_GUARDIAN.
  2. Power cell present: Repairs/creates barriers -> USE_CELL.
  3. No cells/essence: Enters the prioritized altar -> ENTER_ALTAR.

F. Rune Deposit/Drop Flow​

If runes are present in the inventory:

  • Drop Runes Configured: Drops the runes -> DROP_RUNES.
  • Specific Filter Matched: Drops filtered runes -> DROP_RUNES.
  • Otherwise: Deposits into the pool -> DEPOSIT_RUNES.

4. Altar Selection Logic​

The altar selection class GuardiansRiftAltarSelector evaluates accessible altars based on:

  1. Access Gates: Level requirements, quest completions, and talismans.
  2. Ignore Filters: User configuration to ignore specific altars (unless all visible altars are ignored).
  3. Blood/Death Priority: If configured, prioritizes Blood or Death altars immediately.
  4. Point Balancing: Prioritizes Elemental vs. Catalytic based on current game points:
    • If catalyticPoints > elementalPoints -> Prefers Elemental altars.
    • If elementalPoints >= catalyticPoints -> Prefers Catalytic altars.
  5. Priority Order: Sorted by base priority (1 to 5) and possession of a talisman.

5. Pouch Repair and Capacity Rules​

Pouch actions are handled by GuardiansRiftPouchRules:

Capacity Calculator​

  • Colossal Pouch: Scales capacity based on Runecrafting level (8 slots at level 25 up to 40 slots at level 85).
  • Standard Pouches: Combined total (Small: 3, Medium: 6, Large: 9, Giant: 12) depending on player level limits.