Clash Max

The Scheduling Problem

Builder scheduling in Clash of Clans is a constrained parallel machine scheduling problem with discontinuous decision times. The key challenge:

You have B builders (parallel machines), each running one upgrade at a time. You can only start new upgrades when you are awake and checking the game. If a builder finishes at 3 AM, it idles until you wake up. The goal is to minimize this wasted idle time.

Algorithm Architecture

The scheduler uses a two-layer system:

Layer 1: Deterministic Simulation Engine

A forward-simulating event queue that models time progression:

1. Parse current in-progress upgrades from timer fields in the export. Initialize each builder with a busyUntil timestamp.
2. When a builder becomes free at time t:
   • If t falls inside the sleep window, the builder idles until wake time. This idle period is recorded.
   • Otherwise, the algorithm picks the best upgrade and starts it, creating a new busyUntil event.
3. Repeat until the planning horizon is reached (24h, 48h, etc.).

Layer 2: Candidate Scoring (Algorithm Selector)

At each decision point, the pickBestUpgrade function evaluates every candidate with a composite score:

compositeScore = strategyPriority + timingScore * weight

timingScore depends on the selected Scheduling Algorithm:

• Classic Sleep Heuristic: uses sleepFitScore to reward upgrades that cover sleep and penalize finishes deep in sleep.
• Practical Hybrid: uses exact induced idle impact as the primary signal (duration vs. duration+idle), with a small sleep-alignment tie-break.

Classic Sleep sleep-fit table (score range -1 to +1):

Finish Time	Score	Rationale
Before sleep starts	+0.3	Neutral — user is awake, can start next build
After sleep ends	+1.0	Excellent — covers the night, zero idle time
Early in sleep	-0.8	Worst — builder idles most of the night
Late in sleep (near wake)	-0.2	Moderate — short idle, could be worse

Practical Hybrid induced-idle concept:

idle = nextDecisionTime(end) - end
effectiveTime = duration + idle
utilization = duration / effectiveTime

Variant Search (GRASP + Destroy/Repair)

The app generates many candidate schedules (randomized greedy search), then optionally improves the best one using a local search step:

• GRASP-style sampling: generate many randomized schedules and keep the best.
• Destroy & Repair (LNS): remove a small segment around the worst idle block and re-simulate while keeping the rest fixed.
• The Schedule Variants progress bar shows when it is in the Optimizing (destroy & repair) phase.

Priority-Based Scoring

Every building and hero is classified into one of ten category buckets:

Bucket	Examples
TH Blockers	Any building/level required before the next Town Hall upgrade
Town Hall	The Town Hall upgrade itself
Attack Infrastructure	Laboratory, Clan Castle, Army Camps, Spell Factory, Workshop, Hero Hall
Offense	Barracks, Dark Barracks, Siege Barracks, Pet House
Heroes	Barbarian King, Archer Queen, Grand Warden, Royal Champion
Storages	Gold Storage, Elixir Storage, Dark Elixir Storage
Defense	Cannons, Archer Towers, Inferno, Eagle, Scattershot, etc.
Traps	Bombs, Spring Traps, Air Mines, Tornado Trap, etc.
Collectors	Gold Mine, Elixir Collector, Dark Elixir Drill
Other	Any building not covered above

The user arranges these buckets into tiers using the drag-and-drop Priority Editor. Three built-in presets are provided:

• Fastest TH: TH Blockers → Town Hall → Attack Infra → Storages → Offense → Heroes → Defense → Traps → Collectors → Other
• Offense First: TH Blockers → Attack Infra → Offense → Storages → Town Hall → Heroes → Defense → Traps → Collectors → Other
• Hybrid: TH Blockers → Town Hall → Attack Infra → Offense → Heroes → Storages → Defense → Traps → Collectors → Other

How Scoring Works

The tier position gives each candidate a rush order bonus — the dominant signal in scoring. Higher-tier buckets always outscore lower-tier buckets. Within the same tier, small tiebreaker bonuses differentiate candidates:

• TH blocker urgency: buildings that gate the next TH upgrade get a small boost
• Hero continuity: slight preference for continuing the hero with the most levels remaining
• Sleep-fit alignment: minor nudge toward upgrades whose durations align with sleep windows

These tiebreakers are intentionally small so the user’s tier list remains the primary decision driver.

Constraint System

• Storage Capacity: Upgrades whose cost exceeds your current storage capacity are automatically excluded. If high-priority upgrades are blocked, matching storage upgrades get a priority boost.
• TH Upgrade Gating: Town Hall upgrades require all unlock prerequisites (from static data) to be met. Optional buildings like Builder's Hut are excluded from gating.
• Merged Building Requirements: Merged defenses (Multi-Archer Tower, Ricochet Cannon, Multi-Gear Tower, Super Wizard Tower) must be placed before the next Town Hall upgrade, with source buildings at the required level.
• Hero Policy: Schedule all heroes, keep one or more available for war, or skip hero upgrades entirely.
• Lab Level Requirements: Research candidates are filtered by your current lab level, preventing impossible upgrades from being scheduled.
• Wiggle Room: A configurable buffer added to each decision point to account for late check-ins.

Lab Priority Presets

Four presets bias lab scheduling: Community (balanced war meta), Air (air-focused), Ground (ground-focused), and Farming (resource farming). Each maps specific troops/spells to priority bonuses.

Data Model

Export Parsing

The in-game export uses numeric IDs:

• Buildings: 1000xxx range (e.g., 1000001 = Town Hall, 1000007 = Laboratory)
• Troops: 4000xxx range (e.g., 4000005 = Balloon)
• Heroes: 28000xxx range (e.g., 28000000 = Barbarian King)
• Spells: 26000xxx range (e.g., 26000002 = Rage Spell)

When a timer field is present, lvl represents the target level being upgraded to, and timer is seconds remaining. Without timer, lvl is the current completed level.

Upgrade Costs & Times

The app attempts to fetch ClashKing's static_data.json at runtime for accurate, up-to-date costs and durations. This data is cached for 24 hours in localStorage. If unavailable (offline or CORS), the app falls back to embedded approximate data.

Game Rules Modeled

• Lab research during Lab upgrade: Since Dec 2022, research continues even while the Laboratory building is being upgraded.
• Hero upgrades consume builders: Heroes require a free builder and cannot be used while upgrading. The scheduler assigns them to builder slots.
• Walls are instant: Walls do not consume builder time. They are excluded from scheduling and tracked as resource sinks.
• Merged defenses: Multi-Archer Tower, Ricochet Cannon, and other merged buildings require source buildings at specific levels. The scheduler gates placement and tracks merge requirements as TH blockers.
• Builder Base (B.O.B rush): Models the 6th Builder unlock requirements — Builder Hall 9, Clock Tower 6, Star Lab 9, one troop to 18, heroes totaling 45, and gear-up prerequisites.
• Boost modifiers: Gold Pass and event speed boosts can be applied via the builder/research boost percentage inputs.

Limitations

• Upgrade durations are discrete; a "perfect fit" for the sleep window may not exist among available upgrades.
• Resource constraints may block the optimal choice. The scheduler does not model farming income — it reports deadlines, not predictions.
• Some timers/boosts cannot be detected from the export (Gold Pass boosts, active potions). Adjust manually via boost sliders.
• Building names are derived from embedded mappings that may not cover every new building or event-exclusive structure.

Open Source Data Attribution

Upgrade cost/time data is sourced from ClashKing's public CDN. Building name mappings are derived from community data repositories.