Skip to main content
Version: 1.3.x

Simple Calendar API

There are the functions that other modules, systems and macros can access and what they can do. Most of these are for advanced interfacing with Simple Calendar and not something everyone needs to worry about.

Simple Calendar exposes a variable called SimpleCalendar, all of these API functions exist the property api on that variable SimpleCalendar.api

Properties​

Functions​

Types​

Properties

SimpleCalendar.api.Calendars​

This is an enum that contains a list of all available predefined calendars within Simple Calendar.

Important: This is a list of keys used internally to determine which Predefined calendar should be used it does not return an object containing the configuration for a predefined calendar.

SimpleCalendar.api.LeapYearRules​

This is an enum that contains the options for how leap years are calculated. Options are:

  • None: No leap year rules
  • Gregorian: Follow the Gregorian leap year rules
  • Custom: Set up custom leap year rules

SimpleCalendar.api.MoonIcons​

This is an enum that contains a list of all available icons for moon phases.

SimpleCalendar.api.MoonYearResetOptions​

This is an enum that contains the options for when a moons first new moon year should be reset. Options are:

  • None: The moons first new moon year is never reset.
  • Leap Year: The moons first new moon year is reset every leap year.
  • X Years: The moons first new moon year is reset every X years.

SimpleCalendar.api.PresetTimeOfDay​

This is an enum that contains the different preset times that can be used to set the time of day. Options are:

  • Midnight: The beginning of the day. Equates to time 0.
  • Sunrise: When the sun rises above the horizon. Equates to the sunrise time as defined by the seasons.
  • Midday: The middle of the day. Equates to the middle of the day, 12 for most calendars.
  • Sunset: When the sun sets below the horizon. Equates to the sunset time as defined by the seasons.

SimpleCalendar.api.YearNamingRules​

This is an enum that contains the options for how year names are applied to years. Options are:

  • Default: From the year name starting year the names will be applied in order. When names run out no names will be used.
  • Repeat: From the year name starting year the names will be applied in order. When names run out the list will repeat from the beginning.
  • Random: Every year will be giving a random year name from the list.

Functions

SimpleCalendar.api.advanceTimeToPreset(preset)​

Advance the date and time to match the next preset time.

Important: This function can only be run by users who have permission to change the date in Simple Calendar.

Parameters​

ParameterTypeDefault ValueDescription
presetPresetTimeOfDayundefinedThe preset time that is used to set the time of day.

Returns​

This function will return true if the date was set successfully, false if it was not.

Examples​

//Assuming the curent time is 11am, set the time to the next sunset
//Will result in the date staying the same but the time changing to 6pm
SimpleCalendar.api.advanceTimeToPreset(SimpleCalendar.api.PresetTimeOfDay.Sunset);

//Assuming the current time is 11am, set the time to the next sunrise
//Will result in the date advancing by 1 day and the time changing to 6am
SimpleCalendar.api.advanceTimeToPreset(SimpleCalendar.api.PresetTimeOfDay.Sunrise);

SimpleCalendar.api.changeDate(interval)​

Changes the current date of Simple Calendar.

Important: This function can only be run by users who have permission to change the date in Simple Calendar.

Parameters​

ParameterTypeDefault ValueDescription
intervalInterval Time ObjectNo DefaultThe interval objects properties are all optional so only those that are needed have to be set.
Where each property is how many of that interval to change the current date by.

Returns​

This function will return true if the date change was successful and false if it was not.

Examples​

//Assuming a date of June 1, 2021 and user has permission to change the date
SimpleCalendar.api.changeDate({day: 1}); // Will set the new date to June 2, 2021

//Assuming a date of June 1, 2021 and user has permission to change the date
SimpleCalendar.api.changeDate({day: -1}); // Will set the new date to May 31, 2021

//Assuming a date of June 1, 2021 10:00:00 and user has permission to change the date
SimpleCalendar.api.changeDate({year: 1, month: 1, day: 1, hour: 1, minute: 1, second: 1}); // Will set the new date to July 2, 2022 11:01:01

//Assuming a date of June 1, 2021 10:00:00 and user has permission to change the date
SimpleCalendar.api.changeDate({second: 3600}); // Will set the new date to June 1, 2021 11:00:00

SimpleCalendar.api.chooseRandomDate(startDate, endDate)​

Will choose a random date between the 2 passed in dates, or if no dates are passed in will choose a random date.

