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

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

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

⚠️ 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).

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.