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.

!The moon and the sun in the same image

Note: Generative AI was used to assist with the creation of this datapack.

Installation

1. Drop Realistic Moon Phase.zip into <your world>/datapacks/.
2. Put Realistic Moon Phase Resourcepack.zip into .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.
3. 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 the minecraft:visual/moon_angle, sky_light_factor or star_brightness attributes.

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 the minecraft:visual/moon_angle attribute.

---

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.