🐾 ClovePet (Desktop Companion)

A charming, advanced Desktop Pet companion built with Electron and TypeScript. Originally a Valentine's project, it has evolved into a smart productivity guardian that scolds you for distractions and reminds you to stay hydrated!

✨ Features

• Study Guardian: Automatically detects and kills banned games (Steam, Valorant, Roblox, etc.) and scolds you if you open Instagram.
• Pixel-Perfect Hitbox: Advanced transparency detection allows you to click through her empty space to interact with windows behind her.
• Idle System: Clove goes to sleep (clove-idle.png) after 60 seconds of inactivity to stay out of your way.
• Health Reminders: Periodic hydration checks with custom sound effects to keep you drinking water.
• Immersive Sound System: High-quality audio cues for alerts, startup, and success interactions.
• System Tray Integration: Easily show, hide, or quit the pet from the Windows system tray.
• Proposal Flow: Heartwarming dialogue sequence with a "sad loop" rejection handler for special occasions.
• Unobtrusive Design: Roaming is disabled by default—Clove stays exactly where you drag her.

🚀 Getting Started

Prerequisites

• Bun (v1.0 or later)
• Node.js (required for Electron)

Installation

1. Clone the repository

   git clone https://github.com/ee3lol/valentine-pet.git
   cd valentine-pet

2. Install dependencies

   bun install

3. Run Locally

   bun start

🛠️ Building for Distribution

To create a standalone portable executable (.exe) for Windows:

bun run dist

The output file will be located in the release/win-unpacked directory.

📂 Project Structure

The project follows a clean ESM modular structure:

src/
├── assets/          # Images (clove.png, clove-happy.png, etc.)
├── config/          # Dialogue texts and constants
├── core/            # Business logic (Roaming, Interaction Stages)
├── state/           # Global state management
├── utils/           # Helper functions (DOM, Effects)
├── types/           # TypeScript interfaces
├── index.ts         # Main Process (Electron entry)
├── preload.ts       # IPC Bridge (Security)
└── renderer.ts      # Renderer Process (UI entry)

🎨 Customization

Changing Dialogues

Edit src/config/dialogues.ts to change what the pet says during the proposal or rejection phases.

Changing Character

Replace the images in src/assets/:

• clove.png (Default state)
• clove-happy.png (Success state)
• clove-sad.png (Rejection state)

🤝 Contributing

Contributions are welcome!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.

---

• @ee3lol