Change custom_gametime contrib to start days/weeks/months from 1 instead of from 0. Resolve #1753

CHANGELOG.md

@@ -116,6 +116,8 @@ Up requirements to Django 3.2+, Twisted 21+
   with other handlers.
 - Make `DefaultScript.delete`, `DefaultChannel.delete` and `DefaultAccount.delete` return
   bool True/False if deletion was successful (like `DefaultObject.delete` before them)
+- `contrib.custom_gametime` days/weeks/months now always starts from 1 (to match
+  the standard calendar form ... there is no month 0 every year after all).
 
 ### Evennia 0.9.5 (2019-2020)
 

docs/source/Howto/Gametime-Tutorial.md

@@ -216,7 +216,10 @@ TIME_UNITS = {
 ```
 
 Notice we have set a time epoch of 0.  Using a custom calendar, we will come up with a nice display
-of time on our own. In our case the game time starts at year 0, month 0, day 0, and at midnight.
+of time on our own. In our case the game time starts at year 0, month 1, day 1, and at midnight.
+
+> Year, hour, minute and sec starts from 0, month, week and day starts from 1, this makes them
+> behave consistently with the standard time.
 
 Note that while we use "month", "week" etc in the settings, your game may not use those terms in-
 game, instead referring to them as "cycles", "moons", "sand falls" etc. This is just a matter of you

evennia/contrib/custom_gametime.py

@@ -125,7 +125,7 @@ def gametime_to_realtime(format=False, **kwargs):
     return rtime
 
 
-def realtime_to_gametime(secs=0, mins=0, hrs=0, days=0, weeks=0, months=0, yrs=0, format=False):
+def realtime_to_gametime(secs=0, mins=0, hrs=0, days=1, weeks=1, months=1, yrs=0, format=False):
     """
     This method calculates how much in-game time a real-world time
     interval would correspond to. This is usually a lot less
@@ -139,10 +139,24 @@ def realtime_to_gametime(secs=0, mins=0, hrs=0, days=0, weeks=0, months=0, yrs=0
         time (float or tuple): The gametime difference or the same
             time split up into time units.
 
-     Example:
+    Note:
+        days/weeks/months start from 1 (there is no day/week/month 0). This makes it
+            consistent with the real world datetime.
+
+    Raises:
+        ValueError: If trying to add a days/weeks/months of <=0.
+
+    Example:
       realtime_to_gametime(days=2) -> number of game-world seconds
 
     """
+    if days <= 0 or weeks <= 0 or months <= 0:
+        raise ValueError("realtime_to_gametime: days/weeks/months cannot be set <= 0, "
+                         "they start from 1.")
+
+    # days/weeks/months start from 1, we need to adjust them to work mathematically.
+    days, weeks, months = days - 1, weeks - 1, months - 1
+
     gtime = TIMEFACTOR * (
         secs
         + mins * 60
@@ -198,6 +212,9 @@ def real_seconds_until(**kwargs):
     Returns:
         The number of real seconds before the given game time is up.
 
+    Notes:
+        day/week/month start from 1, not from 0 (there is no month 0 for example)
+
     """
     current = gametime.gametime(absolute=True)
     units = sorted(set(UNITS.values()), reverse=True)
@@ -209,9 +226,13 @@ def real_seconds_until(**kwargs):
     units.append(1)
     higher_unit = None
     for unit, value in kwargs.items():
+        if unit in ("day", "week", "month"):
+            # these start from 1 so we must adjust
+            value -= 1
+
         # Get the unit's index
         if unit not in UNITS:
-            raise ValueError("unknown unit".format(unit))
+            raise ValueError(f"Unknown unit '{unit}'. Allowed: {', '.join(UNITS)}")
 
         seconds = UNITS[unit]
         index = units.index(seconds)

evennia/contrib/tests.py

@@ -894,13 +894,13 @@ class TestCustomGameTime(EvenniaTest):
         )
 
     def test_realtime_to_gametime(self):
-        self.assertEqual(custom_gametime.realtime_to_gametime(days=2, mins=34), 349680.0)
+        self.assertEqual(custom_gametime.realtime_to_gametime(days=3, mins=34), 349680.0)
         self.assertEqual(
-            custom_gametime.realtime_to_gametime(days=2, mins=34, format=True),
+            custom_gametime.realtime_to_gametime(days=3, mins=34, format=True),
             (0, 0, 0, 4, 1, 8, 0),
         )
         self.assertEqual(
-            custom_gametime.realtime_to_gametime(format=True, days=2, mins=4), (0, 0, 0, 4, 0, 8, 0)
+            custom_gametime.realtime_to_gametime(format=True, days=3, mins=4), (0, 0, 0, 4, 0, 8, 0)
         )
 
     def test_custom_gametime(self):
@@ -909,7 +909,7 @@ class TestCustomGameTime(EvenniaTest):
 
     def test_real_seconds_until(self):
         self.assertEqual(
-            custom_gametime.real_seconds_until(year=2300, month=11, day=6), 31911667199.77
+            custom_gametime.real_seconds_until(year=2300, month=12, day=7), 31911667199.77
         )
 
     def test_schedule(self):