# DigiPal V2 - Complete Development Guide

## Overview

DigiPal V2 is a revolutionary digital monster companion application that combines:
- **Authentic Digimon World 1 mechanics** based on comprehensive reverse engineering
- **Modern AI conversations** using Qwen 2.5 models
- **Optional 3D generation** using cutting-edge open-source pipeline (Flux → Sparc3D → UniRig)
- **Real-time care simulation** with mortality and complex evolution

## Architecture

### Core Components

```
digiPal/
├── src/
│   ├── core/
│   │   ├── monster_engine_dw1.py      # DW1-accurate monster mechanics
│   │   └── monster_3d_integration.py  # 3D model management
│   ├── pipelines/
│   │   ├── text_to_3d_pipeline.py     # Commercial 3D pipeline (Meshy AI)
│   │   └── opensource_3d_pipeline_v2.py # Open-source pipeline (Flux/Sparc3D/UniRig)
│   ├── ui/
│   │   └── gradio_interface_v2.py     # Enhanced Gradio interface
│   └── ai/
│       └── qwen_processor.py          # AI conversation system
├── app_v2.py                          # Main application entry
└── README.md                          # HuggingFace Spaces config
```

## Key Features Implementation

### 1. DW1-Accurate Monster System

The `DW1Monster` class implements authentic mechanics:

```python
# Lifespan system with mortality
LIFESPAN_DAYS = {
    "BABY": 1, "CHILD": 3, "ADULT": 5, 
    "PERFECT": 6, "ULTIMATE": 7, "MEGA": 8
}

# Complex stat system
- HP/MP (max 9999)
- Offense/Defense/Speed/Brains (max 999)
- Weight (5-99, affects evolution)
- Nature (0-100, affects techniques)

# Care mechanics
- Hunger (depletes faster during activity)
- Energy (restored by sleep)
- Toilet needs (every 3 hours)
- Happiness (affects training)
- Discipline (affects obedience)
- Sickness system (Cold, Injury, Fatigue, Stomach)

# Evolution system
- Time-based progression
- Stat requirements
- Care quality thresholds
- Weight requirements
- Special conditions (perfect week, tournament wins)
```

### 2. Training System

Based on DW1's gym mechanics:
```python
# Training types match DW1 locations
- HP Training (Green Gym)
- MP Training (Beetle Land)
- Offense Training (Dojo)
- Defense Training (Ice Gym)
- Speed Training (Speed Gym)
- Brains Training (Library)

# Performance-based gains
- PERFECT: 150% gain
- GREAT: 120% gain
- GOOD: 100% gain
- MISS: 50% gain + care mistake
```

### 3. Evolution Mechanics

Implements DW1's complex branching:
```python
# Baby → Child (6 hours)
- Personality-based (Brave→Agumon, Calm→Gabumon)
- Care quality affects outcome

# Child → Adult (24 hours)
- Stat requirements (total > 200)
- Weight requirements (15-35)
- Care mistakes < 5
- Highest stat determines form

# Adult → Perfect (72 hours)
- High stats (total > 500)
- Excellent care (mistakes < 3)
- Battle experience (15+ wins)

# Perfect → Ultimate (96 hours)
- Perfect care week required
- Very high stats (total > 800)
- Extensive battles (30+ wins)
```

### 4. 3D Generation Pipeline

Two implementation options:

#### Commercial Pipeline (Meshy AI)
```python
# Fast, high-quality, API-based
- Text → Meshy AI → 3D Model
- 2-12 credits per generation
- Built-in rigging support
- PBR textures included
```

#### Open-Source Pipeline (Production Ready)
```python
# Free, cutting-edge, locally runnable
1. Text → Flux (HF Spaces API)
   - Multi-view generation (6 views)
   - Consistent character design
   
2. Images → Sparc3D (1024³ resolution)
   - Ultra-high quality mesh
   - Texture projection
   
3. Mesh → UniRig (Auto-rigging)
   - Procedural skeleton generation
   - Weight painting
   - Animation-ready output
```

## Setup Instructions

### Basic Setup (No 3D)

```bash
# Clone repository
git clone https://github.com/yourusername/digiPal
cd digiPal

# Install dependencies
pip install -r requirements.txt

# Run application
python app_v2.py
```

### Full Setup (With 3D)

