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 <day> [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 time backwards can delay fermenters, kilns and crops. If another mod already owns a command name, the mod leaves it alone and says so in the log.

The Delete key turns the mod off and on while playing, to compare with the vanilla sky. It only lasts for the session, and the key is set by ToggleKey.

Configuration

BepInEx/config/com.codex.valheim.moonphases.cfg, in five sections. The defaults are meant to be played with; the last section is for people who want to take it apart.

• 1 - General: on/off and the toggle key.
• 2 - Moon: MoonPath, MoonSurface, MoonSurfaceRelief, size and brightness.
• 3 - Eclipses: on/off, how long totality lasts on screen, lighting and corona.
• 4 - Moonlight: on/off, whether shadows follow the Moon, and how dark a moonless night gets.
• 5 - Advanced: month length, calendar start, orbital tilt, every piece of the model separately, and the appearance details.

Five settings deserve a word:

MoonPath. Astronomical places the Moon where the orbital model puts it, so it keeps its own hours: daylight appearances near the quarters, and some nights without it. It is a model, not an ephemeris — see the limitations below. Vanilla keeps the base game's behaviour, opposite the Sun and out every night, with only the phase and the eclipses changing. Both are consistent; it is a matter of taste.

MoonSurface. Realistic uses the two map files shipped with the mod, baked from real surveys of the Moon; Procedural is a surface the mod draws itself, with the seas in their right places. Both are sampled on the CPU, so neither costs VRAM. The CFG keys are MoonSurface, MoonSurfaceRelief and MoonSurfaceLongitudeOffset.