Intended usage¶
LeafSleep (OnePlayerSleep) is built around one core model: every world belongs to a shardGroupId that aggregates eligible, sleeping, and cancelling players across local regions (Folia) or networked backend servers, and commits dawn once per day epoch using a population-adaptive sleepCurve and cancelCurve.
Intended usage¶
- Install the jar on your server (
Paper,Spigot,Purpur,Folia,Fabric, orNeoForge, plusVelocityif usingsharding.transport: "plugin messaging") and boot once to generateconfig.yml,sleep.yml, andmessages.yml. - Choose your server design (see the complete Server & Network Design Guide):
- Single survival server (Paper / Folia / Fabric / NeoForge): Keep
sharding.enabled: false,sharding.transport: "local only", andstorage.type: "SQLITE". - 24/7 global server with variable population: Use
defaultQuorumPolicy: "curve"anddefaultCancelPolicy: "tug of war"inconfig.yml. Pick asleepCurve.type(logarithmic,smootherstep,power,sigmoid, orlinear) so 1–3 late-night players only need1sleeper (minRequired: 1) while peak hours smoothly scale up tomaxRequired: 8without requiring half the server to sleep. - Multi-world single server (Multiverse / creative + survival + resource): Configure each world under
worlds:insleep.yml. Setenabled: falseon lobbies, creative worlds, arenas, Nether, and End; assign distinctshardGroupIdvalues to worlds that should have independent day/night cycles. - Horizontally sharded survival cluster (2 to 100+ Paper/Folia backends): Give each backend a unique
serverShardId(shard-1,shard-2, ...) inconfig.yml, map their shared overworlds to the sameshardGroupId: "overworld-main"insleep.yml, and enablesharding.enabled: truewithsharding.transport: "redis pubsub"(recommended),"plugin messaging", or"direct socket". - Verify health with
/sleep test([OPS bit] Health=HEALTHY | Components=5 | Findings=0) and/sleep status.
How locations are prepared and verified¶
Unlike teleportation plugins that load chunks, LeafSleep never performs chunk I/O on the tick thread (S-005). Instead, ShardSleepCoordinator tracks player sleep eligibility in memory:
- Event-Driven Dirty Invalidations + 1 Hz Idle Reconciliation: Entering or leaving a bed (
BED_ENTER/BED_LEAVE), running/sleep sleep,/sleep cancel, or/sleep ignore, or joining/leaving the server immediately marks local counts dirty. When idle during daytime,ShardSleepCoordinatorreconciles world time and eligibility at a lightweight 1 Hz (20-tick) cadence rather than scanning player lists 20 times per second. - Population-Normalized
UnitCurveQuorum: For anyshardGroupId, normalized population load is $t = \frac{\text{eligible} - 1}{\max(\text{maxPlayers}, \text{eligible}) - 1} \in [0, 1]$.sleepCurveandcancelCurvemap $t$ onto[minRequired, maxRequired]with a small-population guard (max(1, eligibleCount / 2)whenminRequired: 1), so a nearly empty server never gets stuck at night. - Idempotent
targetDayEpochCAS & Phantom Reset: When active sleepers stay at or aboveeffectiveRequiredforwarmupDelayTicks(default60ticks =3s),ShardSleepCoordinatoratomically claimstargetDayEpoch = currentFullTime / 24000L + 1, advances world time totargetDawnTimeTicks(0), clears weather ifclearWeatherOnSkip: true, resetsTIME_SINCE_RESTon each eligible player's owning entity thread (resetPhantomStatistic: true), and dispatcheswakeupEffectsfromsleep.yml.
Teleport parameters are for testing¶
In LeafSleep, interactive chat buttons ([Sleep] -> /sleep sleep and [Cancel] -> /sleep cancel) and /sleep status are the everyday player workflow:
| Command | Purpose | Default Permission |
|---|---|---|
/sleep status (or /ops status) |
Shows per-world shardGroupId, active curve policy (curve:<type>), sleeping/required, cancelling/cancelRequired, eligible/maxPlayers, epoch, and live TPS / MSPT / leafsleepAvg telemetry |
leafsleep.status (true) |
/sleep sleep [messageId] |
Votes to skip the night (or selects a specific weighted message entry from sleep.yml) |
leafsleep.sleep (true) |
/sleep cancel |
Casts a counter-vote against an active sleep warmup (tug of war, curve, or veto) |
leafsleep.cancel (true) |
/sleep ignore |
Toggles personal opt-out from eligibleCount (persisted asynchronously in storage) |
leafsleep.ignore (true) |
/sleep reload |
Validates config.yml, sleep.yml, and messages.yml directives and hot-reloads |
leafsleep.reload (op) |
/sleep test |
Runs all 5 [OPS bit] PBIT, CBIT, and IBIT self-tests |
leafsleep.test (op) |
Where to go next¶
- Server & Network Design Guide - blueprints for every obvious and non-obvious server topology.
- Configuration Reference - every key in
config.yml,sleep.yml, andmessages.yml. - Commands & Permissions - subcommands, permissions, and
[OPS bit]diagnostics. - What NOT to do! - common misconfigurations that break night skipping or cause network desync.
- How it works - sharded state machine, curve math, and hybrid transport internals.