Parameters​

ParameterTypeDefault ValueDescription
startDateDate Time Object{}The start date objects properties are all optional so only those needed have to be set.
Where each property is the earliest date to be chosen when randomly selecting a date.
The month and day properties are both index's so January would be 0 and the first day of the month is also 0.
endDateDate Time Object{}The end date objects properties are all optional so only those needed have to be set.
Where each property is the latest date to be chosen when randomly selecting a date.
The month and day properties are both index's so January would be 0 and the first day of the month is also 0.

Returns​

The Date Time Object returned has the following properties

PropertyTypeDefault ValueDescription
yearNumber0The randomly selected year
monthNumber0The randomly selected month index
dayNumber0The randomly selected day index
hourNumber0The randomly selected hour
minuteNumber0The randomly selected minute
secondNumber0The randomly selected second

Examples​

SimpleCalendar.api.chooseRandomDate({year: 2021, month: 3, day: 0},{year: 2021, month: 5, day: 1})
/*
{
    day: 1
    hour: 12
    minute: 5
    month: 4
    second: 41
    year: 2021
}
 */

SimpleCalendar.api.chooseRandomDate({year: 1900, month: 3},{year: 2021, month: 5})
/*
{
    day: 19
    hour: 8
    minute: 16
    month: 3
    second: 25
    year: 1982
}
*/

SimpleCalendar.api.chooseRandomDate();
/*
{
    day: 11
    hour: 0
    minute: 49
    month: 8
    second: 37
    year: 3276
}
 */

SimpleCalendar.api.clockStatus()​

Will get the current status of the built-in clock in Simple Calendar

Returns​

The returned object has the following properties:

PropertyTypeDescription
startedBooleanIf the clock has started and is running.
stoppedBooleanIf the clock is stopped and not running.
pausedBooleanIf the clock has paused. The clock will be paused when the game is paused or the active scene has an active combat.

Examples​

const status = SimpleCalendar.api.clockStatus();
console.log(status); // {started: false, stopped: true, paused: false}

SimpleCalendar.api.configureCalendar(config)​

Sets up the current calendar to match the passed in configuration. This function can only be run by GMs.

Parameters​

ParameterTypeDefault ValueDescription
configSimpleCalendar.api.Calendar or Calendar ConfigurationundefinedThe configuration to set the current year to. It can be one of the predefined calendars or an Calendar Configuration object representing a custom calendar.

Returns​

Returns a promise that resolves to a boolean value, true if the change was successful and false if it was not.

Examples​


//Set the calendar configuration to the Gregorian calendar
const result = await SimpleCalendar.api.configureCalendar(SimpleCalendar.api.Calendars.Gregorian);

//Set the calendar configuration to a custom calendar
const custom = {};

const result = await SimpleCalendar.api.configureCalendar(custom);

SimpleCalendar.api.dateToTimestamp(date)​

Will convert that passed in date object to a timestamp.

Parameters​

ParameterTypeDefault ValueDescription
dateDate Time Ojbect or nullnullA date object (eg {year:2021, month: 4, day: 12, hour: 0, mintue: 0, second: 0}) with the parameters set to the date that should be converted to a timestamp. Any missing parameters will default to the current date value for that parameter.
Important: The month and day are index based so January would be 0 and the first day of the month will also be 0.

Returns​

Returns the timestamp for that date.

Examples​

SimpleCalendar.api.dateToTimestamp({}); //Returns the timestamp for the current date

SimpleCalendar.api.dateToTimestamp({year: 2021, month: 0, day: 0, hour: 1, minute: 1, second: 0}); //Returns 1609462860

SimpleCalendar.api.formatDateTime(date)​

Converts the passed in date into formatted date and time strings that match the configured date and time formats.

Parameters​

ParameterTypeDefault ValueDescription
dateDate Time Ojbect or nullnullA date object (eg {year:2021, month: 4, day: 12, hour: 0, mintue: 0, second: 0}) with the parameters set to the date and time that should be formatted.
Important: The month and day are index based so January would be 0 and the first day of the month will also be 0.
  • Any missing date/time parameters will default to a value of 0.
  • If the date/time parameters are negative, their value will be set to 0. The exception to this is the year parameter, it can be negative.
  • If the date/time parameters are set to a value greater than possible (eg. the 20th month in a calendar that only has 12 months, or the 34th hour when a day can only have 24 hours) the max value will be used.

