How Clash Max Works

The scheduling model

Home Village scheduling is a forward event simulation, not a backward solver. Each builder lane starts with a busyUntil timestamp seeded from the export. When the next builder frees up, the scheduler advances to the next real action time, filters the legal choices at that moment, assigns one, and then enqueues the follow-up level for that same building if another step exists.

• Sleep, check interval, and wiggle room all shift the decision time before scoring begins.
• Hero policy is enforced at pick time by counting how many hero upgrades are already active.
• The lab runs as a separate lane in parallel, so builder choices do not directly block research.

Home-candidate scoring

Each building candidate starts with a small within-bucket priority based on how far below its current Town Hall cap it is, with extra nudges for early levels and army or hero categories. The larger signal is the rush bucket bonus.

composite = base priority + rush bucket bonus + timing heuristic + special unlock bonuses

• One rush-order step is worth 90 points, so bucket order dominates ordinary tiebreakers.
• If buckets share a custom tier, they inherit the same best bonus from that tier.
• Once Town Hall is legal, the current build adds a very large ready-now bonus so the hall can jump to the top when the preset allows it.
• Current TH blockers, next-TH blockers, merge-source prep, hero continuity, and manual auto-priority targets all add smaller targeted bonuses on top.

Timing heuristic

Beam search still needs a local timing signal when it scores individual candidates. Clash Max uses a utilization-first heuristic that prefers upgrades which keep builders working continuously, then blends in sleep alignment as a smaller tiebreak.

utilization = duration / (duration + idle until next decision)

• The timing score blends about 80% utilization and 20% sleep-fit, then clamps the result to -1..1.
• That timing value is deliberately small compared with rush-order steps, so your preset still drives the overall direction.
• The effect is strongest when two legal upgrades live in the same bucket and one lands much closer to your next real check-in.

Constraint and unblock logic

The picker does more than ask whether an upgrade is legal right now. It also carries forward Town Hall requirements, merged-building source reservations, storage-capacity timelines, Hero Hall and Pet House gates, and lab-production requirements.

• Storage upgrades can inherit priority from a blocked high-priority building or hero if that storage is the real reason the better move cannot start yet.
• Laboratory upgrades can inherit priority from blocked tier-1 research if the missing lab level is what unlocks it.
• Research also respects production-building unlocks like Barracks, Dark Barracks, Spell Factory, and Workshop, not just TH and lab level.

Lab-lane logic

The lab uses four tiers, either from the preset or from manual overrides. The scheduler first narrows to the best available tier, then uses within-tier priority and timing to decide which research starts next.

within a tier: priority * 1000 + timing * 5

• That multiplier means tier and within-tier order stay dominant; timing is only a tiebreaker.
• The lab can take a temporary filler job only if it does not delay a more important research choice past the allowed filler window.
• The unlock check is based on the next real decision time, not just raw resource availability, so the lab respects the same sleep and check timing model as builders.

Variant generation

Every run starts with a deterministic baseline plan, then beam search keeps several promising early branches alive instead of collapsing immediately onto one greedy route.

• Each beam pass traces the early builder decisions, preserves several semantically different paths, and then completes each surviving prefix into a full schedule.
• Variants are deduplicated by a schedule fingerprint built from the non-existing builder and research tasks actually placed into the timeline.
• Generate More Plans adds another beam pass so you can explore a wider set of early-path alternatives without rerunning the entire planner from scratch.
• Heavy generation runs in a Web Worker so the UI can keep rendering while plans are being explored.

Refinement

Refine Selected Plan does not blindly rewrite the whole schedule. It targets a selected plan, destroys a small set of fixed decisions, and reruns only around those decisions to search for tighter timing.

• The pass looks at visible idle blocks, ignores pure no_candidates dead ends, and picks from the worst idle pool first.
• It destroys a small run of nearby builder decisions on the affected lane, keeps the rest of the plan fixed, and resimulates just that local region with a new seed.
• The number of destroyed decisions and total rounds scales with horizon length, so short horizons get a tighter local search than very long ones.

How Home variants are ranked

Ranking is not just builder efficiency. The current build first measures whether a plan covers more of the important buckets inside the selected horizon, then looks at how early those buckets begin.

bucket contribution = bucket weight * hours until first start

• Missing rush buckets are treated as if they started after a penalty window beyond the horizon, not as zero.
• Lab tiers are scored similarly with weights 6 / 4 / 2 / 1 for tiers 1 / 2 / 3 / 4.
• There are small early-start bonuses for touching top builder buckets in the first 48 hours and top lab work in the first 24 hours.
• Final Home ordering is: coverage first, then objective timing, then lab timing, then efficiency, idle time, and total scheduled work.

Builder Base technical differences

Builder Base uses a separate engine. In B.O.B. rush mode, the candidate pool is intentionally narrowed to milestone work, and the schedule can be rerun up to four passes so Clock Tower boost windows settle into a stable pattern.

• Clock Tower timing is modeled directly in task end times, not bolted on as a cosmetic note.
• B.O.B completion is computed from Builder Hall, Clock Tower, Star Lab, the configured rush troop, gear-up milestones, hero total, and the defense-to-9 requirement.
• Builder Base variants rank by earliest projected completion first; if none finish, the build falls back to milestone gaps, objective score, efficiency, and idle time.

Parser and data model notes

The export parser expands counted buildings into individual instances, turns active timers into seeded in-progress tasks, and keeps the game export semantics intact.

• When timer exists, lvl is the current completed level and the active step is lvl + 1.
• Walls are recognized in the import but excluded from timed builder scheduling because they do not occupy a builder lane.
• Canonical upgrade rows come from the local ClashKing mirror first with remote fallback second, while storage capacities still come from validated manual tables because ClashKing does not expose them.
• Research rows can use the checked-in research wiki source when that produces cleaner cost, time, and requirement mapping.