TimeLib

Minecraft 版本： 1.21.5 1.21.6 1.21.7 1.21.8

平台： datapack

标签： library utility

⚠ ATTENTION ⚠

(Sep 27, 2025) I found few major problems with TimeLib that make it unreliable for certain usecases. Please read through these carefully and assess for yourself whether you want to use TimeLib. Once a way is found or added by Mojang to fix these issues, I will keep supporting TimeLib again. As of me writing this, TimeLib v2.3.1 is the latest release.\
\
TimeLib is NOT permanently discontinued, it will come back once all is sorted out!\
I will post updates to the situation here, as well as the MinecraftCommands Discord server (in #resources).

Fundamental (currently) unfixable Problems:

Because of these issues, for TimeLib to keep working as expected, the user would need to manually confirm / adjust the date every time the world reloads. That breaks the point of TimeLib, which is why I need time to think / wait until Mojang makes it possible to mitigate these issues.

• ⚠ If the player head profile (which includes a timestamp) is older than 24 hours (which can happen due to caching and cannot be detected), it's impossible to automatically detect the date accurately
• ⚠ Since 1.21.9, the unix timestamp can only be retrieved from online players, meaning TimeLib cannot update the date while nobody's online, potentially breaking packs that rely on it (Note: It only needs the player to synchronize the date initially. Until the time is desynced, it keeps working even when nobody's online)
• The PausedTicks score that contains the number of ticks that the game has been paused/frozen for only works if at least one player is online from start to finish. If everyone leaves (doesn't have to be at the same time) while the game is frozen, or nobody was online in the first place, the stored value in PausedTicks is not reliable
  • The same problem makes it so freezing the game for 24h+ makes the day not increment (because there's no way to tell how much time has passed if nobody's online)
• Because of daylight savings, the unix timestamp (which is expected to increase monotonously) could go backwards by 1h, potentially breaking packs that necessarily rely on the monotony. Being unable to detect timezones & daylight savings automatically, this cannot be counteracted without manual player input

  Other big known fixable bugs / oversights:

  I will fix these issues once I get to them. In the meantime, I put them here so you're aware of them. While these are not all known issues, these are the major ones.

• ⚠ An oversight makes it possible under rare circumstances for the date to be 1 day ahead of what it should be
• ⚠ An oversight prevents the date from incrementing after more than 1 day has passed since the server / client was running without reboots
• ⚠ While the time is incorrect (because it takes a bit to retrieve the necessary data), TimeLib does not indicate that the time is not synchronized yet, potentially breaking packs that try to grab data when it's not ready

  TimeLib

  A Minecraft Data Pack library that lets you get the real life date & time ingame. For inquiries, please contact @silicatYT on Discord.\
  \
  Download: Modrinth\
  Report bugs: GitHub

Features

• Provides the real life date & time with tick accuracy:
  • Year, Month, Day, Week Day, Hour, Minute, Second & the Unix Timestamp
• Provides the current tickrate
• Detects pausing the game & the pause duration (e.g. /tick freeze or singleplayer)
• Convert any Unix Timestamp into a date & time
• Supports different timezones & daylight savings time
• Supports lag, different tick rates & pausing
• High efficiency

How to use

TimeLib automatically keeps track of the date & time for you. For that to work, you first need to configure the settings to your personal taste. To access the settings, click the message that appears in chat after reloading, or manually run /function timelib:util/settings.

→ Settings

• Command Block Offset: This is required to offset the time difference between the UTC timezone and your system time. If daylight savings change, this setting needs to be adjusted to ensure that the date calculation works properly.
  • Example: UTC (7pm), System clock (8pm) → Use 1h
• Timezone Offset: Use this to change the displayed time.
  • Example: 8pm + 1h offset → 9pm

    → Get the real life date & time

    The values for Year, Month, Day, Week Day, Hour, Minute, Second & the Unix Timestamp are all stored inside the player #TimeLib, with each value having its own scoreboard objective:

• TimeLib.Year, TimeLib.Month, TimeLib.Day, TimeLib.WeekDay, TimeLib.Hour, TimeLib.Minute, TimeLib.Second & TimeLib.UnixTime

Additionally, string versions (with leading 0s) of the date and daytime are stored in the timelib:date and timelib:daytime storages.

→ Events

• #timelib:date_changed: Function tag that gets executed whenever the date changes
• #timelib:daytime_changed: Function tag that gets executed whenever the daytime changes
• #timelib:game_unpaused: Function tag that gets executed whenever the game unpauses
  • The #TimeLib TimeLib.PausedTicks scoreboard holds the number of ticks the game has been paused for

→ Get the tickrate

The tickrate updates once per second and can be read from the TimeLib.Tickrate scoreboard objective.

→ Convert any Unix Timestamp into a date & time

Note: The output date & time are in the UTC timezone, as daylight savings time cannot be properly accounted for.

• Set the #TimeLib.Input TimeLib.UnixTime score as the input.
• Run /function timelib:util/unix_timestamp_to_date.
• The output values will be stored inside the #TimeLib.Output TimeLib.? scores, as well as the timelib:output data storage.

How it works

• TimeLib combines the with Base64 encoded Unix Timestamp inside player heads with the daytime information inside command block outputs to calculate the current date & time.
• To get the tickrate, TimeLib counts the number of ticks between each daytime change.
• The pause detection uses the minecraft.custom:minecraft:total_world_time scoreboard objective, which increments every tick even while the game is paused.

Additional logic is used to ensure optimal results, good performance and accuracy.

Credit

From CMDred:

• SilicatYT: TimeLib
• BananaRedPanda: Base64 Decoder & Help

Good to know

• TimeLib requires an internet connection.
• Getting the tickrate does not utilize worldborder shenanigans.
• If your Data Pack uses a forceloaded chunk at 29999999 29999999 in the overworld, there may be collision.
• TimeLib (2.3.0 and newer) uses the lantern load library that lets you check for dependencies. If you follow its conventions:
  • #TimeLib load.status: 1 if TimeLib is installed, otherwise unset
  • #TimeLib.Version load.status: Release-specific number
• Upgrade to a newer release:
  • For TimeLib releases before 2.3.0: /function timelib:uninstall, then replace your current TimeLib version with the new one, then /reload to install the new version
  • For upgrading from release 2.3.0 or later to a newer release, simply replace the old datapack with the new one
• (v2.3.0+) TimeLib throws errors and stops working if multiple different releases are installed simultaneously. This extends to trying to call utility functions.
  • Similar behaviour occurs when trying to run utility functions after running /function timelib:uninstall

License

As per the MIT License, you are allowed to redistribute, modify and use TimeLib as long as we are credited for the original work.