README.md

metadata

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

Установка

git clone <repository_url>
cd MergeBalanceTools
pip install gradio pandas pyyaml

Запуск

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 - Анализ данных

Пример использования

{
  "function": "mcp_run_simulation",
  "params": {
    "config_name_or_data": "test_balance_v1",
    "iteration_count": 200,
    "initial_energy": 10000,
    "return_detailed_results": true
  }
}

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

Структура цепочки merge-предметов

{
  "ChainId": "flowers_chain",
  "MergeItemId": "flower_seed_1", 
  "RequirementWeight": 100,
  "RewardDifficulty": 15
}

Конфигурация наград

{
  "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 для автоматического тестирования баланса
• Поддержка распределенных симуляций

📄 Лицензия

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

---

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