Bruce Pascoe: Clarify some stuff, add note on odometer rollover

2017-11-15T05:55:45Z

Clarify some stuff, add note on odometer rollover

Bruce Pascoe: Add Sphere.now() page

2017-11-02T16:32:51Z

Add Sphere.now() page

New page

{{DISPLAYTITLE:Sphere.now()}}

The '''<tt>Sphere.now()</tt>''' [[API:Functions|Core API]] function returns the number of frames processed since the engine started running.

===== Usage =====

''frames_elapsed'' = '''Sphere.now'''();

__TOC__

== API Information ==

=== Description ===

'''<tt>Sphere.now()</tt>''' returns the number of complete frames processed since the calling game started. Therefore, on the very first frame this will return 0, on the next frame 1, and so on. Specifically the return value is the number of full event loop turns, which by definition is the same as the number of updates performed. This allows you to use <tt>Sphere.now()</tt> as a frame-perfect timer in cases where using wall-clock time (e.g. <tt>Date.now()</tt>) is not desirable.

By default, Sphere will regulate updates so that 60 frames will be processed every second (60 FPS). Your game can change that by setting the value of <tt>[[API:Sphere.frameRate|Sphere.frameRate]]</tt> to something other than 60.

=== Parameters ===

This function has no parameters.

=== Return Value ===

The number of complete frames processed since the game started running.

== See Also ==

<tt>
* [[API:Sphere.frameRate|Sphere.frameRate]]
</tt>

[[Category:Sphere 2 API]]

@@ Line 13: / Line 13: @@
 === Description ===
-'''<tt>Sphere.now()</tt>''' returns the number of complete frames processed since the calling game started.  Therefore, on the very first frame this will return 0, on the next frame 1, and so on.  Specifically the return value is the number of full event loop turns, which by definition is the same as the number of updates performed.  This allows you to use <tt>Sphere.now()</tt> as a frame-perfect timer in cases where using wall-clock time (e.g. <tt>Date.now()</tt>) is not desirable.
+'''<tt>Sphere.now()</tt>''' returns the number of complete event loop turns since the calling game started, each event loop turn corresponding to a frame.  Therefore, on the very first frame this will return 0, on the next frame 1, and so on.  Because <tt>Sphere.now()</tt> counts frames instead of wall-clock time, this allows you to use it as a frame-perfect timer, which is often more predictable than wall-clock time, particularly if the game begins dropping frames.
-By default, Sphere will regulate updates so that 60 frames will be processed every second (60 FPS).  Your game can change that by setting the value of <tt>[[API:Sphere.frameRate|Sphere.frameRate]]</tt> to something other than 60.
+By default, Sphere regulates the event loop such that 60 frames are processed every second (60 FPS).  Your game can change that by setting the value of <tt>[[API:Sphere.frameRate|Sphere.frameRate]]</tt> to something other than 60.
 === Parameters ===
@@ Line 23: / Line 23: @@
 === Return Value ===
-The number of complete frames processed since the game started running.
+The number of complete frames processed since the game started running.  This value will roll over, like an odometer, after exactly 4,294,967,296 frames.  This is not a practical concern: running at 60 frames per second, your game would need to run continuously, ''for 2 years straight'', before the counter will roll over.
 == See Also ==

API:Sphere.now - Revision history

Bruce Pascoe: Clarify some stuff, add note on odometer rollover

Bruce Pascoe: Add Sphere.now() page