Hooks

Calendaria fires hooks for module integration and automation.

---

Lifecycle Hooks

calendaria.init

Fired during Foundry’s init hook after the Calendaria global namespace is created.

Parameters: None

Hooks.on('calendaria.init', () => {
  console.log('Calendaria initializing');
});

calendaria.ready

Fired during Foundry’s ready hook after all Calendaria managers are initialized but before any Calendaria applications (HUD, BigCal, MiniCal, etc.) render. Use this hook to register widgets or configure integrations before the UI is built.

Parameters:

• data (object)
  • api (CalendariaAPI) - The public API object
  • calendar (CalendariaCalendar|null) - The active calendar
  • version (string) - Module version

Hooks.on('calendaria.ready', ({ api, calendar, version }) => {
  console.log(`Calendaria v${version} ready with calendar: ${calendar?.id}`);
});

calendaria.rendered

Fired after all Calendaria applications configured to show on load have rendered and are visible. Use this for integrations that need the UI to be fully initialized.

Hooks.on('calendaria.rendered', () => {
  console.log('All Calendaria UIs are now visible');
});

---

Render Hooks

calendaria.preRenderCalendar

Fired before BigCal renders.

Parameters:

• data (object)
  • app (BigCal) - The BigCal application instance
  • displayMode (string) - Current display mode ("month", "week", or "year")
  • calendar (CalendariaCalendar) - Active calendar

Hooks.on('calendaria.preRenderCalendar', (data) => {
  console.log(`BigCal rendering in ${data.displayMode} mode`);
});

calendaria.renderCalendar

Fired after BigCal renders and all DOM setup is complete.

Parameters:

• data (object)
  • app (BigCal) - The BigCal application instance
  • element (HTMLElement) - The rendered application element
  • displayMode (string) - Current display mode ("month", "week", or "year")
  • calendar (CalendariaCalendar) - Active calendar

Hooks.on('calendaria.renderCalendar', (data) => {
  // Inject custom content into BigCal after render
  const dayCell = data.element.querySelector('.day-cell.today');
  if (dayCell) dayCell.classList.add('my-module-highlight');
});

---

Calendar Hooks

calendaria.calendarSwitched

Fired when the active calendar changes. Also fires once at startup after initialization completes.

Parameters:

• id (string) - Calendar ID
• calendar (CalendariaCalendar) - Calendar instance

Hooks.on('calendaria.calendarSwitched', (id, calendar) => {
  console.log(`Switched to: ${id}`);
});

calendaria.remoteCalendarSwitch

Fired when another client switches the active calendar.

Parameters:

• id (string) - Calendar ID
• calendar (CalendariaCalendar) - Calendar instance

Hooks.on('calendaria.remoteCalendarSwitch', (id, calendar) => {
  console.log(`Remote switch to: ${id}`);
});

calendaria.calendarAdded

Fired when a calendar is created or imported.

Parameters:

• id (string) - Calendar ID
• calendar (CalendariaCalendar) - Calendar instance

Hooks.on('calendaria.calendarAdded', (id, calendar) => {
  console.log(`Added: ${calendar.name}`);
});

calendaria.calendarUpdated

Fired when a calendar is modified.

Parameters:

• id (string) - Calendar ID
• calendar (CalendariaCalendar) - Updated calendar instance

Hooks.on('calendaria.calendarUpdated', (id, calendar) => {
  console.log(`Updated: ${id}`);
});

calendaria.calendarRemoved

Fired when a calendar is deleted.

Parameters:

• id (string) - Calendar ID

Hooks.on('calendaria.calendarRemoved', (id) => {
  console.log(`Removed: ${id}`);
});

---

Time Hooks

calendaria.dateTimeChange

Fired on every world time change. Primary hook for time tracking.

Parameters:

• data (object)
  • previous (object) - Previous time components (year, month, dayOfMonth, hour, minute, second)
  • current (object) - Current time components
  • diff (number) - Time delta in seconds
  • calendar (CalendariaCalendar) - Active calendar
  • worldTime (number) - Current world time in seconds

Hooks.on('calendaria.dateTimeChange', (data) => {
  console.log(`Time: ${data.current.hour}:${data.current.minute}`);
  console.log(`Delta: ${data.diff}s`);
});

calendaria.dayChange

Fired when the day changes.

Parameters:

• data (object)
  • previous (object) - Previous time components
  • current (object) - Current time components
  • calendar (CalendariaCalendar) - Active calendar

Hooks.on('calendaria.dayChange', (data) => {
  console.log(`Day ${data.current.dayOfMonth}`);
});

