Better Moon Phases
Replaces Minecraft's default moon cycle (8 days, 8 single-day phases) with the real synodic month of 29.530589 days, adds astronomically correct moonrise and moonset times, and extends the day duration to 1 real-world hour (30 minutes of daylight and 30 minutes of night).
If you are looking for deep astronomical immersion and a more realistic passage of time, this datapack is for you. It works flawlessly on multiplayer servers as well: the lunar phase is determined by the server and synced to all clients, requiring no client-side resource pack.
Note: Generative AI was used to assist with the creation of this datapack.
Installation
- Drop
Realistic Moon Phase.zipinto<your world>/datapacks/. - Put
Realistic Moon Phase Resourcepack.zipinto.minecraft/resourcepacks/and enable it in Options > Resource Packs. On a server, either every player installs it or you set it as the server resource pack. - Join the world (or run
/reload), then/function realistic_moon:info.
On an existing world, the starting phase depends on how long the world clock has already been running. If you want to start from a specific phase, use /function realistic_moon:phase/[name].
Commands
| Command | Effect |
|---|---|
/function realistic_moon:info |
Shows current phase, cycle percentage, and time remaining until the next full moon |
/function realistic_moon:phase/full_moon* |
Sets the Moon to the chosen phase without changing the time of day |
/function realistic_moon:day_length/one_hour |
Sets 1 real-hour days (default) |
/function realistic_moon:day_length/normal |
Restores the vanilla 20-minute day length |
Note: You can replace full_moon with any of the 8 available phases: full_moon, waning_gibbous, third_quarter, waning_crescent, new_moon, waxing_crescent, first_quarter, waxing_gibbous.
Statistics
| Feature | Vanilla | Better Moon Phases |
|---|---|---|
| In-game Day | 20 real min | 60 real min |
| Lunar Cycle | 8 days (2h 40m in-game) | 29.53 days (~29.5 in-game hours) |
| Phase Duration | 1 day (20 min) | 3.69 days (~3.7 hours) |
⚠️ Combining high astronomical accuracy with 1-hour day lengths makes a full cycle take a significant amount of real-world time. To shorten it while preserving proportional accuracy, you only need to change one number: in data/minecraft/timeline/moon.json, update period_ticks (and scale the keyframe ticks by the same factor if you want phase windows to remain centered).
| period_ticks | Cycle Length | With 1-Hour Days |
|---|---|---|
| 708734 | 29.53 days | ~29.5 in-game hours (default setting) |
| 354367 | 14.77 days | ~14.8 in-game hours |
| 236245 | 9.84 days | ~9.8 in-game hours |
Alternatively, you can leave the period realistic and restore normal day speed. Running /function realistic_moon:day_length/normal brings the total cycle to ~9h 50m of play time.
Limitations
- The lit limb points at the Sun along the Moon's path, which is what you see in the sky, but the Moon's disc does not counter-rotate the way it does in real life at high latitudes. There are no eclipses either: the game only knows eight phase images.
- Night lighting changes are visual (
sky_light_factor). Mob spawning light levels are untouched, so a dark new-moon night is not more dangerous than a full-moon one. - With 1-hour days each in-game day is three times more real time: crop growth, furnaces and mob build-up per day all triple, because they run on game ticks rather than on the world clock.
- Overrides
data/minecraft/timeline/moon.json, so it conflicts with anything else that edits that timeline or theminecraft:visual/moon_angle,sky_light_factororstar_brightnessattributes.
Compatibility
- Requires Minecraft Java 26.2 (data pack format 107). Incompatible with 1.21.x and earlier due to missing timeline features.
- Overrides
data/minecraft/timeline/moon.json: this will conflict with other datapacks modifying the same timeline or theminecraft:visual/moon_angleattribute.
Roadmap (Future Updates)
We are actively working on expanding the celestial mechanics of Better Moon Phases. Here is our vision for the future:
- ✅ Dark Moonless Nights: Dynamic adjustments to nighttime brightness based on the lunar phase, making New Moons pitch-black and Full Moons bright.
- Expanded Version Support: Expanding compatibility to support other popular Minecraft versions.
- Rare Celestial Events: The introduction of Solar Eclipses blocking out the sun, and eerie Red Moons (Blood Moons) during the night.
- Complex Mechanics & Orbits: Implementing inclined planetary rotations (axial tilt) to simulate true astronomical seasons.
- Visible Planets: Adding accurately tracked, visible planets to the night sky that follow realistic trajectories.
- Calendar System: A functional in-game calendar that tracks celestial events, complete with real-world calendar correspondences.
- Full Mod Implementation: The ultimate goal is to evolve this project from a datapack into a complete standalone mod, which will allow us to break free from vanilla timeline limitations and fully realize all these features.
