Skip to content

Guides

Every service hangs off the client, built when the client is: there is nothing to wire up. Each guide below covers one of them, or one of the parts that sit beside them.

client.alliance     client.castle      client.army       client.attack
client.commanders   client.equipment   client.skills     client.spy
client.map          client.movements   client.messages   client.player
client.defense      client.ranking     client.events     client.rewards

Services

  • Alliance

    Chat, help requests, applications, ranks and the treasury.

  • Messages

    The mailbox, reading and sending mail, battle reports.

  • Castle

    Castles, resources, buildings, the construction queue and tax.

  • Defense

    Reading and setting a castle's keep, wall and moat.

  • Army

    Units, recruitment and the hospital.

  • Commanders

    Commanders and castellans, and renaming them.

  • Skills and generals

    Generals, their abilities, and the skill trees.

  • Equipment

    The equipment inventory, equipping and unequipping.

  • Attack

    Sending an attack with waves you build yourself, and attack presets.

  • Filling waves

    Waves filled from a target's coordinates, the way the game does it.

  • Spy

    Spy missions planned for risk, and their reports.

  • Map scanning

    Kingdom scans and cheap re-scans.

  • Events

    The running events and their scoreboards.

  • Daily rewards

    The login and startup bonuses, lost and found, the activity chest, the weekly honour reward and patch note rewards.

The smaller services have no guide of their own; their API pages list every call:

  • client.player: get_player_info(player_id), get_player_details_bulk(player_ids) and search_player_by_name(name).
  • client.ranking: get_highscore(list_type, search_value) and the event leaderboards, get_ranking_list, get_own_ranking_page, get_ranking_window and search_leaderboard.
  • client.events: refresh(), get_active_events() with the events' in-game titles, get_league_id(event_id) for the leaderboards, get_scores(event) and get_own_points(event) for your own rank and points; the running events and their scoreboards have a guide.

Spending rubies

No call spends rubies unless you pass spend_rubies=True, the one name for that consent everywhere. Without it a call that would spend them raises ValueError (PremiumCommanderCostError for the premium commander) before anything is sent. Where the price can be known, from game data or state, only a call that costs rubies needs the flag; where it cannot, the call always does.

Rubies are spent on Calls Needs the flag
A ruby price of the item castle.build, upgrade_building, upgrade_defense, army.produce_units, heal_units when the game data prices it in rubies
Missing resources castle.build, upgrade_building, upgrade_defense, repair_building, army.produce_units with the flag they are paid with rubies; without it never
Finishing at once castle.finish_construction over 240 seconds left, or a time left it cannot work out
castle.repair_all, army.skip_heal, double_production_slot always
army.heal_all a price above 0
Travel castle.send_resources, send_support, send_troops, attack.send_attack, the client.spy sends a horse that costs rubies (not paid with feathers), any slowdown, the premium commander when none is free
The rest castle.buy_expansion, rename, start_tax, player.start_research, alliance.donate a premium expansion; a rename with no premium account; tax types 5 and 6; a ruby research; donated rubies

Pricing reads the game data, loaded on first use; the call raises GameDataNotLoadedError when it cannot be loaded. Minute skips are items, not rubies, and need no flag.

Game state and data

  • State and freshness

    What client.state holds, and how old it is.

  • Reacting to movements

    Callbacks for incoming attacks, arrivals, recalls and removals.

  • Game data

    Units, buildings, researches, quests and more, as typed tables keyed by their ids.

  • Generated ids

    Game-data ids as enums, for autocomplete.

  • Game texts

    The game's own texts and error messages, in any language.

Beyond one client