Calculators

The calculators() namespace turns raw build/research time into gem cost, applies boosts and potions, and runs Helper Hut and Forge-adjacent math: all built on the shared BuildTime type.

Namespaces

import { calculators } from 'clash-of-clans-data'

calculators().boost() // BuildBoostCalculator
calculators().gems() // GemsCalculator
calculators().helpers() // HelpersCalculator
calculators().potions() // PotionsCalculator
calculators().clockTower() // ClockTowerCalculator

Every calculator reads and returns a BuildTime:

interface BuildTime {
  days: number
  hours: number
  minutes: number
  seconds: number
}

Gems

calculators().gems() converts a remaining build or research time into its gem cost to finish instantly, using the game's tiered scale.

import { calculators } from 'clash-of-clans-data'

const remaining = { days: 1, hours: 0, minutes: 0, seconds: 0 }
const gemCost = calculators().gems().cost(remaining)

Boost

calculators().boost() applies Builder Boost / Research Boost tiers (10%, 15%, or 20%) to either a remaining time or a resource cost.

import { calculators, type BuildCostResource } from 'clash-of-clans-data'

const remaining = { days: 5, hours: 12, minutes: 0, seconds: 0 }
const boosted = calculators().boost().builderBoost(remaining, 20)

const cost = 5_000_000
const reducedCost = calculators().boost().builderBoostCost(cost, 'Gold', 20)

BoostTier is 10 | 15 | 20. BuildCostResource is 'Gold' | 'Elixir' | 'Dark Elixir'.

Potions & snacks

calculators().potions() applies the fixed time reduction from each time-boosting potion or snack.

import { calculators } from 'clash-of-clans-data'

const remaining = { days: 0, hours: 24, minutes: 0, seconds: 0 }
const afterBuilderPotion = calculators().potions().builderPotion(remaining)

Clock Tower

calculators().clockTower() calculates time saved from a Clock Tower activation or a Clock Tower Potion, at a given Clock Tower level.

import { calculators, type ClockTowerLevel } from 'clash-of-clans-data'

const remaining = { days: 1, hours: 0, minutes: 0, seconds: 0 }
const afterBoost = calculators().clockTower().boost(remaining, 8)
const afterPotion = calculators().clockTower().potion(remaining, 8)

ClockTowerLevel is 1 | 2 | ... | 10. See Builder Base buildings & leagues for the Clock Tower building data these calculations pair with.

Helper Hut helpers

calculators().helpers() runs the math for each of the four Helper Hut assistants: see Home Village buildings for their building data.

import { calculators } from 'clash-of-clans-data'

const helpers = calculators().helpers()

helpers.labAssistant(remainingResearch, 6) // BuildTime
helpers.buildersApprentice(remainingBuild, 4) // BuildTime
helpers.alchemist(1_000_000, 5) // AlchemistResult
helpers.prospector(1) // ProspectorResult

interface AlchemistResult {
  input: number
  base: number
  bonus: number
  total: number
}

interface ProspectorResult {
  shinyOre: number
  glowyOre: number
  starryOre: number
}

Next steps

• Home Village buildings: the Helper Hut buildings behind calculators().helpers()
• Builder Base buildings & leagues: the Clock Tower building
• Magic items: items with the same time-reduction effects as these calculators