Calendar Editor

Create a custom calendar or edit an existing one. Open the editor from Settings → Module Settings → Calendaria → Open Calendar Editor.

Overview

The editor has 12 tabs. Overview and Display stand on their own in pink. The other ten are grouped by color: Structure (Months, Weeks, Years, Time) in green, Features (Festivals, Eras, Cycles, Moons, Seasons, Weather) in orange.

Toggle Navigation in the window header’s controls menu collapses the tab sidebar to icons only. Choose it again to restore the labels. The collapsed state lasts until you close the editor.

Editor Navigation

Overview tab

Calendar selector

Calendar Dropdown. Select a calendar template or a custom calendar to edit. The selection loads automatically.
Duplicate Calendar. Copy the loaded calendar.
Create from Scratch. Start a blank calendar.

Calendar identity

Name. Display name for the calendar. Required.
Description. Optional notes about the calendar.

System sync

Shown only when the active game system is PF2E or SF2E.

System WorldClock Theme. Selects the date theme reported to the system’s World Clock and stored on the calendar as metadata.luxonSync.theme. The options reuse the system’s own date-theme labels. A calendar with no theme set hides the system’s in-game Show Clock button. Setting a theme hands the Year Zero Weekday on the Years tab to the system’s World Clock. Clear the theme to control that weekday yourself.

Display tab

Each format field previews itself below the input using sample date and time values. An invalid format string gets an error border, and the error text replaces its preview. A format string containing letters that match no token gets a warning on the preview, and the tooltip names the unrecognized letters.

The question-mark icon on the Date Formats legend opens the Format Token Reference dialog.

Format fields

Field	Used for
Short Format	Compact date strings
Long Format	Expanded date strings
Full Format	The longest date form
Cross-Calendar Format	This calendar’s date when it appears as a cross-calendar entry on another calendar
Time Format (24h)	24-hour clock display
Time Format (12h)	12-hour clock display
Week View Header	The header above BigCal’s week view
Year View Header	The header above BigCal’s year view
Year View Label	The per-year label inside the year view

Months tab

Monthless mode

Remove every month and the tab switches to monthless mode. A notice and a Days Per Year field take the place of the month rows, and Days Per Year sets the total days in each year. MiniCal shows one week at a time instead of a month grid, and month format tokens return empty strings. Seasons and festivals fall back to day-of-year ranges. To return to month-based navigation, add a month.

Month fields

Column	Description
Name	Full month name
Abbreviation	Short form
days	Number of days in a normal year
Leap	Extra days added during leap years
Starts On	Auto (calculated) or fixed weekday for day 1 of this month. Disabled while a week cycle is active
Type	Standard or Intercalary

Month types

Standard. Normal month in the regular calendar structure
Intercalary. Days outside the normal month and week structure. Intercalary days are excluded from weekday progression.

Month controls

Custom Weekdays (calendar-week icon): Opens a dialog listing this month’s weekdays with a Name, Abbreviation and Rest Day field each. The rows start as a copy of the global weekdays. Save stores them as this month’s override. Reset removes the override. Saving rows identical to the global weekdays also removes the override. The button is highlighted while an override is configured.
Add (+): Insert a new month after this one
Move Up/Down (chevrons): Reorder months
Remove (trash icon): Delete this month

Zero-day months

Months with 0 base days only appear during leap years when extra days are added.

Navigation skips 0-day months in non-leap years
Year view displays 0-day months with reduced opacity

Weeks tab

Weekdays list

Column	Description
Name	Full weekday name. May be left blank
Abbreviation	Short form
Rest Day	Checkbox. Marks weekends for styling and hooks

Weekday controls

Add (+): Insert a new weekday after this one
Move Up/Down (chevrons): Reorder weekdays
Remove (trash icon): Delete this weekday

A calendar needs at least one weekday. Removing the last one is refused with a warning.

Week Start

Rotates the calendar grid so the chosen weekday appears in the first column of MiniCal and BigCal. The rotation is display only, and the underlying weekday cycle order is unchanged. When unset, it defaults to the first weekday in the Weekdays list. This selector is disabled while a week cycle is active.

Week cycle

A week cycle makes weeks vary in length. Each row is one week in the cycle, and the cycle repeats in order. Every row has a name and a checkbox for each weekday, and unchecking a weekday skips it in that week. The cycle sits alongside the Weekdays list, which still defines the pool of weekday names.

