Developer Diary #31: How Mods Access the Game Calendar
In short: MKA Engine makes the game's selected calendar available to mods and aligns map climate with the engine's calendar choice. A mod interprets dates by that same rule only when its author uses the information in the mod's date calculations.
What was the problem?
A mod is an add-on that brings new rules or content to a game. If a mod needs to start an event on a particular date or recognize a season, it has to know which month and year that day belongs to. But the number of days elapsed does not tell the whole story: in a 365-day calendar, February 28 is followed by March 1; in the leap-year Gregorian calendar, February 29 comes in between.
Diary #30 explained that a game chooses its calendar and that both dates and saves depend on that choice. The next question was how mods that use game dates would see the same choice. If every mod assumes its own year length, it could interpret the same game day as February 29 in one place and March 1 in another. Then the date shown to a player and a date-based mod action would no longer match.
Seasons have a similar relationship to the calendar. The map’s climate needs to determine which season a date falls in. If the game calendar includes leap days, the climate calculation also needs to account for that choice. Otherwise, the extra February day could make later season boundaries appear to drift.
How did we solve it?
While a game is running, a mod can obtain the selected calendar along with the current day. If its author uses that information in date calculations, the mod can convert elapsed days into years, months, and dates under the game's rule. The calendar choice is available rather than something the mod has to guess, but compatibility depends on the mod author using it.
That information does not rewrite a mod’s date calculations on its own. Mod authors need to use the game’s calendar when converting elapsed days into years, months, and dates. A calculation that assumes only 365-day years could interpret months and dates differently in a Gregorian game. The engine supplies the date and calendar choice; the mod decides what to do on a given day.
When a mod author uses the supplied calendar information across different in-game actions, those actions can interpret dates under the same game rule. The engine makes the selected calendar available; it does not automatically ensure that every mod follows it.
We also made the map climate follow the game’s calendar. When the game is built, the engine gives the climate the calendar it uses, so both use the same year and month pattern. Climate seasons are placed on a shared 365-day seasonal line. In a Gregorian leap year, February 29 takes the same seasonal day position as February 28. As a result, a season set to begin on March 1 still begins on March 1 in a leap year.
The season rule itself does not change. Game content decides when a season starts; the engine locates that date under the selected game calendar. How weather or seasons affect game decisions remains up to the game’s own rules.
What did we find?
The engine repository contains a mod test designed to start the same sample mod on February 28, 2024, advance two game steps, and check two ways of running it. Its expected results are February 29 in the Gregorian calendar and March 1 in the 365-day calendar, provided the sample uses the selected calendar; it also expects two in-game actions to report the same date. The test was not run during this task, so these are its specified expectations.
The source also contains a separate engine test designed to check that the map climate receives the 365-day calendar or Gregorian calendar selected by the game. Its scope is the match between the game and climate calendars, not every possible season-start date. The source date calculation maps February 29 to February 28’s seasonal position.
Why did we choose this approach?
MKA Engine makes the selected calendar available to mods; that shared information helps when a mod author uses it in date calculations. If a mod uses it, the mod can interpret a day under the game’s chosen calendar; the engine does not guarantee that every mod is compatible automatically. The map climate receives the engine’s choice and uses it for its seasonal calculation.
This diary does not repeat the calendar options described in Diary #30. That entry explained which calendar a game can choose and how a save preserves that choice. This one focuses on how the choice reaches mods and the climate calculation. Diary #13 covered mod execution boundaries, and Diary #26 covered population and market operations for mods; here we look at mods reading game time correctly.
What does it cost?
A mod cannot use the selected calendar during its initial registration; the information becomes available when its in-game work begins. The game’s choice determines which calendar it sees.
What comes next?
When mods and map seasons use the same date, different parts of a strategy world meet on one timeline. Making clear where that shared timeline is used helps keep the world’s history dependable.
Frequently asked questions
Does a mod choose the game calendar?
The game chooses it, and the engine makes the choice available to mods. A mod author must use that information for the mod’s date calculations to follow the same calendar.
Does February 29 change the season in a Gregorian game?
The climate calculation treats February 29 as the same seasonal day as February 28. A season that begins on March 1 therefore still begins on that date in a leap year.
Do different ways of running a mod see different dates?
The source test expects both modes of its sample mod to report the same date when the mod uses the selected calendar: February 29 in the 2024 Gregorian calendar and March 1 in the 365-day calendar. The test was not run during this task.
Can a mod read the calendar during its initial registration?
No. The game-calendar context is not available during registration; it becomes available when the mod begins its in-game work. Trying to read it too early returns an error.