HatPet

A custom desktop pet for Linux, built in Godot 4. Wanders freely across the screen in 8 directions, idles, and can be dragged with the mouse.

Requirements

• Linux with an X11 session (or XWayland fallback — see Running section)
• Godot 4.7+ (installed via Flatpak recommended)
• NVIDIA GPU users: Vulkan/Forward+ renderer confirmed working via XWayland

Demo

Check in this path

https://github.com/amareshhebbar/hatpet/working_proof

Install Godot

sudo dnf install flatpak
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install flathub org.godotengine.Godot

Clone and Run

git clone https://github.com/amareshhebbar/hatpet
cd hatpet

Open in the editor (dashboard)

flatpak run org.godotengine.Godot -e --display-driver x11 --path .

Run standalone (no editor, just the pet)

flatpak run org.godotengine.Godot --display-driver x11 --path .

Optional: save a launcher script

cat > ~/run_hatpet.sh << 'SCRIPT'
#!/bin/bash
pkill -9 -f godot
sleep 2
flatpak run org.godotengine.Godot --display-driver x11 --path /absolute/path/to/hatpet
SCRIPT
chmod +x ~/run_hatpet.sh

Then just run ~/run_hatpet.sh any time.

Wayland Note

Native Wayland does not allow client apps to reposition their own window, which breaks movement entirely. The --display-driver x11 flag forces Godot through XWayland instead, which works even inside a GNOME Wayland session. No session switch needed.

Project Structure

hatpet/
├── project.godot                     # Engine config — transparency, borderless, always-on-top window flags
├── pet_root.tscn                     # Main scene: PetRoot -> Visual (AnimatedSprite2D) + BehaviorTimer
├── pet_root.gd                       # Movement state machine, drag handling, 8-directional wander logic
└── kenney_animal-pack-remastered/    # Placeholder sprite assets (CC0, see License.txt inside)

Current Features

• Transparent, borderless, always-on-top window
• 8-directional wandering (horizontal, vertical, diagonal) with screen-edge bouncing
• Idle pauses between movement bursts
• Click-and-drag to reposition
• Single static sprite frame (Kenney animal pack)

Roadmap

• Idle/walk animation frames (currently static single frame)
• Hunger/mood stats with save/load persistence
• Click-to-feed and click-to-pet interactions
• Gravity-based drop physics
• Multi-monitor wander support
• Sound effects
• Linux/X11 export build + .desktop launcher

Troubleshooting

• Window shows as a solid gray box with a title bar instead of a transparent character — confirm window/size/transparent=true, window/size/borderless=true, and window/per_pixel_transparency/allowed=true are all present in project.godot under [display]. Also make sure you're running the exported/standalone build, not the editor's embedded debug view, since embedded play mode ignores these flags.
• Only part of the sprite is visible / it looks cropped — the Visual node's Transform Position and Scale don't match the sprite's native size relative to the window's viewport dimensions. Temporarily enlarge the window (e.g. 200x200) with Scale at 1.0 to confirm the full sprite loads, then recalculate Position (half the window size) and Scale (target size ÷ native sprite size) together.
• Pet is frozen in place but still changes color/animation on schedule — you're on native Wayland without the --display-driver x11 flag. Add it to your run command.
• Multiple Godot processes pile up / stale windows linger — run pkill -9 -f godot and wait a couple seconds before relaunching.
• "Embedded window can't be moved" spam in the terminal — you're running via the editor's Play button (embedded game view) rather than standalone. Stop the embedded session and launch via terminal without the -e flag instead.

License

Project code: choose your own license (MIT recommended for a personal tool). Sprite assets: Kenney Animal Pack Remastered, CC0 — see kenney_animal-pack-remastered/License.txt.