Simple Timekeeping

Free

Version: V13

FVTT: V13

Any System

Changelog

A simple and unobtrusive way to keep track of time. Simple Timekeeping docks on top of the screen to always have a reminder of essential date, time and weather information you can change with a click. Syncs with the core Foundry calendar API.

If you are looking for premade calendars, click Here

Introduction

Simple Timekeeping is a lightweight module designed to help Game Masters manage time, weather, and events in their campaigns. It offers an intuitive interface with minimal setup while providing a rich set of features to enhance immersion and storytelling. The module is designed with a philosophy of "simple yet powerful" - offering complex functionality without a steep learning curve. It works with any game system and can be used alongside other Foundry modules.

Interface Overview

The Simple Timekeeping interface consists of several components:

Top Bar Controls

Time Display: Shows the current day and time
Navigation Controls: Buttons to move backward/forward in time
Preset Time Buttons: Quick access to sunrise, sunset, midday, midnight
Weather Display: Shows current weather condition
Settings Button: Access to module configuration

Event Panel

Event List: Displays upcoming and past events
Search Bar: Filter events by name
Create Event Button: Add new events to the timeline

Configuration Panel

Tabs: Navigate between different configuration sections
Settings: Customize module behavior
Save Button: Apply configuration changes

Configuration

Time Management

Manual Time Control

The interface provides several ways to adjust the game time:

Hour Back/Forward: Move time backward/forward by one hour
Day Back/Forward: Move time backward/forward by one day
Preset Times: Jump to specific times of day:
- Sunrise: Beginning of daylight
- Midday: Peak daylight
- Sunset: Beginning of darkness
- Midnight: Peak darkness

Combat Integration

The module automatically tracks time during combat:

Each combat round advances time by the configured "Seconds per Round" value

Real-time Progression

You can enable automatic time progression:

Game time advances based on "Seconds per Real Second" setting
For example, setting this to 60 would mean 1 minute of game time passes every real second

Weather Badge

Simple Timekeeping includes some weather presets for you that also set the matching (or closest) weather effect on the current scene. Click on the weather badge to chose from presets or set something custom in the configuration menu.

Event Management

Events in Simple Timekeeping allow you to track important campaign moments and schedule future occurrences.

Creating Events

Click the "Create Event" button
Fill in the event details:
- Event Name: Brief descriptive title
- Event Start: Date and time when event begins
- Event End: (Optional) Date and time when event ends
- Repeat: Frequency of recurrence (None, Daily, Weekly, Monthly, Yearly)

Managing Events

Search: Filter events by name using the search bar
Edit: Right Click on an event to access it's context menu

Event Display

Events are displayed in the event list, ordered by date. Current and upcoming events are highlighted for easy reference.

Badge System

Badges provide visual indicators for tracking various campaign elements.

Custom Badge Configuration

You can configure up to four custom badges:

Navigate to module settings
Under "Custom Badge 1-4":
- Set the label text
- Choose a color (hex code)

Badge Usage Examples

Moon Phases: Track lunar cycles
Seasons: Indicate current season
Campaign Day: Track days since campaign start
Faction Status: Monitor allegiances
Holiday: Mark special dates

Scene Integration

Darkness Synchronization

The module can automatically adjust scene darkness based on time of day.

Troubleshooting

Module Not Visible

The module is not visible during combat. Make sure you don't have an ongoing combat.

API

All methods can be accessed from ui.simpleTimekeeping

Badge Management APIs

These functions provide programmatic control over the visual badge elements in the SimpleTimekeeping interface, allowing developers to dynamically update weather and moon phase displays.

`setWeatherBadge(label, color, weatherEffect)`

Updates the weather badge display and optionally applies weather effects to the current scene.

Parameters:

label (string) - The text to display on the weather badge. Will be localized using the module's localization system
color (string) - CSS color value for the badge background (hex, rgb, named colors, etc.)
weatherEffect (string, optional) - Weather effect to apply to the scene. Pass "none" to clear existing effects

Behavior:

Saves the weather label and color to persistent module settings
If weatherEffect is provided, updates the current scene's weather property
Passing "none" as weatherEffect will clear any existing weather effects by setting an empty string
The badge visibility is controlled by whether a label is set - empty labels hide the badge

Usage Examples:

// Set a storm weather badge with scene effects
await ui.simpleTimekeeping.setWeatherBadge("Heavy Rain", "#4a90e2", "rain");
 
