pgzero-plus 0.1.0__py3-none-any.whl

pgzero/tilemaps.py

@@ -0,0 +1,307 @@
+import os
+import pygame
+import xml.etree.ElementTree as ET
+
+from . import loaders
+from .actor import Actor
+
+FLIP_H = 0x80000000
+FLIP_V = 0x40000000
+FLIP_D = 0x20000000
+GID_MASK = 0x0FFFFFFF
+
+
+def _get_tile_surface(tileset, tile_col, tile_row, map_tile_width, map_tile_height):
+    tx = tileset["margin"] + tile_col * (tileset["tile_width"] + tileset["spacing"])
+    ty = tileset["margin"] + tile_row * (tileset["tile_height"] + tileset["spacing"])
+
+    tile_rect = (tx, ty, tileset["tile_width"], tileset["tile_height"])
+    tile_surface = tileset["image"].subsurface(tile_rect)
+
+    return pygame.transform.scale(tile_surface, (map_tile_width, map_tile_height))
+
+
+class Tile(Actor):
+    def __init__(
+        self,
+        tileset,
+        tileset_firstgid,
+        tile_col,
+        tile_row,
+        map_col,
+        map_row,
+        map_tile_width,
+        map_tile_height,
+        scale=1.0,
+        flip_h=False,
+        flip_v=False,
+        flip_d=False,
+    ):
+        self._tileset = tileset
+        self.tileset_firstgid = tileset_firstgid
+        self._map_tile_width = map_tile_width
+        self._map_tile_height = map_tile_height
+
+        super().__init__(self._tile_surface(tile_col, tile_row))
+
+        self.scale = scale
+        self.flip_h = flip_h
+        self.flip_v = flip_v
+        self.flip_d = flip_d
+
+        self.set_map_position(map_col, map_row)
+
+    def set_tile_image(self, tile_col, tile_row):
+        self.image = self._tile_surface(tile_col, tile_row)
+
+    def _tile_surface(self, tile_col, tile_row):
+        """Check (tile_col, tile_row), record the tile ids and return the tile's surface."""
+        columns = self._tileset["columns"]
+        rows = self._tileset["rows"]
+        tile_count = self._tileset["tile_count"]
+
+        if tile_col < 0 or tile_col >= columns:
+            raise ValueError(f"tile_col must be between 0 and {columns - 1}")
+
+        if tile_row < 0 or tile_row >= rows:
+            raise ValueError(f"tile_row must be between 0 and {rows - 1}")
+
+        tile_id = tile_row * columns + tile_col
+
+        if tile_id >= tile_count:
+            raise ValueError(f"tile_col={tile_col}, tile_row={tile_row} points past the tileset's last tile.")
+
+        self.tile_col = tile_col
+        self.tile_row = tile_row
+        self.tile_id = tile_id
+        self.tile_gid = self.tileset_firstgid + self.tile_id
+
+        return _get_tile_surface(
+            self._tileset,
+            tile_col,
+            tile_row,
+            self._map_tile_width,
+            self._map_tile_height,
+        )
+
+    def set_map_position(self, map_col, map_row):
+        self.map_col = map_col
+        self.map_row = map_row
+
+        self.topleft = (
+            self._map_tile_width * map_col * self.scale,
+            self._map_tile_height * map_row * self.scale,
+        )
+
+    def copy(self, map_col=None, map_row=None):
+        if map_col is None:
+            map_col = self.map_col
+
+        if map_row is None:
+            map_row = self.map_row
+
+        return Tile(
+            tileset=self._tileset,
+            tileset_firstgid=self.tileset_firstgid,
+            tile_col=self.tile_col,
+            tile_row=self.tile_row,
+            map_col=map_col,
+            map_row=map_row,
+            map_tile_width=self._map_tile_width,
+            map_tile_height=self._map_tile_height,
+            scale=self.scale,
+            flip_h=self.flip_h,
+            flip_v=self.flip_v,
+            flip_d=self.flip_d,
+        )
+
+
+def _load_xml_from_maps(name):
+    text = loaders.maps.load(name)
+    return ET.fromstring(text)
+
+
+def _resolve_relative_map_path(base_name, relative_path):
+    base_dir = os.path.dirname(base_name)
+    if base_dir:
+        return os.path.normpath(os.path.join(base_dir, relative_path)).replace("\\", "/")
+    return relative_path
+
+
+def _count_tiles_that_fit(image_length, tile_length, margin, spacing):
+    """
+    Count how many tiles fit in one direction of a Tiled tileset image.
+
+    In Tiled, margin is the offset from the top/left edge to the first tile.
+    It is not necessarily repeated on the far right/bottom edge. Any extra
+    pixels after the final tile are just unused image space.
+    """
+    if tile_length <= 0:
+        raise ValueError("tile_length must be greater than 0")
+
+    if margin < 0:
+        raise ValueError("margin cannot be negative")
+
+    if spacing < 0:
+        raise ValueError("spacing cannot be negative")
+
+    usable_length = image_length - margin
+    if usable_length < tile_length:
+        return 0
+
+    return (usable_length + spacing) // (tile_length + spacing)
+
+
+def _load_tilesets(root, tmx_name):
+    tilesets = {}
+
+    for ts in root.findall("tileset"):
+        firstgid = int(ts.attrib["firstgid"])
+
+        if "source" in ts.attrib:
+            tsx_name = _resolve_relative_map_path(tmx_name, ts.attrib["source"])
+            ts_root = _load_xml_from_maps(tsx_name)
+            tileset_base_name = tsx_name
+        else:
+            ts_root = ts
+            tileset_base_name = tmx_name
+
+        image = ts_root.find("image")
+        if image is None:
+            raise ValueError("Tileset is missing an <image> tag")
+
+        # For external TSX files, the image path is relative to the TSX file,
+        # not necessarily the TMX map that imports it.
+        image_name = _resolve_relative_map_path(tileset_base_name, image.attrib["source"])
+        tilesheet = loaders.mapimages.load(image_name)
+
+        tile_width = int(ts_root.attrib["tilewidth"])
+        tile_height = int(ts_root.attrib["tileheight"])
+        spacing = int(ts_root.attrib.get("spacing", 0))
+        margin = int(ts_root.attrib.get("margin", 0))
+
+        calculated_columns = _count_tiles_that_fit(
+            tilesheet.get_width(),
+            tile_width,
+            margin,
+            spacing,
+        )
+        calculated_rows = _count_tiles_that_fit(
+            tilesheet.get_height(),
+            tile_height,
+            margin,
+            spacing,
+        )
+
+        # Tiled writes columns and tilecount into image-based TSX tilesets.
+        # Use values when present because they exactly describe how Tiled
+        # assigned local tile ids. Fall back to image-based calculation for
+        # older or hand-written files.
+        columns = int(ts_root.attrib.get("columns", calculated_columns))
+        if columns <= 0:
+            columns = calculated_columns
+
+        if columns <= 0:
+            raise ValueError("Tileset does not contain any columns of tiles")
+
+        tile_count = int(ts_root.attrib.get("tilecount", columns * calculated_rows))
+        rows = (tile_count + columns - 1) // columns
+
+        if tile_count <= 0:
+            raise ValueError("Tileset does not contain any tiles")
+
+        tilesets[firstgid] = {
+            "image": tilesheet,
+            "image_name": image_name,
+            "tile_width": tile_width,
+            "tile_height": tile_height,
+            "columns": columns,
+            "rows": rows,
+            "tile_count": tile_count,
+            # Keep these aliases so older student code that checks sheet_w or
+            # sheet_h does not immediately break.
+            "sheet_w": columns,
+            "sheet_h": rows,
+            "spacing": spacing,
+            "margin": margin,
+        }
+
+    return tilesets
+
+
+def load_tile_map_actors(tmx_name, scale=1):
+    """
+    Load a Tiled TMX map into a dict of:
+        {layer_name: [Actor, Actor, ...]}
+
+    The TMX/TSX/image files are loaded through pgzero loaders from the maps folder.
+    """
+    root = _load_xml_from_maps(tmx_name)
+
+    map_tile_width = int(root.attrib["tilewidth"])
+    map_tile_height = int(root.attrib["tileheight"])
+
+    tilesets = _load_tilesets(root, tmx_name)
+
+    layers_dict = {}
+
+    for layer in root.findall("layer"):
+        name = layer.attrib["name"]
+        width = int(layer.attrib["width"])
+        height = int(layer.attrib["height"])
+        data = layer.find("data")
+
+        if data is None or data.text is None:
+            layers_dict[name] = []
+            continue
+
+        encoding = data.attrib.get("encoding")
+        if encoding != "csv":
+            raise ValueError(f"Layer '{name}' must use CSV encoding. Found: {encoding!r}")
+
+        gids = [int(v) for v in data.text.split(",") if v.strip()]
+
+        items = []
+
+        for row in range(height):
+            for col in range(width):
+                tile_gid = gids[row * width + col]
+                if tile_gid == 0:
+                    continue
+
+                flipped_h = bool(tile_gid & FLIP_H)
+                flipped_v = bool(tile_gid & FLIP_V)
+                flipped_d = bool(tile_gid & FLIP_D)
+                tile_gid &= GID_MASK
+
+                ts_firstgid = max(gid for gid in tilesets if gid <= tile_gid)
+                tileset = tilesets[ts_firstgid]
+                local_id = tile_gid - ts_firstgid
+
+                if local_id >= tileset["tile_count"]:
+                    raise ValueError(
+                        f"Tile gid {tile_gid} points past the end of tileset " f"starting at firstgid {ts_firstgid}."
+                    )
+
+                tile_col = local_id % tileset["columns"]
+                tile_row = local_id // tileset["columns"]
+
+                tile = Tile(
+                    tileset=tileset,
+                    tileset_firstgid=ts_firstgid,
+                    tile_col=tile_col,
+                    tile_row=tile_row,
+                    map_col=col,
+                    map_row=row,
+                    map_tile_width=map_tile_width,
+                    map_tile_height=map_tile_height,
+                    scale=scale,
+                    flip_h=flipped_h,
+                    flip_v=flipped_v,
+                    flip_d=flipped_d,
+                )
+                items.append(tile)
+
+        layers_dict[name] = items
+
+    return layers_dict