calendaria.monthChange

Fired when the month changes.

Parameters:

• data (object) - Same structure as calendaria.dayChange

Hooks.on('calendaria.monthChange', (data) => {
  console.log(`Month ${data.current.month}`);
});

calendaria.yearChange

Fired when the year changes.

Parameters:

• data (object) - Same structure as calendaria.dayChange

Hooks.on('calendaria.yearChange', (data) => {
  console.log(`Year ${data.current.year}`);
});

calendaria.seasonChange

Fired when the season changes.

Parameters:

• data (object)
  • previous (object) - Previous time components
  • current (object) - Current time components
  • calendar (CalendariaCalendar) - Active calendar
  • previousSeason (object|null) - Previous season definition
  • currentSeason (object|null) - Current season definition

Hooks.on('calendaria.seasonChange', (data) => {
  console.log(`Season: ${data.currentSeason?.name}`);
});

calendaria.remoteDateChange

Fired when time changes from another client.

Parameters:

• data (object)
  • worldTime (number) - New world time in seconds
  • delta (number) - Time delta in seconds

Hooks.on('calendaria.remoteDateChange', (data) => {
  console.log(`Remote time update: ${data.worldTime}`);
});

---

Solar Hooks

Fired when crossing time-of-day thresholds.

calendaria.sunrise

Parameters:

• data (object)
  • worldTime (number) - World time in seconds
  • components (object) - Time components
  • calendar (CalendariaCalendar) - Active calendar

Hooks.on('calendaria.sunrise', (data) => {
  ui.notifications.info('The sun rises!');
});

calendaria.sunset

Parameters: Same as calendaria.sunrise

Hooks.on('calendaria.sunset', (data) => {
  ui.notifications.info('The sun sets!');
});

calendaria.midnight

Parameters: Same as calendaria.sunrise

Hooks.on('calendaria.midnight', (data) => {
  console.log('Midnight');
});

calendaria.midday

Parameters: Same as calendaria.sunrise

Hooks.on('calendaria.midday', (data) => {
  console.log('Noon');
});

---

Moon Hooks

calendaria.moonPhaseChange

Fired when any moon’s phase changes.

Parameters:

• data (object)
  • moons (array) - Array of changed moon data
    • moonIndex (number) - Index of the moon
    • moonName (string) - Localized moon name
    • previousPhaseIndex (number) - Previous phase index
    • previousPhaseName (string|null) - Previous phase name
    • currentPhaseIndex (number) - Current phase index
    • currentPhaseName (string|null) - Current phase name
  • calendar (CalendariaCalendar) - Active calendar
  • worldTime (number) - World time in seconds

Hooks.on('calendaria.moonPhaseChange', (data) => {
  for (const moon of data.moons) {
    console.log(`${moon.moonName}: ${moon.currentPhaseName}`);
  }
});

---

Rest Day Hooks

calendaria.restDayChange

Fired when transitioning to or from a rest day.

Parameters:

• data (object)
  • isRestDay (boolean) - Current rest day status
  • wasRestDay (boolean) - Previous rest day status
  • weekday (object|null) - Weekday info (index, name, abbreviation)
  • worldTime (number) - World time in seconds
  • calendar (CalendariaCalendar) - Active calendar

Hooks.on('calendaria.restDayChange', (data) => {
  if (data.isRestDay) console.log('Rest day begins');
});

---

Clock Hooks

calendaria.clockStartStop

Fired when the real-time clock starts or stops.

Parameters:

• data (object)
  • running (boolean) - Whether clock is running
  • locked (boolean) - Whether the clock is locked
  • increment (number) - Time increment in seconds

Hooks.on('calendaria.clockStartStop', (data) => {
  console.log(data.running ? 'Clock started' : 'Clock stopped');
});

calendaria.clockUpdate

Fired when clock state is updated from another client. Used to sync real-time clock state across all connected clients.

Parameters:

• data (object)
  • running (boolean) - Whether clock is running
  • ratio (number) - Real-time to game-time ratio

Hooks.on('calendaria.clockUpdate', (data) => {
  console.log(`Remote clock sync: running=${data.running}, ratio=${data.ratio}`);
});

calendaria.visualTick

Fired on each real-time clock render frame. Used internally by HUD, BigCal, MiniCal, Time Keeper, and Stop Watch for smooth time display updates.

Parameters:

• data (object)
  • predictedWorldTime (number) - Predicted world time in seconds (may be ahead of actual game.time.worldTime due to interpolation)

Hooks.on('calendaria.visualTick', (data) => {
  console.log(`Predicted time: ${data.predictedWorldTime}`);
});

