API Reference

Calendaria exposes a public API at CALENDARIA.api for macros and module integration.

[!IMPORTANT] Methods marked “GM only” will fail silently or show a warning when called by non-GM users.

---

Time Management

getCurrentDateTime()

Get the current world date and time.

const now = CALENDARIA.api.getCurrentDateTime();
// Returns: { year, month, dayOfMonth, hour, minute, second, ... }

Returns: object - Time components including year adjusted for yearZero.

---

advanceTime(delta, options)

Advance time by a delta. GM only. When delta is an object with day, hour, minute, second keys, it is converted to seconds using the active calendar’s time configuration.

await CALENDARIA.api.advanceTime({ hour: 8 });
await CALENDARIA.api.advanceTime({ day: 1, hour: 6 });
await CALENDARIA.api.advanceTime(3600); // advance by raw seconds
await CALENDARIA.api.advanceTime({ hour: 8 }, { cinematic: true });

Parameter	Type	Description
delta	number|object	Seconds or time delta object (e.g., {day: 1, hour: 2})
options.cinematic	boolean	Trigger the cinematic overlay (default: false)

Note: API calls do not trigger the cinematic overlay by default. Pass cinematic: true to opt in.

Returns: Promise<number> - New world time in seconds.

---

setDateTime(components, options)

Set time to specific values. GM only.

await CALENDARIA.api.setDateTime({ year: 1492, month: 5, day: 15, hour: 10, minute: 30 });
await CALENDARIA.api.setDateTime({ year: 1492, month: 5, day: 15 }, { cinematic: true });

Parameter	Type	Description
components	object	Time components to set
options.cinematic	boolean	Trigger the cinematic overlay (default: false)

Returns: Promise<number> - New world time in seconds.

Note: API calls do not trigger the cinematic overlay by default. Pass cinematic: true to opt in.

---

jumpToDate(options, advanceOptions)

Jump to a specific date while preserving current time of day. GM only.

await CALENDARIA.api.jumpToDate({
  year: 1492,
  month: 5, // 1-indexed
  day: 1
});
await CALENDARIA.api.jumpToDate({ year: 1492, month: 5, day: 1 }, { cinematic: true });

Parameter	Type	Description
options.year	number	Target year
options.month	number	Target month (1-indexed)
options.day	number	Target day of month (1-indexed)
advanceOptions.cinematic	boolean	Trigger the cinematic overlay (default: false)

Returns: Promise<void>

Note: API calls do not trigger the cinematic overlay by default. Pass cinematic: true to opt in.

---

advanceTimeToPreset(preset, options)

Advance time to the next occurrence of a preset time. GM only.

await CALENDARIA.api.advanceTimeToPreset('sunrise');
await CALENDARIA.api.advanceTimeToPreset('midnight');
await CALENDARIA.api.advanceTimeToPreset('sunrise', { cinematic: true });

Parameter	Type	Description
preset	string	'sunrise', 'midday', 'noon', 'sunset', or 'midnight'
options.cinematic	boolean	Trigger the cinematic overlay (default: false)

Note: API calls do not trigger the cinematic overlay by default. Pass cinematic: true to opt in.

Returns: Promise<number> - New world time in seconds.

---

Clock Control

isClockRunning()

Check if the real-time clock is currently running.

const running = CALENDARIA.api.isClockRunning();

Returns: boolean - True if the clock is running.

---

startClock()

Start the real-time clock. Requires time-change permission. Blocked during active combat or when the game is paused with sync enabled.

CALENDARIA.api.startClock();

Returns: void

---

stopClock()

Stop the real-time clock.

CALENDARIA.api.stopClock();

Returns: void

---

toggleClock()

Toggle the real-time clock on or off.

CALENDARIA.api.toggleClock();

Returns: void

---

isClockLocked()

Check if the clock is currently locked. When locked, all time advancement is blocked.

const locked = CALENDARIA.api.isClockLocked();

Returns: boolean - True if the clock is locked.

---

toggleClockLock()

Toggle the clock lock state. GM only.

await CALENDARIA.api.toggleClockLock();

Returns: Promise<void>

---

getClockSpeed()

Get the current real-time clock speed (game seconds per real second).

const speed = CALENDARIA.api.getClockSpeed();
// Returns: 1 (1 game second per real second at default speed)

Returns: number - Clock speed multiplier.

---

Calendar Access

Calendar collections (months, weekdays, seasons, moons, etc.) are stored as keyed objects with string IDs, not arrays. Use the convenience getter arrays for ordered iteration:

Getter	Collection
monthsArray	months.values
weekdaysArray	days.values
seasonsArray	seasons.values
moonsArray	moons
cyclesArray	cycles
erasArray	eras
festivalsArray	festivals
canonicalHoursArray	canonicalHours
namedWeeksArray	weeks.names
weatherZonesArray	weather.zones

The daysInWeek getter returns weekdaysArray.length || 7.

const calendar = CALENDARIA.api.getActiveCalendar();
const months = calendar.monthsArray; // ordered array
const weekCount = calendar.daysInWeek; // number of weekdays or 7

getActiveCalendar()

Get the currently active calendar.

const calendar = CALENDARIA.api.getActiveCalendar();

Returns: object|null - The active calendar or null.

---

getCalendar(id)

Get a specific calendar by ID.

const calendar = CALENDARIA.api.getCalendar('harptos');

Parameter	Type	Description
id	string	Calendar ID

Returns: object|null - The calendar or null if not found.

---

getAllCalendars()

Get all registered calendars.

const calendars = CALENDARIA.api.getAllCalendars();

Returns: Map<string, object> - Map of calendar ID to calendar.

---

getAllCalendarMetadata()

Get metadata for all calendars.

const metadata = CALENDARIA.api.getAllCalendarMetadata();

Returns: object[] - Array of calendar metadata.

---

addCalendar(id, definition)

Add a new calendar. GM only.

await CALENDARIA.api.addCalendar('myCalendar', calendarDefinition);

Parameter	Type	Description
id	string	Unique calendar ID
definition	object	Calendar definition object

Returns: Promise<object|null> - The created calendar or null if the ID already exists.

---

switchCalendar(id)

Switch to a different calendar. GM only.

await CALENDARIA.api.switchCalendar('greyhawk');

Parameter	Type	Description
id	string	Calendar ID to switch to

Returns: Promise<boolean> - True if switched successfully.

---

setActiveCalendar(id, options)

Set the active calendar. GM only. Accepts an options object that controls whether the world’s DISPLAY_FORMATS setting is rewritten from the new calendar’s authored dateFormats.

await CALENDARIA.api.setActiveCalendar('greyhawk', { useCalendarDefaults: true });

Parameter	Type	Description
id	string	Calendar ID to activate
options.useCalendarDefaults	boolean	When true, rewrites the world DISPLAY_FORMATS setting from the new calendar’s dateFormats so every location maps to calendarDefault. Defaults to false

Returns: Promise<boolean> - True if activated successfully.

---

convertDate(date, fromCalendarId, toCalendarId)

Convert a date from one calendar to another via shared world time.

const converted = CALENDARIA.api.convertDate({ year: 1492, month: 5, day: 15 }, 'harptos', 'greyhawk');
// Returns: { year, month, day, hour, minute }

Parameter	Type	Description
date	object	Date to convert {year, month (1-indexed), day (1-indexed), hour?, minute?}
fromCalendarId	string	Source calendar ID
toCalendarId	string	Target calendar ID

Returns: object|null - Converted date or null.

---

getEquivalentDates(date, calendarId)

Get equivalent dates for a date on all other registered calendars.

const equivalents = CALENDARIA.api.getEquivalentDates({ year: 1492, month: 5, day: 15 });

Parameter	Type	Description
date	object	Date {year, month (1-indexed), day (1-indexed)}
calendarId	string	Source calendar ID (defaults to active calendar)

Returns: Array<{calendarId, calendarName, date, formatted}> - Equivalent dates on all other calendars.

---

getCurrentDateOn(calendarId)

Get the current date expressed on a specific (non-active) calendar.

const date = CALENDARIA.api.getCurrentDateOn('greyhawk');
// Returns: { year, month, day, hour, minute }

Parameter	Type	Description
calendarId	string	Target calendar ID

Returns: object|null - Date on the target calendar, or null.

---

showSecondaryCalendar(calendarId)

Open a secondary calendar viewer for a non-active calendar. The viewer stays synced with worldTime.

CALENDARIA.api.showSecondaryCalendar('greyhawk');

Parameter	Type	Description
calendarId	string	Calendar ID to view

Returns: SecondaryCalendar - The viewer instance.

---

Moon Phases

getMoonPhase(moonIndex)

Get the current phase of a specific moon.

const phase = CALENDARIA.api.getMoonPhase(0);
// Returns: { name, icon, position, dayInCycle }

Parameter	Type	Description
moonIndex	number	Index of the moon (default: 0)

Returns: object|null - Moon phase data.

---

getAllMoonPhases()

Get phases for all moons in the active calendar.

const moons = CALENDARIA.api.getAllMoonPhases();

Returns: Array<object> - Array of moon phase data.

---

getMoonPhasePosition(moonIndex, date)

Get the phase position (0–1) for a moon on a given date. Returns 0 when the moon index is out of range or the calendar has no active moons.

const position = CALENDARIA.api.getMoonPhasePosition(0);
// Returns: 0.5 (full moon)

Parameter	Type	Description
moonIndex	number	Moon index (default: 0)
date	object	Optional date (defaults to today)

Returns: number - Phase position from 0 (new moon) to 1.

