Psychic Cleaners

A clean-room pygame-ce homage to a 1984 Activision C64 classic about running a paranormal-removal franchise: buy a vehicle and gear, watch the city map, drive to hauntings, snare stain-ghosts between two beams, dodge a rampaging gummy mascot, and — when the city's psychic residue maxes out — storm Threshold Tower. Mechanics and pacing follow the original; every name, sprite, sound, and melody is an original work. The full concept-by-concept theme mapping is in docs/superpowers/specs/2026-07-13-psychic-cleaners-design.md (section 3).

Every sprite, sound, and melody shown above is generated in code at startup — no image or audio assets ship in this repo (see shell/gfx.py and shell/audio.py).

Provenance

This project is 100% vibe coded: no human looked at the game itself — played it, watched it run, or reviewed a screenshot — until it was published as v20260716-1. All design, implementation, and verification up to that point were done by an AI agent operating this repository end to end (specs, plans, tests, the scripted playtest harness, and CI), with the human author directing scope and reviewing written artifacts (specs, plans, diffs) rather than the running game.

Install

Requires Python >= 3.14.

pip install psychic-cleaners

Play

psychic-cleaners

Win condition: end the finale with a bankroll strictly greater than the one you started with. Your account code carries the bankroll into the next game.

Developing from a clone

Requires uv.

git clone https://github.com/DrGeoff/psychic-cleaners.git
cd psychic-cleaners
uv sync
uv run psychic-cleaners

Controls

Development

uv run pytest                 # full suite (SDL dummy drivers set by tests/conftest.py)
uv run ruff check .           # lint
uv run ruff format .          # format
uv run mypy                   # strict type-check of src and tests
uv run pre-commit install     # ruff + mypy on every commit

CI additionally enforces >= 90% coverage on the pure-logic core: uv run pytest --cov=psychic_cleaners.core --cov-fail-under=90 --override-ini="addopts=--cov-report=term-missing" (the override drops the package-wide --cov from pyproject addopts so the gate measures core/ only).

Project layout

src/psychic_cleaners/
  core/    # pure deterministic game logic — zero pygame imports
           # constants.py is the single tuning point for every gameplay number
  shell/   # all pygame-ce code: app loop, generated sprites/audio, one module per scene
tests/
  core/         # fast unit + Hypothesis property tests
  integration/  # scripted full-playthrough tests of core.game (no pygame)
  shell/        # SDL dummy-driver smoke tests

The shell feeds Command objects into core.game.Game.tick, which returns Event objects; the shell draws state and plays a sound per event. Same seed + same commands = same game, which is what makes the playthrough tests deterministic.

License

Public domain — see LICENSE (The Unlicense).