Overview
Real-time advancement is the concept of having your calendar automatically advance forward on a regular interval.
Note: This could honestly be more accurately called "Automated advancement", rather than "Real-time," but we felt the mismatch in labelling would be confusing.
Essentially, rather than just "ticking" forward in real time, you are configuring a regularly scheduled task that essentially tells the calendar "Add X amount of Y in-universe units every W real-time Z units". So, by choosing "one day per day", you are really saying "every 24 hours, call ->addDay() on the calendar.
Important note
The advancement process requires compute time on the backend, every time it happens. The default is 1 hour == 1 hour in order to strike a balance for the folks who want such a feature for things like west marches campaigns.
We offer the option of 1 minute == 1 minute because we know some people like the granularity; However, the vast majority of people don't need that.
For our sakes, please think about how often you play D&D, and then ask yourself: Do I really need a minute advanced every minute? Chances are, most folks could even get away with 1 day == 1 day.
Setting it up
Setting up real-time advancement is fairly straightforward:
- Enable "Real-Time Advancement"
- Decide how often you want your calendar to advance, and by how much
- Set those values in the advancement settings:
With the above example (the default settings of 1 hour == 1 hour), the Fantasy Calendar advancement scheduled job will call ->addHour() and then set a field called advancement_next_due on the calendar backend to a value of now()->addHour()->startOfMinute(). That will begin happening the minute after you enable advancement.
Webhooks
Wikipedia defines webhooks as "a method of augmenting or altering the behavior of a web page or web application with custom callbacks".
That's ... A bit of a complicated way to say "an option to have a web page or application reach out to your web server when something happens". For example, if you were to develop a custom display of the calendar's information for your own campaign website, you could have FC reach out to your website's backend every time it advances.
Or, as we suspect most people will do, you can have FC update a message via the Discord integration. One group we know has a #campaign-time channel in their discord server with a single message in it, managed by the webhook. All it does is keep that single message up to date by posting the current time and date.
FAQ
Why is this a premium feature?
It comes down to the server-side processing, mostly. Fantasy Calendar runs in a "serverless" environment, in which we pay by the GB-second of RAM usage. That means every single advancement task costs us a little bit of money, by costing us compute time.
Why is it server-side if it costs you compute time? Why not client-side, or when the page is loaded?
Great question. The answer is webhooks! We wanted to offer an option to notify folks every time the calendar advances by sending a payload to a webhook endpoint. You can read more about that above.
Can I have multiple webhooks?
Sure! All you have to do is have your first webhook forward to the others.
Wait, if it's server-side, what happens if there's an outage? Or maintenance?
The short answer is: We compensate for it. You can read the code here if you're interested - But basically we track the time the advancement is "next due" to happen, and only ever process calendars that are due or past due.
For example, if your calendar is set for
1 minute == 1 minute, and we're down for 10 minutes, then when we're back up and running, the advancement process will detect that it's 10 minutes behind and add 10 minutes instead of the usual 1.
Is there a way to set what time the calendar will auto-advance?
At the moment, the only way to do so is to enable advancement around the time you want to advance, since it'll advance for the first time around a minute later.
However, adding such a thing is on our to-do list! We wanted to get the initial version out first, to see what kind of features people would end up needing. Please do reach out and let us know if this would be helpful to you!