---

isMoonFull(moonIndex, date)

Check if a moon is currently in its full phase.

const isFull = CALENDARIA.api.isMoonFull(0);

Parameter	Type	Description
moonIndex	number	Moon index (default: 0)
date	object	Optional date

Returns: boolean - True if the moon is in its full phase.

---

getNextFullMoon(moonIndex, fromDate)

Get the date of the next full moon.

const date = CALENDARIA.api.getNextFullMoon(0);
// Returns: { year, month, day }

Parameter	Type	Description
moonIndex	number	Moon index (default: 0)
fromDate	object	Start date (defaults to today)

Returns: object - Date of next full moon.

---

getNextConvergence(fromDate)

Get the date when all moons are simultaneously full.

const date = CALENDARIA.api.getNextConvergence();

Parameter	Type	Description
fromDate	object	Start date (defaults to today)

Returns: object|null - Date of next convergence, or null if not found within search range.

---

getConvergencesInRange(startDate, endDate)

Get all dates within a range where all moons are simultaneously full.

const dates = CALENDARIA.api.getConvergencesInRange({ year: 1492, month: 0, day: 1 }, { year: 1493, month: 0, day: 1 });

Parameter	Type	Description
startDate	object	Range start
endDate	object	Range end

Returns: object[] - Array of convergence dates.

---

Eclipses

getEclipse(moonOrIndex, date)

Get eclipse data for a moon on a specific date.

const eclipse = CALENDARIA.api.getEclipse(0);
// Returns: { type: 'solar-total', proximity: 0.95 } or { type: null }

Parameter	Type	Description
moonOrIndex	object|number	Moon definition or index into moonsArray
date	object	Date to check {year, month, day} (defaults to current date)

Returns: object - Eclipse result { type, proximity } or { type: null } if no eclipse.

---

isEclipse(date)

Check if any eclipse occurs on a specific date across all moons.

const eclipseToday = CALENDARIA.api.isEclipse();
const eclipseOnDate = CALENDARIA.api.isEclipse({ year: 1492, month: 6, day: 21 });

Parameter	Type	Description
date	object	Date to check (defaults to current date)

Returns: boolean - True if any eclipse occurs.

---

getNextEclipse(moonOrIndex, startDate, options)

Find the next eclipse for a moon.

const next = CALENDARIA.api.getNextEclipse(0);
// Returns: { date: { year, month, day }, type: 'lunar-total', proximity: 1.0 }

Parameter	Type	Description
moonOrIndex	object|number	Moon definition or index into moonsArray
startDate	object	Start searching from (defaults to current date)
options.maxDays	number	Maximum days to search

Returns: object|null - { date, type, proximity } or null if not found.

---

getEclipsesInRange(moonOrIndex, startDate, endDate, options)

Get all eclipses for a moon within a date range.

const eclipses = CALENDARIA.api.getEclipsesInRange(0, { year: 1492, month: 1, day: 1 }, { year: 1493, month: 1, day: 1 });
// Returns: [{ date, type, proximity }, ...]

Parameter	Type	Description
moonOrIndex	object|number	Moon definition or index into moonsArray
startDate	object	Range start {year, month, day}
endDate	object	Range end {year, month, day}
options	object	Search options

Returns: object[] - Array of { date, type, proximity }.

---

Seasons and Sun

getCurrentSeason()

Get the current season.

const season = CALENDARIA.api.getCurrentSeason();

Returns: object|null - Season data with name and properties. This call returns the raw calendar season without alias resolution. Callers wanting display values should use WeatherManager.getAliasedSeason (or WeatherManager.applySeasonAlias(season, zone) for an explicit zone).

---

getAliasedSeason({ scene, zoneId, time })

Static WeatherManager helper that resolves the current season and applies the active zone’s alias.

const season = CALENDARIA.managers.WeatherManager.getAliasedSeason({ scene, zoneId, time });

Parameter	Type	Description
scene	Scene	Scene used to resolve the active zone when zoneId is omitted (optional)
zoneId	string	Explicit zone ID; bypasses scene resolution (optional)
time	number	World time in seconds used to resolve the season; defaults to the current world time

Returns: object - { name, abbreviation, icon, color } with alias overrides merged onto the resolved season.

For an explicit season + zone pair, call WeatherManager.applySeasonAlias(season, zone) directly.

---

getCycleValues()

Get current values for all cycles (zodiac signs, elemental weeks, etc).

const cycles = CALENDARIA.api.getCycleValues();
// Returns: { text, values: [{ cycleName, entryName, index }] }

Returns: object|null - Current cycle values.

---

getSunrise(zone)

Get today’s sunrise time in hours. Zones with both sunriseOverride and sunsetOverride set (and sunrise < sunset, within 0 to hoursPerDay) return the fixed override unchanged across the year, bypassing latitude and shortest/longest interpolation.

const sunrise = CALENDARIA.api.getSunrise();
// With explicit zone:
const sunrise = CALENDARIA.api.getSunrise(myZone);
// Returns: 6.5 (meaning 6:30 AM)

Parameter	Type	Description
zone	object|null	Climate zone object (default: active scene’s zone)

Returns: number|null - Sunrise time in hours.

---

getSunset(zone)

Get today’s sunset time in hours. Zones with both sunriseOverride and sunsetOverride set (and sunrise < sunset, within 0 to hoursPerDay) return the fixed override unchanged across the year.

const sunset = CALENDARIA.api.getSunset();
// With explicit zone:
const sunset = CALENDARIA.api.getSunset(myZone);
// Returns: 18.5 (meaning 6:30 PM)

Parameter	Type	Description
zone	object|null	Climate zone object (default: active scene’s zone)

Returns: number|null - Sunset time in hours.

---

getDaylightHours(zone)

Get hours of daylight today. Zones with both sunriseOverride and sunsetOverride set return sunsetOverride - sunriseOverride as a constant across the year.

const hours = CALENDARIA.api.getDaylightHours();
// With explicit zone:
const hours = CALENDARIA.api.getDaylightHours(myZone);

Parameter	Type	Description
zone	object|null	Climate zone object (default: active scene’s zone)

Returns: number|null - Hours of daylight.

---

getProgressDay(zone)

Get progress through the day period (0 = sunrise, 1 = sunset).

const progress = CALENDARIA.api.getProgressDay();
// With explicit zone:
const progress = CALENDARIA.api.getProgressDay(myZone);

Parameter	Type	Description
zone	object|null	Climate zone object (default: active scene’s zone)

Returns: number|null - Progress value between 0-1.

---

getProgressNight(zone)

Get progress through the night period (0 = sunset, 1 = sunrise).

const progress = CALENDARIA.api.getProgressNight();
// With explicit zone:
const progress = CALENDARIA.api.getProgressNight(myZone);

Parameter	Type	Description
zone	object|null	Climate zone object (default: active scene’s zone)

Returns: number|null - Progress value between 0-1.

---

getTimeUntilTarget(targetHour)

Get time until a specific hour of day.

const time = CALENDARIA.api.getTimeUntilTarget(12);
// Returns: { hours, minutes, seconds }

Parameter	Type	Description
targetHour	number	Target hour (0 to hoursPerDay)

Returns: object|null - Time remaining as { hours, minutes, seconds }.

[!NOTE] For calendars with non-standard time (e.g., 20 hours/day), the targetHour range is 0 to hoursPerDay.

---

getTimeUntilSunrise()

Get time until next sunrise.

const time = CALENDARIA.api.getTimeUntilSunrise();
// Returns: { hours, minutes, seconds }

Returns: object|null - Time remaining.

---

getTimeUntilSunset()

Get time until next sunset.

const time = CALENDARIA.api.getTimeUntilSunset();

Returns: object|null - Time remaining.

---

getTimeUntilMidnight()

Get time until midnight.

const time = CALENDARIA.api.getTimeUntilMidnight();

Returns: object|null - Time remaining.

---

getTimeUntilMidday()

Get time until midday (noon).

const time = CALENDARIA.api.getTimeUntilMidday();

Returns: object|null - Time remaining.

---

isDaytime()

Check if it’s currently daytime.

const daytime = CALENDARIA.api.isDaytime();

Returns: boolean - True if between sunrise and sunset.

---

isNighttime()

Check if it’s currently nighttime.

const nighttime = CALENDARIA.api.isNighttime();

Returns: boolean - True if before sunrise or after sunset.

---

Weekdays and Rest Days

getCurrentWeekday()

Get the current weekday information.

const weekday = CALENDARIA.api.getCurrentWeekday();
// Returns: { index, name, abbreviation, isRestDay }

Returns: object|null - Weekday data.

---

getCurrentWeek()

Get the current named week for the active world time. Exposed on the active calendar instance, not on CALENDARIA.api.

const calendar = CALENDARIA.managers.CalendarManager.getActiveCalendar();
const week = calendar?.getCurrentWeek();
// Returns: { weekName, weekAbbr, weekNumber, index }

Returns: object|null - Named week data, or null if no named weeks are defined or no entry matches the current date.

---

isRestDay()

Check if today is a rest day.

const isRest = CALENDARIA.api.isRestDay();

Returns: boolean - True if current day is a rest day.

---

Festivals

getCurrentFestival()

Get the festival on the current date, if any.

const festival = CALENDARIA.api.getCurrentFestival();

Returns: object|null - Festival data with name, month, day.

---

isFestivalDay()

Check if today is a festival day.

const isFestival = CALENDARIA.api.isFestivalDay();

Returns: boolean - True if current date is a festival.

---

createFestival(calendarId, festivalData)

