# tecs.platform.time


Platform clocks, calendar time, blocking delays, and frame timing.

The application calls `step` once per iteration and passes the result to the
world. `maxDelta` clamps long stalls before simulation sees them. Game code
may read `now`, but it must not call `step` because that moves the frame
baseline.

`now` is monotonic and is the clock for elapsed time and deadlines. `wallNow`
reads the adjustable realtime clock instead and returns an exact Unix
timestamp:

```teal
local stamp <const> = assert(tecs.platform.time.wallNow())
local localTime <const> = assert(
    tecs.platform.time.toDateTime(stamp, true)
)
print(
    ("%04d-%02d-%02d %02d:%02d"):format(
        localTime.year,
        localTime.month,
        localTime.day,
        localTime.hour,
        localTime.minute
    )
)
```

The delay functions block the calling thread. They belong in startup,
headless tools, and measurements, not in a frame. `delayPrecise` may busy
wait to approach its requested duration.

SDL's callback timer registration is deliberately absent. SDL invokes those
callbacks from a timer thread, which cannot safely enter LuaJIT. Game timers
store deadlines against `now` and dispatch from a system, or use
`tecs.sequence` when they belong to simulated time.

Install a provider to replace measured frame deltas during replay:

```teal
local recorded <const>: {number} = {1 / 60, 1 / 60, 1 / 30}
local frame = 0

tecs.platform.time.provider = function(realDt: number): number
    frame = frame + 1
    -- Nil keeps the measurement, so a run past the end of the recording is
    -- live again.
    return recorded[frame]
end
```

Returning nil keeps the measured delta. Pair this provider with
`tecs.platform.events.source` to replay frame timing and platform events together.
`now` always reads the monotonic platform clock and ignores the replay
provider.

## Module contents

### Types

