Simple Timekeeping & Calendar

Keep track of time, weather, moons and events in your world. A small bar at the top of the screen always shows the date, the time and the weather, and a full calendar lets you plan events and write notes for any day. Works with any game system and uses the Foundry calendar, so other modules see the same date.

Looking for ready-made calendars? See Choosing a Calendar.

Getting Started

First Time Setup

The first time you load a world with the module, the GM sees the First Time Setup window:

• Calendar: the calendar of your world, for example Harptos for the Forgotten Realms
• Climate Zone: the climate used to create the weather and the dawn and dusk times
• Sync Scene Darkness and Weather: make scenes darker at night and show the current weather on them
• Generate Weather: pick a new weather every day, with or without the temperature
• Moon Phase Automation: show the current moon phase automatically
• Hide During Combat: hide the bar while a combat is running

You can change all of these later from the Configuration.

The Top Bar

Top Bar

The bar sits at the top of the screen for everyone.

Moving Time (GM only)

• Back / Forward one Day (double arrows) and Back / Forward one Hour (single arrows)
  • Hold Ctrl for 1 week / 30 minutes, Shift for 3 days / 10 minutes, Alt for 2 days / 5 minutes
• Sunrise, Midday, Sunset, Midnight: jump to that time of day
• Click the time to pause or resume the clock. The clock also stops while the game is paused or a combat is running

When the clock runs, game time moves on by itself (10 game seconds for every real second by default) and every combat round advances time by 6 seconds. Both values are in the Time tab of the Configuration.

Other Buttons

• Events (calendar icon, left): show the list of events
• Open Calendar (right): open the Calendar View
• Configure (gear, GM only): open the Configuration

Players only see the Events and Open Calendar buttons.

Badges

• Custom Badges (first on the left): up to 3 labels for anything you want to track, like travel days or the current quest. Click to edit the text and color. Shift + Click adds 1 to the last number in the text, Shift + Right Click removes 1. Badges with no text are hidden
• Date: the full date, colored by season
• Time: changes color from day to night. Hover it to see the full date and season
• Moon: the current moon phase. If the calendar has no moons, or automation is off, click it to pick a phase
• Weather: click it to pick a weather or Generate a random one

Weather Menu

Picking a weather also shows the matching weather effect on your scenes (rain, snow, fog...), if scene sync is on.

Events

Events

Events are things that happen on a specific date: a festival, a deadline, a meeting. Click the Events button on the top bar to see the upcoming ones, with how many days are left. Use the search bar to find an event by name.

Every event is a page in the SimpleTimekeeping journal, so you can write anything you want in it. Click an event to open its page.

Creating an Event

Event Dialog

Click the + button next to the search bar, or click a day in the Calendar View and choose Create Event on This Day.

• Event Start and Event End (optional): click the calendar button to pick the date and time
• Repeat: every day, week, month or year
• All Day: the event lasts the whole day, no time needed
• Color: the color of the event in the Calendar View
• Notification: whisper a chat message to the players when the event starts

Date Picker

Managing Events

Right Click an event to Edit its page, change its date with Edit Event Date/Time, Duplicate, Delete it, or set who can see it with Configure Ownership.

Players see the events they have at least Limited permission on. You can also change the date of an event from its journal page, with the calendar button in the window header.

Calendar View

Calendar View

Click Open Calendar on the top bar to see a whole month at once.

• Move between months and years with the arrows or the dropdowns, and click Today to come back to the current day. The current day has a highlighted border
• Each day shows the moon phase and its events. Click an event to open it
• The colored badge next to the year is the current season

Notes

Write notes for a year, a month, a season or a single day: world events, prices, rumors, reminders. Click + Year Note, + Month Note or + Season Note above the calendar to create one. Notes are shown at the top of the calendar when you look at that month, and days with a note get a small note icon.

Notes are journal pages too, so you choose which players can see them.

Day Menu

Day Menu

Click a day to:

• Create Event on This Day
• Set Current Date to This Day (GM only): jump to that day, keeping the current time
• Add Day Note or Open Day Note
• Set Moon Phase on This Day (GM only, custom calendars): force a phase, for example an eclipse. See Moons

Choosing a Calendar

Calendar Tab

Pick the calendar in the Calendar tab of the Configuration. Simple Timekeeping includes:

• Gregorian (our real-world calendar, simplified)
• Harptos (Forgotten Realms), Barovian (Curse of Strahd), Galifar (Eberron), Golarion (Pathfinder), Thyatian (Mystara), Common Year (Greyhawk), Athasian (Dark Sun)
• Dragonlance (Solamnia and Elves), Cerilian Reckoning (Birthright), Exandrian (Exandria), Drakkenheim
• Imperial (Warhammer), Forbidden Lands
• System Default: the calendar of your game system

If your world needs something else, make your own with the Calendar Editor.

Calendar Editor

Calendar Editor

Open it from Configuration → Calendar tab → Open Calendar Editor.

1. Click + to create a new calendar. It starts as a copy of the calendar you are using now
2. Change what you need in the tabs below
3. Click Save and Set Active to save it and start using it, or Save Calendar to only save it

The buttons at the top let you pick which custom calendar to edit, delete it, and import or export it as a file, to share it or use it in another world.

• General: name, description, hours in a day, leap years
• Weekdays: the names of the days of the week
• Months: the months and how many days they have
• Seasons: when each season starts and ends
• Moons: your moons and their phases
• Biome: the weather and temperatures of your world

To start from another calendar instead, choose it in Copy from Calendar (General tab) and click Import. See Calendar Editor Details for every field.

Weather and Scenes

Environment Tab