// Update just the visual badge without scene effects
await ui.simpleTimekeeping.setWeatherBadge("Partly Cloudy", "#87ceeb");
 
// Clear weather effects but keep the badge
await ui.simpleTimekeeping.setWeatherBadge("Clear Skies", "#87ceeb", "none");

`setMoonBadge(label, color)`

Updates the moon phase badge display with custom text and styling.

Parameters:

label (string) - The text to display on the moon badge. Will be localized using the module's localization system
color (string, optional) - CSS color value for the badge background. If not provided, retains the current color setting

Behavior:

Saves the moon label and optionally the color to persistent module settings
If color is omitted or null, the existing color configuration is preserved
The badge visibility is controlled by whether a label is set - empty labels hide the badge
Will not work if the automatic moon phase calculation system is enabled

Usage Examples:

// Set a custom moon phase with new color
await ui.simpleTimekeeping.setMoonBadge("Waning Crescent", "#c0c0c0");
 
// Update only the text, keeping existing color
await ui.simpleTimekeeping.setMoonBadge("Full Moon");
 
// Clear the moon badge
await ui.simpleTimekeeping.setMoonBadge("");

`setCustomBadge(id, label, color)`

Updates a specified custom badge with new text and/or background color.

Parameters:

id (number) – The badge index to update, starting at 1. Must be within the range 1 to 3.
label (string, optional) – The text to display on the badge. Will be stored exactly as provided (no localization applied unless handled elsewhere).
color (string, optional) – CSS color value for the badge background. If omitted, the existing badge color remains unchanged.

Behavior:

Validates that id is within the allowed badge range; otherwise, displays an error notification and stops.
Updates the stored configuration for the selected badge’s label and/or color.
If label is undefined, the badge label is not modified.
If color is undefined, the badge color is not modified.
Changes are saved persistently via the module’s configuration settings.

Usage Examples:

// Set badge #2 with new text and background color
await ui.simpleTimekeeping.setCustomBadge(2, "Event Day", "#ff9900");
 
// Update only the label of badge #1, keeping its current color
await ui.simpleTimekeeping.setCustomBadge(1, "Holiday");
 
// Change only the color of badge #3
await ui.simpleTimekeeping.setCustomBadge(3, undefined, "#00ffcc");
 
// Attempting to set an out-of-range badge index
await ui.simpleTimekeeping.setCustomBadge(999, "Invalid"); // Displays error

`getCustomBadge(id)`

Retrieves the label, color, and index of a specified custom badge.

Parameters:

id (number) – The badge index to retrieve, starting at 1. Must be within the range 1 to BADGE_COUNT.

Returns:

object – An object containing:
- label (string) – The badge’s label text, or an empty string if unset.
- color (string) – The badge’s background color as a CSS color string. Defaults to "#ffffff" if unset.
- index (number) – The zero-based badge index (e.g., badge 1 returns index: 0).

Behavior:

Validates that id is within the valid badge range; otherwise, displays an error notification and returns nothing.
Reads the badge’s configuration from persistent module settings.
Returns a structured object with label, color, and zero-based index.

Usage Examples:

// Get information for badge #1
const badge1 = ui.simpleTimekeeping.getCustomBadge(1);
// badge1 = { label: "Event Day", color: "#ff9900", index: 0 }
 
// Get information for badge #3
const badge3 = ui.simpleTimekeeping.getCustomBadge(3);
 
// Attempting to get an out-of-range badge
ui.simpleTimekeeping.getCustomBadge(999); // Displays error

`game.time.advance(delta, options)`

Advances or rewinds the world time by a specified amount, in either seconds or time components.

Parameters:

delta (number | TimeComponents) – The amount of time to adjust the world clock:
- If a number, represents the number of seconds to advance (negative values rewind time).
- If a TimeComponents object, it will be converted to seconds via the game’s calendar system.
options (object, optional) – Additional options passed directly to game.settings.set when updating time.

Returns:

Promise<number> – The new absolute world time, in seconds.

Behavior:

Converts delta to a total number of seconds if provided as a TimeComponents object.
Retrieves the current worldTime from the game state.
Updates the "core.time" setting by adding the delta (seconds) to the current time.
Returns the updated world time value.
Accepts both forward (positive) and backward (negative) time adjustments.

Usage Examples:

// Advance the world clock by 1 hour (3600 seconds)
await game.time.advance(3600);
 
// Rewind the world clock by 5 minutes
await game.time.advance(-300);
 
// Advance by a structured time components object
await game.time.advance({ days: 0, hours: 2, minutes: 15 });

