ConstantGameSpeed — wiki

#!/usr/bin/env python

# This file is part of GameClock.
#
# GameClock is free software: you can redistribute it and/or modify it
# under the terms of the GNU Lesser General Public License as published
# by the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# GameClock is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with GameClock.  If not, see /www.gnu.org/licenses/>.

# Compatible: Python 2.7, Python 3.2

"""gameclock.py - Game clock for Gummworld2.

GameClock is a fixed time-step clock that keeps time in terms of game
time. It will attempt to keep game time close to real time, so if an
interval takes one second of game time then the user experiences one
second of real time. In the worst case where the CPU cannot keep up with
the game load, game time will subjectively take longer but still remain
accurate enough to keep game elements in synchronization.

GameClock manages time in the following ways:
        
    1.  Register special callback functions that will be run when they
        are due.
    2.  Schedule game logic updates at a constant speed, independent of
        frame rate.
    3.  Schedule frames at capped frames-per-second, or uncapped.
    4.  Invoke a pre-emptive pause callback when paused.
    5.  Schedule miscellaneous items at user-configurable intervals.
    6.  Optionally sleep between schedules to conserve CPU cycles.
    7.  Gracefully handle corner cases.

Note the Python Library docs mention that not all computer platforms'
time functions return time in fractions of a second. This module will not
work on such platforms.

USAGE

Callback:
    
    clock = GameClock(
        update_callback=update_world,
        frame_callback=draw_scene,
        pause_callback=pause_game)
    while 1:
        clock.tick()

Special callbacks can be directly set and cleared at any time:
    
    clock.update_callback = my_new_update
    clock.frame_callback = my_new_draw
    clock.pause_callback = my_new_pause
    
    clock.update_callback = None
    clock.frame_callback = None
    clock.pause_callback = None

Scheduling miscellanous callbacks:
    
    def every_second_of_every_day(dt):
        "..."
    clock.schedule_interval(every_second_of_every_day, 1.0)

Callbacks can be any kind of callable that accepts the callback signature.

The update_callback receives a single DT argument, which is the time-step
in seconds since the last update.

The frame_callback receives a single INTERPOLATION argument, which is the
fractional position in time of the frame within the current update time-
step. It is a float in the range 0.0 to 1.0.

The pause_callback receives no arguments.

User-defined interval callbacks accept at least a DT argument, which is
the scheduled item's interval, and optional user-defined arguments. See
GameClock.schedule_interval.

DEPRECATIONS

Old Style Game Loop

Use of the old style game loop is deprecated. Don't do this anymore:
    
    if clock.update_ready:
        update(clock.dt_update)
    if clock.frame_ready:
        draw(clock.interpolate)

The old style game loop will work on sufficiently fast hardware. Timekeeping
will break on slow hardware that cannot keep up with a heavy workload. This is
because the old style ignores the cost of the frame routine. By using callbacks
instead, cost is factored into the frame scheduling and overloading the CPU has
fewer negative side effects.

The update_ready and frame_ready public attributes have been removed.

CREDITS

The inspiration for this module came from Koen Witters's superb article
"deWiTTERS Game Loop", aka "Constant Game Speed independent of Variable FPS"
at http://www.koonsolo.com/news/dewitters-gameloop/.

The clock was changed to use a fixed time-step after many discussions with
DR0ID, and a few readings of
http://gafferongames.com/game-physics/fix-your-timestep/.

Thanks to Koen Witters, DR0ID, and Glenn Fiedler for sharing.

Pythonated by Gummbum. While the builtin demo requires pygame, the module
does not. The GameClock class is purely Python and should be compatible with
other Python-based multi-media and game development libraries.
"""

__version__ = '$Id: gameclock.py 428 2013-08-28 05:43:47Z stabbingfinger@gmail.com $'
__author__ = 'Gummbum, (c) 2011-2014'


import functools
import time