• Climate Zone (Environment tab): from Equatorial to Boreal. It decides the weather, the temperatures and how long the days are during the year
• Generate Weather (Automation tab): pick a new weather every day, optionally with the temperature in Celsius or Fahrenheit
• Sync Scene Darkness and Weather (Automation tab): scenes get darker at night with a day/night tint, and show the weather effect

Scene Setting

Each scene can override the sync setting at the bottom of the Environment tab of its configuration, for example to keep a dungeon dark at noon.

For weather made just for your world, use the Biome of a custom calendar.

Configuration

Automation Tab

Click the gear on the top bar, or Module Settings → Configure.

• Badges: text and color of the weather, moon and custom badges, show the full date, and how to show the day number (none, days since the start of the calendar, or day of the year)
• Aspect: season colors, 24 hour clock, font and spacing, plain style, full width, hide during combat, distance from the top of the screen
• Time: game seconds for every real second, seconds per combat round, how often the clock updates
• Environment: day and night tint, dawn and dusk time, Climate Zone, Dawn/Dusk Source
• Calendar: events journal name, hide expired events, event notifications, the calendar and the Calendar Editor
• Automation: scene sync, moon phase automation, weather generation, and macros that run at the start of a new day, at dawn, at dusk and at midday

Click Set current Date/Time at the bottom to jump to any date.

Troubleshooting

• The bar is not visible: Hide During Combat is on and a combat is running
• Time is not moving: the clock is paused (click the time on the bar), the game is paused, or a combat is running
• A custom calendar shows an error: open the Calendar Editor, fix the field it complains about and save again

Advanced

Calendar Editor Details

Months Tab

General

• Hours per Day, Minutes per Hour, Seconds per Minute
• Days per Year: calculated from the months
• Year Zero: the year shown when the world time is 0
• First Weekday: the weekday of the first day of year zero
• Leap Years: enable them, then set the First Leap Year and the Leap Year Interval (for example every 4 years)

Months

• Days and Leap Days: days in a normal year and in a leap year. Leave Leap Days empty to use the normal value. A month with 0 days and 1 leap day only exists in leap years, like Shieldmeet
• Intercalary: festival days outside the normal weeks and month numbering, like Midwinter in Harptos
• Dawn and Dusk: optional, see Dawn and Dusk

Seasons

Each season goes from a Start Month to an End Month. For seasons that don't line up with months, set Start Day and End Day as a day of the year, counting from 0.

Moons

Moons Tab

A calendar can have any number of moons.

• Phases: each phase lasts the given number of days. The full cycle is their sum. Use Standard Phases fills in the usual eight phases
• Icon: optional, an emoji or one of the moon icons from the dropdown
• Offset (days): moves the whole cycle forward, to line up a full moon with a specific date
• Color: tints the phase icons of this moon
• Erratic: every cycle lasts a random number of days between Min Days and Max Days (like Morrslieb in Warhammer). The dice button rerolls the random cycles

Set Moon Phase

Set Phase on Day forces a phase on a date, for example a blood moon on a festival. Set it in the Moons tab, or from the day menu of the Calendar View. It can repeat every year, month or week. Choose Use Cycle to remove it. Custom phases can have their own name and icon.

Biome

Biome Tab

The biome is the weather of a custom calendar. It is used when the Climate Zone in the Environment tab is set to Custom (Biome).

• Start From Climate Zone: load the values of a climate zone, then change them
• Daylight: Fixed Dawn/Dusk uses the dawn and dusk values you set, a climate zone calculates them from the day of the year
• Temperatures: minimum and maximum for each season. Empty seasons use the Default row
• Weather: the weathers that can happen in each season, with a Weight. Higher weights happen more often, the Chance column shows the result. Seasons with no weather use the Default list

Dawn and Dusk

Dawn and dusk are written as a fraction of the day, from 0 to 1. In a 24 hour day 0.25 is 06:00, 0.5 is 12:00 and 0.75 is 18:00.

They come from, in order:

1. The Dawn and Dusk of the current month in the calendar, if set. Set Dawn/Dusk Source to Use only Biome to ignore them
2. The Climate Zone or the Biome
3. The Dawn and Dusk settings in the Environment tab, when the Climate Zone is disabled

Event Links

Write @event[uuid] in any journal or chat message, where uuid is the UUID of an event page, to show a link with the event date. Hover it to see how long until it starts or ends.

@st-event[uuid] does the same, but is always handled by Simple Timekeeping. Use it if another module also uses @event: @event only turns into a link when the page is an event, and otherwise leaves the text to other modules. On a page that is not an event, @st-event shows a plain link without the date.

@event[JournalEntry.abc123.JournalEntryPage.def456]
@st-event[JournalEntry.abc123.JournalEntryPage.def456]

Macros and API

All methods are on ui.simpleTimekeeping.

// Weather badge: label, color, scene weather effect ("none" clears it), optional 3D Canvas particle preset
await ui.simpleTimekeeping.setWeatherBadge("Heavy Rain", "#4a90e2", "rain");
 
// Moon badge: label, optional color, optional tooltip. Only when Moon Phase Automation is off or the calendar has no moons
await ui.simpleTimekeeping.setMoonBadge("🌕 Full Moon", "#c0c0c0");
 
// Custom badges 1 to 3: label and/or color (undefined leaves it unchanged)
await ui.simpleTimekeeping.setCustomBadge(1, "Travel Day 4", "#e8a33d");
const badge = ui.simpleTimekeeping.getCustomBadge(1); // { label, color, index }
 
// Open the windows
ui.simpleTimekeeping.openCalendar();
ui.simpleTimekeeping.openCalendarEditor();
 
// Move time with the Foundry API: seconds, or time components
await game.time.advance(3600);
await game.time.advance({ hour: 2, minute: 15 });

The hook initSimpleTimekeeping is called with the SimpleTimekeeping class on ready.