The name you give a row becomes that week’s named week.

With no rows, the section shows an empty state and an Add button. Use the row Add (+) button to insert another row after it, and the Remove (trash icon) to delete a row.

Named weeks

Named weeks are optional. With no entries, the section shows “No named weeks defined.” Use the Add button to create the first entry, which activates named weeks.

Progression Mode. How weeks are numbered:
- Per Year. Week numbers continue through the entire year.
- Per Month. Week numbers reset at the start of each month.
Repeat. Shown in Per Year mode once at least one entry exists. Cycles the named weeks beyond the last defined week number.

Column	Description
Week Name	Full week name
Abbreviation	Short form
Week Number	Which week number this name targets. Per Year mode only. Duplicate numbers are flagged

Named days

Give an individual day of the calendar its own name. Named days are optional. With no entries, the section shows “No named days defined.” Use the Add button to create the first entry, which activates named days.

Progression Mode. How days are numbered:
- Per Year. Day numbers count continuously through the year, including intercalary days.
- Per Month. Day numbers reset at the start of each month.
Repeat. Shown once at least one entry exists. Cycles the named days beyond the last defined day number.

Column	Description
Day Name	Full day name
Abbreviation	Short form. Falls back to the first letters of the name when left blank
Day Number	Which day number this name targets. Duplicate numbers are flagged

Use the row Add (+) button to insert another entry after it, and the Remove (trash icon) to delete one.

Years tab

Year settings

Year Zero. The reference year (year 0 in your calendar’s internal numbering)
Epoch Day Offset. Shifts the calendar by whole days along the shared world timeline. Use it to align a secondary calendar to a specific date without changing its month layout.
Year Zero Weekday. Which weekday falls on day 1 of year zero. This drives the calendar’s weekday calculations. When a System WorldClock Theme is set, the system’s World Clock derives this weekday and the selector is locked. The locked selector shows the weekday currently in effect. Your authored weekday is kept and returns when you clear the theme.
Reset Weekdays. Restarts the weekday cycle on the first day of every year, so day 1 of each year lands on the same weekday. Leave it off to let the weekday cycle run unbroken across year boundaries.
Allow Negative Years. Permits navigation to years before year 1. With it off, MiniCal and BigCal clamp the viewed year to 1.

Leap year configuration

Leap Year Rule. Select how leap years are calculated:
- None. No leap years
- Simple. Every N years
- Gregorian. Standard Earth calendar rules (every 4 years, except centuries, except 400-year marks)
- Fixed Cycle. Leap years at fixed offsets within a repeating period
- Custom. Pattern-based rules

Simple leap year fields

Leap Year Interval. How often leap years occur
First Leap Year. First year with a leap day

Custom leap year fields

Leap Year Pattern. Comma-separated divisibility rules. A year matches when it is divisible by any listed number. Prefix a number with ! to exclude years divisible by it.
First Leap Year. First year the pattern applies from

Fixed Cycle leap year fields

Leap Cycle Length. Length of the repeating cycle in years
Leap Year Offsets. Comma-separated year offsets within the cycle that are leap years. The bundled Islamic calendar uses this rule for its tabular leap cycle.

Named years

Assign display names to specific years. When a year has a name, the [yearName] format token renders it in date strings. The pipe fallback syntax [yearName|YYYY] shows the year name when defined, falling back to the numeric year.

Column	Description
Name	Display name for the year
Year	The year number this name applies to

Time tab

Time structure

Hours Per Day. Number of hours in one day
Minutes Per Hour. Number of minutes per hour
Seconds Per Minute. Number of seconds per minute
Seconds Per Round. Combat round duration in seconds

Non-standard time units

A calendar can use any number of hours per day, minutes per hour, and seconds per minute. When it does:

AM/PM midday is calculated as hoursPerDay / 2 instead of fixed 12
Time dial and hour markers scale to the configured hours
All API time methods respect the calendar’s time structure
Sunrise and sunset calculations adapt to the day length

Daylight hours

Enable Dynamic Daylight. Toggle daylight calculations on or off. When unchecked, the other daylight fields are hidden
Shortest Day. Month and day of the winter solstice
Shortest Day Sunlight. Hours of daylight on the shortest day
Longest Day. Month and day of the summer solstice
Longest Day Sunlight. Hours of daylight on the longest day

