Gantt This

Calendar Offset

4 min read

< Back to calendar overview

This page discusses how calendars work together. 3 YAML properties are used for this kind of calculation:

  • ´sharedOffset´ -> aligns where the calendar sits in time, controls time math.
  • ´startDay´ (optional) -> control when and if the calendar starts, controls visual rendering bounds.
  • ´endDay´ (optional) -> control when and if the calendar ends, controls visual rendering bounds.

Tip

If you do not plan to use more than one calendar, just keep sharedOffset at 0 (zero) and omit the other two.

Visual Example:

Scroll down for more in-depth explanation.

  • Gregorian: Has no startDay or endDay set, so its timeline extends infinitely in both directions.
  • Mayan Long Count: Has both startDay ({year: -3114, month: 8, day: 11}) and endDay (in the year 2012), drawing the calendar axis strictly within that window.
  • French Republican: Has a startDay (in the year 1792) when the calendar was created, but no endDay, so it continues drawing forward into the future.
  • Your dnd campaign might use The Dale Reckoning (DR) calendar, which anchors its global math epoch to Year 0 DR (sharedOffset). However, your campaign only takes place during a specific 5-year arc (1370 DR – 1375 DR). Setting startDay to 1370 and endDay to 1375 crops the rendered axis strictly to those active adventure years.
Multi-Calendar Axis Bounds & Alignment Demonstrating sharedOffset (Epoch Alignment) vs startDay / endDay (Axis Drawing Limits) Gregorian / Global Day 0 Anchor 1. Gregorian Calendar sharedOffset: 0 | startDay: none | endDay: none (Unbounded baseline) Year 0 / Epoch 2. Mayan Long Count sharedOffset: -3114y | startDay: -3114y | endDay: +2012y (Offset & bounds match) startDay (-3114y) endDay (+2012y) 3. French Republican Calendar sharedOffset: +1792y | startDay: +1792y | endDay: none (Creation year = axis start) startDay (+1792y) +1792y offset shift 4. Calendar of Harptos (D&D Campaign Arc) sharedOffset: -1000y | startDay: 1370 DR | endDay: 1375 DR (Epoch != Campaign Axis Bounds) 0 DR (Epoch Anchor) startDay (1370 DR) endDay (1375 DR)

Property sharedOffset

Imagine two calendars that each count time starting from their Year 1, Month 1, Day 1 (or other format). How does the plugin know how to position them relative to one another on a single unified timeline?

This property bridges that gap. It defines where a calendar’s Day One sits relative to an absolute, global Day Zero.

How It Works

Anchor Calendar (sharedOffset: 0): Setting an offset of 0 treats that calendar as the baseline anchor. For example, in a Gregorian setup, Day 1 corresponds to January 1, 1 AD, and Day 0 is December 31, 1 BC.

Shared Epoch (sharedOffset: A): Giving two calendars the same sharedOffset aligns their respective Day 1 instances on the exact same point on the timeline.

Offset Shifts (sharedOffset: ±X): Adjusting sharedOffset by ±X days shifts that calendar’s start date forward or backward along the global timeline by X days. For example, a calendar with sharedOffset: -15000 starts 15,000 days before the anchor calendar’s Day 1.

Properties ‘startDay’ and ‘endDay’

These properties define if and when a calendar starts and ends in time. Both are optional. They define a single day in time, not a year.

  • Omitting both creates a calendar which extends infinitely in both directions.
  • Adding startDay creates a lower bound for the calendar.
  • Adding endDay creates an upper bound for the calendar.

Format

All 3 of these properties share the same format:

number | {year: number, month: number, day: number}

When using only a number, it defines days - not years!
The alternative would be a combination of year, month, and day. These values represent Gregorian dates.

Real Calculation Example

The Mayan calendar started August 9th, 3114 BC. The following 3 examples would accomplish this result.

sharedOffset: {year: -3114, month: 8, day: 11}
 
sharedOffset: -1137507
 
sharedOffset:
  year: -3114
  month: 8
  day: 11

Graph View