pgzero-plus 0.1.0__py3-none-any.whl

pgzero/game.py

@@ -0,0 +1,573 @@
+import sys
+import operator
+import time
+import types
+from time import perf_counter, sleep
+
+import pygame
+import pgzero.clock
+import pgzero.keyboard
+import pgzero.screen
+import pgzero.loaders
+import builtins
+
+from . import constants
+from typing import Any
+
+screen = None  # This global surface is what actors draw to
+DISPLAY_FLAGS = pygame.SHOWN
+
+
+class Game:
+    """
+    Simple game-wide state container for beginner projects.
+
+    Use this to keep track of things like score, level, timers, and
+    the current game state without needing lots of global variables.
+    """
+
+    def __init__(self):
+        self._start_callback = None
+        self._clock = None
+        self._is_restarting = False
+        self._restart_clear_mode = "immediate"
+        self.reset()
+
+    def _bind_engine(self, start_callback=None, clock=None):
+        self._start_callback = start_callback
+        self._clock = clock
+
+    def reset(self):
+        """Reset the game back to its default starting values."""
+        self.state = "playing"
+
+        self.score = 0
+        self.level = 1
+
+        self.timer = 0
+        self.frame_count = 0
+
+        self.data = {}
+
+    def restart(self, delay=0.0, clear_clock="immediate"):
+        """
+        Restart the game.
+
+        clear_clock options:
+        - "immediate": clear scheduled events right away
+        - "on_restart": clear scheduled events when the restart actually happens
+        - "never": do not clear scheduled events
+
+        Note: any previously scheduled restart is always unscheduled first.
+        """
+        if self._is_restarting:
+            raise RuntimeError(
+                "game.restart() was called from inside start(). "
+                "Do not call game.restart() inside start(). "
+                "The library already calls start() during restart."
+            )
+
+        if clear_clock not in ("immediate", "on_restart", "never"):
+            raise ValueError("clear_clock must be 'immediate', 'on_restart', or 'never'")
+
+        self._check_can_delay(delay)
+
+        self._restart_clear_mode = clear_clock
+
+        if self._clock:
+            # Always cancel any pending restart first
+            self._clock.unschedule(self._do_restart)
+
+            # Only clear everything else immediately if requested
+            if clear_clock == "immediate":
+                self._clock.clear()
+
+        if delay and delay > 0:
+            self._clock.schedule_unique(self._do_restart, delay)
+            return
+
+        self._do_restart()
+
+    def _check_can_delay(self, delay):
+        """Raise a helpful error if a delayed restart can't be scheduled.
+
+        Delays need the game clock, which is only connected once the game
+        starts running, so this happens when the call is at the top level
+        of the game file instead of inside a function.
+        """
+        if delay and delay > 0 and self._clock is None:
+            raise RuntimeError(
+                "A delayed restart can only be used while the game is "
+                "running. Call it from inside a function such as update() "
+                "or on_key_down(), not at the top level of your file."
+            )
+
+    def _do_restart(self):
+        if self._is_restarting:
+            return
+
+        self._is_restarting = True
+        try:
+            # Delay clock clearing until the actual restart moment
+            if self._clock and self._restart_clear_mode == "on_restart":
+                self._clock.clear()
+                # clear() may remove this scheduled callback, so make sure
+                # we do not accidentally re-enter or depend on future calls
+
+            self.reset()
+            if callable(self._start_callback):
+                self._start_callback()
+        finally:
+            self._is_restarting = False
+
+    def _end(self, state, restart_after, clear_clock):
+        """Leave the "playing" state, optionally scheduling a restart."""
+        if self.state != "playing":
+            return
+        self._check_can_delay(restart_after)
+        self.state = state
+
+        if self._clock and clear_clock == "immediate":
+            self._clock.clear()
+
+        if restart_after is not None:
+            restart_mode = clear_clock if clear_clock != "immediate" else "never"
+            self.restart(restart_after, clear_clock=restart_mode)
+
+    def win(self, restart_after=None, clear_clock="immediate"):
+        self._end("won", restart_after, clear_clock)
+
+    def lose(self, restart_after=None, clear_clock="immediate"):
+        self._end("lost", restart_after, clear_clock)
+
+    def over(self, restart_after=None, clear_clock="immediate"):
+        self._end("over", restart_after, clear_clock)
+
+    def start(self):
+        """Start or resume normal gameplay."""
+        self.state = "playing"
+
+    def pause(self):
+        """Pause the game."""
+        if self.state == "playing":
+            self.state = "paused"
+
+    def resume(self):
+        """Resume the game if paused."""
+        if self.state == "paused":
+            self.state = "playing"
+
+    def next_level(self):
+        """Advance to the next level."""
+        self.level += 1
+
+    def add_score(self, points):
+        """Increase the score by the given number of points."""
+        self.score += points
+
+    def tick(self, dt):
+        """
+        Update common counters.
+        dt = time since last frame (in seconds)
+        """
+        self.frame_count += 1
+
+        if self.state == "playing":
+            self.timer += dt
+
+    # These two methods don't change how attributes work at runtime. Their
+    # type hints tell editors and linters (e.g. Pylance) that students may
+    # add their own attributes, such as ``game.lives = 3``, without being
+    # warned that the attribute doesn't exist. Do not remove them.
+    def __getattr__(self, name: str) -> Any:
+        raise AttributeError(f"'Game' object has no attribute '{name}'")
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        object.__setattr__(self, name, value)
+
+
+def exit():
+    """Wait for up to a second for all sounds to play out
+    and then exit
+    """
+    t0 = time.time()
+    while pygame.mixer.get_busy():
+        time.sleep(0.1)
+        if time.time() - t0 > 1.0:
+            break
+    sys.exit()
+
+
+def positional_parameters(handler):
+    """Get the positional parameters of the given function."""
+    code = handler.__code__
+    return code.co_varnames[: code.co_argcount]
+
+
+class DEFAULTICON:
+    """Sentinel indicating that we want to use the default icon."""
+
+
+class PGZeroGame:
+    """The core game loop for Pygame Zero.
+
+    Dispatch events, call update functions, draw. Repeat.
+    """
+
+    def __init__(self, mod: types.ModuleType, fps: bool = False):
+        """Construct a game loop given the pgzero module mod.
+
+        If fps is True, show a FPS count at the bottom left of the window.
+        """
+        self.mod = mod
+        self.screen = None
+        self.width = None
+        self.height = None
+        self.title = None
+        self.icon = None
+        self.fps = fps
+        self.keyboard = pgzero.keyboard.keyboard
+        self.handlers = {}
+
+    def reinit_screen(self) -> bool:
+        """Reinitialise the window.
+
+        Return True if the dimensions of the screen changed.
+
+        """
+        global screen
+        changed = False
+        mod = self.mod
+
+        icon = getattr(self.mod, "ICON", DEFAULTICON)
+        if icon and icon != self.icon:
+            self.show_icon()
+
+        w = getattr(mod, "WIDTH", 800)
+        h = getattr(mod, "HEIGHT", 600)
+        if w != self.width or h != self.height:
+            self.screen = pygame.display.set_mode((w, h), DISPLAY_FLAGS, vsync=1)
+            pgzero.screen.screen_instance._set_surface(self.screen)
+
+            # Set the global screen that actors blit to
+            screen = self.screen
+            self.width = w
+            self.height = h
+
+            # Dimensions changed, request a redraw
+            changed = True
+
+        title = getattr(self.mod, "TITLE", "Pygame Zero Game")
+        if title != self.title:
+            pygame.display.set_caption(title)
+            self.title = title
+
+        return changed
+
+    @staticmethod
+    def show_default_icon():
+        """Show a default icon loaded from Pygame Zero resources."""
+        from io import BytesIO
+        from pkgutil import get_data
+
+        buf = BytesIO(get_data(__name__, "data/icon.png"))
+        pygame.display.set_icon(pygame.image.load(buf))
+
+    def show_icon(self):
+        icon = getattr(self.mod, "ICON", DEFAULTICON)
+        if icon is DEFAULTICON:
+            self.show_default_icon()
+        else:
+            pygame.display.set_icon(pgzero.loaders.images.load(icon))
+        self.icon = icon
+
+    EVENT_HANDLERS = {
+        pygame.MOUSEBUTTONDOWN: "on_mouse_down",
+        pygame.MOUSEBUTTONUP: "on_mouse_up",
+        pygame.MOUSEMOTION: "on_mouse_move",
+        pygame.KEYDOWN: "on_key_down",
+        pygame.KEYUP: "on_key_up",
+        constants.MUSIC_END: "on_music_end",
+    }
+
+    def map_buttons(val):
+        return {c for c, pressed in zip(constants.mouse, val) if pressed}
+
+    EVENT_PARAM_MAPPERS = {"buttons": map_buttons, "button": constants.mouse, "key": constants.keys}
+
+    def load_handlers(self):
+        from .spellcheck import spellcheck
+
+        spellcheck(vars(self.mod))
+        self.handlers = {}
+        for type, name in self.EVENT_HANDLERS.items():
+            handler = getattr(self.mod, name, None)
+            if callable(handler):
+                self.handlers[type] = self.prepare_handler(handler)
+
+    def prepare_handler(self, handler):
+        """Adapt a pgzero game's raw handler function to take a Pygame Event.
+
+        Returns a one-argument function of the form ``handler(event)``.
+        This will ensure that the correct arguments are passed to the raw
+        handler based on its argument spec.
+
+        The wrapped handler will also map certain parameter values using
+        callables from EVENT_PARAM_MAPPERS; this ensures that the value of
+        'button' inside the handler is a real instance of constants.mouse,
+        which means (among other things) that it will print as a symbolic value
+        rather than a naive integer.
+
+        """
+        code = handler.__code__
+        param_names = code.co_varnames[: code.co_argcount]
+
+        def make_getter(mapper, getter):
+            if mapper:
+                return lambda event: mapper(getter(event))
+            return getter
+
+        param_handlers = []
+        for name in param_names:
+            getter = operator.attrgetter(name)
+            mapper = self.EVENT_PARAM_MAPPERS.get(name)
+            param_handlers.append((name, make_getter(mapper, getter)))
+
+        def prep_args(event):
+            return {name: get(event) for name, get in param_handlers}
+
+        def new_handler(event):
+            try:
+                prepped = prep_args(event)
+            except ValueError:
+                # If we couldn't construct the keys/mouse objects representing
+                # the button that was pressed, then skip the event handler.
+                #
+                # This happens because Pygame can generate key codes that it
+                # does not have constants for.
+                return
+            else:
+                return handler(**prepped)
+
+        return new_handler
+
+    def get_update_func(self):
+        """Get a one-argument update function.
+
+        If the module defines a function matching ::
+
+            update(dt)
+
+        or ::
+
+            update()
+
+        then this will be called. Otherwise return a no-op function.
+
+        """
+        try:
+            update = self.mod.update
+        except AttributeError:
+            return None
+        else:
+            if update.__code__.co_argcount == 0:
+                return lambda dt: update()
+            return update
+
+    def get_draw_func(self):
+        """Get a draw function.
+
+        If no draw function is define, raise an exception.
+
+        """
+        try:
+            draw = self.mod.draw
+        except AttributeError:
+            return lambda: None
+        else:
+            if draw.__code__.co_argcount != 0:
+                raise TypeError("draw() must not take any arguments.")
+            return draw
+
+    def get_start_func(self):
+        """Get the start() function from the user module if it exists."""
+        start = getattr(self.mod, "start", None)
+        if start is not None and not callable(start):
+            raise TypeError(f"{start!r} is not callable")
+        return start
+
+    def run(self):
+        """Invoke the main loop, and then clean up."""
+        try:
+            self.mainloop()
+        finally:
+            pygame.display.quit()
+            pygame.mixer.quit()
+
+    def inject_global_handlers(self):
+        """Inject handlers provide by the Pygame Zero system.
+
+        Some of these wrap user handlers so must be injected later.
+        """
+        self.handlers[pygame.QUIT] = lambda e: sys.exit(0)
+        self.handlers[pygame.VIDEOEXPOSE] = lambda e: None
+
+        user_key_down = self.handlers.get(pygame.KEYDOWN)
+        user_key_up = self.handlers.get(pygame.KEYUP)
+
+        def key_down(event):
+            if event.key == pygame.K_q and event.mod & (pygame.KMOD_CTRL | pygame.KMOD_META):
+                sys.exit(0)
+            self.keyboard._press(event.key)
+            if user_key_down:
+                return user_key_down(event)
+
+        def key_up(event):
+            self.keyboard._release(event.key)
+            if user_key_up:
+                return user_key_up(event)
+
+        self.handlers[pygame.KEYDOWN] = key_down
+        self.handlers[pygame.KEYUP] = key_up
+
+    def tick_game_state(self, dt):
+        """Tick the global game object if it exists."""
+        game_obj = getattr(self.mod, "game", None)
+
+        if game_obj is None:
+            game_obj = getattr(builtins, "game", None)
+
+        if game_obj is None:
+            return False
+
+        tick = getattr(game_obj, "tick", None)
+        if not callable(tick):
+            return False
+
+        tick(dt)
+        return True
+
+    def handle_events(self, dt, update) -> bool:
+        """Handle all events for the current frame.
+
+        Return True if an event was handled.
+        """
+        updated = False
+
+        for event in pygame.event.get():
+            if event.type == constants.MUSIC_END:
+                # internal music bookkeeping
+                from . import music
+
+                music._on_music_end()
+
+            handler = self.handlers.get(event.type)
+            if handler:
+                handler(event)
+                updated = True
+
+        clock = pgzero.clock.clock
+        clock.tick(dt)
+        updated |= clock.fired
+
+        updated |= self.tick_game_state(dt)
+
+        if update:
+            update(dt)
+            updated = True
+
+        updated |= self.reinit_screen()
+        return updated
+
+    def mainloop(self):
+        """Run the main loop of Pygame Zero."""
+        self.reinit_screen()
+
+        update = self.get_update_func()
+        draw = self.get_draw_func()
+        start = self.get_start_func()
+
+        game_obj = getattr(self.mod, "game", None)
+        if game_obj is None:
+            game_obj = getattr(builtins, "game", None)
+
+        if game_obj is not None and hasattr(game_obj, "_bind_engine"):
+            game_obj._bind_engine(start_callback=start, clock=pgzero.clock.clock)
+
+        self.load_handlers()
+        self.inject_global_handlers()
+
+        if start:
+            start()
+
+        logic_timer = Timer("logic", print=self.fps)
+        draw_timer = Timer("draw", print=self.fps)
+        for i, dt in enumerate(frames(60)):
+            with logic_timer:
+                updated = self.handle_events(dt, update)
+
+            if updated:
+                with draw_timer:
+                    draw()
+
+                if self.fps and i and i % 60 == 0:
+                    ftime_ms = draw_timer.get_mean() + logic_timer.get_mean()
+                    fps = 1000 / ftime_ms
+
+                    print(f"fps: {fps:0.1f}  time per frame: {ftime_ms:0.1f}ms")
+                pygame.display.flip()
+
+
+def frames(fps=60):
+    """Iterate over frames at the given fps, yielding time delta (in s)."""
+    tgt = 1 / fps  # target frame time
+
+    t = perf_counter()
+    dt = tgt
+
+    while True:
+        yield dt
+        nextt = perf_counter()
+        dt = nextt - t
+        if dt < tgt:
+            sleep(tgt - dt)
+            nextt = perf_counter()
+            dt = nextt - t
+        t = nextt
+
+
+class Timer:
+    """Context manager to time the game loop."""
+
+    __slots__ = (
+        "name",
+        "total",
+        "count",
+        "worst",
+        "start",
+        "print",
+    )
+
+    def __init__(self, name, print=False):
+        self.name = name
+        self.total = 0
+        self.count = 0
+        self.worst = 0
+        self.print = print
+
+    def __enter__(self):
+        self.start = perf_counter()
+
+    def __exit__(self, *_):
+        t = (perf_counter() - self.start) * 1e3
+        self.count += 1
+        self.total += t
+        if t > self.worst:
+            self.worst = t
+
+    def get_mean(self) -> float:
+        mean = self.total / self.count
+        if self.print:
+            print(f"{self.name} mean: {mean:0.1f}ms  " f"worst: {self.worst:0.1f}ms")
+        self.worst = self.total = self.count = 0
+        return mean