Create a festival note for a calendar. GM only.

await CALENDARIA.api.createFestival('harptos', {
  name: 'Midsummer',
  content: '<p>The feast of Midsummer.</p>',
  startDate: { year: 1492, month: 7, day: 1 },
  color: '#f0a500',
  icon: 'fa-sun',
  duration: 1,
  categories: ['festival']
});

Parameter	Type	Description
calendarId	string	Calendar ID
festivalData.name	string	Festival name
festivalData.content	string	Description (HTML)
festivalData.startDate	object	Start date {year, month (1-indexed), day (1-indexed)}
festivalData.color	string	Festival color (hex)
festivalData.icon	string	Icon class (e.g., 'fa-sun')
festivalData.duration	number	Duration in days (default: 1)
festivalData.conditionTree	object	Condition tree for recurrence
festivalData.categories	string[]	Preset IDs

Returns: Promise<object|null> - Created note page, or null on failure.

---

getFestivals(calendarId)

Get all festival notes for a calendar.

const festivals = CALENDARIA.api.getFestivals();
// Or for a specific calendar:
const festivals = CALENDARIA.api.getFestivals('harptos');

Parameter	Type	Description
calendarId	string	Calendar ID (defaults to active calendar)

Returns: object[] - Array of festival note stubs.

---

Formatting

formatDate(components, formatOrPreset)

Format date and time components as a string.

// Using presets
const formatted = CALENDARIA.api.formatDate(null, 'dateLong');
const formatted = CALENDARIA.api.formatDate(null, 'datetime12');

// Using custom format
const formatted = CALENDARIA.api.formatDate({ year: 1492, month: 5, day: 15 }, 'DD MMMM YYYY');

Parameter	Type	Description
components	object	Time components (defaults to current time)
formatOrPreset	string	Preset name or format string (default: 'dateLong')

Presets:

Category	Presets
Utility	'off', 'calendarDefault', 'custom'
Approximate	'approxDate', 'approxTime'
Standard	'dateShort', 'dateMedium', 'dateLong', 'dateFull'
Regional	'dateUS', 'dateUSFull', 'dateISO', 'dateNumericUS', 'dateNumericEU'
Ordinal/Fantasy	'ordinal', 'ordinalLong', 'ordinalEra', 'ordinalFull', 'seasonDate'
Time	'time12', 'time12Sec', 'time24', 'time24Sec'
DateTime	'datetimeShort12', 'datetimeShort24', 'datetime12', 'datetime24'

Returns: string - Formatted date/time string.

[!NOTE] When passing custom components, the day property should be 1-indexed (1-31). Internal time components use 0-indexed dayOfMonth (0-30). The formatDate() function automatically converts to 1-indexed for display when using D or DD tokens.

---

timeSince(targetDate, currentDate)

Get relative time description between two dates.

const relative = CALENDARIA.api.timeSince({ year: 1492, month: 5, dayOfMonth: 15 });
// Returns: "3 days ago" or "in 2 weeks"

Parameter	Type	Description
targetDate	object	Target date { year, month, dayOfMonth }
currentDate	object or null	Current date (defaults to current time)

Returns: string - Relative time string.

---

getFormatTokens()

Get available format tokens and their descriptions.

const tokens = CALENDARIA.api.getFormatTokens();
// Returns: [{ token, descriptionKey, type }, ...]

Returns: Array<{token: string, descriptionKey: string, type: string}> - Available format tokens.

---

getFormatPresets()

Get default format presets.

const presets = CALENDARIA.api.getFormatPresets();

Returns: object - Format preset definitions.

---

Date/Time Conversion

timestampToDate(timestamp)

Convert a world time timestamp to date components.

const date = CALENDARIA.api.timestampToDate(86400);
// Returns: { year, month, ordinal, monthName, intercalary, day, hour, minute }

Parameter	Type	Description
timestamp	number	World time in seconds

Returns: object|null - Date components:

Field	Type	Description
year	number	Year (adjusted for yearZero)
month	number	1-based sequential month index (includes intercalary months)
ordinal	number	Traditional month ordinal (may be shared by intercalary and regular months)
monthName	string	Localized month name
intercalary	boolean	Whether this month is an intercalary (festival) month
day	number	1-based day of month
hour	number	Hour
minute	number	Minute

---

dateToTimestamp(date)

Convert date components to a world time timestamp.

// Using sequential month index
const timestamp = CALENDARIA.api.dateToTimestamp({
  year: 1492,
  month: 5,
  day: 15,
  hour: 10,
  minute: 30
});

// Using ordinal (prefers non-intercalary months when ordinals are shared)
const timestamp2 = CALENDARIA.api.dateToTimestamp({
  year: 729,
  ordinal: 7,
  day: 1
});

Parameter	Type	Description
date	object	Date components
date.year	number	Year
date.month	number	1-based sequential month index (takes priority over ordinal)
date.ordinal	number	Traditional month ordinal (used if month is not provided)
date.day	number	1-based day of month
date.hour	number	Hour (optional, default 0)
date.minute	number	Minute (optional, default 0)
date.second	number	Second (optional, default 0)

Returns: number - World time in seconds.

---

chooseRandomDate(startDate, endDate)

Generate a random date within a range.

const randomDate = CALENDARIA.api.chooseRandomDate({ year: 1492, month: 0, day: 1 }, { year: 1492, month: 11, day: 31 });

Parameter	Type	Description
startDate	object	Start date (defaults to current date)
endDate	object	End date (defaults to 1 year from start)

Returns: object - Random date components.

---

Date Arithmetic

addDays(date, days)

Add days to a date.

const newDate = CALENDARIA.api.addDays({ year: 1492, month: 5, day: 15 }, 10);
// Returns date 10 days later

Parameter	Type	Description
date	object	Date { year, month, day }
days	number	Days to add (negative to subtract)

Returns: object - New date components.

---

addMonths(date, months)

Add months to a date.

const newDate = CALENDARIA.api.addMonths({ year: 1492, month: 5, day: 15 }, 3);

Parameter	Type	Description
date	object	Date { year, month, day }
months	number	Months to add (negative to subtract)

Returns: object - New date components.

---

addYears(date, years)

Add years to a date.

const newDate = CALENDARIA.api.addYears({ year: 1492, month: 5, day: 15 }, 10);

Parameter	Type	Description
date	object	Date { year, month, day }
years	number	Years to add (negative to subtract)

Returns: object - New date components.

---

addHours(date, hours)

Add hours to a date.

const newDate = CALENDARIA.api.addHours({ year: 1492, month: 5, day: 15, hour: 10 }, 8);

Parameter	Type	Description
date	object	Date { year, month, day, hour?, minute? }
hours	number	Hours to add (negative to subtract)

Returns: object - New date components.

---

addMinutes(date, minutes)

Add minutes to a date.

const newDate = CALENDARIA.api.addMinutes({ year: 1492, month: 5, day: 15, hour: 10, minute: 30 }, 45);

Parameter	Type	Description
date	object	Date { year, month, day, hour?, minute? }
minutes	number	Minutes to add (negative to subtract)

Returns: object - New date components.

---

addSeconds(date, seconds)

Add seconds to a date.

const newDate = CALENDARIA.api.addSeconds({ year: 1492, month: 5, day: 15, hour: 10 }, 3600);

Parameter	Type	Description
date	object	Date { year, month, day, hour?, minute? }
seconds	number	Seconds to add (negative to subtract)

Returns: object - New date components.

---

daysBetween(startDate, endDate)

Calculate the number of days between two dates.

const days = CALENDARIA.api.daysBetween({ year: 1492, month: 5, day: 1 }, { year: 1492, month: 5, day: 15 });
// Returns: 14

Parameter	Type	Description
startDate	object	Start date { year, month, day }
endDate	object	End date { year, month, day }

Returns: number - Days between dates (positive if endDate is later).

---

monthsBetween(startDate, endDate)

Calculate the number of months between two dates.

const months = CALENDARIA.api.monthsBetween({ year: 1492, month: 0, day: 1 }, { year: 1492, month: 6, day: 1 });
// Returns: 6

Parameter	Type	Description
startDate	object	Start date { year, month, day }
endDate	object	End date { year, month, day }

Returns: number - Months between dates.

---

hoursBetween(startDate, endDate)

Calculate hours between two dates.

const hours = CALENDARIA.api.hoursBetween({ year: 1492, month: 5, day: 1, hour: 8 }, { year: 1492, month: 5, day: 1, hour: 17 });
// Returns: 9

Parameter	Type	Description
startDate	object	Start date { year, month, day, hour?, minute? }
endDate	object	End date { year, month, day, hour?, minute? }

Returns: number - Hours between dates (can be negative/fractional).

---

minutesBetween(startDate, endDate)

Calculate minutes between two dates.

const minutes = CALENDARIA.api.minutesBetween({ year: 1492, month: 5, day: 1, hour: 8, minute: 0 }, { year: 1492, month: 5, day: 1, hour: 8, minute: 45 });
// Returns: 45

Parameter	Type	Description
startDate	object	Start date { year, month, day, hour?, minute? }
endDate	object	End date { year, month, day, hour?, minute? }

Returns: number - Minutes between dates (can be negative).

---

secondsBetween(startDate, endDate)

Calculate seconds between two dates.

const seconds = CALENDARIA.api.secondsBetween({ year: 1492, month: 5, day: 1, hour: 8 }, { year: 1492, month: 5, day: 1, hour: 9 });
// Returns: 3600

