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, 104 insertions, 0 deletions

diff --git a/INSTALL.md b/INSTALL.md
new file mode 100644
index 0000000..cd00c39
--- /dev/null
+++ b/INSTALL.md
@@ -0,0 +1,104 @@
+# eSheep — Wayland Installation Guide
+
+## Quick install
+
+```bash
+bash install.sh
+```
+
+The script auto-detects apt / pacman / dnf. For anything else, see the manual
+steps below.
+
+---
+
+## Manual install
+
+### 1 — System packages
+
+**Debian/Ubuntu:**
+```bash
+sudo apt-get install -y \
+    python3 python3-gi python3-gi-cairo \
+    gir1.2-gtk-3.0 gir1.2-gtklayershell-0.1 \
+    python3-pil python3-numpy python3-pip
+```
+
+**Arch:**
+```bash
+sudo pacman -S --needed python python-gobject python-pillow gtk3 gtk-layer-shell python-numpy
+```
+
+**Fedora:**
+```bash
+sudo dnf install -y python3 python3-gobject python3-pillow gtk3 gtk-layer-shell python3-numpy
+```
+
+### 2 — Wayfire IPC library (optional, for window walking)
+
+```bash
+pip3 install --user wayfire --break-system-packages
+# or without the flag on non-Debian systems:
+pip3 install --user wayfire
+```
+
+### 3 — Copy files
+
+```bash
+mkdir -p ~/.local/share/esheep ~/.local/bin
+
+cp esheep.py animations.xml ~/.local/share/esheep/
+
+cat > ~/.local/bin/esheep << 'EOF'
+#!/usr/bin/env bash
+exec python3 "$HOME/.local/share/esheep/esheep.py" \
+     --xml "$HOME/.local/share/esheep/animations.xml" "$@"
+EOF
+chmod +x ~/.local/bin/esheep
+```
+
+### 4 — Enable Wayfire IPC (optional)
+
+Edit `~/.config/wayfire.ini` and add `ipc` to the plugins list:
+
+```ini
+[core]
+plugins = ... ipc
+```
+
+Reload Wayfire (log out/in or `pkill -HUP wayfire`), then confirm:
+
+```bash
+echo $WAYFIRE_SOCKET   # should print a socket path
+```
+
+---
+
+## Usage
+
+```
+esheep [--count N] [--daemon] [--exit] [--xml PATH]
+
+  --count N    Spawn N sheep (default: 1)
+  --daemon     Detach from terminal and run in the background
+  --exit       Kill all running eSheep instances and quit
+  --xml PATH   Use a custom animations.xml
+```
+
+---
+
+## Troubleshooting
+
+**"wlr-layer-shell not supported"**
+Your compositor doesn't support the layer-shell protocol. eSheep requires a
+wlroots-based compositor: Wayfire, Sway, Hyprland, etc.
+
+**Sheep ignores windows / only walks on the screen floor**
+The Wayfire `ipc` plugin isn't active or `$WAYFIRE_SOCKET` isn't set in the
+current session. See step 4 above.
+
+**`wayfire` Python package not found**
+Run `pip3 install --user wayfire --break-system-packages`.
+
+**Sheep appears but flower/bounce never happen**
+Both are timed events (flower: every 60–120 s; hop/bounce: every 45–90 s).
+Leave eSheep running for a few minutes.