calendaria.worldTimeUpdated

Fired when the Foundry updateWorldTime hook fires. Provides the raw world time and delta.

Parameters:

• worldTime (number) - Current world time in seconds
• dt (number) - Time delta in seconds

Hooks.on('calendaria.worldTimeUpdated', (worldTime, dt) => {
  console.log(`World time: ${worldTime}, delta: ${dt}`);
});

---

Stop Watch Hooks

calendaria.stopwatchStart

Fired when the stop watch starts.

Parameters:

• data (object)
  • mode (string) - Stop watch mode ("realtime" or "gametime")

Hooks.on('calendaria.stopwatchStart', (data) => {
  console.log(`Stopwatch started in ${data.mode} mode`);
});

calendaria.stopwatchPause

Fired when the stop watch is paused.

Parameters:

• data (object)
  • mode (string) - Stop watch mode
  • elapsed (number) - Elapsed time in milliseconds (realtime) or seconds (gametime)

Hooks.on('calendaria.stopwatchPause', (data) => {
  console.log(`Paused at ${data.elapsed}`);
});

calendaria.stopwatchReset

Fired when the stop watch is reset.

Parameters:

• data (object)
  • mode (string) - Stop watch mode

Hooks.on('calendaria.stopwatchReset', (data) => {
  console.log(`Stopwatch reset (${data.mode})`);
});

calendaria.stopwatchLap

Fired when a lap is recorded.

Parameters:

• data (object)
  • mode (string) - Stop watch mode
  • lap (number) - Lap number
  • elapsed (number) - Elapsed time at lap

Hooks.on('calendaria.stopwatchLap', (data) => {
  console.log(`Lap ${data.lap}: ${data.elapsed}`);
});

---

Note Hooks

calendaria.noteCreated

Fired when a calendar note is created.

Parameters:

• stub (object) - Note stub with id, name, flagData

Hooks.on('calendaria.noteCreated', (stub) => {
  console.log(`Created: ${stub.name}`);
});

calendaria.noteUpdated

Fired when a calendar note is modified.

Parameters:

• stub (object) - Note stub with id, name, flagData

Hooks.on('calendaria.noteUpdated', (stub) => {
  console.log(`Updated: ${stub.name}`);
});

calendaria.noteDeleted

Fired when a calendar note is deleted.

Parameters:

• pageId (string) - Journal page ID

Hooks.on('calendaria.noteDeleted', (pageId) => {
  console.log(`Deleted: ${pageId}`);
});

---

Event Hooks

calendaria.eventTriggered

Fired when a scheduled event or reminder occurs.

Parameters:

• data (object)
  • id (string) - Note/event ID
  • name (string) - Event name
  • flagData (object) - Event calendar data
  • currentDate (object) - Current date components (events only)
  • reminderType (string) - Reminder type (reminders only)
  • isReminder (boolean) - True if this is a reminder

Hooks.on('calendaria.eventTriggered', (data) => {
  console.log(`Event: ${data.name}`);
  if (data.isReminder) console.log('This is a reminder');
});

calendaria.eventDayChanged

Fired when a multi-day event progresses to a new day.

Parameters:

• data (object)
  • id (string) - Note ID
  • name (string) - Event name
  • progress (object) - Progress info (currentDay, totalDays, percentage, isFirstDay, isLastDay)

Hooks.on('calendaria.eventDayChanged', (data) => {
  console.log(`Day ${data.progress.currentDay} of ${data.progress.totalDays}`);
});

---

Reminder Hooks

calendaria.reminderReceived

Fired when a reminder notification is received from another client. Used internally by ReminderScheduler to display notifications, but also available for module integration.

Parameters:

• data (object)
  • type (string) - Reminder type ("toast" or "dialog")
  • noteId (string) - Journal page ID
  • noteName (string) - Note name
  • journalId (string) - Parent journal entry ID
  • message (string) - Formatted reminder message
  • icon (string|null) - Icon identifier
  • iconType (string|null) - Icon type ("fontawesome", "image", etc.)
  • color (string|null) - Icon color
  • targets (string[]) - Array of user IDs who should receive the reminder

Hooks.on('calendaria.reminderReceived', (data) => {
  if (data.targets.includes(game.user.id)) {
    console.log(`Reminder: ${data.noteName}`);
  }
});

---

Condition Hooks

calendaria.conditionEvaluated

Fired after a note’s condition tree is evaluated via the API.

Parameters:

• data (object)
  • noteId (string) - Note ID
  • result (boolean) - Evaluation result
  • date (object) - Date the condition was evaluated against

