Add a pause() function

[lordmauve]

It would be useful to have a pause() function in the builtins that completely pauses the game, and a corresponding unpause() (or make pause() toggle).

This should be useful in two different contexts:

• At the REPL
• To add a pause feature to games

[lucas-james]

I'm looking into this :)

[lordmauve]

I was playing with #123 and I think it's too simplistic.

Simply stopping the clock and update() function means that events will still be dispatched. This would mean that users have to write

if is_paused():
    return

in basically every event hook except the one that handles the pause key. This isn't really in keeping with the "zero boilerplate" goals of Pygame Zero.

We should instead also suspend dispatch of the event hooks while paused. This presents the problem of how to catch the pause key; I think a PAUSE_KEY global would be fine, eg.

PAUSE_KEY = keys.P

(defaulting to Ctrl-P if unspecified.)

However, if we throw away other events while paused, then other bad things happen: if keys were pressed when pause was enabled, then released while paused, when unpaused the game will be out of sync - it could think that keys are down that are not.

What we need to do is dispatch all events that we saw while paused, when resuming.

If we simply buffer events, then we may get other bad results (eg. many bullets fired at the same instant). It can also use unbounded memory to record the events. Instead we should coalesce input events and dispatch the minimum number of events to have indicated all input state changes, at the moment the game is unpaused.