Eras and Cycles

Eras

Eras define historical periods with custom year formatting. Configure eras in the Calendar Editor > Eras tab.

Era fields

Field	Description
Name	Full era name
Abbreviation	Short form
Start Year	First year of this era
End Year	Last year, left empty if ongoing

Overlapping eras

Eras may overlap, with multiple eras covering the same year range. When eras overlap, use indexed format tokens to reference a specific matching era by position.

Era resolution

When displaying a year, Calendaria finds all matching eras by checking which eras contain that year. The yearInEra is calculated as displayYear - startYear + 1.

Displaying eras in date formats

Use era format tokens in date format strings to include era information. The indexed tokens ([era=N], [eraAbbr=N], [yearInEra=N], [yearInEraOrdinal=N]) take a zero-based index into the matching eras. Index 0 returns the first matching era, 1 the second, and so on.

Token	Description
G	Era abbreviation
GGGG	Full era name
[era=N]	Full name of the era at zero-based index N
[eraAbbr=N]	Abbreviation of the era at zero-based index N
[yearInEra=N]	Year within the era at zero-based index N
[yearInEraOrdinal]	Year within era, ordinal form
[yearInEraOrdinal=N]	Ordinal year within the era at zero-based index N

Examples:

• Y G produces “1492 DR”
• Do of MMMM, Y GGGG produces “15th of Hammer, 1492 Dale Reckoning”
• [era=0] / [era=1] produces “Dale Reckoning / Age of Mortals” when both eras overlap

---

Cycles

Cycles are repeating sequences such as zodiac signs or elemental weeks. Configure cycles in the Calendar Editor > Cycles tab.

Cycle fields

Field	Description
Name	Cycle name
Length	How many based-on units each stage lasts (the divisor). Use 1 for one stage per unit. The number of stages is the Stages list length, and the full cycle repeats every Length x (number of stages) based-on units.
Offset	Starting offset for calculation
Based On	Time unit driving the cycle
Stages	List of cycle stages with names

Based-on options

Value	Description
year	Calendar year
eraYear	Year within current era
month	Month index
monthDay	Day of month
day	Absolute day count from epoch
yearDay	Day of year

Display format

The cycle format field controls how cycles appear in the UI. Use numbered placeholders, one per configured cycle in order. Each placeholder is replaced with that cycle’s current stage name.

• [1], [2], etc. - Current stage name for each cycle

Example: [1] - Week of [2] produces “Gemini - Week of Fire”

Tip

To display era and cycle information in date format strings, use the format tokens documented in Format Tokens.

---

For developers

See API Reference and Hooks.