Custom Climate Data

If you wish you could customize the weather generation starting from this sample template. No support is provided for custom climate data. default is used whenever a matching season or climate is not found.

Valid weather options are clear partlyCloudy cloudy overcast rain thunderstorm drizzle snow blizzard hail fog mist windy tornado hurricane ashfall sandstorm luminousSky bloodRain manaStorm arcaneFog voidstorm celestialEclipse meteorShower frozenHell sunshower spectralStorm etherealDrizzle wildMagicWinds

Note that seasons are determined independently from how they are setup in the calendar and are based of percentages of days of the year following standard northern emisphere seasons.

Copy paste the following and change the values as your prefer.

{
  "default": {
    "temperature": {
      "spring": {
        "min": 10,
        "max": 18
      },
      "summer": {
        "min": 18,
        "max": 30
      },
      "autumn": {
        "min": 8,
        "max": 16
      },
      "winter": {
        "min": -5,
        "max": 5
      },
      "default": {
        "min": 8,
        "max": 20
      }
    },
    "weather": {
      "spring": {
        "clear": 5,
        "rain": 4,
        "cloudy": 3,
        "mist": 2
      },
      "summer": {
        "clear": 6,
        "partlyCloudy": 4,
        "thunderstorm": 2
      },
      "autumn": {
        "rain": 4,
        "cloudy": 4,
        "windy": 2
      },
      "winter": {
        "snow": 5,
        "blizzard": 3,
        "fog": 2
      },
      "default": {
        "rain": 3,
        "cloudy": 3,
        "mist": 2,
        "drizzle": 2
      }
    }
  }
}

AI Calendar Generator

If you wish, you can use this AI Foundry calendar generator created by @Phenomen here (opens in a new tab).

Custom Calendar

Simple Timekeeping utilizes the core Foundry API for the calendar, if you want to have specifics beyond the examples below, visit the FVTT API Reference (opens in a new tab)

Custom Simple Timekeeping values

Simple Timekeeping will read some additional values from the configuration. You can check the Harptos configuration for the most complete example.

Dusk\Dawn

Months support dusk and dawn properties, ranging from 0 to 1, where in a 24hrs day 0.25 is 06:00, 0.5 is 12:00 and 1 is 24:00. Scale it accordingly for non-24hrs calendars.

      { "name": "Hammer", "abbreviation": "Ham", "ordinal": 1, "days": 31, "dawn": 0.33, "dusk": 0.69 }

Moons

The moons key can hold data regarding moons (or planets) and will be used to dynamically update the moon badge. Phase names must be in order starting from new moon. The moon cycle is fixed and starts at time 0, if you need to offset it, use the offset property. Both cycle and offset are in days.

{
  "moons": {
    "values": [
      {
        "name": "Selûne",
        "cycleLength": 30,
        "phaseNames": [
          "New Moon",
          "Waxing Crescent",
          "First Quarter",
          "Waxing Gibbous",
          "Full Moon",
          "Waning Gibbous",
          "Last Quarter",
          "Waning Crescent"
        ],
        "offset": 0
      }
    ]
  }
}

Custom moons setting

The custom moons setting allows to define a JSON that overrides the moons defined in the calendar, it just needs the values of the moons and not the full moon object

[
  {
    "name": "Selûne",
    "cycleLength": 30,
    "offset": 0
  }
]

In this example, the phase names are also omitted, if you omit the phase names, the default ones for the earth moon will be used.

Sample Calendars

These examples are already included in the module but here they are provided in JSON format for easy reference or customization. You can also view the currently active calendar JSON while in-game by using the console command CONFIG.time.worldCalendarConfig.

Harptos Calendar (Forgotten Realms)

