MoonPhases

Moon Phases

An astronomical Moon for Valheim. Phases, position, apparent size, moonlight and eclipses all come from one orbital model tied to the world's time. Nothing is random: an eclipse happens when the geometry says so, and it falls on the same day in every world.

Client side only. The server does not need the mod, players without it keep the vanilla sky, and nothing is written to the save.

About this

I made this for my own world. Valheim's Moon never changes, and I wanted to look up at night and find a sky that was going somewhere. It grew from there, and I am putting it up in case someone else wants the same thing.

Treat it as an attempt rather than an authority. It is one person's model of the sky fitted into a game that was never built for one, so it has rough edges, it guesses in places, and some of it is a compromise between what is real and what reads well on screen. If something looks wrong to you, it may well be.

What you will see

• Phases from the real 29.53-day cycle, with the lit side facing the Sun and the craters staying put, as a tidally locked Moon does.
• A Moon that keeps its own hours. Near the quarters it shows up in daylight; on some nights it is missing. A full moon still rises at sunset and stays out all night.
• Moonlight that follows the phase: night brightness, shadows and the glint on the water track the Moon's phase, height and eclipses. Vanilla flips the Sun's light at night and keeps every night equally bright.
• Lunar eclipses: the planet's shadow crosses the disc, with a soft penumbra, a turquoise fringe from ozone at the umbra's edge and a copper Blood Moon at totality, which dims the whole landscape.
• Solar eclipses: the new Moon crosses the Sun, light and sky dim in step with the covered area, and the corona shows at totality. Total or annular is decided by the Moon's distance, as in reality.
• The lunar surface itself, baked from real colour and elevation surveys of the Moon, so the seas and craters sit where they belong and the relief catches the light near the terminator. A procedural surface is included as an alternative.
• Libration: over a month the Moon shows up to about 7 degrees past its mean edge, and the maria drift towards and away from the limb.

The eclipse calendar

Day 1 begins with a nearly full Moon; the first night is about 99.8% illuminated. The first visible total solar eclipse is on day 76:

| World day | Eclipse |

|---|---|

| 76 | Total solar, near noon (the real eclipse of 9 March 2016) |

| 252 | Annular solar, at night, not visible |

| 607 | Total solar (the real one of 21 August 2017) |

| 769 | Total lunar, at night: a supermoon as well, so a big copper one |

Eclipses come in seasons, roughly every 173 days, and the dates are the same in every world. EpochOffsetDays moves the starting date; existing worlds keep their current world day, so their future events shift when this setting changes. The real eclipse dates named above are comparisons, not exact civil dates for the in-game clock.

Try setday 1 21:00 to see the first full Moon, or setday 76 11:50 for the first total solar eclipse. The displayed hours use Valheim's rescaled day clock, and peaks are approximate to a minute.

Commands

moonphase show the current Moon and next eclipse

moonpath [astronomical|vanilla] show or change the Moon's path

moonsurface [realistic|procedural] show or change the Moon's surface

setday [dawn|noon|dusk|midnight|HH:MM]

moonphase reports the world day, but does not reveal the current clock time, including on dedicated servers. It still gives the scheduled hour of the next eclipse. moonphase only reports. moonpath and moonsurface apply immediately and save their choices in the CFG. Editing BepInEx/config/com.codex.valheim.moonphases.cfg also reloads the mod automatically after a brief pause; a restart is not needed for settings changes. setday changes the world clock, like the game's skiptime; it is saved with the world and only works in singleplayer or as the host. Moving