Cooldown

⭐ Premium

The optional cooldown field paces how fast an objective’s progress adds up: at most maxAmount units of progress count within any sliding window of windowSeconds. When the field is absent, progress adds up freely.

Cooldown is available on every amount-based objective. It is not part of the base objective shape: a future objective type that isn’t amount-based would not carry it (see the technical note on the Objectives overview).

{
  "type": "Kill",
  "title": "Kill chickens, one every 5 minutes",
  "description": "Only one kill counts every 5 minutes. Patience.",
  "amountRequired": 5,
  "cooldown": { "maxAmount": 1, "windowSeconds": 300, "hardCap": false },
  "conditions": {},
  "entities": ["chicken"]
}

Fields

Field	Type	Description
maxAmount	number (≥ 1)	How many units of progress can count within one window. Same unit as amountRequired, not a number of actions: one gather swing that yields 30 wood spends 30 units.
windowSeconds	number (≥ 1)	Length of the sliding window, in seconds.
hardCap	boolean	How an action that exceeds the remaining budget is handled. Defaults to false (soft). See Soft vs hard cap.

Why pace an objective?

• Stop one-sitting farming. A contract meant to last a rotation can otherwise be cheesed in minutes at a good farming spot.
• Stretch engagement. A paced objective brings players back to the contract several times over the rotation instead of once.
• Soften snowballing. High-value contracts completed in the first hour of a rotation flood the economy early, and pacing spreads the payout curve.

When not to pace

• It can frustrate more than it stretches. A blocked objective means a player who wants to keep playing is told to stop. Some log off instead of coming back, especially on a short-session server.
• It punishes the players you want. Cooldown caps the fast, engaged players and does nothing to the casual ones who were never going to farm it in one sitting. The pace is set by your most active players but paid by everyone.
• It shrinks the completion window. Every pace pushes the minimum completion time up (see Keep it completable). Stack a tight cooldown on a short rotation and the objective becomes impossible for anyone who joins late.
• Over-pacing the whole set is worse than any single objective. If most contracts are paced, players run out of things to do between windows and the server feels empty. Pace a few signature contracts and leave the rest free.
• A condition may be the better tool. If the goal is “only counts in the right situation” rather than “only counts this often”, a condition fits better and carries none of the waiting.

Rule of thumb

If you can’t name the farming behaviour you’re stopping, don’t use a cooldown.

How the sliding window works

The window slides: it always covers the trailing windowSeconds from the current moment. There is no fixed reset tick.

• The budget is maxAmount minus the progress already counted inside the trailing window. An action only counts while some budget remains.
• When the budget reaches zero the player is blocked until the oldest counted progress ages out of the window, which releases its amount back into the budget.
• At maxAmount: 1 this reads as a classic cooldown: each counted increment locks the objective for the full window. At higher values it acts as a throughput cap (“up to 100 corn every 30 minutes”).
• The window is tracked per player, per objective. It survives server restarts and dies with the player’s progress: abandoning the contract or losing it to a rotation clears it.

Visualizing the window

Understand better visually? Check out this blog post on sliding windows

Soft vs hard cap

An action can be worth more than the remaining budget (a single harvest tick can yield more than one corn). hardCap decides what happens:

• Soft (false, the default): if any budget remains, the whole action counts in full. The window can overshoot maxAmount by up to one action’s worth. With 10 budget left, a harvest of 100 corn counts all 100.
• Hard (true): the action is clamped to the remaining budget and the excess is dropped. With 10 budget left, a harvest of 100 corn counts 10 and discards 90.

Soft feels fairer to players (no work is silently thrown away). Hard enforces the pace strictly. When in doubt, keep the default.

What players see

While a cooldown is limiting an objective, players get live feedback in both the contracts menu and the HUD:

• The menu shows a countdown to the next budget release, the amount that release returns, and the remaining window budget.
  • E.g: “🕐 10:02 (+42) • 49/100” means that the player has a 49 amount budget left out of a maximum of 100. In 10:02 minutes, the budget will increase by 42.
• The HUD stays compact: it shows the remaining budget while some remains, and a countdown to the next release while blocked. A blocked objective is highlighted and its progress bar dimmed.
• An objective with no active window shows no cooldown UI at all.

Windows shorter than the Hide Cooldown UI when window is below seconds config (default 10) never show cooldown UI, avoiding flicker on very short windows. The dimmed progress bar still communicates that the objective is blocked.

Keep it completable

A cooldown puts a floor on how long the objective takes. The fastest possible completion is a full maxAmount burst immediately, then another as each window expires:

minimum seconds = (ceil(amountRequired / maxAmount) - 1) * windowSeconds

Make sure that fits inside the rotation of every category the contract belongs to. For example, an objective asking to “harvest 300 corn, up to 100 every 30 minutes” has a minimum completion time of 60 minutes: two full harvests of 100, then a final harvest of 100 after the second window expires. Fine in a daily category, impossible in an hourly one.

minimum seconds = (ceil(300 / 100) - 1) * 1800 = (3 - 1) * 1800 = 2 * 1800 = 3600 seconds = 60 minutes

You don’t have to do the math

The web editor raises a non-blocking warning when a cooldown makes an objective uncompletable within a category’s rotation.

Examples

Two of the default contracts use a cooldown:

Free Range: kill 5 chickens, at most 1 every 5 minutes. A classic cooldown.

"cooldown": { "maxAmount": 1, "windowSeconds": 300, "hardCap": false }

Corn Rationing: harvest 300 corn, up to 100 every 30 minutes. A throughput cap with a soft limit, so a big harvest tick that crosses the 100 mark still counts in full.

"cooldown": { "maxAmount": 100, "windowSeconds": 1800, "hardCap": false }

Notes

• Cooldown is a premium feature. On the Lite edition, a contract whose objective carries a cooldown is locked: it never enters a rotation, and its definition is preserved untouched for when you upgrade.
• Cooldown is not a condition. Conditions filter when an action counts based on the state of the world at that instant, while cooldown limits how fast counted progress adds up over time.
• The inverse also exists: burst ignores actions that come too slow instead of too fast, and both can be combined on one objective.