README.md

---
title: DigiPal - AI Monster Companion
emoji: 🐨
colorFrom: purple
colorTo: green
sdk: gradio
sdk_version: 5.34.2
app_file: app.py
pinned: false
license: apache-2.0
hardware: zero-gpu
hf_oauth: true
hf_oauth_scopes:
- read-repos
- write-repos
hf_oauth_expiration_minutes: 480
models:
- kyutai/stt-2.6b-en
- Qwen/Qwen2.5-0.5B-Instruct
- OmniGen2/OmniGen2
- tencent/Hunyuan3D-2.1
tags:
- game
- 3d
- voice
- monster
- ai-companion
- digital-pet
---

# 🤖 DigiPal: AI-Powered Digital Monster Companion

<div align="center">
  
[![Hugging Face Spaces](https://img.shields.io/badge/🤗%20Hugging%20Face-Spaces-blue)](https://huggingface.co/spaces/your-username/DigiPal)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

[Demo](https://huggingface.co/spaces/your-username/DigiPal) | [Report Bug](https://github.com/your-username/DigiPal/issues) | [Request Feature](https://github.com/your-username/DigiPal/issues)

</div>

## 🌟 Overview

DigiPal brings the nostalgic charm of digital pet games into the AI era. Create, train, and evolve unique digital monsters using cutting-edge AI models. Inspired by classic games like Digimon World, DigiPal combines voice interaction, real-time 3D generation, and engaging gameplay mechanics.

### ✨ Key Features

- 🎙️ **Voice Interaction**: Create monsters by describing them with your voice
- 🖼️ **AI-Powered Generation**: Unique monster designs generated in real-time
- 🦾 **3D Models**: Automatic conversion from 2D to rigged 3D models
- 🎮 **Classic Gameplay**: Training, evolution, and care mechanics
- 💾 **Persistent Storage**: Your monsters are saved across sessions
- 🤖 **Emoji Communication**: Monsters speak in emojis and numbers
- 🌐 **Zero GPU Optimized**: Runs efficiently on HuggingFace Spaces

## 🚀 Getting Started

### Online Demo

Visit our [HuggingFace Space](https://huggingface.co/spaces/your-username/DigiPal) to try DigiPal instantly!

### Local Installation

```bash
# Clone the repository
git clone https://github.com/your-username/DigiPal.git
cd DigiPal

# Install dependencies
pip install -r requirements.txt

# Run the application
python app.py
```

## 🎮 How to Play

### 1. Create Your Monster

**Voice Control:**
- Click the microphone button
- Describe your ideal monster
- Example: "Create a fire-breathing dragon with blue scales"

**Visual Control:**
- Upload reference images
- Draw your monster concept
- Use the camera for real-world inspiration

### 2. Train & Evolve

- Choose training types: Strength, Defense, Speed, Intelligence
- Complete training sessions to improve stats
- Meet evolution requirements to unlock new forms

### 3. Care System

- **Feed**: Keep hunger above 30%
- **Play**: Maintain happiness above 40%
- **Rest**: Manage fatigue levels
- **Medicine**: Heal when health drops

### 4. Monster Communication

Your monster communicates using emojis and numbers:
- 🤖💚 = Happy state
- 🍖❓ = Hungry
- 😴💤 = Tired
- Numbers represent HP and happiness percentages

## 🏗️ Architecture

### AI Pipeline

1. **Speech Recognition**: Kyutai STT for voice commands
2. **Text Generation**: Qwen2.5 for monster traits
3. **Image Generation**: OmniGen2 for visual creation
4. **3D Conversion**: Hunyuan3D for model generation
5. **Rigging**: Automatic skeleton and animation

### Technology Stack

- **Frontend**: Gradio with cyberpunk theming
- **Backend**: Python with HuggingFace Spaces
- **AI Models**: State-of-the-art transformers
- **Storage**: Persistent HF Spaces storage
- **Optimization**: Zero GPU with intelligent fallbacks

## 📊 Game Mechanics

### Stats System
- **HP**: Health points (10-999)
- **Attack**: Offensive power (5-500)
- **Defense**: Defensive capability (5-500)
- **Speed**: Movement and reaction (5-500)
- **Special**: Magic/unique abilities (5-500)

### Evolution Stages
1. **Rookie**: Starting form
2. **Champion**: First evolution (150+ total stats)
3. **Ultimate**: Advanced form (300+ total stats)
4. **Mega**: Final evolution (500+ total stats)

### Personality Types
- Brave, Timid, Aggressive, Gentle
- Playful, Serious, Loyal, Independent
- Each affects training preferences and dialogue

## 🛠️ Advanced Features

### Custom Modifications

Modify `core/game_mechanics.py` to:
- Add new evolution paths
- Create custom training types
- Implement new care mechanics

### Model Swapping

Replace AI models in `models/` directory:
- Use different STT models
- Try alternative image generators
- Experiment with 3D converters

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit changes (`git commit -m 'Add AmazingFeature'`)
4. Push to branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Inspired by Digimon World series
- Built with HuggingFace ecosystem
- Community feedback and contributions
- Open-source AI model creators

## 📞 Contact & Support

- **Issues**: [GitHub Issues](https://github.com/your-username/DigiPal/issues)
- **Discussions**: [HuggingFace Community](https://huggingface.co/spaces/your-username/DigiPal/discussions)
- **Email**: [email protected]

---

<div align="center">
Made with ❤️ by the DigiPal Team
</div>