Returns​

Returns an object that contains a formatted date string and a formatted time string.

Examples​

// Assuming that the default date and time formats are in place
// Date: Full Month Name Day, Year
// Time: 24Hour:Minute:Second

SimpleCalendar.api.formatDate({year: 2021, month: 11, day: 24, hour: 12, minute: 13, second: 14});
// Returns {date: 'December 25, 2021', time: '12:13:14'}

SimpleCalendar.api.formatDate({year: -2021, month: -11, day: 24, hour: 12, minute: 13, second: 14})
// Returns {date: 'January 25, -2021', time: '12:13:14'}

SimpleCalendar.api.formatDate({year: 2021, month: 111, day: 224, hour: 44, minute: 313, second: 314})
// Returns {date: 'December 31, 2021', time: '23:59:59'}

SimpleCalendar.api.getAllMonths()​

Gets the details for all the months of the calendar.

Returns​

This function returns an array of Month Objects.

Examples​

SimpleCalendar.api.getAllMonths();
/* Returns an array like this, assuming the Gregorian Calendar
[
    {
        "id": "13390ed",
        "name": "January",
        "abbreviation": "Jan",
        "numericRepresentation": 1,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "effafeee",
        "name": "February",
        "abbreviation": "Feb",
        "numericRepresentation": 2,
        "numericRepresentationOffset": 0,
        "numberOfDays": 28,
        "numberOfLeapYearDays": 29,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "25b48251",
        "name": "March",
        "abbreviation": "Mar",
        "numericRepresentation": 3,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "e5e9782f",
        "name": "April",
        "abbreviation": "Apr",
        "numericRepresentation": 4,
        "numericRepresentationOffset": 0,
        "numberOfDays": 30,
        "numberOfLeapYearDays": 30,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "93f626f6",
        "name": "May",
        "abbreviation": "May",
        "numericRepresentation": 5,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "22b4b204",
        "name": "June",
        "abbreviation": "Jun",
        "numericRepresentation": 6,
        "numericRepresentationOffset": 0,
        "numberOfDays": 30,
        "numberOfLeapYearDays": 30,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "adc0a7ca",
        "name": "July",
        "abbreviation": "Jul",
        "numericRepresentation": 7,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "58197d71",
        "name": "August",
        "abbreviation": "Aug",
        "numericRepresentation": 8,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "eca76bbd",
        "name": "September",
        "abbreviation": "Sep",
        "numericRepresentation": 9,
        "numericRepresentationOffset": 0,
        "numberOfDays": 30,
        "numberOfLeapYearDays": 30,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "6b0da33e",
        "name": "October",
        "abbreviation": "Oct",
        "numericRepresentation": 10,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "150f5519",
        "name": "November",
        "abbreviation": "Nov",
        "numericRepresentation": 11,
        "numericRepresentationOffset": 0,
        "numberOfDays": 30,
        "numberOfLeapYearDays": 30,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    },
    {
        "id": "b67bc3ee",
        "name": "December",
        "abbreviation": "Dec",
        "numericRepresentation": 12,
        "numericRepresentationOffset": 0,
        "numberOfDays": 31,
        "numberOfLeapYearDays": 31,
        "intercalary": false,
        "intercalaryInclude": false,
        "startingWeekday": null
    }
]
 */

SimpleCalendar.api.getAllMoons()​

Gets the details for all the moons of the calendar.

Returns​

This function returns an array of Moon Objects.

Examples​

SimpleCalendar.api.getAllMoons();
/* Returns an array like this, assuming the Gregorian Calendar
[
    {
        "id": "2c26abfa",
        "name": "Moon",
        "color": "#ffffff",
        "cycleLength": 29.53059,
        "cycleDayAdjust": 0.5,
        "firstNewMoon": {
            "year": 2000,
            "month": 1,
            "day": 6,
            "yearX": 0,
            "yearReset": "none"
        },
        "phases": [
            {
                "name": "New Moon",
                "length": 1,
                "icon": "new",
                "singleDay": true
            },
            {
                "name": "Waxing Crescent",
                "length": 6.3826,
                "icon": "waxing-crescent",
                "singleDay": false
            },
            {
                "name": "First Quarter",
                "length": 1,
                "icon": "first-quarter",
                "singleDay": true
            },
            {
                "name": "Waxing Gibbous",
                "length": 6.3826,
                "icon": "waxing-gibbous",
                "singleDay": false
            },
            {
                "name": "Full Moon",
                "length": 1,
                "icon": "full",
                "singleDay": true
            },
            {
                "name": "Waning Gibbous",
                "length": 6.3826,
                "icon": "waning-gibbous",
                "singleDay": false
            },
            {
                "name": "Last Quarter",
                "length": 1,
                "icon": "last-quarter",
                "singleDay": true
            },
            {
                "name": "Waning Crescent",
                "length": 6.3826,
                "icon": "waning-crescent",
                "singleDay": false
            }
        ],
        "currentPhase": {
            "name": "Waning Crescent",
            "length": 6.3826,
            "icon": "waning-crescent",
            "singleDay": false
        }
    }
]
 */