Parameter	Type	Description
startDate	object	Start date { year, month, day, hour?, minute? }
endDate	object	End date { year, month, day, hour?, minute? }

Returns: number - Seconds between dates (can be negative).

---

compareDates(date1, date2)

Compare two dates including time components.

const result = CALENDARIA.api.compareDates({ year: 1492, month: 5, day: 15, hour: 10 }, { year: 1492, month: 5, day: 15, hour: 14 });
// Returns: -1 (date1 is earlier)

Parameter	Type	Description
date1	object	First date
date2	object	Second date

Returns: number - -1 if date1 < date2, 0 if equal, 1 if date1 > date2.

---

compareDays(date1, date2)

Compare two dates ignoring time components.

const result = CALENDARIA.api.compareDays({ year: 1492, month: 5, day: 15 }, { year: 1492, month: 5, day: 20 });
// Returns: -1 (date1 is earlier)

Parameter	Type	Description
date1	object	First date
date2	object	Second date

Returns: number - -1 if date1 < date2, 0 if same day, 1 if date1 > date2.

---

isSameDay(date1, date2)

Check if two dates are the same day.

const same = CALENDARIA.api.isSameDay({ year: 1492, month: 5, day: 15, hour: 10 }, { year: 1492, month: 5, day: 15, hour: 20 });
// Returns: true

Parameter	Type	Description
date1	object	First date
date2	object	Second date

Returns: boolean - True if same calendar day.

---

dayOfWeek(date)

Get the weekday index for a date.

const weekday = CALENDARIA.api.dayOfWeek({ year: 1492, month: 5, day: 15 });
// Returns: 0-6 depending on calendar weekdays

Parameter	Type	Description
date	object	Date { year, month, day }

Returns: number - Weekday index (0-based).

---

isValidDate(date)

Check if a date is valid for the active calendar.

const valid = CALENDARIA.api.isValidDate({ year: 1492, month: 5, day: 31 });

Parameter	Type	Description
date	object	Date { year, month, day }

Returns: boolean - True if date exists in the calendar.

---

Notes

getAllNotes()

Get all calendar notes.

const notes = CALENDARIA.api.getAllNotes();

Returns: object[] - Array of note stubs with id, name, flagData, etc.

---

getNote(pageId)

Get a specific note by ID.

const note = CALENDARIA.api.getNote('abc123');

Parameter	Type	Description
pageId	string	Journal entry page ID

Returns: object|null - Note stub or null.

---

getNoteDocument(pageId)

Get the full Foundry JournalEntryPage document for a note.

const page = CALENDARIA.api.getNoteDocument('abc123');
// Access full document properties
console.log(page.text.content);

Parameter	Type	Description
pageId	string	Journal entry page ID

Returns: JournalEntryPage|null - Full Foundry document or null.

[!NOTE] Use getNote() for calendar-specific data (stub). Use getNoteDocument() when you need the full Foundry document for content access or document methods.

---

createNote(options)

Create a new calendar note. Players can create their own notes; GM can create notes for anyone.

const note = await CALENDARIA.api.createNote({
  name: 'Council Meeting',
  content: "<p>Meeting with the Lords' Alliance</p>",
  startDate: { year: 1492, month: 5, day: 15, hour: 14, minute: 0 },
  endDate: { year: 1492, month: 5, day: 15, hour: 16, minute: 0 },
  allDay: false,
  categories: ['meeting'],
  icon: 'fas fa-handshake',
  color: '#4a90e2',
  visibility: 'visible',
  openSheet: 'edit'
});

Parameter	Type	Description
options.name	string	Note title
options.content	string	Note content (HTML). If omitted and categories are set, the preset’s content template is used
options.startDate	object	Start date {year, month, day, hour?, minute?} (1-indexed month/day)
options.endDate	object	End date (optional)
options.allDay	boolean	All-day event (default: true)
options.conditionTree	object	Condition tree for recurrence scheduling (see below)
options.categories	string[]	Preset IDs
options.icon	string	Icon path or class
options.color	string	Event color (hex)
options.visibility	string	'visible', 'hidden', or 'secret' (default: 'visible')
options.displayStyle	string	'icon', 'pip', or 'banner' (default: 'icon')
options.openSheet	false|'edit'|'view'	Open the note sheet after creation in the given mode (default: 'edit'). Pass boolean false to skip

Recurrence with conditionTree

A conditionTree is a group of conditions evaluated against each candidate date. For a recurring annual event, use a fixed month/day group:

// Birthday on Aug 23 every year
await CALENDARIA.api.createNote({
  name: "Aldric's Birthday",
  startDate: { year: 1492, month: 8, day: 23 },
  categories: ['birthday'],
  conditionTree: {
    type: 'group',
    mode: 'and',
    children: [
      { type: 'condition', field: 'month', op: '==', value: 8 },
      { type: 'condition', field: 'day', op: '==', value: 23 }
    ]
  }
});

The type: 'group' field is required on the root — without it the tree is silently ignored and the note only fires on its exact startDate. Inside conditions, month and day values are 1-indexed (matching what you see in the UI), even though startDate.month / startDate.dayOfMonth are 0-indexed internally — the public API converts those for you.

[!WARNING] The legacy repeat field on noteData ('daily', 'weekly', 'monthly', 'yearly', etc.) is deprecated as of 1.0.0 and will be removed in 1.2.0. Express recurrence with conditionTree instead. Passing a deprecated repeat value will emit a Foundry compatibility warning.

Returns: Promise<object|null> - Created note page.

---

updateNote(pageId, updates)

Update an existing note. GM only.

await CALENDARIA.api.updateNote('abc123', {
  name: 'Rescheduled Meeting',
  startDate: { year: 1492, month: 5, day: 16, hour: 14 }
});

Parameter	Type	Description
pageId	string	Journal entry page ID
updates.name	string	New note title
updates.startDate	object	New start date
updates.endDate	object	New end date
updates.allDay	boolean	New all-day setting
updates.conditionTree	object	New condition tree for recurrence
updates.categories	string[]	New preset IDs
updates.icon	string	New icon
updates.color	string	New color
updates.visibility	string	New visibility: 'visible', 'hidden', 'secret'
updates.displayStyle	string	New display style: 'icon', 'pip', 'banner'

Returns: Promise<object|null> - Updated note page.

---

deleteNote(pageId)

Delete a calendar note.

await CALENDARIA.api.deleteNote('abc123');

Parameter	Type	Description
pageId	string	Journal entry page ID

Returns: Promise<boolean> - True if deleted successfully.

---

deleteAllNotes()

Delete all calendar notes. GM only.

await CALENDARIA.api.deleteAllNotes();

Returns: Promise<number> - Number of notes deleted.

---

setNoteVisibility(pageId, visibility)

Set a note’s visibility level.

await CALENDARIA.api.setNoteVisibility('abc123', 'hidden');

Parameter	Type	Description
pageId	string	Journal entry page ID
visibility	string	'visible', 'hidden', or 'secret'

Returns: Promise<object|null> - Updated note page, or null on failure.

---

setNoteDisplayStyle(pageId, style)

Set a note’s display style.

await CALENDARIA.api.setNoteDisplayStyle('abc123', 'banner');

Parameter	Type	Description
pageId	string	Journal entry page ID
style	string	'icon', 'pip', or 'banner'

Returns: Promise<object|null> - Updated note page, or null on failure.

---

navigateToNote(pageId, options)

Open BigCal (or MiniCal) at a note’s date and open its sheet.

await CALENDARIA.api.navigateToNote('abc123');

Parameter	Type	Description
pageId	string	Journal entry page ID
options.context	string	Force target: 'bigcal' or 'minical' (auto-detects if omitted)

Returns: Promise<void>

---

openNote(pageId, options)

Open a note in the UI.

await CALENDARIA.api.openNote('abc123', { mode: 'edit' });

Parameter	Type	Description
pageId	string	Journal entry page ID
options.mode	string	'view' or 'edit' (default: 'view')

Returns: Promise<void>

---

Note Queries

getNotesForDate(year, month, day, options)

Get notes on a specific date.

const notes = CALENDARIA.api.getNotesForDate(1492, 5, 15);
// With full content:
const notes = CALENDARIA.api.getNotesForDate(1492, 5, 15, { includeContent: true });

Parameter	Type	Description
year	number	Display year
month	number	Month (1-indexed)
day	number	Day of month (1-indexed)
options.includeContent	boolean	Include note HTML content in results (default: false)

Returns: object[] - Array of note stubs.

---

getNotesForMonth(year, month, options)

Get all notes in a month.

const notes = CALENDARIA.api.getNotesForMonth(1492, 5);
// With full content:
const notes = CALENDARIA.api.getNotesForMonth(1492, 5, { includeContent: true });

Parameter	Type	Description
year	number	Display year
month	number	Month (1-indexed)
options.includeContent	boolean	Include note HTML content in results (default: false)

Returns: object[] - Array of note stubs.

---

getNotesInRange(startDate, endDate, options)

Get notes within a date range.

const notes = CALENDARIA.api.getNotesInRange({ year: 1492, month: 5, day: 1 }, { year: 1492, month: 5, day: 31 });
// With full content:
const notes = CALENDARIA.api.getNotesInRange({ year: 1492, month: 5, day: 1 }, { year: 1492, month: 5, day: 31 }, { includeContent: true });

Parameter	Type	Description
startDate	object	Start date {year, month, day}
endDate	object	End date {year, month, day}
options.includeContent	boolean	Include note HTML content in results (default: false)

Returns: object[] - Array of note stubs.

---

searchNotes(searchTerm, options)

Search notes by name or content.

