wack-a-wombat 1.0.0__tar.gz

wack_a_wombat-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The wack-a-wombat authors
+
+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.

wack_a_wombat-1.0.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: wack-a-wombat
+Version: 1.0.0
+Summary: A terminal whack-a-mole starring wombats. WASD to move, SPACE to whack.
+License-Expression: MIT
+Keywords: game,tui,curses,terminal,wombat,whack-a-mole,arcade
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Games/Entertainment :: Arcade
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: windows-curses; sys_platform == "win32"
+Dynamic: license-file
+
+# Wack-a-Wombat
+
+A terminal whack-a-mole with 100% more wombat. Pure Python 3.9+, no
+dependencies (just the standard library's `curses`; on Windows it pulls in
+`windows-curses`).
+
+Play it right now, nothing to install:
+
+```
+uvx wack-a-wombat
+```
+
+or install the `wack-a-wombat` command:
+
+```
+pipx install wack-a-wombat      # or: pip install --user wack-a-wombat
+```
+
+From a checkout: `python3 -m wack_a_wombat`.
+
+## How to play
+
+Wombats pop out of their burrows. Move the mallet onto one and whack it before it
+ducks back down. One round on the clock; score as much as you can.
+
+| Key                         | Action                         |
+| --------------------------- | ------------------------------ |
+| `W A S D` / arrows / `HJKL` | move the mallet                |
+| `SPACE` / `ENTER`           | whack                          |
+| `P` / `ESC`                 | pause (resume, end round, menu)|
+| `M`                         | toggle the terminal bell       |
+| `?`                         | how to play (title screen)     |
+
+### Critters
+
+| Sprite       | What to do                     | Points                          |
+| ------------ | ------------------------------ | ------------------------------- |
+| Wombat       | whack it                       | 10 x multiplier (+ speed bonus) |
+| Golden wombat| whack it, fast - it's brief    | 50 x multiplier (+ speed bonus) |
+| Sleeping     | **leave it alone**             | -25 and your streak is gone     |
+
+- **Streak**: every 5 consecutive hits raise your multiplier, up to x4. A whiff, a
+  bonked sleeper or an escaped wombat resets it.
+- **Speed bonus**: up to +10 for hitting a wombat the instant it appears.
+- **Danger**: the final 5 seconds - wombats stay up for less time and come faster.
+
+### Modes
+
+| Mode     | Grid | Round | Feel                                 |
+| -------- | ---- | ----- | ------------------------------------ |
+| Backyard | 3x3  | 30s   | one wombat at a time, gentle ramp    |
+| Outback  | 4x4  | 45s   | up to two at once, more sleepers     |
+| Frenzy   | 4x4  | 30s   | up to three at once, very short gaps |
+
+Each mode has its own top-10 leaderboard with name, score, hits, accuracy, best
+streak, fastest whack and date.
+
+### Wombat skins
+
+Three hand-drawn wombats, all with the signature big flat nose, small round ears
+and loaf-shaped body. Switch with `WOMBAT < >` on the title screen or `--skin`.
+
+| Skin       | Style                                             |
+| ---------- | ------------------------------------------------- |
+| `classic`  | nose-first: a giant filled nose pad on a flat head |
+| `arcade`   | bursting out of a grassy mound, paws on the rim    |
+| `lineart`  | 90s ASCII-forum line art                           |
+
+The art came from a panel of ASCII artists each drawing in a different style,
+scored by judges on wombat-likeness, how readable each state is mid-game, charm
+and the title showpiece; `classic` won and was refined from the judges' notes.
+
+## Command line
+
+```
+wack-a-wombat [--mode backyard|outback|frenzy] [--seed N] [--no-color] [--fps N]
+              [--sound | --no-sound] [--skin NAME] [--data-dir DIR]
+              [--list-modes] [--list-skins] [--reset-scores] [--version]
+```
+
+Settings and high scores are JSON files in `~/.config/wack-a-wombat/` (or
+`$XDG_CONFIG_HOME/wack-a-wombat/`, or `$WACK_A_WOMBAT_HOME`). Writes are atomic;
+a corrupt file is moved aside rather than overwritten.
+
+`--seed N` makes every round reproducible: the first round after launch always
+gets the same wombats, as does the second, and so on, however long you idle on
+the title screen.
+
+Backyard fits a classic 80x24 terminal (the HUD squeezes to two lines below 28
+rows); the 4x4 modes need at least 31 rows, 35 for the full HUD. Anything smaller
+gets a resize prompt and the round pauses until there's room.
+
+## Architecture
+
+```
+wack_a_wombat/
+  cli.py            argparse entry point
+  app.py            curses bootstrap, frame loop, scene stack, shared services
+  engine/           reusable TUI bits - no game knowledge
+    input.py        key -> Action mapping (wasd / arrows / hjkl)
+    palette.py      named attrs; 256 -> 8 colours -> mono degradation
+    canvas.py       clipped, exception-free drawing over a curses window
+    scene.py        Scene + SceneStack with transparent overlays
+    tween.py        clamp/lerp/easing, Timer, Blink, RollingNumber
+    fx.py           score popups, labels, screen shake, confetti
+  game/             pure game logic - no curses, deterministic given a seed
+    config.py       Mode definitions (grid, timing, difficulty curve)
+    critters.py     CritterKind, Phase, Critter
+    director.py     difficulty ramp: up-time, gaps, kind mix, simultaneous cap
+    scoring.py      points, multipliers, speed bonus
+    stats.py        per-round statistics
+    model.py        Round: the state machine, emits events
+  art/              Sprite type, wombat skins, block-letter banners, block font
+  persistence/      atomic JSON store, per-mode leaderboard, settings
+  scenes/           title (+attract demo), game, pause, game over, name entry,
+                    high scores, help; board_view draws and colours the grid,
+                    ui draws the shadowed banners
+tests/              unit tests + headless end-to-end via a fake curses window
+tools/preview.py    render every screen at any terminal size, as text or colour HTML
+```
+
+The `Round` in `game/model.py` is the heart: feed it `update(dt)`, `move()` and
+`whack()`, drain its events, and it never touches the screen. Scenes translate
+events into effects. That split is what makes the game fully testable without a
+terminal - `tests/test_scenes.py` plays whole rounds through the real scenes into
+a fake window.
+
+## Development
+
+```
+python3 -m unittest discover -s tests -v      # everything, incl. a ~10s pty smoke test
+WOMBAT_SKIP_PTY=1 python3 -m unittest discover -s tests
+python3 tools/preview.py 40 100               # eyeball every screen as text
+python3 tools/preview.py --html shots/all.html --skin arcade   # in colour
+python3 -m wack_a_wombat --seed 1             # deterministic wombats
+```