| Type | Kind | Description |
| --- | --- | --- |
| [`DateTime`](/modules/platform/time/#tecs.platform.time.DateTime) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Represents a calendar date, time, and UTC offset. |
| [`LocalePreferences`](/modules/platform/time/#tecs.platform.time.LocalePreferences) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Represents the current locale's preferred date and clock layouts. |
| [`Timestamp`](/modules/platform/time/#tecs.platform.time.Timestamp) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Represents an exact instant on the Unix realtime clock. |
| [`WindowsTime`](/modules/platform/time/#tecs.platform.time.WindowsTime) | <span class="tealdoc-kind-badge tealdoc-kind-record">record</span> | Represents the two exact words of a Windows FILETIME value. |

### Functions

| Function | Kind | Description |
| --- | --- | --- |
| [`dayOfWeek`](/modules/platform/time/#tecs.platform.time.dayOfWeek) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the weekday of a calendar date. |
| [`dayOfYear`](/modules/platform/time/#tecs.platform.time.dayOfYear) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the zero-based day within a calendar year. |
| [`daysInMonth`](/modules/platform/time/#tecs.platform.time.daysInMonth) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Returns the number of days in a calendar month. |
| [`delay`](/modules/platform/time/#tecs.platform.time.delay) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Blocks the calling thread for at least a number of milliseconds. |
| [`delayNanoseconds`](/modules/platform/time/#tecs.platform.time.delayNanoseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Blocks the calling thread for at least a number of nanoseconds. |
| [`delayPrecise`](/modules/platform/time/#tecs.platform.time.delayPrecise) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Blocks while approaching a nanosecond delay as closely as possible. |
| [`fromDateTime`](/modules/platform/time/#tecs.platform.time.fromDateTime) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts calendar fields to an exact Unix timestamp. |
| [`fromWindowsTime`](/modules/platform/time/#tecs.platform.time.fromWindowsTime) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts a Windows FILETIME to an exact Unix timestamp. |
| [`localePreferences`](/modules/platform/time/#tecs.platform.time.localePreferences) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads the current locale's preferred date order and clock layout. |
| [`microsecondsToNanoseconds`](/modules/platform/time/#tecs.platform.time.microsecondsToNanoseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts whole microseconds to nanoseconds. |
| [`millisecondsToNanoseconds`](/modules/platform/time/#tecs.platform.time.millisecondsToNanoseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts whole milliseconds to nanoseconds. |
| [`nanosecondsToMicroseconds`](/modules/platform/time/#tecs.platform.time.nanosecondsToMicroseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts nanoseconds to microseconds. |
| [`nanosecondsToMilliseconds`](/modules/platform/time/#tecs.platform.time.nanosecondsToMilliseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts nanoseconds to milliseconds. |
| [`nanosecondsToSeconds`](/modules/platform/time/#tecs.platform.time.nanosecondsToSeconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts nanoseconds to seconds. |
| [`now`](/modules/platform/time/#tecs.platform.time.now) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads the monotonic counter in seconds. |
| [`performanceCounter`](/modules/platform/time/#tecs.platform.time.performanceCounter) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads the platform's raw high-resolution counter. |
| [`performanceFrequency`](/modules/platform/time/#tecs.platform.time.performanceFrequency) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads the frequency of the platform's high-resolution counter. |
| [`provider`](/modules/platform/time/#tecs.platform.time.provider) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Caller-writable. Installs a replay hook that receives the measured frame delta. |
| [`reset`](/modules/platform/time/#tecs.platform.time.reset) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Resets the baseline so the next step measures from now. |
| [`secondsToNanoseconds`](/modules/platform/time/#tecs.platform.time.secondsToNanoseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts whole seconds to nanoseconds. |
| [`step`](/modules/platform/time/#tecs.platform.time.step) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Advances one frame and returns the dt the world should receive. |
| [`ticksMilliseconds`](/modules/platform/time/#tecs.platform.time.ticksMilliseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads milliseconds elapsed since SDL initialized. |
| [`ticksNanoseconds`](/modules/platform/time/#tecs.platform.time.ticksNanoseconds) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads nanoseconds elapsed since SDL initialized. |
| [`toDateTime`](/modules/platform/time/#tecs.platform.time.toDateTime) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts an exact Unix timestamp to calendar fields. |
| [`toWindowsTime`](/modules/platform/time/#tecs.platform.time.toWindowsTime) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Converts an exact Unix timestamp to a Windows FILETIME. |
| [`wallNow`](/modules/platform/time/#tecs.platform.time.wallNow) | <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span> | Reads the adjustable realtime clock. |

### Values

| Value | Type | Description |
| --- | --- | --- |
| [`maxDelta`](/modules/platform/time/#tecs.platform.time.maxDelta) | `number` | Caller-writable. Sets the longest frame delta in seconds that step returns. |
| [`microsecondsPerSecond`](/modules/platform/time/#tecs.platform.time.microsecondsPerSecond) | `integer` | Read-only. Reports the number of microseconds in one second. |
| [`millisecondsPerSecond`](/modules/platform/time/#tecs.platform.time.millisecondsPerSecond) | `integer` | Read-only. Reports the number of milliseconds in one second. |
| [`nanosecondsPerMicrosecond`](/modules/platform/time/#tecs.platform.time.nanosecondsPerMicrosecond) | `integer` | Read-only. Reports the number of nanoseconds in one microsecond. |
| [`nanosecondsPerMillisecond`](/modules/platform/time/#tecs.platform.time.nanosecondsPerMillisecond) | `integer` | Read-only. Reports the number of nanoseconds in one millisecond. |
| [`nanosecondsPerSecond`](/modules/platform/time/#tecs.platform.time.nanosecondsPerSecond) | `integer` | Read-only. Reports the number of nanoseconds in one second. |
| [`nominal`](/modules/platform/time/#tecs.platform.time.nominal) | `number` | Caller-writable. Sets the nominal frame delta in seconds. |

## Types

<a id="tecs.platform.time.DateTime"></a>
### tecs.platform.time.DateTime <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Represents a calendar date, time, and UTC offset.
Read-only. Exposes the calendar date and time record.


```teal
record tecs.platform.time.DateTime
    year: integer
    month: integer
    day: integer
    hour: integer
    minute: integer
    second: integer
    nanosecond: integer
    dayOfWeek: integer
    utcOffset: integer
end
```

<a id="tecs.platform.time.DateTime.year"></a>
#### tecs.platform.time.DateTime.year <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the calendar year.


```teal
tecs.platform.time.DateTime.year: integer
```

<a id="tecs.platform.time.DateTime.month"></a>
#### tecs.platform.time.DateTime.month <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the month from 1 through 12.


```teal
tecs.platform.time.DateTime.month: integer
```

<a id="tecs.platform.time.DateTime.day"></a>
#### tecs.platform.time.DateTime.day <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the day of the month from 1 through 31, bounded
further by the selected month and year.


```teal
tecs.platform.time.DateTime.day: integer
```

<a id="tecs.platform.time.DateTime.hour"></a>
#### tecs.platform.time.DateTime.hour <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the hour from 0 through 23.


```teal
tecs.platform.time.DateTime.hour: integer
```

<a id="tecs.platform.time.DateTime.minute"></a>
#### tecs.platform.time.DateTime.minute <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the minute from 0 through 59.


```teal
tecs.platform.time.DateTime.minute: integer
```

<a id="tecs.platform.time.DateTime.second"></a>
#### tecs.platform.time.DateTime.second <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the second from 0 through 60. The last value
represents a possible leap second.


```teal
tecs.platform.time.DateTime.second: integer
```

<a id="tecs.platform.time.DateTime.nanosecond"></a>
#### tecs.platform.time.DateTime.nanosecond <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the fractional second from 0 through 999999999
nanoseconds.


```teal
tecs.platform.time.DateTime.nanosecond: integer
```

<a id="tecs.platform.time.DateTime.dayOfWeek"></a>
#### tecs.platform.time.DateTime.dayOfWeek <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports the weekday from 0 through 6, with Sunday at zero.
`fromDateTime` ignores this field.


```teal
tecs.platform.time.DateTime.dayOfWeek: integer
```

<a id="tecs.platform.time.DateTime.utcOffset"></a>
#### tecs.platform.time.DateTime.utcOffset <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets seconds east of UTC. A value of zero represents
UTC, and `toDateTime` fills the platform's offset for local time.


```teal
tecs.platform.time.DateTime.utcOffset: integer
```

<a id="tecs.platform.time.LocalePreferences"></a>
### tecs.platform.time.LocalePreferences <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Represents the current locale's preferred date and clock layouts.
Read-only. Exposes the locale preference record.


```teal
record tecs.platform.time.LocalePreferences
    dateFormat: string
    timeFormat: string
end
```

<a id="tecs.platform.time.LocalePreferences.dateFormat"></a>
#### tecs.platform.time.LocalePreferences.dateFormat <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports `"yearMonthDay"`, `"dayMonthYear"` or
`"monthDayYear"`.


```teal
tecs.platform.time.LocalePreferences.dateFormat: string
```

<a id="tecs.platform.time.LocalePreferences.timeFormat"></a>
#### tecs.platform.time.LocalePreferences.timeFormat <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Read-only. Reports `"twentyFourHour"` or `"twelveHour"`.


```teal
tecs.platform.time.LocalePreferences.timeFormat: string
```

<a id="tecs.platform.time.Timestamp"></a>
### tecs.platform.time.Timestamp <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Represents an exact instant on the Unix realtime clock.
Read-only. Exposes the exact Unix timestamp record.


```teal
record tecs.platform.time.Timestamp
    seconds: integer
    nanosecond: integer
end
```

<a id="tecs.platform.time.Timestamp.seconds"></a>
#### tecs.platform.time.Timestamp.seconds <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets whole seconds since 1970-01-01 00:00:00 UTC. A
negative value names an instant before the epoch.


```teal
tecs.platform.time.Timestamp.seconds: integer
```

<a id="tecs.platform.time.Timestamp.nanosecond"></a>
#### tecs.platform.time.Timestamp.nanosecond <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the normalized remainder within `seconds`, from
zero through 999999999.


```teal
tecs.platform.time.Timestamp.nanosecond: integer
```

<a id="tecs.platform.time.WindowsTime"></a>
### tecs.platform.time.WindowsTime <span class="tealdoc-kind-badge tealdoc-kind-record">record</span>

Represents the two exact words of a Windows FILETIME value.
Read-only. Exposes the Windows FILETIME record.


```teal
record tecs.platform.time.WindowsTime
    low: integer
    high: integer
end
```

<a id="tecs.platform.time.WindowsTime.low"></a>
#### tecs.platform.time.WindowsTime.low <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the low unsigned 32 bits.


```teal
tecs.platform.time.WindowsTime.low: integer
```

<a id="tecs.platform.time.WindowsTime.high"></a>
#### tecs.platform.time.WindowsTime.high <span class="tealdoc-kind-badge tealdoc-kind-field">field</span>

Caller-writable. Sets the high unsigned 32 bits.


```teal
tecs.platform.time.WindowsTime.high: integer
```

## Functions

<a id="tecs.platform.time.dayOfWeek"></a>
### tecs.platform.time.dayOfWeek <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the weekday of a calendar date.



```teal
function tecs.platform.time.dayOfWeek(
    year: integer, month: integer, day: integer
): integer, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `year` | `integer` | The caller supplies the calendar year. |
| `month` | `integer` | The caller supplies a month from 1 through 12. |
| `day` | `integer` | The caller supplies a valid day within that month. |

#### Returns

| Type | Description |
| --- | --- |
| `integer` | A value from 0 through 6, with Sunday at zero, or nil for an invalid date. |
| `string` | The SDL error when no value is returned. |

<a id="tecs.platform.time.dayOfYear"></a>
### tecs.platform.time.dayOfYear <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the zero-based day within a calendar year.



```teal
function tecs.platform.time.dayOfYear(
    year: integer, month: integer, day: integer
): integer, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `year` | `integer` | The caller supplies the calendar year. |
| `month` | `integer` | The caller supplies a month from 1 through 12. |
| `day` | `integer` | The caller supplies a valid day within that month. |

#### Returns

| Type | Description |
| --- | --- |
| `integer` | A value from 0 through 365 on success, or nil for an invalid date. |
| `string` | The SDL error when no value is returned. |

<a id="tecs.platform.time.daysInMonth"></a>
### tecs.platform.time.daysInMonth <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Returns the number of days in a calendar month.



```teal
function tecs.platform.time.daysInMonth(
    year: integer, month: integer
): integer, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `year` | `integer` | The caller supplies the year whose leap status controls February. |
| `month` | `integer` | The caller supplies a month from 1 through 12. |

#### Returns

| Type | Description |
| --- | --- |
| `integer` | The number of days on success, or nil for an invalid month. |
| `string` | The SDL error when no count is returned. |

<a id="tecs.platform.time.delay"></a>
### tecs.platform.time.delay <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Blocks the calling thread for at least a number of milliseconds.

OS scheduling may make the delay longer. Do not call this from a frame.



```teal
function tecs.platform.time.delay(milliseconds: integer)
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `milliseconds` | `integer` | The caller supplies a nonnegative integer through 4294967295. |

#### Returns

None.

<a id="tecs.platform.time.delayNanoseconds"></a>
### tecs.platform.time.delayNanoseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Blocks the calling thread for at least a number of nanoseconds.

OS scheduling may make the delay longer. Do not call this from a frame.



```teal
function tecs.platform.time.delayNanoseconds(nanoseconds: number)
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `nanoseconds` | `number` | The caller supplies a nonnegative safe integer. |

#### Returns

None.

<a id="tecs.platform.time.delayPrecise"></a>
### tecs.platform.time.delayPrecise <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Blocks while approaching a nanosecond delay as closely as possible.

SDL may busy wait, and OS scheduling may still make the delay longer. Do
not call this from a frame.



```teal
function tecs.platform.time.delayPrecise(nanoseconds: number)
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `nanoseconds` | `number` | The caller supplies a nonnegative safe integer. |

#### Returns

None.

<a id="tecs.platform.time.fromDateTime"></a>
### tecs.platform.time.fromDateTime <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts calendar fields to an exact Unix timestamp.

`utcOffset` defaults to zero. `hour`, `minute`, `second`, and `nanosecond`
also default to zero. SDL ignores `dayOfWeek`.



```teal
function tecs.platform.time.fromDateTime(
    dateTime: DateTime
): Timestamp, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `dateTime` | [`DateTime`](/modules/platform/time/#tecs.platform.time.DateTime) | The caller supplies a valid Gregorian calendar date and seconds east of UTC. |

#### Returns

| Type | Description |
| --- | --- |
| [`Timestamp`](/modules/platform/time/#tecs.platform.time.Timestamp) | A normalized timestamp on success, or nil for invalid fields or a date outside SDL's range. |
| `string` | The SDL error when no timestamp is returned. |

<a id="tecs.platform.time.fromWindowsTime"></a>
### tecs.platform.time.fromWindowsTime <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts a Windows FILETIME to an exact Unix timestamp.

SDL clamps a FILETIME outside its roughly 1677 through 2262 range. The
resulting nanoseconds are a multiple of 100.



```teal
function tecs.platform.time.fromWindowsTime(
    windowsTime: WindowsTime
): Timestamp
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `windowsTime` | [`WindowsTime`](/modules/platform/time/#tecs.platform.time.WindowsTime) | The caller supplies exact unsigned 32-bit words. |

#### Returns

| Type | Description |
| --- | --- |
| [`Timestamp`](/modules/platform/time/#tecs.platform.time.Timestamp) | A normalized timestamp. |

<a id="tecs.platform.time.localePreferences"></a>
### tecs.platform.time.localePreferences <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads the current locale's preferred date order and clock layout.

The platform query may be slow and preferences may change outside the
process. A caller that needs the result frequently should cache it and
refresh deliberately.



```teal
function tecs.platform.time.localePreferences(): LocalePreferences, string
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| [`LocalePreferences`](/modules/platform/time/#tecs.platform.time.LocalePreferences) | A fresh preference record on success, or nil on failure. |
| `string` | The SDL error when preferences are unavailable. |

<a id="tecs.platform.time.microsecondsToNanoseconds"></a>
### tecs.platform.time.microsecondsToNanoseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts whole microseconds to nanoseconds.



```teal
function tecs.platform.time.microsecondsToNanoseconds(
    microseconds: integer
): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `microseconds` | `integer` | The caller supplies a nonnegative integer no larger than 9007199254740 so the integer result remains exact. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | The same duration in nanoseconds. |

<a id="tecs.platform.time.millisecondsToNanoseconds"></a>
### tecs.platform.time.millisecondsToNanoseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts whole milliseconds to nanoseconds.



```teal
function tecs.platform.time.millisecondsToNanoseconds(
    milliseconds: integer
): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `milliseconds` | `integer` | The caller supplies a nonnegative integer no larger than 9007199254 so the integer result remains exact. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | The same duration in nanoseconds. |

<a id="tecs.platform.time.nanosecondsToMicroseconds"></a>
### tecs.platform.time.nanosecondsToMicroseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts nanoseconds to microseconds.



```teal
function tecs.platform.time.nanosecondsToMicroseconds(
    nanoseconds: number
): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `nanoseconds` | `number` | The caller supplies any numeric duration. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | The duration divided by one thousand. |

<a id="tecs.platform.time.nanosecondsToMilliseconds"></a>
### tecs.platform.time.nanosecondsToMilliseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts nanoseconds to milliseconds.



```teal
function tecs.platform.time.nanosecondsToMilliseconds(
    nanoseconds: number
): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `nanoseconds` | `number` | The caller supplies any numeric duration. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | The duration divided by one million. |

<a id="tecs.platform.time.nanosecondsToSeconds"></a>
### tecs.platform.time.nanosecondsToSeconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts nanoseconds to seconds.



```teal
function tecs.platform.time.nanosecondsToSeconds(
    nanoseconds: number
): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `nanoseconds` | `number` | The caller supplies any numeric duration. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | The duration divided by one billion. |

<a id="tecs.platform.time.now"></a>
### tecs.platform.time.now <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads the monotonic counter in seconds. Not affected by the provider.



```teal
function tecs.platform.time.now(): number
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `number` | A high-resolution elapsed-time reading with an arbitrary origin. |

<a id="tecs.platform.time.performanceCounter"></a>
### tecs.platform.time.performanceCounter <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads the platform's raw high-resolution counter.

Prefer `now` for intervals. A raw counter may lose low bits when converted
from SDL's unsigned 64-bit value to a Lua number.



```teal
function tecs.platform.time.performanceCounter(): number
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `number` | A platform-specific count with an arbitrary origin. |

<a id="tecs.platform.time.performanceFrequency"></a>
### tecs.platform.time.performanceFrequency <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads the frequency of the platform's high-resolution counter.



```teal
function tecs.platform.time.performanceFrequency(): number
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `number` | Raw counter units per second. |

<a id="tecs.platform.time.provider"></a>
### tecs.platform.time.provider <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Caller-writable. Installs a replay hook that receives the measured
frame delta. Returning a number replaces it; returning nil keeps it.



```teal
function tecs.platform.time.provider(realDt: number): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `realDt` | `number` | The application supplies the measured frame delta in seconds. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | A number replaces the measured delta, while nil keeps it. |

<a id="tecs.platform.time.reset"></a>
### tecs.platform.time.reset <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Resets the baseline so the next `step` measures from now. Called after
startup so the first frame's dt excludes load time.


```teal
function tecs.platform.time.reset()
```

#### Arguments

None.

#### Returns

None.

<a id="tecs.platform.time.secondsToNanoseconds"></a>
### tecs.platform.time.secondsToNanoseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts whole seconds to nanoseconds.



```teal
function tecs.platform.time.secondsToNanoseconds(
    seconds: integer
): number
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `seconds` | `integer` | The caller supplies a nonnegative integer no larger than 9007199 so the integer result remains exact. |

#### Returns

| Type | Description |
| --- | --- |
| `number` | The same duration in nanoseconds. |

<a id="tecs.platform.time.step"></a>
### tecs.platform.time.step <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Advances one frame and returns the dt the world should receive.

Clamps to `maxDelta`, then offers the value to `provider`.



```teal
function tecs.platform.time.step(): number
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `number` | The elapsed simulation time for this frame, in seconds. |

<a id="tecs.platform.time.ticksMilliseconds"></a>
### tecs.platform.time.ticksMilliseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads milliseconds elapsed since SDL initialized.



```teal
function tecs.platform.time.ticksMilliseconds(): number
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `number` | A monotonic millisecond count. Its origin differs from `now`, so values from the two functions are not directly comparable. |

<a id="tecs.platform.time.ticksNanoseconds"></a>
### tecs.platform.time.ticksNanoseconds <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads nanoseconds elapsed since SDL initialized.

A Lua number stops distinguishing adjacent nanoseconds after about 104
days, while elapsed differences remain useful at the precision its
magnitude permits.



```teal
function tecs.platform.time.ticksNanoseconds(): number
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| `number` | A monotonic nanosecond count. Its origin differs from `now`, so values from the two functions are not directly comparable. |

<a id="tecs.platform.time.toDateTime"></a>
### tecs.platform.time.toDateTime <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts an exact Unix timestamp to calendar fields.



```teal
function tecs.platform.time.toDateTime(
    timestamp: Timestamp, localTime: boolean
): DateTime, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `timestamp` | [`Timestamp`](/modules/platform/time/#tecs.platform.time.Timestamp) | The caller supplies a normalized value returned here or built within the range from about 1677 through 2262. |
| `localTime` | `boolean` | The caller requests local time when true. Omitted or false requests UTC. |

#### Returns

| Type | Description |
| --- | --- |
| [`DateTime`](/modules/platform/time/#tecs.platform.time.DateTime) | A fresh calendar record on success, or nil for an invalid or unsupported timestamp. |
| `string` | The validation or SDL error when no record is returned. |

<a id="tecs.platform.time.toWindowsTime"></a>
### tecs.platform.time.toWindowsTime <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Converts an exact Unix timestamp to a Windows FILETIME.

FILETIME counts 100-nanosecond intervals since 1601, so this conversion
discards the last two decimal digits of `nanosecond`.



```teal
function tecs.platform.time.toWindowsTime(
    timestamp: Timestamp
): WindowsTime, string
```

#### Arguments

| Name | Type | Description |
| --- | --- | --- |
| `timestamp` | [`Timestamp`](/modules/platform/time/#tecs.platform.time.Timestamp) | The caller supplies a normalized timestamp in SDL's representable range. |

#### Returns

| Type | Description |
| --- | --- |
| [`WindowsTime`](/modules/platform/time/#tecs.platform.time.WindowsTime) | The exact high and low FILETIME words, or nil for an invalid timestamp. |
| `string` | The validation error when no words are returned. |

<a id="tecs.platform.time.wallNow"></a>
### tecs.platform.time.wallNow <span class="tealdoc-kind-badge tealdoc-kind-static">Static</span>

Reads the adjustable realtime clock.



```teal
function tecs.platform.time.wallNow(): Timestamp, string
```

#### Arguments

None.

#### Returns

| Type | Description |
| --- | --- |
| [`Timestamp`](/modules/platform/time/#tecs.platform.time.Timestamp) | An exact Unix timestamp on success, or nil on failure. |
| `string` | The SDL error when no timestamp is available. |

## Values

<a id="tecs.platform.time.maxDelta"></a>
### tecs.platform.time.maxDelta <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Caller-writable. Sets the longest frame delta in seconds that `step`
returns.


```teal
tecs.platform.time.maxDelta: number
```

<a id="tecs.platform.time.microsecondsPerSecond"></a>
### tecs.platform.time.microsecondsPerSecond <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Read-only. Reports the number of microseconds in one second.


```teal
tecs.platform.time.microsecondsPerSecond: integer
```

<a id="tecs.platform.time.millisecondsPerSecond"></a>
### tecs.platform.time.millisecondsPerSecond <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Read-only. Reports the number of milliseconds in one second.


```teal
tecs.platform.time.millisecondsPerSecond: integer
```

<a id="tecs.platform.time.nanosecondsPerMicrosecond"></a>
### tecs.platform.time.nanosecondsPerMicrosecond <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Read-only. Reports the number of nanoseconds in one microsecond.


```teal
tecs.platform.time.nanosecondsPerMicrosecond: integer
```

<a id="tecs.platform.time.nanosecondsPerMillisecond"></a>
### tecs.platform.time.nanosecondsPerMillisecond <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Read-only. Reports the number of nanoseconds in one millisecond.


```teal
tecs.platform.time.nanosecondsPerMillisecond: integer
```

<a id="tecs.platform.time.nanosecondsPerSecond"></a>
### tecs.platform.time.nanosecondsPerSecond <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Read-only. Reports the number of nanoseconds in one second.


```teal
tecs.platform.time.nanosecondsPerSecond: integer
```

<a id="tecs.platform.time.nominal"></a>
### tecs.platform.time.nominal <span class="tealdoc-kind-badge tealdoc-kind-variable">variable</span>

Caller-writable. Sets the nominal frame delta in seconds. The
application initializes it from the target frame rate.


```teal
tecs.platform.time.nominal: number
```