pgzero/tone.py

@@ -0,0 +1,132 @@
+"""Tone generator for Pygame Zero.
+
+This tone generator is a wrapper for pyfxr, a custom Cython library for sound
+generation. Tones are kept in a LRU cache which in typical applications
+will reduce the number of times they need to be regenerated.
+
+To minimise the extent that pauses affect gameplay, the ``play()`` function
+offloads tone generation to a separate thread. Because tones are generated
+with numpy operations this should allow at least part of this work to happen
+on another CPU core, if present.
+
+"""
+from functools import lru_cache
+from collections import namedtuple
+from threading import Thread, Lock
+from queue import Queue
+from enum import Enum
+
+import pygame
+import pyfxr
+
+
+__all__ = (
+    'play',
+    'create',
+)
+
+
+# Longest note to allow
+MAX_DURATION = 4
+
+
+class Waveform(Enum):
+    SIN = pyfxr.Wavetable.sine()
+    SQUARE = pyfxr.Wavetable.square()
+    SAW = pyfxr.Wavetable.saw()
+    TRIANGLE = pyfxr.Wavetable.triangle()
+
+
+ToneParams = namedtuple('ToneParams', 'hz duration waveform volume')
+
+
+# lru_cache isn't threadsafe until Python 3.7, so protect it ourselves
+# https://bugs.python.org/issue28969
+cache_lock = Lock()
+note_queue = Queue()
+player_thread = None
+
+
+def _play_thread():
+    """Play any notes requested by the game thread.
+
+    Multithreading is useful because numpy releases the GIL while performing
+    many C operations.
+
+    """
+    while True:
+        params = note_queue.get()
+        with cache_lock:
+            note = _create(params)
+        note.play()
+
+
+def create(*args, **kwargs):
+    """Create a tone of a given duration at the given pitch.
+
+    Return a Sound which can be played later.
+
+    """
+    params = _convert_args(*args, **kwargs)
+    with cache_lock:
+        return _create(params)
+
+
+@lru_cache()
+def _create(params):
+    """Actually create a tone."""
+    # Construct a mono tone of the right length
+    tone = pyfxr.tone(
+        pitch=params.hz,
+        sustain=max(0, params.duration - 0.2),
+        wavetable=params.waveform.value,
+    )
+
+    # NB. pygame assumes that the sound format of any buffer object matches
+    # that of the current mixer settings. We use mixer.pre_init(22050, -16, 2)
+    # which means that it is expecting 22kHz audio stereo, but we're feeding it
+    # 44kHz mono - but, perhaps surprisingly, that works Ok. The extra samples
+    # get interpreted as the second channel.
+    #
+    # If we change the mixer to 44kHz we'd need to convert to stereo here by
+    # doubling samples.
+    #
+    # Really this is a mess and Pygame should support converting the format
+    # of buffers (as it does for .wav files).
+    snd = pygame.mixer.Sound(buffer=tone)
+    snd.set_volume(params.volume)
+    return snd
+
+
+def _convert_args(pitch, duration, *, waveform=Waveform.SIN, volume=0.8):
+    """Convert the given arguments to _create parameters."""
+    if duration > MAX_DURATION:
+        raise ValueError(
+            'Note duration %ss is too long: notes may be at most %ss long' %
+            (duration, MAX_DURATION)
+        )
+    if not duration:
+        raise ValueError("Note has zero duration")
+    if isinstance(pitch, str):
+        pitch = pyfxr.note_to_hertz(pitch)
+    return ToneParams(pitch, duration, Waveform(waveform), volume)
+
+
+def play(*args, **kwargs):
+    """Plays a tone of a certain length from a note or frequency in hertz.
+
+    Tones have a maximum duration of 4 seconds. This limitation is imposed to
+    avoid accidentally creating sounds that take too long to generate and
+    require a lot of memory.
+
+    To work around this, create the sounds you want to use up-front with
+    create() and hold onto them, perhaps in an array.
+
+    """
+    global player_thread
+    params = _convert_args(*args, **kwargs)
+    if not player_thread or not player_thread.is_alive():
+        pygame.mixer.init()
+        player_thread = Thread(target=_play_thread, daemon=True)
+        player_thread.start()
+    note_queue.put(params)