Daylight hours are interpolated between these solstices using a sinusoidal curve.

Meridiem indicators

Ante Meridiem. Full text for morning hours
Post Meridiem. Full text for afternoon and evening hours
AM Abbreviation. Abbreviated morning label
PM Abbreviation. Abbreviated evening label

The A and a format tokens use the abbreviated forms. The [meridiemFull] token gives the full-length labels.

Canonical hours

Define named time periods such as Dawn or Dusk.

Column	Description
Name	Period name
Abbreviation	Short form
Start Hour	When this period begins (0 to hoursPerDay)
End Hour	When this period ends (0 to hoursPerDay)

Seasons tab

Season type

Dated. Seasons have fixed start and end dates
Periodic. Seasons cycle by a fixed duration in days

Season offset (periodic only)

Starting Offset. Number of days into the year before the first season begins

Season fields

Field	Description
Name	Season name
Abbreviation	Short form
Icon/Color	Click the icon button to open an edit dialog for Font Awesome icon and color
Seasonal Type	Canonical season tag (Spring, Summer, Autumn, Winter) used to resolve equinox and solstice anchors and to drive weather integrations. Seasons left unset are skipped when astronomical anchors are resolved

Dated season fields

Start Month/Day. When this season begins
End Month/Day. When this season ends

Periodic season fields

Duration. Number of days this season lasts

Season controls

Add (+): Insert a new season after this one
Remove (trash icon): Delete this season

Per-season temperature ranges and weather chance overrides are configured from the Weather tab.

Astronomical anchors

Equinox and solstice festivals, and computed notes that anchor to an equinox or solstice, find their target day from the calendar’s daylight curve. The Longest Day is the day with the most daylight and the Shortest Day is the day with the least. The spring and autumn equinoxes fall at the midpoints between them. A calendar can define explicit spring and autumn equinox dates in its data, and anchors then use those dates instead of the midpoints. These days follow the configured Shortest Day and Longest Day dates and stay correct across leap years. A season with no Seasonal Type set is skipped, and an anchor that references a type with no matching season does not resolve.

A computed step that searches for a moon phase resolves to the day nearest the exact phase point rather than the first day of a multi-day phase span. Phases match by their underlying key even when the phase name is renamed or translated. A phase day that falls before the step’s start date belongs to the previous lunation and is skipped.

Eras tab

Era fields

Column	Description
Name	Era name
Abbreviation	Short form
Start Year	First year of this era
End Year	Last year of this era (leave blank for ongoing)

Indexed era tokens

When multiple eras overlap, use indexed tokens to reference a specific match. The index is zero-based:

Token	Description
`[era=N]`	Full name of matching era N, starting from 0
`[eraAbbr=N]`	Abbreviation of matching era N
`[yearInEra=N]`	Year within matching era N

If year 1492 falls in both “Dale Reckoning” and “Age of Mortals”, [era=0] gives “Dale Reckoning” and [era=1] gives “Age of Mortals”.

Era controls

Add (+): Insert a new era after this one
Remove (trash icon): Delete this era

Festivals tab

The Festivals tab is a read-only list. Each festival’s metadata lives on its linked journal note. When you open the editor straight from an import, the tab shows a notice with the count of imported festivals. They are created and listed once you save the calendar, after which you can reopen it to edit them.

Add Festival: Create a new festival note and link it to the calendar
Reset to Bundled: Restore the festival notes for bundled calendars back to their template set. Not available on custom calendars.

Festival list

Column	Description
Icon	The festival’s icon rendered in the festival’s color
Name	Festival name
Schedule Summary	Readable summary of the festival’s schedule

Item controls per row:

Open (pencil icon): Open the festival’s linked note sheet to edit metadata
Delete (trash icon): Remove the note and unlink it from the calendar

Editing a festival

Festival metadata (name, icon, color, schedule, countsForWeekday, leapYearOnly, leapDuration, description) is stored on the linked journal note. Click Open on a festival row to edit its fields in the note sheet.

BigCal grid cells, MiniCal day cells and intercalary day rows use the festival’s color for their borders, backgrounds, day numbers and icon.

Moons tab

Moon fields