class _IntervalItem(object):
    """An interval item runs after an elapsed interval."""
    # __slots__ = ['func', 'interval', 'lasttime', 'life', 'args', 'id']
    id = 0
    def __init__(self, func, interval, curtime, life, args):
        self.func = func
        self.interval = float(interval)
        self.lasttime = curtime
        self.life = life
        self.args = args
        self.id = _IntervalItem.id
        _IntervalItem.id += 1


class GameClock(object):
    
    def __init__(self,
            max_ups=30,
            max_fps=0,
            use_wait=False,
            time_source=time.time,
            update_callback=None,
            frame_callback=None,
            paused_callback=None):
        
        # Configurables.
        self.get_ticks = time_source
        self.max_ups = max_ups
        self.max_fps = max_fps
        self.use_wait = use_wait
        self.update_callback = update_callback
        self.frame_callback = frame_callback
        self.paused_callback = paused_callback
        
        # Time keeping.
        TIME = self.get_ticks()
        self._real_time = TIME
        self._game_time = TIME
        self._last_update = TIME
        self._last_update_real = TIME
        self._next_update = TIME
        self._last_frame = TIME
        self._next_frame = TIME
        self._next_second = TIME
        self._update_ready = False
        self._frame_ready = False
        self._paused = 0
        
        # Schedules
        self._need_sort = False
        self._schedules = []
        self._unschedules = []
        
        # Metrics: update and frame progress counter in the current one-second
        # interval.
        self.num_updates = 0
        self.num_frames = 0
        # Metrics: duration in seconds of the previous update and frame.
        self.dt_update = 0.0
        self.dt_frame = 0.0
        # Metrics: how much real time a callback consumes
        self.cost_of_update = 0.0
        self.cost_of_frame = 0.0
        # Metrics: average updates and frames per second over the last five
        # seconds.
        self.ups = 0.0
        self.fps = 0.0
    
    @property
    def max_ups(self):
        return self._max_ups
    @max_ups.setter
    def max_ups(self, val):
        self._max_ups = val
        self._update_interval = 1.0 / val
    
    @property
    def max_fps(self):
        return self._max_fps
    @max_fps.setter
    def max_fps(self, val):
        self._max_fps = val
        self._frame_interval = 1.0 / val if val>0 else 0
    
    @property
    def game_time(self):
        """Virtual elapsed time in game milliseconds.
        """
        return self._game_time
    @property
    def paused(self):
        """The real time at which the clock was paused, or zero if the clock
        is not paused.
        """
        return self._paused
    
    @property
    def interpolate(self):
        interp = (self._real_time - self._last_update_real) / self._update_interval
        if interp < 0.0:
            return 0.0
        if interp > 1.0:
            return 1.0
        return interp
    
    def tick(self):
        # Now.
        real_time = self.get_ticks()
        self._real_time = real_time
        
        # Pre-emptive pause callback.
        if self._paused:
            if self.paused_callback:
                self.paused_callback()
            return
        
        # Check if update and frame are due.
        update_interval = self._update_interval
        game_time = self._game_time
        if real_time >= self._next_update:
            self.dt_update = update_interval  # fixed timestep: good
            self._last_update_real = real_time
            game_time += update_interval
            self._game_time = game_time
            self._last_update = game_time
            self._next_update = real_time + update_interval
            self.num_updates += 1
            if self.update_callback:
                self._update_ready = True
        if real_time - self._last_frame >= self._update_interval or (
                real_time + self.cost_of_frame < self._next_update and
                real_time >= self._next_frame):
            self.dt_frame = real_time - self._last_frame
            self._last_frame = real_time
            self._next_frame = real_time + self._frame_interval
            self.num_frames += 1
            if self.frame_callback:
                self._frame_ready = True

        # Check if a schedule is due, and when.
        sched_ready = False
        sched_due = 0
        if self._schedules:
            sched = self._schedules[0]
            sched_due = sched.lasttime + sched.interval
            if real_time >= sched_due:
                sched_ready = True
        
        # Run schedules if any are due.
        if self._update_ready or sched_ready:
            self._run_schedules()
        
        # Run the frame callback (moved inline to reduce function calls).
        if self.frame_callback and self._frame_ready:
            get_ticks = self.get_ticks
            t = get_ticks()
            self.frame_callback(self.interpolate)
            self.cost_of_frame = get_ticks() - t
            self._frame_ready = False
        
        # Flip metrics counters every second.
        if real_time >= self._next_second:
            self._flip(real_time)
        
        # Sleep to save CPU.
        if self.use_wait:
            upcoming_events = [
                self._next_frame,
                self._next_update,
                self._next_second,
            ]
            if sched_due != 0:
                upcoming_events.append(sched_due)
            next_due = functools.reduce(min, upcoming_events)
            t = self.get_ticks()
            time_to_sleep = next_due - t
            if time_to_sleep >= 0.002:
                time.sleep(time_to_sleep)
        
    def pause(self):
        """Pause the clock so that time does not elapse.
        
        While the clock is paused, no schedules will fire and tick() returns
        immediately without progressing internal counters. Game loops that
        completely rely on the clock will need to take over timekeeping and
        handling events; otherwise, the game will appear to deadlock. There are
        many ways to solve this scenario. For instance, another clock can be
        created and used temporarily, and the original swapped back in and
        resumed when needed.
        """
        self._paused = self.get_ticks()
    
    def resume(self):
        """Resume the clock from the point that it was paused."""
        real_time = self.get_ticks()
        paused = self._paused
        for item in self._schedules:
            dt = paused - item.lasttime
            item.lasttime = real_time - dt
        self._last_update_real = real_time - (paused - self._last_update_real)
        self._paused = 0
        self._real_time = real_time
    
    def schedule_interval(self, func, interval, life=0, args=[]):
        """Schedule an item to be called back each time an interval elapses.
        
        While the clock is paused time does not pass.
        
        Parameters:
            func -> The callback function.
            interval -> The time in seconds (float) between calls.
            life -> The number of times the callback will fire, after which the
                schedule will be removed. If the value 0 is specified, the event
                will persist until manually unscheduled.
            args -> A list that will be passed to the callback as an unpacked
                sequence, like so: item.func(*[item.interval]+item.args).
            
        """
        # self.unschedule(func)
        item = _IntervalItem(
            func, interval, self.get_ticks(), life, [interval]+list(args))
        self._schedules.append(item)
        self._need_sort = True
        return item.id
    
    def unschedule(self, func):
        """Unschedule managed functions. All matching items are removed."""
        sched = self._schedules
        for item in list(sched):
            if item.func == func:
                sched.remove(item)

    def unschedule_by_id(self, id):
        """Unschedule a single managed function by the unique ID that is
        returned by schedule_interval().
        """
        sched = self._schedules
        for item in list(sched):
            if item.id == id:
                sched.remove(item)                
    @staticmethod
    def _interval_item_sort_key(item):
        return item.lasttime + item.interval
    
    def _run_schedules(self):
        get_ticks = self.get_ticks
        
        # Run the update callback.
        if self.update_callback and self._update_ready:
            t = get_ticks()
            self.update_callback(self.dt_update)
            self.cost_of_update = get_ticks() - t
            self._update_ready = False
        
        # Run the interval callbacks.
        if self._need_sort:
            self._schedules.sort(key=self._interval_item_sort_key)
            self._need_sort = False
        real_time = self._real_time
        for sched in self._schedules:
            interval = sched.interval
            due = sched.lasttime + interval
            if real_time >= due:
                sched.func(*sched.args)
                sched.lasttime += interval
                need_sort = True
                if sched.life > 0:
                    if sched.life == 1:
                        self._unschedules.append(sched.id)
                        need_sort = False
                    else:
                        sched.life -= 1
                if need_sort:
                    self._need_sort = True
            else:
                break
        if self._unschedules:
            for id in self._unschedules:
                self.unschedule_by_id(id)
            del self._unschedules[:]
    
    def _flip(self, real_time):
        self.ups = self.num_updates
        self.fps = self.num_frames
        
        self.num_updates = 0
        self.num_frames = 0
        
        self._last_second = real_time
        self._next_second += 1.0

