alchemy-game 0.1.0__tar.gz

alchemy_game-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Davidson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alchemy_game-0.1.0/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: alchemy-game
+Version: 0.1.0
+Summary: An alchemical match-four puzzle game built with Pygame
+Keywords: game,puzzle,match-four,pygame,alchemy
+Author: Andrew Davidson
+Author-email: Andrew Davidson <drace.davidson@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Puzzle Games
+Requires-Dist: pygame>=2.6.1,<3
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/wulfalpha/alchemy
+Project-URL: Repository, https://github.com/wulfalpha/alchemy
+Project-URL: Issues, https://github.com/wulfalpha/alchemy/issues
+Description-Content-Type: text/markdown
+
+# Alchemy
+
+A Pygame match-four puzzle with independently drawn alchemical symbols and a quiet laboratory aesthetic.
+
+## Install
+
+With Python 3.12+:
+
+```sh
+pip install alchemy-game
+```
+
+Or as a standalone tool (no project venv needed):
+
+```sh
+pipx install alchemy-game
+# or: uv tool install alchemy-game
+```
+
+Then run:
+
+```sh
+alchemy
+```
+
+## Play
+
+From a clone of this repository, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv run alchemy
+```
+
+Or install into your Python environment with `python -m pip install -e .`, then run `alchemy`.
+
+- Click a symbol, then an adjacent symbol to swap them.
+- Match **four or more** identical symbols horizontally or vertically. Diagonals and groups without a four-symbol line do not clear.
+- Valid swaps use one of your 30 moves. Invalid swaps are reversed for free.
+- Cleared tiles refill from above; further matches produce cascades.
+- Each cleared symbol earns 25 points, with another 25 for each symbol beyond four. The total is multiplied by the cascade number. Intersections count each tile once. A true plus adds **200 points per crossing**, before the cascade multiplier: both horizontal and vertical runs must be 4+ symbols and extend on both sides of the crossing. T and L shapes do not earn this bonus.
+- **H** or **Hint** highlights a valid swap, without a penalty.
+- **R** or **New game** restarts. **Esc** quits.
+- Boards with no valid swaps are replaced automatically for free; the score and remaining moves carry over.
+
+## Sounds
+
+Optional sound hooks are ready. Drop WAV or OGG effects into `sounds/` using the filenames in [sounds/README.md](https://github.com/wulfalpha/alchemy/blob/main/sounds/README.md), then restart. Press **M** to mute; use `--volume 0.4` to adjust volume. Missing audio files or devices do not prevent play.
+
+## Artwork
+
+`img/AoA_symbols.pdf` is a visual reference supplied with the project. The game does not extract or display artwork from that PDF.
+
+The five transparent PNGs in `img/` are fresh geometric drawings of traditional fire, water, air, earth, and sun symbols. Replace `fire.png`, `water.png`, `air.png`, `earth.png`, or `sun.png` to customize the game. Square transparent images work best; they display at 48 × 48 pixels.
+
+`python tools/draw_symbols.py` regenerates the default images in both `img/` and `src/alchemy/assets/`. The latter provides packaged fallback assets for installed builds. Copy custom images there as well before building a distribution.
+
+This is an independent prototype. No affiliation with an earlier game is implied; naming and distribution rights have not been legally reviewed.
+
+## Development
+
+Rules live in `src/alchemy/board.py`; rendering and input live in `src/alchemy/app.py`.
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy PYTHONPATH=src python -m alchemy --smoke-test --seed 42 --screenshot /tmp/alchemy.png
+```
+
+The full suite, including the edge-case tests in `tests/edge/`, needs pytest:
+
+```sh
+SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy uv run --with pytest pytest -q
+```
+
+Use `alchemy --seed 42` for a reproducible game. This first version has session scoring; persistent high scores, bundled sound clips, and additional modes are not implemented yet.
+
+## License
+
+Released under the [MIT License](https://github.com/wulfalpha/alchemy/blob/main/LICENSE). Copyright (c) 2026 Andrew Davidson.

alchemy_game-0.1.0/README.md

@@ -0,0 +1,78 @@
+# Alchemy
+
+A Pygame match-four puzzle with independently drawn alchemical symbols and a quiet laboratory aesthetic.
+
+## Install
+
+With Python 3.12+:
+
+```sh
+pip install alchemy-game
+```
+
+Or as a standalone tool (no project venv needed):
+
+```sh
+pipx install alchemy-game
+# or: uv tool install alchemy-game
+```
+
+Then run:
+
+```sh
+alchemy
+```
+
+## Play
+
+From a clone of this repository, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv run alchemy
+```
+
+Or install into your Python environment with `python -m pip install -e .`, then run `alchemy`.
+
+- Click a symbol, then an adjacent symbol to swap them.
+- Match **four or more** identical symbols horizontally or vertically. Diagonals and groups without a four-symbol line do not clear.
+- Valid swaps use one of your 30 moves. Invalid swaps are reversed for free.
+- Cleared tiles refill from above; further matches produce cascades.
+- Each cleared symbol earns 25 points, with another 25 for each symbol beyond four. The total is multiplied by the cascade number. Intersections count each tile once. A true plus adds **200 points per crossing**, before the cascade multiplier: both horizontal and vertical runs must be 4+ symbols and extend on both sides of the crossing. T and L shapes do not earn this bonus.
+- **H** or **Hint** highlights a valid swap, without a penalty.
+- **R** or **New game** restarts. **Esc** quits.
+- Boards with no valid swaps are replaced automatically for free; the score and remaining moves carry over.
+
+## Sounds
+
+Optional sound hooks are ready. Drop WAV or OGG effects into `sounds/` using the filenames in [sounds/README.md](https://github.com/wulfalpha/alchemy/blob/main/sounds/README.md), then restart. Press **M** to mute; use `--volume 0.4` to adjust volume. Missing audio files or devices do not prevent play.
+
+## Artwork
+
+`img/AoA_symbols.pdf` is a visual reference supplied with the project. The game does not extract or display artwork from that PDF.
+
+The five transparent PNGs in `img/` are fresh geometric drawings of traditional fire, water, air, earth, and sun symbols. Replace `fire.png`, `water.png`, `air.png`, `earth.png`, or `sun.png` to customize the game. Square transparent images work best; they display at 48 × 48 pixels.
+
+`python tools/draw_symbols.py` regenerates the default images in both `img/` and `src/alchemy/assets/`. The latter provides packaged fallback assets for installed builds. Copy custom images there as well before building a distribution.
+
+This is an independent prototype. No affiliation with an earlier game is implied; naming and distribution rights have not been legally reviewed.
+
+## Development
+
+Rules live in `src/alchemy/board.py`; rendering and input live in `src/alchemy/app.py`.
+
+```sh
+PYTHONPATH=src python -m unittest discover -s tests -v
+SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy PYTHONPATH=src python -m alchemy --smoke-test --seed 42 --screenshot /tmp/alchemy.png
+```
+
+The full suite, including the edge-case tests in `tests/edge/`, needs pytest:
+
+```sh
+SDL_VIDEODRIVER=dummy SDL_AUDIODRIVER=dummy uv run --with pytest pytest -q
+```
+
+Use `alchemy --seed 42` for a reproducible game. This first version has session scoring; persistent high scores, bundled sound clips, and additional modes are not implemented yet.
+
+## License
+
+Released under the [MIT License](https://github.com/wulfalpha/alchemy/blob/main/LICENSE). Copyright (c) 2026 Andrew Davidson.

alchemy_game-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "alchemy-game"
+version = "0.1.0"
+description = "An alchemical match-four puzzle game built with Pygame"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["pygame>=2.6.1,<3"]
+keywords = [
+    "game",
+    "puzzle",
+    "match-four",
+    "pygame",
+    "alchemy",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Environment :: Win32 (MS Windows)",
+    "Environment :: X11 Applications",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment :: Puzzle Games",
+]
+
+[[project.authors]]
+name = "Andrew Davidson"
+email = "drace.davidson@gmail.com"
+
+[project.urls]
+Homepage = "https://github.com/wulfalpha/alchemy"
+Repository = "https://github.com/wulfalpha/alchemy"
+Issues = "https://github.com/wulfalpha/alchemy/issues"
+
+[project.scripts]
+alchemy = "alchemy:main"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "alchemy"

alchemy_game-0.1.0/pyproject.toml.orig

@@ -0,0 +1,41 @@
+[project]
+name = "alchemy-game"
+version = "0.1.0"
+description = "An alchemical match-four puzzle game built with Pygame"
+readme = "README.md"
+authors = [
+    { name = "Andrew Davidson", email = "drace.davidson@gmail.com" }
+]
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.12"
+dependencies = ["pygame>=2.6.1,<3"]
+keywords = ["game", "puzzle", "match-four", "pygame", "alchemy"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: MacOS X",
+    "Environment :: Win32 (MS Windows)",
+    "Environment :: X11 Applications",
+    "Intended Audience :: End Users/Desktop",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment :: Puzzle Games",
+]
+
+[project.urls]
+Homepage = "https://github.com/wulfalpha/alchemy"
+Repository = "https://github.com/wulfalpha/alchemy"
+Issues = "https://github.com/wulfalpha/alchemy/issues"
+
+[project.scripts]
+alchemy = "alchemy:main"
+
+[build-system]
+requires = ["uv_build>=0.12.23,<0.13.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = "alchemy"

alchemy_game-0.1.0/src/alchemy/__init__.py

@@ -0,0 +1,3 @@
+def main() -> None:
+    from .app import main as run
+    run()

alchemy_game-0.1.0/src/alchemy/__main__.py

@@ -0,0 +1,3 @@
+from . import main
+
+main()

alchemy_game-0.1.0/src/alchemy/app.py

@@ -0,0 +1,157 @@
+"""Pygame presentation and input."""
+import argparse
+import os
+from pathlib import Path
+
+os.environ.setdefault('PYGAME_HIDE_SUPPORT_PROMPT', '1')
+import pygame
+from .board import Game, legal_moves
+from .audio import Audio
+
+WIDTH, HEIGHT = 1040, 780
+LEFT, TOP, TILE = 48, 154, 70
+BG = (15, 24, 30)
+TEXT = (241, 229, 203)
+MUTED = (156, 173, 174)
+GOLD = (223, 181, 103)
+COLORS = [(107, 54, 45), (38, 80, 103), (73, 89, 77), (85, 68, 104), (110, 88, 42)]
+NAMES = ['fire', 'water', 'air', 'earth', 'sun']
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Alchemy: a match-four puzzle')
+    parser.add_argument('--seed', type=int, help='Reproducible starting board')
+    parser.add_argument('--smoke-test', action='store_true', help='Render a frame and exit')
+    parser.add_argument('--screenshot', type=Path, help='Save the rendered frame as PNG')
+    parser.add_argument('--sound-dir', type=Path, help='Directory of optional WAV/OGG effects')
+    parser.add_argument('--mute', action='store_true', help='Start with sound muted')
+    parser.add_argument('--volume', type=float, default=0.6, help='Effect volume from 0 to 1')
+    args = parser.parse_args()
+    if not 0 <= args.volume <= 1:
+        parser.error('--volume must be between 0 and 1')
+    pygame.init()
+    audio = Audio(args.sound_dir, args.volume, args.mute)
+    screen = pygame.display.set_mode((WIDTH, HEIGHT))
+    pygame.display.set_caption('Alchemy | The Fourfold Art')
+    clock = pygame.time.Clock()
+    fonts = {size: pygame.font.SysFont('dejavusans', size) for size in (14, 16, 19, 24, 38, 48)}
+    root = Path(__file__).resolve().parents[2] / 'img'
+    if not root.is_dir():
+        root = Path(__file__).resolve().parent / 'assets'
+    symbols = []
+    for name in NAMES:
+        custom = root / f'{name}.png'
+        fallback = Path(__file__).resolve().parent / 'assets' / f'{name}.png'
+        symbols.append(pygame.transform.smoothscale(pygame.image.load(str(custom if custom.exists() else fallback)).convert_alpha(), (48, 48)))
+    game = Game(args.seed)
+    selected = None
+    hint = None
+    next_resolve = 0
+    running = True
+    hint_button = pygame.Rect(662, 590, 142, 46)
+    restart_button = pygame.Rect(818, 590, 164, 46)
+
+    def text(value, pos, size=19, color=TEXT):
+        screen.blit(fonts[size].render(str(value), True, color), pos)
+
+    while running:
+        now = pygame.time.get_ticks()
+        for event in pygame.event.get():
+            if event.type == pygame.QUIT:
+                running = False
+            elif event.type == pygame.KEYDOWN:
+                if event.key == pygame.K_ESCAPE:
+                    running = False
+                elif event.key == pygame.K_m:
+                    audio.toggle()
+                elif event.key == pygame.K_r:
+                    audio.play("restart")
+                    game = Game(args.seed)
+                    selected = hint = None
+                elif event.key == pygame.K_h and not game.pending and game.moves:
+                    hint = legal_moves(game.grid)[0]
+                    audio.play("hint")
+            elif event.type == pygame.MOUSEBUTTONDOWN and event.button == 1:
+                if restart_button.collidepoint(event.pos):
+                    audio.play("restart")
+                    game = Game(args.seed)
+                    selected = hint = None
+                elif hint_button.collidepoint(event.pos) and not game.pending and game.moves:
+                    hint = legal_moves(game.grid)[0]
+                    audio.play("hint")
+                elif not game.pending and game.moves:
+                    x = (event.pos[0] - LEFT) // TILE
+                    y = (event.pos[1] - TOP) // TILE
+                    if 0 <= x < 8 and 0 <= y < 8:
+                        cell = (x, y)
+                        hint = None
+                        if selected == cell:
+                            selected = None
+                        elif selected is not None and abs(selected[0]-x) + abs(selected[1]-y) == 1:
+                            if game.attempt(selected, cell):
+                                audio.play("swap")
+                                next_resolve = now + 350
+                            else:
+                                audio.play("invalid")
+                            selected = None
+                        else:
+                            selected = cell
+                            audio.play("select")
+        if game.pending and now >= next_resolve:
+            for sound_event in game.resolve():
+                audio.play(sound_event)
+            next_resolve = now + 350
+
+        screen.fill(BG)
+        pygame.draw.circle(screen, (21, 34, 40), (975, 60), 260, 1)
+        pygame.draw.circle(screen, (21, 34, 40), (975, 60), 220, 1)
+        text('A L C H E M Y', (48, 28), 38)
+        text('T H E   F O U R F O L D   A R T', (50, 85), 14, GOLD)
+        text('A little patience. A little transformation.', (662, 67), 16, MUTED)
+        pygame.draw.line(screen, (57, 68, 68), (48, 125), (982, 125))
+        for y, row in enumerate(game.grid):
+            for x, value in enumerate(row):
+                rect = pygame.Rect(LEFT+x*TILE+3, TOP+y*TILE+3, TILE-6, TILE-6)
+                pygame.draw.rect(screen, COLORS[value], rect, border_radius=10)
+                pygame.draw.rect(screen, (255, 226, 154) if (x,y) in game.pending else (104, 107, 99), rect, 1, border_radius=10)
+                screen.blit(symbols[value], symbols[value].get_rect(center=rect.center))
+                if selected == (x, y) or (hint and (x, y) in hint):
+                    pygame.draw.rect(screen, GOLD, rect.inflate(4, 4), 3, border_radius=12)
+                if (x,y) in game.pending:
+                    overlay = pygame.Surface(rect.size, pygame.SRCALPHA)
+                    overlay.fill((255, 234, 173, 95))
+                    screen.blit(overlay, rect)
+
+        text('YOUR EXPERIMENT', (662, 158), 14, GOLD)
+        text(f'{game.score:,}', (658, 183), 48)
+        text('POINTS', (664, 244), 14, MUTED)
+        text(f'{game.moves:02d}', (855, 183), 48)
+        text('MOVES LEFT', (857, 244), 14, MUTED)
+        pygame.draw.line(screen, (57, 68, 68), (662, 282), (982, 282))
+        text('The practice', (662, 305), 24)
+        for i, line in enumerate(('Swap two neighboring symbols.', 'Align 4 or more in a row or column.', 'Cleared symbols make room for new ones.', 'Chain reactions multiply your points.', 'Cross two 4+ lines: +200 per plus.')):
+            text(line, (662, 350+i*28), 14, MUTED)
+        for i, symbol in enumerate(symbols):
+            screen.blit(symbol, (663+i*65, 508))
+        for button, label in ((hint_button, 'Hint  [H]'), (restart_button, 'New game  [R]')):
+            pygame.draw.rect(screen, (35, 49, 55), button, border_radius=8)
+            pygame.draw.rect(screen, (92, 105, 103), button, 1, border_radius=8)
+            screen.blit(fonts[16].render(label, True, TEXT), fonts[16].render(label, True, TEXT).get_rect(center=button.center))
+        text(f'Sound: {"off" if audio.muted else "on"}  [M]   /   ESC to quit', (662, 661), 14, MUTED)
+        text(game.message, (48, 735), 16, GOLD)
+
+        if game.moves == 0 and not game.pending:
+            shade = pygame.Surface((560, 560), pygame.SRCALPHA)
+            shade.fill((9, 17, 24, 225))
+            screen.blit(shade, (LEFT, TOP))
+            text('Experiment complete', (110, 320), 24)
+            text(f'{game.score:,} points', (150, 370), 38, GOLD)
+            text('Press R to begin a new experiment.', (122, 439), 16)
+        pygame.display.flip()
+        if args.screenshot:
+            pygame.image.save(screen, str(args.screenshot))
+            args.screenshot = None
+        if args.smoke_test:
+            running = False
+        clock.tick(60)
+    pygame.quit()

alchemy_game-0.1.0/src/alchemy/audio.py

@@ -0,0 +1,49 @@
+"""Optional drop-in sound effects. Missing files and audio devices are harmless."""
+import logging
+from pathlib import Path
+
+import pygame
+
+EVENTS = ('select', 'swap', 'invalid', 'match', 'cascade', 'plus',
+          'hint', 'shuffle', 'restart', 'game_over')
+
+
+class Audio:
+    def __init__(self, directory=None, volume=0.6, muted=False):
+        self.muted = muted
+        self.sounds = {}
+        if not pygame.mixer.get_init():
+            try:
+                pygame.mixer.init()
+            except pygame.error:
+                return
+        roots = ([Path(directory)] if directory is not None else [
+            Path(__file__).resolve().parents[2] / 'sounds',
+            Path(__file__).resolve().parent / 'assets' / 'sounds',
+        ])
+        for event in EVENTS:
+            for root in roots:
+                for extension in ('.wav', '.ogg'):
+                    path = root / (event + extension)
+                    if not path.is_file():
+                        continue
+                    try:
+                        sound = pygame.mixer.Sound(str(path))
+                        sound.set_volume(max(0.0, min(1.0, volume)))
+                        self.sounds[event] = sound
+                        break
+                    except (pygame.error, OSError) as error:
+                        logging.warning('Cannot load sound %s: %s', path, error)
+                if event in self.sounds:
+                    break
+
+    def play(self, event):
+        if not self.muted and pygame.mixer.get_init():
+            sound = self.sounds.get(event)
+            if sound is not None:
+                sound.play()
+
+    def toggle(self):
+        self.muted = not self.muted
+        if self.muted and pygame.mixer.get_init():
+            pygame.mixer.stop()

alchemy_game-0.1.0/src/alchemy/board.py

@@ -0,0 +1,136 @@
+"""Match-four rules, independent of the display."""
+from random import Random
+
+SIZE = 8
+KINDS = 5
+PLUS_BONUS = 200
+
+
+def matches(grid):
+    found = set()
+    for y in range(SIZE):
+        for x in range(SIZE):
+            value = grid[y][x]
+            if value is None:
+                continue
+            for dx, dy in ((1, 0), (0, 1)):
+                run = []
+                xx, yy = x, y
+                while xx < SIZE and yy < SIZE and grid[yy][xx] == value:
+                    run.append((xx, yy))
+                    xx += dx
+                    yy += dy
+                if len(run) >= 4:
+                    found.update(run)
+    return found
+
+
+def plus_centers(grid):
+    """True pluses: both 4+ runs extend on both sides of their crossing."""
+    centers = set()
+    for y in range(1, SIZE - 1):
+        for x in range(1, SIZE - 1):
+            value = grid[y][x]
+            if value is None:
+                continue
+            lengths = []
+            for dx, dy in ((1, 0), (-1, 0), (0, 1), (0, -1)):
+                length = 0
+                xx, yy = x + dx, y + dy
+                while 0 <= xx < SIZE and 0 <= yy < SIZE and grid[yy][xx] == value:
+                    length += 1
+                    xx, yy = xx + dx, yy + dy
+                lengths.append(length)
+            right, left, down, up = lengths
+            if min(lengths) > 0 and right + left + 1 >= 4 and down + up + 1 >= 4:
+                centers.add((x, y))
+    return centers
+
+
+def swap(grid, a, b):
+    ax, ay = a
+    bx, by = b
+    grid[ay][ax], grid[by][bx] = grid[by][bx], grid[ay][ax]
+
+
+def legal_moves(grid):
+    result = []
+    for y in range(SIZE):
+        for x in range(SIZE):
+            for b in ((x + 1, y), (x, y + 1)):
+                if b[0] >= SIZE or b[1] >= SIZE:
+                    continue
+                a = (x, y)
+                swap(grid, a, b)
+                if matches(grid):
+                    result.append((a, b))
+                swap(grid, a, b)
+    return result
+
+
+def new_grid(rng):
+    while True:
+        grid = [[rng.randrange(KINDS) for _ in range(SIZE)] for _ in range(SIZE)]
+        if not matches(grid) and legal_moves(grid):
+            return grid
+
+
+def refill(grid, cleared, rng):
+    for x in range(SIZE):
+        remaining = [grid[y][x] for y in range(SIZE) if (x, y) not in cleared]
+        column = [rng.randrange(KINDS) for _ in range(SIZE - len(remaining))] + remaining
+        for y, value in enumerate(column):
+            grid[y][x] = value
+
+
+class Game:
+    def __init__(self, seed=None):
+        self.rng = Random(seed)
+        self.grid = new_grid(self.rng)
+        self.score = 0
+        self.moves = 30
+        self.chain = 0
+        self.pending = set()
+        self.message = 'Select a symbol, then an adjacent symbol.'
+
+    def attempt(self, a, b):
+        if self.pending or self.moves <= 0:
+            return False
+        if any(not (0 <= x < SIZE and 0 <= y < SIZE) for x, y in (a, b)):
+            return False
+        if abs(a[0] - b[0]) + abs(a[1] - b[1]) != 1:
+            return False
+        swap(self.grid, a, b)
+        self.pending = matches(self.grid)
+        if not self.pending:
+            swap(self.grid, a, b)
+            self.message = 'Make a line of at least four. Try another swap.'
+            return False
+        self.moves -= 1
+        self.chain = 0
+        return True
+
+    def resolve(self):
+        if not self.pending:
+            return
+        self.chain += 1
+        count = len(self.pending)
+        pluses = len(plus_centers(self.grid) & self.pending)
+        bonus = pluses * PLUS_BONUS
+        points = (count * 25 + max(0, count - 4) * 25 + bonus) * self.chain
+        events = ["cascade" if self.chain > 1 else "match"]
+        if pluses:
+            events.append("plus")
+        self.score += points
+        self.message = f'{count} symbols transmuted!  +{points}  /  Cascade x{self.chain}'
+        if pluses:
+            self.message += f'  /  Plus bonus +{bonus * self.chain}'
+        refill(self.grid, self.pending, self.rng)
+        self.pending = matches(self.grid)
+        if not self.pending and self.moves and not legal_moves(self.grid):
+            self.grid = new_grid(self.rng)
+            self.message = 'No swaps left: a fresh board has been brewed.'
+            events.append("shuffle")
+        if not self.pending and not self.moves:
+            events.append("game_over")
+        return events