pgzero/keyboard.py

@@ -0,0 +1,67 @@
+import re
+from warnings import warn
+
+from .constants import keys
+
+DEPRECATED_KEY_RE = re.compile(r"[A-Z]")
+PREFIX_RE = re.compile(r"^K_(?!\d$)")
+
+
+class Keyboard:
+    """The current state of the keyboard.
+
+    Each attribute represents a key. For example, ::
+
+        keyboard.a
+
+    is True if the 'A' key is depressed, and False otherwise.
+
+    """
+
+    # The current key state. This may as well be a class attribute - there's
+    # only one keyboard.
+    _pressed = set()
+
+    def __getattr__(self, kname):
+        # return is a reserved word, so alias enter to return
+        if kname == "enter":
+            kname = "return"
+        elif DEPRECATED_KEY_RE.match(kname):
+            # warn(
+            #     "Uppercase keyboard attributes (eg. keyboard.%s) are "
+            #     "deprecated." % kname,
+            #     DeprecationWarning,
+            #     2
+            # )
+            kname = PREFIX_RE.sub("", kname)
+        try:
+            key = keys[kname.upper()]
+        except AttributeError:
+            raise AttributeError('The key "%s" does not exist' % key)
+        return key.value in self._pressed
+
+    def _press(self, key):
+        """Called by Game to mark the key as pressed."""
+        self._pressed.add(key)
+
+    def _release(self, key):
+        """Called by Game to mark the key as released."""
+        self._pressed.discard(key)
+
+    def __getitem__(self, k):
+        if isinstance(k, keys):
+            return k.value in self._pressed
+        else:
+            # warn(
+            #     "String lookup in keyboard (eg. keyboard[%r]) is "
+            #     "deprecated." % k,
+            #     DeprecationWarning,
+            #     2,
+            # )
+            return getattr(self, k)
+
+    def __repr__(self):
+        return "<Keyboard pressed={}>".format(self._pressed)
+
+
+keyboard = Keyboard()