pgzero_plus-0.1.0.dist-info/METADATA

@@ -0,0 +1,259 @@
+Metadata-Version: 2.4
+Name: pgzero-plus
+Version: 0.1.0
+Summary: An enhanced fork of Pygame Zero with additional features for teaching and developing 2D games
+Author-email: Michael D'Argenio <mjdargen@gmail.com>
+License-Expression: LGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/mjdargen/pgzero
+Project-URL: Documentation, https://pygame-zero.readthedocs.io/
+Project-URL: Source, https://github.com/mjdargen/pgzero
+Project-URL: Issues, https://github.com/mjdargen/pgzero/issues
+Keywords: pygame,pgzero,games,education
+Classifier: Intended Audience :: Education
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Education
+Classifier: Topic :: Games/Entertainment
+Requires-Python: <3.14,>=3.6
+Description-Content-Type: text/markdown
+License-File: COPYING
+Requires-Dist: pygame>=2.6.1
+Requires-Dist: numpy
+Requires-Dist: pyfxr>=0.3.0
+Requires-Dist: importlib-metadata==4.8.3; python_version < "3.8"
+Dynamic: license-file
+
+# Pygame Zero Plus
+
+**Pygame Zero Plus** (`pgzero-plus`) is an independent fork of [Pygame Zero](https://github.com/lordmauve/pgzero), a beginner-friendly Python game development framework that reduces boilerplate code.
+
+This fork adds features and quality-of-life improvements for introductory computer science and game design courses while retaining the familiar Pygame Zero API, including `Actor`, `screen`, and `pgzrun`.
+
+## What's New
+
+- **Enhanced Actors:** Scaling, flipping, opacity, and customizable collision rectangles.
+- **Sprite Animations:** `Sprite` and `SpriteActor` classes for animated sprite sheets.
+- **Tilemaps:** Loading and rendering maps created with [Tiled Map Editor](https://www.mapeditor.org/), including tilesets and tile transformations.
+- **Game Management:** A `Game` object for tracking scores, levels, game states, and restarting games.
+
+## Installation
+
+The PyPI distribution is named `pgzero-plus`, but it provides the same `pgzero` Python package and `pgzrun` command as the original Pygame Zero. **Do not install both distributions in the same Python environment.**
+
+### Install or Update
+
+Once published on PyPI:
+
+**Windows:**
+
+```bash
+python -m pip install --upgrade pgzero-plus
+```
+
+**macOS / Linux:**
+
+```bash
+python3 -m pip install --upgrade pgzero-plus
+```
+
+### Switching from Pygame Zero or an Older Fork
+
+If you previously installed `pgzero` or `pgzero-mjd`, uninstall any overlapping distributions before installing Pygame Zero Plus. This also helps repair environments where multiple forks have been installed together.
+
+**Windows:**
+
+```bash
+python -m pip uninstall -y pgzero pgzero-mjd pgzero-plus
+python -m pip install pgzero-plus
+```
+
+**macOS / Linux:**
+
+```bash
+python3 -m pip uninstall -y pgzero pgzero-mjd pgzero-plus
+python3 -m pip install pgzero-plus
+```
+
+`--force-reinstall` does **not** remove a differently named distribution, so it is not a substitute for uninstalling the original `pgzero` package.
+
+### Running Games
+
+Pygame Zero Plus supports running games as regular Python scripts, including with the Run button in VS Code.
+
+Start your program with:
+
+```python
+import pgzrun
+from pgzero.builtins import *
+```
+
+The explicit `pgzero.builtins` import helps editors such as VS Code (Pylance) recognize names like `Actor` and `screen`.
+
+Define your variables and functions, such as `start()`, `draw()`, and `update()`, then end the program with:
+
+```python
+pgzrun.go()
+```
+
+Run the script through your editor or with:
+
+```bash
+python game.py
+```
+
+Alternatively, use the traditional Pygame Zero command:
+
+```bash
+pgzrun game.py
+```
+
+## Development
+
+Clone the repository:
+
+```bash
+git clone https://github.com/mjdargen/pgzero.git
+cd pgzero
+```
+
+Install the fork in editable mode **and** install all development tools with one command:
+
+```bash
+python -m pip install -r requirements-dev.txt
+```
+
+`requirements-dev.txt` includes `-e .`, which installs the local package and its runtime dependencies. Source changes are available immediately without rebuilding the wheel. If the original `pgzero` is installed in this environment, uninstall it first as described above.
+
+### Pre-commit Checks
+
+[Pre-commit](https://pre-commit.com/) checks whitespace, file endings, YAML/TOML syntax, merge conflict markers, and accidentally added large files.
+
+Activate it **once per clone**, after installing the development dependencies:
+
+```bash
+python -m pre_commit install
+```
+
+It then runs automatically on staged files before each `git commit`. If a hook modifies a file, review it with `git diff`, stage the fix with `git add`, and retry the commit.
+
+To check all tracked files manually at any time:
+
+```bash
+python -m pre_commit run --all-files
+```
+
+Using `python -m pre_commit` avoids Windows PATH issues where the `pre-commit` command is not recognized.
+
+### Testing
+
+Run all tests from the repository root:
+
+```bash
+python -m pytest
+```
+
+For detailed output or one test file:
+
+```bash
+python -m pytest -v
+python -m pytest test/test_actor.py
+```
+
+### Documentation
+
+Documentation is written in [Sphinx](https://www.sphinx-doc.org/) using the `.rst` files in `doc/`. Update these pages when features or behavior change, and add new pages to `doc/index.rst` so they appear in the navigation.
+
+Build and preview locally from the repository root:
+
+```bash
+python -m sphinx -b html doc doc/_build/html
+```
+
+On Windows (PowerShell), open the generated documentation with:
+
+```powershell
+start doc/_build/html/index.html
+```
+
+On macOS or Linux, open that HTML file in your browser. The Sphinx configuration lives in `doc/conf.py`.
+
+Once this repository is connected to [Read the Docs](https://readthedocs.org/), its `.readthedocs.yaml` configuration allows the hosted documentation to rebuild automatically after changes are pushed. GitHub Actions verifies that the documentation builds; Read the Docs hosts and publishes the website.
+
+### Automated Checks on GitHub
+
+The [Code Checks workflow](https://github.com/mjdargen/pgzero/actions) (`.github/workflows/checks.yml`) runs automatically on pushes to `main` and on pull requests. It runs pre-commit, pytest, Sphinx, the package build, and distribution validation.
+
+These checks run **after** a push, so a failing check does not undo the push. Check the Actions page for results and fix any failures before publishing a release.
+
+## Building and Verification
+
+The automated release workflow builds distributions for publishing, so **manual builds are optional** during everyday development. To check a release locally, run:
+
+```bash
+python -m pre_commit run --all-files
+python -m pytest
+python -m sphinx -b html doc doc/_build/html
+python -m build
+python -m twine check --strict dist/*
+```
+
+The wheel (`.whl`) and source archive (`.tar.gz`) are written to `dist/`. Clear out older distributions from `dist/` before building a new version so you do not accidentally inspect or upload old files.
+
+### Verify the Built Wheel
+
+Install the built wheel in a **fresh virtual environment** to check the distribution itself instead of your editable development installation. The example filename below is for version `0.1.0`; update it when the version changes.
+
+**Windows (PowerShell):**
+
+```powershell
+python -m venv .venv-wheel-check
+.\.venv-wheel-check\Scripts\python.exe -m pip install dist/pgzero_plus-0.1.0-py3-none-any.whl
+.\.venv-wheel-check\Scripts\python.exe -m pip check
+.\.venv-wheel-check\Scripts\python.exe -c "import pgzero, pgzrun; print(pgzero.__file__)"
+```
+
+**macOS / Linux:**
+
+```bash
+python3 -m venv .venv-wheel-check
+.venv-wheel-check/bin/python -m pip install dist/pgzero_plus-0.1.0-py3-none-any.whl
+.venv-wheel-check/bin/python -m pip check
+.venv-wheel-check/bin/python -c "import pgzero, pgzrun; print(pgzero.__file__)"
+```
+
+**Python 3.6 compatibility:** This fork targets Python 3.6 through 3.13, including older Codio environments. The modern build backend does not support building from source on Python 3.6. Before a release, install the **built wheel** in Codio and run a representative game there; passing tests on Python 3.13 does not establish compatibility with Python 3.6.
+
+## Publishing Releases
+
+GitHub Actions handles publishing through `.github/workflows/release.yml`. A new package is **not** published on every push to `main`; publishing starts only when you push a version tag.
+
+### One-time PyPI Setup
+
+1. Create a GitHub repository environment named `pypi` under **Settings → Environments**.
+2. Configure [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishers/) for project `pgzero-plus`, GitHub owner `mjdargen`, repository `pgzero`, workflow `release.yml`, and environment `pypi`. For a first release, use a _pending trusted publisher_ if the project has not yet been created on PyPI.
+
+This allows GitHub Actions to publish without storing a PyPI API token.
+
+### Create a Release
+
+1. Set the new `version` in `pyproject.toml`. For example, `version = "0.1.0"`.
+2. Commit and push your changes to `main`, then confirm that **Code Checks** passes on the [Actions page](https://github.com/mjdargen/pgzero/actions).
+3. Create and push a Git tag **matching** that version, with a leading `v`:
+
+```bash
+git switch main
+git pull
+git tag -a v0.1.0 -m "Release v0.1.0"
+git push origin v0.1.0
+```
+
+The release workflow verifies the version, runs the checks, builds the wheel and source archive, publishes to PyPI, and creates a GitHub Release with the built files attached. If a check or build fails, publishing stops.
+
+For a later release, update the version number and use its matching tag (for example, `0.1.1` and `v0.1.1`). Use patch releases for bug fixes and minor releases for new features. **PyPI does not allow replacing files for an existing published version.**
+
+## Credits & License
+
+This project is an independent fork of [Pygame Zero](https://github.com/lordmauve/pgzero), originally developed by Daniel Pope and contributors.
+
+Original documentation: https://pygame-zero.readthedocs.io/
+
+Licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later).