Merge Tactics — Deck Optimizer (Synergy Pairs)

A Python prototype inspired by Clash Royale-style deck building and auto-battler synergy systems.

The objective is to automatically build the strongest possible team (deck) by maximizing the number of activated traits - meaning traits that appear at least twice in a team.

The optimizer supports optional gameplay constraints such as:

• Locked cards (must be included)
• Banned cards (must be excluded)
• Maximum elixir budget
• Pre-activated starting traits

---

Project Overview

In synergy-based games, team strength often depends on activating multiple trait combinations.

This project models that logic and searches for the optimal team composition using:

• A trait activation system (threshold ≥ 2)
• A beam search strategy to efficiently explore combinations
• A scoring system prioritizing synergy breadth over raw power

---

Features

• Trait-based synergy activation
• Beam search optimization
• Optional constraints:
  • --locked
  • --banned
  • --max-elixir
  • --initial-traits
• Clean modular architecture
• CSV-based dataset (separated from code)

---

Installation

pip install -r requirements.txt

---

How to Run

Basic usage:

python -m src.cli

---

CLI Examples

Force a specific card into the team

python -m src.cli --locked "Knight"

Ban certain cards

python -m src.cli --banned "Wizard,Witch"

Start with pre-activated traits

python -m src.cli --initial-traits "Goblin,Clan"

Apply an elixir constraint

python -m src.cli --max-elixir 20

Combine constraints

python -m src.cli --locked "Knight" --banned "Wizard" --initial-traits "Goblin" --max-elixir 22

---

Example Output

=== Best Team ===
pairs>=2: 6
team: ['Knight', 'Archers', 'Goblins', 'Spear Goblins', 'Barbarians', 'Skeleton Dragons']
active traits: ['Noble', 'Clan', 'Goblin', 'Ranger', 'Juggernaut', 'Brawler']

---

Example Top Teams (from CSV Export)

Below is a preview of the top 5 teams generated by:

python -m src.cli --top-k 20 --export results/top_teams.csv

Rank	Activated Traits (pairs≥2)	Total Elixir	Team
1	6	15	Knight, Archers, Skeleton Dragons, Valkyrie, Prince, Giant Skeleton
2	6	16	Knight, Archers, Barbarians, Prince, Dart Goblin, Goblin Machine
3	6	16	Archers, Spear Goblins, Barbarians, Dart Goblin, Executioner, Mega Knight
4	6	17	Goblins, Spear Goblins, Musketeer, Prince, Giant Skeleton, Royal Ghost
5	6	17	Knight, Barbarians, Musketeer, Valkyrie, Executioner, Mega Knight

The full CSV export also includes:

• Raw score
• Trait counts per team
• Per-trait bonus activation
• Locked / banned card tracking

This allows further analysis in Excel, Power BI, or Python.

---

Scoring Logic

The scoring system follows a clear priority:

1. Maximize number of activated traits (≥2 occurrences)
2. Minimize total elixir cost (tie-break)
3. Base power is included for informational purposes

This encourages breadth-based synergy strategies, similar to auto-battler game mechanics.

---

Data Structure

Cards are defined in:

data/cards.csv

Required fields:

• card
• elixir
• base_power
• traits (semicolon-separated)

You can expand the card pool by simply editing the CSV file.

---

Exported CSV Structure

The exported CSV contains the following columns:

• rank
• score
• pairs2
• team
• team_size
• total_elixir
• trait_counts
• initial_trait_counts
• per_trait_bonus
• locked_cards
• banned_cards

This design enables advanced analysis and filtering outside the CLI environment.

---

Performance Notes

The beam search width (default: 2000) balances exploration quality and runtime.

Typical runtime for the default dataset (27 cards, team size 6): < 1 second on a standard laptop.

---

Project Structure

personal-optimizer-merge-tactics/
├── data/
│   └── cards.csv
├── src/
│   ├── models.py
│   ├── io_data.py
│   ├── scoring.py
│   ├── search.py
│   └── cli.py
├── requirements.txt
└── README.md

---

Technical Highlights

• Python 3
• Pandas / NumPy
• Custom beam search implementation
• Modular architecture
• CLI interface via argparse

---

Why This Project Matters

This project demonstrates:

• Combinatorial optimization
• Heuristic search design
• Clean code modularization
• Separation of data and logic
• CLI tool development
• Game mechanics modeling

It bridges algorithmic thinking with practical system design. It also reflects a data-oriented mindset: defining metrics, prioritizing optimization criteria, and exporting structured results for downstream analysis.

---

Project Status

Prototype - functional core complete.

Planned improvements:

• Improve export format (JSON-native fields)
• Add analytics summary on exported results
• Advanced trait thresholds (2 / 4 / 6 scaling)
• Performance benchmarking
• Unit tests
• Web interface or visualization layer

---

Author

Mathieu Alassoeur
Data Analyst | Business Intelligence