2026-10-28 16:57:43 +00:00
|
|
|
|
// 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<Resource, number>
|
|
|
|
|
|
export type Cost = Record<Exclude<Resource, 'food'>, number>
|
|
|
|
|
|
|
|
|
|
|
|
export type BuildingType =
|
|
|
|
|
|
| 'headquarters'
|
|
|
|
|
|
| 'storage'
|
|
|
|
|
|
| 'farm'
|
|
|
|
|
|
| 'timber_camp'
|
|
|
|
|
|
| 'clay_pit'
|
|
|
|
|
|
| 'iron_mine'
|
|
|
|
|
|
| 'hiding_place'
|
|
|
|
|
|
| 'wall'
|
|
|
|
|
|
| 'rally_point'
|
feat: rally point, troop movements, support, reports, scouts, battle simulator and village rename
Send attacks and support from the rally point with a live travel-time preview, see own
commands and spotted incoming attacks with countdowns and call-back, send support home
or withdraw it, read battle and support reports with an unread badge, run the battle
simulator, rename villages, and send troops straight from the map. The watchtower gets
a diorama model; the mock server answers every new intent.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 23:16:06 +00:00
|
|
|
|
| 'watchtower'
|
2026-10-28 20:44:41 +00:00
|
|
|
|
| 'barracks'
|
|
|
|
|
|
| 'stable'
|
|
|
|
|
|
| 'workshop'
|
|
|
|
|
|
| 'academy'
|
2026-10-28 16:57:43 +00:00
|
|
|
|
|
2026-10-28 20:51:43 +00:00
|
|
|
|
export type UnitType =
|
|
|
|
|
|
| 'spear'
|
|
|
|
|
|
| 'sword'
|
|
|
|
|
|
| 'archer'
|
feat: rally point, troop movements, support, reports, scouts, battle simulator and village rename
Send attacks and support from the rally point with a live travel-time preview, see own
commands and spotted incoming attacks with countdowns and call-back, send support home
or withdraw it, read battle and support reports with an unread badge, run the battle
simulator, rename villages, and send troops straight from the map. The watchtower gets
a diorama model; the mock server answers every new intent.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 23:16:06 +00:00
|
|
|
|
| 'scout'
|
2026-10-28 20:51:43 +00:00
|
|
|
|
| 'light_cavalry'
|
|
|
|
|
|
| 'heavy_cavalry'
|
|
|
|
|
|
| 'ram'
|
|
|
|
|
|
| 'catapult'
|
|
|
|
|
|
| 'nobleman'
|
|
|
|
|
|
|
feat: rally point, troop movements, support, reports, scouts, battle simulator and village rename
Send attacks and support from the rally point with a live travel-time preview, see own
commands and spotted incoming attacks with countdowns and call-back, send support home
or withdraw it, read battle and support reports with an unread badge, run the battle
simulator, rename villages, and send troops straight from the map. The watchtower gets
a diorama model; the mock server answers every new intent.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 23:16:06 +00:00
|
|
|
|
/** Units by type; missing types mean none. */
|
|
|
|
|
|
export type Units = Partial<Record<UnitType, number>>
|
|
|
|
|
|
|
|
|
|
|
|
export type MovementType = 'attack' | 'support' | 'return'
|
|
|
|
|
|
export type TravelMode = 'sneaky' | 'cautious' | 'normal' | 'fast' | 'forced'
|
|
|
|
|
|
|
2026-10-28 18:54:19 +00:00
|
|
|
|
/** Why the server refuses an offer. The client shows `village.blocked.<reason>`; no_space means not enough free building space. */
|
2026-10-28 18:26:16 +00:00
|
|
|
|
export type BlockedReason = 'max_per_village' | 'no_space' | 'max_level' | 'requires'
|
2026-10-28 16:57:43 +00:00
|
|
|
|
|
|
|
|
|
|
export interface AuthUser {
|
|
|
|
|
|
id: number
|
|
|
|
|
|
name: string
|
|
|
|
|
|
email: string
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
/** `POST auth/login` and `POST auth/register`. */
|
|
|
|
|
|
export interface AuthResult {
|
|
|
|
|
|
token: string
|
|
|
|
|
|
user: AuthUser
|
|
|
|
|
|
}
|
|
|
|
|
|
|
2026-10-29 00:57:00 +00:00
|
|
|
|
/** Where a new village starts: anywhere on the frontier, or in one quarter of the map. */
|
|
|
|
|
|
export type StartDirection = 'random' | 'nw' | 'ne' | 'sw' | 'se'
|
|
|
|
|
|
|
2026-10-28 16:57:43 +00:00
|
|
|
|
/** 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 interface VillageState {
|
|
|
|
|
|
id: number
|
2026-10-28 18:58:42 +00:00
|
|
|
|
world_id: number
|
2026-10-28 16:57:43 +00:00
|
|
|
|
name: string
|
|
|
|
|
|
x: number
|
|
|
|
|
|
y: number
|
2026-10-29 00:57:00 +00:00
|
|
|
|
/** Map continent, e.g. K55 for 0|0 to 99|99. */
|
2026-10-28 18:58:42 +00:00
|
|
|
|
continent: string
|
|
|
|
|
|
/** Sum of the buildings' level points, as shown on the map. */
|
|
|
|
|
|
points: number
|
2026-10-28 18:54:19 +00:00
|
|
|
|
/** Building space: what buildings and queued new buildings take, out of the village maximum. */
|
|
|
|
|
|
space: { used: number; max: number }
|
2026-10-28 16:57:43 +00:00
|
|
|
|
/** 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
|
2026-10-28 20:58:09 +00:00
|
|
|
|
/** Villagers drafted as militia: they eat but don't work until `until`. */
|
|
|
|
|
|
levy: Levy
|
2026-10-28 21:05:45 +00:00
|
|
|
|
starvation: Starvation
|
2026-10-28 20:51:43 +00:00
|
|
|
|
/** Own units standing in the village. */
|
|
|
|
|
|
troops: Partial<Record<UnitType, number>>
|
|
|
|
|
|
/** One entry per building that trains units, in building order. */
|
|
|
|
|
|
military: MilitaryBuilding[]
|
feat: rally point, troop movements, support, reports, scouts, battle simulator and village rename
Send attacks and support from the rally point with a live travel-time preview, see own
commands and spotted incoming attacks with countdowns and call-back, send support home
or withdraw it, read battle and support reports with an unread badge, run the battle
simulator, rename villages, and send troops straight from the map. The watchtower gets
a diorama model; the mock server answers every new intent.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 23:16:06 +00:00
|
|
|
|
/** 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
|
2026-10-28 16:57:43 +00:00
|
|
|
|
builders: number
|
|
|
|
|
|
buildings: Building[]
|
|
|
|
|
|
queue: BuildOrder[]
|
|
|
|
|
|
buildable: BuildOption[]
|
|
|
|
|
|
/** Lets the client correct for its own clock being off. */
|
|
|
|
|
|
server_time: string
|
|
|
|
|
|
}
|
|
|
|
|
|
|
feat: rally point, troop movements, support, reports, scouts, battle simulator and village rename
Send attacks and support from the rally point with a live travel-time preview, see own
commands and spotted incoming attacks with countdowns and call-back, send support home
or withdraw it, read battle and support reports with an unread badge, run the battle
simulator, rename villages, and send troops straight from the map. The watchtower gets
a diorama model; the mock server answers every new intent.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 23:16:06 +00:00
|
|
|
|
/** 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
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
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<string, number> | null
|
|
|
|
|
|
lost: Record<string, number> | 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
|
|
|
|
|
|
/** 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<Record<BuildingType, number[]>> | null
|
|
|
|
|
|
} | null
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
/** `rally.simulate`: a battle on paper with the world's rules. */
|
|
|
|
|
|
export interface SimulatedBattle {
|
|
|
|
|
|
won: boolean
|
|
|
|
|
|
attacker: { units: Record<string, number>; lost: Record<string, number> }
|
|
|
|
|
|
defender: { units: Record<string, number>; lost: Record<string, number> }
|
|
|
|
|
|
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
|
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
export type Report =
|
|
|
|
|
|
| (ReportBase & { type: 'attack' | 'defense'; payload: BattleReport })
|
|
|
|
|
|
| (ReportBase & { type: 'support'; payload: SupportReport })
|
|
|
|
|
|
|
|
|
|
|
|
/** `report.index`, `report.delete` and `report.readAll`. */
|
|
|
|
|
|
export interface ReportPage {
|
|
|
|
|
|
reports: Report[]
|
|
|
|
|
|
page: number
|
|
|
|
|
|
pages: number
|
|
|
|
|
|
unread: number
|
|
|
|
|
|
}
|
|
|
|
|
|
|
2026-10-28 16:57:43 +00:00
|
|
|
|
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
|
2026-10-28 20:51:43 +00:00
|
|
|
|
/** Units queued but not trained yet; they already eat instead of working. */
|
|
|
|
|
|
training: number
|
|
|
|
|
|
}
|
|
|
|
|
|
|
2026-10-28 20:58:09 +00:00
|
|
|
|
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
|
|
|
|
|
|
}
|
|
|
|
|
|
|
2026-10-28 21:05:45 +00:00
|
|
|
|
/** 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
|
|
|
|
|
|
}
|
|
|
|
|
|
|
2026-10-28 20:51:43 +00:00
|
|
|
|
/** 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
|
2026-10-28 16:57:43 +00:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
export interface Building {
|
|
|
|
|
|
id: number
|
|
|
|
|
|
type: BuildingType
|
|
|
|
|
|
level: number
|
2026-10-28 18:54:19 +00:00
|
|
|
|
/** Building space this instance takes, fixed per type (0 for the wall). */
|
|
|
|
|
|
space: number
|
2026-10-28 16:57:43 +00:00
|
|
|
|
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
|
2026-10-28 21:26:50 +00:00
|
|
|
|
/** null when the building cannot go lower (core buildings at level 1); target level 0 removes it. */
|
2026-10-28 20:18:57 +00:00
|
|
|
|
demolish: { target_level: number; refund: Cost; seconds: number } | null
|
2026-10-28 16:57:43 +00:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
/** 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
|
2026-10-28 18:54:19 +00:00
|
|
|
|
space: number
|
2026-10-28 20:01:23 +00:00
|
|
|
|
/** Requirements no building meets yet; only advanced buildings have any. */
|
|
|
|
|
|
requires: { type: BuildingType; level: number }[]
|
2026-10-28 16:57:43 +00:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
|
|
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'
|
2026-10-28 21:26:50 +00:00
|
|
|
|
/** 0 means the instance is removed; levels start at 1. */
|
2026-10-28 16:57:43 +00:00
|
|
|
|
target_level: number
|
2026-10-28 18:54:19 +00:00
|
|
|
|
space: number
|
2026-10-28 16:57:43 +00:00
|
|
|
|
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
|
|
|
|
|
|
}
|