Real Clock Seasons

Synchronizes the Minecraft Overworld clock with real wall-clock time — an independent NeoForge mod, not a fork of any other mod and requiring none to be installed to function.

This exists because long, open-ended Minecraft sessions — AFK farms, building, just playing for hours — tend to drift completely out of sync with real time, and no existing mod handled that well alongside season or time-of-day mods with real compatibility. If that's a problem you've run into too, ideas and suggestions toward better immersion and better compatibility with time/season mods are genuinely welcome — see CONTRIBUTING.md.

Official compatibility targets are Serene Seasons and Ecliptic Seasons (see COMPATIBILITY.md for current implementation status). A public extension contract (ClockCorrectionListener, registered via RegisterClockCorrectionListenersEvent) is also available for any other mod that wants to react to a clock correction.

What it does

• Corrects the Overworld's WorldClock to match real time, on a configurable interval (default: every real second).
• Preserves the elapsed in-game day count across corrections (a correction never resets "day N" back to day 0).
• Optionally freezes the vanilla "skip to morning" clock jump when players sleep, so sleeping never fights the real-time sync.
• Optionally forces an immediate sync when a player joins or when the server starts, instead of waiting for the next scheduled cycle.
• Notifies any registered ClockCorrectionListener after every correction — the extension point other mods use to react to a clock jump, with no built-in knowledge of which mod (if any) is listening.

How real time maps to Minecraft's clock

Vanilla's WorldClock does not treat tick 0 as midnight — it treats it as dawn. This addon's converter follows that convention:

Real time	Minecraft tick	Why
06:00 (dawn)	0	Vanilla's own anchor for the start of the day-tick cycle.
12:00 (noon)	dayLength / 4	A quarter of the cycle from dawn.
18:00 (dusk)	dayLength / 2	Half the cycle from dawn.
00:00 (midnight)	dayLength * 3 / 4	Three-quarters of the cycle from dawn.

An earlier version of this addon used a naive linear mapping (00:00 real → tick 0) that produced a constant, exactly-reproducible 6-hour display offset (e.g. 14:39 real time rendering as 20:39 in Minecraft) — fixed; see CHANGELOG.md. The current mapping is covered by dedicated tests in RealClockConverterTest, including the exact case that was reported.

Requirements

• NeoForge 26.1.2.71 on Minecraft 26.1.2
• Java 25

Installation

Drop the jar in your mods/ folder. No other mod is required. First launch generates config/realclockseasons-common.toml with Enabled = false by default — flip it to true to activate.

Official releases

Source is tagged at v1.0.0, but no compiled release has been published yet (see ROADMAP.md) — right now, building from source (see CONTRIBUTING.md) is the only way to run this mod. Once a compiled release exists, official builds will be published by the maintainer only — see CHANGELOG.md for what's shipped. A jar you or anyone else compiled from source (including a modified fork) is not an official release and isn't supported as one.

Configuration

All options live in config/realclockseasons-common.toml:

Option	Default	Meaning
Enabled	false	Master switch. Everything else in this table only matters if this is true.
SyncIntervalTicks	20	How often (in game ticks) the clock is corrected.
UseSystemTimeZone	true	Use the server's own system time zone.
CustomTimeZone	America/Bogota	Used only when UseSystemTimeZone is false. Any java.time.ZoneId.
EnableSleepFreeze	true	Suppress the vanilla sleep-triggered clock jump in the Overworld.
DebugLogging	false	Verbose [RealClockSeasons][DEBUG] log lines.
SyncOnJoin	true	Force an immediate sync when a player logs in.
SyncOnServerStart	true	Force an immediate sync as soon as the Overworld is bound at startup.
FutureProofMode	false	Treat unexpected WorldClock-binding failures as non-fatal (logs and stays inactive) instead of crashing the server.

Full rationale for each option is in the comments generated in the TOML file itself (see config/RealClockSeasonsConfig.java).

Commands

Command	Permission	Effect
/realclockseasons status	anyone	Shows real time, Minecraft ticks, sync state, and how many ClockCorrectionListeners are registered.
/realclockseasons sync	gamemaster	Forces an immediate correction, bypassing the scheduled interval.
/realclockseasons reload	gamemaster	Re-reads the config file and rebuilds the clock pipeline without a server restart.
/realclockseasons debug	gamemaster	Toggles verbose logging for the current run (session-only; edit DebugLogging in the config to persist).

Project documentation

• ARCHITECTURE.md — package layout and the dependency direction rules that keep this addon decoupled.
• COMPATIBILITY.md — official Serene Seasons and Ecliptic Seasons support, plus the generic extension contract for any other mod.
• ROADMAP.md — what's planned, in order.
• CHANGELOG.md — version history.
• CONTRIBUTING.md — how to build, test, and submit changes.

License

BSD-3-Clause — see LICENSE.