const results = CALENDARIA.api.searchNotes('dragon', {
  caseSensitive: false,
  categories: ['quest']
});

Parameter	Type	Description
searchTerm	string	Text to search for
options.caseSensitive	boolean	Case-sensitive search (default: false)
options.categories	string[]	Filter by category IDs

Returns: object[] - Array of note stubs.

---

getNotesByPreset(presetId)

Get notes with a specific preset (category).

const notes = CALENDARIA.api.getNotesByPreset('meeting');

Parameter	Type	Description
presetId	string	Preset ID

Returns: object[] - Array of note stubs.

---

getPresets()

Get all preset (category) definitions.

const presets = CALENDARIA.api.getPresets();

Returns: object[] - Array of preset definitions.

---

addPreset(options)

Add a custom note preset. GM only.

const preset = await CALENDARIA.api.addPreset({
  label: 'Session Log',
  color: '#51cf66',
  icon: 'fas fa-book-open',
  defaults: {
    allDay: true,
    displayStyle: 'icon',
    content: '<p><strong>Recap</strong></p><p></p><p><strong>Key Events</strong></p><p></p>'
  }
});

Parameter	Type	Description
options.label	string	Display name (required)
options.color	string	Hex color
options.icon	string	FontAwesome icon class
options.defaults	object	Default values for notes created with this preset
options.defaults.allDay	boolean	Default all-day setting
options.defaults.displayStyle	string	'icon', 'pip', or 'banner'
options.defaults.visibility	string	'visible', 'hidden', or 'secret'
options.defaults.reminderType	string	'toast', 'chat', or 'dialog'
options.defaults.reminderOffset	number	Reminder offset in hours
options.defaults.hasDuration	boolean	Default multi-day setting
options.defaults.duration	number	Default duration in days
options.defaults.macro	string	Macro ID to execute
options.defaults.content	string	HTML content template pre-filled into new notes

Returns: Promise<object> - The created preset.

---

updatePreset(presetId, updates)

Update a note preset’s properties.

await CALENDARIA.api.updatePreset('session', {
  defaults: { content: '<p><strong>Session Notes</strong></p><p></p>' }
});

Parameter	Type	Description
presetId	string	Preset ID
updates.label	string	New display name
updates.color	string	New hex color
updates.icon	string	New FontAwesome icon class
updates.playerUsable	boolean	Allow non-GM users
updates.defaults	object	Default values (merged with existing)
updates.overrides	object	Override values (merged with existing)

Returns: Promise<object|null> - Updated preset or null if not found.

---

deletePreset(presetId)

Delete a custom note preset.

await CALENDARIA.api.deletePreset('my-custom-preset');

Parameter	Type	Description
presetId	string	Preset ID to delete

Returns: Promise<boolean> - True if deleted.

---

Search

search(term, options)

Search all content including notes and dates.

const results = CALENDARIA.api.search('council', {
  searchContent: true,
  limit: 10
});

Parameter	Type	Description
term	string	Search term (minimum 2 characters)
options.searchContent	boolean	Search note content
options.limit	number	Max results

Returns: object[] - Array of results with type field.

---

Condition Engine

createCondition(field, op, …values)

Create a condition object for use in a condition tree.

const condition = CALENDARIA.api.createCondition('weekday', '==', 0);
// Returns: { type: 'condition', field: 'weekday', op: '==', value: 0 }

Parameter	Type	Description
field	string	Condition field (see conditionFields enum)
op	string	Comparison operator (see conditionOperators enum)
...values	*	Condition value(s). First is primary, second (if any) is secondary value

Returns: object - Condition {type: 'condition', field, op, value, value2?}.

---

createConditionGroup(mode, children, options)

Create a condition group for combining conditions with boolean logic.

const group = CALENDARIA.api.createConditionGroup('and', [CALENDARIA.api.createCondition('weekday', '==', 0), CALENDARIA.api.createCondition('month', '==', 5)]);
// Returns: { type: 'group', mode: 'and', children: [...] }

Parameter	Type	Description
mode	string	'and', 'or', 'nand', 'xor', or 'count'
children	object[]	Array of condition objects and/or nested groups
options.threshold	number	Required match count for 'count' mode

Returns: object - Group {type: 'group', mode, children, threshold?}.

---

evaluateNote(pageId, date, options)

Check if a note occurs on a specific date by evaluating its condition tree.

const matches = CALENDARIA.api.evaluateNote('abc123', { year: 1492, month: 5, day: 15 });
// Silent evaluation (no hook):
const matches = CALENDARIA.api.evaluateNote('abc123', { year: 1492, month: 5, day: 15 }, { silent: true });

Parameter	Type	Description
pageId	string	Journal entry page ID
date	object	Date to check {year, month (1-indexed), day (1-indexed)}
options.silent	boolean	Skip firing the CONDITION_EVALUATED hook (default: false)

Returns: boolean - True if the note occurs on this date.

[!NOTE] The CONDITION_EVALUATED hook fires after evaluation unless silent is true. See Hooks.

---

Recurrence

getNextOccurrences(pageId, count)

Get the next N occurrences of a recurring note from the current date.

const dates = CALENDARIA.api.getNextOccurrences('abc123', 10);
// Returns: [{ year, month, day }, ...]

Parameter	Type	Description
pageId	string	Journal entry page ID
count	number	Number of occurrences to find (default: 5)

Returns: object[] - Array of date objects {year, month (1-indexed), day (1-indexed)}.

---

getNoteOccurrencesInRange(pageId, startDate, endDate, maxOccurrences)

Get all occurrences of a note within a date range.

const dates = CALENDARIA.api.getNoteOccurrencesInRange('abc123', { year: 1492, month: 1, day: 1 }, { year: 1493, month: 1, day: 1 });

Parameter	Type	Description
pageId	string	Journal entry page ID
startDate	object	Range start {year, month (1-indexed), day (1-indexed)}
endDate	object	Range end {year, month (1-indexed), day (1-indexed)}
maxOccurrences	number	Maximum occurrences to return (default: 100)

Returns: object[] - Array of date objects {year, month (1-indexed), day (1-indexed)}.

---

Cinematic Time Skip

isCinematicActive()

Check whether a cinematic overlay is currently playing.

const active = CALENDARIA.api.isCinematicActive();

Returns: boolean - True if a cinematic is playing.

---

playCinematic(payload)

Play a cinematic overlay with a pre-built payload.

const payload = CALENDARIA.api.buildCinematicPayload(startTime, endTime);
await CALENDARIA.api.playCinematic(payload);

Parameter	Type	Description
payload	object	Cinematic payload (from buildCinematicPayload)

Returns: Promise<void> - Resolves when the cinematic completes or is aborted.

---

abortCinematic()

Abort the currently playing cinematic.

CALENDARIA.api.abortCinematic();

Returns: void

---

buildCinematicPayload(startTime, endTime)

Build a cinematic payload without playing it. Used to prepare data for playCinematic().

const payload = CALENDARIA.api.buildCinematicPayload(game.time.worldTime, game.time.worldTime + 604800);

Parameter	Type	Description
startTime	number	Start world time (seconds)
endTime	number	End world time (seconds)

Returns: object - Cinematic payload with keyframes and settings.

---

Fog of War

isFogEnabled()

Check whether Fog of War is enabled.

const enabled = CALENDARIA.api.isFogEnabled();

Returns: boolean

---

isDateRevealed(year, month, day, calendarId?)

Check whether a specific date is revealed for the current user. GMs always get true. Returns true if fog is disabled.

CALENDARIA.api.isDateRevealed(1492, 6, 15);
CALENDARIA.api.isDateRevealed(1492, 6, 15, 'harptos');

Parameter	Type	Description
year	number	Year
month	number	Month (1-indexed)
day	number	Day (1-indexed)
calendarId	string	Calendar ID (optional, defaults to active)

Returns: boolean

---

getRevealedRanges(calendarId?)

Get all revealed date ranges for a calendar.

const ranges = CALENDARIA.api.getRevealedRanges();
// [{ start: { year: 1492, month: 1, day: 1 }, end: { year: 1492, month: 6, day: 15 } }]

Parameter	Type	Description
calendarId	string	Calendar ID (optional, defaults to active)

Returns: Array<{start, end}> - Each with {year, month, day} (1-indexed).

---

revealDateRange(start, end, calendarId?)

Reveal a date range. GM only. Overlapping and adjacent ranges merge automatically.

await CALENDARIA.api.revealDateRange({ year: 1492, month: 1, day: 1 }, { year: 1492, month: 6, day: 15 });

Parameter	Type	Description
start	object	Start date {year, month (1-indexed), day (1-indexed)}
end	object	End date {year, month (1-indexed), day (1-indexed)}
calendarId	string	Calendar ID (optional, defaults to active)

Returns: Promise<void>

---

clearRevealedRanges(calendarId?)

Clear all revealed ranges for a calendar. GM only.

await CALENDARIA.api.clearRevealedRanges();

Parameter	Type	Description
calendarId	string	Calendar ID (optional, defaults to active)

Returns: Promise<void>

---

Date Picker

showDatePicker(options)

Show a date picker dialog. Returns the selected date as a Promise, and optionally fires a callback.

const date = await CALENDARIA.api.showDatePicker({ showTime: true });
// Returns: { year, month, day, hour, minute } or null if cancelled

// With callback and positioning:
CALENDARIA.api.showDatePicker({
  title: 'Select Date',
  position: { x: 200, y: 300 },
  onSelect: (date) => console.log('Selected:', date)
});