from gameclock import GameClock

"""
USAGE TIPS

When first trying this demo follow these steps. These tips assume the
stock (unmodified) settings are used.

    1.  Initially the game uses a Pygame clock loop, unthrottled. Use this
        mode to compare the maximum frame rate between this mode and the
        GameClock loop. Press the M key to toggle frame rate throttling.
    2.  Press the M key to throttle Pygame to 30 FPS. This is the typical
        method employed in Pygame to fix the rate of game ticks.
    3.  Press the L key to swith to GameClock loop. Note the UPS (updates
        per second) are 30, as with the Pygame clock. The frame rate should
        be much higher, and the motion of the balls should be smoother.
    4.  Press the Tab key to cycle GameClock to the next settings, which
        throttle the frame rate at 120 per second. Switch between Pygame and
        GameClock with the L key and compare the smoothness of the motion.
    5.  In GameClock mode with a CPU meter running press the W key to toggle
        Wait (GameClock uses time.wait()) and watch the effect on CPU usage.
    6.  Press the Tab key to watch how smoothness of motion is affected when
        the GameClock frame rate is throttled to 60 FPS, and again at 30.
        Note that at 30 FPS there is no apparent difference between
        GameClock and Pygame.
    7.  Press the Tab key again to view GameClock throttled to 6 UPS. Ball
        class implements two kinds of interpolation: motion, and screen edge
        collision. Use the P key to toggle screen edge prediction. Note
        that when Predict is on the balls behave well when colliding with
        screen edges. When Predict is off predict() assumes it will never
        change course, and update() snaps it back from the predicted
        position. The effect is visually jarring, and is visible even at
        higher frame rates.
    8.  Pressing K toggles whether collisions kill balls. It does not
        toggle collision detection. There is no appreciable difference here
        between Pygame and GameClock.
    9.  Pressing B creates 25 more balls.
    10. There are a couple gotchas with GameClock that have been called out
        in code comments. See update_gameclock().

ABOUT THE DEMO

This demo sends a ball careening about the window. It is probably not the
best usage for the GameClock class, but it provides a good basis for
demonstrating linear motion prediction, and salving an eyesore with some
judicious collision prediction.

You could certainly use the GameClock simply as a timer and FPS throttle,
but that only scratches the surface.

With an implementation like this demo you're deciding you want to update
some visual aspects of the game as often as possible, while time passes at a
slower, constant rate for the game mechanics. This is done by separating the
game mechanics routine from the display routine and calling them on
independent cycles. If the game mechanics are comparatively more costly in
computing power, there is potentially a lot of benefit in choosing to update
the mechanics at a much lower rate than updating frames for display.

Of course, in order to update the display meaningfully you need to modify
it. Otherwise you're seeing the same image posted repeatedly. But if the
display changes are waiting on game mechanics to post, you can only update
the display as fast as you can compute the entire world. This is where
prediction fits in: updating the display in advance of the game mechanics.

The design problem is what do you predict? First, it should make a positive
difference in the user experience. Second, the more you add to your display
computation the lower your frame rate.

There are two kinds of prediction Ball can use: motion and collision. Once
we start predicting the motion we notice that when the ball collides with
the screen edge the rebound jars the eye. This is because simple motion
prediction assumes there will be no course changes and overshoots the edge.
In most cases the prediction is right, but in edge collision it is wrong,
and the next update snaps it back from the predicted position.

If this were invisible it wouldn't be a problem. Rather it is quite
annoying. The problem can be solved by predicting collisions, making
update() and predict() adjust their calculations by the interpolation value
at the time the collision occurred. And we see the ill effect is resolved
when we turn on screen-edge collision prediction (enabling with the P key).

A notable distinction is there are two collision conditions that change the
ball's behavior: collision with the screen edges and collision with another
ball. The distinction is that predicting screen edge collision makes a
visible difference.

By contrast, when two balls collide it does not visually matter whether they
react immediately or there is a delay, even at a very low 6 updates-per-
second. Therefore, the potentially expensive ball-vs-ball collision
detection can be done less frequently. Of course, if you're shooting very
fast bullets it would matter, but that doesn't apply to our demo.

Ultimately the choice of what to predict and what to defer is a project
decision. Hopefully this explanation has illuminated the reasoning used in
designing the demo's prediction capabilities and has shown that if done
intelligently, such tricks can add virtual performance to your application.

THE INTERFACE

Input keys:
    L -> Loop; Toggle between Pygame and GameClock timed loops.
    Tab:[TicksPerSecond MaxFPS] -> Cycle through the GameClock settings.
    K -> Kill; Toggle whether collisions kill balls.
    M -> MaxFPS; Toggle Pygame clock's MaxFPS throttle.
    P -> Predict; Toggle whether the ball uses its GameClock predictive algorithm.
    W -> Wait; Toggle whether GameClock uses time.sleep().
    B -> Balls; Make 25 more balls.

The title bar displays the runtime settings and stats. If the stats are
chopped off you can increase the window width in main().

Stats:
    Runtime:[FPS=%d UPS=%d] -> The number of frames and updates that
        occurred during the previous second.
"""
import random
import pygame
from pygame.locals import (
    Color, QUIT, KEYDOWN, K_ESCAPE, K_TAB, K_1, K_b, K_k, K_l, K_m, K_p, K_w,
)
# GameClock control.
TICKS_PER_SECOND = 30.0
MAX_FRAME_SKIP = 5.0
# Ball control.
MAX_BALL_SPEED = 240.0  # pixels per second
INIT_BALLS = 100        # initial number of balls
## Note to tweakers: Try adjusting these GameClock settings before adjusting
## the fundamental ones above.
SETTINGS = (
    # TicksPerSecond   MaxFPS
    (TICKS_PER_SECOND, 0),                     # unlimited FPS
    (TICKS_PER_SECOND, MAX_BALL_SPEED / 2),    # max FPS is half ball speed
    (TICKS_PER_SECOND, TICKS_PER_SECOND * 2),  # max FPS is double TPS
    (TICKS_PER_SECOND, TICKS_PER_SECOND),      # max FPS is TPS
    (TICKS_PER_SECOND / 5, 0),                 # TPS is 6; unlimited FPS
)
# Use Pygame clock, or GameClock.
USE_PYGAME_CLOCK = True
PYGAME_FPS = 0
# Ball uses prediction? Enable this to see how combining interpolation and
# prediction can smooth frames between updates, and solve visual artifacts.
USE_PREDICTION = True
# Balls are killed when they collide.
DO_KILL = False
# Appearance.
BGCOLOR = Color(175,125,125)
## NO MORE CONFIGURABLES.
# Game objects.
elapsed = 0
game_ticks = 0
pygame_clock = None
clock = None
screen = None
screen_rect = None
eraser_image = None
sprite_group = None

