How ClashClock works

What ClashClock is, and what it is not

ClashClock keeps your Clash of Clans upgrade timers in one place, tells you when a builder is free, and plans the upgrades still ahead of you around the hours when you cannot play. It is a web app that runs in your browser. I built it, I run it, and I maintain its game data myself.

It is not connected to your game. It never sees your Supercell ID or password, and it cannot start, cancel or speed up an upgrade. Everything it knows about your village is text you paste in, figures you type in, or public information that the official game API returns for a player tag. You start every upgrade in the game yourself. ClashClock is an unofficial fan project and is not endorsed by Supercell.

A number travels through four parts before it reaches your screen:

1. The game data: the cost, time, level cap and requirements of every upgrade, from the game's own files.
2. The import: your export, and optionally the official API, turned into a village the app can calculate with.
3. The time and cost rules: what an upgrade really takes once the Gold Pass, helpers and potions count.
4. The planner: which upgrade goes to which worker, and when.

All four are plain TypeScript without user-interface code, and most of the project's roughly 1,600 automated tests are about them.

Where the numbers come from

The game's own files

Every cost, build time, level cap and requirement comes from the data files the game client itself downloads from Supercell's public asset server: compressed tables, one set per game version, addressed by a hash called the fingerprint. A build script turns them into one JSON file that ships with the app: roughly 600 entities (buildings, traps, walls, troops, spells, heroes, pets, equipment and more) and about 5,400 level rows, each with a cost, a resource, a time and the Town Hall it needs.

The files have conventions you only learn by checking them against the game. A building row describes the level it builds; a troop, spell, hero or pet row carries the cost and time of the next level but the requirements of its own. Hero, pet and equipment ids are not in the files and derive from a row's position, which I confirmed against real exports. Names in the app's five languages come from the game's own localisation files; pictures come from the wiki.

How the numbers are checked

Four checks guard the data. The timer check and the pinned-numbers test also run as automated tests on every push; data:validate and data:audit are scripts I run by hand when a game update lands, and the audit needs the network:

• data:validate compares every level with a community dataset built from the wiki. Where they differ, the game files win.
• data:audit compares numbers with tables that a community project extracts from the newest client. It fails on any missing entity or level and on any cost or time I cannot explain.
• data:timers checks every timer the app can show against a separate reference built from the current client's files (version 18.600) and independent tables. The audit of 5 October 2026 covered 3,906 timer records across 318 entities. No base duration needed changing; the bugs it found were in my calculations (helper work, Gold Pass previews), and I fixed those.
• The pinned-numbers test holds what a rebuild must never lose, because tests that read their expectations from the data stay green on stale data.

Overrides, and what “can be off after an update” means

The file set I build from dates from April 2026. Supercell has changed the game several times since, among them on 26 May, 16 June, 31 August and 8 October 2026, and those files do not know. A file called overrides.json carries the difference instead: 38 entities today, such as higher hero levels, new Supercharge tiers and Builder's Hut 8. Every override names its source, and where a second source exists I check the numbers against it; where the two disagree, the override says why. The build skips an override without a source and warns when a newer file set makes one redundant.

So “can be off right after a game update” means something specific: a new level, building or unit can be missing until I add it, and a cost the update changed can still show its old value. The game also gives itself away: the official API reports a maximum level for every unit, so the app can tell you when the game has more levels than it does.

How your village gets in

The export

The game can export your village as text. You paste it into ClashClock, which reads it on your device; the pasted text itself is never uploaded. The player tag in it is sent for the league and clan lookup, and with an account the village you build from it is synced; “What is stored, what is sent, and where” below has the details. How to export.

{ "tag": "#…", "timestamp": 1788969427,
  "buildings": [
    { "data": 1000008, "lvl": 9,  "cnt": 4 },       four Cannons at level 9, idle
    { "data": 1000021, "lvl": 12, "timer": 86400 }, one X-Bow at level 12, 86,400 s left
    …
  ],
  "helpers":   [ { "data": 93000000, "lvl": 8, "helper_cooldown": 49617 } ],
  "buildings2": [ … ]                                the Builder Base
}