Parameter	Type	Description
options.date	object	Initial date {year, month (1-indexed), day (1-indexed)} (defaults to current)
options.showTime	boolean	Show time inputs (default: false)
options.title	string	Custom dialog title
options.position	object	Dialog position {x, y} in pixels
options.onSelect	Function	Callback fired with the selected date

Returns: Promise<object|null> - Selected date or null if cancelled.

---

Application Controls

All applications have show, hide, and toggle methods on the public API.

// BigCal
CALENDARIA.api.showBigCal();
CALENDARIA.api.hideBigCal();
CALENDARIA.api.toggleBigCal();

// MiniCal
CALENDARIA.api.showMiniCal();
CALENDARIA.api.hideMiniCal();
CALENDARIA.api.toggleMiniCal();

// HUD
CALENDARIA.api.showHUD();
CALENDARIA.api.hideHUD();
CALENDARIA.api.toggleHUD();

// TimeKeeper
CALENDARIA.api.showTimeKeeper();
CALENDARIA.api.hideTimeKeeper();
CALENDARIA.api.toggleTimeKeeper();

// Sun Dial
CALENDARIA.api.showSunDial();
CALENDARIA.api.showSunDial({ closeOnClickOutside: true });
CALENDARIA.api.hideSunDial();
CALENDARIA.api.toggleSunDial();

// Stopwatch
CALENDARIA.api.showStopwatch();
CALENDARIA.api.hideStopwatch();
CALENDARIA.api.toggleStopwatch();

// Chronicle
CALENDARIA.api.showChronicle();
CALENDARIA.api.showChronicle({ startDate, endDate, lockedRange: true, calendarId });
CALENDARIA.api.hideChronicle();
CALENDARIA.api.toggleChronicle();

// Note Viewer (supports pre-filter options)
CALENDARIA.api.showNoteViewer();
CALENDARIA.api.showNoteViewer({ date: { year: 1492, month: 5, day: 15 } });
CALENDARIA.api.showNoteViewer({ preset: 'meeting', search: 'dragon' });
CALENDARIA.api.showNoteViewer({ visibility: 'hidden' });
CALENDARIA.api.hideNoteViewer();
CALENDARIA.api.toggleNoteViewer();

// Secondary Calendar
CALENDARIA.api.showSecondaryCalendar('greyhawk');

showChronicle(options)

Show the Chronicle with an optional locked date range.

Parameter	Type	Description
options.startDate	object	Range start {year, month (1-indexed), day (1-indexed)}
options.endDate	object	Range end {year, month (1-indexed), day (1-indexed)}
options.lockedRange	boolean	Locks the view to startDate/endDate
options.calendarId	string	Calendar ID whose entries drive the view

Returns: Chronicle - The chronicle instance.

showNoteViewer(options)

Show the Note Viewer with optional pre-filters.

Parameter	Type	Description
options.date	object	Pre-filter to date {year, month (1-indexed), day (1-indexed)}
options.preset	string	Pre-filter to preset ID
options.search	string	Pre-filter with search term
options.visibility	string	Pre-filter to visibility level

Returns: NoteViewer - The viewer instance.

Stopwatch Controls

CALENDARIA.api.startStopwatch(); // Show and start
CALENDARIA.api.pauseStopwatch(); // Pause if running
CALENDARIA.api.resetStopwatch(); // Reset to zero

---

openCalendarEditor(calendarId)

Open the calendar editor. GM only.

await CALENDARIA.api.openCalendarEditor(); // New calendar
await CALENDARIA.api.openCalendarEditor('custom'); // Edit existing

Parameter	Type	Description
calendarId	string	Calendar ID to edit (omit for new)

Returns: Promise<object|null> - The editor application.

---

Weather

getCurrentWeather(zoneId)

Get current weather state, optionally for a specific zone.

const weather = CALENDARIA.api.getCurrentWeather();
// With specific zone:
const weather = CALENDARIA.api.getCurrentWeather('desert');
// Returns: { id, label, icon, color, temperature, wind, precipitation, ... }

Parameter	Type	Description
zoneId	string	Optional zone ID (defaults to active scene’s zone)

Returns: object|null - Current weather state including wind { speed, direction, forced } and precipitation { type, intensity }.

---

setWeather(presetId, options)

Set weather by preset ID.

await CALENDARIA.api.setWeather('thunderstorm', { temperature: 65 });
// Set weather for a specific intraday period:
await CALENDARIA.api.setWeather('rain', { period: 'morning' });
// Set all periods at once:
await CALENDARIA.api.setWeather('snow', { allPeriods: true });
// Override wind and precipitation on top of the preset:
await CALENDARIA.api.setWeather('cloudy', {
  temperature: 11,
  wind: { speed: 2, direction: 'SW', forced: false },
  precipitation: { type: null, intensity: 0 }
});

Parameter	Type	Description
presetId	string	Weather preset ID (e.g., 'clear', 'rain', 'thunderstorm')
options.temperature	number	Optional temperature value
options.wind	object	Wind override { speed, direction, forced } (falls back to preset wind when omitted)
options.precipitation	object	Precipitation override { type, intensity } (falls back to preset precipitation when omitted)
options.period	string	Specific period to set when intraday is enabled ('night', 'morning', 'afternoon', 'evening')
options.allPeriods	boolean	Set all periods to this weather when intraday is enabled

Wind values: speed is an integer 0-5 (calm, light, moderate, strong, severe, extreme — see WIND_SPEEDS in scripts/constants.mjs). direction can be a number in degrees (0 = N, 90 = E, 180 = S, 270 = W), a 16-point compass string ('N', 'NNE', 'NE', …, 'NW', 'NNW'), or null. Strings are converted to degrees internally via COMPASS_DIRECTIONS — pass a number if you need precise rotation. forced is a boolean that locks the wind against generator inertia.

Precipitation values: type is null, 'drizzle', 'rain', 'snow', 'sleet', or 'hail'. intensity is a number in the range 0-1.

Returns: Promise<object> - The set weather.

---

setCustomWeather(weatherData)

Set custom weather with arbitrary values.

await CALENDARIA.api.setCustomWeather({
  label: 'Magical Storm',
  icon: 'fas fa-bolt',
  color: '#9b59b6',
  description: 'Arcane lightning crackles overhead',
  temperature: 45
});

Parameter	Type	Description
weatherData.label	string	Display label
weatherData.icon	string	Font Awesome icon class
weatherData.color	string	Display color
weatherData.description	string	Description text
weatherData.temperature	number	Temperature value

Returns: Promise<object> - The set weather.

---

clearWeather()

Clear the current weather.

await CALENDARIA.api.clearWeather();

Returns: Promise<void>

---

getCurrentWeatherPeriod()

Get the current intraday weather period based on the world clock.

const period = CALENDARIA.api.getCurrentWeatherPeriod();
// Returns: 'night', 'morning', 'afternoon', or 'evening'

Returns: string - Current period ID.

---

getWeatherForPeriod(periodName, zoneId)

Get weather for a specific intraday period from the current day.

const weather = CALENDARIA.api.getWeatherForPeriod('morning');
// With specific zone:
const weather = CALENDARIA.api.getWeatherForPeriod('evening', 'desert');

Parameter	Type	Description
periodName	string	Period ID: 'night', 'morning', 'afternoon', 'evening'
zoneId	string	Zone ID (defaults to active scene’s zone)

Returns: object|null - Weather data for the period, or null if intraday is disabled.

---

generateWeather(options)

Generate and set weather based on climate and season.

await CALENDARIA.api.generateWeather();
await CALENDARIA.api.generateWeather({ climate: 'tropical', season: 'summer' });

Parameter	Type	Description
options.climate	string	Climate override
options.season	string	Season override

Returns: Promise<object> - Generated weather.

---

getWeatherForecast(options)

Get a weather forecast for upcoming days.

const forecast = CALENDARIA.api.getWeatherForecast();
// With options:
const forecast = CALENDARIA.api.getWeatherForecast({ zoneId: 'desert', accuracy: 100 });
// Returns: [{ year, month, day, preset, temperature, wind, precipitation, isVaried }, ...]

Parameter	Type	Description
options.zoneId	string	Zone to get forecast for (defaults to active scene’s zone)
options.accuracy	number	Override forecast accuracy (0–100). GMs default to 100
options.days	number	Number of days (defaults to Forecast Days setting)

Returns: object[] - Array of forecast entries. Each entry includes an isVaried flag indicating whether variance was applied. Forecast entries include a periods property only for GM users; non-GM users receive entries without period breakdown data.

Permission: Requires viewWeatherForecast permission for non-GM users.

---

getWeatherForDate(year, month, day, zoneId)

Get recorded weather for a specific historical date.

const weather = CALENDARIA.api.getWeatherForDate(1492, 7, 15);
// With zone:
const weather = CALENDARIA.api.getWeatherForDate(1492, 7, 15, 'desert');

Parameter	Type	Description
year	number	Year
month	number	Month (0-indexed)
day	number	Day of month (1-indexed)
zoneId	string	Optional zone ID (defaults to active zone)

Returns: object|null - Historical weather entry or null.

---

getWeatherHistory(options)

Get the full weather history, optionally filtered by zone.

const history = CALENDARIA.api.getWeatherHistory();
// Zone-filtered:
const history = CALENDARIA.api.getWeatherHistory({ zoneId: 'desert' });

Parameter	Type	Description
options.zoneId	string	Optional zone filter

Returns: object - Nested history structure.

---

clearWeatherHistory(options)

Clear weather history entries. GM only. Also clears the forecast plan by default to prevent deleted entries from regenerating.