def logger(*args):
    if logging:
        print ' '.join([str(a) for a in args])
logging = True

class Ball(pygame.sprite.Sprite):
    size = (40, 40)

    def __init__(self):
        pygame.sprite.Sprite.__init__(self)
        self.image = pygame.surface.Surface(self.size)
        self.rect = self.image.get_rect()
        self._detail_block(self.image, Color('red'), self.rect)
        w, h = screen_rect.size
        self.x = float(random.randrange(self.size[0], w - self.size[0]))
        self.y = float(random.randrange(self.size[1], h - self.size[1]))
        self.rect.center = round(self.x), round(self.y)
        self.dx = random.choice([-1, 1])
        self.dy = random.choice([-1, 1])
        # Speed is pixels per second.
        self.speed = MAX_BALL_SPEED
        ## These prorate the speed step made in update() by remembering the
        ## interpolation value when a screen edge collision occurs. This
        ## removes all occurrence of twitchy rebounds.
        self.predictive_rebound_x = 0.0
        self.predictive_rebound_y = 0.0

    def _dim(self, color, frac):
        c = Color(*color)
        c.r = int(round(c.r * frac))
        c.g = int(round(c.g * frac))
        c.b = int(round(c.b * frac))
        return c

    def _detail_block(self, image, color, rect):
        image.fill(self._dim(color, 0.6))
        tl, tr = (0, 0), (rect.width - 1, 0)
        bl, br = (0, rect.height - 1), (rect.width - 1, rect.height - 1)
        pygame.draw.lines(image, color, False, (bl, tl, tr))
        pygame.draw.lines(image, self._dim(color, 0.3), False, (tr, br, bl))

    def update(self, *args):
        """Call once per tick to update state."""
        ## If prediction is enabled then predict() handles rebounds.
        use_prediction = list(args).pop(0)
        if not use_prediction:
            self._rebound(0.0)
        ## Speed step needs to be adjusted by the value of interpolation
        ## at the time the ball collided with an edge (predictive_rebound_*).
        self.x += self.dx * self.speed / TICKS_PER_SECOND * (1 - self.predictive_rebound_x)
        self.y += self.dy * self.speed / TICKS_PER_SECOND * (1 - self.predictive_rebound_y)
        self.predictive_rebound_x, self.predictive_rebound_y = 0.0, 0.0
        self.rect.center = round(self.x), round(self.y)

    def predict(self, interpolation, use_prediction):
        """Call as often as you like. Hitting the edge is predicted, and the
        ball's direction is changed appropriately."""
        ## If prediction is not enabled then update() handles rebounds.
        if use_prediction:
            self._rebound(interpolation)
        ## Interpolation needs to be adjusted by the value of interpolation
        ## at the time the ball collided with an edge (predictive_rebound_*).
        x = self.x + self.dx * self.speed / TICKS_PER_SECOND * (interpolation - self.predictive_rebound_x)
        y = self.y + self.dy * self.speed / TICKS_PER_SECOND * (interpolation - self.predictive_rebound_y)
        self.rect.center = round(x), round(y)

    def _rebound(self, interpolation):
        ## 1. Handle screen edge collisions.
        ## 2. Update the prediction_rebound_* adjusters.
        r = self.rect
        if r.left < screen_rect.left:
            r.left = screen_rect.left
            self.x = float(r.centerx)
            self.dx = -self.dx
            self.predictive_rebound_x = interpolation
        elif r.right >= screen_rect.right:
            r.right = screen_rect.right - 1
            self.x = float(r.centerx)
            self.dx = -self.dx
            self.predictive_rebound_x = interpolation
        if r.top < screen_rect.top:
            r.top = screen_rect.top
            self.y = float(r.centery)
            self.dy = -self.dy
            self.predictive_rebound_y = interpolation
        elif r.bottom >= screen_rect.bottom:
            r.bottom = screen_rect.bottom - 1
            self.y = float(r.centery)
            self.dy = -self.dy
            self.predictive_rebound_y = interpolation

