GameTime

GameTime tells a script how much time has passed. All of its values are read-only.

Property	Type
deltaTime	number	Seconds since the previous frame. Use it in Update.
fixedDeltaTime	number	The fixed step FixedUpdate runs on: always 1/60 (about 0.0167).
osTime	integer	The real-world clock: whole seconds since 1 January 1970 (UTC).
fps	integer	Frames-per-second smoothed to the closes integer
timeInSeconds	integer	Time since the engine start in seconds

---

deltaTime

Frames don't all take the same time. Anything that should happen per second rather than per frame has to be multiplied by deltaTime, or it will run faster on faster computers.

---@field speed number
speed = 30   -- units per second

function Update()
    -- Wrong: moves 30 units every frame (1800 per second at 60 fps).
    -- entity.transform:addPosition(Vector3(speed, 0, 0))

    -- Right: moves 30 units per second at any frame rate.
    entity.transform:addPosition(Vector3(speed * GameTime.deltaTime, 0, 0))
end

Timers work the same way: count deltaTime down (or up) yourself.

local cooldown = 0

function Update()
    cooldown = cooldown - GameTime.deltaTime
    if cooldown <= 0 and Input.GetMouseButtonDown(Input.MouseLeft) then
        cooldown = 0.25   -- at most 4 shots per second
        Fire()
    end
end

deltaTime is the real frame time. There is no time scale or pause yet, and a long stall (a loading hitch, a breakpoint) makes the next deltaTime large. If a big jump would break something, cap it: local dt = mathT.Min(GameTime.deltaTime, 0.1).

---

fixedDeltaTime

Inside FixedUpdate, use fixedDeltaTime instead of deltaTime: each call stands for exactly one 1/60 s step. See Callback Functions.

local ticks = 0

function FixedUpdate()
    ticks = ticks + 1
    elapsed = ticks * GameTime.fixedDeltaTime   -- exact, no drift
end

---

osTime

osTime is the clock on the player's computer, in whole seconds. It keeps counting whatever the game does, so it is not useful for gameplay timing. Use it for things like:

• Seeding random numbers so each run is different: mathT.RandomSeed(GameTime.osTime).
• Measuring how long a whole play session lasted.

local startedAt

function Start()
    startedAt = GameTime.osTime
end

function OnTriggerEnter(other)
    if other.hasPlayerController then
        Debug.Print("Finished in", GameTime.osTime - startedAt, "seconds")
    end
end

fps

fps is the current frames-per-second smoothed to the nearest integer. Useful for debugging

function Update()
    Debug.Print("Current FPS:" ... GameTime.fps)
end

timeInSeconds

timeInSeconds is ng

function Update()
    Debug.Print("Current FPS:" ... GameTime.fps)
end