// Clear all history
await CALENDARIA.api.clearWeatherHistory({ all: true });

// Clear future entries only
await CALENDARIA.api.clearWeatherHistory({ future: true });

// Clear a specific year
await CALENDARIA.api.clearWeatherHistory({ year: 1492 });

// Clear a specific month (1-indexed)
await CALENDARIA.api.clearWeatherHistory({ year: 1492, month: 7 });

// Clear without resetting forecast plan
await CALENDARIA.api.clearWeatherHistory({ all: true, clearForecast: false });

Parameter	Type	Description
options.all	boolean	Clear all history
options.future	boolean	Clear entries after the current date
options.year	number	Clear entries for a specific year
options.month	number	Clear entries for a specific month (1-indexed, requires year)
options.clearForecast	boolean	Clear the forecast plan (default: true)

Returns: Promise<number> - Number of entries removed.

---

setSceneZoneOverride(scene, zoneId)

Set a per-scene climate zone override.

await CALENDARIA.managers.WeatherManager.setSceneZoneOverride(game.scenes.active, 'tropical');
// Explicitly disable zone (No Zone):
await CALENDARIA.managers.WeatherManager.setSceneZoneOverride(game.scenes.active, null);
// Clear override (revert to calendar default):
await CALENDARIA.managers.WeatherManager.setSceneZoneOverride(game.scenes.active, undefined);

Note: This method is on WeatherManager, not on the public API object.

Parameter	Type	Description
scene	Scene	Scene document
zoneId	string|null|undefined	Zone ID, null for “No Zone”, or undefined to clear

Returns: Promise<void>

---

isZoneDisabled(scene)

Check if a scene has explicitly disabled zone-based weather (“No Zone” selected).

const disabled = CALENDARIA.managers.WeatherManager.isZoneDisabled(game.scenes.active);

Note: This method is on WeatherManager, not on the public API object.

Parameter	Type	Description
scene	Scene	Scene document

Returns: boolean - True if the scene has “No Zone” set.

---

refreshEnvironmentOverrides(presetId)

Invalidate cached environment overrides for a preset. Called internally by the Weather Editor after saving changes.

CALENDARIA.managers.WeatherManager.refreshEnvironmentOverrides('thunderstorm');

Note: This method is on WeatherManager, not on the public API object.

Parameter	Type	Description
presetId	string	Weather preset ID

Returns: void

---

resolveDisplayLabel(presetId, fallbackLabel, calendarId, zoneId)

Resolve the display label for a weather preset. Resolution priority: (1) per-zone alias from the Climate Editor, (2) name override from the Weather Editor, (3) localized fallback label. Useful for module developers who need to display weather names consistent with all override layers.

const label = CALENDARIA.managers.WeatherManager.resolveDisplayLabel('rain', 'Rain', 'harptos', 'desert');
// Returns: "Monsoon" (if aliased) or "Rain" (fallback)

Note: This method is on WeatherManager, not on the public API object.

Parameter	Type	Description
presetId	string	Weather preset ID
fallbackLabel	string	Default label if no alias is configured
calendarId	string	Calendar ID for alias lookup
zoneId	string	Zone ID for alias lookup

Returns: string - Resolved display label.

---

getActiveZone()

Get the active climate zone.

const zone = CALENDARIA.api.getActiveZone();

Returns: object|null - Active zone config.

---

setActiveZone(zoneId)

Set the active climate zone. Fires the calendaria.weatherChange hook and broadcasts the change to all connected clients, so weather displays update immediately.

await CALENDARIA.api.setActiveZone('desert');

Parameter	Type	Description
zoneId	string	Climate zone ID

Returns: Promise<void>

---

getWeatherPresets()

Get all available weather presets.

const presets = await CALENDARIA.api.getWeatherPresets();

Returns: Promise<object[]> - Array of weather presets.

---

getCalendarZones()

Get all climate zones for the active calendar.

const zones = CALENDARIA.api.getCalendarZones();

Returns: object[] - Array of zone configs.

---

addWeatherPreset(preset)

Add a custom weather preset.

await CALENDARIA.api.addWeatherPreset({
  id: 'acid-rain',
  label: 'Acid Rain',
  icon: 'fas fa-skull',
  color: '#2ecc71',
  description: 'Corrosive precipitation',
  tempMin: 10,
  tempMax: 25,
  wind: { speed: 1, direction: null },
  precipitation: { type: 'rain', intensity: 0.6 },
  inertiaWeight: 0,
  hudEffect: 'rain-acid',
  fxPreset: 'acid-rain',
  soundFx: 'rain-acid-rain-blood-rain'
});

Parameter	Type	Description
preset.id	string	Unique ID
preset.label	string	Display label
preset.icon	string	Icon class
preset.color	string	Display color
preset.description	string	Description
preset.tempMin	number	Min temperature (°C)
preset.tempMax	number	Max temperature (°C)
preset.wind	object	{ speed, direction, forced }
preset.precipitation	object	{ type, intensity }
preset.inertiaWeight	number	Inertia multiplier (0–2)
preset.hudEffect	string	HUD particle effect
preset.fxPreset	string	FXMaster effect name
preset.soundFx	string	Sound loop filename

Returns: Promise<object> - The added preset.

---

removeWeatherPreset(presetId)

Remove a custom weather preset.

await CALENDARIA.api.removeWeatherPreset('acid-rain');

Parameter	Type	Description
presetId	string	Preset ID to remove

Returns: Promise<boolean> - True if removed.

---

getTemperature(zoneId)

Get the current temperature for a zone.

const temp = CALENDARIA.api.getTemperature();
// With specific zone:
const temp = CALENDARIA.api.getTemperature('desert');
// Returns: { celsius, display, unit }

Parameter	Type	Description
zoneId	string	Optional zone ID (defaults to active scene’s zone)

Returns: object|null - Temperature data with celsius, display value, and unit.

---

getPreset(presetId)

Get a specific weather preset by ID.

const preset = CALENDARIA.api.getPreset('thunderstorm');
// Returns: { id, label, icon, color, description, tempMin, tempMax, wind, precipitation, ... }

Parameter	Type	Description
presetId	string	Preset ID (e.g., 'clear', 'rain', 'thunderstorm')

Returns: object|null - Preset definition or null if not found.

---

updateWeatherPreset(presetId, updates)

Update an existing custom weather preset. Only custom presets can be updated.

await CALENDARIA.api.updateWeatherPreset('acid-rain', {
  label: 'Caustic Rain',
  color: '#e74c3c',
  tempMax: 30
});

Parameter	Type	Description
presetId	string	Preset ID to update
updates	object	Properties to update (label, icon, color, etc.)

Returns: Promise<object|null> - Updated preset or null if not found.

---

formatTemperature(celsius)

Format a temperature value for display using the world’s temperature unit setting.

const display = CALENDARIA.api.formatTemperature(22);
// Returns: "72°F" (if unit is Fahrenheit) or "22°C" (if unit is Celsius)

Parameter	Type	Description
celsius	number	Temperature in Celsius

Returns: string - Formatted temperature string.

---

playWeatherSound(src, options)

Play a standalone weather sound effect with any Foundry audio path.

await CALENDARIA.api.playWeatherSound('sounds/rain-heavy.ogg');

Parameter	Type	Description
src	string	Foundry audio file path
options	object	Audio context override

Returns: Promise<boolean> - True if playback started.

---

stopWeatherSound(options)

Stop the currently playing weather sound with fade-out.

await CALENDARIA.api.stopWeatherSound();
await CALENDARIA.api.stopWeatherSound({ fade: 500 });

Parameter	Type	Description
options.fade	number	Fade-out duration in ms (default: 2000)

Returns: Promise<boolean> - True if a sound was stopped.

---

playWeatherFX(presetName, options)

Play an FXMaster weather preset. Uses exclusive mode (stops other presets). Requires FXMaster module.

await CALENDARIA.api.playWeatherFX('rain');
await CALENDARIA.api.playWeatherFX('snow', { density: 'heavy' });

Parameter	Type	Description
presetName	string	FXMaster preset name (e.g., 'rain', 'snow', 'fog')
options.density	string	Particle density
options.belowTokens	boolean	Render below token layer

Returns: Promise<boolean> - True if FX started.

---

stopWeatherFX()

Stop all active FXMaster weather effects. Requires FXMaster module.

await CALENDARIA.api.stopWeatherFX();

Returns: Promise<boolean> - True if effects were stopped.

---

getClimateZoneTemplates()

Get all available climate zone templates for creating new zones.

const templates = CALENDARIA.api.getClimateZoneTemplates();
// Returns array of template objects

Returns: Array<object> - Climate zone templates with id, name, temperatures, and weather weights.

---

createClimateZone(zoneConfig)

Create a new climate zone on the active calendar. GM-only.

// Minimal: just a name
const zone = await CALENDARIA.api.createClimateZone({ name: 'Frozen Wastes' });

// Full config
const zone = await CALENDARIA.api.createClimateZone({
  name: 'Frozen Wastes',
  id: 'frozen-wastes',
  description: 'A harsh frozen climate zone',
  temperatures: { Winter: { min: -40, max: -10 }, Summer: { min: -20, max: 5 } },
  presets: [],
  seasonOverrides: {},
  windSpeedRange: { min: 2, max: 5 },
  windDirections: { N: 30, NE: 20, E: 10 },
  brightnessMultiplier: 0.8,
  environmentBase: { hue: 200, intensity: 0.3, luminosity: 0, saturation: -0.2, shadows: 0.5 },
  environmentDark: { hue: 240, intensity: 0.5, luminosity: -0.5, saturation: -0.3, shadows: 0.8 },
  shortestDay: 6,
  longestDay: 18,
  colorShift: { dawn: 30, dusk: 280, night: 240, transitionDuration: 1 }
});

