Break Manager
The Break Manager takes the breaks from play that the player sets up, starting each one only where your plugin allows, and returns to play when it ends.
What it does
After a run of play, at a spot your plugin marks as safe, BreakManager takes a break and then returns to play. A break has one of four formats:
| Format | The break |
|---|---|
"logout" | Logs out, and logs back in on the same world. |
"afk" | Gives no input. The game logs the idle player out, and the return logs back in. |
"newWorld" | Logs out, and logs back in on another world. |
"hop" | Hops to another world without logging out, and carries on. It has no break length. |
The player turns breaks on for each plugin in the Break Manager plugin's side panel, and picks how long to play and to break, and the format. They can pick one format, or several for each break to draw from. No break starts for your plugin until they turn breaks on for it. One break runs at a time, across every plugin.
The player sets breaks once, in one place, for every plugin they run. Your plugin keeps no break clocks, and never logs out or back in itself. It makes three calls: register once, sit out each tick a break is running, and mark where a break may start.
Register
BreakManager.register(runMin, runMax, breakMin, breakMax, format) starts the plugin's play clock and suggests its defaults: runMin to runMax minutes of play between breaks, breakMin to breakMax minutes of break, and the format. The player's saved settings override all of them. Calling it again replaces the defaults and restarts the clock.
function plugin:startUp()
-- Suggested defaults: play 60 to 120 minutes, break 5 to 15, by logging out.
-- The player's own Break Manager settings win over all of these.
BreakManager.register(60, 120, 5, 15, "logout")
end
function plugin:shutDown()
BreakManager.unregister()
endAn argument left out takes the global default, and so does a window whose maximum is 0 or less. A format other than "logout", "afk", "newWorld" or "hop" raises.
-- Every default the player has not set comes from Bento's.
BreakManager.register()BreakManager.unregister() stops the plugin taking breaks until it registers again. Call it from shutDown. A break this plugin owns is abandoned where it stands: an account it logged out stays logged out.
Sit out a break
BreakManager.active() returns whether a break is running, whichever plugin's it is. Check it first in the tick, and return while it is true. It always returns false for a plugin that has not registered.
function plugin:onGameTick(_event: GameTick)
-- A break first, then a pause: no pause starts during a break.
if BreakManager.active() or Humanizer.paused() then
return
end
work()
endA plugin that also takes Humanizer pauses checks the break first. No pause starts during a break.
Say where it is safe
A break starts only where your plugin allows it. BreakManager.atSafeSpot() starts this plugin's break when one is due and the player has breaks on for it. It returns true while a break is running, this plugin's or another's, so the plugin sits out the tick. Call it wherever stopping would do no harm, such as just after banking.
With the Humanizer as well, offer the spot to the break first, then to a pause: BreakManager.atSafeSpot() or Humanizer.atSafeSpot(), as the whole plugin below does.
Show the break
For a status line or a panel:
| Call | Returns |
|---|---|
BreakManager.format() | The running break's format. It can change from one break to the next, so read it rather than assume the one you registered. nil when no break is running, or the plugin has not registered. |
BreakManager.remainingSeconds() | Seconds left in the running break, rounded up. nil when none is running. Once its time is up and the client is on its way back, this is nil while active() stays true. A "hop" break has no length, so this is nil all through it. |
BreakManager.untilBreakSeconds() | Seconds until this plugin's next break is due, rounded up. It reads 0 once one is due, and the break starts at the next safe spot. nil while breaks are off for the plugin, it has not registered, or a break is running. |
function plugin:sidePanel(panel: Panel)
if BreakManager.active() then
local left = BreakManager.remainingSeconds()
if left then
panel:label(`On a {BreakManager.format()} break, {left} s left`)
else
panel:label("Coming back from a break")
end
return
end
local untilBreak = BreakManager.untilBreakSeconds()
if untilBreak == 0 then
panel:label("A break is due at the next safe spot")
elseif untilBreak then
panel:label(`Next break in {math.ceil(untilBreak / 60)} min`)
else
panel:label("Breaks are off for this plugin")
end
endAfter a logout
Every format but "hop" logs the player out, and back in when the break ends, so your plugin sees the logout like any other. A "hop" break stays logged in, but the world change still takes the game out of LOGGED_IN and back. Reset in onGameStateChanged what either makes stale: an action you were waiting on, an NPC you held. A webwalk waits through the logout and carries on.
function plugin:onGameStateChanged(event: GameStateChanged)
if event:getGameState() ~= GameState.LOGGED_IN then
-- What the plugin knew about the scene is stale after a break's logout or hop.
waitingFor = nil
target = nil
end
endA whole plugin
This is src/main.luau in full: a plugin that chops trees and banks the logs, taking breaks and pauses.
--!strict
-- Chops trees and banks the logs, cooperating with the Break Manager and the
-- Humanizer: it sits out a break or a pause, and marks where each is safe.
local plugin = Plugin.new({
name = "Woodcutter",
description = "Chops trees, banks the logs.",
})
local TREE = "Tree"
local LOGS = ItemID.LOGS
local BANK_TILE = WorldPoint.new(3185, 3436, 0) -- a tile by your bank, in the loaded scene
local WAIT_TICKS = 8
local justBanked = false
local waitingFor: (() -> boolean)? = nil
local giveUpAt = 0
local function expect(check: () -> boolean)
waitingFor = check
giveUpAt = client:getTickCount() + WAIT_TICKS
end
local function bankLogs(): (RunStatus, string?)
if not bank:isOpen() then
if not bank:isNearBank() then
player:walkTo(BANK_TILE)
expect(function() return bank:isNearBank() end)
return "running", "walking to the bank"
end
if not bank:open() then
return "blocked", "no bank in range"
end
expect(function() return bank:isOpen() end)
return "running", "opening the bank"
end
if player:inventory():contains(LOGS) then
bank:deposit(LOGS, "all")
expect(function() return not player:inventory():contains(LOGS) end)
return "running", "depositing"
end
bank:close()
expect(function() return not bank:isOpen() end)
justBanked = true
return "running", "closing the bank"
end
local function chop(): (RunStatus, string?)
if player:isAnimating() then
return "running", "chopping"
end
local tree = scene:objects():named(TREE):nearest()
if tree == nil then
return "idle", "no tree here"
end
if tree:interact("Chop down") then
expect(function() return player:isAnimating() end)
end
return "running", "walking to a tree"
end
local function run(): (RunStatus, string?)
-- A break first, then a pause: no pause starts during a break.
if BreakManager.active() then
return "idle", "on a break"
end
if Humanizer.paused() then
return "idle", "pausing"
end
if waitingFor and not waitingFor() and client:getTickCount() < giveUpAt then
return "running", "waiting for the last action"
end
waitingFor = nil
-- Just banked, and the bank is shut: the safest spot this plugin has.
if justBanked and not bank:isOpen() then
justBanked = false
if BreakManager.atSafeSpot() or Humanizer.atSafeSpot() then
return "idle", "starting a break or a pause"
end
end
if player:inventory():isFull() or bank:isOpen() then
return bankLogs()
end
return chop()
end
local enabled = false
local status: RunStatus = "idle"
local reason: string? = "paused"
function plugin:startUp()
BreakManager.register(60, 120, 5, 15, "logout")
Humanizer.register(10, 25, 45, 90)
end
function plugin:shutDown()
BreakManager.unregister()
Humanizer.unregister()
enabled = false
waitingFor = nil
end
function plugin:onGameStateChanged(event: GameStateChanged)
if event:getGameState() ~= GameState.LOGGED_IN then
waitingFor = nil
justBanked = false
end
end
function plugin:onGameTick(_event: GameTick)
if enabled then
status, reason = run()
end
end
function plugin:sidePanel(panel: Panel)
panel:heading("Woodcutter")
panel:label(status .. ": " .. (reason or ""))
if panel:button(if enabled then "Pause" else "Start") then
enabled = not enabled
end
end
return plugin- It registers both in
startUp, and unregisters both inshutDown. runchecks the break, then the pause, before the wait for the last action and before anything that acts.- Just after banking is its safe spot. The break is offered it first, then a pause.
- A logout clears what it was waiting for, so it decides again from the scene it comes back to.