def update_pygame():
    """Update function for use with Pygame clock."""
    global elapsed
    sprite_group.update(False)
    handle_collisions()
    elapsed += pygame_clock.get_time()
    if elapsed >= 1000:
        set_caption_pygame()
        elapsed -= 1000

def display_pygame():
    """Display function for use with Pygame clock."""
    sprite_group.clear(screen, eraser_image)
    sprite_group.draw(screen)
    pygame.display.update()

def update_gameclock(dt):
    """Update function for use with GameClock."""
    global game_ticks
    ## GOTCHA: Both Ball.update() and Ball.predict() modify sprite
    ## position, so the update and display routines must each perform
    ## erasure. This results in redundant erasures whenever an update and
    ## frame are ready in the same pass. This happens almost every game tick
    ## at high frame rates, often enough that an avoidance optimization
    ## would gain a few FPS.
    sprite_group.clear(screen, eraser_image)
    sprite_group.update(USE_PREDICTION)
    handle_collisions()

def display_gameclock(interpolation):
    """Display function for use with GameClock."""
    ## GOTCHA: See the comment in update_gameclock().
    sprite_group.clear(screen, eraser_image)
    for ball in sprite_group:
        ball.predict(interpolation, USE_PREDICTION)
    sprite_group.draw(screen)
    pygame.display.update()

