Initial commit: eSheep Wayland desktop pet

Python/GTK3/gtk-layer-shell port of the classic Windows eSheep.
All 54 original animations via the upstream animations.xml sprite sheet.

Features beyond the base animation engine:
- Window walking via Wayfire IPC
- UFO abduction sequence (drawn procedurally)
- Flower-sniff: anim 26 + sprite overlay (anim 27)
- Soft/hard landing bounce (patched anim 9/10 seq_nexts)
- Periodic small hop to trigger natural bounce without windows
- Click-to-drag sheep with mouse
- Multi-sheep bump and greet interactions
- --count, --daemon, --exit flags

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

1 files changed, 101 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..78e4636
--- /dev/null
+++ b/README.md
@@ -0,0 +1,101 @@
+# eSheep — Wayland Desktop Pet
+
+A Linux/Wayland port of the classic Windows 95 eSheep desktop pet, using GTK3,
+gtk-layer-shell, and the original eSheep animation XML.
+
+The sheep walks across your screen, climbs window edges, falls off them, gets
+abducted by UFOs, sniffs flowers, and bounces when it lands.
+
+---
+
+## Features
+
+- All 54 original eSheep animations (walk, run, sleep, bath, climb, fall, …)
+- Lands on and walks across the tops of open windows (requires Wayfire IPC)
+- Falls off window edges with soft/hard landings; occasionally bounces
+- Periodic small hops with a chance of a boing landing
+- Flower-sniff sequence: sheep stops, a flower sprite appears at its feet
+- UFO abduction every ~90 seconds
+- Click-and-drag any sheep with the mouse
+- Multi-sheep: sheep bump into and greet each other
+- `--count N` for a flock
+- `--daemon` to detach from the terminal
+- `--exit` to kill all running instances
+
+---
+
+## Requirements
+
+| Package | Notes |
+|---------|-------|
+| Python 3.8+ | |
+| python3-gi | PyGObject |
+| python3-gi-cairo | Cairo bindings |
+| python3-pil | Pillow |
+| python3-numpy | |
+| gir1.2-gtk-3.0 | GTK 3 introspection |
+| gir1.2-gtklayershell-0.1 | Layer-shell introspection |
+| wayfire (pip) | Optional — enables window walking |
+
+---
+
+## Install
+
+```bash
+git clone git@mirkwood.jots.org:esheep-wayland.git
+cd esheep-wayland
+bash install.sh
+```
+
+The installer detects apt / pacman / dnf and installs dependencies, then copies
+files to `~/.local/share/esheep/` and creates a `~/.local/bin/esheep` launcher.
+
+Make sure `~/.local/bin` is in your `$PATH`.
+
+---
+
+## Usage
+
+```bash
+# Basic
+esheep
+
+# Flock
+esheep --count 5
+
+# Run in background
+esheep --count 3 --daemon
+
+# Kill all running instances
+esheep --exit
+```
+
+---
+
+## Window walking (Wayfire)
+
+For the sheep to walk on window tops, the Wayfire `ipc` plugin must be active.
+Edit `~/.config/wayfire.ini`:
+
+```ini
+[core]
+plugins = ... ipc
+```
+
+Then reload Wayfire (log out/in or `pkill -HUP wayfire`). Confirm with:
+
+```bash
+echo $WAYFIRE_SOCKET
+```
+
+Window walking is silently skipped if the socket isn't available — the sheep just
+lives on the screen floor instead.
+
+---
+
+## Credits
+
+Animation data (`animations.xml` and sprite sheet) from
+[Adrianotiger/desktopPet](https://github.com/Adrianotiger/desktopPet).
+
+Original eSheep by Adriano Petrucci.