Eclipses

A moon with eclipses enabled produces solar and lunar eclipses from its own orbital settings. Eclipse dates are calculated deterministically, with no randomness involved.

Eclipse types

Solar eclipses

A solar eclipse happens when a moon passes between the world and the sun during a new moon phase. Alignment and apparent size decide the type.

Type	Description
Total Solar	The moon fully covers the sun
Annular Solar	The moon is centered on the sun but too small to fully cover it, leaving a bright ring
Partial Solar	The moon only partially covers the sun

Lunar eclipses

A lunar eclipse happens when the world’s shadow falls on a moon during a full moon phase. Depth in the shadow decides the type.

Type	Description
Total Lunar	The moon passes fully into the world’s shadow
Partial Lunar	The moon partially enters the shadow
Penumbral Lunar	The moon passes through the outer edge of the shadow

How eclipses work

Each eclipse-enabled moon runs a nodal cycle, the period on which its orbit crosses the sun’s plane. A cycle holds two alignment windows, one at the start and one at the midpoint, and eclipse opportunities come twice per cycle.

Rare, Occasional, and Frequent scale that cycle to the moon’s own cycle length. A slow-orbiting moon eclipses less often than a fast one on the same setting. Custom ignores cycle length and uses the nodal period you enter.

Alignment on its own is not enough. The moon must also be at the right phase: new for a solar eclipse, full for a lunar one.

Eclipses are evaluated one day at a time. A moon can sit inside both the alignment window and its new or full phase band for more than one day, so a single eclipse can register on several consecutive dates. The reported type moves away from total as the alignment drifts off center.

Eclipses and scene darkness

Eclipses change scene darkness while darkness sync and moon illumination are both enabled. A solar eclipse imposes a minimum darkness level scaled to the eclipse type. A lunar eclipse dims that moon’s contribution to nighttime brightness, and a total lunar eclipse leaves the moon contributing almost nothing. A moon in total lunar eclipse tints the scene’s night lighting blood-red.

See Scene Ambience.

Configuration

Eclipses are configured per moon on the Moons tab of the Calendar Editor.

Control	Description
Eclipse Frequency	Sets the alignment cycle: None, Rare, Occasional, Frequent, or Custom
Nodal Period	Alignment cycle length in days. Shown only while frequency is Custom
Apparent Size	How large the moon appears relative to the sun. Determines whether close solar eclipses are total or annular

Scheduling notes on eclipses

Notes can trigger on eclipses through the condition engine. When at least one moon has eclipses enabled, the condition preset dropdown includes an Eclipses group:

Any Eclipse. Matches any eclipse type
Any Solar Eclipse. Matches total, partial, and annular solar eclipses
Any Lunar Eclipse. Matches total, partial, and penumbral lunar eclipses
Two presets per eclipse-enabled moon, one solar and one lunar, each named after the moon. The name is the only part specific to that moon. The solar preset fires on a solar eclipse from any moon, and the lunar preset on a lunar eclipse from any moon.

To restrict a note to one moon, open the condition builder and add the Eclipse Type field. It pairs an eclipse type with a Moon selector and evaluates only the moon you pick. The Is Eclipse, Is Solar Eclipse, and Is Lunar Eclipse fields are calendar-wide and fire when any moon eclipses. All four fields stay hidden until at least one moon has eclipses enabled.

Text enrichers

The [[cal.eclipse]] and [[cal.nexteclipse]] enrichers embed eclipse data in journals, chat, and item descriptions. See Text Enrichers for syntax and parameters.

For developers

See API Reference and Hooks.