SimpleCalendar.api.getAllSeasons()​

Gets the details for all the seasons for the calendar.

Returns​

This function returns an array of Season objects.

Examples​

SimpleCalendar.api.getAllSeasons();
/* Returns an array like this, assuming the Gregorian Calendar
[
    {
        color: "#fffce8",
        id: "4916a231",
        name: "Spring",
        startingDay: 20,
        startingMonth: 3,
        sunriseTime: 21600,
        sunsetTime: 64800
    },
    {
        color: "#f3fff3",
        id: "e596489",
        name: "Summer",
        startingDay: 20,
        startingMonth: 6,
        sunriseTime: 21600,
        sunsetTime: 64800
    },
    {
        color: "#fff7f2",
        id: "3f137ee5",
        name: "Fall",
        startingDay: 22,
        startingMonth: 9,
        sunriseTime: 21600,
        sunsetTime: 64800
    },
    {
        color: "#f2f8ff",
        id: "92f919a2",
        name: "Winter",
        startingDay: 21,
        startingMonth: 12,
        sunriseTime: 21600,
        sunsetTime: 64800
    }
]
 */

SimpleCalendar.api.getAllWeekdays​

Gets the details about all the weekdays for the calendar.

Returns​

This function returns an array of Weekday Object.

Examples​

SimpleCalendar.api.getAllWeekdays();
/* Returns an array like this, assuming the Gregorian Calendar
[
    {
        id: "dafbfd4",
        name: "Sunday",
        numericRepresentation: 1
    },
    {
        id: "8648c7e9",
        name: "Monday",
        numericRepresentation: 2
    }
    {
        id: "b40f3a20",
        name: "Tuesday",
        numericRepresentation: 3
    },
    {
        id: "6c20a99e",
        name: "Wednesday",
        numericRepresentation: 4
    },
    {
        id: "56c14ec7",
        name: "Thursday",
        numericRepresentation: 5
    },
    {
        id: "2c732d04",
        name: "Friday",
        numericRepresentation: 6
    },
    {
        id: "c8f72e3d",
        name: "Saturday",
        numericRepresentation: 7
    }
]
 */

SimpleCalendar.api.getCurrentDay()​

Gets the details about the current day.

Returns​

This function returns a Day Object.

Examples​

SimpleCalendar.api.getCurrentDay();
/* Returns an object like this:
{
    id: "cbdb31cb",
    name: "8",
    numericRepresentation: 8
}
 */

SimpleCalendar.api.getCurrentMonth()​

Gets the details about the current month.

Returns​

This function returns a Month Object.

Examples​

SimpleCalendar.api.getCurrentMonth();
/* Returns an object like this:
{
    abbreviation: "Jun",
    id: "22b4b204",
    intercalary: false,
    intercalaryInclude: false,
    name: "June",
    numberOfDays: 30,
    numberOfLeapYearDays: 30,
    numericRepresentation: 6,
    numericRepresentationOffset: 0,
    startingWeekday: null
}
 */

SimpleCalendar.api.getCurrentSeason()​

Gets the details about the season for the current date of the calendar.

Returns​

This function returns a Season Object.

Examples​

SimpleCalendar.api.getCurrentSeason();
/* Returns an object like this
{
    color: "#fffce8",
    id: "4916a231",
    name: "Spring",
    startingDay: 19,
    startingMonth: 2,
    sunriseTime: 21600,
    sunsetTime: 64800
}
*/

SimpleCalendar.api.getCurrentWeekday()​

Gets the details about the current weekday.

Returns​

This function returns a Weekday Object.

Examples​

