Monthly reset explained

What actually happens at midnight on the 1st — period rollover, rewards, milestones, and offline players.

The period reset is the moment a leaderboard's "this month" turns over. It's the most opaque part of the plugin's lifecycle, and the part most likely to surprise you the first time it fires. This page walks through it step by step.

When does it fire?

Whatever the monthly.reset-time config value is — by default, 00:00 server-local time on the 1st of every month. The scheduler fires once per board, in board-key order, in a single tick.

If your server happens to be offline at the scheduled time, the plugin runs the reset on the next startup. It checks the last-fired timestamp in the database and catches up immediately. There is no "missed" reset.

What happens, in order

When the reset fires for a single board, the plugin:

Snapshots the current standings. The top N players (where N is the largest position used in your rewards and points-position blocks) are captured into a temporary in-memory list.
Awards points. Each top-N player gets the points configured in points.position-points (or the per-board override). Points are added to their cumulative points total — they're never reset.
Fires per-position rewards. For each top-N player, the plugin runs the configured commands and queues the message. Online players see the message immediately; offline players see it on next join.
Resets the period total. For DELTA and ACCUMULATE boards, the period counter is zeroed. For CURRENT boards, nothing changes — there's nothing to reset.
Persists the period number. The new month's period number is written to the database so the next refresh starts a fresh slate.
Refreshes the GUI. The next /leaderboard open shows the blank board with no rows yet — that's normal, fish or kill or vote once and you'll appear.

What does not happen

Milestones do not reset. Milestone state is permanent by design. See the milestones page for the rationale and the manual reset escape hatch.
All-time totals do not reset. If you use CURRENT boards (e.g. richest player), they keep ticking through the rollover — nothing about them is "monthly".
Player points do not reset. Points are cumulative across months by design — that's the whole point of the meta-leaderboard.

Offline players

A reset is fully offline-safe:

Rewards are queued in the database and fired on the player's next join. The commands actually run at reset time, so make sure they don't require the player to be online (use give, not tell, etc).
Reward messages are stored as a pending whisper and shown the moment the player connects.
Points are written immediately — the player's points balance is correct as soon as the reset fires, regardless of whether they were online.

If you want to test the reset before letting it fire for real, run /lbadmin reset force on a staging server. It runs the exact same code path as the scheduled reset, so anything that would happen at midnight on the 1st will happen there instead.

Common surprises

"My monthly board is showing the same player as last month." Either your board is type: CURRENT (all-time) when you wanted DELTA (period-based), or that player just happens to be #1 again. Check the value — if it matches their all-time value, it's the former.
"Rewards fired but the player says they got nothing." Check latest.log for the command output. The most common cause is a typo in commands (e.g. an item name that no longer exists in this MC version).
"The reset fired twice." It didn't — but if you migrated servers and the old one had a stale last-period row, the new install might catch up. Run /lbadmin status and confirm the current period number matches the calendar month.