Parameter	Type	Required	Description
name	string	Yes	Zone display name
id	string	No	Zone ID (auto-generated from name if omitted). Must be unique
description	string	No	Zone description text
temperatures	object	No	Temperature ranges keyed by season name ({ 'Winter': { min, max } }). Defaults to { _default: { min: 10, max: 22 } }
presets	Array|object	No	Weather preset configurations
seasonOverrides	object	No	Per-season overrides
windSpeedRange	object	No	Wind speed range ({ min, max }, tiers 0-5)
windDirections	object	No	Wind direction weights by cardinal direction
brightnessMultiplier	number	No	Scene darkness scaling (default: 1.0)
environmentBase	object	No	Base (day) lighting overrides (hue, intensity, luminosity, saturation, shadows)
environmentDark	object	No	Dark (night) lighting overrides
shortestDay	number	No	Manual shortest day hours override
longestDay	number	No	Manual longest day hours override
colorShift	object	No	Time-of-day color shift settings (dawn/dusk/night hue, transition duration)

Returns: Promise<object|null> - The created zone object, or null on failure.

---

getWeatherProbabilities(options)

Get the weather probability breakdown for a zone and season.

const data = CALENDARIA.api.getWeatherProbabilities();
const data = CALENDARIA.api.getWeatherProbabilities({ season: 'Winter' });
const data = CALENDARIA.api.getWeatherProbabilities({ zoneId: 'arctic', season: 'Summer' });

Parameter	Type	Description
zoneId	string	Zone ID (defaults to active zone)
season	string	Season name (defaults to current season)

Returns: object with:

• zone - { id, name } of the resolved zone
• season - Localized season name
• entries - Array of { id, label, icon, color, weight, percent } sorted by percent descending
• tempRange - { min, max } in Celsius

---

openWeatherProbabilities(options)

Open the Weather Probability dialog.

CALENDARIA.api.openWeatherProbabilities();
CALENDARIA.api.openWeatherProbabilities({ season: 'Winter' });

Parameter	Type	Description
zoneId	string	Initial zone ID
season	string	Initial season name

Returns: The dialog instance.

---

isBundledCalendar(calendarId)

Check if a calendar is a bundled (built-in) calendar.

const isBundled = CALENDARIA.api.isBundledCalendar('harptos');
// Returns: true
const isBundled = CALENDARIA.api.isBundledCalendar('custom-mycal');
// Returns: false

Parameter	Type	Description
calendarId	string	Calendar ID to check

Returns: boolean - True if bundled calendar.

---

Multiplayer & Permissions

isPrimaryGM()

Check if current user is the primary GM (responsible for time saves and sync).

const isPrimary = CALENDARIA.api.isPrimaryGM();

Returns: boolean

---

canModifyTime()

Check if current user can modify time.

const canModify = CALENDARIA.api.canModifyTime();

Returns: boolean

---

canManageNotes()

Check if current user can create/edit notes.

const canManage = CALENDARIA.api.canManageNotes();

Returns: boolean

---

Permissions

Individual permission checks are available on the CALENDARIA.permissions namespace. See Permissions for the full permission list and defaults.

hasPermission(permission)

Check if current user has a specific permission.

const canChange = CALENDARIA.permissions.hasPermission('changeDateTime');

Parameter	Type	Description
permission	string	Permission key

Permission Keys: viewBigCal, viewMiniCal, viewTimeKeeper, addNotes, editNotes, deleteNotes, changeDateTime, changeWeather, viewWeatherForecast, changeActiveCalendar, editCalendars

Returns: boolean

---

canViewBigCal()

Check if current user can view the BigCal.

const canView = CALENDARIA.permissions.canViewBigCal();

Returns: boolean

---

canViewMiniCal()

Check if current user can view the MiniCal.

const canView = CALENDARIA.permissions.canViewMiniCal();

Returns: boolean

---

canViewTimeKeeper()

Check if current user can view the TimeKeeper.

const canView = CALENDARIA.permissions.canViewTimeKeeper();

Returns: boolean

---

canAddNotes()

Check if current user can create notes.

const canAdd = CALENDARIA.permissions.canAddNotes();

Returns: boolean

---

canEditNotes()

Check if current user can edit notes owned by other players.

const canEdit = CALENDARIA.permissions.canEditNotes();

Returns: boolean

---

canDeleteNotes()

Check if current user can delete notes.

const canDelete = CALENDARIA.permissions.canDeleteNotes();

Returns: boolean

---

canChangeDateTime()

Check if current user can modify date/time.

const canChange = CALENDARIA.permissions.canChangeDateTime();

Returns: boolean

---

canChangeWeather()

Check if current user can change weather.

const canChange = CALENDARIA.permissions.canChangeWeather();

Returns: boolean

---

canViewWeatherForecast()

Check if current user can view weather forecasts.

const canView = CALENDARIA.permissions.canViewWeatherForecast();

Returns: boolean

---

canChangeActiveCalendar()

Check if current user can switch the active calendar.

const canChange = CALENDARIA.permissions.canChangeActiveCalendar();

Returns: boolean

---

canEditCalendars()

Check if current user can access the Calendar Editor.

const canEdit = CALENDARIA.permissions.canEditCalendars();

Returns: boolean

---

Widgets

For external module integration. See Widgets for full documentation.

widgetPoints

Available widget insertion points.

const points = CALENDARIA.api.widgetPoints;
// { HUD_BUTTONS_LEFT, HUD_BUTTONS_RIGHT, HUD_INDICATORS, HUD_TRAY, MINICAL_SIDEBAR, BIGCAL_ACTIONS }

---

replaceableElements

Built-in indicator elements that can be replaced by widgets.

const elements = CALENDARIA.api.replaceableElements;
// { WEATHER_INDICATOR, SEASON_INDICATOR, ERA_INDICATOR, CYCLE_INDICATOR }

---

registerWidget(moduleId, config)

Register a custom widget.

CALENDARIA.api.registerWidget('my-module', {
  id: 'my-button',
  type: 'button',
  insertAt: 'hud.buttons.right',
  icon: 'fas fa-star',
  label: 'My Button',
  onClick: () => console.log('Clicked!')
});

Parameter	Type	Description
moduleId	string	Your module’s ID
config	object	Widget configuration

See Widgets for config options.

---

getRegisteredWidgets(insertPoint)

Get widgets registered at a specific point.

const widgets = CALENDARIA.api.getRegisteredWidgets('hud.buttons.right');

Parameter	Type	Description
insertPoint	string	Widget point ID

Returns: array - Registered widget configs.

---

getWidgetByReplacement(elementId)

Get widget that replaces a built-in element.

const widget = CALENDARIA.api.getWidgetByReplacement('weather-indicator');

Parameter	Type	Description
elementId	string	Replaceable element ID

Returns: object|null - Widget config or null.

---

refreshWidgets()

Force all widgets to re-render.

CALENDARIA.api.refreshWidgets();

---

Enum Getters

Read-only enum getters for building conditions, setting display styles, and managing visibility.

conditionFields

Get the available condition fields for use with createCondition().

const fields = CALENDARIA.api.conditionFields;
// { MONTH: 'month', WEEKDAY: 'weekday', SEASON: 'season', MOON_PHASE: 'moonPhase', ... }

Returns: object - CONDITION_FIELDS enum (45 fields).

---

conditionOperators

Get the available condition operators.

const ops = CALENDARIA.api.conditionOperators;
// { EQUAL: '==', NOT_EQUAL: '!=', GREATER: '>', LESS: '<', MODULO: '%', DAYS_AGO: 'daysAgo', ... }

Returns: object - CONDITION_OPERATORS enum (11 operators).

---

conditionGroupModes

Get the available condition group modes.

const modes = CALENDARIA.api.conditionGroupModes;
// { AND: 'and', OR: 'or', NAND: 'nand', XOR: 'xor', COUNT: 'count' }

Returns: object - CONDITION_GROUP_MODES enum.

---

displayStyles

Get the available note display styles.

const styles = CALENDARIA.api.displayStyles;
// { ICON: 'icon', PIP: 'pip', BANNER: 'banner' }

Returns: object - DISPLAY_STYLES enum.

---

noteVisibility

Get the available note visibility levels.

const levels = CALENDARIA.api.noteVisibility;
// { VISIBLE: 'visible', HIDDEN: 'hidden', SECRET: 'secret' }

Returns: object - NOTE_VISIBILITY enum.

---

Hooks

hooks

Get all available Calendaria hook name constants. See Hooks for full documentation, parameters, and examples.

const hooks = CALENDARIA.api.hooks;
// Use: Hooks.on(hooks.DAY_CHANGE, (data) => { ... });

Returns: object - Hook name constants (e.g., DAY_CHANGE, WEATHER_CHANGE, CLOCK_START_STOP).

---

CONDITION_EVALUATED Hook

Fires after note condition evaluation via the evaluateNote() API method (unless silent is true).

Hooks.on(CALENDARIA.api.hooks.CONDITION_EVALUATED, (pageId, date, result) => {
  console.log(`Note ${pageId} on ${date.year}-${date.month}-${date.day}: ${result}`);
});

Parameter	Type	Description
pageId	string	Journal entry page ID
date	object	Date that was evaluated
result	boolean	Whether the note matched the date