Fantasy Grounds Custom Calendar Tutorial

[mattekure]

I have seen a number of posts asking for help with creating custom calendars. I have tried to go through the forums and pull together all the gathered wisdom from many different posts and I have put together a custom calendar tutorial.

The attached tutorial gives an overview of creating a calendar, covering both the XML definition within the module file, and the optional LUA code in an extension. I have included 6 working examples with their respective files and compiled modules/extensions. I have tried to provide some documentation within both the sample XML and LUA files to make things easy to understand. I would appreciate any comments or improvements.

Also, huge credit goes out to user Andraax for all his calendar posts. A huge amount of what I learned was by going through those examples.


Included Examples
Example 1 - simple calendar, no holidays
----------------
First sample calendar has only a mod file and no accompanying extension. This is because it is a very simple calendar requiring no additional calculations.
Calendar basics
The Example 1 calendar has
7 months.
Each month has 28 days (4 weeks)
Each week has 7 days.
So, due to the simple math, each month looks exactly the same as every other month. The first day of the Month is the first day of the the week. There are no leap years.

Example 2
----------
The same calendar as Example 1 except with holidays added.

Example 3
-------------
Example Calendar 3 is a simple calendar consisting of 12 months. Odd months have 30 days, and even months have 31 days. There are no leap years.

In order for FG to know what day of the week a month starts, an extension is included with the LUA code to calculate that.

Example 4
-----------
Example 3 is the default Gregorian calendar as defined in the CoreRPG with some code comments added in with explanations.

The Gregorian calendar has months of varying length from 28-31 days, and has leap years. So the example includes the extension code which calculates both the day of the week properly, and calculates the number of days to add to the leap year.

Example 5
---------
An excellent example calendar from a user on the FG forums

Example 6
----------
A modified version of the traveller calendar, showing how to modify/format the day and date display


https://forge.fantasygrounds.com/shop/items/1612/view

I have added the Generic Day Handler Extension to the Forge for auto updating.
This extension will roll over days of the week as long as you dont have leap years. you can enable it in your calendar by using this as your lunar day calendar by adding

<lunardaycalc type="string">LunarWrap</lunardaycalc>

[damned]

Great work mattekure

[mattekure]

Added a new example. The new example shows a modified version of the traveller calendar and demonstrates how you can modify how the calendar formats its day entries, and how you can change the formatting of the calendar date output to the chat.

[ThatsSoNoc]

Hi,

I have used your Georgian Calendar (modified - Leap Years and Leap Days) as the basis upon which I have skinned my custom calendar - changing the names of the days of the week, months of the year, and adding liturgical holidays in keeping with various custom pantheons.

However, I am unable to figure out how to create (code) a 'holiday' notation, that will appear on the calendar, which is fixed to a particular day of the week - E.G. Every Wednesday is Farmer's Market Day - and not to a numerical date of a month. Because the numerical date of each Wednesday shifts over time, back and forth, thus Wednesdays in a month do not always occur on that same numerical date, month after month, year after year?

Secondly, is there a means to fix a holiday to a specific day of the month, and have it reoccurring yearly, or possibly monthly, regardless of the actual numerical date - E.G. The second Sunday of every month (or the second Sunday of the third month) is St. Cuthburt's Day?

Finally, and quite possibly the hardest (impossible ?) request - can you set a holiday to occur, based on the lunar cycle calendar - similar to how Easter and Ramadan holidays are set from year to year? E.G. The first full moon of the year? Or the second crescent moon of the year? And so forth.

Thank-you for your suggested coding.

[mattekure]

Unfortunately, holidays are defined in the XML and cannot be defined programatically in code. So they will be fixed. Its not possible to have a holiday that always falls on a specific day of the week or changing the recurrence like that.

[yeknom]

Hi there Mattekure! Thanks for this. It has helped me tremendously.

If I wanted to add a holiday every 2 weeks using the example 2 from above would I have to have a period of 14 days then a holiday and then another period of 14 days with both periods have the same name month?

[GunnarGreybeard]

It's been a long while since I messed with a new calendar. This will come in handy when I go to relearn how to do it.

[mattekure]

Hi there Mattekure! Thanks for this. It has helped me tremendously.

If I wanted to add a holiday every 2 weeks using the example 2 from above would I have to have a period of 14 days then a holiday and then another period of 14 days with both periods have the same name month?

The answer is a little more complex. You should really think of a Period as a month. You can give several different periods (months) the same name, but they will appear as separate months on the calendar. And you wont be able to start the numbering differently, each period will start at day 1.

Keeping it simple, if you have months that are always 28 days, and you have 12 months per year. You would define each period, with a holidays section containing 2 holidays, one on the 1st, and one on the 15th. As long as its kept simple like that, its super easy.

But lets take a more difficult example using real world gregorian calendar. If a holiday occurs every 14 days, starting on Jan 1. The dates would be:
Jan 1
Jan 15
Jan 29
Feb 12
Feb 26
Mar 12
Mar 26
Apr 9
etc.

So you can see that the numbers dont align nicely. In order to implement this in FG, you would have to manually calculate every holiday through the year. If your calendar is simple in that it has an exact multiple of 14 days in the year, then they will always be spaced nicely. But if you have some odd number of days, like 365. Then if the holiday falls on Dec 28, FG will mark the next holiday on Jan 1. There isnt a way to use a function to alter the holidays.

[yeknom]

Thanks for this. I will see what I can do.

[devinlc]

I modified your tutorial calendar #1 to add in some new months and then used 7zip to pack the db and definition xml files into a .mod file. Put it into the mod folder for FG and when I went to the calendar window...nothing new appeared. Thinking I must have done something wrong, I directly transferred your .mod file for tutorial calendar #1 to the module folder, restarted FG, went to the calendar window, and still no new calendar.

Any advice or suggestions?