Merge branch 'Issue-6598' into 'master'

Update overview.rst (#6598)

See merge request OpenMW/openmw!1655

AUTHORS.md

@@ -249,6 +249,7 @@ Documentation
     Joakim Berg (lysol90)
     Ryan Tucker (Ravenwing)
     sir_herrbatka
+    David Nagy (zuzaman)
 
 Packagers
 ---------

docs/source/reference/lua-scripting/overview.rst

@@ -546,10 +546,10 @@ Timers
 ======
 
 Timers are in the :ref:`openmw.async <Package openmw.async>` package.
-They can be set either in game seconds or in game hours.
+They can be set either in simulation time or in game time.
 
-- `Game seconds`: the number of seconds in the game world (i.e. seconds when the game is not paused), passed from starting a new game.
+- `Simulation time`: the number of seconds in the game world (i.e. seconds when the game is not paused), passed from starting a new game.
-- `Game hours`: current time of the game world in hours. The number of seconds in a game hour is not guaranteed to be fixed.
+- `Game time`: current time of the game world in seconds. Note that game time generally goes faster than the simulation time.
 
 When the game is paused, all timers are paused as well.
 
@@ -578,7 +578,7 @@ An example:
     end)
 
     local function teleportWithDelay(delay, actor, cellName, pos)
-        async:newTimerInSeconds(delay, teleportWithDelayCallback, {
+        async:newSimulationTimer(delay, teleportWithDelayCallback, {
             actor = actor,
             destCellName = cellName,
             destPos = pos,
@@ -603,7 +603,7 @@ An example:
         engineHandlers = {
             onKeyPress = function(key)
                 if key.symbol == 'x' then
-                    async:newUnsavableTimerInSeconds(
+                    async:newUnsavableSimulationTimer(
                         10,
                         function()
                             ui.showMessage('You have pressed "X" 10 seconds ago')
@@ -613,28 +613,21 @@ An example:
         }
     }
 
-Also in `openmw_aux`_ are the helper functions ``runEveryNSeconds`` and ``runEveryNHours``, they are implemented on top of unsavable timers:
+Also in `openmw_aux`_ is the helper function ``runRepeatedly``, it is implemented on top of unsavable timers:
 
 .. code-block:: Lua
 
-    local async = require('openmw.async')
     local core = require('openmw.core')
+    local time = require('openmw_aux.time')
 
     -- call `doSomething()` at the end of every game day. 
-    -- `timeBeforeMidnight` is a delay before the first call. `24` is an interval.
+    -- the second argument (`time.day`) is the interval.
     -- the periodical evaluation can be stopped at any moment by calling `stopFn()`
-    local timeBeforeMidnight = 24 - math.fmod(core.getGameTimeInHours(), 24)
+    local timeBeforeMidnight = time.day - core.getGameTime() % time.day
-    local stopFn = aux_util.runEveryNHours(24, doSomething, timeBeforeMidnight)
+    local stopFn = time.runRepeatedly(doSomething, time.day, {
-
+        initialDelay = timeBeforeMidnight,
-    return {
+        type = time.GameTime,
-        engineHandlers = {
+    })
-            onLoad = function()
-                -- the timer is unsavable, so we need to restart it in `onLoad`.
-                timeBeforeMidnight = 24 - math.fmod(core.getGameTimeInHours(), 24)
-                stopFn = aux_util.runEveryNHours(24, doSomething, timeBeforeMidnight)
-            end,
-        }
-    }
 
 
 Queries

files/builtin_scripts/openmw_aux/time.lua

@@ -66,7 +66,7 @@ end
 --     function() print('Test2') end, 5 * time.minute,
 --     { initialDelay = 30 * time.second })
 -- @usage
--- local timeBeforeMidnight = time.day - time.gameTime() % time.day
+-- local timeBeforeMidnight = time.day - core.getGameTime() % time.day
 -- time.runRepeatedly(doSomething, time.day, {
 --     initialDelay = timeBeforeMidnight,
 --     type = time.GameTime,