SimpleCalendar.api.getCurrentWeekday();
/* Returns an object like this
{
    id: "b40f3a20",
    name: "Tuesday",
    numericRepresentation: 3
}
*/

SimpleCalendar.api.getCurrentYear()​

Gets the details about the current year.

Returns​

This function returns a Year Object.

Examples​

SimpleCalendar.api.getCurrentYear();
/* Returns an object like this
{
    firstWeekday: 4,
    id: "bbe5385c",
    numericRepresentation: 2021,
    postfix: "",
    prefix: "",
    showWeekdayHeadings: true,
    yearNames: [],
    yearNamesStart: 0,
    yearNamingRule: "default",
    yearZero: 1970
}
*/

SimpleCalendar.api.getLeapYearConfiguration()​

Gets the details about how leap years are configured for the calendar.

Returns​

This function returns a Leap Year Object.

Examples​

SimpleCalendar.api.getLeapYearConfiguration();
/* Returns an object like this
{
    customMod: 0,
    id: "1468d034",
    rule: "gregorian"
}
*/

SimpleCalendar.api.getTimeConfiguration()​

Get the details about how time is configured for the calendar.

Returns​

This function returns a Time Object.

Examples​

SimpleCalendar.api.getTimeConfiguration();
/* Returns an object like this
{
    gameTimeRatio: 1,
    hoursInDay: 24,
    id: "d4791796",
    minutesInHour: 60,
    secondsInCombatRound: 6,
    secondsInMinute: 60,
    unifyGameAndClockPause: true,
    updateFrequency: 1
}
*/

SimpleCalendar.api.isPrimaryGM()​

Returns if the current user is considered the primary GM or not.

Examples​


SimpleCalendar.api.isPrimaryGM(); //True or Flase depending on if the current user is primary gm

SimpleCalendar.api.secondsToInterval(seconds)​

Will attempt to parse the passed in seconds into larger time intervals that make it up.

Parameters​

ParameterTypeDefault ValueDescription
secondsNumberNo DefaultThe number of seconds to convert to different intervals.

Returns​

Returns an Interval Time Object.

Examples​

//Assuming a Gregorian Calendar
SimpleCalendar.api.secondsToInterval(3600); //Returns {year: 0, month: 0, day: 0, hour: 1, minute: 0, second 0}
SimpleCalendar.api.secondsToInterval(3660); //Returns {year: 0, month: 0, day: 0, hour: 1, minute: 1, second: 0}
SimpleCalendar.api.secondsToInterval(86400); //Returns {year: 0, month: 0, day: 1, hour: 0, minute: 0, second: 0}
SimpleCalendar.api.secondsToInterval(604800); //Returns {year: 0, month: 0, day: 7, hour: 0, minute: 0, second: 0}
SimpleCalendar.api.secondsToInterval(2629743); //Returns {year: 0, month: 1, day: 0, hour: 10, minute: 29, second: 3}
SimpleCalendar.api.secondsToInterval(31556926); //Returns {year: 1, month: 0, day: 0, hour: 5, minute: 48, second: 46}

SimpleCalendar.api.setDate(date)​

Will set the current date to the passed in date.

Important: This function can only be run by users who have permission to change the date in Simple Calendar.

Parameters​

ParameterTypeDefault ValueDescription
dateDate Time Object or nullnullA date object (eg {year:2021, month: 4, day: 12, hour: 0, mintue: 0, second: 0}) with the parameters set to the date that the calendar should be set to. Any missing parameters will default to the current date value for that parameter.
Important: The month and day are index based so January would be 0 and the first day of the month will also be 0.

Returns​

This function will return true if the date was set successfully, false if it was not.

Examples​

//To set the date to December 25th 1999 with the time 00:00:00
SimpleCalendar.setDateTime(1999, 11, 24);

//To set the date to December 31st 1999 and the time to 11:59:59pm
SimpleCalendar.setDateTime(1999, 11, 30, 23, 59, 59);

SimpleCalendar.api.showCalendar(date, compact)​

Will open up Simple Calendar to the current date, or the passed in date.

Parameters​

ParameterTypeDefault ValueDescription
dateDate Time Object or nullnullA date object (eg {year:2021, month: 4, day: 12}) with the year, month and day set to the date to be visible when the calendar is opened.
Important: The month is index based so January would be 0.
compactbooleanfalseIf to open the calendar in compact mode or not.

Examples​

