// Payloads exchanged with the server. Every number in here is computed server-side; // the client only projects resources and countdowns forward from the timestamps. export type Resource = 'wood' | 'clay' | 'iron' | 'food' export type Resources = Record export type Cost = Record, number> export type BuildingType = | 'headquarters' | 'storage' | 'farm' | 'timber_camp' | 'clay_pit' | 'iron_mine' | 'hiding_place' | 'wall' | 'rally_point' | 'watchtower' | 'barracks' | 'stable' | 'workshop' | 'academy' export type UnitType = | 'spear' | 'sword' | 'archer' | 'scout' | 'light_cavalry' | 'heavy_cavalry' | 'ram' | 'catapult' | 'nobleman' /** Units by type; missing types mean none. */ export type Units = Partial> export type MovementType = 'attack' | 'support' | 'return' export type TravelMode = 'sneaky' | 'cautious' | 'normal' | 'fast' | 'forced' /** Why the server refuses an offer. The client shows `village.blocked.`; no_space means not enough free building space. */ export type BlockedReason = 'max_per_village' | 'no_space' | 'max_level' | 'requires' export interface AuthUser { id: number name: string email: string } /** `POST auth/login` and `POST auth/register`. */ export interface AuthResult { token: string user: AuthUser } /** Where a new village starts: anywhere on the frontier, or in one quarter of the map. */ export type StartDirection = 'random' | 'nw' | 'ne' | 'sw' | 'se' /** One row of `world.index`. */ export interface WorldSummary { id: number name: string slug: string speed: number village_id: number | null } /** `village.show`, and the reply to every `village.*` mutation. */ export type VillageRole = 'resources' | 'military' /** * What fills the space gives a village its role: one kind of building taking at least * `share` of the space both kinds take, and at least `min_space`. */ export interface Specialisation { role: VillageRole | null /** Space the standing buildings of each role take. */ space: Record share: number min_space: number /** Bonuses as shares: production (camps' output), recruit_speed, defense. */ roles: { role: VillageRole; buildings: BuildingType[]; bonuses: Partial> }[] } export interface VillageState { id: number world_id: number name: string x: number y: number /** Map continent, e.g. K55 for 0|0 to 99|99. */ continent: string /** Sum of the buildings' level points, as shown on the map. */ points: number /** Building space: what buildings and queued new buildings take, out of the village maximum. */ space: { used: number; max: number } specialisation: Specialisation /** Amounts stored at `resources_at`. */ resources: Resources resources_at: string /** Net change per hour. Food is farm output minus upkeep, so it can be negative. */ rates: Resources storage_cap: number population: Population /** Villagers drafted as militia: they eat but don't work until `until`. */ levy: Levy starvation: Starvation /** Own units standing in the village. */ troops: Partial> /** One entry per building that trains units, in building order. */ military: MilitaryBuilding[] /** Own groups leaving from or coming home to this village, and spotted groups coming here; by arrival. */ movements: Movement[] support: { /** Support from other villages standing here, by home village. */ here: SupportGroup[] /** This village's troops standing in other villages, by host. */ away: SupportGroup[] } rally: RallyInfo /** The player's unread reports on this world. */ unread_reports: number /** 0..100; noblemen lower it, at 0 the village changes hands. */ loyalty: number conquest: Conquest /** The player's villages in this world, by id: the switcher. */ villages: { id: number; name: string; x: number; y: number; points: number }[] /** Quest book badge: lines with a completed quest to claim, level rewards to collect. */ quests: { claimable: number; rewards: number } builders: number buildings: Building[] queue: BuildOrder[] buildable: BuildOption[] /** Lets the client correct for its own clock being off. */ server_time: string } /** A village as movements and reports refer to it; player null for barbarians. */ export interface VillageRef { id: number name: string x: number y: number player: { id: number; name: string } | null } /** A group under way. Groups of other players show no units, mode or send time. */ export interface Movement { id: number type: MovementType /** out: an own command leaving here; home: own troops coming back here; in: coming here. */ direction: 'out' | 'in' | 'home' mode: TravelMode | null from: VillageRef to: VillageRef units: Units | null /** Loot on a return trip. */ cargo: Cost | null sent_at: string | null arrives_at: string /** Until when the command can still be called back; null when it can't. */ cancel_until: string | null /** Raiders from a barbarian camp: no player sent them. */ raid: boolean /** While raiders still gather at their camp: when they march. */ marches_at: string | null } export interface SupportGroup { village: VillageRef units: Units } export interface RallyInfo { /** Nothing can be sent without a rally point. */ has_rally_point: boolean /** speed multiplies the pace; visibility is the radius in fields the group is seen in (0: only on arrival). */ modes: { mode: TravelMode; speed: number; visibility: number }[] default_mode: TravelMode /** Fields around the village within which incoming groups are spotted. */ detection: number /** Seconds after sending during which a command can be called back. */ cancel_window: number /** While set, players can't attack this player, and this player can only attack barbarians. */ protected_until: string | null } /** `rally.preview`: what the send form shows before sending. */ export interface MarchPlan { x: number y: number /** The village on that field, or null for an empty one. */ target: VillageRef | null mode: TravelMode distance: number /** Travel time; null without units or for the own field. */ seconds: number | null } export type ReportType = 'attack' | 'defense' | 'support' export interface BattleSide { village: VillageRef /** By unit; defenders may include `militia`. null where an attacker without survivors learned nothing. */ units: Record | null lost: Record | null } export interface BattleReport { /** Whether the attacker won. */ won: boolean /** Percent, between −25 and 25 by default. */ luck: number /** Percent. */ morale: number night: boolean attacker: BattleSide defender: BattleSide wall: { before: number; after: number } | null building: { type: BuildingType; before: number; after: number } | null loot: Cost capacity: number /** Noblemen survived a won attack: loyalty before and after, and whether the village changed hands. */ loyalty?: { before: number; after: number; conquered: boolean } | null /** Raiders from a barbarian camp attacked; a beaten band leaves a bounty in the village. */ raid?: boolean bounty?: Cost | null /** Only when scouts went along. Resources and buildings only when some got through. */ scouting?: { sent: number lost: number through: boolean resources: Cost | null /** Levels of every instance, highest first. */ buildings: Partial> | null } | null } /** `rally.simulate`: a battle on paper with the world's rules. */ export interface SimulatedBattle { won: boolean attacker: { units: Record; lost: Record } defender: { units: Record; lost: Record } wall: { before: number; after: number } | null building: { before: number; after: number } | null power: { attack: number; defense: number } } export interface SupportReport { from: VillageRef to: VillageRef units: Units } interface ReportBase { id: number happened_at: string read: boolean } /** Raiders whose camp was beaten down before they arrived: no battle. */ export interface ScatteredRaid { raid: true scattered: true attacker: { village: VillageRef; units: null; lost: null } defender: { village: VillageRef; units: null; lost: null } } export type Report = | (ReportBase & { type: 'attack' | 'defense'; payload: BattleReport | ScatteredRaid }) | (ReportBase & { type: 'support'; payload: SupportReport }) export type RankingKind = 'players' | 'villages' | 'attack' | 'defense' export interface RankingRow { rank: number player: { id: number; name: string } /** Only in the village ranking. */ village?: { id: number; name: string; x: number; y: number } /** Points, or opponents defeated (by the food the fallen ate). */ value: number /** Only in the player ranking. */ villages?: number own: boolean } /** `ranking.index`: one page; without a page asked for, the one with the own row. */ export interface RankingPage { kind: RankingKind page: number pages: number rows: RankingRow[] own: { rank: number; page: number } | null } /** `report.index`, `report.delete` and `report.readAll`. */ export interface ReportPage { reports: Report[] page: number pages: number unread: number } export interface Population { /** Food per hour the village can feed. */ food_budget: number /** Food per hour eaten by villagers and soldiers. */ upkeep: number villagers: number /** Villagers assigned to buildings. */ workers: number soldiers: number /** Units queued but not trained yet; they already eat instead of working. */ training: number } export interface Levy { /** 0 when no levy is under way. */ militia: number /** When the militia go back to work on their own. */ until: string | null /** How long a new levy would last. */ seconds: number } /** Upkeep above income drains the food stock; once it is empty, soldiers desert after a grace time. */ export interface Starvation { /** When the stock runs out at the current rates; null while food isn't draining. */ food_empty_at: string | null /** Set while the stock is empty and the village eats more than it harvests. */ since: string | null /** The next desertion wave, while starving. */ desertion_at: string | null } /** A barracks, stable, workshop or academy: what it trains and its own queue. */ export interface MilitaryBuilding { building_id: number type: BuildingType level: number units: RecruitOption[] queue: RecruitOrder[] } export interface RecruitOption { unit: UnitType /** Per unit. */ cost: Cost /** Per unit at this building, from its level and staffing. */ seconds: number /** Food per hour one unit eats. */ upkeep: number /** Most units that resources and villagers allowed when the snapshot was taken. */ max: number blocked: 'requires' | null requires: { type: BuildingType; level: number }[] } export interface RecruitOrder { id: number unit: UnitType count: number /** Units trained by the snapshot; the rest arrive every seconds_per_unit after starts_at. */ done: number seconds_per_unit: number starts_at: string finishes_at: string } export interface Building { id: number type: BuildingType level: number /** Building space this instance takes, fixed per type (0 for the wall). */ space: number priority: number workers: { assigned: number; required: number } /** assigned / required, 0..1. */ staffing: number production: { resource: Resource; per_hour: number } | null /** Next level after everything already queued; null at max level. */ upgrade: Offer | null /** null when the building cannot go lower (core buildings at level 1); target level 0 removes it. */ demolish: { target_level: number; refund: Cost; seconds: number } | null /** What one instance does at its level, and one level up (null at max level). */ effects: BuildingEffect[] next_effects: BuildingEffect[] | null } /** One line of what a building does: production at full staffing (per hour), percentages as whole numbers. */ export interface BuildingEffect { key: 'production' | 'capacity' | 'hides' | 'detection' | 'wall_defense' | 'wall_bonus' | 'build_speed' | 'builders' | 'space' | 'recruit_speed' value: number resource?: Resource } /** Whether it is affordable is left to the client, which compares the cost to projected resources. */ export interface Offer { target_level: number cost: Cost seconds: number blocked: BlockedReason | null } export interface BuildOption extends Offer { type: BuildingType space: number /** Requirements no building meets yet; only advanced buildings have any. */ requires: { type: BuildingType; level: number }[] } export interface BuildOrder { id: number /** null for a new instance that does not exist yet. */ building_id: number | null type: BuildingType action: 'build' | 'upgrade' | 'demolish' /** 0 means the instance is removed; levels start at 1. */ target_level: number space: number cost: Cost position: number /** Builder slot working on it, or null while it waits. */ builder: number | null starts_at: string | null finishes_at: string | null } /** Push `village:updated` after the server processed an event for this village. */ export interface VillageUpdated { village_id: number } /** What a rejected `ws.send` carries. */ export interface GameError { message: string code?: string } /** A screen a quest goal points at that is not a building's row on the headquarters screen. */ export type QuestScreen = 'overview' | 'recruit' | 'rally' | 'workforce' | 'map' | 'reports' export interface QuestGoal { /** building: a type at a level in any village; instances: that many of a type in one village; counter: an action done that often. */ kind: 'building' | 'instances' | 'counter' /** A building type, or a counter key such as `recruited.spear`. */ subject: string have: number need: number met: boolean /** Where to go: a building type (its headquarters row) or a screen. */ hint: BuildingType | QuestScreen } export interface Quest { key: string goals: QuestGoal[] reward: Partial complete: boolean } export interface QuestLine { line: 'construction' | 'army' | 'village' done: number total: number /** The first unclaimed quest; null once the line is finished. */ quest: Quest | null quests: { key: string; claimed: boolean }[] } /** A building level reached for the first time pays back part of its cost. */ export interface LevelReward { id: number type: BuildingType level: number reward: Partial /** Where it was reached; it is collected into the current village. */ village: { id: number; name: string | null } } /** `quest.index`. */ export interface QuestBookState { lines: QuestLine[] rewards: LevelReward[] /** What the next level of each building type in this village would pay back. */ upcoming: { type: BuildingType; level: number; reward: Partial }[] /** Share of a level's cost paid back, 0..1. */ share: number } /** `quest.claim` and `quest.collect`. */ export interface QuestClaimed { book: QuestBookState village: VillageState } /** Coins and noble slots of the player. Every nobleman alive and every village beyond the first takes a slot. */ export interface Conquest { coins: number slots: number used: number /** Coins still missing for the next slot. */ next_slot_coins: number coin_cost: Cost /** Fields a nobleman marches at most; 0 for no limit. */ max_distance: number }