• A row with a timer and no count is one instance in the middle of an upgrade. It finishes at the export's timestamp plus the timer, and ClashClock stores that absolute moment, so countdowns keep running. A row with a count stands for that many idle ones. Walls are counts per level; sections ending in 2 are the Builder Base.
• An id the game data does not know, or a timer longer than the level's known build time, is kept and reported, not dropped. That is how I find where my data or my reading of the export is wrong.

Two things the export does not spell out:

• Supercharge. The building keeps its regular maximum level and a separate field counts the tiers done. It reads 0 while the first tier runs, so a timer on that row belongs to the next tier.
• Gear-ups. A defence row with a gear-up flag and a timer is the Master Builder retooling it. My first version read it as an upgrade and showed a Cannon going from 7 to 8 on a two-day timer, though that level takes three hours.

What comes from where

What a second export does

Importing again lists what changed before anything is applied. The export is the truth for levels, counts and running upgrades, so a timer you set by hand that the export does not know is dropped and reported. Reminder switches, an upgrade's starting length, a Goblin flag, helpers you switched on by hand and a builder you added survive. So does your plan: done or running steps fall out of it, and when the import puts a building below the next level the plan held, the levels in between go back in front, because level 8 can never come before level 7.

What the official API adds

The API knows every hero, troop, spell, pet and owned piece of equipment, both hall levels, and your name, league and clan. It knows nothing of buildings, walls, helpers or running timers, so it cannot replace the export; it keeps levels current between two exports.

• It gives only English names, and the game files hold near-duplicates (“Dragon”, “Golden Dragon”), so a name is matched against units your village already has, and a new unit is added only if exactly one upgradable unit fits.
• While an upgrade runs the API still shows the old level, so a level reaching the target is how the app learns it is over. For an idle unit the API wins in both directions.
• Equipment you have not found is written as level 1 in the export, like a piece you own at level 1. Only the API, which lists owned pieces, can tell them apart, and the app acts on it only when the read was taken at least 30 minutes after the export, because the API lags the game.

With an account the app reads the API once a day when it opens; without one it fetches no levels.

How long an upgrade takes and what it costs

A step's base time and cost are the row for the level it reaches. Everything else is a correction on top, applied when the step starts.

The Gold Pass

The Builder Boost cuts the time and price of building and hero upgrades by the same percentage in both villages; the Research Boost does the same for the Laboratory and Pet House. The game rounds the result and ClashClock copies it: under 30 minutes the new time rounds up to the second, up to a day it goes down to a whole 10 minutes, and beyond a day it goes down to the hour. The price rounds up.