wack_a_wombat-1.0.0/README.md

@@ -0,0 +1,136 @@
+# Wack-a-Wombat
+
+A terminal whack-a-mole with 100% more wombat. Pure Python 3.9+, no
+dependencies (just the standard library's `curses`; on Windows it pulls in
+`windows-curses`).
+
+Play it right now, nothing to install:
+
+```
+uvx wack-a-wombat
+```
+
+or install the `wack-a-wombat` command:
+
+```
+pipx install wack-a-wombat      # or: pip install --user wack-a-wombat
+```
+
+From a checkout: `python3 -m wack_a_wombat`.
+
+## How to play
+
+Wombats pop out of their burrows. Move the mallet onto one and whack it before it
+ducks back down. One round on the clock; score as much as you can.
+
+| Key                         | Action                         |
+| --------------------------- | ------------------------------ |
+| `W A S D` / arrows / `HJKL` | move the mallet                |
+| `SPACE` / `ENTER`           | whack                          |
+| `P` / `ESC`                 | pause (resume, end round, menu)|
+| `M`                         | toggle the terminal bell       |
+| `?`                         | how to play (title screen)     |
+
+### Critters
+
+| Sprite       | What to do                     | Points                          |
+| ------------ | ------------------------------ | ------------------------------- |
+| Wombat       | whack it                       | 10 x multiplier (+ speed bonus) |
+| Golden wombat| whack it, fast - it's brief    | 50 x multiplier (+ speed bonus) |
+| Sleeping     | **leave it alone**             | -25 and your streak is gone     |
+
+- **Streak**: every 5 consecutive hits raise your multiplier, up to x4. A whiff, a
+  bonked sleeper or an escaped wombat resets it.
+- **Speed bonus**: up to +10 for hitting a wombat the instant it appears.
+- **Danger**: the final 5 seconds - wombats stay up for less time and come faster.
+
+### Modes
+
+| Mode     | Grid | Round | Feel                                 |
+| -------- | ---- | ----- | ------------------------------------ |
+| Backyard | 3x3  | 30s   | one wombat at a time, gentle ramp    |
+| Outback  | 4x4  | 45s   | up to two at once, more sleepers     |
+| Frenzy   | 4x4  | 30s   | up to three at once, very short gaps |
+
+Each mode has its own top-10 leaderboard with name, score, hits, accuracy, best
+streak, fastest whack and date.
+
+### Wombat skins
+
+Three hand-drawn wombats, all with the signature big flat nose, small round ears
+and loaf-shaped body. Switch with `WOMBAT < >` on the title screen or `--skin`.
+
+| Skin       | Style                                             |
+| ---------- | ------------------------------------------------- |
+| `classic`  | nose-first: a giant filled nose pad on a flat head |
+| `arcade`   | bursting out of a grassy mound, paws on the rim    |
+| `lineart`  | 90s ASCII-forum line art                           |
+
+The art came from a panel of ASCII artists each drawing in a different style,
+scored by judges on wombat-likeness, how readable each state is mid-game, charm
+and the title showpiece; `classic` won and was refined from the judges' notes.
+
+## Command line
+
+```
+wack-a-wombat [--mode backyard|outback|frenzy] [--seed N] [--no-color] [--fps N]
+              [--sound | --no-sound] [--skin NAME] [--data-dir DIR]
+              [--list-modes] [--list-skins] [--reset-scores] [--version]
+```
+
+Settings and high scores are JSON files in `~/.config/wack-a-wombat/` (or
+`$XDG_CONFIG_HOME/wack-a-wombat/`, or `$WACK_A_WOMBAT_HOME`). Writes are atomic;
+a corrupt file is moved aside rather than overwritten.
+
+`--seed N` makes every round reproducible: the first round after launch always
+gets the same wombats, as does the second, and so on, however long you idle on
+the title screen.
+
+Backyard fits a classic 80x24 terminal (the HUD squeezes to two lines below 28
+rows); the 4x4 modes need at least 31 rows, 35 for the full HUD. Anything smaller
+gets a resize prompt and the round pauses until there's room.
+
+## Architecture
+
+```
+wack_a_wombat/
+  cli.py            argparse entry point
+  app.py            curses bootstrap, frame loop, scene stack, shared services
+  engine/           reusable TUI bits - no game knowledge
+    input.py        key -> Action mapping (wasd / arrows / hjkl)
+    palette.py      named attrs; 256 -> 8 colours -> mono degradation
+    canvas.py       clipped, exception-free drawing over a curses window
+    scene.py        Scene + SceneStack with transparent overlays
+    tween.py        clamp/lerp/easing, Timer, Blink, RollingNumber
+    fx.py           score popups, labels, screen shake, confetti
+  game/             pure game logic - no curses, deterministic given a seed
+    config.py       Mode definitions (grid, timing, difficulty curve)
+    critters.py     CritterKind, Phase, Critter
+    director.py     difficulty ramp: up-time, gaps, kind mix, simultaneous cap
+    scoring.py      points, multipliers, speed bonus
+    stats.py        per-round statistics
+    model.py        Round: the state machine, emits events
+  art/              Sprite type, wombat skins, block-letter banners, block font
+  persistence/      atomic JSON store, per-mode leaderboard, settings
+  scenes/           title (+attract demo), game, pause, game over, name entry,
+                    high scores, help; board_view draws and colours the grid,
+                    ui draws the shadowed banners
+tests/              unit tests + headless end-to-end via a fake curses window
+tools/preview.py    render every screen at any terminal size, as text or colour HTML
+```
+
+The `Round` in `game/model.py` is the heart: feed it `update(dt)`, `move()` and
+`whack()`, drain its events, and it never touches the screen. Scenes translate
+events into effects. That split is what makes the game fully testable without a
+terminal - `tests/test_scenes.py` plays whole rounds through the real scenes into
+a fake window.
+
+## Development
+
+```
+python3 -m unittest discover -s tests -v      # everything, incl. a ~10s pty smoke test
+WOMBAT_SKIP_PTY=1 python3 -m unittest discover -s tests
+python3 tools/preview.py 40 100               # eyeball every screen as text
+python3 tools/preview.py --html shots/all.html --skin arcade   # in colour
+python3 -m wack_a_wombat --seed 1             # deterministic wombats
+```

