(For the documentation on controlling time warp, please see the timewarp page. This page is the documentation on the structure that holds an individual timestamp representing some universal moment in time.)

Time Span

In several places the game uses a TimeSpan format. This is a structure that gives the time in various formats. It also allows you to perform arithmetic on the time.

TimeSpan represents SIMULATED time

When you are examining a TimeSpan you are looking at the “in character” simulated time, not the “out of character” real world time. This is a very important distinction to remember, as the following points illustrate:

  • A TimeSpan does not count the time that was passing while the game was paused.
  • If you turn off your computer and don’t play the game for several days, the TimeSpan does not count this time.
  • If your game lags and stutters such that the simulation is taking 2 seconds of real time to calculate 1 second of game time, then the number of seconds that have passed according to a TimeSpan will be fewer than the number of seconds that have passed in the real world.

This allows you to use a TimeSpan such as is returned by the TIME special variable to make correct physics calculations.

Built-in function TIME

TIME(universal_time)
Parameters:
Returns:

A :struct`TimeSpan` of the time represented by the seconds timestamp passed in.

Return type:

TimeSpan

This creates a TimeSpan given a “universal time”, which is a number of seconds since the current game began, IN GAMETIME. example: TIME(3600) will give you a TimeSpan representing the moment exactly 1 hour (3600 seconds) since the current game first began.

The parameter is OPTIONAL. If you leave it off, and just call TIME(), then you end up getting the current time, which is the same thing that TIME gives you (without the parentheses).

Special variable TIME

TIME
Access:Get only
Type:TimeSpan

The special variable TIME is used to get the current time in the gameworld (not the real world where you’re sitting in a chair playing Kerbal Space Program.) It is the same thing as calling TIME with empty parentheses.

Using a TimeSpan

Any time you perform arithmetic on a TIMESPAN you get a result back that is also a TimeSpan. In other words, TIME is a TimeSpan, but TIME + 100 is also a TimeSpan.

Note that Kerbals do not have the concept of “months”:

TIME                // Gets the current universal time
TIME:CLOCK          // Universal time in H:M:S format(1:50:26)
TIME:CALENDAR       // Year 1, day 134
TIME:YEAR           // 1
TIME:DAY            // 134 : changes depending on KUNIVERSE:HOURSPERDAY
TIME:HOUR           // 1
TIME:MINUTE         // 50
TIME:SECOND         // 26
TIME:SECONDS        // Total Seconds since campaign began

Note that the notion of “how many hours in a day” and “how many days in a year” depends on the gameworld, not our real world. Kerbin has a shorter day, and a longer year in days as a result, than Earth. But there is an option in KSP’s main settings screen that can toggle this notion, and kOS will use whatever option you set it to.

Also note that the mods that alter the calendar for other solar systems, if they inject changes into KSP’s main game, will cause these values to change too.

Using TIME or TIME() to detect when the physics have been updated ‘one tick’

The game will make an effort to maintain regular physics updates at a fixed rate (defaulting to 25 updates per second), sacrificing animation rate as necessary. When the game is unable to maintain regular updates at this rate, the clock time (in the upper left of the screen) will turn yellow or red instead of green.

You can use the time reported by TIME to detect whether or not a real physics ‘tic’ has occurred yet, which can be important for scripts that need to take measurements from the simulated universe. If no physics tic has occurred, then TIME will still be exactly the same value.

Warning

Please be aware that the kind of calendar TimeSpan‘s use will depend on your KSP settings. The main KSP game supports both Kerbin time and Earth time and changing that setting will affect how TimeSpan works in kOS.

The difference is whether 1 day = 6 hours or 1 day = 24 hours.

You can access this setting from your script by using Kuniverse:HOURSPERDAY.

Warning

Beware the pitfall of confusing the TimeSpan:SECOND (singular) suffix with the TimeSpan:SECONDS (plural) suffix.

TimeSpan:SECOND

This is the whole number of remainder seconds leftover after all whole-number minutes, hours, days, and years have been subtracted out, and it’s never outside the range [0..60). It’s essentially the ‘seconds hand’ on a clock.

TimeSpan:SECONDS

This is the number of seconds total if you want to represent time as just a simple flat number without all the components. It’s the total count of the number of seconds since the beginning of time (Epoch). Because it’s a floating point number, it can store times less than 1 second. Note this is a measure of how much simulated Kerbal time has passed since the game began. People experienced at programming will be familiar with this concept. It’s the Kerbal’s version of “unix time”.

The epoch (time zero) in the KSP game is the time at which you first started the new campaign. All campaign games begin with the planets in precisely the same position and the clock set to zero years, zero days, zero hours, and so on.

structure TimeSpan
Suffix Type Description
CLOCK String “HH:MM:SS”
CALENDAR String “Year YYYY, day DDD”
SECOND Scalar (0-59) Second-hand number
MINUTE Scalar (0-59) Minute-hand number
HOUR Scalar (0-5) Hour-hand number
DAY Scalar (1-426) Day-hand number
YEAR Scalar Year-hand number
SECONDS Scalar (fractional) Total Seconds since Epoch (includes fractional partial seconds)

Note

This type is serializable.

TimeSpan:CLOCK
Access:Get only
Type:String

Time in (HH:MM:SS) format.

TimeSpan:CALENDAR
Access:Get only
Type:String

Day in “Year YYYY, day DDD” format. (Kerbals don’t have ‘months’.)

TimeSpan:SECOND
Access:Get only
Type:Scalar (0-59)

Second-hand number.

TimeSpan:MINUTE
Access:Get only
Type:Scalar (0-59)

Minute-hand number

TimeSpan:HOUR
Access:Get only
Type:Scalar (0-5) or (0-23)

Hour-hand number. Kerbin has six hours in its day.

TimeSpan:DAY
Access:Get only
Type:Scalar (1-426) or (1-356)

Day-hand number. Kerbin has 426 days in its year.

TimeSpan:YEAR
Access:Get only
Type:Scalar

Year-hand number

TimeSpan:SECONDS
Access:Get only
Type:Scalar (float)

Total Seconds since Epoch. Epoch is defined as the moment your current saved game’s universe began (the point where you started your campaign). Can be very precise.