453 lines
14 KiB
TypeScript
453 lines
14 KiB
TypeScript
// 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'
|
||
| '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<Record<UnitType, number>>
|
||
|
||
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.<reason>`; 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 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 }
|
||
/** 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<Record<UnitType, number>>
|
||
/** 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
|
||
}
|
||
|
||
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
|
||
/** Noblemen survived a won attack: loyalty before and after, and whether the village changed hands. */
|
||
loyalty?: { before: number; after: number; conquered: boolean } | 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<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
|
||
}
|
||
|
||
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<Resources>
|
||
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<Resources>
|
||
/** 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<Resources> }[]
|
||
/** 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
|
||
}
|