//Assuming a Gregorian Calendar
SimpleCalendar.api.showCalendar(); // Will open the calendar to the current date.
SimpleCalendar.api.showCalendar({year: 1999, month: 11, day: 25}); // Will open the calendar to the date December 25th, 1999
SimpleCalendar.api.showCalendar(null, true); // Will opent the calendar to the current date in compact mode.

SimpleCalendar.api.startClock()​

Starts the real time clock of Simple Calendar. Only the primary GM can start a clock.

Returns​

Will return true if the clock started, false if it did not.

Examples​

SimpleCalendar.api.startClock();

SimpleCalendar.api.stopClock()​

Stops the real time clock of Simple Calendar.

Returns​

Will return true if the clock stopped, false if it did not.

Examples​

SimpleCalendar.api.stopClock();

SimpleCalendar.api.timestamp()​

Return the timestamp (in seconds) of the calendars currently set date.

Examples​

const timestamp = SimpleCalendar.api.timestamp();
console.log(timestamp); // This will be a number representing the current number of seconds passed in the calendar.

SimpleCalendar.api.timestampPlusInterval(timestamp, interval)​

Returns the current timestamp plus the passed in interval amount.

Parameters​

ParameterTypeDefault ValueDescription
timestampNumberNo DefaultThe timestamp (in seconds) to have the interval added too.
intervalInterval Time ObjectNo DefaultThe interval objects properties are all optional so only those needed have to be set.
Where each property is how many of that interval to increase the passed in timestamp by.

Examples​

let newTime = SimpleCalendar.api.timestampPlusInterval(0, {day: 1});
console.log(newTime); // this will be 0 + the number of seconds in 1 day. For most calendars this will be 86400

// Assuming Gregorian Calendar with the current date of June 1, 2021
newTime = SimpleCalendar.api.timestampPlusInterval(1622505600, {month: 1, day: 1});
console.log(newTime); // This will be the number of seconds that equal July 2nd 2021

SimpleCalendar.api.timestampToDate(timestamp)​

Takes in a timestamp (in seconds) and will return that as a Simple Calendar date object.

Parameters​

ParameterTypeDefault ValueDescription
timestampNumberNo DefaultThe timestamp (in seconds) to convert into a date object.

Returns​

A Date Object is returned.

Examples​

// Assuming Gregorian Calendar with the current date of June 1, 2021
let scDate = SimpleCalendar.api.timestampToDate(1622505600);
console.log(scDate);
/* This is what the returned object will look like
{
    currentSeason: {color: "#fffce8", startingMonth: 3, startingDay: 20, name: "Spring"},
    day: 0,
    dayDisplay: "1",
    dayOfTheWeek: 2,
    dayOffset: 0,
    display: {
        date: "June 01, 2021",
        day: "1",
        daySuffix: "st",
        month: "6",
        monthName: "June",
        time: "00:00:00",
        weekday: "Tuesday",
        year: "2021",
        yearName: "",
        yearPostfix: "",
        yearPrefix: "",
    },
    hour: 0,
    minute: 0,
    month: 5,
    monthName: "June",
    second: 0,
    showWeekdayHeadings: true,
    weekdays: ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"],
    year: 2021,
    yearName: "",
    yearPostfix: "",
    yearPrefix: "",
    yearZero: 1970
}
*/

Types

Calendar Configuration Object​

This type contains all information for configuring a calendar.

PropertyTypeOptionalDefaultDescription
currentDateCurrent Date ObjectYes{}The current date of the calendar.
leapYearSettingsLeap Year ObjectYes{}The leap year settings for the calendar.
monthSettingsArray<Month Object>Yes[]An array of month settings for the calendar.
moonSettingsArray<Moon Object>Yes[]An array of moon settings for the calendar.
noteCategoriesArray<Note Cateogry Object>Yes[]An array of note categories for the calendar.
seasonSettingsArray<Season Object>Yes[]An array of season for the calendar.
timeSettingsTime ObjectYes{}The time settings for the calendar.
weekdaySettingsArray<Weekday Object>Yes[]An array of weekday settings for the calendar.
yearSettingsYear ObjectYes{}The year settings for the calendar.

Current Date Object​

This type contains information on the current date.

PropertyTypeOptionalDefaultDescription
yearNumberNo0The current year.
monthNumberNo1The current month's numeric representation.
dayNumberNo1The current day's numeric representation.
secondsNumberNo0The current number of seconds passed in the current day.

