README.md

---
title: MergeBalanceTools
emoji: 🏢
colorFrom: yellow
colorTo: purple
sdk: gradio
sdk_version: 5.36.2
app_file: app.py
pinned: false
short_description: Набор инструментов для баланса мердж-2 игр.
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

# 🎮 Merge Balance Tools - Симулятор генерации заказов

Профессиональный инструмент для балансировки экономики merge-игр с поддержкой автоматизации через MCP протокол.

## ✨ Основные возможности

- 🔄 **Симуляция генерации заказов** с настраиваемыми параметрами сложности
- 📊 **Детальная аналитика** игрового баланса через статистические отчеты  
- 💾 **Система конфигураций** для сохранения и повторного использования настроек
- 🤖 **MCP API интеграция** для работы с ИИ агентами и автоматизации
- 📁 **Импорт Unity Asset файлов** для загрузки существующих конфигураций
- 📈 **Экспорт результатов** в CSV формате для дальнейшего анализа

## 🚀 Быстрый старт

### Требования
- Python 3.8+
- pip

### Установка
```bash
git clone <repository_url>
cd MergeBalanceTools
pip install gradio pandas pyyaml
```

### Запуск
```bash
python app.py
```
Откройте браузер по адресу `http://localhost:7860`

## 📋 Использование

### Базовый workflow
1. **Загрузите файлы конфигурации** (Unity .asset файлы) или создайте конфигурацию вручную
2. **Настройте параметры** генератора заказов в соответствующих секциях
3. **Запустите симуляцию** с нужным количеством итераций
4. **Проанализируйте результаты** в таблице данных и сводном отчете
5. **Сохраните конфигурацию** для повторного использования

### Ключевые параметры
- **Макс. заказов в истории**: Влияет на разнообразие генерируемых требований
- **Инкремент сложности**: Скорость роста сложности заказов
- **Шанс награды-энергии**: Баланс между энергетическими и предметными наградами
- **Веса требований**: Распределение вероятностей для заказов с 1-2 требованиями

## 🏗️ Архитектура проекта

```
MergeBalanceTools/
├── app.py                     # Основное Gradio приложение
├── config_manager.py          # Система управления конфигурациями
├── mcp_server.py             # MCP сервер для ИИ агентов
├── configs/                  # Автоматически создаваемая папка для конфигураций
├── Main_merge_item_chains/   # Примеры файлов цепочек Unity
├── MergeItems/              # Примеры merge-предметов
└── README.md                # Документация проекта
```

## 🤖 MCP API для ИИ агентов

Проект предоставляет полнофункциональный MCP (Model Context Protocol) сервер для интеграции с ИИ агентами:

### Основные функции API
- `mcp_save_simulator_config` - Сохранение конфигураций
- `mcp_load_simulator_config` - Загрузка конфигураций  
- `mcp_run_simulation` - Запуск симуляций
- `mcp_get_simulation_results` - Получение результатов
- `mcp_analyze_simulation_results` - Анализ данных

### Пример использования
```json
{
  "function": "mcp_run_simulation",
  "params": {
    "config_name_or_data": "test_balance_v1",
    "iteration_count": 200,
    "initial_energy": 10000,
    "return_detailed_results": true
  }
}
```

## 📊 Форматы данных

### Структура цепочки merge-предметов
```json
{
  "ChainId": "flowers_chain",
  "MergeItemId": "flower_seed_1", 
  "RequirementWeight": 100,
  "RewardDifficulty": 15
}
```

### Конфигурация наград
```json
{
  "DifficultyScore": 500,
  "Amount": 3,
  "MergeItemId": "energy_boost",
  "RewardWeight": 80,
  "ReductionFactor": 5
}
```

## 🔧 Расширенные возможности

### Импорт Unity Asset файлов
Система поддерживает прямой импорт файлов конфигурации из Unity:
- Файлы цепочек merge-предметов (`.asset`)
- Ruleset файлы с правилами генерации (`.asset`)
- Settings файлы с общими настройками (`.asset`)

### Система конфигураций
- Автоматическое сохранение в JSON формате
- Версионность конфигураций с временными метками
- Валидация данных при загрузке
- Удобный интерфейс управления

### Экспорт и анализ
- Экспорт результатов симуляции в CSV
- Генерация текстовых отчетов со статистикой
- Поддержка различных форматов анализа через MCP API

## 🛠️ Техническая информация

### Зависимости
- `gradio` - Веб-интерфейс приложения
- `pandas` - Обработка и анализ данных
- `pyyaml` - Парсинг Unity Asset файлов
- `dataclasses` - Типизированные структуры данных

### Совместимость
- Python 3.8+
- Кроссплатформенность (Windows, macOS, Linux)
- Веб-браузер с поддержкой JavaScript

## 📚 Документация

Полная документация доступна в интерфейсе приложения во вкладке "MCP API для ИИ агентов" или в отдельном файле документации.

### Основные разделы документации:
- Быстрый старт и установка
- Детальное описание интерфейса
- Примеры использования
- API Reference для MCP функций
- Устранение типичных проблем

## 🤝 Поддержка и развитие

### Типичные проблемы
- **Ошибки парсинга .asset файлов**: Проверьте кодировку UTF-8 и структуру YAML
- **Преждевременное завершение симуляции**: Увеличьте начальную энергию или снизьте стоимость предметов
- **MCP функции недоступны**: Убедитесь в наличии всех файлов проекта

### Roadmap
- [ ] Поддержка дополнительных форматов экспорта
- [ ] Расширенная аналитика с визуализацией
- [ ] Интеграция с системами CI/CD для автоматического тестирования баланса
- [ ] Поддержка распределенных симуляций

## 📄 Лицензия

Проект разработан для внутреннего использования в целях балансировки игр.

---

**Разработано для профессионального использования в геймдеве** 🎯