Properties & Methods

v4.0

Properties

When gameTime is not specified (i.e. defaults to -1), the Now() gameTime will be used.

Day and Month have an additional bool shiftForNumbericalDisplay, which is false by default. When true, the value returned will be 1 higher, since humans don't use "0" for the first day or month.

public int GameTime => _gameTime; // Returns an int

// Return ints
public int Minute(int gameTime = -1)
public int Hour(int gameTime = -1)
public int Day(int gameTime = -1, bool shiftForNumericalDisplay = false)
public int Week(int gameTime = -1)
public int Month(int gameTime = -1, bool shiftForNumericalDisplay = false)
public int Season(int gameTime = -1)
public int Year(int gameTime = -1)

// Return strings
public string DayName(int gameTime = -1)
public string MonthName(int gameTime = -1)
public string SeasonName(int gameTime = -1)

public int DaysPerWeek
public int NumberOfMonths
public int NumberOfSeasons
public int DaysPerMonth
public int MinutesPerHour
public int HoursPerDay
public int DaysPerYear
public int DaysPerSeason // There could be different number of days per season if the year is not divisible!
public int WeeksPerYear // Any last partial week is counted!
public float DaysPerSeasonFloat
public float WeeksPerYearFloat

// In-game time
public float SecondsPerGameMinute
public float SecondsPerGameHour
public float SecondsPerGameDay
public float SecondsPerGameWeek
public float SecondsPerGameMonth
public float SecondsPerGameSeason
public float SecondsPerGameYear

// 1 in-game minute = 1 "GameMinute" -- these are the same as "MinutesPer"
public int GameTimePerHour => minutesPerHour; // minutesPerHour is the same as GameTimePerHour!
public int GameTimePerDay
public int GameTimePerWeek
public int GameTimePerMonth
public int GameTimePerSeason
public int GameTimePerYear

Methods

The Gametime Module contains many methods which perform time and date calculations, and may be quite convenient for your project.

FullDate() returns a human-readable string, and can be formatted in a variety of ways.

public string FullDate(int gameTime = -1 // -1 uses = Now()
    , bool numericalDisplay = true // Ex. 6/12/2023
    , bool includeTime = true // Ex. 6/12/2023 10:19pm
    , bool includeDayOfWeek = true // Ex. Monday June 12, 2023 10:20 pm
    , string dateSeparator = "/") // Ex 6/12/2023

These methods will get a gameTime value back.

public float Now(bool includeSubtime = true)

// Returns Now() plus or minus a gameTime value based on the read-world minutes
public float LaterRealTime(float realWorldMinutes)
public float EarlierRealTime(float realWorldMinutes)

// Returns Now() plus or minus the values in the provided TimeSpan object
public float Later(TimeSpan span)
public float Earlier(TimeSpan span)

// Returns Now() plus or minus the values provided
public float Later(float seconds = 0f, float minutes = 0f, float hours = 0f
    , float days = 0f, float weeks = 0f, float months = 0f, float seasons = 0f
    , float years = 0f)
public float Earlier(float seconds = 0f, float minutes = 0f, float hours = 0f
    , float days = 0f, float weeks = 0f, float months = 0f, float seasons = 0f
    , float years = 0f)
    
// Gets the gameTime for the start of the season in the year provided
public float SeasonGameTime(int season, int year = -1) // -1 = Current Year

These methods will manage gameTime in some way.

// Handles real-world values, converting them to in-game additions
public void AddRealWorldSeconds(float realWorldSeconds)
public void AddRealWorldMinutes(int realWorldMinutes)
public void AddRealWorldHours(int realWorldHours)

// Handles in-game values [Use negative values to subtract]
public void AddMinutes(float minutesToAdd)
public void AddHours(float hoursToAdd)
public void AddDays(float daysToAdd)
public void AddWeeks(float weeksToAdd)
public void AddMonths(float monthsToAdd)
public void AddYears(float yearsToAdd)
public void AddSeasons(float seasonsToAdd)