def handle_collisions():
    """Handle collisions for both Pygame clock and GameClock."""
    for sprite in sprite_group:
        for other in pygame.sprite.spritecollide(sprite, sprite_group, False):
            if sprite is not other and DO_KILL:
                sprite.kill()
                other.kill()

def set_caption_pygame():
    """Set window caption for both Pygame clock and GameClock."""
    pygame.display.set_caption(
        'Loop=Pygame Kill=%s MaxFPS=%d Runtime:[FPS=%d Balls=%d]' % (
        DO_KILL, PYGAME_FPS, pygame_clock.get_fps(), len(sprite_group)))

def set_caption_gameclock(dt):
    pygame.display.set_caption(
        ' '.join(('Loop=GameClock Tab:[TPS=%d MaxFPS=%d] Predict=%s Wait=%s Kill=%s',
                 'Runtime:[FPS=%d UPS=%d Balls=%d]')) % (
        clock.max_ups, clock.max_fps, USE_PREDICTION, clock.use_wait,
        DO_KILL, clock.fps, clock.ups, len(sprite_group)))

def main():
    global clock, pygame_clock, screen, screen_rect, sprite_group, eraser_image
    global USE_PYGAME_CLOCK, DO_KILL, USE_PREDICTION, PYGAME_FPS
    screen = pygame.display.set_mode((800, 600))
    screen.fill(BGCOLOR)
    screen_rect = screen.get_rect()
    eraser_image = screen.copy()
    which_settings = 0
    pygame_clock = pygame.time.Clock()
    clock = GameClock(*SETTINGS[which_settings], update_callback=update_gameclock, frame_callback=display_gameclock)
    clock.schedule_interval(set_caption_gameclock, 1.0)
    clock.use_wait = False
    sprite_group = pygame.sprite.Group([Ball() for i in range(INIT_BALLS)])
    #
    game_is_running = True
    while game_is_running:
        if USE_PYGAME_CLOCK:
            pygame_clock.tick(PYGAME_FPS)
            update_pygame()
            display_pygame()
        else:
            clock.tick()
        #
        for e in pygame.event.get():
            if e.type == QUIT: quit()
            elif e.type == KEYDOWN:
                if e.key == K_ESCAPE: quit()
                elif e.key == K_TAB:
                    which_settings += 1
                    if which_settings >= len(SETTINGS):
                        which_settings = 0
                    (clock.max_ups, clock.max_fps) = SETTINGS[which_settings]
                elif e.key == K_1:
                    sprite_group.add(Ball())
                elif e.key == K_b:
                    sprite_group.add([Ball() for i in range(25)])
                elif e.key == K_k:
                    DO_KILL = not DO_KILL
                elif e.key == K_l:
                    USE_PYGAME_CLOCK = not USE_PYGAME_CLOCK
                elif e.key == K_m:
                    if PYGAME_FPS == 0:
                        PYGAME_FPS = 30
                    else:
                        PYGAME_FPS = 0
                elif e.key == K_p:
                    USE_PREDICTION = not USE_PREDICTION
                elif e.key == K_w:
                    clock.use_wait = not clock.use_wait

pygame.init()
main()