A comprehensive text-based MMA promotion management and fight simulation game. Build your promotion, sign fighters, organize events, and watch realistic fights unfold using advanced AI-driven combat simulation.
# Clone the repository
git clone <repository-url>
cd MMASimulator
# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the package and dependencies
pip install -e ".[dev]"# Start the MMA Simulator CLI
mmasim
# Or run specific commands directly
mmasim promotion create "My Fight Club" --budget 500000 --difficulty normal
mmasim roster sign --name "John Fighter" --weight-class "Lightweight" --salary 15000
mmasim events create "Fight Night 1" --venue "Local Arena" --capacity 5000
mmasim events run "Fight Night 1"from src.mmasim.models.promotion import Promotion
from src.mmasim.models.fighter import Fighter, FighterStats
from src.mmasim.services.fight_engine import FightEngine
from src.mmasim.models.fight import Fight
from src.mmasim.models.ruleset import Ruleset
# Create a promotion
promotion = Promotion(
id="my-promotion",
name="Elite Fighting Championship",
budget=1000000,
prestige=60,
difficulty="normal"
)
# Create fighters
fighter_a = Fighter(
id="fighter-1",
name="Thunder Johnson",
age=28,
weight_class="Lightweight",
skill_level=75,
marketability=70,
stats=FighterStats(
striking_power=80,
striking_accuracy=75,
cardio=85,
fight_iq=70
# ... other stats
)
)
fighter_b = Fighter(
id="fighter-2",
name="Lightning Smith",
age=26,
weight_class="Lightweight",
skill_level=73,
marketability=65,
stats=FighterStats(
striking_power=70,
takedown_offense=85,
submission_offense=80
# ... other stats
)
)
# Simulate a fight
engine = FightEngine()
fight = Fight(
id="main-event",
fighter_a_id=fighter_a.id,
fighter_b_id=fighter_b.id
)
ruleset = Ruleset(
name="Standard MMA Rules",
rounds=3,
round_duration_minutes=5,
weight_classes=["Lightweight"],
scoring_system="10-point-must"
)
result = engine.simulate_fight(fighter_a, fighter_b, fight, ruleset)
print(f"Winner: {result['winner']}")
print(f"Method: {result['method']}")
print(f"Round: {result['round']}")- Realistic Fight Engine: Advanced combat simulation with multiple fighting styles
- Comprehensive Fighter Stats: 10+ attributes covering striking, grappling, cardio, and mental aspects
- Multiple Victory Methods: KO, TKO, Submission, Decision outcomes
- Flexible Rulesets: Configurable rounds, scoring systems, and weight classes
- Financial System: Revenue from ticket sales, broadcasts, sponsorships, merchandise
- Roster Management: Sign/release fighters, manage contracts and salaries
- Event Planning: Create events, book fights, manage venues
- Prestige System: Build your promotion's reputation through successful events
- AI Matchmaker: Intelligent fight booking with multiple strategies (entertainment, rankings, revenue)
- Training System: Develop fighters through structured training camps and weekly plans
- Economic Analysis: Detailed financial reporting and growth forecasting
- Save/Load System: Persistent game state with JSON serialization
- Fight Analytics: Detailed breakdowns of fight outcomes and performance
- Financial Reports: Revenue, expenses, profit margins, and ROI analysis
- Training Progress: Track fighter development and attribute improvements
- Career Statistics: Comprehensive fighter and promotion histories
The simulator follows a clean, modular architecture:
src/mmasim/
├── models/ # Core data models (Fighter, Promotion, Event, Fight)
├── services/ # Business logic (FightEngine, EventsService, RosterService)
├── cli/ # Command-line interface
└── lib/ # Integration libraries (AI, Economy, Training, Persistence)
- Models: Data structures for fighters, promotions, events, and fights
- Fight Engine: Core simulation engine with realistic combat mechanics
- Services: Business logic for managing promotions, rosters, and events
- Integration Libraries: Advanced features like AI matchmaking and economic analysis
# Run all tests
pytest
# Run specific test categories
pytest tests/contract/ # Contract tests (core functionality)
pytest tests/unit/ # Unit tests (individual components)
pytest tests/integration/ # Integration tests (system interactions)
pytest tests/perf/ # Performance tests (speed requirements)
# Run with coverage
pytest --cov=src/mmasim --cov-report=html# Install development dependencies
pip install -e ".[dev]"
# Run linting
ruff check src/ tests/
black --check src/ tests/
# Run type checking (if using mypy)
mypy src/- Follow the MMA Simulator Constitution (see
specs/constitution.md) - Write tests first (TDD approach)
- Ensure all contract tests pass
- Maintain performance requirements (fights < 50ms, events < 1s)
- Update documentation for new features
The simulator is designed for speed:
- Fight Simulation: < 50ms per fight
- Event Processing: < 1s for typical events
- Batch Operations: Optimized for large tournaments and seasons
- Memory Efficient: Handles extensive simulations without memory leaks
Start with a small budget and build your promotion from the ground up:
- Sign unknown fighters and develop them
- Host small venue events initially
- Gradually build prestige and expand to larger venues
- Compete with AI promotions for top talent
Start with unlimited resources to create your dream promotion:
- Sign any fighters you want
- Host mega-events immediately
- Focus on creating epic matchups
- Experiment with different strategies
Run single-elimination or round-robin tournaments:
- Bracket-style competitions
- Grand Prix formats
- Custom tournament rules
- Automated bracket management
- Training Camps: 4-12 week structured development programs
- Attribute Growth: Improve striking, grappling, cardio, and mental stats
- Skill Specialization: Develop unique fighting styles
- Career Arcs: Fighters peak and decline realistically
- Prestige Levels: Unlock better venues and broadcast deals
- Financial Milestones: Reinvest profits into better facilities
- Market Expansion: Grow from local to regional to national promotion
- Legacy Building: Create memorable moments and legendary fighters
This project follows the MMA Simulator Constitution v1.0.0 emphasizing:
- Fairness & Transparency: Simulation algorithms are deterministic and explainable
- Deterministic Reproducibility: Same inputs always produce same outputs
- Extensibility: Modular design supports custom rules and modifications
- Player Agency: Players control key decisions with meaningful consequences
- Reliability: Comprehensive testing ensures stable, predictable behavior
- Constitution:
specs/constitution.md- Core principles and design philosophy - Specification:
specs/spec.md- Detailed feature requirements - Implementation Plan:
specs/plan.md- Technical roadmap and architecture - Task List:
specs/tasks.md- Development task breakdown - API Documentation: Generated from code comments
Current Version: 1.0.0 - Complete Implementation
✅ Completed Features:
- Complete project setup and configuration
- All core models (Fighter, Promotion, Event, Fight, Ruleset)
- Full business logic services (FightEngine, EventsService, RosterService, PromotionService)
- Advanced integration libraries (AI Matchmaker, Economy Calculator, Training Planner)
- Comprehensive CLI interface
- Complete test suite (17/17 contract tests passing)
- Performance optimizations
- Documentation and examples
Next Steps:
- Community feedback and feature requests
- Additional fighting styles and techniques
- Tournament bracket visualizations
- Web interface for enhanced user experience
- Multiplayer promotion competition
[Add your license information here]
We welcome contributions! Please read the Constitution and implementation guidelines before submitting pull requests.
Create legendary fighters, build epic promotions, and simulate the fights of your dreams!