Difference between revisions of "API:Sphere.now"

From Spherical
Jump to: navigation, search
(Add Sphere.now() page)
 
(Clarify some stuff, add note on odometer rollover)
 
Line 13: Line 13:
 
=== Description ===
 
=== 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 ===
 
=== Parameters ===
Line 23: Line 23:
 
=== Return Value ===
 
=== 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 ==
 
== See Also ==

Latest revision as of 05:55, 15 November 2017


The Sphere.now() Core API function returns the number of frames processed since the engine started running.

Usage
frames_elapsed = Sphere.now();

API Information

Description

Sphere.now() 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 Sphere.now() 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 regulates the event loop such that 60 frames are processed every second (60 FPS). Your game can change that by setting the value of Sphere.frameRate to something other than 60.

Parameters

This function has no parameters.

Return Value

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