Humanizer

The Humanizer pauses your plugin on a schedule, at spots your plugin marks as safe.

What it does

Humanizer pauses your plugin from time to time, in two kinds:

PauseWhat happens
ShortA pause of a moment. During some, the Humanizer does one idle thing of its own, such as opening a tab.
AFKA pause with no input at all, which can last minutes.

Your plugin chooses how often each kind comes, and where one may start. The Humanizer chooses how long a pause lasts. Your plugin keeps no pause clocks and writes no idle behaviour of its own. Each plugin has its own windows and its own clocks.

Your plugin makes three calls: declare the windows once, sit out each tick a pause is running, and mark where a pause may start.

Declare the windows

Humanizer.register(shortMin, shortMax, afkMin, afkMax) declares the windows, in whole minutes between pauses: a short pause every shortMin to shortMax minutes, an AFK pause every afkMin to afkMax. A maximum of 0 turns that kind off. Calling it again replaces the windows and restarts both clocks.

Humanizer.unregister() forgets the windows and any running pause. Call it from shutDown.

function plugin:startUp()
    -- A short pause every 10 to 25 minutes, an AFK pause every 45 to 90.
    Humanizer.register(10, 25, 45, 90)
end

function plugin:shutDown()
    Humanizer.unregister()
end

Sit out a pause

Humanizer.paused() returns whether a pause is running. Check it first, before anything in the tick acts, and return if it is true. It returns false for a plugin that has not registered.

function plugin:onGameTick(_event: GameTick)
    -- First, before anything acts: skip the tick while a pause runs.
    if Humanizer.paused() then
        return
    end
    work()
end

Say where it is safe

A pause starts only where your plugin allows it. Humanizer.atSafeSpot() starts one when one is due, an AFK pause before a short one, and returns true while a pause is running, so the plugin sits out the tick. Call it wherever stopping would do no harm, such as just after banking, with nothing fighting the player, or between trips.

Humanizer.atShortSafeSpot() is the same, but starts only a short pause, for a spot where your plugin can spare a moment but not minutes.

-- Banked, and nothing is fighting the player: a pause of any length is fine here.
if justBanked and not player:isInteracting() then
    justBanked = false
    if Humanizer.atSafeSpot() then
        return
    end
end

-- Between kills: room for a moment, not for minutes.
if not player:isInteracting() and player:inventory():contains(FOOD) then
    if Humanizer.atShortSafeSpot() then
        return
    end
end

No pause starts during a break. A plugin that also takes breaks checks BreakManager.active() before the Humanizer: Break Manager shows the order.

Show the pause

For a status line or a panel:

CallReturns
Humanizer.pauseKind()"short" or "afk", or nil when no pause is running.
Humanizer.remainingTicks()Game ticks left in the running pause, or 0.
Humanizer.activity()What the running pause is doing, as text, such as "open inventory tab". nil for an AFK pause, a quiet short pause, or none.
Humanizer.cancel()Ends the running pause, if any, and restarts both clocks.
function plugin:sidePanel(panel: Panel)
    if Humanizer.paused() then
        local doing = Humanizer.activity()
        panel:label(`{Humanizer.pauseKind()} pause, {Humanizer.remainingTicks()} ticks left`)
        if doing then
            panel:label(doing)
        end
        if panel:button("Skip the pause") then
            Humanizer.cancel()
        end
    end
end

A whole plugin

This is src/main.luau in full: a plugin that fishes and drops what it catches, taking the pauses the Humanizer schedules.

--!strict

-- Fishes shrimp and drops it, taking the pauses the Humanizer schedules: it sits
-- out each one, and marks where one may start.

local plugin = Plugin.new({
    name = "Shrimper",
    description = "Fishes shrimp and drops it.",
})

local SPOT = "Fishing spot"
local SHRIMPS = 317 -- raw shrimps
local WAIT_TICKS = 8

local waitingFor: (() -> boolean)? = nil
local giveUpAt = 0

local function expect(check: () -> boolean)
    waitingFor = check
    giveUpAt = client:getTickCount() + WAIT_TICKS
end

local function run(): (RunStatus, string?)
    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

    local inventory = player:inventory()
    if inventory:isFull() then
        local before = inventory:itemAmount(SHRIMPS)
        inventory:interact(SHRIMPS, "Drop")
        expect(function() return player:inventory():itemAmount(SHRIMPS) < before end)
        return "running", "dropping"
    end

    -- An empty inventory, nothing fishing: a pause of any length is fine here.
    if inventory:emptySlots() == 28 and Humanizer.atSafeSpot() then
        return "idle", "starting a pause"
    end

    if player:isAnimating() then
        -- Mid-catch: a short pause may start, never a long one.
        if Humanizer.atShortSafeSpot() then
            return "idle", "starting a short pause"
        end
        return "running", "fishing"
    end
    local spot = scene:npcs():named(SPOT):nearest()
    if spot == nil then
        return "idle", "no fishing spot here"
    end
    if spot:interact("Net") then
        expect(function() return player:isAnimating() end)
    end
    return "running", "walking to the spot"
end

local enabled = false
local status: RunStatus = "idle"
local reason: string? = "paused"

function plugin:startUp()
    Humanizer.register(10, 25, 45, 90)
end

function plugin:shutDown()
    Humanizer.unregister()
    enabled = false
    waitingFor = nil
end

function plugin:onGameTick(_event: GameTick)
    if enabled then
        status, reason = run()
    end
end

function plugin:sidePanel(panel: Panel)
    panel:heading("Shrimper")
    panel:label(status .. ": " .. (reason or ""))
    if Humanizer.paused() then
        panel:label(`{Humanizer.remainingTicks()} ticks left in the pause`)
    end
    if panel:button(if enabled then "Pause" else "Start") then
        enabled = not enabled
    end
end

return plugin
  • It registers in startUp and unregisters in shutDown. Turning the plugin off forgets any running pause.
  • paused() comes first in run, before the wait for the last action and before anything that acts.
  • It names two kinds of safe spot. An empty inventory can take a pause of any length; the middle of a catch can spare a short one.