{
    "name": "Harptos (Forgotten Realms)",
    "id": "harptos",
    "system": "dnd5e",
    "description": "The standard calendar of the Forgotten Realms, consisting of twelve 30-day months punctuated by five annual festival days.",
    "years": {
        "yearZero": 0,
        "firstWeekday": 0,
        "leapYear": {
            "leapStart": 4,
            "leapInterval": 4
        }
    },
    "months": {
        "values": [
            {
                "name": "Hammer",
                "abbreviation": "Ham",
                "ordinal": 1,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Midwinter",
                "abbreviation": "Mid",
                "ordinal": 1,
                "days": 1,
                "startingWeekday": 0,
                "intercalary": true
            },
            {
                "name": "Alturiak",
                "abbreviation": "Alt",
                "ordinal": 2,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Ches",
                "abbreviation": "Che",
                "ordinal": 3,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Tarsakh",
                "abbreviation": "Tar",
                "ordinal": 4,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Greengrass",
                "abbreviation": "Gre",
                "ordinal": 4,
                "days": 1,
                "intercalary": true,
                "startingWeekday": 0
            },
            {
                "name": "Mirtul",
                "abbreviation": "Mir",
                "ordinal": 5,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Kythorn",
                "abbreviation": "Kyt",
                "ordinal": 6,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Flamerule",
                "abbreviation": "Fla",
                "ordinal": 7,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Midsummer",
                "abbreviation": "Mid",
                "ordinal": 7,
                "days": 1,
                "intercalary": true,
                "startingWeekday": 0
            },
            {
                "name": "Shieldmeet",
                "abbreviation": "Shi",
                "ordinal": 7,
                "days": 0,
                "leapDays": 1,
                "intercalary": true,
                "startingWeekday": 0
            },
            {
                "name": "Eleasis",
                "abbreviation": "Ele",
                "ordinal": 8,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Eleint",
                "abbreviation": "El",
                "ordinal": 9,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Highharvestide",
                "abbreviation": "Hig",
                "ordinal": 9,
                "days": 1,
                "intercalary": true,
                "startingWeekday": 0
            },
            {
                "name": "Marpenoth",
                "abbreviation": "Mar",
                "ordinal": 10,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Uktar",
                "abbreviation": "Ukt",
                "ordinal": 11,
                "days": 30,
                "startingWeekday": 0
            },
            {
                "name": "Feast of the Moon",
                "abbreviation": "Fes",
                "ordinal": 11,
                "days": 1,
                "intercalary": true,
                "startingWeekday": 0
            },
            {
                "name": "Nightal",
                "abbreviation": "Nig",
                "ordinal": 12,
                "days": 30,
                "startingWeekday": 0
            }
        ]
    },
    "days": {
        "values": [
            {
                "name": "First-day",
                "abbreviation": "1D",
                "ordinal": 1
            },
            {
                "name": "Second-day",
                "abbreviation": "2D",
                "ordinal": 2
            },
            {
                "name": "Third-day",
                "abbreviation": "3D",
                "ordinal": 3
            },
            {
                "name": "Fourth-day",
                "abbreviation": "4D",
                "ordinal": 4
            },
            {
                "name": "Fifth-day",
                "abbreviation": "5D",
                "ordinal": 5
            },
            {
                "name": "Sixth-day",
                "abbreviation": "6D",
                "ordinal": 6
            },
            {
                "name": "Seventh-day",
                "abbreviation": "7D",
                "ordinal": 7,
                "isRestDay": true
            }
        ],
        "daysPerYear": 365,
        "hoursPerDay": 24,
        "minutesPerHour": 60,
        "secondsPerMinute": 60
    },
    "seasons": {
        "values": [
            {
                "name": "Spring",
                "monthStart": 3,
                "monthEnd": 6,
                "dayStart": 78,
                "dayEnd": 171
            },
            {
                "name": "Summer",
                "monthStart": 6,
                "monthEnd": 9,
                "dayStart": 171,
                "dayEnd": 264
            },
            {
                "name": "Autumn",
                "monthStart": 9,
                "monthEnd": 12,
                "dayStart": 264,
                "dayEnd": 354
            },
            {
                "name": "Winter",
                "monthStart": 12,
                "monthEnd": 3,
                "dayStart": 354,
                "dayEnd": 78
            }
        ]
    },
    "moons": {
        "values": [
            {
                "name": "Selûne",
                "cycleLength": 30,
                "offset": 0
            }
        ]
    }
}

Gregorian Simplified

This calendar uses the built in localization keys for the gregorian calendar instead of using the straight up localized names.

