(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.

Special variable TIME¶

TIME¶

Access:	Get only
Type:	`TimeSpan`

The special variable TIME is used to get the current time.

Any time you perform arithmetic on TIME 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

Using TIME to detect when the physics have been updated ‘one tick’¶

kOS programs run however fast your computer’s animation rate will allow, which can flow and change from one moment to the next depending on load. However, the physics of the universe get updated at a fixed rate according to your game settings (the default, as of KSP 0.25, is 25 physics updates per second)

You can use the TIME special variable 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.