Hooks
Here are all the hooks that Simple Calendar emits and when they are emitted.
How to Listen for a Hook
The global Simple Calendar object comes with a variable called hooks which will list all the available hooks that can be listened for.
Example:
SimpleCalendar.Hooks.DateTimeChange
The current hooks that are emitted are:
| Hook Name | Value | Description |
|---|---|---|
| DateTimeChange | "simple-calendar-date-time-change" | This hook is emitted any time the current date is updated. |
| ClockStartStop | "simple-calendar-clock-start-stop" | This hook is emitted any time the clock is started/stopped or paused. |
| PrimaryGM | "simple-calendar-primary-gm" | This hook is emitted when the current user is promoted to the primary GM role. |
| Ready | "simple-calendar-ready" | This hook is emitted when Simple Calendar is fully initialized and ready to take commands. Note: For GM's this can take a little longer as some additional checks are done to see which GM will be considered the primary GM |
Date/Time Change
When it is emitted
This hook is emitted any time the current date is updated. The current date can be updated by several means:
- When the GM clicks on the "Set Current Date" button after adjusting the current date.
- When the clock is running every interval update.
- When the Set Date/Time API function is called.
- When the Change Date/Time API function is called.
- When the game world time has changed and Simple Calendar is configured to update when that changes.
What is passed
When this hook is emitted it will pass a data object that contains information about the new current day. The object will have these top level properties:
| Property Name | Type | Default Value | Description |
|---|---|---|---|
| date | Date Object | {} | This contains information about the current date of the calendar. |
| diff | Number | 0 | This contains the difference in seconds from the previous date and time to this new date and time. |
| moons | Array<Moon Object> | [] | This contains information about the moon(s) phases for the current date. |
| year | Year Object | {} | Depreciated Please use the date property. This will be removed when Foundry v10 stable is released. |
| month | Month Object | {} | Depreciated Please use the date property. This will be removed when Foundry v10 stable is released. |
| day | Day Object | {} | Depreciated Please use the date property. This will be removed when Foundry v10 stable is released. |
| time | Time Object | {} | Depreciated Please use the date property. This will be removed when Foundry v10 stable is released. |
| season | Season Object | {} | Depreciated Please use the date property. This will be removed when Foundry v10 stable is released. |
Year Properties
| Property Name | Value Type | Description |
|---|---|---|
| number | number | This is the current years numerical representation. |
| prefix | string | This is the text that appears before the years numerical representation. |
| postfix | string | This is the test that appears after the years numerical representation. |
| isLeapYear | boolean | If this year is a leap year. |
Month Properties
| Property Name | Value Type | Description |
|---|---|---|
| number | number | The months numerical representation. |
| name | string | The name of the month. |
| numberOfDays | number | How many days are in this month. |
| numberOfLeapYearDays | number | How many days are in this month during a leap year. |
| intercalary | boolean | If this month is considered an intercalary month or not. |
Day Properties
| Property Name | Value Type | Description |
|---|---|---|
| number | number | The days numerical representation. |
Time Properties
| Property Name | Value Type | Description |
|---|---|---|
| hour | string | The number of hours into the day it currently is. This result is 0 padded. |
| minute | string | The number of minutes into the day it currently is. This result is 0 padded. |
| second | string | The number of seconds into the day it currently is. This result is 0 padded. |
Season Properties
| Property Name | Value Type | Description |
|---|---|---|
| name | string | The name of the season. |
| color | string | The hex color representation of the season. |
Examples
Hooking to
This is an example of how to listen for the hook:
Hooks.on(SimpleCalendar.Hooks.DateTimeChange, (data) => {
console.log(data);
});
Response Data
This is an example of the data that is passed with this hook:
{
"date": {
"year": 2021,
"month": 6,
"dayOffset": 0,
"day": 8,
"dayOfTheWeek": 5,
"hour": 0,
"minute": 15,
"second": 30,
"yearZero": 1970,
"weekdays": [
"Sunday",
"Monday",
"Tuesday",
"Wednesday",
"Thursday",
"Friday",
"Saturday"
],
"showWeekdayHeadings": true,
"currentSeason": {
"color": "#f3fff3",
"startingMonth": 5,
"startingDay": 19,
"name": "Summer"
},
"isLeapYear": false,
"monthName": "July",
"dayDisplay": "9",
"yearName": "",
"yearPrefix": "",
"yearPostfix": "",
"display": {
"day": "9",
"daySuffix": "th",
"weekday": "Friday",
"monthName": "July",
"month": "7",
"year": "2021",
"yearName": "",
"yearPrefix": "",
"yearPostfix": "",
"time": "00:15:30"
}
},
"diff": 1,
"moons": [
{
"name": "Moon",
"color": "#ffffff",
"cycleLength": 29.53059,
"cycleDayAdjust": 0.5,
"currentPhase": {
"name": "New Moon",
"length": 1,
"icon": "new",
"singleDay": true
}
}
],
"season": {
"name": "Summer",
"color": "#f3fff3"
},
"month": {
"name": "July",
"number": 7,
"intercalary": false,
"numberOfDays": 31,
"numberOfLeapYearDays": 31
},
"day": {
"number": 9
},
"time": {
"hour": "00",
"minute": "15",
"second": "30"
},
"year": {
"number": 2021,
"prefix": "",
"postfix": "",
"isLeapYear": false
}
}
Clock Start/Stop
When it is emitted
This event is emitted in the following cases:
- When the clock is started.
- When the clock is stopped.
- When the game is paused or unpaused.
- When a combat is started or ended in the active scene
- When a combat round is advanced.
What is passed
When this hook is emitted it will pass a data object that contains the following properties:
| Property Name | Value Type | Description |
|---|---|---|
| started | boolean | If the clock is started and running. |
| stopped | boolean | If the clock is stopped and not running. |
| paused | boolean | If the clock is paused. The clock is paused when the game is paused or there is an active combat running in the active scene. |
Examples
Hooking to
This is an example of how to listen for the hook:
Hooks.on(SimpleCalendar.Hooks.ClockStartStop, (data) => {
console.log(data);
});
Response Data
This is an example of the data that is passed with this hook:
{
"started": false,
"stopped": true,
"paused": false
}
Is Primary GM
When it is emitted
This event is emitted when the current users is promoted to the primary GM role.
This will happen 5 seconds after loading the game if no other GM is currently in the primary role.
What is passed
| Property Name | Value Type | Description |
|---|---|---|
| isPrimaryGM | boolean | If the user is the primary gm (true). |
Examples
Hooking to
This is an example of how to listen for the hook:
Hooks.on(SimpleCalendar.Hooks.PrimaryGM, (data) => {
console.log(data);
});
Response Data
This is an example of the data that is passed with this hook:
{
"isPrimaryGM": true
}
Ready
When it is emitted
This event is emitted when Simple Calendar is fully initialized and ready to use.
For GMs this will happen up to 5 seconds after loading the game as additional checks are done to see which GM is to be considered the primary GM.
What is passed
No data is passed when this hook is fired.
Examples
Hooking to
This is an example of how to listen for the hook:
Hooks.on(SimpleCalendar.Hooks.Ready, () => {
console.log(`Simple Calendar is ready!`);
});