Field	Description
Name	Moon name
Cycle Length	Days for a complete lunar cycle, from new moon to new moon. Accepts decimal values
Color	Tint color for the moon icon
Hide from Players	Checkbox. A hidden moon renders only for the GM

Reference date

A known date when the moon was at a specific phase. The moon’s phase on any date is calculated from this reference point.

Year. Reference year
Month. Reference month
Day. Reference day of the month
Phase. Which phase the moon is at on the reference date (dropdown)
Adjust. Offset in days to fine-tune phase alignment (positive or negative)

Moon phases

Each phase covers a percentage range of the cycle.

Column	Description
Icon	Click to open a file picker and choose an image for this phase. An icon value that is not a file path renders as text instead of an image
Phase	Phase name
Rising	Name for the transitional sub-phase as the moon approaches this phase
Fading	Name for the transitional sub-phase as the moon leaves this phase
Start %	Percentage through the cycle when this phase begins (fixed mode only)
End %	Percentage through the cycle when this phase ends (fixed mode only)
Weight	Relative likelihood of this phase in Randomized mode (minimum `1`). Replaces Start %/End % columns when mode is set to Randomized. Higher weight means the phase occupies a larger share of the cycle

Phase slider

The slider shows all phases as colored segments and syncs bidirectionally with the Start %/End % number inputs.

Moon Phase Slider

Drag handles between phases to adjust boundaries. Adjacent phases push to maintain a 1% minimum gap.
Double-click a phase segment to normalize it to an equal share (100% / number of phases).
Click percentage labels to toggle between percentage and days display.

Moon brightness

Brightness Contribution. Range slider (0 to 0.3) controlling maximum illumination at full moon.

Moon illumination follows a cosine curve based on phase position. Multiple moons sum their contributions. See Moon Phases: Moon Brightness and Scene Ambience.

Phase mode

Phase Mode. Dropdown with two options:
- Fixed (default): Phases follow a deterministic cycle based on the cycle length and reference date. Phase boundaries are defined by Start %/End % values.
- Randomized. Phases are determined by a seeded PRNG, producing erratic, non-cyclical moon behavior.

Randomized mode settings

When phase mode is set to Randomized, additional controls appear:

Phase Seed. Integer seed for the random number generator. The same seed always produces the same phase sequence. Click the dice button to generate a random seed.
Cycle Variance. Range slider (0 to 1) controlling how much the moon’s effective cycle length deviates from its base cycle length. At 0, the randomized cycle stays close to the base length. At 1, cycle lengths vary widely.
Phase Weight (per phase). Number input (minimum 1) in the phases table. Weight controls each phase’s share of the cycle. All phases at weight 1 produces a uniform distribution. Doubling a phase’s weight doubles its likelihood of appearing.

Anchor phases

Guaranteed phase overrides on specific dates. The moon is always at the specified phase on that date regardless of randomization.

Column	Description
Year	The year this anchor applies to (leave blank to apply every year)
Month	Which month the anchor falls in
Day	Day of the month
Phase	Which phase the moon is forced to on this date (dropdown of the moon’s defined phases)
Reset	Checkbox. Takes effect on fixed-mode moons. When enabled, restarts the phase cycle from this anchor point instead of overriding the phase for one day

Add Anchor Phase. Add a new anchor phase entry
Remove (trash icon): Delete an anchor phase

Eclipse settings

Eclipses are configured per moon. They occur when the moon aligns with the calendar’s nodal window model: solar eclipses at new moon during nodal alignment, lunar eclipses at full moon during nodal alignment.

Eclipse Frequency. Dropdown controlling how often eclipses occur:
- None (default): Eclipses disabled for this moon
- Rare. Infrequent eclipses
- Occasional. Moderate eclipse frequency
- Frequent. Eclipses occur often
- Custom. Manually specify the nodal period

Custom eclipse fields

When frequency mode is set to Custom:

Nodal Period. Number of days for the moon’s orbital node to complete one cycle. Controls the spacing between eclipse windows. Smaller values produce more frequent eclipses.

Apparent size

Visible when eclipses are enabled (any mode except None):

Apparent Size. Range slider (0.1 to 2.0) controlling the moon’s apparent angular size relative to the sun. Determines the solar eclipse subtype:
- Values < 1.0 produce annular solar eclipses
- Values >= 1.0 produce total solar eclipses
- Off-center alignments produce partial solar eclipses at any size