Date Object​

This type contains the current date information

PropertyTypeDefault ValueDescription
currentSeasonSeason Object{}The information for the season of the date, properties include "name" for the seasons name and "color" for the color associated with the season.
dayNumber0The index of the day of the month represented in the timestamp.
dayDisplayString""Depreciated Please use display.day instead. This will be removed when Foundry v9 Stable is released.
dayOfTheWeekNumber0The day of the week the day falls on.
dayOffsetNumber0The number of days that the months days are offset by.
displayDate Display Object{}All of the strings associated with displaying the date are put here
hourNumber0The hour represented in the timestamp.
isLeapYearBooleanfalseIf this date falls on a leap year.
middayNumber0The timestamp of when midday occurs for this date.
minuteNumber0The minute represented in the timestamp.
monthNumber0The index of the month represented in the timestamp.
monthNameString""Depreciated Please use display.monthName instead. This will be removed when Foundry v9 Stable is released.
secondNumber0The seconds represented in the timestamp.
showWeekdayHeadingsBooleantrueIf to show the weekday headings for the month.
sunriseNumber0The timestamp of when the sun rises for this date.
sunsetNumber0The timestamp of when the sun sets for this date.
weekdaysString Array[]A list of weekday names.
yearNumber0The year represented in the timestamp.
yearNameString""Depreciated Please use display.yearName instead. This will be removed when Foundry v9 Stable is released.
yearPostfixString""Depreciated Please use display.yearPostfix instead. This will be removed when Foundry v9 Stable is released.
yearPrefixString""Depreciated Please use display.yearPrefix instead. This will be removed when Foundry v9 Stable is released.
yearZeroNumber0What is considered as year zero when doing timestamp calculations.

Date Display Object​

This type contains the formatted strings used to display the current date and time.

PropertyTypeDefault ValueDescription
dateString""The formatted date string based on the format set in the configuration for the date.
dayString""How the day is displayed, generally its number on the calendar.
daySuffixString""The Ordinal Suffix associated with the day number (st, nd, rd or th)
monthString""The month number.
monthNameString""The name of the month.
timeString''The formatted time string based on the format set in the configuration for the time.
weekdayString""The name of the weekday this date falls on.
yearString""The year number
yearNameString""The name of the year, if year names have been set up.
yearPostfixString""The postfix value for the year
yearPrefixString""The prefix value for the year

Date Time Object​

This type is used to indicate dates and times.

PropertyTypeOptionalDefaultDescription
yearNumberYes0The year for the date time.
monthNumberYes0The month for the date time. Importat: The month is index based, meaning the first month of a year will have a value of 0.
dayNumberYes0The day for the date time. Important: The day is index based, meaning the first day of the month will have a value of 0.
hourNumberYes0The hour for the date time.
minuteNumberYes0The minute for the date time.
secondNumberYes0The second for the date time.

Day Object​

This object contains information about a day

PropertyTypeOptionalDefaultDescription
idStringNo""The unique ID associated with this day object.
nameStringNo""The name of the day, at the moment it is just the day number in string form.
numericRepresentationNumberNo1The number associated with the day

First New Moon Object​

This type is used to configure when the first new moon for a moon was.

PropertyTypeOptionalDefaultDescription
yearResetMoonYearResetOptionsNoSimpleCalendar.api.MoonYearResetOptions.NoneIf and when the year of the new moon should be reset.
yearXNumberNo0Reset the new moon year every X years.
yearNumberNo0The year of the first new moon.
monthNumberNo1The month of the first new moon.
dayNumberNo1The day of the first new moon.

Leap Year Object​

This type contains information about leap year rules.

PropertyTypeOptionalDefaultDescription
idStringYes""The unique ID associated with the leap year configuration.
ruleLeapYearRulesNoSimpleCalendar.api.LeapYearRules.NoneThis is the leap year rule to follow.
customModNumberNo0The number of years that a leap year happens when the rule is set to 'custom'.

Interval Time Object​

This type is used to indicate intervals of time.

PropertyTypeOptionalDefaultDescription
yearNumberYes0The number of years making up the interval.
monthNumberYes0The number of months making up the interval.
dayNumberYes0The number of days making up the interval.
hourNumberYes0The number of hours making up the interval.
minuteNumberYes0The number of minutes making up the interval.
secondNumberYes0The number of seconds making up the interval.