Hooks.on('calendaria.conditionEvaluated', (data) => {
  console.log(`Note ${data.noteId} evaluated: ${data.result}`);
});

calendaria.presetsChanged

Fired when note presets (categories) are added, removed, or modified.

Parameters:

• presets (object[]) - Updated array of all presets

Hooks.on('calendaria.presetsChanged', (presets) => {
  console.log(`Presets updated: ${presets.length} total`);
});

---

Fog of War Hooks

calendaria.fogRangeChanged

Fired when the GM reveals or resets fog of war date ranges.

Parameters:

• data (object)
  • ranges (object[]) - Updated array of revealed date ranges

Hooks.on('calendaria.fogRangeChanged', (data) => {
  console.log(`Fog ranges updated: ${data.ranges.length} ranges`);
});

---

Cinematic Hooks

calendaria.cinematicStart

Fired when a cinematic time skip begins.

Parameters:

• data (object) - Cinematic payload

Hooks.on('calendaria.cinematicStart', (data) => {
  console.log('Cinematic started');
});

calendaria.cinematicEnd

Fired when a cinematic time skip completes.

Parameters:

• data (object) - Cinematic payload

Hooks.on('calendaria.cinematicEnd', (data) => {
  console.log('Cinematic ended');
});

calendaria.cinematicAbort

Fired when a cinematic time skip is aborted by the user.

Parameters:

• data (object) - Cinematic payload

Hooks.on('calendaria.cinematicAbort', (data) => {
  console.log('Cinematic aborted');
});

---

Weather Hooks

calendaria.weatherChange

Fired when weather changes. Note: This hook is fired with varying payloads depending on the source.

Parameters:

• data (object|undefined) - May be undefined when triggered from UI picker
  • previous (object|null) - Previous weather state
  • current (object|null) - Current weather state
  • zoneId (string|undefined) - Climate zone ID for the change
  • remote (boolean) - True if change originated from another client (optional)
  • visualOnly (boolean) - True when fired from Weather Editor preview (FX and sound handlers should skip processing)
  • bulk (boolean) - True when the change affects all zones at once (e.g., day change, regeneration, active zone switch, intraday period change, initial generation, time-jump backfill). When bulk is true, previous, current, and zoneId are not provided — listeners should re-read weather state from the API

Hooks.on('calendaria.weatherChange', (data) => {
  if (data?.current) {
    console.log(`Weather: ${data.current.id}`);
  }
});

calendaria.weatherPeriodChange

Fired when the intraday weather period changes (sunrise, midday, sunset, midnight thresholds).

Parameters:

• data (object)
  • period (string) - The period that just started ("night", "morning", "afternoon", "evening")

Hooks.on('calendaria.weatherPeriodChange', (data) => {
  console.log(`Weather period: ${data.period}`);
});

---

Import Hooks

calendaria.importStarted

Fired when a calendar import begins.

Parameters:

• data (object)
  • importerId (string) - Importer ID
  • calendarId (string) - Target calendar ID

Hooks.on('calendaria.importStarted', (data) => {
  console.log(`Importing via ${data.importerId}`);
});

calendaria.importComplete

Fired when import finishes successfully.

Parameters:

• data (object)
  • importerId (string) - Importer ID
  • calendarId (string) - Created calendar ID
  • calendar (CalendariaCalendar) - Imported calendar

Hooks.on('calendaria.importComplete', (data) => {
  console.log(`Imported: ${data.calendarId}`);
});

calendaria.importFailed

Fired when import fails.

Parameters:

• data (object)
  • importerId (string) - Importer ID
  • calendarId (string) - Target calendar ID
  • error (string) - Error message

Hooks.on('calendaria.importFailed', (data) => {
  console.error(`Import failed: ${data.error}`);
});

---

Display Hooks

calendaria.displayFormatsChanged

Fired when display format settings are saved.

Parameters:

• newFormats (object) - Updated display format configuration

Hooks.on('calendaria.displayFormatsChanged', (newFormats) => {
  console.log('Display formats updated');
});

---

Widget Hooks

calendaria.widgetRegistered

Fired when a widget is registered via the Widget API.

Parameters:

• fullId (string) - Full widget ID (moduleId.widgetId)
• config (object) - Widget configuration

Hooks.on('calendaria.widgetRegistered', (fullId, config) => {
  console.log(`Widget registered: ${fullId}`);
});

calendaria.widgetsRefresh

Fired when widgets are refreshed (re-rendered).

Parameters: None

Hooks.on('calendaria.widgetsRefresh', () => {
  console.log('Widgets refreshed');
});