Converting & Comparing

Convert between "Real Seconds", GameTime, TimeSpan, and DatePart

// Real Seconds to...
public TimeSpan RealSecondsToTimeSpan(float realSeconds)
public float RealSecondsToGameTime(float realSeconds)
public float RealSecondsToDatePart(DatePart datePart, float realSeconds)

// GameTime to...
private TimeSpan GameTimeToTimeSpan(float gameTime) 
public float GameTimeToRealSeconds(float gameTime)
public float GameTimeToDatePart(DatePart datePart, float gameTime)

// TimeSpan to...
public float TimespanToGameTime(TimeSpan timeSpan)
public float TimeSpanToRealSeconds(TimeSpan timeSpan)
public float TimeSpanToDatePart(DatePart datePart, TimeSpan timeSpan)

/// DatePart to...
public float DatePartToGameTime(DatePart datePart, float value)
public float DatePartToRealSeconds(DatePart datePart, float value)
public TimeSpan DatePartToTimeSpan(DatePart datePart, float value)

We use Real Seconds for converting between real-world time and in-game gameTime, because it is the lowest common measurement, using the variable realWorldSecondsPerGameMinute

This value is the basis for all in-game time.

DatePart comparisons to gameTime

When gameTime is not provided, it defaults to Now()

// Returns the current lowest value of datePart compared to the next greatest
// denominator.
public int GetDatePart(DatePart datePart, float gameTime = -1)

// Returns the selected datePart since the last comparison DatePart
public float DatePartInto(DatePart datePart, DatePart comparison, float gameTime = -1)

// Returns the datePart until the next comparison DatePart
public float DatePartUntil(DatePart datePart, DatePart comparison, float gameTime = -1)

Examples

// Hours until the next day starts
var hoursUntilMidnight = DatePartUntil(DatePart.Hour, DatePart.Day);

// Days into the current season, for a specific gameTime
var daysIntoSeason = DatePartInto(DatePart.Day, DatePart.Season, savedGameTime);

These helper methods may be more convenient to use.

// DatePart past the last comparison DatePart
public float SecondsInto(DatePart comparison, float gameTime = -1)
public float MinutesInto(DatePart comparison, float gameTime = -1)
public float HoursInto(DatePart comparison, float gameTime = -1)
public float DaysInto(DatePart comparison, float gameTime = -1)
public float WeeksInto(DatePart comparison, float gameTime = -1)
public float MonthsInto(DatePart comparison, float gameTime = -1)
public float SeasonsInto(DatePart comparison, float gameTime = -1)

// DatePart until the next comparison DatePart
public float SecondsUntil(DatePart comparison, float gameTime = -1)
public float MinutesUntil(DatePart comparison, float gameTime = -1)
public float HoursUntil(DatePart comparison, float gameTime = -1)
public float DaysUntil(DatePart comparison, float gameTime = -1)
public float WeeksUntil(DatePart comparison, float gameTime = -1)
public float MonthsUntil(DatePart comparison, float gameTime = -1) 
public float SeasonsUntil(DatePart comparison, float gameTime = -1)

// DatePart comparisons to New Year
public float SecondsSinceNewYear(int gameTime = -1)
public float MinutesSinceNewYear(int gameTime = -1)
public float HoursSinceNewYear(int gameTime = -1)
public float DaysSinceNewYear(int gameTime = -1)
public float WeeksSinceNewYear(int gameTime = -1)
public float MonthsSinceNewYear(int gameTime = -1)

public float SecondsUntilNewYear(int gameTime = -1)
public float MinutesUntilNewYear(int gameTime = -1)
public float HoursUntilNewYear(int gameTime = -1)
public float DaysUntilNewYear(int gameTime = -1)
public float WeeksUntilNewYear(int gameTime = -1)
public float MonthsUntilNewYear(int gameTime = -1)
public float SeasonsUntilNewYear(int gameTime = -1)