Editing WoW:API GetGameTime

{{wowapi}} __NOTOC__
Returns the current server time in hours and minutes
 hours,minutes = GetGameTime();

== Parameters ==
: none

== Returns ==
* hours (number) - The current hour (0-23).
* minutes (number) - The minutes passed in the current hour (0-59).

== Details ==
Gets the current server time for the zone server the client's avatar is standing, or primarily connected to. This may not be the same game server as the realm server a user logged into.  

=== Examples ===
 local hour,minute = GetGameTime()

 message(hour .. ":" .. minute)

In a macro to print current server time in chat:
 /script local hour,minute = GetGameTime(); DEFAULT_CHAT_FRAME:AddMessage(hour .. ":" .. minute);

Posts a message to local chat current server time appears.

== Notes on time accuracy ==
A developer's notes on GetGameTime idiosyncrasies and managing WoW UI time issues.

=== Inter-zone and instance issues ===
This function can unexpectedly return results that are inconsistent with actual time for the login realm sever.

The value returned is from the physical instance server you are actually playing on, and not that of the world instance server (realm server) you log into. Servers for instances such as for Raids and PvP are often shared between login world servers. And instance servers are not always running using the same time zone as the login realm server. This is particularly noticeable for Oceanic and other low population world servers.

So for example, if you log into US Ysera EST at 18:00, and enter Ulduar running on an instance server that is PST. Suddenly the time returned will be 3 hours behind the time you were getting.  Confusing but important :)  Please keep this in mind if using this time for anything important functionally, such as diffing times or using as part of functional historical data.

A second compounding issue is that even if the current zone server is in the same time zone as the login server, you might have variance between the two blizzard server's clocks, like 5-10 minutes, though not typically the case.

=== WoW time API choices ===
For getting consistent times you have two basic choices: 1) use server or 2) use local client time.

Server time is good because all players in a realm will have the same time within more or less a minute accuracy, when you are on the same zone or instance server.

The client time APIs are good because you have seconds precision. However everyone's client times are different, as not only due people logging into realm servers from different time zones around the world, but their computers time may be off just like any other clock, or never been set, or even set with wrong time zone, all adding lots of variance. Despite this, using local time for most apps where a universal time between user isn't important, is the way to go if the app need to be sure its own time to not jump around.

=== Compensating for inter-player differences ===
Even though the "server time" would be the generally better API for relating time between users, the "instance server not same time as login server" problem suddenly makes the server time much less valuable for consistency.

A third choice for consistent times is to mix the two and run a timer correction update event in the background, where you get a base time difference between local and server time as to correct local time to server time, and base seconds (plus diff) purely off of local time. So:
# seed a base time variable to a reconciled current server time + local time
# use local time + saved base as a time value in AddOn (server time with second precision)
# continue every fraction of second or so to see if server time has rolled over to next minute
# reconcile and update base
# and so on...

The update event basically corrects the base difference over time to keep it accurate with server time. The base correction update is necessary because users computers can drift dramatically depending on the computer, and because users can choose to change their time zone or clock at any time. Also doing time diffs and adds is not as simple as it sounds; its a bit contrived to get it right. What you end up with however is as near second accuracy universal server time across all clients. This depends on how accurate minute rollovers form server time are and using the clients seconds counter should not drift any perceptible amount inside a minute.

It appears the WoW client itself is basing the server time minute rollovers on local client time as well, just not shared with us through this function. Its unclear which communication from the server carries the time update, or how often or what triggers the actual server time updates to the client. But in practice this combination approach appears to work very very well, where recorded AddOn raid item and other DKP statistics can show to be with in the same second or so, across multiple clients who are also hopping in and out of zones and instances, sometimes constantly.

=== Compensating for inter-server differences ===
However... with the newer problem, where the servers themselves may have different server times even though they are accessible from the same realm login, (and the original reason for the extended note) you will need to basically shut off the base correction when a player enters an instance and save the difference value to your saved vars, in case the player restarts or logs into an instance instead of the realm world server.

This leaves the problem of a user installing the AddOn and logging on to an instance server first rather than the realm world server (and people who raid know that can really happen a lot, ala "oh let me go enable or install that AddOn I need, brb"). In this case you will need to seed the base with the difference of the instance server just once and then follow the rule of shutting it off in an instance, where it will naturally be corrected within a minute or so of entering realm world server.

This is a lot of trouble to get simple consistent server time, and ... may seem crazy to worry about. For some apps is more than nice to have, ala player joins and leaves for say raid tracker for example and dealing with non-trivial things for users to fix after the fact like wtf DKP upload results, its worth it. The core issue isn't having accuracy like an atomic clock, but not having time values jump in a way that makes the data absurd or inconsistent or impossible to process like DKP uploads, and a close second is all users having the basic same time of the day in a consistent format and time zone, which is really the same thing for multi user uploads in my example.  All Blizzard could do to fix this would be to make a hole where to continue to get server time from the realm server for AddOns and possibly share the seconds counter as a third return value in this API function if there is such a thing, and is all probably not a trivial thing to change.

Lastly, as an aside, the suspicion is that the server to client time updates are actually done in a low bandwidth fashion in one of several ways. They are taken directly from other data for other purposes like timings from one of the standard server game clocks out of packets intended for avatar updates and the like with the seconds clipped off. Another possibility could be a very occasional update from the server, out of band, and updated by the client based on local time anyway. If is out of band and special the last example would be the least bandwidth by far. Regardless it would have been nice to have an extra return value with the seconds from GetServerTime, with wherever the client's value used to know when to flip the seconds value, rather than re-synthesize it again on the Lua side. :)

=== Addendum ===
A wiki user added "difference between two clients can exceed a minute [disregarding hours]" to the general server time API description above, but its unclear if they meant for users on different zone server or not, since the same zone server will have the same server "hours" for all clients. The preceding commentary above explains the split-server cases.

The reason the times may only flip to the next minute between two clients only approximately at the same time, is that the server wont send an update every time the API is called, as this is a client-side only call and always returns immediately. Instead, the client caches the last server time is received, and the client flips the minute on its own based on client time even if the server hasn't sent any messages that would carry server time by the time the minute would need to flip for the client. This is also one of the reasons that server time is only in minutes, with no seconds.