wack_a_wombat-1.0.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "wack-a-wombat"
+dynamic = ["version"]  # from wack_a_wombat/__init__.py
+description = "A terminal whack-a-mole starring wombats. WASD to move, SPACE to whack."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["game", "tui", "curses", "terminal", "wombat", "whack-a-mole", "arcade"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Environment :: Console :: Curses",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: Games/Entertainment :: Arcade",
+]
+# curses ships with Python everywhere except Windows
+dependencies = ["windows-curses; sys_platform == 'win32'"]
+
+[project.scripts]
+wack-a-wombat = "wack_a_wombat.cli:main"
+
+[tool.setuptools.dynamic]
+version = { attr = "wack_a_wombat.__version__" }
+
+[tool.setuptools.packages.find]
+include = ["wack_a_wombat*"]

wack_a_wombat-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

wack_a_wombat-1.0.0/tests/test_art.py

@@ -0,0 +1,111 @@
+import unittest
+
+from wack_a_wombat.art import banners, blockfont
+from wack_a_wombat.art.skin import CELL_SPRITE_NAMES
+from wack_a_wombat.art.sprite import CELL_H, CELL_W, TITLE_MAX_H, TITLE_MAX_W, Sprite, is_ascii_row
+from wack_a_wombat.art.wombats import DEFAULT_SKIN, SKINS, get_skin, next_skin, skin_keys
+
+
+class SpriteType(unittest.TestCase):
+    def test_make_pads_and_anchors_bottom(self):
+        s = Sprite.make(["ab", "c"], width=4, height=3)
+        self.assertEqual(s.rows, ("    ", "ab  ", "c   "))
+        self.assertEqual((s.h, s.w), (3, 4))
+
+    def test_make_anchor_top(self):
+        s = Sprite.make(["ab"], width=2, height=2, anchor="top")
+        self.assertEqual(s.rows, ("ab", "  "))
+
+    def test_make_rejects_non_ascii_and_overflow(self):
+        with self.assertRaises(ValueError):
+            Sprite.make(["café"])
+        with self.assertRaises(ValueError):
+            Sprite.make(["toolong"], width=3)
+        with self.assertRaises(ValueError):
+            Sprite.make(["a", "b", "c"], height=2)
+        with self.assertRaises(ValueError):
+            Sprite.make(["tab\there"])
+
+    def test_shift_and_hide(self):
+        s = Sprite.make(["ab", "cd", "ef"])
+        self.assertEqual(s.shifted_down(1).rows, ("  ", "ab", "cd"))
+        self.assertEqual(s.shifted_down(0), s)
+        self.assertEqual(s.shifted_down(9).rows, ("  ", "  ", "  "))
+        self.assertEqual(Sprite.make(["zZa"]).hide("zZ").rows, ("  a",))
+        self.assertEqual(Sprite.make(["ab"]).translate(str.upper).rows, ("AB",))
+
+
+class Skins(unittest.TestCase):
+    def test_registry(self):
+        self.assertIn(DEFAULT_SKIN, SKINS)
+        self.assertIs(get_skin("does-not-exist"), SKINS[DEFAULT_SKIN])
+        keys = skin_keys()
+        self.assertEqual(next_skin(keys[-1]), keys[0])
+        self.assertEqual(next_skin("bogus"), keys[1 % len(keys)])
+
+    def test_every_cell_sprite_is_exactly_cell_sized_ascii(self):
+        for skin in SKINS.values():
+            for name in CELL_SPRITE_NAMES:
+                sprite = getattr(skin, name)
+                self.assertEqual(sprite.h, CELL_H, f"{skin.key}.{name}")
+                for row in sprite.rows:
+                    self.assertEqual(len(row), CELL_W, f"{skin.key}.{name}: {row!r}")
+                    self.assertTrue(is_ascii_row(row), f"{skin.key}.{name}: {row!r}")
+            self.assertLessEqual(skin.title.h, TITLE_MAX_H)
+            self.assertLessEqual(skin.title.w, TITLE_MAX_W)
+            self.assertTrue(all(is_ascii_row(r) for r in skin.title.rows))
+
+    def test_states_differ_and_burrow_is_empty_on_top(self):
+        for skin in SKINS.values():
+            self.assertNotEqual(skin.up.rows, skin.sleeping.rows, skin.key)
+            self.assertNotEqual(skin.up.rows, skin.golden.rows, skin.key)
+            self.assertNotEqual(skin.up.rows, skin.bonked.rows, skin.key)
+            self.assertNotEqual(skin.up.rows, skin.peek.rows, skin.key)
+            self.assertNotEqual(skin.up.rows, skin.burrow.rows, skin.key)
+            # a sleeping wombat needs z's, a burrow has nothing above the rim
+            self.assertTrue(any(ch in "zZ" for row in skin.sleeping.rows for ch in row), skin.key)
+            self.assertEqual(skin.burrow.rows[0].strip(), "", skin.key)
+
+    def test_cell_sprites_share_a_rim_with_the_burrow(self):
+        """The bottom row of every wombat state should mostly coincide with the burrow's,
+        so states swap in place without the hole jumping around."""
+        for skin in SKINS.values():
+            rim = skin.burrow.rows[-1]
+            for name in ("peek", "up", "bonked", "sleeping", "golden"):
+                row = getattr(skin, name).rows[-1]
+                shared = sum(1 for a, b in zip(rim, row) if a == b and a != " ")
+                self.assertGreaterEqual(shared, CELL_W // 3, f"{skin.key}.{name} rim: {row!r} vs {rim!r}")
+
+
+class Banners(unittest.TestCase):
+    def test_banners_are_ascii_and_fit_80_columns(self):
+        for name in ("TITLE", "GAME_OVER", "HIGH_SCORES", "PAUSED"):
+            banner = getattr(banners, name)
+            self.assertIsInstance(banner, Sprite)
+            self.assertGreater(banner.h, 0)
+            self.assertLessEqual(banner.w, 78, name)
+            self.assertTrue(all(is_ascii_row(r) for r in banner.rows), name)
+            self.assertTrue(all(len(r) == banner.w for r in banner.rows), name)
+        self.assertLessEqual(banners.PAUSED.w, 44)
+
+
+class BlockFont(unittest.TestCase):
+    def test_all_glyphs_are_five_rows_and_rectangular(self):
+        for ch, rows in blockfont.GLYPHS.items():
+            self.assertEqual(len(rows), blockfont.GLYPH_H, ch)
+            self.assertEqual(len({len(r) for r in rows}), 1, ch)
+            self.assertTrue(all(set(r) <= {"#", " "} for r in rows), ch)
+
+    def test_render_covers_what_the_game_prints(self):
+        for text in ("3", "2", "1", "GO!", "TIME'S UP!", "ROUND OVER", "0123456789"):
+            rows = blockfont.render(text)
+            self.assertEqual(len(rows), blockfont.GLYPH_H)
+            self.assertEqual(len({len(r) for r in rows}), 1)
+            self.assertEqual(len(rows[0]), blockfont.width(text))
+        self.assertEqual(blockfont.width(""), 0)
+        self.assertEqual(blockfont.glyph("~"), blockfont.GLYPHS["?"])
+        self.assertEqual(blockfont.render("a"), blockfont.render("A"))
+
+
+if __name__ == "__main__":
+    unittest.main()