Lunar eclipse subtypes (total, partial, penumbral) come from how close the alignment falls to the center of the nodal window, not from apparent size.

Moon and phase controls

Add Moon (+): Add a new moon
Remove Moon (trash icon): Delete this moon. A confirmation dialog appears before removal. On save, notes and moon-phase macro triggers that reference other moons by position are updated to keep pointing at the same moon. Notes that referenced the deleted moon are listed in a warning notification. Macro triggers for the deleted moon are removed.
Add Phase (+): Add a phase to this moon
Remove Phase (trash icon): Delete this phase

Cycles tab

Cycles produce repeating patterns of named stages.

Cycle format

Display Format. Template string for displaying cycle values using placeholders like [1], [2], etc.

Cycle fields

Field	Description
Name	Cycle name
Length	How many units of the Based On unit pass before the cycle advances one stage. Use 1 to advance a stage every unit
Offset	Starting offset (which stage is “first”)
Based On	What unit drives the cycle (see options below)

Based-on options

Calendar Year. Cycle advances each calendar year
Era Year. Cycle advances based on years within the current era
Month. Cycle advances each month
Day of Month. Cycle advances each day of the month (resets monthly)
Absolute Day. Cycle advances each day (total days since epoch)
Day of Year. Cycle advances each day of the year (resets yearly)

Cycle stages

Each cycle has numbered stages that repeat in order.

Stage Name. Name for this position in the cycle

Cycle controls

Add Cycle (+): Add a new cycle
Remove Cycle (trash icon): Delete this cycle
Add Stage (+): Add a stage to this cycle
Remove Stage (trash icon): Delete this stage

Weather tab

Season climate

Lists all defined seasons. Click the edit button (pencil icon) on a season row to open the Climate Editor in season mode, where you configure temperature ranges and weather preset chance overrides for that season.

Zone climate

Two-column list of all climate zones with inline controls:

Name. Inline-editable zone name
Edit (cloud-sun icon): Open the Climate Editor in zone mode for full configuration
Duplicate (copy icon): Clone this zone below, including presets, season overrides, and preset aliases. The copy inherits a unique ID and a “Copy of ” label
Add (+): Opens the Add Climate Zone dialog. Copy from Template seeds the new zone’s presets and temperature ranges from a bundled climate template. Choosing Custom starts it blank. Zone Name sets the label and derives the zone’s id. The zone is inserted after this row.
Remove (trash icon): Delete this zone. A confirmation dialog naming the zone appears first.

Exporting calendars

Click Export to download the current calendar as a JSON file. The filename is the calendar name in lowercase with each run of non-alphanumeric characters replaced by a hyphen, plus a .json extension.

The exported file includes:

All calendar configuration (months, weekdays, seasons, moons, etc.)
Calendar metadata (name, description)
Export version and timestamp
Current date (when exporting the active calendar)
Calendar notes linked to the calendar
Festival seeds reconstructed from linked journal notes

Re-import via the Calendaria JSON importer. See Importing calendars.

Saving your calendar

Click Save Changes to store the calendar. A confirmation dialog appears with one option:

Set as active calendar. Checkbox to switch to this calendar after saving, which reloads the world. Shown only to GMs when the calendar is not already active.

Unsaved changes confirmation

If unsaved changes exist when closing the editor, switching calendars, creating a new calendar, or duplicating, a confirmation dialog asks whether to discard or cancel.

Editing built-in calendars

Modifying a bundled calendar saves changes as an override. Clicking Delete on an overridden bundled calendar prompts to reset it to the original.

Deleting calendars

Delete behavior depends on calendar type:

Custom calendars. Permanently deletes the calendar
Bundled calendars with overrides. Resets to the original bundled version
Bundled calendars without overrides. Cannot be deleted

Deleting a custom calendar asks for confirmation first. Deleting the calendar that is currently active switches the world to the bundled Gregorian calendar before the deletion goes through, and the deletion is abandoned if that switch fails. After a successful delete the editor reloads whichever calendar is active.

Reset button

Reset asks for confirmation, then clears all current editor data and starts with a blank template. It also deletes the festival notes of the loaded calendar. The saved calendar definition is unchanged.