```bash
# Install additional dependencies
pip install gradio_client trimesh pillow

# Clone required repositories
git clone https://github.com/lizhihao6/Sparc3D
git clone https://github.com/VAST-AI-Research/UniRig

# Configure API keys (optional)
export HF_TOKEN="your_huggingface_token"

# Run with 3D enabled
ENABLE_3D=true python app_v2.py
```

### HuggingFace Spaces Deployment

The application is optimized for Spaces:

1. **YAML Configuration** (in README.md):
```yaml
suggested_hardware: zero-a10g
suggested_storage: medium
```

2. **Environment Variables**:
```
ENABLE_3D=true
ENABLE_AI=true
LOG_LEVEL=INFO
```

## Usage Guide

### Creating Your First Monster

1. **Choose Species Type**: Affects evolution paths
   - Data: Mechanical/Digital evolutions
   - Vaccine: Holy/Light evolutions
   - Virus: Dark/Chaos evolutions
   - Free: Balanced evolutions

2. **Select Personality**: Affects behavior and growth
   - Brave: +Offense, -Defense
   - Calm: +Defense, -Speed
   - Energetic: +Speed, -MP
   - Clever: +Brains/MP, -HP
   - Friendly: Balanced, easier care

### Care Guidelines

1. **Feeding**:
   - Feed when hunger > 50
   - Don't overfeed (causes care mistakes)
   - Different foods have different effects

2. **Training**:
   - Train when energy > 50
   - Match training to desired evolution
   - Perfect performance gives bonus gains

3. **Health**:
   - Check toilet needs every 3 hours
   - Heal sickness immediately
   - Let monster sleep at night (8PM-8AM)

### Evolution Tips

1. **For Strong Evolutions**:
   - Minimize care mistakes (< 3)
   - Balanced stat growth
   - Regular training
   - Win battles

2. **Special Evolutions**:
   - Perfect care for 7 days
   - Win tournaments
   - Specific stat distributions
   - Weight requirements

## Technical Details

### Performance Optimization

1. **ZeroGPU Support**:
```python
@spaces.GPU(duration=60)
def generate_3d_model():
    # GPU-intensive operations
```

2. **Async Operations**:
- Database operations
- 3D generation pipeline
- Multi-view image generation

3. **Memory Management**:
- Model quantization (8-bit)
- Texture compression
- Mesh decimation

### Customization Options

1. **Monster Definitions**:
Edit `monster_engine_dw1.py` to add:
- New evolution paths
- Custom techniques
- Special forms

2. **3D Styles**:
Modify prompts in `_generate_3d_prompt()`:
- Art style preferences
- Detail levels
- Color schemes

3. **UI Themes**:
Edit `CUSTOM_CSS` in interface:
- Color schemes
- Fonts
- Animations

## Troubleshooting

### Common Issues

1. **"No GPU detected"**
   - Application works on CPU but slower
   - 3D generation may timeout

2. **"3D pipeline not available"**
   - Check Sparc3D/UniRig installation
   - Verify CUDA installation
   - Try commercial pipeline instead

3. **"Monster died unexpectedly"**
   - Check care history
   - Monitor lifespan remaining
   - Reduce care mistakes

### Performance Tips

1. **For Faster 3D Generation**:
   - Use "draft" quality
   - Reduce texture resolution
   - Enable model caching

2. **For Better Evolution Rates**:
   - Train regularly but don't overtrain
   - Keep happiness > 70
   - Minimize toilet accidents

## Future Enhancements

### Planned Features

1. **Battle System**:
   - Turn-based combat
   - Technique learning
   - PvP battles

2. **World Exploration**:
   - File City building
   - NPC recruitment
   - Item collection

3. **Breeding System**:
   - Genetic inheritance
   - Hybrid forms
   - Egg management

4. **Mini-Games**:
   - Training challenges
   - Fishing
   - Treasure hunting

## Credits

- **DW1 Reverse Engineering**: SydMontague, Vicen04, Romsstar
- **3D Pipeline**: Flux (Black Forest Labs), Sparc3D (lizhihao6), UniRig (VAST-AI)
- **AI Models**: Qwen 2.5 (Alibaba)
- **Framework**: Gradio (HuggingFace)

## Philosophy

Built following Rick Rubin's creative philosophy:
- **Strip to essentials**: Focus on core monster-raising mechanics
- **Amplify emotion**: Every interaction should create connection
- **Respect the source**: Authentic to Digimon World 1's spirit
- **Push boundaries**: Modern tech serving classic gameplay

## License

MIT License - See LICENSE file for details

---

*"The goal is not to recreate the past, but to capture what made it special and express it through modern possibilities."*