The percentages are not there from day one of a season. They are rewards on the season track, unlocked by points (the wiki's April 2026 table: Builder 10, 15 and 20 percent at 80, 640 and 1,060 points). Nothing I can read tells me your points, so the plan assumes 2,500 points over 30 days unless you enter the percentages your game shows, which then win for the rest of the season. In the Gold Pass sheet this assumption is the “Normal pace” switch: on, the plan follows the usual pace (10 percent within a day, 15 about a week in, 20 about two weeks in); off, you set the levels your game shows.

Helpers, potions and the Clock Tower

• Helpers. The Builder's Apprentice and Lab Assistant work for one hour; at level N they add N hours of work in it, and both share a 23-hour work day. At level 8, an Apprentice sent to a 259-hour upgrade makes it end 251 hours after it started.
• Potions and snacks. A Builder Potion runs home builders at 10 times speed for an hour; a Research or Pet Potion runs the Laboratory or Pet House at 24 times. Boosts of one kind never add up (a Builder Bite does nothing during a Builder Potion); boosts of different kinds do (a Study Soup adds to a Research Potion).
• Clock Tower. In the Builder Base it runs everything at 10 times for 14 to 32 minutes, by level, once every 22 hours. That cooldown is a number I could not confirm, and the code says so.

ClashClock stores each running upgrade's true finish time and moves it when you log a potion or helper. The plan counts work, not clock time: a ten-times hour removes nine hours of work wherever it falls. Events such as the Hammer Jam are in no file I can read, so you enter them with dates and effects; the app never assumes a date, because every Hammer Jam so far differed. An event multiplies with the Gold Pass (50 and 20 percent leave 40 percent of the time), as players report.

How the planner decides

The planner answers one question over and over: a worker is free, what should it start next?

Workers, lanes and steps

A step is one level of one thing: Cannon 5 to 6, a hero level, a new Army Camp. A lane is one worker: each builder (the Builder's Huts in your export, plus B.O.B.'s Hut once he lives there), the Laboratory and the Pet House; in the Builder Base the Master Builder, O.T.T.O. once his outpost stands and B.O.T.O., the builder bought with gems (you can add him by hand until an export shows his shack), and the Star Laboratory. Heroes use builders, walls cost no builder time, and a building's levels are built one after another even when two builders are free.

The loop

The planner is a simulation that only moves forward. Running upgrades occupy their lanes first; then it repeatedly takes the lane that frees up first and asks which steps could start at that moment. A step may start only when:

• the Town Hall it needs stands (one still upgrading does not count);
• the buildings it requires (Hero Hall, Laboratory, Pet House) stand at the right level, finished and not just started;
• the previous level of the same building is done;
• your storages can hold its price: the game refuses an upgrade they cannot hold, so the planner waits for the storage upgrade that makes room, counted from when it is done, or pulls one forward;
• for a Home Village hero, no Clan War League is running;
• you are online, because a step only starts in online time.

Among the steps that pass, the strategy picks one, the worker is busy until it finishes (boosts counted), and the loop goes on until four years or 6,000 steps are planned. The base scheduler chooses one step at a time. Max additionally compares several complete schedules with earlier Town Hall starts, prioritizing less builder idle time and then earlier completion of leftover work. This is a bounded search, not a guarantee of the globally best plan. Potion search and Own plan also compare alternatives. The forecasts run extra plans too, for example the gem comparison and the Town Hall and Max dates, but only to work out a date or what a choice would change, not to pick your steps. Being greedy is a limit, and also why every decision can be explained: the scheduler records why it chose each step, and the step sheet names what a late start waited for. It is deterministic too, with no randomness and no clock reading, and a test pins a hash of a whole plan so a change in output has to be deliberate. The plan is recalculated every minute and after every edit, in a background worker.

Your offline hours, and what idle means

You enter the times you cannot open the game, as daily, weekly or one-off windows in your time zone. The planner never starts a step inside them, so a builder that frees up at 01:00 waits until you are back. That wait is what the app calls idle: worker time lost because you were away, and nothing else. A worker waiting for a prerequisite is not idle; the step sheet says what it waited for. The figure covers a fixed seven days, so it means the same in every village. It also moves with the hour the plan starts, because that decides where upgrades end relative to your nights. On the sample village (a real Town Hall 9 export, four builders, asleep 23:00 to 06:00, at work 08:00 to 17:00 on weekdays, time zone Europe/Zurich), a plan started at the moment of the export leaves about 13 of the next week's 672 builder hours idle, in Rush and in Max alike. Started at other hours of the same week, the same plans leave anywhere from about 5 to 55 hours in Rush and 1 to 26 in Max. The idle figure on the Plan tab is higher, because it also counts the Laboratory and the Pet House: 15 hours in Rush and 29 in Max at that same moment.

How a step is scored

importance = weight[category] × keyBuilding[name] × valueOfLevel × 0.2 if a Supercharge tier
priority   = importance ÷ √( (hours + 0.25) × (cost in millions + 0.05) )
choice     = priority × duration ÷ (duration + idle the step would leave)

The weight comes from the strategy. Key-building multipliers order buildings within a category: Army Camps, Clan Castle, Laboratory and Pet House ×3 in every Home Village strategy; Inferno Tower, Eagle Artillery, Scattershot and Monolith ×2; X-Bow, Spell Tower and a few others 1.3 to 1.8. The third line is where your offline hours enter: a step that would hand its builder back at 02:00 is discounted by that idle time, so a long upgrade spanning the night beats a short one ending in the middle of it.

The strategies

Rush weighs heroes 3, troops, spells and army buildings 2.5, defences 0.2; Max weighs heroes 2.2, troops and spells 1.8, army buildings 1.6, defences 1. The table below lists the weights of the main categories. Rush raises the key defences, so an Inferno Tower scores 0.2 × 4.5 = 0.9 against 2.5 × 3 = 7.5 for an Army Camp.

Rush chooses in this order, and the first rule with an answer wins:

1. A step you pulled forward, or a hero goal.
2. A storage upgrade, when a step is priced above what the storages hold.
3. The Town Hall, the moment the game allows it.
4. What the next Town Hall waits for. Among work that fits the remaining builder time, Laboratory and Pet House upgrades needed for your top three priorities or to prevent a research gap come before preparations for later halls.
5. A gap filler: the most important step by weight that a builder can finish before the Town Hall path needs it again, or that ends inside the current Town Hall phase while enough other builders are free. Collectors, mines and drills are placed when a hall opens a plot and never upgraded.

Max works in importance bands:

1. A plot a hall has opened comes first: a new building adds more strength per builder hour than any upgrade.
2. Otherwise the highest importance band wins, a band being the importance rounded to the nearest quarter; within a band, the third line decides. Without bands, a Cannon 15 to 16 would beat a Cannon 16 to 17 over a difference in the third decimal, and the plan would follow that noise instead of doing the quicker upgrade first.
3. If the best step of the leading band would leave its builder idle for more than an hour, the most important step that would not takes the slot.

What the game demands before a Town Hall

A Town Hall does not simply go up when a builder is free. The game wants everything the current hall opened to stand first: every plot it allows, the Hero Hall at the level the new heroes need and, at higher halls, specific upgrades. All of it must be finished, not started. The planner applies this in every strategy, and for a Town Hall you pin it adds what is missing. In the Rush plan for the sample village the Town Hall 10 upgrade starts on the minute the required Hero Hall upgrade is done. Plots and the Hero Hall level come from the game data; the few rules the files do not state (the level-21 towers and an Eagle Artillery at 7 before Town Hall 17, an Inferno Artillery at 5 before Town Hall 18) I typed in from community tables, and a game update can catch me out there.

Research, pets, heroes, helpers and potions

Research and pets mostly bypass the formula. In Rush and Max the Laboratory and Pet House follow your own priority list, then a preset I wrote for your Town Hall bracket; only what neither covers falls back to the formula. The preset is an editorial recommendation, not a measured popularity ranking; I found no reliable dataset of troop usage by Town Hall.

For a hero you can set a goal, and with a continuous chain the planner keeps one builder on that hero until the target is reached. By default no Home Village hero upgrade is placed inside the Clan War League, since a hero in the middle of an upgrade cannot fight. ClashClock models the league as starting on the 1st of each month at 08:00 UTC and lasting 11 days. That calendar is a rule I typed in, not something in the game files, so a month Supercell shifts would put the band in the wrong place.

Each work helper is sent once a day to the running upgrade whose shortening hands its builder back earliest in online time. Potions are placed by you or by a search that tries a handful of moments, plans the days after each and keeps the one that costs the least idle time per potion.

Own plan

In Own plan you choose. Your steps run in your order, a builder you tied a list to takes it strictly in order, and nothing is added: no research, no pet upgrades, no Goblin hired unasked, nothing that waits for loot. The one exception is what the game demands before a Town Hall you added.

A drop is refused in only two cases: it would make a step wait for itself (level 7 before level 6, or a looping list), or no storage upgrade in your plan could ever hold its price. Where a step is not tied to a builder, the planner runs twice, once in your order and once with those steps grouped by building, the longest first, and keeps the one that places more of your steps and leaves less builder time idle. That compares two heuristics, not every plan, and the code says so.

The 6th builder

B.O.B. becomes a sixth builder in your Home Village once B.O.B Control in the Builder Base is fully upgraded. ClashClock checks seven requirements: gear-ups for the Cannon, Archer Tower and Mortar at home; any Builder Base troop at level 18; any Builder Base defence at level 9; Battle Machine and Battle Copter at 45 levels combined; and B.O.B Control at level 5. The 6th builder guide lists them with their costs and the order that works; this is what ClashClock does with them.

• “Any” means any: a troop or defence you already have at that level answers its requirement. Otherwise the troop is your pick, the Baby Dragon by default (my choice, because it attacks well all the way up), and the defence is the one that gets there fastest.
• For the heroes the planner tries every split of the 45 levels between the Battle Machine and the Battle Copter and takes the one with the least upgrade time, then the lowest cost, building the Copter's altar first if it is missing.
• The path follows the fixed order written out in that guide. Before each Builder Base step it adds a Builder Hall level or a storage when one is needed, and Clock Tower levels only when the time a level costs is earned back before the path ends.
• A gear-up is paid in Home Village Gold but done by the Master Builder, so it occupies a Builder Base builder: 2, 7 and 14 days, 10 million Gold in all. The export shows a running gear-up and, as far as I can infer, a finished one; if neither shows, you tick it off by hand. B.O.B Control has no build time in the game files, so the plan treats it as a gate, not as work.

What is stored, what is sent, and where

On your device. Your villages, plans and settings live in your browser's IndexedDB, with a few small entries in localStorage and sessionStorage (for example your theme, language, sync revision, sign-in token and which reminder was shown). The service worker caches the app and the game images so it opens offline. ClashClock itself sets no cookies; if that ever changes, the privacy policy is where it will say so. The site is a static export served by Cloudflare, and the planner runs in your browser, so your village is never sent to a server to be planned.

An account is optional. It uses Supabase for sign-in and for one database row holding your whole app state as one document, which row level security restricts to your own account. Every write carries the revision it last saw. If another device saved first, the cloud copy stays as it is, this device takes that newer state and a message says so; an edit you made here in the meantime is lost. The first sign-in on a device asks which side to keep whenever both hold villages. A device that has synced before takes a newer cloud state without asking, so edits made on it while signed out are replaced.

The game API. Supercell's API only answers requests from IP addresses named when the key was created, and neither Cloudflare nor Supabase can promise one, so requests go through a RoyaleAPI proxy. A Supabase function holds the key; the browser sends a player tag and its session and gets back a trimmed document of levels, name, league and clan. Each tag is read at most once every ten hours, whoever asks, and calls are logged (account id, tag, time) for a week to enforce limits. Without an account, a security check (Cloudflare Turnstile) lets a device create an anonymous guest session, which can look up league and clan for up to five tags and never receives level lists.

Reminders. With the app open they come from the app itself. For a closed app there is Web Push: the browser writes the reminders due in the next seven days to a queue, and a function sends them when due. Each queued reminder holds ready-made text that names the upgrade, its level and the village (for example “Cannon level 9 is done”), an event key, the kind of reminder and the time. When one is due, that same text goes to your browser through your browser vendor's push service, encrypted for your browser as Web Push requires. Reminders go out 45 seconds early, which covers the function's once-a-minute check and the push service's own delay. Without an account, switching push on first creates an anonymous device ID after a security check. On iPhone and iPad push needs the app installed on the home screen. Switching push off deletes the subscription and everything unsent.

Accuracy, known limits and how to report a wrong number

ClashClock is accurate where it copies the game and approximate where it models behaviour.

Limits I know about

• The export is a snapshot. A potion, helper, book, hammer or gem finish used after exporting is invisible to ClashClock until you log it or import again. The export's own boosts and helper-timer fields are not decoded, because I could not establish what the raw timer means under every active boost, so an export taken during a boost can mislead; one taken after it ends avoids the problem.
• Account-specific boosts are not in the export. The Re-Engagement Boost can be switched on as an event, using what players report (half time and cost for 14 days, Home Village only); login bonuses are not modelled.
• A time-only plan assumes the loot is there. On the sample village a Rush plan starts Town Hall 18 on day 176, and its four years of upgrades cost 5.5 billion Gold: what the builders could do with unlimited loot, not a forecast. The optional “plan by resources” mode holds steps until they can be paid for, from farming figures that are my estimates.
• Progress percentages count levels, not time. A hero level counts as much as a Cannon level, and walls are left out.
• New content can arrive before any public source has its numbers. The Portal Pendant was in real exports under an id nobody had named. I entered it under a guess and corrected it two days later, when an export showed the real one.

When a timer disagrees with the game

Open the upgrade and use “Adjust remaining time”: enter what the game shows, and it also replaces a wrongly set boost. If a timer keeps drifting, check what you used since the export (potions, snacks, helpers, books) and whether the Gold Pass percentages match your game, then import again once the boost has run out. The chapter on fixing a wrong timer has the details.

To report a wrong number, use the contact form on Support with the page, what you expected and what happened. For a timer, send the upgrade's name, its current and next level, which village, and every boost that was active: the Gold Pass percentage, a potion, a helper, a returning-player bonus. Never send a password.