# evennia.contrib.base_systems.custom_gametime.custom_gametime

Custom gametime

Contrib - Griatch 2017, vlgeoff 2017

This implements the evennia.utils.gametime module but supporting a custom calendar for your game world. It allows for scheduling events to happen at given in-game times, taking this custom calendar into account.

Usage:

Use as the normal gametime module, that is by importing and using the helper functions in this module in your own code. The calendar can be customized by adding the TIME_UNITS dictionary to your settings file. This maps unit names to their length, expressed in the smallest unit. Here’s the default as an example:

> TIME_UNITS = {

>   “sec”: 1, “min”: 60, “hr”: 60 * 60, “hour”: 60 * 60, “day”: 60 * 60 * 24, “week”: 60 * 60 * 24 * 7, “month”: 60 * 60 * 24 * 7 * 4, “yr”: 60 * 60 * 24 * 7 * 4 * 12, “year”: 60 * 60 * 24 * 7 * 4 * 12, }

When using a custom calendar, these time unit names are used as kwargs to the converter functions in this module.

`evennia.contrib.base_systems.custom_gametime.custom_gametime.``time_to_tuple`(seconds, *divisors)

  Helper function. Creates a tuple of even dividends given a range of divisors.

  Parameters

    - seconds (int) – Number of seconds to format

    - *divisors (int) – a sequence of numbers of integer dividends. The number of seconds will be integer-divided by the first number in this sequence, the remainder will be divided with the second and so on.

  Returns

    time (tuple) –

    This tuple has length len(*args)+1, with the

      last element being the last remaining seconds not evenly divided by the supplied dividends.

`evennia.contrib.base_systems.custom_gametime.custom_gametime.``gametime_to_realtime`(format=False, **kwargs)

  This method helps to figure out the real-world time it will take until an in-game time has passed. E.g. if an event should take place a month later in-game, you will be able to find the number of real-world seconds this corresponds to (hint: Interval events deal with real life seconds).

  Keyword Arguments

    - format (bool) – Formatting the output.

    - month etc (days,) – These are the names of time units that must match the settings.TIME_UNITS dict keys.

  Returns

    time (float or tuple) –

    The realtime difference or the same

      time split up into time units.

  Example

  gametime_to_realtime(days=2) -> number of seconds in real life from

    now after which 2 in-game days will have passed.

`evennia.contrib.base_systems.custom_gametime.custom_gametime.``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 interesting than the other way around.

  Keyword Arguments

    - times (int) – The various components of the time.

    - format (bool) – Formatting the output.

  Returns

    time (float or tuple) –

    The gametime difference or the same

      time split up into time units.

  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

`evennia.contrib.base_systems.custom_gametime.custom_gametime.``custom_gametime`(absolute=False)

  Return the custom game time as a tuple of units, as defined in settings.

  Parameters

    absolute (bool, optional) – return the relative or absolute time.

  Returns

    The tuple describing the game time. The length of the tuple is related to the number of unique units defined in the settings. By default, the tuple would be (year, month, week, day, hour, minute, second).

`evennia.contrib.base_systems.custom_gametime.custom_gametime.``real_seconds_until`(**kwargs)

  Return the real seconds until game time.

  If the game time is 5:00, TIME_FACTOR is set to 2 and you ask the number of seconds until it’s 5:10, then this function should return 300 (5 minutes).

  Parameters

    (str (times) – int): the time units.

  Example

  real_seconds_until(hour=5, min=10, sec=0)

  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)

`evennia.contrib.base_systems.custom_gametime.custom_gametime.``schedule`(callback, repeat=False, **kwargs)

  Call the callback when the game time is up.

  Parameters

    - callback (function) – The callback function that will be called. This must be a top-level function since the script will be persistent.

    - repeat (bool, optional) – Should the callback be called regularly?

    - day – int): The time units to call the callback; should match the keys of TIME_UNITS.

    - month – int): The time units to call the callback; should match the keys of TIME_UNITS.

    - (str (etc) – int): The time units to call the callback; should match the keys of TIME_UNITS.

  Returns

    script (Script) – The created script.

  Examples

  schedule(func, min=5, sec=0) # Will call next hour at :05. schedule(func, hour=2, min=30, sec=0) # Will call the next day at 02:30.

  Notes

  This function will setup a script that will be called when the time corresponds to the game time. If the game is stopped for more than a few seconds, the callback may be called with a slight delay. If repeat is set to True, the callback will be called again next time the game time matches the given time. The time is given in units as keyword arguments.

class `evennia.contrib.base_systems.custom_gametime.custom_gametime.``GametimeScript`(*args, **kwargs)

  Bases: `evennia.scripts.scripts.DefaultScript`

  Gametime-sensitive script.

  `at_script_creation`()

    The script is created.

  `at_repeat`()

    Call the callback and reset interval.

  exception `DoesNotExist`

    Bases: `evennia.scripts.scripts.DefaultScript.DoesNotExist`

  exception `MultipleObjectsReturned`

    Bases: `evennia.scripts.scripts.DefaultScript.MultipleObjectsReturned`

  `path` = 'evennia.contrib.base_systems.custom_gametime.custom_gametime.GametimeScript'
  `typename` = 'GametimeScript'