Team Up Tool - Darkest Dungeon Team Builder

A comprehensive desktop application for managing and building team compositions in Darkest Dungeon, featuring AI-powered analysis, hero management, and team generation capabilities.

✨ Features

Core Functionality

• Find My Teams: Search and filter teams based on your selected heroes
• Select My Heroes: Manage your hero roster from game save files
• Hero Wiki: Browse detailed hero information from wiki database
• Team Generation: Automatically generate team compositions using mapping logic
• Team Review: Review, approve, or reject generated teams before adding to database
• Hero Manager: Convert .darkest files to wiki format with AI assistance

Key Highlights

• 🎯 Smart team matching based on hero roles and abilities
• 🤖 AI-powered hero analysis (optional, using Gemini API)
• 📊 Comprehensive team database with composition templates
• 🖼️ Hero image gallery integration
• 📝 Detailed wiki system for hero information
• 🌙 Dark theme UI for comfortable viewing

📋 Requirements

• Python 3.8 or higher
• Required Python packages:
  • tkinter (usually included with Python)
  • PIL (Pillow)
  • google-generativeai (for AI features, optional)
  • python-dotenv (for environment variables, optional but recommended)

🚀 Installation

1. Clone the Repository

git clone https://github.com/yourusername/Project_TeamUp.git
cd Project_TeamUp

2. Set Up Virtual Environment (Recommended)

# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate

3. Install Dependencies

pip install Pillow google-generativeai python-dotenv

4. Configure Environment Variables

Create a .env file in the root directory:

# Gemini API Configuration
GEMINI_API_KEY=your_api_key_here

To get a Gemini API key:

1. Visit Google AI Studio
2. Create a new API key
3. Copy it to your .env file

Note: AI features are optional. The application can run without the API key, but hero analysis features will be disabled.

📁 Project Structure

Project_TeamUp/
├── scripts/
│   ├── all_in_one_tool.py      # Main application
│   ├── team_mapper.py           # Team generation logic
│   ├── migrate_teams.py         # Migration utilities
│   └── split_teams.py           # Team splitting utilities
├── assets/                      # Resource files (optional)
│   ├── heroes_images/           # Hero images
│   ├── wiki/                    # Hero information files
│   ├── teams/                   # Generated teams database
│   ├── my_heroes.txt            # Your hero roster
│   └── team_compositions.json   # Team composition templates
├── .env                         # Environment variables (not in git)
├── .env.example                 # Example environment file
├── .gitignore                   # Git ignore rules
└── README.md                    # This file

Resource File Locations

The application supports two resource locations:

1. assets/ folder (recommended for GitHub): All resource files organized in one place
2. Root directory (current default): Files directly in project root

The application automatically detects and uses the assets/ folder if it exists, otherwise falls back to the root directory.

🎮 Usage

Running the Application

cd scripts
python all_in_one_tool.py

Or if using assets folder:

python scripts/all_in_one_tool.py

Main Menu Features

1. Find My Teams

• Load your heroes from my_heroes.txt
• Search teams by keywords or hero names
• Filter by composition type
• View team details, hero images, and skill selections

2. Select My Heroes

• Import heroes from game save files
• Manage your hero roster
• Export to my_heroes.txt

3. Hero Wiki

• Browse all heroes in the wiki database
• View detailed hero information and abilities
• Search and filter heroes

4. Hero Manager

• Load .darkest files from game saves
• Convert to wiki format with AI assistance
• Manage hero images and information

5. Analyze New Teams

• Generate new team compositions using mapping logic
• Select specific compositions or analyze all
• Teams are generated based on:
  • Composition requirements from team_compositions.json
  • Hero data from wiki files
  • Duplicate detection

6. Review Generated Teams

• Review newly generated teams before saving
• Accept or reject teams individually
• Teams are only saved to the database after approval

7. Settings

• Configure Gemini API key (loaded from .env)
• Test API connection
• Application settings

📝 Data Files

team_compositions.json

Contains team composition templates (khuôn mẫu đội hình):

• Composition names and descriptions
• Key mechanics and requirements
• Role and ability requirements

Teams Database

Located in teams/ folder:

• Each composition has its own folder (normalized name)
• Individual teams stored as separate JSON files
• Composition metadata in _composition_info.json

my_heroes.txt

Your personal hero roster, one hero name per line.

Wiki Files

Located in wiki/ folder (or assets/wiki/):

• One .txt file per hero
• Contains detailed hero analysis and information

🔧 Configuration

Environment Variables

Create a .env file with:

GEMINI_API_KEY=your_api_key_here

Settings File

Application settings are saved in settings.json (automatically created).

🗂️ File Organization

Recommended Structure for GitHub

Organize resources in an assets/ folder:

assets/
├── heroes_images/
├── wiki/
├── teams/
├── my_heroes.txt
└── team_compositions.json

The application will automatically detect and use this structure.

🛠️ Development

Code Structure

• Main Application: scripts/all_in_one_tool.py

  • GUI frames for each feature
  • File I/O and data management
  • Integration with team mapper

• Team Generation: scripts/team_mapper.py

  • Hero-requirement matching logic
  • Team combination generation
  • Skill selection algorithms

Adding New Features

1. Create a new frame class in all_in_one_tool.py
2. Register it in MainApp.__init__
3. Add navigation button in MainMenuFrame

📦 Building Executable

To create a standalone executable with PyInstaller, see BUILD.md for detailed instructions.

Quick Start

# Windows PowerShell
.\build.ps1

# Windows CMD
build.bat

# Or manually
pyinstaller --clean all_in_one_tool.spec

The executable will be created in dist/TeamUpTool.exe.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Darkest Dungeon by Red Hook Studios
• Google Gemini API for AI features

⚠️ Notes

• The application requires hero images and wiki files to function fully
• Team generation works best with complete hero data
• .env file should never be committed to version control
• Make sure to add .env to .gitignore

🐛 Troubleshooting

API Key Issues

• Ensure .env file exists in root directory
• Check that GEMINI_API_KEY is set correctly
• Verify API key is valid in Google AI Studio

Missing Resources

• Ensure hero images are in heroes_images/ or assets/heroes_images/
• Check that wiki files exist in wiki/ or assets/wiki/
• Verify team_compositions.json exists

Import Errors

• Make sure all dependencies are installed: pip install -r requirements.txt
• Check Python version: python --version (should be 3.8+)

---

Enjoy building your perfect Darkest Dungeon teams! 🗡️🛡️