Adding a stub Clock class and providing a fixed update event in Window and View (#2169)

* Delete the old unused clock code

* Create new streamlines clock class

* more clock stuff

* Application updated with Fixed Update, and clocks with aliases to time values

* Clock linting

* Remove the unnecessary time values from examples

* fixing sign issue with accumulated fraction

* an example using fixed update

* linting pass

* Changed to ticks and fixed integration test

* linting pass

* formating

* decreasing number of properties for now

* unit test fix

* fixed light demo's

Author: DragonMoffon

arcade/application.py

@@ -18,6 +18,7 @@
 
 import arcade
 from arcade import SectionManager, get_display_size, set_window
+from arcade.clock import Clock, FixedClock
 from arcade.color import TRANSPARENT_BLACK
 from arcade.context import ArcadeContext
 from arcade.types import Color, RGBANormalized, RGBOrA255
@@ -79,6 +80,10 @@ class Window(pyglet.window.Window):
     :param resizable: Can the user resize the window?
     :param update_rate: How frequently to run the on_update event.
     :param draw_rate: How frequently to run the on_draw event. (this is the FPS limit)
+    :param fixed_rate: How frequently should the fixed_updates run, fixed updates will always run at this rate.
+    :param fixed_frame_cap: The maximum number of fixed updates that can occur in one update loop.
+                                defaults to infinite. If large lag spikes cause your game to freeze, try setting
+                                this to a smaller number. This may cause your physics to lag behind temporarily
     :param antialiasing: Should OpenGL's anti-aliasing be enabled?
     :param gl_version: What OpenGL version to request. This is ``(3, 3)`` by default \
                                        and can be overridden when using more advanced OpenGL features.
@@ -119,6 +124,8 @@ def __init__(
         enable_polling: bool = True,
         gl_api: str = "gl",
         draw_rate: float = 1 / 60,
+        fixed_rate: float = 1.0 / 60.0,
+        fixed_frame_cap: Optional[int] = None,
     ) -> None:
         # In certain environments we can't have antialiasing/MSAA enabled.
         # Detect replit environment
@@ -186,6 +193,7 @@ def __init__(
             )
             self.register_event_type("on_update")
             self.register_event_type("on_action")
+            self.register_event_type("on_fixed_update")
         except pyglet.window.NoSuchConfigException:
             raise NoOpenGLException(
                 "Unable to create an OpenGL 3.3+ context. "
@@ -197,11 +205,19 @@ def __init__(
             except pyglet.gl.GLException:
                 LOG.warning("Warning: Anti-aliasing not supported on this computer.")
 
+        self._global_clock: Clock = Clock()
+        self._fixed_clock: FixedClock = FixedClock(self._global_clock, fixed_rate)
+
         # We don't call the set_draw_rate function here because unlike the updates, the draw scheduling
         # is initially set in the call to pyglet.app.run() that is done by the run() function.
         # run() will pull this draw rate from the Window and use it. Calls to set_draw_rate only need
         # to be done if changing it after the application has been started.
         self._draw_rate = draw_rate
+
+        # Fixed rate cannot be changed post initialisation as this throws off physics sims.
+        # If more time resolution is needed in fixed updates, devs can do 'sub-stepping'.
+        self._fixed_rate = fixed_rate
+        self._fixed_frame_cap = fixed_frame_cap
         self.set_update_rate(update_rate)
 
         self.set_vsync(vsync)
@@ -381,11 +397,27 @@ def on_update(self, delta_time: float) -> Optional[bool]:
         """
         pass
 
+    def on_fixed_update(self, delta_time: float):
+        """
+        Move everything. Perform collision checks. Always
+
+        """
+        pass
+
     def _dispatch_updates(self, delta_time: float) -> None:
         """
         Internal function that is scheduled with Pyglet's clock, this function gets run by the clock, and
         dispatches the on_update events.
-        """
+        It also accumulates time and runs fixed updates until the Fixed Clock catches up to the global clock
+        """
+        self._global_clock.tick(delta_time)
+        fixed_count = 0
+        while self._fixed_clock.accumulated >= self._fixed_rate and (
+            self._fixed_frame_cap is None or fixed_count <= self._fixed_frame_cap
+        ):
+            self._fixed_clock.tick(self._fixed_rate)
+            self.dispatch_event("on_fixed_update", self._fixed_rate)
+            fixed_count += 1
         self.dispatch_event("on_update", delta_time)
 
     def set_update_rate(self, rate: float) -> None:
@@ -976,6 +1008,45 @@ def center_y(self) -> float:
         """Returns the Y-coordinate of the center of the window."""
         return self.height / 2
 
+    # --- CLOCK ALIASES ---
+    @property
+    def time(self) -> float:
+        return self._global_clock.time
+
+    @property
+    def fixed_time(self) -> float:
+        return self._fixed_clock.time
+
+    @property
+    def delta_time(self) -> float:
+        return self._global_clock.delta_time
+
+    @property
+    def fixed_delta_time(self) -> float:
+        return self._fixed_rate
+
+    @property
+    def global_clock(self) -> Clock:
+        return self._global_clock
+
+    @property
+    def global_fixed_clock(self) -> FixedClock:
+        return self._fixed_clock
+
+    # Possibly useful clock properties
+
+    # @property
+    # def current_fixed_tick(self) -> int:
+    #     return self._fixed_clock.ticks
+
+    # @property
+    # def accumulated_time(self) -> float:
+    #     return self._fixed_clock.accumulated
+
+    # @property
+    # def accumulated_fraction(self) -> float:
+    #     return self._fixed_clock.fraction
+
 
 def open_window(
     width: int,
@@ -1072,6 +1143,10 @@ def on_update(self, delta_time: float) -> Optional[bool]:
         """To be overridden"""
         pass
 
+    def on_fixed_update(self, delta_time: float):
+        """To be overridden"""
+        pass
+
     def on_draw(self) -> Optional[bool]:
         """Called when this view should draw"""
         pass

arcade/clock.py

@@ -0,0 +1,110 @@
+class Clock:
+    """
+    A time keeping class.
+
+    :Coming post 3.0:
+    you can add 'sub-clocks' to arcade's top level clock which will tick at the same time, and
+    have cumulative tick_speeds. This allows you to slow down only certain elements rather than everything.
+    """
+
+    def __init__(
+        self, initial_elapsed: float = 0.0, initial_frame: int = 0, tick_speed: float = 1.0
+    ):
+        self._elapsed_time: float = initial_elapsed
+        self._frame: int = initial_frame
+        self._tick_delta_time: float = 0.0
+        self._tick_speed: float = tick_speed
+
+    def tick(self, delta_time: float):
+        self._tick_delta_time = delta_time * self._tick_speed
+        self._elapsed_time += self._tick_delta_time
+        self._frame += 1
+
+    def time_since(self, time: float):
+        return self._elapsed_time - time
+
+    def frames_since(self, frame: int):
+        return self._frame - frame
+
+    @property
+    def time(self):
+        """
+        The total number of seconds that have elapsed for this clock
+        """
+        return self._elapsed_time
+
+    @property
+    def t(self):
+        """
+        Alias to Clock.time
+        """
+        return self._elapsed_time
+
+    @property
+    def delta_time(self):
+        """
+        The amount of time that elapsed during the last tick
+        """
+        return self._tick_delta_time
+
+    @property
+    def dt(self):
+        """
+        Alias to Clock.delta_time
+        """
+        return self.delta_time
+
+    @property
+    def speed(self):
+        """
+        A modifier on the delta time that elapsed each tick.
+
+        Decreasing the speed will 'slow down' time for this clock
+        Immutable in 3.0
+        """
+        return self._tick_speed
+
+    @property
+    def ticks(self):
+        """
+        The number of ticks that have occurred for this clock
+        """
+        return self._frame
+
+    @property
+    def tick_count(self):
+        """
+        Alias to Clock.frame
+        """
+        return self._frame
+
+
+class FixedClock(Clock):
+    """
+    A fixed clock which expects its delta_time to stay constant. If it doesn't it will throw an error.
+    """
+
+    def __init__(self, sibling: Clock, fixed_tick_rate: float = 1.0 / 60.0):
+        self._sibling_clock: Clock = sibling
+        self._fixed_rate: float = fixed_tick_rate
+        super().__init__()
+
+    def tick(self, delta_time: float):
+        if delta_time != self._fixed_rate:
+            raise ValueError(
+                f"the delta_time {delta_time}, "
+                f"does not match the fixed clock's required delta_time {self._fixed_rate}"
+            )
+        super().tick(self._fixed_rate)
+
+    @property
+    def rate(self):
+        return self._fixed_rate
+
+    @property
+    def accumulated(self):
+        return self._sibling_clock.time - self._elapsed_time
+
+    @property
+    def fraction(self):
+        return self.accumulated / self._fixed_rate

arcade/examples/fixed_update_interpolation.py

@@ -0,0 +1,88 @@
+"""
+Interpolate a sprite's motion which is calculated in fixed update.
+
+The bouncing done in this example is very bare-bones, and unstable.
+The fixed update has been slowed down to highlight the value of interpolation,
+the fixed update should be kept close to the nominal update rate, or even faster.
+
+If Python and Arcade are installed, this example can be run from the command line with:
+python -m arcade.examples.fixed_update_interpolation.py
+"""
+import arcade
+
+# --- Constants ---
+GRAVITY = 98.1  # 98.1 px per second
+CIRCLE_RADIUS = 30
+
+SCREEN_WIDTH = 1289
+SCREEN_HEIGHT = 720
+SCREEN_TITLE = "Sprite Follow Path Simple Example"
+
+
+class Game(arcade.Window):
+
+    def __init__(self):
+        super().__init__(fixed_rate=1/120.0)
+        self.unfixed_sprite = arcade.SpriteCircle(CIRCLE_RADIUS, arcade.color.RADICAL_RED)
+        self.interpolated_sprite = arcade.SpriteCircle(CIRCLE_RADIUS, arcade.color.ORANGE)
+        self.fixed_sprite = arcade.SpriteCircle(CIRCLE_RADIUS, arcade.color.GOLD)
+
+        # We store the last position of the fixed sprite to find the interpolated sprite's position
+        self.last_position = 0.0
+
+        self.sprites = arcade.SpriteList()
+        self.sprites.extend((self.unfixed_sprite, self.fixed_sprite, self.interpolated_sprite))
+
+    def setup(self):
+        self.unfixed_sprite.change_y = self.fixed_sprite.change_y = self.interpolated_sprite.change_y = 0.0
+
+        self.unfixed_sprite.position = SCREEN_WIDTH / 4.0, SCREEN_HEIGHT / 2.0
+        self.interpolated_sprite.position = 2.0 * SCREEN_WIDTH / 4.0, SCREEN_HEIGHT / 2.0
+        self.fixed_sprite.position = 3.0 * SCREEN_WIDTH / 4.0, SCREEN_HEIGHT / 2.0
+
+        self.last_position = self.fixed_sprite.center_y
+
+    def on_key_press(self, symbol: int, modifiers: int):
+        if symbol == arcade.key.R:
+            self.setup()
+
+    def on_fixed_update(self, delta_time: float):
+        # Accelerate the sprite downward due to gravity
+        self.fixed_sprite.change_y -= GRAVITY * delta_time
+
+        # If the sprite is colliding with the ground then make it 'bounce' by flipping it's velocity
+        if self.fixed_sprite.center_y <= CIRCLE_RADIUS and self.fixed_sprite.change_y <= 0.0:
+            self.fixed_sprite.change_y *= -1
+
+        # Move the sprite based on its velocity
+        self.last_position = self.fixed_sprite.center_y
+        self.fixed_sprite.center_y += self.fixed_sprite.change_y * delta_time
+
+    def on_update(self, delta_time: float):
+        # Accelerate the sprite downward due to gravity
+        self.unfixed_sprite.change_y -= GRAVITY * delta_time
+
+        # If the sprite is colliding with the ground then make it 'bounce' by flipping it's velocity
+        if self.unfixed_sprite.center_y <= CIRCLE_RADIUS and self.unfixed_sprite.change_y <= 0.0:
+            self.unfixed_sprite.change_y *= -1
+
+        # Move the sprite based on its velocity
+        self.unfixed_sprite.center_y += self.unfixed_sprite.change_y * delta_time
+
+        self.interpolated_sprite.center_y = arcade.math.lerp(
+            self.last_position, self.fixed_sprite.center_y, self.global_fixed_clock.fraction
+        )
+
+    def on_draw(self):
+        self.clear()
+        self.sprites.draw()
+
+
+def main():
+    win = Game()
+    win.setup()
+    win.run()
+
+
+if __name__ == '__main__':
+    main()

arcade/examples/gl/compute_ssbo.py

@@ -131,7 +131,6 @@ def __init__(self, *args, **kwargs):
         # We need to specify OpenGL 4.3 when using Compute Shaders
         super().__init__(1280, 720, "Compute Shader", gl_version=(4, 3), resizable=True, vsync=True)
         # Keep track of time
-        self.time = 0
         self.frame_time = 0
         # The work group size we have configured the compute shader to.
         # This is hardcoded the compute shader (careful with changing)
@@ -317,7 +316,6 @@ def on_draw(self):
 
     def on_update(self, delta_time: float):
         # Keep our time variables up to date
-        self.time += delta_time
         self.frame_time = delta_time
 
     def gen_initial_data(self, num_balls):

arcade/examples/gl/compute_texture.py

@@ -49,7 +49,6 @@ class App(arcade.Window):
     def __init__(self, *args, **kwargs):
         # We need to specify OpenGL 4.3 when using Compute Shaders
         super().__init__(*SIZE, "Compute Shader", gl_version=(4, 3))
-        self.time = 0
         self.cs = self.ctx.compute_shader(source=COMPUTE_SHADER)
         # In gles the texture needs to be immutable (immutable storage, not contents)
         self.texture = self.ctx.texture(SIZE, components=4, immutable=True)
@@ -107,7 +106,6 @@ def on_draw(self):
         self.quad.render(self.program)
 
     def on_update(self, delta_time: float):
-        self.time += delta_time
         self.cs["time"] = self.time * 10
 
 

arcade/examples/gl/multisample_fbo.py

@@ -19,8 +19,6 @@ class MultisampleFramebuffer(arcade.Window):
 
     def __init__(self, width, height):
         super().__init__(width, height, "Multisampled Framebuffer", samples=SAMPLES)
-        self.time = 0
-
         # Create a MSAA texture and framebuffer
         self.texture = self.ctx.texture(self.get_framebuffer_size(), samples=SAMPLES)
         self.fbo = self.ctx.framebuffer(color_attachments=[self.texture])
@@ -51,8 +49,5 @@ def on_draw(self):
         self.ctx.screen.use()
         self.ctx.copy_framebuffer(self.fbo, self.ctx.screen)
 
-    def on_update(self, delta_time: float):
-        self.time += delta_time
-
 
 MultisampleFramebuffer(800, 600).run()