time: add GetTimeCached() frame-stable timestamp

Backports retail 4.x's frame-cached GetTime() behavior under a distinct
name, leaving vanilla GetTime() live/per-call. 1.12's Script_GetTime
recomputes the OS tick on every call, so same-frame calls can differ;
GetTimeCached() samples once per frame (via the shared Tick::WorldTick
hook) and returns that until the next frame, on the same epoch as
GetTime() so the two are directly comparable. Falls back to a live
sample before the first world tick so it never returns 0.

Deliberately NOT a perf feature and documented as such: the 1.12 tick
source is cheap (GetTickCount shared-page read or rdtsc) and both
functions pay the same dominant Lua->C dispatch, so caching saves
nothing measurable. The only benefit is frame-stable semantics; the
real hot-loop fix is caching GetTime() in a Lua local, which no C
function can do for the caller. New global chosen over modifying
GetTime() to avoid changing a core vanilla function's behavior.

Author: brues-code

README.md

@@ -66,7 +66,7 @@ Full per-function reference: **[docs/API.md](docs/API.md)**.
 | [Talent](docs/API.md#talent) | `GetTalentIDByIndex`, `GetTalentSpellID` |
 | [Targeting](docs/API.md#targeting) | `GetPlayerFacing`, `TargetDirectionEnemy`, `TargetDirectionFriend`, `TargetNearest`, `TargetNearestEnemyPlayer`, `TargetNearestFriendPlayer` |
 | [TaxiMap](docs/API.md#taximap) | `C_TaxiMap.GetTaxiNodesForMap`, `C_TaxiMap.GetAllTaxiNodes`, `C_TaxiMap.GetTaxiPaths`, `C_TaxiMap.GetTaxiPathWaypoints`, `C_TaxiMap.GetTaxiRoute` |
-| [Time](docs/API.md#time) | `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal`, `C_Timer.After`, `C_Timer.NewTicker`, `C_Timer.NewTimer`, `GetServerTime` |
+| [Time](docs/API.md#time) | `C_DateAndTime.AdjustTimeByDays`, `C_DateAndTime.AdjustTimeByMinutes`, `C_DateAndTime.CompareCalendarTime`, `C_DateAndTime.GetCalendarTimeFromEpoch`, `C_DateAndTime.GetCurrentCalendarTime`, `C_DateAndTime.GetSecondsUntilDailyReset`, `C_DateAndTime.GetServerTimeLocal`, `C_Timer.After`, `C_Timer.NewTicker`, `C_Timer.NewTimer`, `GetServerTime`, `GetTimeCached` |
 | [Totem](docs/API.md#totem) | `GetTotemInfo`, `GetTotemTimeLeft`, `GetTotemDuration`, `TargetTotem` |
 | [TradeSkillUI](docs/API.md#tradeskillui) | `C_TradeSkillUI.GetTradeSkillListLink`, `C_TradeSkillUI.GetCraftListLink`, `C_TradeSkillUI.GetTradeSkillListRecipes` |
 | [UIColor](docs/API.md#uicolor) | `C_UIColor.GetColors` |

docs/API.md

@@ -494,6 +494,7 @@ build instructions.
 
 - [Time](#time)
   - [`GetServerTime()`](#getservertime)
+  - [`GetTimeCached()`](#gettimecached)
   - [`C_Timer.After(seconds, callback)`](#c_timeraftersseconds-callback)
   - [`C_Timer.NewTimer(seconds, callback)`](#c_timernewtimerseconds-callback)
   - [`C_Timer.NewTicker(seconds, callback, [iterations])`](#c_timernewtickerseconds-callback-iterations)
@@ -11860,6 +11861,40 @@ right call for calendar / log-timestamp / cooldown-sync use cases.
 > boundary and the timestamp is accurate to within a second of the
 > engine's clock for as long as the session continues.
 
+### `GetTimeCached()`
+
+Returns the same value as [`GetTime()`](https://warcraft.wiki.gg/wiki/API_GetTime)
+— seconds on the engine's uptime clock — but **frame-stable**: every call
+within a single frame returns the identical value, refreshed once per
+frame. Same epoch as `GetTime()`, so the two are directly comparable.
+
+Backports the retail 4.x `GetTime()` behavior (retail samples the clock
+once per frame in the main loop) under a distinct name, leaving vanilla's
+`GetTime()` untouched — 1.12's `GetTime()` is *live*, recomputing the OS
+tick on every call, so two same-frame `GetTime()` calls can differ.
+
+```lua
+-- Frame-stable: consistent timestamps across a frame's work
+local now = GetTimeCached()
+if now - lastFire >= interval then
+    lastFire = now
+    ...
+end
+```
+
+> **Not a performance feature.** The underlying tick source is cheap in
+> 1.12 (`GetTickCount`, a user-mode shared-page read, or `rdtsc`), and
+> both functions pay the same Lua→C call overhead, which dominates. So
+> `GetTimeCached()` is not meaningfully faster than `GetTime()` — its
+> only advantage is the frame-stable semantics. To actually cut cost in a
+> hot `OnUpdate`, cache the value in a Lua local
+> (`local now = GetTime()`) and reuse it; that removes the per-call Lua
+> dispatch, which a cached C function cannot.
+
+The cache is refreshed from the shared once-per-frame `Tick::WorldTick`
+hook; before the first world tick (pre-login / glue) it falls back to a
+live sample, so it never returns 0.
+
 ### `C_Timer.After(seconds, callback)`
 
 Schedules `callback` to fire once after `seconds`. Returns nothing.

src/time/Cached.cpp

@@ -0,0 +1,81 @@
+// This file is part of ClassicAPI.
+//
+// ClassicAPI is free software: you can redistribute it and/or modify it under the terms
+// of the GNU General Public License as published by the Free Software Foundation, either
+// version 3 of the License, or (at your option) any later version.
+//
+// ClassicAPI is distributed in the hope that it will be useful, but WITHOUT ANY
+// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
+// PURPOSE. See the GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License along with
+// ClassicAPI. If not, see <https://www.gnu.org/licenses/>.
+
+// `GetTimeCached()` — a frame-stable companion to vanilla `GetTime()`.
+//
+// 1.12's `GetTime()` is *live*: `Script_GetTime` (`0x00515ea0`) calls the
+// OS tick source (`FUN_OS_TICKCOUNT_MS` → `GetTickCount`, or QPC in
+// timing-mode 1) on every invocation and scales by 0.001, so two calls in
+// the same frame can differ. Retail 4.x changed `GetTime()` to read a
+// value sampled once per frame in the main loop, so all same-frame calls
+// return the identical timestamp. Rather than change vanilla `GetTime`'s
+// long-standing live behavior, we expose the frame-stable value under a
+// new name and leave `GetTime()` alone.
+//
+// `GetTimeCached()` returns seconds on the SAME epoch as `GetTime()` (the
+// OS millisecond counter × 0.001), so the two are directly comparable —
+// the only difference is that `GetTimeCached()` holds constant for the
+// duration of a frame. We refresh the cache from the shared once-per-frame
+// `Tick::WorldTick` hook (which fires at the tail of each world frame).
+
+#include "Game.h"
+#include "Offsets.h"
+#include "tick/WorldTick.h"
+
+#include <cstdint>
+
+namespace Time::Cached {
+
+namespace {
+
+// OS millisecond counter sampled at the last frame boundary. 0 until the
+// first world tick fires (pre-world). Read as uint32 — `GetTickCount`
+// wraps at ~24.86 days, matching how the rest of the codebase treats this
+// counter (see aura/Data.cpp), and how `Script_GetTime` masks it to 32
+// bits before scaling.
+uint32_t g_frameMs = 0;
+
+uint32_t SampleTickMs() {
+    using TickCount_t = uint32_t(__fastcall *)();
+    return reinterpret_cast<TickCount_t>(
+        static_cast<uintptr_t>(Offsets::FUN_OS_TICKCOUNT_MS))();
+}
+
+// Tail-of-frame refresh. Tail-of-frame-N ≈ start-of-frame-(N+1) minus the
+// inter-frame gap, which is all a frame-stable timestamp needs: every read
+// during a frame returns the value stamped at the previous boundary.
+void OnWorldTick() {
+    g_frameMs = SampleTickMs();
+}
+
+// `GetTimeCached()` → number (seconds). Frame-stable analog of
+// `GetTime()`, same epoch. Falls back to a live sample when no frame has
+// ticked yet (pre-world / glue), so it never returns 0.
+int __fastcall Script_GetTimeCached(void *L) {
+    uint32_t ms = g_frameMs;
+    if (ms == 0)
+        ms = SampleTickMs();
+    Game::Lua::PushNumber(L, static_cast<double>(ms) * 0.001);
+    return 1;
+}
+
+void RegisterLuaFunctions() {
+    Game::Lua::RegisterGlobalFunction("GetTimeCached", &Script_GetTimeCached);
+}
+
+const Game::ModuleAutoRegister _autoreg{&RegisterLuaFunctions};
+const Tick::WorldTick::AutoSubscribe _tick{&OnWorldTick};
+
+} // namespace
+
+} // namespace Time::Cached