{
    "name": "Simplified Gregorian",
    "id": "gregorian",
    "description": "The Gregorian calendar with some simplifications regarding leap years or seasonal timing.",
    "years": {
        "yearZero": 0,
        "firstWeekday": 0,
        "leapYear": {
            "leapStart": 8,
            "leapInterval": 4
        }
    },
    "months": {
        "values": [
            {
                "name": "CALENDAR.GREGORIAN.January",
                "abbreviation": "CALENDAR.GREGORIAN.JanuaryAbbr",
                "ordinal": 1,
                "days": 31
            },
            {
                "name": "CALENDAR.GREGORIAN.February",
                "abbreviation": "CALENDAR.GREGORIAN.FebruaryAbbr",
                "ordinal": 2,
                "days": 28,
                "leapDays": 29
            },
            {
                "name": "CALENDAR.GREGORIAN.March",
                "abbreviation": "CALENDAR.GREGORIAN.MarchAbbr",
                "ordinal": 3,
                "days": 31
            },
            {
                "name": "CALENDAR.GREGORIAN.April",
                "abbreviation": "CALENDAR.GREGORIAN.AprilAbbr",
                "ordinal": 4,
                "days": 30
            },
            {
                "name": "CALENDAR.GREGORIAN.May",
                "abbreviation": "CALENDAR.GREGORIAN.MayAbbr",
                "ordinal": 5,
                "days": 31
            },
            {
                "name": "CALENDAR.GREGORIAN.June",
                "abbreviation": "CALENDAR.GREGORIAN.JuneAbbr",
                "ordinal": 6,
                "days": 30
            },
            {
                "name": "CALENDAR.GREGORIAN.July",
                "abbreviation": "CALENDAR.GREGORIAN.JulyAbbr",
                "ordinal": 7,
                "days": 31
            },
            {
                "name": "CALENDAR.GREGORIAN.August",
                "abbreviation": "CALENDAR.GREGORIAN.AugustAbbr",
                "ordinal": 8,
                "days": 31
            },
            {
                "name": "CALENDAR.GREGORIAN.September",
                "abbreviation": "CALENDAR.GREGORIAN.SeptemberAbbr",
                "ordinal": 9,
                "days": 30
            },
            {
                "name": "CALENDAR.GREGORIAN.October",
                "abbreviation": "CALENDAR.GREGORIAN.OctoberAbbr",
                "ordinal": 10,
                "days": 31
            },
            {
                "name": "CALENDAR.GREGORIAN.November",
                "abbreviation": "CALENDAR.GREGORIAN.NovemberAbbr",
                "ordinal": 11,
                "days": 30
            },
            {
                "name": "CALENDAR.GREGORIAN.December",
                "abbreviation": "CALENDAR.GREGORIAN.DecemberAbbr",
                "ordinal": 12,
                "days": 31
            }
        ]
    },
    "days": {
        "values": [
            {
                "name": "CALENDAR.GREGORIAN.Monday",
                "abbreviation": "CALENDAR.GREGORIAN.MondayAbbr",
                "ordinal": 1
            },
            {
                "name": "CALENDAR.GREGORIAN.Tuesday",
                "abbreviation": "CALENDAR.GREGORIAN.TuesdayAbbr",
                "ordinal": 2
            },
            {
                "name": "CALENDAR.GREGORIAN.Wednesday",
                "abbreviation": "CALENDAR.GREGORIAN.WednesdayAbbr",
                "ordinal": 3
            },
            {
                "name": "CALENDAR.GREGORIAN.Thursday",
                "abbreviation": "CALENDAR.GREGORIAN.ThursdayAbbr",
                "ordinal": 4
            },
            {
                "name": "CALENDAR.GREGORIAN.Friday",
                "abbreviation": "CALENDAR.GREGORIAN.FridayAbbr",
                "ordinal": 5
            },
            {
                "name": "CALENDAR.GREGORIAN.Saturday",
                "abbreviation": "CALENDAR.GREGORIAN.SaturdayAbbr",
                "ordinal": 6,
                "isRestDay": true
            },
            {
                "name": "CALENDAR.GREGORIAN.Sunday",
                "abbreviation": "CALENDAR.GREGORIAN.SundayAbbr",
                "ordinal": 7,
                "isRestDay": true
            }
        ],
        "daysPerYear": 365,
        "hoursPerDay": 24,
        "minutesPerHour": 60,
        "secondsPerMinute": 60
    },
    "seasons": {
        "values": [
            {
                "name": "CALENDAR.GREGORIAN.Spring",
                "monthStart": 3,
                "monthEnd": 5
            },
            {
                "name": "CALENDAR.GREGORIAN.Summer",
                "monthStart": 6,
                "monthEnd": 8
            },
            {
                "name": "CALENDAR.GREGORIAN.Fall",
                "monthStart": 9,
                "monthEnd": 11
            },
            {
                "name": "CALENDAR.GREGORIAN.Winter",
                "monthStart": 12,
                "monthEnd": 2
            }
        ]
    },
    "moons": {
        "values": [
            {
                "name": "Moon",
                "cycleLength": 30,
                "offset": 0
            }
        ]
    }
}

Simple Quest Situational Shortcuts