game-village-politics-frontend/app/types/game.ts

508 lines
16 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

// 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 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<VillageRole, number>
share: number
min_space: number
/** Bonuses as shares: production (camps' output), recruit_speed, defense. */
roles: { role: VillageRole; buildings: BuildingType[]; bonuses: Partial<Record<'production' | 'recruit_speed' | 'defense', number>> }[]
}
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<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
/** 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<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
/** 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<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
}
/** 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<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
}