Start frame time at zero in --lockstep

This allows physics systems to be run deterministically.

Author: jonathanhogg

docs/language.md

@@ -75,8 +75,9 @@ The engine-supplied global values are:
 - `quantum` - the beats per quantum (usually 4)
 - `delta` - the difference between the current value of `beat` and the value
     at the last display frame
-- `time` - the current frame time (derived from Python's `perf_counter()`
-    usually, though increasing by exactly `1/fps` per frame in non-realtime
+- `time` - the time that the current frame began execution (either the value
+    of the high-resolution Python `perf_counter()` timer or a counter beginning
+    at `0` and incrementing by exactly `1/fps` on each frame in non-realtime
     mode)
 - `clock` - the current UTC time as a seconds-since-UNIX-epoch value
 - `frame` - the current frame number, counting from 0 and increasing by one

docs/physics.md

@@ -108,6 +108,12 @@ The internal simulation clock can be read from the state and used to track the
 actual amount of simulation time that has passed (see [State
 interaction](#state-interaction) below).
 
+A physics system is entirely deterministic *iff* it uses fixed starting
+conditions *and* **Flitter** is run in non-realtime mode. When run in realtime
+mode, small numerical differences in how time advances will introduce tiny
+variations that compound quickly in any non-trivial system to produce chaotic
+results.
+
 ### `!particle`
 
 A `!particle` node specifies a point/spherical object to be simulated. At each

src/flitter/engine/control.py

@@ -102,7 +102,7 @@ def switch_to_page(self, page_number):
                 self.counter.reset(tempo, int(quantum), start)
                 logger.info("Restore counter at beat {:.1f}, tempo {:.1f}, quantum {}", self.counter.beat, self.counter.tempo, self.counter.quantum)
             else:
-                self.counter.reset()
+                self.counter.reset(start=system_clock() if self.realtime else 0)
             setproctitle(f'flitter [{self.current_path}]')
 
     def has_next_page(self):
@@ -169,7 +169,7 @@ async def run(self):
         try:
             frame_count = 0
             frames = []
-            start_time = frame_time = system_clock() if self.realtime else self.counter.start
+            start_time = frame_time = system_clock() if self.realtime else 0
             last = self.counter.beat_at_time(frame_time)
             save_state_time = system_clock() + self.STATE_SAVE_PERIOD
             execution = render = housekeeping = 0