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:

FormatThe 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()
end

An 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()
end

A 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:

CallReturns
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
end

After 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
end

A 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 in shutDown.
  • run checks 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.