Add calendar date-time-events macros

[JamzTheMan]

Is your feature request related to a problem? Please describe. Date math, formatting, event handling, etc can be cumbersome to code in macro code. It can be a lot of macro code just to handle some simple timed events a user may need, like: "Remind me in 3 days to roll for disease xyz" or "track crafting is done for awesome sword in 21 days" or more combat intensive "remind me my cool spell ends in 13 rounds"

*Note: I don't believe this could conceivably cover every fictional calendar and not handle complicated "rule" based system, eg leap years or other rules that dynamically adjust time/days/months based on rules. It will need to be a somewhat static calendar system which should cover a very large bulk of game systems. Also, it will be assumed seconds is the smallest unit of time and year is the largest unit of time. Minutes/hours/days/months will be the other units of time.

Describe the solution you'd like Develop a series of macros to:

1. Define custom calendar
2. Adjust date time forward or backward
3. Add events for future dates (optionally tie to a tokenId)
4. Request next event date (should return tokenId's tied to event or next event for a tokenId passed in)
5. Return current timestamp (optionally formatted)
6. Possible UI to dispay calendar or just datetime with buttons to adjust time? (stretch goal, otherwise framework has to use a frame to create their own)

Describe alternatives you've considered Developed using current macro code but can be cumbersome and slow.

Additional context Gregorian Calendar will be default but user can define a custom calendar using a JSON supplied to a macro containing:

1. Number of seconds in a minute
2. Number of minutes in an hour
3. Number of hours in a day
4. Array of month objects containing name, number of days in month (month being an arbitrary name but technically could also be used to define things like "summer festival" which is 10 days between month 5 & 6, should this be a month though? thoughts?)
5. Optional: The above would be default time "units", json could hold optional object that defines units of time like Rounds and Turns, eg "round": { "unit": "seconds", "duration": 6 }

[Zuljita]

I do actively track minutes spent doing x and y, to know when we've hit time for a wandering monster check. Having better onboard support for that would be nice. Many of the Spells in my system of choice require maintenance every x minutes, hour or seconds. If there was an easy way to remind everyone of events we put into the calendar as that time comes, I'd use it a lot. Same with status effects, If I could say tag a status to expire in x seconds, and just keep moving a universal timer as things happen, I'd use the heck out of that feature.

[Syndaryl]

Comments:

Date/time management is a rabbit-hole of epic proportions. BE AFRAID. That said, there must be some standard libraries for Java that can be leaned on - do not try to do it all yourself. That way lies madness.

How would this calendar system tie to initiative? Not all game systems connect a fixed amount of "real world time" units to a turn (or "round", or whatever) but it's quite common to do so. It's very common to have duration/effects tied to a game turn (or "round", or "segment" or whatever), as a user I would want to use the same interface and system for tracking these combat length effects as longer out-of-combat effects. Not being able to do so would be confusing and frustrating.

That said, it's going to be painful but important to distinguish between games that

• assign time to an individual players turn (one second for each turn, means if Bob, then Marge, then Frank go, 3 seconds have passed)
• to the overall "combat round" (10 seconds to a combat round, it doesn't matter if it's only Bob, Marge, and Frank, or 50 orcs - once they've all taken their actions, 10 seconds have passed)
• systems like GURPS: a GURPS turn is 1 second long, but specifically one second from when you act to the beginning of your next action. Actions ostensibly overlap temporally.
• Other complex systems

IDK how to handle these problems.

Re alternate calendars - before defining a custom calendar, I'd see if you can support other real-world alternate calendars, in particular non-solar ones like the Chinese lunar calendar. Ideally there should be code for this already in your java time/calendar library that you can leverage without Framework writers filling out custom data.

The third general type are wheel-within-wheel systems like the Mayan solar-lunar calendar which would be... hopefully not an issue. Or will still require custom macro stuff, but hopefully can leverage the calendar support to require less macro work?

[Azhrei]

What she said. 👍

It seems to me there are two items that revolve around time: short term combat/encounter type stuff, and long term in-game stuff. The former could be integrated with the init panel and the latter would be more “calendar” oriented.

I think the combat stuff is more well-defined within most game systems and ought to be the easiest to implement. Whether actions overlap is something that a checkbox can handle, but other things (like the length of game time for each “turn”) would need to be configurable if it’s going to integrate with the calendar.

The configuration of the calendar will need to be multiple “months” in a list with each one a given length of time. The old Greyhawk calendar had 12 months but one (or was it two?) days between months for festivals/celebrations. Those day(s) would simply be another “month” with a length of one day.

[JamzTheMan]

Well, to be fair, calendar system is not an initiative system. How and when you "advance" time is still up to the framework. If after one pass of init, 2 seconds go by, update calendar by 2 seconds, if it's 1 second after each person, then it's that

Once the initiative panel has "events" that it can emit, then you could tie your macros in, but that's not what this set of macros is set to add.

It simply is a macro to "add a unit of time", get "current time", "store event until time x" and "get list of events"

Just like every other "macro" in MapTool, it MAY be usable for a given game system.

I would think these are closer to other Math.* functions. The "math" is just date math instead.

[melek]

Some scattered thoughts about this. Sorry I'm not more organized, but I have a lot of ideas. I'll try to put the more practical ideas up front ;)

• I think that focusing on basic timekeeping is a good start. Starting the campaign at '0' and adding time in seconds to a saved Time Elapsed campaign property via macros would be cool. From time elapsed, any calendar imaginable can be calculated so any campaign can create its own calendar based on a custom day-length and an arbitrary start date/time.
• Events could be a list of elapsed times with data attached to each entry. Perhaps a campaign setting could exist to optionally send the GM or All players a broadcast in chat if an event is passed when the clock is advanced.
• I'd love to see a built-in 'Calendar' panel that would display the current game date/time, list events to qualified players, and have a menu to expose the new features to non-programming users (advance/backtrack the clock, add/remove events).
• The initiative panel could be optionally assigned a per-battle, per-turn, or per-round amount of time to advance a battle clock that starts at 0 every time initiative is refreshed to Round 1. I would make this setting a campaign property with those settings and a 'none' option. I would also love to see elapsed battle time on the Initiative panel, maybe in the top-right corner.
• Adding battle time to time elapsed would often be desirable after a combat, perhaps it could be accomplished with an optional automatic setting when 'Round' is pressed to reset the round counter or done manually via macros. However it may work, games with time-bending effects would appreciate flexibility here to undo, stretch, or squish the amount of time added to the clock.

Beyond practical thoughts... I know what we really are discussing right now are macro functions, but I'm extremely excited imagining a 'Calendar' campaign properties tab to create multiple customized calendars defining day-length, weeks, months, intercalary days (like Azhrei mentioned), and events/holidays. UX-friendly ways to define game rulesets is always a plus in my eyes.

I totally second that date-keeping is super complicated. Frankly I don't think we could cover all possible calendar structures in a UI-provided calendar tab. For example, there is a Balinese calendar in use that has overlapping weeks of different lengths.

For a sci-fi game I ran, the day length changed wildly from planet to planet, and I tracked day/night and local calendars separately for each planet while the players used a interstellar calendar. The only way I could see maptool supporting this internally would be to let the player define multiple in-game calendars and key them to one another. Without a UI to navigate that, it would be mostly useless to non-programmers, and I don't expect anything like that.

edit: Had to fix typos/copy paste detritus.

[JamzTheMan]

Ya, I'm a little skittish about doing any sort of UI, especially using the current swing UI components. It could be as simple as showing a formated date/time and advance time buttons, but I could see people asking for "custom" buttons "i want to advance by 12 seconds at a time" or such... and in which case straight up macros/mt frame would just be better...

The interstellar calendar is a good point. For the life of me, I could not image every tracking that as a GM... Any game system that also puts out a custom crazy calendar just for the sake of doing it just seems silly these days. The GM will just abstract it if it is too difficult (which is why I applaud Paizo for making the Golarian calendar passed on Gregorian, just 4719 for 2019 and there stuff advances in real time)

Any hoo, I suppose we could make it so that you pass a calendar "name" when you create and get the calendar so you could have more than one calendar... Maybe that would be useful as well in case you had something like real time vs "matrix time" (thinking shadowrun old skool) that runs as a subset of real time? Although I would make that optional parameter that would use the "default" calendar if you don't specify calendar name...

I definitely want to stay away from linking it to the Initiative system for now, that already needs it's own update/rewrite per reasons listed above (doesn't work for Hero systems or SW/Deadlands, etc)

That Balinese calendar is crazy lol. BTW, I did a quick look but didn't find any "fictional" calendar libs for java or alternate calendar libs really but if anyone knows or finds one let me know.

I'll think about the json more, maybe let you do a full description of a "year" in json as a series of objects would be flexible enough?