Mochi Pacman Frog Screen Pet

A tiny Windows desktop pet made from a pixel-art Pacman frog spritesheet. It sits near the bottom of your screen, hops left and right, turns around at screen edges, reacts to your mouse with a tongue flick, and goes to sleep after 30 minutes without nearby mouse interaction.

Features

• Transparent always-on-top desktop pet window.
• Autonomous horizontal left/right hopping.
• Edge detection and turn-around behavior.
• Mouse proximity attention behavior.
• Tongue flick when the pointer gets close.
• Sleep state after inactivity, holding on the lying/resting frame.
• Runtime left/right mirroring for idle, sleep, happy, tongue, chomp, jump, and attention states.
• Runtime alpha cleanup to reduce green halos around the sprite.
• Per-pet randomized speech bubbles.

Requirements

For running from source:

• Windows 10 or 11
• Python 3.10+
• Pillow

Install dependencies:

python -m pip install -r requirements.txt

Run From Source

From this folder:

python frog_screen_pet.py

The default profile is frog; it can also be selected explicitly:

python frog_screen_pet.py --pet frog

Run the cat profile:

python frog_screen_pet.py --pet cat

Or use the included launcher:

run_frog_pet.bat

Build The EXE

Install build dependencies:

python -m pip install -r requirements-build.txt

Build:

build_exe.bat

The app will be created at:

dist\MochiPacmanFrog.exe

Normalize A Sprite Sheet

The reusable recrop tool detects transparent sprite components, merges nearby detached fragments, and writes them into a uniform grid:

python tools\recrop_spritesheet.py ^
  cat_sprite_sheet_fullhd_transparent.png ^
  assets\pets\cat\spritesheet.webp ^
  --frame-counts 7,8,7,5,6,7,8,8,8 ^
  --report assets\pets\cat\recrop_report.txt

The frame-count list describes the number of frames expected in each source row. Component thresholds and output cell dimensions can be adjusted through the tool's CLI options.

Run the exe:

dist\MochiPacmanFrog.exe

Controls

• Move the mouse near the frog to make it pay attention.
• Move the mouse very close to trigger the tongue flick.
• Leave it alone for 30 minutes and it will sleep.
• Press Esc while the pet has focus to exit.
• In --click-through mode, close it from Terminal with Ctrl+C or Task Manager.

Options

Examples:

python frog_screen_pet.py --scale 0.75 --bottom-margin 20 --speed 13
python frog_screen_pet.py --sleep-after 1800 --tongue-radius 190
python frog_screen_pet.py --alpha-threshold 24
python frog_screen_pet.py --no-normalize-hops
python frog_screen_pet.py --click-through

Common options:

Option	Default	Description
--pet	frog	Pet profile selected from src/pets/.
--spritesheet	profile default	Override the profile's spritesheet.
--scale	0.65	Visual size of the pet.
--bottom-margin	8	Pixels above the bottom of the screen.
--speed	11	Horizontal pixels moved per hop frame.
--decision-every	3.5	Seconds between autonomous behavior choices.
--tongue-radius	150	Mouse distance that triggers tongue flick.
--attention-radius	260	Mouse distance that triggers attention.
--tongue-cooldown	2.2	Minimum seconds between tongue flicks.
--sleep-after	1800	Seconds before sleeping. 1800 is 30 minutes.
--alpha-threshold	12	Higher values remove more edge halo pixels.
--no-normalize-hops	off	Disable runtime hop-size normalization.
--click-through	off	Let clicks pass through the pet window on Windows.

Animation Speed

Frame durations are defined near the top of frog_screen_pet.py in the ANIMATIONS dictionary.

Example:

"hop_right": Animation(1, tuple(range(8)), (120, 120, 120, 120, 120, 120, 120, 220)),

The numbers are milliseconds per frame. Bigger numbers make the animation slower.

Troubleshooting

If you see a green outline:

python frog_screen_pet.py --alpha-threshold 24

If movement looks too fast:

python frog_screen_pet.py --speed 8

If the pet is too large or small:

python frog_screen_pet.py --scale 0.55
python frog_screen_pet.py --scale 0.8

If the pet gets in the way:

python frog_screen_pet.py --click-through

Project Files

• frog_screen_pet.py - minimal executable entry point.
• src/app.py - application controller and animation tick.
• src/cli.py - command-line parsing and application startup.
• src/models.py - animation definitions and mutable runtime pet state.
• src/config.py - shared runtime configuration.
• src/behavior.py - mouse reactions, sleeping, and autonomous decisions.
• src/movement.py - movement and screen-edge handling.
• src/rendering.py - spritesheet loading and frame preparation.
• src/window.py - Tkinter and Windows window integration.
• src/resources.py - source/PyInstaller resource lookup.
• src/speech.py - per-pet random dialogue scheduling and speech state.
• src/speech_window.py - speech-bubble drawing and screen positioning.
• src/pets/ - per-pet profiles; the frog definition lives in frog.py.
• tools/recrop_spritesheet.py - normalize loosely arranged transparent sprite sheets.
• spritesheet.webp - v2 sprite atlas used by the app.
• run_frog_pet.bat - source launcher for Windows.
• build_exe.bat - PyInstaller build launcher.
• requirements.txt - runtime Python dependency.
• requirements-build.txt - build-time Python dependency.

License

MIT License. See LICENSE.