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:

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.

Solar eclipses. The mod uses the best available viewing point for each daylight solar eclipse. Every modded client gets the same view regardless of its position on Valheim's map. This viewing rule does not change the eclipse calendar, Moon phases, or lunar eclipses.

MoonlightGamma. The default is 1, so moonlight follows the model's estimated light output. At first and last quarter this is roughly 9% of full-moon light. Set it to 0.5 for a brighter look. The ambient floor still keeps moonless nights visible in Valheim.

SolarTotalityDuration. Valheim's accelerated day makes raw totality last only a few seconds. The default stretches the visual event to about 15 seconds. The rendered Moon, corona and landscape dimming stay aligned while the world clock and eclipse calendar continue normally. Set it to 0 for raw timing.

How it works

Valheim's sky cannot do any of this on its own, so the mod works around two hard limits:

• The vanilla Moon cannot be moved. The Custom/SkyboxProcedural shader always draws it opposite _SkyboxSunDir, which is why the vanilla Moon is permanently in the full-moon position. The mod hides it and draws its own, on camera-facing quads placed after the sky and before the clouds. On the vanilla path the skybox's own moon is reused, painted black, as the dark side, so the sky's glow and the aurora still fall in front of it.
• Valheim has no moonlight. At night it flips the Sun's directional light and keeps the same intensity. That light is also what makes the glint on the water. The mod scales and aims it after EnvMan.SetEnv, and moves the moonless part of it into the ambient light, which has no direction and therefore no glint.

StealthSystem reads that same light, so it is handed the untouched vanilla values: darker nights never make anyone sneakier. The change is purely visual.

The model uses the synodic, sidereal, draconic and anomalistic months, Kepler's equation with the real eccentricity, the 5.145° orbital tilt and shadow cones with the Danjon enlargement.

Limitations

• One shared view for the whole world: daylight solar eclipses are shown from their best viewing point. Player position on Valheim's map does not change eclipse visibility. The model has no full geographic sky.
• No seasons: the Sun's daily path doubles as the ecliptic.
• The game's Moon and Sun are about ten times larger than the real ones. Eclipses are solved at real sizes and only the display is scaled.
• With an accelerated in-game day, eclipse timing is compressed; raw solar totality lasts only seconds.
• Atmospheric refraction at the horizon (the flattened rising Moon) is not implemented.

Credits

The lunar maps were baked from public-domain colour and elevation surveys of the Moon published by NASA's Scientific Visualization Studio.