Month Object​

This type contains information about a month.

PropertyTypeOptionalDefaultDescription
abbreviationStringYes""The abbreviated name of the month.
idStringYes""The unique ID associated with this month.
nameStringNo""The name of the month.
numericRepresentationNumberNo1The number associated with the display of this month.
numericRepresentationOffsetNumberNo0The amount to offset day numbers by for this month.
numberOfDaysNumberNo0The number of days this month has during a non leap year.
numberOfLeapYearDaysNumberNo0The number of days this month has during a leap year.
intercalaryBooleanNoFalseIf this month is an intercalary month.
intercalaryIncludeBooleanNoFalseIf this month is intercalary then if its days should be included in total day calculations.
startingWeekdayNumber or NullNoNullThe day of the week this month should always start on.

Moon Object​

This type contains information about a moon.

PropertyTypeOptionalDefaultDescription
idStringYes""The unique ID associated with this season.
colorStringNo"#FFFFFF"The color associated with the moon.
currentPhaseMoon Phase ObjectYes{}The moon phase for the current date.
cycleDayAdjustNumberNo0A way to nudge the cycle calculations to align with correct dates.
cycleLengthNumberNo0How many days it takes the moon to complete 1 cycle.
firstNewMoonFirst New Moon ObjectYes{}When the first new moon was. This is used to calculate the current phase for a given day.
nameStringNo""The name of the moon.
phasesArray<Moon Phase Object>Yes[]The different phases of the moon.

Moon Phase Object​

This type contains information about a moon phase.

PropertyTypeOptionalDefaultDescription
iconMoonIconsNo``The icon to associate with this moon phase.
lengthNumberNo0How many days of the cycle this phase takes up.
nameStringNo""The name of the phase.
singleDayBooleanNoFalseIf this phase should only take place on a single day.

Note Category Object​

This type contains information about a note category.

PropertyTypeOptionalDefaultDescription
nameStringNo""The name of the note category.
colorStringNo""The background color assigned to the note category.
textColorStringNo"#FFFFFF"The color of the text assigned to the note category.

Season Object​

This type contains information about a season.

PropertyTypeDefault ValueDescription
colorString#ffffffThe color associated with this season.
idString""The unique ID associated with this season.
nameString""The name of the season.
startingDayNumber1The day index of the month that the season starts on.
startingMonthNumber1The month index that the season starts on.
sunriseNumber0The number of seconds into the starting day of the season that the sun rises. EG. a value of 3600 would be 1:00am in a Gregorian Calendar.
sunsetNumber0The number of seconds into the starting day of the season that the sun sets. EG. a value of 82800 would be 11:00pm in a Gregorian Calendar.

Time Object​

This type contains information about how time is configured.

PropertyTypeOptionalDefaultDescription
idStringYes""The unique ID associated with the time configuration.
hoursInDayNumberNo24The number of hours in a single day.
minutesInHourNumberNo60The number of minutes in a single hour.
secondsInMinuteNumberNo60The number of seconds in a single minute.
gameTimeRatioNumberNo1When running the clock for every second that passes in the real world how many seconds pass in game.
unifyGameAndClockPauseBooleanNoFalseIf to start/stop the clock when the game is unpaused/paused.
updateFrequencyNumberNo1How often (in real world seconds) to update the time while the clock is running.

Weekday Object​

This type contains information about a weekday.

PropertyTypeOptionalDefaultDescription
idStringYes""The unique ID associated with this weekday.
nameStringNo""The name of the weekday.
numericRepresentationNumberNo0The number representing the weekday.

Year Object​

This type contains information about a year.

PropertyTypeOptionalDefaultDescription
idStringYes""The unique ID associated with the year.
numericRepresentationNumberNo0The number representing the year.
prefixStringNo""A string to append to the beginning of a year's number.
postfixStringNo""A string to append to the end of a year's number.
showWeekdayHeadingsBooleanNoTrueIf to show weekday headings on the calendar.
firstWeekdayNumberNo0The day of the week the first day of the first month of year zero starts on.
yearZeroNumberNo0What is considered to be the first year when calculating timestamps.
yearNamesArray<String>No[]A list of names to use for years.
yearNamingRuleYearNamingRuleNoSimpleCalendar.api.YearNamingRule.DefaultHow to calculate what year name to give to a year.
yearNamesStartNumberNo0The year to start applying the year names.